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): render selected ranges with weighted capacity

kashorinefc8bd56e79a
diff --git a/packages/cli/src/commands/execution.ts b/packages/cli/src/commands/execution.ts
index 4d83be7c..dee7f825 100644
--- a/packages/cli/src/commands/execution.ts
+++ b/packages/cli/src/commands/execution.ts
@@ -119,7 +119,7 @@ export async function runExecutionCommand(input: {
: ` · ${item.requests.completed}/${item.requests.total} steps`;
return `${item.id}: ${buildStatusView({ id: item.id, runtime: item }).work.state}`
+ requestProgress
- + `${item.cancellationRequested ? " · cancelling" : ""}`
+ + `${item.stop?.cause === "execution-failed" ? " · stopping after failure" : item.cancellationRequested ? " · cancelling" : ""}`
+ `${item.issue === undefined ? "" : ` · ${item.issue.message}`}`;
});
const activeOperations = activity.builds.flatMap((item) => item.operations)
@@ -303,15 +303,17 @@ export async function runExecutionCommand(input: {
requested: active?.cancellationRequested === true,
build,
};
+ const alreadyStopping = active?.stop?.cause === "execution-failed";
const title = active === undefined && finished === undefined
? "Build not found"
- : active === undefined ? "Build already finished" : "Build cancellation requested";
+ : active === undefined ? "Build already finished"
+ : alreadyStopping ? "Build already stopping after failure" : "Build cancellation requested";
write(machine, title,
- active === undefined && finished === undefined ? "warning" : active === undefined ? "info" : "success", [
+ active === undefined && finished === undefined ? "warning" : active === undefined || alreadyStopping ? "info" : "success", [
["Build", args.build], ...(build === null ? [] : [["Work", build.work.state] as const]),
], active === undefined && finished?.outcome !== undefined
? [`No running work was changed; this Build is already ${finished.outcome}.`]
- : []);
+ : alreadyStopping ? [active.stop!.reason ?? "Waiting for submitted work to finish."] : []);
if (active === undefined && finished === undefined) io.setExitCode?.(1);
} finally {
await runtime.close();
diff --git a/packages/cli/src/observation.ts b/packages/cli/src/observation.ts
index e99239a6..2eef47cb 100644
--- a/packages/cli/src/observation.ts
+++ b/packages/cli/src/observation.ts
@@ -40,11 +40,15 @@ export function buildProgressView(view: CliBuildView, now = Date.now()): BuildPr
...(view.requests === undefined ? {} : { requests: view.requests }),
phases: progressPhases(view),
elapsedMs: Math.max(0, now - view.createdAt),
- details: view.operations
- .filter((item) => item.status === "pending")
+ details: [
+ ...(view.stop === undefined ? [] : [view.stop.cause === "execution-failed"
+ ? `Build stopping after failure${view.stop.reason === undefined ? "" : `: ${view.stop.reason}`}`
+ : `Build cancelling${view.stop.reason === undefined ? "" : `: ${view.stop.reason}`}`]),
+ ...view.operations.filter((item) => item.status === "pending")
.map((item) => `${item.endpoint}: ${item.progress === undefined
? item.status
: formatOperationProgress(item.progress)}`),
+ ],
};
}
@@ -55,6 +59,7 @@ export function buildObservationKey(view: CliBuildView): string {
outcome: view.outcome,
issue: view.issue,
cancellationRequested: view.cancellationRequested,
+ stop: view.stop,
requests: view.requests,
phases: progressPhases(view),
});
diff --git a/packages/cli/src/output.ts b/packages/cli/src/output.ts
index bdd38f5a..19b1f4c2 100644
--- a/packages/cli/src/output.ts
+++ b/packages/cli/src/output.ts
@@ -761,6 +761,7 @@ export function writeCliHelp(io: CliIo, topic?: string): void {
row("programs up|status|down", "manage declared external programs only"),
row("packages install|status", "manage pinned upstream packages in the machine home"),
row("activity [--watch]", "inspect active Builds and shared capacity"),
+ row("cancel <build-id>", "withdraw one active Build"),
row("paths", "show physical state locations"),
row("auth status|login|logout", "manage Endpoint credentials"),
"",
diff --git a/packages/cli/src/view.ts b/packages/cli/src/view.ts
index 0ae57ad1..d5013268 100644
--- a/packages/cli/src/view.ts
+++ b/packages/cli/src/view.ts
@@ -57,6 +57,7 @@ export type CliBuildStatusView = {
readonly state: "unknown" | "submitting" | "working" | "done";
readonly outcome?: "complete" | "failed" | "cancelled";
readonly cancellationRequested?: boolean;
+ readonly stop?: BuildView["stop"];
readonly requests?: { readonly total: number; readonly completed: number };
};
readonly result: {
@@ -156,6 +157,7 @@ export function buildStatusView(options: {
? {}
: { outcome: options.runtime?.outcome ?? options.result!.outcome }),
...(options.runtime?.cancellationRequested === true ? { cancellationRequested: true } : {}),
+ ...(options.runtime?.stop === undefined ? {} : { stop: options.runtime.stop }),
...(options.runtime?.requests === undefined ? {} : { requests: options.runtime.requests }),
},
result: {
diff --git a/packages/cli/test/control-commands.test.ts b/packages/cli/test/control-commands.test.ts
index 2fcd55c5..e7e56fb3 100644
--- a/packages/cli/test/control-commands.test.ts
+++ b/packages/cli/test/control-commands.test.ts
@@ -568,3 +568,26 @@ test("cancelling a completed Build reports that no cancellation was requested",
},
});
});
+
+test("cancelling an already failed execution preserves and reports its stop reason", async () => {
+ const stop = { cause: "execution-failed", reason: "Original execution failure" } as const;
+ const active = {
+ id: "build-stopping", createdAt: 1, activity: "waiting", cancellationRequested: false, stop,
+ targets: [], acceptedRecords: 0, outstandingCommands: 0, operations: [],
+ } as const;
+ const control = { async cancel() { return active; }, async close() {} } as unknown as CliRuntimeControl;
+ const distribution = {
+ openRuntimeHost: async (path: string) => ({ profile: path, openControl: async () => control }),
+ } as unknown as CliDistribution;
+ let output = "";
+ await runCli(["cancel", "build-stopping", "--runtime", "/tmp/runtime.json", "--json"],
+ { write: (text) => { output += text; } }, distribution);
+ const result = JSON.parse(output);
+ assert.equal(result.requested, false);
+ assert.deepEqual(result.build.work.stop, stop);
+ output = "";
+ await runCli(["cancel", "build-stopping", "--runtime", "/tmp/runtime.json"],
+ { write: (text) => { output += text; } }, distribution);
+ assert.match(output, /already stopping after failure/);
+ assert.match(output, /Original execution failure/);
+});
diff --git a/packages/cli/test/observation.test.ts b/packages/cli/test/observation.test.ts
index ef4383c0..b81050bd 100644
--- a/packages/cli/test/observation.test.ts
+++ b/packages/cli/test/observation.test.ts
@@ -94,3 +94,11 @@ test("Runtime activity ignores capacity leases but observes Build progress", ()
activityObservationKey("running", [other, running]),
);
});
+
+
+test("watch output observes a Build stop independently of remote Operation failures", () => {
+ const running = view("waiting", 1, 0);
+ const stopping = { ...running, stop: { cause: "execution-failed" as const, reason: "Runtime interrupted" } };
+ assert.notEqual(buildObservationKey(stopping), buildObservationKey(running));
+ assert.ok(buildProgressView(stopping).details.includes("Build stopping after failure: Runtime interrupted"));
+});
diff --git a/packages/core/README.md b/packages/core/README.md
index 23c4b9d4..d7c98954 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -14,5 +14,9 @@ reconstructs the current view, emits the next commands and accepts their results
`Output -> Record` bindings and Targets. Graphs, satisfactions and Candidate identities end at the
planning boundary.
+`resolveNeedCommand(state, commandId)` resolves the Command belonging to an existing Need, including
+when a stopped Build has no outstanding work. Core owns this identity rule; execution adapters do not
+parse Command IDs. The query does not schedule or execute work.
+
Core does not parse source files, load packages, execute components, call providers, store artifact
bytes or know what a video is. Those responsibilities remain in compiler and runtime packages.
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 04d06cff..21ca97af 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -25,6 +25,7 @@ export {
admitBuildResult,
defineBuild,
materializeBuild,
+ resolveNeedCommand,
reduce,
start,
} from "./reducer.js";
diff --git a/packages/core/src/reducer.ts b/packages/core/src/reducer.ts
index c3906f73..0182d410 100644
--- a/packages/core/src/reducer.ts
+++ b/packages/core/src/reducer.ts
@@ -6,6 +6,7 @@ import type {
CoreCommand,
CompiledGraph,
CommandResult,
+ CommandId,
FulfillNeedCommand,
InvokeProducerCommand,
LinkedProgram,
@@ -25,6 +26,16 @@ function commandId(kind: "producer" | "need", subject: string): string {
return `${kind}:${subject}`;
}
+function needCommand(need: Need): FulfillNeedCommand {
+ return { kind: "fulfill-need", id: commandId("need", need.id), need };
+}
+
+/** Resolve an issued Need's Command even after the Build has stopped scheduling work. */
+export function resolveNeedCommand(state: BuildState, id: CommandId): FulfillNeedCommand | undefined {
+ const need = state.needs.find((item) => needCommand(item).id === id);
+ return need === undefined ? undefined : needCommand(need);
+}
+
function withoutCommand(state: BuildState, id: string): readonly CoreCommand[] {
return state.outstanding.filter((command) => command.id !== id);
}
@@ -198,9 +209,9 @@ function schedule(state: BuildState): BuildState {
const commands: CoreCommand[] = [...state.outstanding];
for (const need of state.needs) {
if (records.has(need.result)) continue;
- const id = commandId("need", need.id);
- if (issued.has(id)) continue;
- commands.push({ kind: "fulfill-need", id, need });
+ const command = needCommand(need);
+ if (issued.has(command.id)) continue;
+ commands.push(command);
}
for (const stepState of state.steps) {
diff --git a/packages/core/test/core.test.ts b/packages/core/test/core.test.ts
index 9de682bb..2816961c 100644
--- a/packages/core/test/core.test.ts
+++ b/packages/core/test/core.test.ts
@@ -4,6 +4,7 @@ import {
BuildMachine,
defineBuild,
reduce,
+ resolveNeedCommand,
} from "@hypit/core";
import type {
CommandResult,
@@ -144,3 +145,15 @@ test("scheduling is incremental: a ready Producer runs while an unrelated Need i
item.kind === "invoke-producer" && item.producer.name === "assemble");
assert.ok(assembleSide, "the side chain's next Producer was scheduled behind the outstanding Need");
});
+
+
+test("Core resolves an existing Need Command after failure without restarting scheduling", () => {
+ const { state, command } = reachNeed();
+ assert.deepEqual(resolveNeedCommand(state, command.id), command);
+ const failed = reduce(state, { kind: "command-failed", command: command.id, code: "EXAMPLE", message: "stopped" });
+ assert.equal(failed.status, "failed");
+ assert.equal(failed.outstanding.length, 0);
+ assert.deepEqual(resolveNeedCommand(failed, command.id), command);
+ assert.equal(resolveNeedCommand(failed, "absent-command"), undefined);
+ assert.equal(failed.outstanding.length, 0);
+});
diff --git a/packages/driver-node/src/driver.ts b/packages/driver-node/src/driver.ts
index c6413abb..a47192fa 100644
--- a/packages/driver-node/src/driver.ts
+++ b/packages/driver-node/src/driver.ts
@@ -1,8 +1,9 @@
import { randomUUID } from "node:crypto";
-import { reduce, resolveProducer } from "@hypit/core";
+import { reduce, resolveNeedCommand, resolveProducer } from "@hypit/core";
import type { ProducerHandlerResult } from "@hypit/component-kit";
import type { EndpointFulfillment, EndpointOutcome } from "@hypit/endpoint-kit";
+import { endpointResourceClaims } from "@hypit/endpoint-kit";
import type {
BuildState,
CommandResult,
@@ -209,10 +210,10 @@ export class NodeDriver {
executable: {
command,
endpointId: registration.id,
- resources: registration.scheduling?.resources ?? [{
+ resources: registration.scheduling === undefined ? [{
id: `endpoint:${registration.id}`,
limit: 1,
- }],
+ }] : endpointResourceClaims(registration.scheduling, command.need),
registration,
},
};
@@ -309,6 +310,10 @@ export class NodeDriver {
if (latest?.status === "completed" || latest?.status === "cancelled") {
return await this.#completedOperation(state, executable, latest, latest.id);
}
+ if (latest?.status === "pending" && latest.cancellationRequested) {
+ const settled = await this.cancelOperation(state, latest);
+ return await this.#completedOperation(state, executable, settled, latest.id);
+ }
if (latest?.status === "pending" && latest.wakeAt !== undefined && latest.wakeAt > Date.now()) {
return { status: "pending", operation: latest.id, wakeAt: latest.wakeAt };
}
@@ -317,7 +322,9 @@ export class NodeDriver {
}
if (latest?.status === "pending" && latest.handle === undefined) {
const unknown = await operations.update(latest.id, {
- status: "failed",
+ status: "pending",
+ wakeAt: Date.now() + 30_000,
+ progress: { phase: "submission-unknown" },
failure: {
code: "SUBMISSION_UNKNOWN",
message: `Operation ${latest.id} stopped before its Endpoint acknowledgement was stored; the same Build will not submit it again`,
@@ -347,7 +354,9 @@ export class NodeDriver {
outcome = await executable.registration.endpoint.start(endpointContext);
} catch (error) {
const unknown = await operations.update(identity.id, {
- status: "failed",
+ status: "pending",
+ wakeAt: Date.now() + 30_000,
+ progress: { phase: "submission-unknown" },
failure: {
code: "SUBMISSION_UNKNOWN",
message: `Endpoint start ended without a stored acknowledgement: ${failureMessage(error)}`,
@@ -359,19 +368,29 @@ export class NodeDriver {
if (latest.status !== "pending" || latest.handle === undefined) {
throw new Error(`Operation ${latest.id} cannot be polled`);
}
- outcome = await executable.registration.endpoint.poll({
- ...endpointContext,
- handle: structuredClone(latest.handle),
- });
+ try {
+ outcome = await executable.registration.endpoint.poll({
+ ...endpointContext,
+ handle: structuredClone(latest.handle),
+ ...(latest.failure === undefined ? {} : { settling: true as const }),
+ });
+ } catch {
+ // A transport error says nothing about whether the submitted work has ended.
+ outcome = { status: "pending", handle: latest.handle, wakeAt: Date.now() + 1_000,
+ progress: { phase: "poll-unavailable" } };
+ }
}
const write = async (update: OperationUpdate): Promise<OperationSnapshot> =>
await operations.update(identity.id, update);
if (outcome.status === "pending") {
+ const handle = outcome.handle === undefined ? latest?.handle : outcome.handle;
+ const failure = latest?.failure ?? outcome.failure;
const written = await write({
status: "pending",
- handle: outcome.handle,
+ ...(handle === undefined ? {} : { handle }),
...(outcome.wakeAt === undefined ? {} : { wakeAt: outcome.wakeAt }),
...(outcome.progress === undefined ? {} : { progress: outcome.progress }),
+ ...(failure === undefined ? {} : { failure }),
});
return await this.#completedOperation(
state,
@@ -380,6 +399,12 @@ export class NodeDriver {
identity.id,
);
}
+ if (latest?.failure !== undefined || outcome.status === "settled") {
+ const written = await write({ status: "failed", failure: latest?.failure ?? {
+ code: "ENDPOINT_SETTLED_WITHOUT_RESULT", message: "Endpoint ended without a fulfillment result",
+ } });
+ return await this.#completedOperation(state, executable, written, identity.id);
+ }
if (outcome.status === "failed") {
const written = await write({
status: "failed",
@@ -499,39 +524,49 @@ export class NodeDriver {
return await this.#execute(state, classified.executable, context);
}
- /** Stop polling one persisted external Operation and make one best-effort Provider cancel call. */
- async cancelOperation(
- initial: BuildState,
- operation: OperationSnapshot,
- ): Promise<OperationSnapshot> {
+ /** Cancel once, then observe the same remote work until termination is confirmed. */
+ async cancelOperation(initial: BuildState, operation: OperationSnapshot): Promise<OperationSnapshot> {
const operations = this.operations;
if (operations === undefined) throw new Error("cancelling an Operation requires OperationStore");
const current = await operations.read(operation.id) ?? operation;
- if (current.status === "completed" || current.status === "failed" || current.status === "cancelled") return current;
- const prepared = this.prepare(initial);
- const descriptor = prepared.runnable.find((item) => item.command.id === operation.command);
- if (descriptor === undefined) throw new Error(`Operation ${operation.id} Command is not currently runnable`);
- const classified = this.#classify(prepared.state, descriptor.command);
- const executable = classified.executable;
- if (executable === undefined || !("endpointId" in executable)
- || executable.endpointId !== operation.endpoint
- || executable.registration.kind !== "asynchronous") {
- throw new Error(`Operation ${operation.id} does not match the current Endpoint Command`);
+ if (current.status !== "pending") return current;
+ if (current.cancellationRequested && (current.wakeAt ?? 0) > Date.now()) return current;
+ const pending = (phase: string, wakeAt = Date.now() + 1_000, handle = current.handle) => operations.update(current.id, {
+ status: "pending", ...(handle === undefined ? {} : { handle }),
+ wakeAt, progress: { phase }, cancellationRequested: true,
+ ...(current.failure === undefined ? {} : { failure: current.failure }),
+ });
+ if (current.handle === undefined) return await pending("submission-unknown", Date.now() + 30_000);
+ const command = resolveNeedCommand(initial, current.command);
+ if (command === undefined) throw new Error(`Operation ${current.id} has no matching Need Command`);
+ const { need } = command;
+ const resolution = this.endpoints.resolve(need);
+ if (resolution.status !== "resolved" || resolution.registration.id !== current.endpoint
+ || resolution.registration.kind !== "asynchronous") {
+ throw new Error(`Operation ${current.id} does not match its bound Endpoint`);
}
- const endpointContext = {
- command: structuredClone(executable.command),
- need: structuredClone(executable.command.need),
- resources: this.#resourceStore(operation.build),
- credentials: await this.#endpointCredentials(executable.registration),
- operation: current.id,
- handle: structuredClone(current.handle as NonNullable<typeof current.handle>),
- };
+ const endpoint = resolution.registration.endpoint;
try {
- await executable.registration.endpoint.cancel?.(endpointContext);
+ const context = {
+ command: structuredClone(command), need: structuredClone(need),
+ resources: this.#resourceStore(current.build),
+ credentials: await this.#endpointCredentials(resolution.registration),
+ operation: current.id, handle: structuredClone(current.handle), settling: true as const,
+ };
+ if (!current.cancellationRequested) {
+ await pending("cancelling");
+ const cancelled = await endpoint.cancel?.(context);
+ if (cancelled?.status === "confirmed") return await operations.update(current.id, { status: "cancelled" });
+ if (cancelled?.status === "accepted" && cancelled.wakeAt !== undefined && cancelled.wakeAt > Date.now()) {
+ return await pending("cancelling", cancelled.wakeAt);
+ }
+ }
+ const outcome = await endpoint.poll(context);
+ if (outcome.status === "pending") return await pending("cancelling", outcome.wakeAt ?? Date.now() + 1_000, outcome.handle);
+ return await operations.update(current.id, { status: "cancelled" });
} catch {
- // Build cancellation is best effort. Local execution stops even if the Provider cannot.
+ return await pending("cancellation-unconfirmed");
}
- return await operations.update(current.id, { status: "cancelled" });
}
async run(initial: BuildState, context?: RuntimeExecutionContext): Promise<DriverRunResult> {
diff --git a/packages/driver-node/src/registry.ts b/packages/driver-node/src/registry.ts
index 08e50c30..3fffd0d5 100644
--- a/packages/driver-node/src/registry.ts
+++ b/packages/driver-node/src/registry.ts
@@ -14,7 +14,7 @@ import type {
ProducerRef,
TypeRef,
} from "@hypit/protocol";
-import { verifyCredentialRef } from "@hypit/runtime";
+import { capacityUnits, verifyCredentialRef } from "@hypit/runtime";
import type {
ProducerHandler,
@@ -40,6 +40,7 @@ function verifyScheduling(scheduling: EndpointScheduling | undefined): void {
if (scheduling === undefined) return;
if (scheduling.resources.length === 0) throw new Error("scheduling resources must not be empty");
const ids = scheduling.resources.map((resource) => {
+ capacityUnits(resource);
if (resource.id.trim().length === 0) throw new Error("scheduling resource id must not be empty");
if (!Number.isSafeInteger(resource.limit) || resource.limit < 1) {
throw new Error(`scheduling resource ${resource.id} limit must be a positive safe integer`);
diff --git a/packages/driver-node/test/scheduler.test.ts b/packages/driver-node/test/scheduler.test.ts
index 83d3addf..6c60114c 100644
--- a/packages/driver-node/test/scheduler.test.ts
+++ b/packages/driver-node/test/scheduler.test.ts
@@ -325,8 +325,10 @@ test("a persisted submitting Operation is never submitted again after its caller
const [resumed] = await new LocalBuildScheduler(asyncExecutor(endpoint, operations))
.run([{ id: "submission-window", state: interrupted!.state }]);
- assert.equal(resumed?.status, "failed");
- assert.equal(resumed?.state.diagnostics.at(-1)?.code, "SUBMISSION_UNKNOWN");
+ assert.equal(resumed?.status, "paused");
+ const [unknown] = await operations.list({ build: "submission-window" });
+ assert.equal(unknown?.status, "pending");
+ assert.equal(unknown?.failure?.code, "SUBMISSION_UNKNOWN");
assert.equal(starts, 0);
});
@@ -367,3 +369,43 @@ test("wakeAt prevents early polling and Runtime cancellation becomes a terminal
assert.equal(cancelled?.status, "failed");
assert.equal(cancelled?.state.diagnostics.at(-1)?.code, "CANCELLED");
});
+
+test("request quantities govern concurrent admission, independent of whole-Need count", async () => {
+ const producerRegistry = new ProducerRegistry();
+ registerGreetingProducers(producerRegistry);
+ const endpoints = new EndpointRegistry();
+ let active = 0, maximum = 0;
+ endpoints.registerImmediateEndpoint("weighted", capabilities.generation, types.generated, async () => {
+ active += 4; maximum = Math.max(maximum, active);
+ await new Promise((resolve) => setTimeout(resolve, 10));
+ active -= 4;
+ return { value: { kind: "inline", value: "done" } };
+ }, { scheduling: { resources: [{ id: "browsers", limit: 6 }], unitsForRequest: () => ({ browsers: 4 }) } });
+ const results = await new LocalBuildScheduler(new NodeDriver({ producers: producerRegistry, endpoints }))
+ .run(["a", "b"].map((id) => ({ id, state: createGreetingBuild() })));
+ assert.ok(results.every((result) => result.status === "complete"));
+ assert.equal(maximum, 4, "two four-worker requests cannot fit in six slots");
+});
+
+test("a poll transport error keeps the same Operation until its remote work finishes", async () => {
+ const operations = memoryOperations();
+ let starts = 0, unavailable = true;
+ const endpoint: AsyncEndpoint = {
+ start() { starts++; return { status: "pending", handle: { job: "one" } }; },
+ poll() {
+ if (unavailable) throw new Error("connection lost");
+ return { status: "completed", result: { value: { kind: "inline", value: "done" } } };
+ },
+ };
+ const scheduler = new LocalBuildScheduler(asyncExecutor(endpoint, operations));
+ const [first] = await scheduler.run([{ id: "poll-error", state: createGreetingBuild() }]);
+ const [second] = await scheduler.run([{ id: "poll-error", state: first!.state }]);
+ const [operation] = await operations.list({ build: "poll-error" });
+ assert.equal(operation?.status, "pending");
+ assert.equal(operation?.progress?.phase, "poll-unavailable");
+ unavailable = false;
+ await operations.update(operation!.id, { status: "pending", handle: operation!.handle! });
+ const [third] = await scheduler.run([{ id: "poll-error", state: second!.state }]);
+ assert.equal(third?.status, "complete");
+ assert.equal(starts, 1);
+});
diff --git a/packages/endpoint-kit/README.md b/packages/endpoint-kit/README.md
index ae499aa4..385f8ce8 100644
--- a/packages/endpoint-kit/README.md
+++ b/packages/endpoint-kit/README.md
@@ -8,8 +8,17 @@ limits, then installs handlers into a Host registrar.
Immediate endpoints return a result directly. Asynchronous endpoints implement `start`, `poll` and
optional best effort `cancel`. Provider-total and exact-capability resource limits control concurrency
-without changing Core demand. Each resource declares one limit; asynchronous work retains that slot until
-its persisted Operation is terminal.
+without changing Core demand. Each resource declares a `limit` and optional `units` (default 1).
+A capability may add `resources` and a pure `unitsForRequest(request)` resolver for quantities of
+already declared resources. Runtime admits all claims atomically for one `fulfill-need` Command.
+
+For asynchronous work, `failed` means the external job has ended or submission was definitely rejected.
+Transport errors and local deadlines cannot prove that. Return `pending` with the same handle;
+a pending `failure` records a local deadline while Runtime waits for remote termination. A poll with
+`settling: true` observes the existing job and returns `settled` when it ends, without downloading output.
+`cancel` returning `accepted`, `unsupported` or `too-late` does not release capacity. Only confirmed
+cancellation or observed termination does. A lost submission acknowledgement may remain pending without
+a handle; it must not trigger automatic resubmission or an automatic capacity release.
An individual immediate capability may declare `transient: true`. That permits a Runtime to use the
same handler in a disposable authoring execution with no Build, Result or recoverable Operation. It is a
diff --git a/packages/endpoint-kit/src/index.ts b/packages/endpoint-kit/src/index.ts
index 09ccd1d2..a0c0ece0 100644
--- a/packages/endpoint-kit/src/index.ts
+++ b/packages/endpoint-kit/src/index.ts
@@ -14,8 +14,9 @@ import type {
CredentialValue,
OperationFailure,
OperationProgress,
+ CapacityResourceClaim,
} from "@hypit/runtime";
-import { verifyCredentialRef } from "@hypit/runtime";
+import { capacityUnits, verifyCredentialRef } from "@hypit/runtime";
export type Awaitable<T> = T | Promise<T>;
@@ -56,10 +57,13 @@ export type ImmediateEndpointHandler = (
export type EndpointOutcome =
| {
readonly status: "pending";
- readonly handle: CanonicalValue;
+ readonly handle?: CanonicalValue;
readonly wakeAt?: number;
readonly progress?: OperationProgress;
+ readonly failure?: OperationFailure;
}
+ /** Only returned to a settling poll, after the external work has stopped. No output is downloaded. */
+ | { readonly status: "settled" }
| { readonly status: "completed"; readonly result: EndpointFulfillment }
| { readonly status: "failed"; readonly failure: OperationFailure };
@@ -71,6 +75,8 @@ export type EndpointStartContext = EndpointInvocationContext & {
export type EndpointPollContext = EndpointStartContext & {
/** Provider task state returned by start(). */
readonly handle: CanonicalValue;
+ /** Observe termination without creating work, enforcing a local deadline, or downloading results. */
+ readonly settling?: true;
};
/**
@@ -92,13 +98,24 @@ export type AsyncEndpoint = {
/** Endpoint scheduling. It never changes Core demand. */
export type EndpointScheduling = {
- readonly resources: readonly {
- readonly id: string;
- /** Maximum Commands occupying this active Provider resource across Builds. */
- readonly limit: number;
- }[];
+ readonly resources: readonly CapacityResourceClaim[];
+ /** Pure request-dependent quantities for already declared resources. */
+ readonly unitsForRequest?: (request: EndpointRequest) => Readonly<Record<string, number>>;
};
+export function endpointResourceClaims(scheduling: EndpointScheduling, request: EndpointRequest): readonly CapacityResourceClaim[] {
+ const quantities = scheduling.unitsForRequest?.(request) ?? {};
+ for (const id of Object.keys(quantities)) {
+ if (!scheduling.resources.some((resource) => resource.id === id)) throw new Error(`Undeclared capacity resource ${id}`);
+ }
+ return scheduling.resources.map((resource) => {
+ const units = quantities[resource.id];
+ const claim = units === undefined ? resource : { ...resource, units };
+ capacityUnits(claim);
+ return claim;
+ });
+}
+
export type EndpointRegistrationOptions = {
readonly supports?: (request: EndpointRequest) => boolean;
readonly scheduling?: EndpointScheduling;
@@ -169,6 +186,8 @@ export type EndpointCredentialDescription = {
};
type EndpointCapabilityBase = {
+ readonly resources?: readonly CapacityResourceClaim[];
+ readonly unitsForRequest?: EndpointScheduling["unitsForRequest"];
readonly capability: CapabilityRef;
readonly returns: TypeRef;
readonly supports?: (request: EndpointRequest) => boolean;
@@ -317,6 +336,7 @@ export function defineEndpointPackage(options: DefineEndpointPackageOptions): En
...(capability.transient === true ? { transient: true } : {}),
credentials,
scheduling: {
+ ...(capability.unitsForRequest === undefined ? {} : { unitsForRequest: capability.unitsForRequest }),
resources: [
{
id: `pool:${options.pool}`,
@@ -326,6 +346,7 @@ export function defineEndpointPackage(options: DefineEndpointPackageOptions): En
id: `capacity:${options.pool}/${capacity}`,
limit: exactConcurrency,
},
+ ...(capability.resources ?? []),
],
},
};
diff --git a/packages/hyperframes/src/document.ts b/packages/hyperframes/src/document.ts
index 4cd4060e..7b19da63 100644
--- a/packages/hyperframes/src/document.ts
+++ b/packages/hyperframes/src/document.ts
@@ -373,6 +373,9 @@ function renderElement(
`data-playback-rate="${sampledPlaybackRate(segment.rate, element.sampling!.sourceFrameRate, context.programNumerator, context.programDenominator)}"`,
`data-hypit-source-frame="${run.sourceFrame.numerator}/${run.sourceFrame.denominator}"`,
`data-hypit-source-rate="${segment.rate.numerator}/${segment.rate.denominator}"`,
+ `data-hypit-start-frame="${startFrame}"`,
+ `data-hypit-end-frame="${startFrame + durationFrames}"`,
+ `data-hypit-source-fps="${element.sampling!.sourceFrameRate.numerator}/${element.sampling!.sourceFrameRate.denominator}"`,
`style="${escapeHtml(inlineStyle)}"`,
attributes(element.attributes).trim(),
"muted",
@@ -401,7 +404,9 @@ function renderElement(
`height="${element.surface.height}"`,
].join(" ");
if (element.surface.timing.kind === "still") return `<img ${common} ${surface} src="${source}"/>`;
- return `<video ${common} ${surface} muted playsinline src="${source}"></video>`;
+ const timing = element.surface.timing;
+ const exact = `data-hypit-start-frame="${context.presentStartFrame}" data-hypit-end-frame="${context.presentStartFrame + timing.frameCount}" data-hypit-source-frame="0/1" data-hypit-source-rate="1/1" data-hypit-source-fps="${timing.frameRate.numerator}/${timing.frameRate.denominator}"`;
+ return `<video ${common} ${surface} ${exact} muted playsinline src="${source}"></video>`;
}
const media = [
@@ -413,7 +418,8 @@ function renderElement(
].filter(Boolean).join(" ");
const source = escapeHtml(hyperframesResourceUri(element.artifact.resource));
if (element.kind === "image") return `<img ${common} ${media} src="${source}"/>`;
- return `<video ${common} ${media} src="${source}">${descendants}</video>`;
+ const exact = `data-hypit-start-frame="${context.presentStartFrame}" data-hypit-end-frame="${context.presentStartFrame + context.presentDurationFrames}" data-hypit-source-frame="0/1" data-hypit-source-rate="1/1" data-hypit-source-fps="${context.programNumerator}/${context.programDenominator}"`;
+ return `<video ${common} ${media} ${exact} src="${source}">${descendants}</video>`;
}
function renderVisualPresent(
diff --git a/packages/hyperframes/src/types.ts b/packages/hyperframes/src/types.ts
index 0529eb39..9966249f 100644
--- a/packages/hyperframes/src/types.ts
+++ b/packages/hyperframes/src/types.ts
@@ -28,7 +28,7 @@ export type HyperframesDocument = HyperframesFrameDomain & {
readonly html: string;
};
-/** Runtime-local work unit; chunk selection is never author intent or a Core object. */
+/** A half-open interval on the document frame clock, also used for local worker partitions. */
export type HyperframesFrameSpan = {
readonly startFrame: number;
readonly endFrameExclusive: number;
diff --git a/packages/media-execution/README.md b/packages/media-execution/README.md
index 50915e29..ca5a3799 100644
--- a/packages/media-execution/README.md
+++ b/packages/media-execution/README.md
@@ -2,6 +2,12 @@
Shared FFmpeg execution body for Hypit media Providers.
+Timeline-audio requests accept an optional `range: { startFrame, endFrameExclusive }` on the
+original programme clock. Only overlapping clips are read. Loop phase, tempo, gain and fades
+are evaluated in their original clip coordinates before trimming and rebasing the selected mix.
+The output remains 48 kHz stereo PCM. At rational frame rates, its sample count is rounded from
+the selected frame count; reconciling that zero-based clock can trim or pad one boundary sample.
+
`@hypit/media-pipeline` owns provider-neutral Needs, plans and result contracts. This package
owns the byte-level implementations of the eight current operations:
diff --git a/packages/media-execution/src/execute.ts b/packages/media-execution/src/execute.ts
index 6d55d641..99459daf 100644
--- a/packages/media-execution/src/execute.ts
+++ b/packages/media-execution/src/execute.ts
@@ -4,7 +4,7 @@ import { createReadStream } from "node:fs";
import { mkdtemp, open, readFile, rm, stat, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
-import { mediaTypes, sealMediaInspection, sealMuxedMedia, sealSynchronizedMedia, sealTimelineAudio, verifyMediaInspection, verifyMediaStreamSelection, verifyRenderedVisual, verifySynchronizedMedia, verifyTimelineAudio } from "@hypit/media";
+import { verifyMediaFrameRange, mediaFrameRangeSamples, mediaTypes, sealMediaInspection, sealMuxedMedia, sealSynchronizedMedia, sealTimelineAudio, verifyMediaInspection, verifyMediaStreamSelection, verifyRenderedVisual, verifySynchronizedMedia, verifyTimelineAudio } from "@hypit/media";
import type { MediaAudioStream, MediaInspection, MediaRational, MediaStream, MediaStreamSelection, MediaTimestamp, MediaVideoStream, MuxedMedia, RenderedVisual, SynchronizedMedia, TimelineAudio } from "@hypit/media";
import type { ProgramSpace } from "@hypit/program-space";
import { assertSpeechEvidenceAudioIdentity, sealSpeechEvidenceAudio, speechEvidenceSampleBoundary, speechTypes } from "@hypit/speech";
@@ -503,6 +503,7 @@ function evidenceAudioNeed(value: CanonicalValue): ProjectSpeechEvidenceAudioNee
function renderAudioNeed(value: CanonicalValue): RenderAudioNeed {
const item = object(value, "RenderAudioNeed") as unknown as RenderAudioNeed;
verifyAudioProgramPlan(item.plan);
+ if (item.range !== undefined) verifyMediaFrameRange(item.range, item.plan.frameCount);
return item;
}
@@ -534,9 +535,12 @@ function atempo(rate: number): string[] {
return filters;
}
-function audioClipFilter(clip: AudioProgramClip, inputIndex: number, outputIndex: number): string {
+function audioClipFilter(clip: AudioProgramClip, inputIndex: number, outputIndex: number,
+ window: { readonly startSample: number; readonly endSampleExclusive: number }): string {
const length = clip.targetEndSampleExclusive - clip.targetStartSample;
const sourceLength = clip.sourceEndSampleExclusive - clip.sourceStartSample;
+ const left = Math.max(window.startSample, clip.targetStartSample);
+ const right = Math.min(window.endSampleExclusive, clip.targetEndSampleExclusive);
const filters = [
`atrim=start_sample=${clip.sourceStartSample}:end_sample=${clip.sourceEndSampleExclusive}`,
"asetpts=PTS-STARTPTS",
@@ -554,7 +558,10 @@ function audioClipFilter(clip: AudioProgramClip, inputIndex: number, outputIndex
...(clip.fadeOutSamples === 0 ? [] : [
`afade=t=out:start_sample=${length - clip.fadeOutSamples}:nb_samples=${clip.fadeOutSamples}`,
]),
- `adelay=${clip.targetStartSample}S:all=1`,
+ // Crop after tempo, looping and envelopes, keeping their original phase.
+ `atrim=start_sample=${left - clip.targetStartSample}:end_sample=${right - clip.targetStartSample}`,
+ "asetpts=N/SR/TB",
+ `adelay=${left - window.startSample}S:all=1`,
];
return `[${inputIndex}:a:0]${filters.join(",")}[clip${outputIndex}]`;
}
@@ -1145,10 +1152,15 @@ export async function executeRenderTimelineAudio(
): Promise<MediaOperationResult> {
const need = renderAudioNeed(constraints);
const plan: AudioProgramPlan = need.plan;
+ const window = need.range === undefined
+ ? { startSample: 0, endSampleExclusive: plan.sampleFrames, sampleFrames: plan.sampleFrames }
+ : mediaFrameRangeSamples(need.range, plan.frameRate);
+ const clips = plan.clips.filter((clip) => clip.targetStartSample < window.endSampleExclusive
+ && clip.targetEndSampleExclusive > window.startSample);
const work = await mkdtemp(join(tmpdir(), "hypit-media-audio-"));
try {
const artifacts = new Map<string, { source: BlobRef; path: string; inputIndex: number; sampleFrames: number }>();
- for (const clip of plan.clips) {
+ for (const clip of clips) {
const existing = artifacts.get(clip.artifact.resource);
if (existing !== undefined) {
assert(existing.sampleFrames === clip.sourceSampleFrames,
@@ -1179,20 +1191,20 @@ export async function executeRenderTimelineAudio(
const output = join(work, "program.wav");
const argv = ["-y"];
for (const item of artifacts.values()) argv.push("-i", item.path);
- if (plan.clips.length === 0) {
+ if (clips.length === 0) {
argv.push(
"-f", "lavfi", "-i", "anullsrc=r=48000:cl=stereo",
- "-af", `atrim=start_sample=0:end_sample=${plan.sampleFrames},asetpts=N/SR/TB`,
+ "-af", `atrim=start_sample=0:end_sample=${window.sampleFrames},asetpts=N/SR/TB`,
);
} else {
- const chains = plan.clips.map((clip, index) => {
+ const chains = clips.map((clip, index) => {
const inputIndex = artifacts.get(clip.artifact.resource)!.inputIndex;
- return audioClipFilter(clip, inputIndex, index);
+ return audioClipFilter(clip, inputIndex, index, window);
});
- const labels = plan.clips.map((_clip, index) => `[clip${index}]`).join("");
+ const labels = clips.map((_clip, index) => `[clip${index}]`).join("");
chains.push(
- `${labels}amix=inputs=${plan.clips.length}:duration=longest:dropout_transition=0:normalize=0,`
- + `apad=whole_len=${plan.sampleFrames},atrim=start_sample=0:end_sample=${plan.sampleFrames},`
+ `${labels}amix=inputs=${clips.length}:duration=longest:dropout_transition=0:normalize=0,`
+ + `apad=whole_len=${window.sampleFrames},atrim=start_sample=0:end_sample=${window.sampleFrames},`
+ "asetpts=N/SR/TB[out]",
);
argv.push("-filter_complex", chains.join(";"), "-map", "[out]");
@@ -1214,11 +1226,11 @@ export async function executeRenderTimelineAudio(
maxProbeOutputBytes: env.maxProbeOutputBytes,
...(env.sharedLibraryPath === undefined ? {} : { sharedLibraryPath: env.sharedLibraryPath }),
});
- assert(audio.decodedSampleFrames === plan.sampleFrames,
+ assert(audio.decodedSampleFrames === window.sampleFrames,
"Rendered TimelineAudio sample count differs from its plan");
const value: TimelineAudio = sealTimelineAudio({
artifact,
- sampleFrames: plan.sampleFrames,
+ sampleFrames: window.sampleFrames,
});
return inlineResult(canonicalize(value));
} finally {
diff --git a/packages/media-pipeline/src/component.ts b/packages/media-pipeline/src/component.ts
index e7a67a3c..47febd12 100644
--- a/packages/media-pipeline/src/component.ts
+++ b/packages/media-pipeline/src/component.ts
@@ -1,3 +1,4 @@
+import { verifyMediaFrameRange } from "@hypit/media";
import { mediaComponent } from "@hypit/media";
import { plannedNeedInputs } from "@hypit/component-kit";
import type { ComponentPackage, PlannedNeedFacet } from "@hypit/component-kit";
@@ -311,6 +312,17 @@ export const mediaPipelineComponent = {
return { outputs: {}, needs: { audio: canonicalize(need) } };
},
},
+ {
+ producer: mediaPipelineProducers.renderAudioRange,
+ handler: ({ inputs }) => {
+ const plan = inline(inputs.plan!.value, "AudioProgramPlan");
+ verifyAudioProgramPlan(plan);
+ const range = inline(inputs.range!.value, "MediaFrameRange");
+ verifyMediaFrameRange(range, plan.frameCount);
+ const need: RenderAudioNeed = { plan, range };
+ return { outputs: {}, needs: { audio: canonicalize(need) } };
+ },
+ },
{
producer: mediaPipelineProducers.mux,
handler: ({ inputs }) => {
@@ -352,6 +364,7 @@ export const mediaPipelineComponent = {
{ media: "audio" },
),
plannedMediaNeed(mediaPipelineProducers.renderAudio, "audio", mediaPipelineCapabilities.renderAudio, { plan: "audio" }),
+ plannedMediaNeed(mediaPipelineProducers.renderAudioRange, "audio", mediaPipelineCapabilities.renderAudio, { plan: "audio" }),
plannedMediaNeed(mediaPipelineProducers.mux, "media", mediaPipelineCapabilities.mux, { visual: "video", audio: "audio" }),
],
} satisfies ComponentPackage;
diff --git a/packages/media-pipeline/src/manifest.ts b/packages/media-pipeline/src/manifest.ts
index 88ca2df3..ec9226af 100644
--- a/packages/media-pipeline/src/manifest.ts
+++ b/packages/media-pipeline/src/manifest.ts
@@ -47,6 +47,7 @@ export const mediaPipelineProducers = {
projectSpeechEvidenceAudio: { module: mediaPipelineModuleRef, name: "request-speech-evidence-audio" },
planAudio: { module: mediaPipelineModuleRef, name: "compile-audio-program" },
renderAudio: { module: mediaPipelineModuleRef, name: "request-audio-render" },
+ renderAudioRange: { module: mediaPipelineModuleRef, name: "request-audio-range" },
mux: { module: mediaPipelineModuleRef, name: "request-media-mux" },
projectMuxed: { module: mediaPipelineModuleRef, name: "project-muxed-media" },
} satisfies Record<string, ProducerRef>;
@@ -619,6 +620,16 @@ export const mediaPipelineManifest: ModuleManifest = {
returns: mediaTypes.timelineAudio,
}],
},
+ {
+ name: mediaPipelineProducers.renderAudioRange.name,
+ inputs: [{ name: "plan", type: mediaPipelineTypes.audioProgramPlan }, { name: "range", type: mediaTypes.frameRange }],
+ outputs: [],
+ needs: [{
+ name: "audio",
+ capability: mediaPipelineCapabilities.renderAudio,
+ returns: mediaTypes.timelineAudio,
+ }],
+ },
{
name: mediaPipelineProducers.mux.name,
inputs: [
diff --git a/packages/media-pipeline/src/types.ts b/packages/media-pipeline/src/types.ts
index 4744025a..888f315f 100644
--- a/packages/media-pipeline/src/types.ts
+++ b/packages/media-pipeline/src/types.ts
@@ -1,5 +1,5 @@
import type { BlobRef } from "@hypit/protocol";
-import type { MediaInspection, MediaRational, MediaStreamSelection, RenderedVisual, TimelineAudio } from "@hypit/media";
+import type { MediaFrameRange, MediaInspection, MediaRational, MediaStreamSelection, RenderedVisual, TimelineAudio } from "@hypit/media";
export type MediaSelectionRequest = {
readonly video:
@@ -166,6 +166,7 @@ export type AudioProgramPlan = {
export type RenderAudioNeed = {
readonly plan: AudioProgramPlan;
+ readonly range?: MediaFrameRange;
};
export type MuxMediaNeed = {
diff --git a/packages/media/src/component.ts b/packages/media/src/component.ts
index f7b57b76..38bf6694 100644
--- a/packages/media/src/component.ts
+++ b/packages/media/src/component.ts
@@ -1,9 +1,11 @@
import type { ComponentPackage } from "@hypit/component-kit";
import { verifyMediaInspection, verifyMediaStreamSelection, verifyMuxedMedia, verifyRenderedVisual, verifySynchronizedMedia, verifyTimelineAudio } from "./identity.js";
import { mediaTypes } from "./manifest.js";
+import { verifyMediaFrameRange } from "./frame-range.js";
function inline(value: { readonly kind: string; readonly value?: unknown }, subject: string): unknown { if (value.kind !== "inline") throw new Error(`${subject} must be inline`); return value.value; }
export const mediaComponent = {
validators: [
+ { type: mediaTypes.frameRange, handler: ({ value }) => verifyMediaFrameRange(inline(value, "MediaFrameRange")) },
{ type: mediaTypes.inspection, handler: ({ value }) => verifyMediaInspection(inline(value, "MediaInspection")) },
{ type: mediaTypes.streamSelection, handler: ({ value }) => verifyMediaStreamSelection(inline(value, "MediaStreamSelection")) },
{ type: mediaTypes.synchronized, handler: ({ value }) => verifySynchronizedMedia(inline(value, "SynchronizedMedia")) },
diff --git a/packages/media/src/frame-range.ts b/packages/media/src/frame-range.ts
new file mode 100644
index 00000000..0eb63103
--- /dev/null
+++ b/packages/media/src/frame-range.ts
@@ -0,0 +1,33 @@
+import type { MediaRational } from "./types.js";
+
+/** A half-open selection on the original programme frame clock. */
+export type MediaFrameRange = {
+ readonly startFrame: number;
+ readonly endFrameExclusive: number;
+};
+
+export function verifyMediaFrameRange(value: unknown, frameCount?: number): asserts value is MediaFrameRange {
+ const range = value as MediaFrameRange | undefined;
+ if (range === null || typeof range !== "object"
+ || !Number.isSafeInteger(range.startFrame) || range.startFrame < 0
+ || !Number.isSafeInteger(range.endFrameExclusive) || range.endFrameExclusive <= range.startFrame
+ || (frameCount !== undefined && range.endFrameExclusive > frameCount)) {
+ throw new Error("Media frame range must satisfy 0 <= startFrame < endFrameExclusive <= frameCount");
+ }
+}
+
+/**
+ * Start on the original clock; duration belongs to the new zero-based frame clock.
+ * At rational rates, rounding the two clocks can differ by one PCM sample.
+ */
+export function mediaFrameRangeSamples(range: MediaFrameRange, frameRate: MediaRational) {
+ verifyMediaFrameRange(range);
+ const boundary = (frame: number): number => {
+ const n = BigInt(frame) * 48_000n * BigInt(frameRate.denominator);
+ const d = BigInt(frameRate.numerator);
+ return Number((2n * n + d) / (2n * d));
+ };
+ const startSample = boundary(range.startFrame);
+ const sampleFrames = boundary(range.endFrameExclusive - range.startFrame);
+ return { startSample, endSampleExclusive: startSample + sampleFrames, sampleFrames };
+}
diff --git a/packages/media/src/index.ts b/packages/media/src/index.ts
index 5bbfd30b..80c120a3 100644
--- a/packages/media/src/index.ts
+++ b/packages/media/src/index.ts
@@ -11,3 +11,5 @@ export { compositableSurfaceSchema, fontArtifactSchema, fontStackSchema, mediaIn
export { assertCompositableSurfaceRef, assertFontArtifactRef, assertFontStackRef } from "./render.js";
export type * from "./render.js";
export type * from "./types.js";
+export { verifyMediaFrameRange, mediaFrameRangeSamples } from "./frame-range.js";
+export type { MediaFrameRange } from "./frame-range.js";
diff --git a/packages/media/src/manifest.ts b/packages/media/src/manifest.ts
index 243cd85a..98f9aad6 100644
--- a/packages/media/src/manifest.ts
+++ b/packages/media/src/manifest.ts
@@ -3,6 +3,7 @@ import type { ModuleManifest, TypeRef } from "@hypit/protocol";
import { compositableSurfaceSchema, fontArtifactSchema, fontStackSchema, mediaInspectionSchema, mediaStreamSelectionSchema, muxedMediaSchema, renderedVisualSchema, synchronizedMediaSchema, timelineAudioSchema } from "./schema.js";
export const mediaModuleRef = { name: "@hypit/media", version: "1" } as const;
export const mediaTypes = {
+ frameRange: { module: mediaModuleRef, name: "MediaFrameRange" },
inspection: { module: mediaModuleRef, name: "MediaInspection" },
streamSelection: { module: mediaModuleRef, name: "MediaStreamSelection" }, synchronized: { module: mediaModuleRef, name: "SynchronizedMedia" },
renderedVisual: { module: mediaModuleRef, name: "RenderedVisual" }, timelineAudio: { module: mediaModuleRef, name: "TimelineAudio" },
@@ -107,6 +108,7 @@ export const mediaMarkupSurfaces = [
export const mediaManifest: ModuleManifest = {
format: "hypit.module@1", name: mediaModuleRef.name, version: mediaModuleRef.version, dependencies: [artifactDependency],
types: [
+ { name: mediaTypes.frameRange.name },
{ name: mediaTypes.inspection.name },
{ name: mediaTypes.streamSelection.name },
{ name: mediaTypes.synchronized.name },
diff --git a/packages/provider-hyperframes-aws-lambda/src/provider.ts b/packages/provider-hyperframes-aws-lambda/src/provider.ts
index 35709461..3459484a 100644
--- a/packages/provider-hyperframes-aws-lambda/src/provider.ts
+++ b/packages/provider-hyperframes-aws-lambda/src/provider.ts
@@ -408,13 +408,12 @@ export function createAwsLambdaHyperframesProvider(config: CreateAwsLambdaHyperf
outputKey: outputKey(context.operation),
executionName: executionName(context.operation),
});
+ const handle = makeHandle(context, site, render, startedAt);
+ return wakeAfter(canonicalize(handle), pollIntervalMs, now(), { phase: "submitted" });
} catch (error) {
- return implementationFailure("HYPERFRAMES_SUBMISSION_FAILED", error);
+ return { status: "pending", wakeAt: now() + 30_000, progress: { phase: "submission-unknown" },
+ failure: { code: "SUBMISSION_UNKNOWN", message: "HyperFrames submission acknowledgement is unknown; the same Build will not submit again" } };
}
- const handle = makeHandle(context, site, render, startedAt);
- return wakeAfter(canonicalize(handle), pollIntervalMs, now(), {
- phase: "submitted",
- });
};
const safeSubmit = async (
@@ -434,11 +433,11 @@ export function createAwsLambdaHyperframesProvider(config: CreateAwsLambdaHyperf
try {
handle = readHandle(context.handle, context);
} catch (error) {
- return implementationFailure("HYPERFRAMES_HANDLE_INVALID", error);
+ throw error;
}
- if (now() - handle.startedAt >= maxOperationMs) {
- return implementationFailure("HYPERFRAMES_OPERATION_TIMEOUT",
- new Error("HyperFrames render exceeded its operation deadline"));
+ if (!context.settling && now() - handle.startedAt >= maxOperationMs) {
+ return { ...wakeAfter(canonicalize(handle), pollIntervalMs, now(), { phase: "settling" }),
+ failure: { code: "HYPERFRAMES_OPERATION_TIMEOUT", message: "HyperFrames deadline exceeded; waiting for remote termination" } };
}
let document: HyperframesDocument;
let progress: HyperframesLambdaProgress;
@@ -450,12 +449,12 @@ export function createAwsLambdaHyperframesProvider(config: CreateAwsLambdaHyperf
region,
});
} catch (error) {
- return implementationFailure("HYPERFRAMES_PROGRESS_UNAVAILABLE", error);
+ return wakeAfter(canonicalize(handle), pollIntervalMs, now(), { phase: "poll-unavailable" });
}
try {
verifyProgress(progress, document);
} catch (error) {
- return implementationFailure("HYPERFRAMES_PROGRESS_INVALID", error);
+ return wakeAfter(canonicalize(handle), pollIntervalMs, now(), { phase: "poll-unavailable" });
}
const next = { ...handle, polls: handle.polls + 1 };
if (progress.status === "RUNNING") {
@@ -466,6 +465,7 @@ export function createAwsLambdaHyperframesProvider(config: CreateAwsLambdaHyperf
unit: "frames",
});
}
+ if (context.settling) return { status: "settled" };
if (progress.status !== "SUCCEEDED") {
const details = progress.errors.map((item) => `${item.state}: ${item.error}: ${item.cause}`).join("; ");
return implementationFailure(`HYPERFRAMES_${progress.status}`,
diff --git a/packages/provider-hyperframes-aws-lambda/test/provider.test.ts b/packages/provider-hyperframes-aws-lambda/test/provider.test.ts
index eca6011c..856ca9d0 100644
--- a/packages/provider-hyperframes-aws-lambda/test/provider.test.ts
+++ b/packages/provider-hyperframes-aws-lambda/test/provider.test.ts
@@ -210,6 +210,9 @@ function context(request: Need, resources: ResourceStore) {
}
test("the Lambda Endpoint declines frame domains and requirements it cannot preserve", () => {
+ assert.equal(supportsAwsLambdaHyperframes(hyperframesVisualRequest(documentFixture(30), {
+ range: { startFrame: 3, endFrameExclusive: 6 },
+ })), false, "a range must not silently become a whole-document render");
assert.equal(supportsAwsLambdaHyperframes(hyperframesVisualRequest(documentFixture(24))), true);
assert.equal(supportsAwsLambdaHyperframes(hyperframesVisualRequest(documentFixture(30))), true);
assert.equal(supportsAwsLambdaHyperframes(hyperframesVisualRequest(documentFixture(60))), true);
@@ -307,7 +310,7 @@ test("one submission is polled and streams the output into the ResourceStore", a
const completed = await endpoint.poll({
...common,
- handle: started.handle,
+ handle: started.handle!,
});
assert.equal(completed.status, "completed", JSON.stringify(completed));
assert.equal(streamed, 2, "the remote object should use the streaming ResourceStore facet");
@@ -340,7 +343,7 @@ test("running render progress is projected without exposing the private handle",
if (started.status !== "pending") return;
const running = await endpoint.poll({
...common,
- handle: started.handle,
+ handle: started.handle!,
});
assert.equal(running.status, "pending");
if (running.status === "pending") {
@@ -360,7 +363,7 @@ test("cancellation stops the submitted execution", async () => {
if (started.status !== "pending") return;
await endpoint.cancel({
...common,
- handle: started.handle,
+ handle: started.handle!,
});
assert.equal(state.stopped.length, 1);
});
diff --git a/packages/provider-hyperframes-local/README.md b/packages/provider-hyperframes-local/README.md
index 507fc2ac..718de158 100644
--- a/packages/provider-hyperframes-local/README.md
+++ b/packages/provider-hyperframes-local/README.md
@@ -2,35 +2,75 @@
Trusted local Provider for the `@hypit/render-hyperframes#render-visual` capability. It stages the
Resource dependencies declared by a `HyperframesDocument`, renders a silent MP4 with the
-HyperFrames CLI, probes the bytes, and returns a verified `RenderedVisual`. Before staging a typed
+HyperFrames engine, probes the bytes, and returns a verified `RenderedVisual`. Before staging a typed
Surface it decodes the exact bytes and checks declared dimensions, still/frame timing, SDR/sRGB and
opaque/straight-alpha facts. These checks validate the typed rendering input; they do not create
content identity or hidden output metadata.
-There are deliberately two concurrency controls:
+Runtime configuration separates work size from shared capacity:
- `defaultConcurrency` limits whole render requests admitted by the Endpoint's Runtime capacity resource.
-- `workers` controls HyperFrames' parallel Chrome frame workers inside one admitted render.
+- Optional `browserCapacity` limits Chrome slots shared by all render Needs in the same `pool`.
+ Each Need reserves its actual worker count atomically with the whole-request slot. A request larger
+ than this budget reports a configuration error; it does not silently reduce the requested workers.
+- `workers` controls independent Chrome processes inside one admitted render. Explicit counts are
+ honored, capped only by selected frame count. `auto` uses half the available CPU parallelism,
+ bounded to 1–4 workers.
-The Provider owns both controls because they are deployment policy, not author intent. It never
+The Runtime Profile configures these controls through the Provider because they are deployment policy.
+`auto` is resolved when the Provider is activated, so admission and execution use the same count. It never
renders program audio; `@hypit/provider-media-local` separately prepares `TimelineAudio` and muxes
the final media.
-`browserGpu` picks Chrome's rasterizer and defaults to `hardware`, so composited frames are drawn by
-the GPU. The cost of the alternative is large rather than marginal: on `software` the same
-1080×1920 render falls to SwiftShader on the CPU and takes tens of minutes where the GPU takes a few.
-Set `software` on a machine with no usable GPU, or `auto` to let the HyperFrames CLI decide.
+`browserGpu` picks Chrome's rasterizer and defaults to `hardware`. Set `software` without a usable
+GPU, or `auto` to let the engine decide. Capture uses screenshots and independent browser processes;
+the CLI's automatic worker and drawElement policies do not override the count.
The Runtime Adapter also declares one managed browser program. `programs up` invokes the pinned
HyperFrames CLI's `browser ensure`; its probe resolves and starts that browser and checks
ffprobe before a Build.
+The same executor is exported for callers with an already compiled document:
+
+```ts
+const visual = await renderHyperframesVisual(
+ { document, range: { startFrame: 240, endFrameExclusive: 360 } },
+ { resources, workers: 4, onProgress: (event) => console.log(event) },
+);
+```
+
+Omit `range` for the complete document. Ranges are zero-based and half-open on the original
+programme clock. At 30 fps, `[240, 360)` returns 120 frames covering seconds 8–12.
+`onProgress` reports preparation, worker ranges, browser PIDs, completion and elapsed time.
+`signal` cancels capture and encoding; `processTimeoutMs` bounds the operation.
+`initializationTimeoutMs` (30 seconds by default) and `frameTimeoutMs` (15 seconds) bound each
+worker's initialization and individual frame capture. Errors name the worker and stage/frame.
+A completed worker closes its Chrome immediately. A timeout aborts the other workers and awaits cleanup.
+
+One call stages the HTML and assets once, merges overlapping source-frame extraction windows,
+and shares decoded PNGs across workers. Each worker initializes its own page and captures its
+assigned frames at their original absolute times. Output numbering starts at zero; encoding runs
+once. Exact compiler sampling markers retain loops, holds and fractional playback rates. There is
+no SVML rewrite, intermediate cut MP4 or repeat normalization. Already compiled video documents
+need the current compiler's frame markers.
+
+Source extraction uses the pinned engine's FFmpeg/FFprobe resolver. `ffmpegPath` selects the final
+H.264 encoder; `ffprobePath` verifies output and typed surfaces. `nodePath` and `hyperframesCliPath`
+serve managed browser installation. The requested frame range travels in the Model's Need.
+
```ts
const provider = createLocalHyperframesProvider({
+ pool: "local-render",
workers: 4,
- defaultConcurrency: 1,
+ defaultConcurrency: 2,
+ browserCapacity: 6,
});
```
+Two instances in `local-render`, configured with 4 and 2 workers and identical capacity limits, can
+render together. With `browserCapacity: 4`, the second waits. This budget covers Chrome slots;
+source decoding and final encoding remain separate phases, not per-frame Chrome workers. Direct
+`renderHyperframesVisual()` calls do not enter Runtime's shared admission system.
+
The current package executes trusted official code in a local process. It is not a sandbox for
untrusted documents or community renderer implementations.
diff --git a/packages/provider-hyperframes-local/package.json b/packages/provider-hyperframes-local/package.json
index 24806f9b..d13c57cb 100644
--- a/packages/provider-hyperframes-local/package.json
+++ b/packages/provider-hyperframes-local/package.json
@@ -11,6 +11,8 @@
"activation": "./src/activation.ts"
},
"dependencies": {
+ "@hyperframes/engine": "0.7.101",
+ "@hyperframes/producer": "0.7.101",
"@hypit/endpoint-kit": "workspace:*",
"@hypit/hyperframes": "workspace:*",
"@hypit/media": "workspace:*",
@@ -19,8 +21,8 @@
"@hypit/protocol": "workspace:*",
"@hypit/render-hyperframes": "workspace:*",
"@hypit/runtime": "workspace:*",
- "@hypit/runtime-kit": "workspace:*",
"@hypit/runtime-host-node": "workspace:*",
+ "@hypit/runtime-kit": "workspace:*",
"hyperframes": "0.7.101"
},
"devDependencies": {
diff --git a/packages/provider-hyperframes-local/src/activation.ts b/packages/provider-hyperframes-local/src/activation.ts
index 585ca994..5d26369c 100644
--- a/packages/provider-hyperframes-local/src/activation.ts
+++ b/packages/provider-hyperframes-local/src/activation.ts
@@ -21,16 +21,15 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
if (context.pool === undefined) throw new Error("local HyperFrames Provider Pool is required");
const config = runtimeConfigObject(context.config, "local HyperFrames");
runtimeConfigExact(config, [
- "nodePath", "hyperframesCliPath", "ffprobePath", "workers", "quality", "browserGpu",
- "defaultConcurrency", "processTimeoutMs", "maxProcessOutputBytes", "maxRenderedBytes",
+ "nodePath", "hyperframesCliPath", "ffprobePath", "ffmpegPath", "workers", "quality", "browserGpu",
+ "defaultConcurrency", "browserCapacity", "initializationTimeoutMs", "frameTimeoutMs", "processTimeoutMs", "maxProcessOutputBytes", "maxRenderedBytes",
], "local HyperFrames");
runtimeConfigString(config.nodePath, "HyperFrames nodePath");
runtimeConfigString(config.hyperframesCliPath, "HyperFrames hyperframesCliPath");
runtimeConfigString(config.ffprobePath, "HyperFrames ffprobePath");
const workers = config.workers;
if (workers !== undefined && workers !== "auto") {
- const count = runtimeConfigPositiveInteger(workers, "HyperFrames workers");
- if (count !== undefined && count > 64) throw new Error("HyperFrames workers must not exceed 64");
+ runtimeConfigPositiveInteger(workers, "HyperFrames workers");
}
const quality = runtimeConfigString(config.quality, "HyperFrames quality");
if (quality !== undefined && quality !== "draft" && quality !== "standard" && quality !== "high") {
@@ -45,8 +44,13 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
const configuredFfprobe = runtimeConfigString(config.ffprobePath, "HyperFrames ffprobePath");
const nodePath = resolveRuntimeExecutable(context.dataRoot, configuredNode ?? process.execPath);
const hyperframesCliPath = resolveRuntimeExecutable(context.dataRoot, configuredCli ?? defaultHyperframesCliPath());
+ const configuredFfmpeg = runtimeConfigString(config.ffmpegPath, "HyperFrames ffmpegPath");
+ const ffmpegPath = resolveRuntimeExecutable(context.dataRoot, configuredFfmpeg ?? "ffmpeg");
const ffprobePath = resolveRuntimeExecutable(context.dataRoot, configuredFfprobe ?? "ffprobe");
const defaultConcurrency = runtimeConfigPositiveInteger(config.defaultConcurrency, "HyperFrames defaultConcurrency");
+ const browserCapacity = runtimeConfigPositiveInteger(config.browserCapacity, "HyperFrames browserCapacity");
+ const initializationTimeoutMs = runtimeConfigPositiveInteger(config.initializationTimeoutMs, "HyperFrames initializationTimeoutMs");
+ const frameTimeoutMs = runtimeConfigPositiveInteger(config.frameTimeoutMs, "HyperFrames frameTimeoutMs");
const processTimeoutMs = runtimeConfigPositiveInteger(config.processTimeoutMs, "HyperFrames processTimeoutMs");
const maxProcessOutputBytes = runtimeConfigPositiveInteger(config.maxProcessOutputBytes, "HyperFrames maxProcessOutputBytes");
const maxRenderedBytes = runtimeConfigPositiveInteger(config.maxRenderedBytes, "HyperFrames maxRenderedBytes");
@@ -57,10 +61,14 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
nodePath,
hyperframesCliPath,
ffprobePath,
+ ffmpegPath,
...(workers === undefined ? {} : { workers: workers as HyperframesWorkers }),
...(quality === undefined ? {} : { quality: quality as HyperframesQuality }),
...(browserGpu === undefined ? {} : { browserGpu: browserGpu as HyperframesBrowserGpu }),
...(defaultConcurrency === undefined ? {} : { defaultConcurrency }),
+ ...(browserCapacity === undefined ? {} : { browserCapacity }),
+ ...(initializationTimeoutMs === undefined ? {} : { initializationTimeoutMs }),
+ ...(frameTimeoutMs === undefined ? {} : { frameTimeoutMs }),
...(processTimeoutMs === undefined ? {} : { processTimeoutMs }),
...(maxProcessOutputBytes === undefined ? {} : { maxProcessOutputBytes }),
...(maxRenderedBytes === undefined ? {} : { maxRenderedBytes }),
@@ -70,8 +78,10 @@ const localHyperframesRuntimeAdapter = createRuntimeEndpointAdapterFacet({
nodePath,
hyperframesCliPath,
ffprobePath,
+ ffmpegPath,
}),
diagnose: async () => [
+ ...await diagnoseRuntimeExecutable({ root: context.dataRoot, configured: configuredFfmpeg, fallback: "ffmpeg", subject: "FFmpeg" }),
...await diagnoseRuntimeExecutable({
root: context.dataRoot,
configured: configuredNode,
diff --git a/packages/provider-hyperframes-local/src/index.ts b/packages/provider-hyperframes-local/src/index.ts
index bce74fb1..380f7e15 100644
--- a/packages/provider-hyperframes-local/src/index.ts
+++ b/packages/provider-hyperframes-local/src/index.ts
@@ -5,3 +5,6 @@ export type {
HyperframesQuality,
HyperframesWorkers,
} from "./provider.js";
+
+export { renderHyperframesVisual } from "./render.js";
+export type { RenderHyperframesVisualOptions, HyperframesRenderProgress } from "./render.js";
diff --git a/packages/provider-hyperframes-local/src/options.ts b/packages/provider-hyperframes-local/src/options.ts
new file mode 100644
index 00000000..c182a7c3
--- /dev/null
+++ b/packages/provider-hyperframes-local/src/options.ts
@@ -0,0 +1,19 @@
+export type HyperframesWorkers = number | "auto";
+export type HyperframesQuality = "draft" | "standard" | "high";
+export type HyperframesBrowserGpu = "auto" | "software" | "hardware";
+
+export type HyperframesExecutionOptions = {
+ readonly ffprobePath?: string;
+ /** Final H.264 encoder. Source extraction uses the pinned engine's binary resolver. */
+ readonly ffmpegPath?: string;
+ /** Parallel Chrome workers inside one render. This is separate from Provider request concurrency. */
+ readonly workers?: HyperframesWorkers;
+ readonly quality?: HyperframesQuality;
+ /** Chrome's rasterizer, default hardware. Use software without a usable GPU. */
+ readonly browserGpu?: HyperframesBrowserGpu;
+ readonly processTimeoutMs?: number;
+ readonly initializationTimeoutMs?: number;
+ readonly frameTimeoutMs?: number;
+ readonly maxProcessOutputBytes?: number;
+ readonly maxRenderedBytes?: number;
+};
diff --git a/packages/provider-hyperframes-local/src/output.ts b/packages/provider-hyperframes-local/src/output.ts
new file mode 100644
index 00000000..415d2b9c
--- /dev/null
+++ b/packages/provider-hyperframes-local/src/output.ts
@@ -0,0 +1,73 @@
+import type { HyperframesDocument } from "@hypit/hyperframes";
+import { assert, runProcess } from "./process.js";
+
+type ProbeStream = {
+ readonly codec_type?: unknown;
+ readonly codec_name?: unknown;
+ readonly width?: unknown;
+ readonly height?: unknown;
+ readonly avg_frame_rate?: unknown;
+ readonly r_frame_rate?: unknown;
+ readonly nb_read_frames?: unknown;
+ readonly nb_frames?: unknown;
+};
+
+function parseRational(value: unknown, subject: string): { readonly numerator: bigint; readonly denominator: bigint } {
+ assert(typeof value === "string" && /^\d+\/\d+$/u.test(value), `${subject} is not a rational`);
+ const [numerator, denominator] = value.split("/");
+ assert(numerator !== undefined && denominator !== undefined && BigInt(denominator) > 0n,
+ `${subject} is invalid`);
+ return { numerator: BigInt(numerator), denominator: BigInt(denominator) };
+}
+
+function equalsRational(
+ actual: { readonly numerator: bigint; readonly denominator: bigint },
+ expected: { readonly numerator: number; readonly denominator: number },
+): boolean {
+ return actual.numerator * BigInt(expected.denominator)
+ === BigInt(expected.numerator) * actual.denominator;
+}
+
+function outputFrameCount(stream: ProbeStream): number {
+ const value = stream.nb_read_frames ?? stream.nb_frames;
+ assert(typeof value === "string" && /^\d+$/u.test(value), "Rendered visual has no decoded frame count");
+ const count = Number(value);
+ assert(Number.isSafeInteger(count), "Rendered visual frame count exceeds safe arithmetic");
+ return count;
+}
+
+export async function verifyOutput(args: {
+ readonly path: string;
+ readonly document: HyperframesDocument;
+ readonly ffprobePath: string;
+ readonly timeoutMs: number;
+ readonly maxOutputBytes: number;
+ readonly signal?: AbortSignal;
+}): Promise<void> {
+ const probe = await runProcess({
+ executable: args.ffprobePath,
+ argv: ["-v", "error", "-print_format", "json", "-show_streams", "-count_frames", args.path],
+ timeoutMs: args.timeoutMs,
+ maxOutputBytes: args.maxOutputBytes,
+ ...(args.signal === undefined ? {} : { signal: args.signal }),
+ });
+ let value: unknown;
+ try {
+ value = JSON.parse(Buffer.from(probe.stdout).toString("utf8"));
+ } catch {
+ throw new Error("ffprobe returned invalid JSON for the HyperFrames output");
+ }
+ assert(value !== null && typeof value === "object" && !Array.isArray(value),
+ "ffprobe returned an invalid HyperFrames inspection");
+ const streams = (value as { readonly streams?: unknown }).streams;
+ assert(Array.isArray(streams) && streams.length === 1, "Rendered visual must contain exactly one stream");
+ const stream = streams[0] as ProbeStream;
+ assert(stream.codec_type === "video" && stream.codec_name === "h264",
+ "Rendered visual must contain one H.264 video stream and no audio");
+ assert(stream.width === args.document.canvas.width && stream.height === args.document.canvas.height,
+ "Rendered visual canvas differs from its document");
+ const rate = parseRational(stream.avg_frame_rate ?? stream.r_frame_rate, "Rendered visual frame rate");
+ assert(equalsRational(rate, args.document.frameRate), "Rendered visual frame rate differs from its document");
+ assert(outputFrameCount(stream) === args.document.frameCount,
+ "Rendered visual frame count differs from its document");
+}
diff --git a/packages/provider-hyperframes-local/src/process.ts b/packages/provider-hyperframes-local/src/process.ts
new file mode 100644
index 00000000..9df20041
--- /dev/null
+++ b/packages/provider-hyperframes-local/src/process.ts
@@ -0,0 +1,79 @@
+import { spawn } from "node:child_process";
+
+type ProcessResult = {
+ readonly stdout: Uint8Array;
+ readonly stderr: string;
+};
+
+export function assert(condition: unknown, message: string): asserts condition {
+ if (!condition) throw new Error(message);
+}
+export function positiveInteger(value: number, subject: string): number {
+ assert(Number.isSafeInteger(value) && value > 0, `${subject} must be a positive integer`);
+ return value;
+}
+
+function processEnvironment(): NodeJS.ProcessEnv {
+ const names = ["PATH", "HOME", "TMPDIR", "LANG", "LC_ALL"] as const;
+ return Object.fromEntries(names.flatMap((name) => process.env[name] === undefined
+ ? []
+ : [[name, process.env[name]]])) as NodeJS.ProcessEnv;
+}
+
+export async function runProcess(args: {
+ readonly executable: string;
+ readonly argv: readonly string[];
+ readonly timeoutMs: number;
+ readonly maxOutputBytes: number;
+ readonly signal?: AbortSignal;
+}): Promise<ProcessResult> {
+ args.signal?.throwIfAborted();
+ return await new Promise((resolve, reject) => {
+ const child = spawn(args.executable, [...args.argv], {
+ shell: false,
+ windowsHide: true,
+ stdio: ["ignore", "pipe", "pipe"],
+ env: processEnvironment(),
+ });
+ const stdout: Buffer[] = [];
+ let outputBytes = 0;
+ let stderr = "";
+ let settled = false;
+ const finish = (error?: Error): void => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(timer);
+ args.signal?.removeEventListener("abort", abort);
+ if (error === undefined) resolve({ stdout: Buffer.concat(stdout), stderr });
+ else reject(error);
+ };
+ const abort = () => { child.kill("SIGKILL"); finish(args.signal?.reason ?? new Error("Process aborted")); };
+ args.signal?.addEventListener("abort", abort, { once: true });
+ const timer = setTimeout(() => {
+ child.kill("SIGKILL");
+ finish(new Error(`${args.executable} timed out`));
+ }, args.timeoutMs);
+ child.stdout.on("data", (chunk: Buffer) => {
+ outputBytes += chunk.byteLength;
+ if (outputBytes > args.maxOutputBytes) {
+ child.kill("SIGKILL");
+ finish(new Error(`${args.executable} output exceeded the configured limit`));
+ return;
+ }
+ stdout.push(chunk);
+ });
+ child.stderr.on("data", (chunk: Buffer) => {
+ outputBytes += chunk.byteLength;
+ stderr = `${stderr}${chunk.toString()}`.slice(-32_000);
+ if (outputBytes > args.maxOutputBytes) {
+ child.kill("SIGKILL");
+ finish(new Error(`${args.executable} output exceeded the configured limit`));
+ }
+ });
+ child.on("error", (error) => finish(error));
+ child.on("close", (code) => {
+ if (code === 0) finish();
+ else finish(new Error(`${args.executable} exited ${String(code)}: ${stderr}`));
+ });
+ });
+}
diff --git a/packages/provider-hyperframes-local/src/program.ts b/packages/provider-hyperframes-local/src/program.ts
index b2304cd9..182f3de7 100644
--- a/packages/provider-hyperframes-local/src/program.ts
+++ b/packages/provider-hyperframes-local/src/program.ts
@@ -24,6 +24,7 @@ export function localHyperframesBrowserProgram(
readonly nodePath: string;
readonly hyperframesCliPath: string;
readonly ffprobePath: string;
+ readonly ffmpegPath?: string;
},
): ManagedProgram {
const probeBrowser = async (): Promise<ManagedProgramState> => {
@@ -48,7 +49,7 @@ export function localHyperframesBrowserProgram(
async probe(): Promise<ManagedProgramState> {
const browser = await probeBrowser();
if (browser.state !== "ready") return browser;
- const media = await probeMediaToolchain({ ffprobePath: input.ffprobePath });
+ const media = await probeMediaToolchain({ ffprobePath: input.ffprobePath, ...(input.ffmpegPath === undefined ? {} : { ffmpegPath: input.ffmpegPath }) });
return media.state === "ready"
? { state: "ready" }
: { state: media.state, detail: media.detail };
diff --git a/packages/provider-hyperframes-local/src/provider.ts b/packages/provider-hyperframes-local/src/provider.ts
index 9102ffd7..7574e2e8 100644
--- a/packages/provider-hyperframes-local/src/provider.ts
+++ b/packages/provider-hyperframes-local/src/provider.ts
@@ -1,335 +1,61 @@
-import { spawn } from "node:child_process";
-import { createReadStream } from "node:fs";
-import { mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import { mediaTypes, sealRenderedVisual } from "@hypit/media";
-import type { RenderedVisual } from "@hypit/media";
-import { verifyCompositableSurfaceBytes } from "@hypit/media-execution";
-import type { EndpointInvocationContext, EndpointFulfillment } from "@hypit/endpoint-kit";
-import { assertHyperframesDocument } from "@hypit/hyperframes";
-import type { HyperframesDocument } from "@hypit/hyperframes";
-import { stageHyperframesProject } from "@hypit/hyperframes/project";
-import { renderHyperframesCapabilities } from "@hypit/render-hyperframes";
+import { defineEndpointPackage } from "@hypit/endpoint-kit";
+import { mediaTypes } from "@hypit/media";
+import { renderHyperframesCapabilities, verifyHyperframesVisualRequest } from "@hypit/render-hyperframes";
import { canonicalize } from "@hypit/protocol";
import { resolveNodePackageExecutable } from "@hypit/package-loader-node";
-import { isStreamingResourceStore } from "@hypit/runtime";
-import type { BlobRef, CanonicalValue } from "@hypit/protocol";
-import { defineEndpointPackage } from "@hypit/endpoint-kit";
-
-const HYPERFRAMES_VERSION = "0.7.101";
-
-export const localHyperframesProviderModuleRef = {
- name: "@hypit/provider-hyperframes-local",
- version: "1",
-} as const;
-
-export type HyperframesWorkers = number | "auto";
-export type HyperframesQuality = "draft" | "standard" | "high";
-export type HyperframesBrowserGpu = "auto" | "software" | "hardware";
+import { renderHyperframesVisual, resolveExecutionOptions } from "./render.js";
+import type { HyperframesExecutionOptions } from "./options.js";
-export type CreateLocalHyperframesProviderOptions = {
+export type * from "./options.js";
+export const localHyperframesProviderModuleRef = { name: "@hypit/provider-hyperframes-local", version: "1" } as const;
+export type CreateLocalHyperframesProviderOptions = HyperframesExecutionOptions & {
readonly instance?: string;
readonly pool?: string;
+ /** Used by managed browser installation, not frame capture. */
readonly nodePath?: string;
readonly hyperframesCliPath?: string;
- readonly ffprobePath?: string;
- /** Parallel Chrome workers inside one render. This is separate from Provider request concurrency. */
- readonly workers?: HyperframesWorkers;
- readonly quality?: HyperframesQuality;
- /**
- * Chrome's rasterizer. Defaults to `hardware`: a composited frame is drawn by the GPU rather
- * than by SwiftShader on the CPU, which is the difference between minutes and half an hour on a
- * full-length vertical render. Set `software` on a machine with no usable GPU.
- */
- readonly browserGpu?: HyperframesBrowserGpu;
- /** Number of whole documents allowed to render at once on this configured instance. */
+ /** Whole render requests admitted concurrently; independent of frame workers. */
readonly defaultConcurrency?: number;
- readonly processTimeoutMs?: number;
- readonly maxProcessOutputBytes?: number;
- readonly maxRenderedBytes?: number;
+ /** Shared Chrome slots across Need executions using this pool. */
+ readonly browserCapacity?: number;
};
-type ProcessResult = {
- readonly stdout: Uint8Array;
- readonly stderr: string;
-};
-
-type ProbeStream = {
- readonly codec_type?: unknown;
- readonly codec_name?: unknown;
- readonly width?: unknown;
- readonly height?: unknown;
- readonly avg_frame_rate?: unknown;
- readonly r_frame_rate?: unknown;
- readonly nb_read_frames?: unknown;
- readonly nb_frames?: unknown;
-};
-
-function assert(condition: unknown, message: string): asserts condition {
- if (!condition) throw new Error(message);
-}
-
-function positiveInteger(value: number, subject: string): number {
- assert(Number.isSafeInteger(value) && value > 0, `${subject} must be a positive integer`);
- return value;
-}
-
export function defaultHyperframesCliPath(): string {
return resolveNodePackageExecutable("hyperframes", "hyperframes", { from: import.meta.url });
}
-function processEnvironment(): NodeJS.ProcessEnv {
- const names = ["PATH", "HOME", "TMPDIR", "LANG", "LC_ALL"] as const;
- return Object.fromEntries(names.flatMap((name) => process.env[name] === undefined
- ? []
- : [[name, process.env[name]]])) as NodeJS.ProcessEnv;
-}
-
-async function runProcess(args: {
- readonly executable: string;
- readonly argv: readonly string[];
- readonly timeoutMs: number;
- readonly maxOutputBytes: number;
-}): Promise<ProcessResult> {
- return await new Promise((resolve, reject) => {
- const child = spawn(args.executable, [...args.argv], {
- shell: false,
- windowsHide: true,
- stdio: ["ignore", "pipe", "pipe"],
- env: processEnvironment(),
- });
- const stdout: Buffer[] = [];
- let outputBytes = 0;
- let stderr = "";
- let settled = false;
- const finish = (error?: Error): void => {
- if (settled) return;
- settled = true;
- clearTimeout(timer);
- if (error === undefined) resolve({ stdout: Buffer.concat(stdout), stderr });
- else reject(error);
- };
- const timer = setTimeout(() => {
- child.kill("SIGKILL");
- finish(new Error(`${args.executable} timed out`));
- }, args.timeoutMs);
- child.stdout.on("data", (chunk: Buffer) => {
- outputBytes += chunk.byteLength;
- if (outputBytes > args.maxOutputBytes) {
- child.kill("SIGKILL");
- finish(new Error(`${args.executable} output exceeded the configured limit`));
- return;
- }
- stdout.push(chunk);
- });
- child.stderr.on("data", (chunk: Buffer) => {
- outputBytes += chunk.byteLength;
- stderr = `${stderr}${chunk.toString()}`.slice(-32_000);
- if (outputBytes > args.maxOutputBytes) {
- child.kill("SIGKILL");
- finish(new Error(`${args.executable} output exceeded the configured limit`));
- }
- });
- child.on("error", (error) => finish(error));
- child.on("close", (code) => {
- if (code === 0) finish();
- else finish(new Error(`${args.executable} exited ${String(code)}: ${stderr}`));
- });
- });
-}
-
-async function artifactBytes(
- context: EndpointInvocationContext,
- artifact: BlobRef,
-): Promise<Uint8Array | AsyncIterable<Uint8Array>> {
- if (isStreamingResourceStore(context.resources)) {
- const chunks = await context.resources.open(artifact.resource);
- assert(chunks !== undefined, `HyperFrames Artifact ${artifact.resource} is unavailable`);
- return chunks;
- }
- const bytes = await context.resources.get(artifact.resource);
- assert(bytes !== undefined, `HyperFrames Artifact ${artifact.resource} is unavailable`);
- assert(bytes.byteLength === artifact.size, `HyperFrames Artifact ${artifact.resource} size differs`);
- return bytes;
-}
-
-function parseRational(value: unknown, subject: string): { readonly numerator: bigint; readonly denominator: bigint } {
- assert(typeof value === "string" && /^\d+\/\d+$/u.test(value), `${subject} is not a rational`);
- const [numerator, denominator] = value.split("/");
- assert(numerator !== undefined && denominator !== undefined && BigInt(denominator) > 0n,
- `${subject} is invalid`);
- return { numerator: BigInt(numerator), denominator: BigInt(denominator) };
-}
-
-function equalsRational(
- actual: { readonly numerator: bigint; readonly denominator: bigint },
- expected: { readonly numerator: number; readonly denominator: number },
-): boolean {
- return actual.numerator * BigInt(expected.denominator)
- === BigInt(expected.numerator) * actual.denominator;
-}
-
-function outputFrameCount(stream: ProbeStream): number {
- const value = stream.nb_read_frames ?? stream.nb_frames;
- assert(typeof value === "string" && /^\d+$/u.test(value), "Rendered visual has no decoded frame count");
- const count = Number(value);
- assert(Number.isSafeInteger(count), "Rendered visual frame count exceeds safe arithmetic");
- return count;
-}
-
-async function verifyOutput(args: {
- readonly path: string;
- readonly document: HyperframesDocument;
- readonly ffprobePath: string;
- readonly timeoutMs: number;
- readonly maxOutputBytes: number;
-}): Promise<void> {
- const probe = await runProcess({
- executable: args.ffprobePath,
- argv: ["-v", "error", "-print_format", "json", "-show_streams", "-count_frames", args.path],
- timeoutMs: args.timeoutMs,
- maxOutputBytes: args.maxOutputBytes,
- });
- let value: unknown;
- try {
- value = JSON.parse(Buffer.from(probe.stdout).toString("utf8"));
- } catch {
- throw new Error("ffprobe returned invalid JSON for the HyperFrames output");
- }
- assert(value !== null && typeof value === "object" && !Array.isArray(value),
- "ffprobe returned an invalid HyperFrames inspection");
- const streams = (value as { readonly streams?: unknown }).streams;
- assert(Array.isArray(streams) && streams.length === 1, "Rendered visual must contain exactly one stream");
- const stream = streams[0] as ProbeStream;
- assert(stream.codec_type === "video" && stream.codec_name === "h264",
- "Rendered visual must contain one H.264 video stream and no audio");
- assert(stream.width === args.document.canvas.width && stream.height === args.document.canvas.height,
- "Rendered visual canvas differs from its document");
- const rate = parseRational(stream.avg_frame_rate ?? stream.r_frame_rate, "Rendered visual frame rate");
- assert(equalsRational(rate, args.document.frameRate), "Rendered visual frame rate differs from its document");
- assert(outputFrameCount(stream) === args.document.frameCount,
- "Rendered visual frame count differs from its document");
-}
-
-function visualRequest(value: CanonicalValue): HyperframesDocument {
- assert(value !== null && typeof value === "object" && !Array.isArray(value),
- "HyperFrames visual request must be an object");
- const item = value as { readonly document?: unknown };
- assertHyperframesDocument(item.document as HyperframesDocument);
- return item.document as HyperframesDocument;
-}
-
-function result(value: CanonicalValue): EndpointFulfillment {
- return { value: { kind: "inline", value } };
-}
-
export function createLocalHyperframesProvider(config: CreateLocalHyperframesProviderOptions) {
- const nodePath = config.nodePath ?? process.execPath;
- const hyperframesCliPath = config.hyperframesCliPath ?? defaultHyperframesCliPath();
- const ffprobePath = config.ffprobePath ?? "ffprobe";
- const workers = config.workers ?? "auto";
- assert(workers === "auto" || (Number.isSafeInteger(workers) && workers > 0 && workers <= 64),
- "workers must be auto or an integer in [1, 64]");
- const quality = config.quality ?? "standard";
- assert(["draft", "standard", "high"].includes(quality), "HyperFrames quality is invalid");
- const browserGpu = config.browserGpu ?? "hardware";
- assert(["auto", "software", "hardware"].includes(browserGpu), "HyperFrames browserGpu is invalid");
- const processTimeoutMs = positiveInteger(config.processTimeoutMs ?? 30 * 60_000, "processTimeoutMs");
- const maxProcessOutputBytes = positiveInteger(config.maxProcessOutputBytes ?? 4 * 1024 * 1024,
- "maxProcessOutputBytes");
- const maxRenderedBytes = positiveInteger(config.maxRenderedBytes ?? 16 * 1024 * 1024 * 1024,
- "maxRenderedBytes");
- const configuration = canonicalize({
- nodePath,
- hyperframesCliPath,
- hyperframesVersion: HYPERFRAMES_VERSION,
- ffprobePath,
- workers,
- quality,
- browserGpu,
- processTimeoutMs,
- maxProcessOutputBytes,
- maxRenderedBytes,
- });
+ const execution = resolveExecutionOptions(config);
+ const pool = config.pool ?? config.instance ?? "hyperframes.local";
+ const browsers = `capacity:${pool}/browsers`;
+ if (config.browserCapacity !== undefined && (!Number.isSafeInteger(config.browserCapacity) || config.browserCapacity < 1)) {
+ throw new Error("HyperFrames browserCapacity must be a positive integer");
+ }
return defineEndpointPackage({
module: localHyperframesProviderModuleRef,
facet: "render",
instance: config.instance ?? "hyperframes.local",
- pool: config.pool ?? config.instance ?? "hyperframes.local",
+ pool,
pricing: { kind: "local" },
defaultConcurrency: config.defaultConcurrency ?? 1,
capabilities: [{
lifecycle: "immediate" as const,
capability: renderHyperframesCapabilities.renderVisual,
returns: mediaTypes.renderedVisual,
+ ...(config.browserCapacity === undefined ? {} : {
+ resources: [{ id: browsers, limit: config.browserCapacity }],
+ unitsForRequest: (request: import("@hypit/endpoint-kit").EndpointRequest) => {
+ verifyHyperframesVisualRequest(request.constraints);
+ const { document, range } = request.constraints;
+ return { [browsers]: Math.min(execution.workers,
+ range === undefined ? document.frameCount : range.endFrameExclusive - range.startFrame) };
+ },
+ }),
handler: async (context) => {
- const document = visualRequest(context.need.constraints);
- const work = await mkdtemp(join(tmpdir(), "hypit-hyperframes-local-"));
- try {
- await stageHyperframesProject({
- document,
- directory: work,
- read: (artifact) => artifactBytes(context, artifact),
- validateSurface: async (surface, bytes) => {
- await verifyCompositableSurfaceBytes({
- surface,
- bytes,
- ffprobePath,
- processTimeoutMs,
- maxProbeOutputBytes: maxProcessOutputBytes,
- });
- },
- });
- const output = join(work, "visual.mp4");
- const fps = document.frameRate.denominator === 1
- ? String(document.frameRate.numerator)
- : `${document.frameRate.numerator}/${document.frameRate.denominator}`;
- const browserGpuArg = browserGpu === "software"
- ? ["--no-browser-gpu"]
- : browserGpu === "hardware" ? ["--browser-gpu"] : [];
- await runProcess({
- executable: nodePath,
- argv: [
- hyperframesCliPath,
- "render",
- work,
- "--composition", "index.html",
- "--output", output,
- "--format", "mp4",
- "--fps", fps,
- "--workers", String(workers),
- "--quality", quality,
- ...browserGpuArg,
- "--no-best-effort",
- "--quiet",
- ],
- timeoutMs: processTimeoutMs,
- maxOutputBytes: maxProcessOutputBytes,
- });
- const outputStat = await stat(output);
- assert(outputStat.isFile() && outputStat.size > 0, "HyperFrames emitted no visual output");
- assert(outputStat.size <= maxRenderedBytes, "HyperFrames output exceeded the configured size limit");
- await verifyOutput({
- path: output,
- document,
- ffprobePath,
- timeoutMs: processTimeoutMs,
- maxOutputBytes: maxProcessOutputBytes,
- });
- const artifact = isStreamingResourceStore(context.resources)
- ? await context.resources.putStream(createReadStream(output), "video/mp4")
- : await context.resources.put(await readFile(output), "video/mp4");
- const value: RenderedVisual = sealRenderedVisual({
- frameRate: document.frameRate,
- frameCount: document.frameCount,
- canvas: document.canvas,
- artifact,
- });
- return result(canonicalize(value));
- } finally {
- await rm(work, { recursive: true, force: true }).catch(() => {});
- }
+ const request = context.need.constraints;
+ verifyHyperframesVisualRequest(request);
+ const visual = await renderHyperframesVisual(request, { ...config, workers: execution.workers, resources: context.resources });
+ return { value: { kind: "inline", value: canonicalize(visual) } };
},
}],
});
diff --git a/packages/provider-hyperframes-local/src/render.ts b/packages/provider-hyperframes-local/src/render.ts
new file mode 100644
index 00000000..bac225ef
--- /dev/null
+++ b/packages/provider-hyperframes-local/src/render.ts
@@ -0,0 +1,226 @@
+import { createReadStream } from "node:fs";
+import { mkdir, mkdtemp, readFile, rm, stat, writeFile } from "node:fs/promises";
+import { availableParallelism, tmpdir } from "node:os";
+import { join, relative, resolve, sep } from "node:path";
+import type { EndpointInvocationContext } from "@hypit/endpoint-kit";
+import { stageHyperframesProject } from "@hypit/hyperframes/project";
+import { sealRenderedVisual } from "@hypit/media";
+import type { MediaFrameRange, RenderedVisual } from "@hypit/media";
+import { verifyCompositableSurfaceBytes } from "@hypit/media-execution";
+import { verifyHyperframesVisualRequest } from "@hypit/render-hyperframes";
+import type { HyperframesVisualRequest } from "@hypit/render-hyperframes";
+import { isStreamingResourceStore } from "@hypit/runtime";
+import type { HyperframesExecutionOptions } from "./options.js";
+import { assert, positiveInteger, runProcess } from "./process.js";
+import { verifyOutput } from "./output.js";
+import { distributeFrameRange, sourceFrameAt, sourceWindows, videoSlots } from "./sampling.js";
+
+export type HyperframesRenderProgress =
+ | { readonly phase: "prepared"; readonly workers: number; readonly sourceFrames: number; readonly elapsedMs: number }
+ | { readonly phase: "worker-initializing" | "worker-start" | "worker-complete"; readonly worker: number; readonly range: MediaFrameRange;
+ readonly browserPid: number | undefined; readonly elapsedMs: number }
+ | { readonly phase: "complete"; readonly frames: number; readonly elapsedMs: number };
+
+export type RenderHyperframesVisualOptions = HyperframesExecutionOptions & {
+ readonly resources: EndpointInvocationContext["resources"];
+ readonly signal?: AbortSignal;
+ readonly onProgress?: (event: HyperframesRenderProgress) => void;
+};
+
+export function resolveExecutionOptions(options: HyperframesExecutionOptions) {
+ const workers = options.workers ?? "auto";
+ assert(workers === "auto" || (Number.isSafeInteger(workers) && workers > 0),
+ "workers must be auto or a positive safe integer");
+ const quality = options.quality ?? "standard";
+ assert(["draft", "standard", "high"].includes(quality), "HyperFrames quality is invalid");
+ const browserGpu = options.browserGpu ?? "hardware";
+ assert(["auto", "software", "hardware"].includes(browserGpu), "HyperFrames browserGpu is invalid");
+ return {
+ workers: workers === "auto" ? Math.min(4, Math.max(1, Math.floor(availableParallelism() / 2))) : workers,
+ quality, browserGpu,
+ ffmpegPath: options.ffmpegPath ?? "ffmpeg",
+ ffprobePath: options.ffprobePath ?? "ffprobe",
+ initializationTimeoutMs: positiveInteger(options.initializationTimeoutMs ?? 30_000, "initializationTimeoutMs"),
+ frameTimeoutMs: positiveInteger(options.frameTimeoutMs ?? 15_000, "frameTimeoutMs"),
+ processTimeoutMs: positiveInteger(options.processTimeoutMs ?? 30 * 60_000, "processTimeoutMs"),
+ maxProcessOutputBytes: positiveInteger(options.maxProcessOutputBytes ?? 4 * 1024 * 1024, "maxProcessOutputBytes"),
+ maxRenderedBytes: positiveInteger(options.maxRenderedBytes ?? 16 * 1024 * 1024 * 1024, "maxRenderedBytes"),
+ };
+}
+
+/** Execute full or selected frames of one compiled document, keeping the original page clock. */
+export async function renderHyperframesVisual(
+ request: HyperframesVisualRequest,
+ options: RenderHyperframesVisualOptions,
+): Promise<RenderedVisual> {
+ verifyHyperframesVisualRequest(request);
+ const config = resolveExecutionOptions(options);
+ const { document } = request;
+ const range = request.range ?? { startFrame: 0, endFrameExclusive: document.frameCount };
+ const frameCount = range.endFrameExclusive - range.startFrame;
+ const tasks = distributeFrameRange(range, config.workers);
+ const fps = { num: document.frameRate.numerator, den: document.frameRate.denominator };
+ const started = performance.now();
+ const elapsedMs = () => Math.round(performance.now() - started);
+ const engine = await import("@hyperframes/engine");
+ const { createFileServer } = await import("@hyperframes/producer");
+ const controller = new AbortController();
+ const signal = options.signal === undefined ? controller.signal : AbortSignal.any([controller.signal, options.signal]);
+ const work = await mkdtemp(join(tmpdir(), "hypit-hyperframes-local-"));
+ const timer = setTimeout(() => controller.abort(new Error("HyperFrames render timed out")), config.processTimeoutMs);
+ type Session = Awaited<ReturnType<typeof engine.createCaptureSession>>;
+ const sessions = new Set<Session>();
+ const closing = new Map<Session, Promise<void>>();
+ const close = (session: Session): Promise<void> => {
+ let promise = closing.get(session);
+ if (promise === undefined) {
+ promise = engine.closeCaptureSession(session).finally(() => { sessions.delete(session); });
+ closing.set(session, promise);
+ }
+ return promise;
+ };
+ const stage = async <T>(subject: string, timeoutMs: number, run: () => Promise<T>): Promise<T> => {
+ signal.throwIfAborted();
+ const timeout = setTimeout(() => controller.abort(new Error(`HyperFrames ${subject} timed out after ${timeoutMs} ms`)), timeoutMs);
+ let onAbort: () => void = () => {};
+ const stopped = new Promise<never>((_, reject) => {
+ onAbort = () => reject(signal.reason);
+ signal.addEventListener("abort", onAbort, { once: true });
+ });
+ try { return await Promise.race([run(), stopped]); }
+ finally { clearTimeout(timeout); signal.removeEventListener("abort", onAbort); }
+ };
+ let server: Awaited<ReturnType<typeof createFileServer>> | undefined;
+ // Closing pages interrupts an in-flight capture as well as the next loop iteration.
+ const abort = () => { for (const session of sessions) void close(session).catch(() => {}); };
+ signal.addEventListener("abort", abort, { once: true });
+ try {
+ signal.throwIfAborted();
+ await stageHyperframesProject({
+ document, directory: work,
+ read: async (artifact) => {
+ const bytes = isStreamingResourceStore(options.resources)
+ ? await options.resources.open(artifact.resource) : await options.resources.get(artifact.resource);
+ assert(bytes !== undefined, `HyperFrames Artifact ${artifact.resource} is unavailable`);
+ return bytes;
+ },
+ validateSurface: (surface, bytes) => verifyCompositableSurfaceBytes({ surface, bytes,
+ ffprobePath: config.ffprobePath, processTimeoutMs: config.processTimeoutMs,
+ maxProbeOutputBytes: config.maxProcessOutputBytes }),
+ });
+ const slots = videoSlots(await readFile(join(work, "index.html"), "utf8"));
+ const sources = new Map<string, { frames: Map<number, string>; width: number; height: number }>();
+ let sourceFrames = 0;
+ // One source at a time bounds decoder pressure independently of browser concurrency.
+ for (const source of sourceWindows(slots, range)) {
+ const path = resolve(work, source.src);
+ assert(path.startsWith(`${work}${sep}`), "HyperFrames source is outside the staged project");
+ const frames = new Map<number, string>();
+ let width = 0, height = 0;
+ for (const window of source.windows) {
+ signal.throwIfAborted();
+ const count = window.endFrameExclusive - window.startFrame;
+ const extracted = await engine.extractVideoFramesRange(path, `source-${sources.size}-${window.startFrame}`,
+ window.startFrame * source.fps.den / source.fps.num, count * source.fps.den / source.fps.num,
+ { fps: source.fps, outputDir: join(work, "decoded"), format: "png", ...(count === 1 ? { finalFrameOnly: true } : {}) },
+ signal, { ffmpegProcessTimeout: config.processTimeoutMs });
+ assert(extracted.totalFrames === count, `HyperFrames expected ${count} source frames, decoded ${extracted.totalFrames}`);
+ for (let index = 0; index < count; index++) {
+ const framePath = extracted.framePaths.get(index);
+ assert(framePath !== undefined, "HyperFrames extraction omitted a requested source frame");
+ frames.set(window.startFrame + index, framePath);
+ }
+ width = extracted.metadata.width;
+ height = extracted.metadata.height;
+ sourceFrames += count;
+ }
+ sources.set(source.src, { frames, width, height });
+ }
+ class SelectedFrameLookup extends engine.FrameLookupTable {
+ override getActiveFramePayloads(time: number) {
+ const frame = Math.round(time * fps.num / fps.den);
+ const payloads = new Map<string, { framePath: string; frameIndex: number }>();
+ for (const slot of slots) {
+ if (frame < slot.startFrame || frame >= slot.endFrameExclusive) continue;
+ const frameIndex = sourceFrameAt(slot, frame);
+ const framePath = sources.get(slot.src)?.frames.get(frameIndex);
+ // Browser initialization may seek outside the requested interval.
+ if (frame < range.startFrame || frame >= range.endFrameExclusive) continue;
+ assert(framePath !== undefined, `HyperFrames has no decoded frame ${frameIndex} for ${slot.id}`);
+ payloads.set(slot.id, { framePath, frameIndex });
+ }
+ return payloads;
+ }
+ }
+ server = await createFileServer({ projectDir: work, port: 0, fps });
+ const serverUrl = server.url;
+ const outputFrames = join(work, "frames");
+ await mkdir(outputFrames);
+ options.onProgress?.({ phase: "prepared", workers: tasks.length, sourceFrames, elapsedMs: elapsedMs() });
+ const results = await Promise.allSettled(tasks.map(async (task, worker) => {
+ let session: Session | undefined;
+ try {
+ signal.throwIfAborted();
+ const directory = join(work, `worker-${worker}`);
+ await mkdir(directory);
+ const injector = engine.createVideoFrameInjector(slots.length === 0 ? null : new SelectedFrameLookup(), {
+ frameSrcResolver: (path) => new URL(relative(work, path).split(sep).map(encodeURIComponent).join("/"), `${serverUrl}/`).href,
+ });
+ session = await engine.createCaptureSession(serverUrl, directory, {
+ ...document.canvas, fps, format: "png",
+ compositionDurationSeconds: document.frameCount * fps.den / fps.num,
+ skipReadinessVideoIds: slots.map((slot) => slot.id),
+ videoMetadataHints: slots.flatMap((slot) => {
+ const source = sources.get(slot.src);
+ return source === undefined ? [] : [{ id: slot.id, width: source.width, height: source.height }];
+ }),
+ }, injector, { browserGpuMode: config.browserGpu, enableBrowserPool: false, forceScreenshot: true, useDrawElement: false });
+ sessions.add(session);
+ signal.throwIfAborted();
+ const activeSession = session;
+ const browserPid = session.browser.process()?.pid;
+ options.onProgress?.({ phase: "worker-initializing", worker, range: task, browserPid, elapsedMs: elapsedMs() });
+ await stage(`worker ${worker} initialization`, config.initializationTimeoutMs, () => engine.initializeSession(activeSession));
+ options.onProgress?.({ phase: "worker-start", worker, range: task, browserPid, elapsedMs: elapsedMs() });
+ for (let frame = task.startFrame; frame < task.endFrameExclusive; frame++) {
+ signal.throwIfAborted();
+ const captured = await stage(`worker ${worker} frame ${frame}`, config.frameTimeoutMs,
+ () => engine.captureFrameToBuffer(activeSession, frame, frame * fps.den / fps.num));
+ await writeFile(join(outputFrames, `${String(frame - range.startFrame).padStart(9, "0")}.png`), captured.buffer);
+ }
+ options.onProgress?.({ phase: "worker-complete", worker, range: task, browserPid, elapsedMs: elapsedMs() });
+ } catch (error) {
+ controller.abort(error);
+ throw error;
+ } finally {
+ if (session !== undefined) await close(session);
+ }
+ }));
+ signal.throwIfAborted();
+ for (const result of results) if (result.status === "rejected") throw result.reason;
+ await Promise.all(closing.values());
+ const output = join(work, "visual.mp4");
+ const crf = { draft: 28, standard: 23, high: 18 }[config.quality];
+ await runProcess({ executable: config.ffmpegPath,
+ argv: ["-v", "error", "-y", "-framerate", `${fps.num}/${fps.den}`, "-i", join(outputFrames, "%09d.png"),
+ "-frames:v", String(frameCount), "-an", "-c:v", "libx264", "-crf", String(crf),
+ "-preset", config.quality === "draft" ? "veryfast" : "medium", "-pix_fmt", "yuv420p", "-movflags", "+faststart", output],
+ timeoutMs: config.processTimeoutMs, maxOutputBytes: config.maxProcessOutputBytes, signal });
+ const outputStat = await stat(output);
+ assert(outputStat.size > 0 && outputStat.size <= config.maxRenderedBytes, "HyperFrames output is empty or exceeds its byte limit");
+ await verifyOutput({ path: output, document: { ...document, frameCount }, ffprobePath: config.ffprobePath,
+ timeoutMs: config.processTimeoutMs, maxOutputBytes: config.maxProcessOutputBytes, signal });
+ signal.throwIfAborted();
+ const artifact = isStreamingResourceStore(options.resources)
+ ? await options.resources.putStream(createReadStream(output), "video/mp4")
+ : await options.resources.put(await readFile(output), "video/mp4");
+ options.onProgress?.({ phase: "complete", frames: frameCount, elapsedMs: elapsedMs() });
+ return sealRenderedVisual({ frameRate: document.frameRate, frameCount, canvas: document.canvas, artifact });
+ } finally {
+ clearTimeout(timer);
+ signal.removeEventListener("abort", abort);
+ await Promise.allSettled([...sessions].map(close));
+ server?.close();
+ await rm(work, { recursive: true, force: true });
+ }
+}
diff --git a/packages/provider-hyperframes-local/src/sampling.ts b/packages/provider-hyperframes-local/src/sampling.ts
new file mode 100644
index 00000000..e09286a2
--- /dev/null
+++ b/packages/provider-hyperframes-local/src/sampling.ts
@@ -0,0 +1,89 @@
+import type { MediaFrameRange } from "@hypit/media";
+import { assert } from "./process.js";
+
+type Rational = { readonly numerator: bigint; readonly denominator: bigint };
+export type VideoSlot = MediaFrameRange & {
+ readonly id: string;
+ readonly src: string;
+ readonly sourceFrame: Rational;
+ readonly sourceRate: Rational;
+ readonly sourceFps: { readonly num: number; readonly den: number };
+};
+
+function rational(value: string, label: string): Rational {
+ assert(/^\d+\/[1-9]\d*$/u.test(value), `HyperFrames ${label} must be a non-negative rational`);
+ const [a, b] = value.split("/");
+ return { numerator: BigInt(a!), denominator: BigInt(b!) };
+}
+
+/** Read the compiler's exact frame markers, without reconstructing author intent from seconds. */
+export function videoSlots(html: string): VideoSlot[] {
+ return [...html.matchAll(/<video\b[^>]*>/gu)].map(([tag]) => {
+ const attribute = (name: string): string => {
+ const value = new RegExp(`(?:\\s)${name}="([^"]*)"`, "u").exec(tag)?.[1];
+ assert(value !== undefined, `HyperFrames video lacks ${name}; compile its frame sampling before rendering`);
+ return value.replaceAll("&amp;", "&").replaceAll("&quot;", '"').replaceAll("&lt;", "<").replaceAll("&gt;", ">");
+ };
+ const sourceFps = rational(attribute("data-hypit-source-fps"), "source frame rate");
+ const slot = {
+ id: attribute("id"), src: attribute("src"),
+ startFrame: Number(attribute("data-hypit-start-frame")),
+ endFrameExclusive: Number(attribute("data-hypit-end-frame")),
+ sourceFrame: rational(attribute("data-hypit-source-frame"), "source frame"),
+ sourceRate: rational(attribute("data-hypit-source-rate"), "source rate"),
+ sourceFps: { num: Number(sourceFps.numerator), den: Number(sourceFps.denominator) },
+ };
+ assert(Number.isSafeInteger(slot.startFrame) && slot.startFrame >= 0
+ && Number.isSafeInteger(slot.endFrameExclusive) && slot.endFrameExclusive > slot.startFrame
+ && Number.isSafeInteger(slot.sourceFps.num) && slot.sourceFps.num > 0
+ && Number.isSafeInteger(slot.sourceFps.den), "HyperFrames video frame mapping is invalid");
+ return slot;
+ });
+}
+
+/** A decoded frame owns [n, n+1) in source-frame coordinates. */
+export function sourceFrameAt(slot: VideoSlot, frame: number): number {
+ const a = slot.sourceFrame;
+ const r = slot.sourceRate;
+ const value = Number((a.numerator * r.denominator
+ + BigInt(frame - slot.startFrame) * r.numerator * a.denominator) / (a.denominator * r.denominator));
+ assert(Number.isSafeInteger(value) && value >= 0, "HyperFrames source frame exceeds safe arithmetic");
+ return value;
+}
+
+export function sourceWindows(slots: readonly VideoSlot[], range: MediaFrameRange) {
+ const sources = new Map<string, { fps: VideoSlot["sourceFps"]; windows: MediaFrameRange[] }>();
+ for (const slot of slots) {
+ const first = Math.max(range.startFrame, slot.startFrame);
+ const last = Math.min(range.endFrameExclusive, slot.endFrameExclusive) - 1;
+ if (last < first) continue;
+ let source = sources.get(slot.src);
+ if (source === undefined) {
+ source = { fps: slot.sourceFps, windows: [] };
+ sources.set(slot.src, source);
+ }
+ assert(source.fps.num * slot.sourceFps.den === slot.sourceFps.num * source.fps.den,
+ "One HyperFrames source has conflicting frame rates");
+ source.windows.push({ startFrame: sourceFrameAt(slot, first), endFrameExclusive: sourceFrameAt(slot, last) + 1 });
+ }
+ return [...sources].map(([src, source]) => {
+ const windows: MediaFrameRange[] = [];
+ for (const window of source.windows.sort((a, b) => a.startFrame - b.startFrame)) {
+ const previous = windows.at(-1);
+ if (previous !== undefined && window.startFrame <= previous.endFrameExclusive) {
+ windows[windows.length - 1] = { startFrame: previous.startFrame,
+ endFrameExclusive: Math.max(previous.endFrameExclusive, window.endFrameExclusive) };
+ } else windows.push(window);
+ }
+ return { src, fps: source.fps, windows };
+ });
+}
+
+export function distributeFrameRange(range: MediaFrameRange, workers: number): MediaFrameRange[] {
+ const count = range.endFrameExclusive - range.startFrame;
+ const active = Math.min(count, workers);
+ return Array.from({ length: active }, (_, index) => ({
+ startFrame: range.startFrame + Math.floor(index * count / active),
+ endFrameExclusive: range.startFrame + Math.floor((index + 1) * count / active),
+ }));
+}
diff --git a/packages/provider-hyperframes-local/test/range.test.ts b/packages/provider-hyperframes-local/test/range.test.ts
new file mode 100644
index 00000000..faabd9aa
--- /dev/null
+++ b/packages/provider-hyperframes-local/test/range.test.ts
@@ -0,0 +1,136 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { sealComposition, sealVisualTrack } from "@hypit/composition";
+import { mediaFrameRangeSamples } from "@hypit/media";
+import { EndpointRegistry, MemoryResourceStore } from "@hypit/driver-node";
+import { compileHyperframesDocument } from "@hypit/hyperframes";
+import { sealProgramSpace } from "@hypit/program-space";
+import type { BlobRef } from "@hypit/protocol";
+import { renderHyperframesVisual } from "../src/index.js";
+import { hypitPackage } from "../src/activation.js";
+import type { RuntimeEndpointAdapterImplementation } from "@hypit/runtime-kit";
+import { endpointResourceClaims } from "@hypit/endpoint-kit";
+import { renderHyperframesCapabilities } from "@hypit/render-hyperframes";
+import { mediaTypes } from "@hypit/media";
+import { canonicalize } from "@hypit/protocol";
+import type { HyperframesRenderProgress } from "../src/index.js";
+import { distributeFrameRange, sourceFrameAt, sourceWindows, videoSlots } from "../src/sampling.js";
+
+function documentFor(artifact: BlobRef) {
+ const space = sealProgramSpace({ id: "range-space", narrativeId: "range-narrative",
+ durationSec: 12 / 30, frameRate: { numerator: 30, denominator: 1 } });
+ const track = sealVisualTrack({ id: "video", visualIr: "hypit.visual-ir@1", programSpaceId: space.id,
+ presents: [{ id: "sample", span: { startFrame: 0, endFrameExclusive: 12 },
+ stacking: { order: 0, tieBreak: "sample" }, elements: [{ id: "video", order: 0, kind: "video", artifact,
+ style: [{ name: "position", value: "absolute" }, { name: "inset", value: 0 },
+ { name: "width", value: "64px" }, { name: "height", value: "64px" }],
+ sampling: { sourceFrameRate: space.frameRate, sourceFrameCount: 4, segments: [
+ { target: { startFrame: 0, endFrameExclusive: 6 }, sourceFrame: { numerator: 2, denominator: 1 },
+ rate: { numerator: 1, denominator: 1 }, loop: { startFrame: 0, endFrameExclusive: 4 } },
+ { target: { startFrame: 6, endFrameExclusive: 8 }, sourceFrame: { numerator: 3, denominator: 1 },
+ rate: { numerator: 0, denominator: 1 } },
+ { target: { startFrame: 8, endFrameExclusive: 12 }, sourceFrame: { numerator: 0, denominator: 1 },
+ rate: { numerator: 1, denominator: 2 } },
+ ] },
+ }] }],
+ });
+ return compileHyperframesDocument(sealComposition({ id: "range-video",
+ canvas: { width: 64, height: 64, clearColor: "#000000" }, tracks: [track] }), space);
+}
+
+test("source selection retains loop, hold and fractional-speed sampling and shares decoded frames", () => {
+ const document = documentFor({ kind: "blob", resource: "res_range_source", size: 1, mediaType: "video/mp4" });
+ const slots = videoSlots(document.html);
+ const range = { startFrame: 3, endFrameExclusive: 11 };
+ const sampled = Array.from({ length: 8 }, (_, i) => {
+ const frame = range.startFrame + i;
+ return sourceFrameAt(slots.find((s) => frame >= s.startFrame && frame < s.endFrameExclusive)!, frame);
+ });
+ assert.deepEqual(sampled, [1, 2, 3, 3, 3, 0, 0, 1]);
+ assert.deepEqual(sourceWindows(slots, range)[0]?.windows, [{ startFrame: 0, endFrameExclusive: 4 }]);
+ assert.deepEqual(distributeFrameRange(range, 3), [
+ { startFrame: 3, endFrameExclusive: 5 }, { startFrame: 5, endFrameExclusive: 8 },
+ { startFrame: 8, endFrameExclusive: 11 },
+ ]);
+});
+
+test("real selected renders sample video correctly across loop, hold and stretch with independent browsers", {
+ skip: process.env.HYPIT_BROWSER_TESTS !== "1",
+}, async () => {
+ const root = await mkdtemp(join(tmpdir(), "hypit-render-range-test-"));
+ try {
+ const colors = [[240, 20, 20], [20, 220, 20], [20, 20, 240], [220, 220, 20]];
+ const raw = Buffer.concat(colors.map((color) => Buffer.from(Array.from({ length: 64 * 64 }, () => color).flat())));
+ const path = join(root, "source.mp4");
+ const encoded = spawnSync("ffmpeg", ["-v", "error", "-y", "-f", "rawvideo", "-pix_fmt", "rgb24",
+ "-s", "64x64", "-r", "30", "-i", "pipe:0", "-c:v", "libx264", "-crf", "0", "-pix_fmt", "yuv420p", path], { input: raw });
+ assert.equal(encoded.status, 0, encoded.stderr.toString());
+ const resources = new MemoryResourceStore();
+ const document = documentFor(await resources.put(await readFile(path), "video/mp4"));
+ const events: HyperframesRenderProgress[] = [];
+ const render = async (name: string, range: { startFrame: number; endFrameExclusive: number } | undefined,
+ workers: number) => {
+ const visual = await renderHyperframesVisual({ document, ...(range === undefined ? {} : { range }) },
+ { resources, workers, quality: "high", processTimeoutMs: 120000, onProgress: (e) => events.push(e) });
+ const file = join(root, `${name}.mp4`);
+ await writeFile(file, (await resources.get(visual.artifact.resource))!);
+ const decoded = spawnSync("ffmpeg", ["-v", "error", "-i", file, "-f", "rawvideo", "-pix_fmt", "rgb24", "pipe:1"]);
+ assert.equal(decoded.status, 0, decoded.stderr.toString());
+ return decoded.stdout;
+ };
+ const full = await render("full", undefined, 1);
+ events.length = 0;
+ const selected = await render("selected", { startFrame: 3, endFrameExclusive: 11 }, 3);
+ const starts = events.filter((e): e is Extract<HyperframesRenderProgress, { worker: number }> => e.phase === "worker-start");
+ assert.equal(starts.length, 3);
+ assert.equal(new Set(starts.map((e) => e.browserPid)).size, 3);
+ const one = await render("one", { startFrame: 7, endFrameExclusive: 8 }, 4);
+ const stride = 64 * 64 * 3, center = (32 * 64 + 32) * 3;
+ assert.equal(full.length, 12 * stride);
+ assert.equal(selected.length, 8 * stride);
+ assert.equal(one.length, stride);
+ for (const [i, source] of [1, 2, 3, 3, 3, 0, 0, 1].entries()) {
+ for (let channel = 0; channel < 3; channel++) {
+ assert.ok(Math.abs(selected[i * stride + center + channel]! - colors[source]![channel]!) < 12);
+ assert.ok(Math.abs(selected[i * stride + center + channel]! - full[(i + 3) * stride + center + channel]!) < 4);
+ }
+ }
+ for (let channel = 0; channel < 3; channel++) assert.ok(Math.abs(one[center + channel]! - colors[3]![channel]!) < 12);
+ await assert.rejects(renderHyperframesVisual({ document, range: { startFrame: 7, endFrameExclusive: 8 } },
+ { resources, workers: 2, initializationTimeoutMs: 1, processTimeoutMs: 30_000 }), /worker 0 initialization timed out/);
+ assert.equal((await render("after-timeout", { startFrame: 7, endFrameExclusive: 8 }, 1)).length, stride);
+ } finally { await rm(root, { recursive: true, force: true }); }
+});
+
+
+test("fractional frame rates keep selected audio duration on the output frame clock", () => {
+ assert.deepEqual(mediaFrameRangeSamples({ startFrame: 1, endFrameExclusive: 2 },
+ { numerator: 30000, denominator: 1001 }), { startSample: 1602, endSampleExclusive: 3204, sampleFrames: 1602 });
+});
+
+
+test("Hyperframes claims actual browser count including a range shorter than workers", async () => {
+ const document = documentFor({ kind: "blob", resource: "res_range_source", size: 1, mediaType: "video/mp4" });
+ const request = { id: "visual", capability: renderHyperframesCapabilities.renderVisual,
+ returns: mediaTypes.renderedVisual, constraints: canonicalize({ document }), result: "visual-result" };
+ const adapter = hypitPackage.hostFacets[0]!.implementation as RuntimeEndpointAdapterImplementation;
+ for (const [workers, browserCapacity, expectedUnits] of [[4, 6, 4], [128, 128, 12]] as const) {
+ const registry = new EndpointRegistry();
+ const activation = await adapter.activate({
+ hostStateRoot: tmpdir(), dataRoot: tmpdir(), instance: "render", pool: "machine",
+ config: canonicalize({ workers, defaultConcurrency: 2, browserCapacity }),
+ });
+ await activation.endpoint.install(registry);
+ const selected = registry.resolve(request);
+ assert.equal(selected.status, "resolved");
+ const claims = endpointResourceClaims(selected.registration.scheduling!, request);
+ assert.deepEqual(claims.at(-1), { id: "capacity:machine/browsers", limit: browserCapacity, units: expectedUnits });
+ const single = { ...request, constraints: canonicalize({ document, range: { startFrame: 7, endFrameExclusive: 8 } }) };
+ assert.deepEqual(endpointResourceClaims(selected.registration.scheduling!, single).at(-1),
+ { id: "capacity:machine/browsers", limit: browserCapacity, units: 1 });
+ }
+});
diff --git a/packages/provider-kie/README.md b/packages/provider-kie/README.md
index 6cbfb5f5..1d91172d 100644
--- a/packages/provider-kie/README.md
+++ b/packages/provider-kie/README.md
@@ -84,9 +84,14 @@ optional `capabilityConcurrency` entry narrows the capacity of one exact KIE mod
default the Endpoint instance is the shared-resource identity. Set Profile `pool` only when multiple
Endpoint instances really use the same account or deployment quota. Another Provider is independent
unless the Profile explicitly gives it that same real-resource identity.
-One task acquires its total and model-specific capacity claims atomically. These are shared-resource
+One Need execution acquires its total and model-specific capacity claims atomically. These are shared-resource
limits, not parent and child queues.
+`submissionIntervalMs` spaces submissions within one Provider instance. It is a frequency limit,
+not a concurrency slot, and is not shared across separate instances by the `pool` setting.
+Polling errors retain the task and its capacity. A local operation deadline records failure and
+continues observing termination; unsupported cancellation cannot release a still-running task.
+
An advanced embedding adds `kie` to its Endpoint list beside a complete, explicit set of Runtime
service packages and selections. The `.svml` Module Closure separately contains only the model
Manifests actually imported by the author document; installing KIE does not add author intent.
diff --git a/packages/provider-kie/src/provider.ts b/packages/provider-kie/src/provider.ts
index 7afc7dd7..49cf6be5 100644
--- a/packages/provider-kie/src/provider.ts
+++ b/packages/provider-kie/src/provider.ts
@@ -441,6 +441,7 @@ function endpoint(options: {
};
return {
async start(context) {
+ let submitting = false;
try {
const route = kieRouteForCapability(context.need.capability);
if (route === undefined) throw new KieError("KIE_UNSUPPORTED_CAPABILITY", "KIE does not implement this exact capability");
@@ -455,6 +456,7 @@ function endpoint(options: {
};
const task = await route.compile(context.need.constraints, resolve);
await options.gate.enter();
+ submitting = true;
const taskId = await options.client.createTask(task, key);
const handle: KieHandle = {
taskId,
@@ -465,6 +467,11 @@ function endpoint(options: {
phase: "submitted",
});
} catch (error) {
+ if (submitting && !(error instanceof KieError && ["KIE_SUBMISSION_REJECTED", "KIE_RATE_LIMITED"].includes(error.code))) {
+ return { status: "pending", wakeAt: options.now() + 30_000,
+ progress: { phase: "submission-unknown" }, failure: { code: "SUBMISSION_UNKNOWN",
+ message: "KIE submission acknowledgement is unknown; the same Build will not submit again" } };
+ }
return failure(error);
}
},
@@ -473,15 +480,17 @@ function endpoint(options: {
try {
handle = readHandle(context.handle, context);
} catch (error) {
- return failure(error);
+ throw error;
}
+ let remoteEnded = false;
try {
const route = kieRouteForCapability(context.need.capability);
if (route === undefined || route.key !== handle.routeKey) {
throw new KieError("KIE_HANDLE_INVALID", "KIE handle capability differs");
}
- if (options.now() - handle.startedAt >= options.maxOperationMs) {
- throw new KieError("KIE_OPERATION_TIMEOUT", "KIE task exceeded its operation deadline");
+ if (!context.settling && options.now() - handle.startedAt >= options.maxOperationMs) {
+ return { ...wakeAfter(canonicalize(handle), options.pollIntervalMs, options.now(), { phase: "settling" }),
+ failure: { code: "KIE_OPERATION_TIMEOUT", message: "KIE task exceeded its operation deadline; waiting for remote termination" } };
}
const key = secret(context);
const data = await options.client.taskInfo(handle.taskId, key);
@@ -491,6 +500,8 @@ function endpoint(options: {
phase: state,
});
}
+ remoteEnded = state === "fail" || state === "success";
+ if (remoteEnded && context.settling) return { status: "settled" };
if (state === "fail") {
const vendorCode = typeof data.failCode === "string" && data.failCode.length > 0 ? data.failCode : "unknown";
const vendorMessage = typeof data.failMsg === "string" && data.failMsg.length > 0
@@ -527,7 +538,8 @@ function endpoint(options: {
result: { value: result },
};
} catch (error) {
- return failure(error);
+ if (remoteEnded) return failure(error);
+ return wakeAfter(canonicalize(handle), options.pollIntervalMs, options.now(), { phase: "poll-unavailable" });
}
},
};
diff --git a/packages/provider-kie/test/provider.test.ts b/packages/provider-kie/test/provider.test.ts
index 0ef26b9b..c154b532 100644
--- a/packages/provider-kie/test/provider.test.ts
+++ b/packages/provider-kie/test/provider.test.ts
@@ -163,7 +163,7 @@ test("KIE uploads referenced resources, polls one task, and persists generated b
assert.equal(started.status === "pending" && (started.handle as Record<string, unknown>).taskId, "task_seedance_test");
const completed = await endpoint.poll({
...common,
- handle: started.handle,
+ handle: started.handle!,
});
assert.equal(completed.status, "completed");
assert.equal(calls.length, 5);
@@ -216,7 +216,7 @@ test("KIE fulfills generic Background Removal with the documented Recraft wire m
assert.equal(started.status, "pending");
if (started.status !== "pending") return;
const completed = await endpoint.poll({
- ...common, handle: started.handle,
+ ...common, handle: started.handle!,
});
assert.equal(completed.status, "completed");
if (completed.status !== "completed") return;
@@ -224,3 +224,30 @@ test("KIE fulfills generic Background Removal with the documented Recraft wire m
assert.equal(completed.result.value.kind === "blob" && completed.result.value.mediaType, "image/png");
assert.equal(calls.length, 5);
});
+
+test("KIE keeps a timed-out task reserved while observing its actual remote end", async () => {
+ const request = need({});
+ let now = 0, unavailable = false, state = "generating", submissions = 0;
+ const { endpoint } = await endpointFor(request, async (url) => {
+ if (String(url).includes("createTask")) { submissions++; throw new Error("no submission expected"); }
+ if (unavailable) throw new Error("offline");
+ return Response.json({ code: 200, data: { state } });
+ }, () => now);
+ const common = { command: { kind: "fulfill-need", id: "need:test", need: request } as const,
+ need: request, resources: new MemoryResourceStore(), credentials: { apiKey: { secret: "test" } }, operation: "op:test",
+ handle: { taskId: "existing", routeKey: "seedance-2-mini", startedAt: 0 } };
+ // Use the route's actual private handle format, obtained without any external call.
+ const { kieRouteForCapability } = await import("../src/routes.js");
+ common.handle.routeKey = kieRouteForCapability(request.capability)!.key;
+ unavailable = true;
+ assert.equal((await endpoint.poll(common)).status, "pending");
+ now = 60_001;
+ const timedOut = await endpoint.poll(common);
+ assert.equal(timedOut.status, "pending");
+ assert.equal(timedOut.status === "pending" && timedOut.failure?.code, "KIE_OPERATION_TIMEOUT");
+ unavailable = false;
+ assert.equal((await endpoint.poll({ ...common, settling: true })).status, "pending");
+ state = "success";
+ assert.deepEqual(await endpoint.poll({ ...common, settling: true }), { status: "settled" });
+ assert.equal(submissions, 0);
+});
diff --git a/packages/provider-media-local/test/provider.test.ts b/packages/provider-media-local/test/provider.test.ts
index 5aa0c615..e089f08f 100644
--- a/packages/provider-media-local/test/provider.test.ts
+++ b/packages/provider-media-local/test/provider.test.ts
@@ -929,3 +929,41 @@ test("local media Provider draws a stand-in card as a picture and as an exact si
const silenceBytes = await resources.get(silence.resource);
assert.equal(silenceBytes?.byteLength, 44 + 48_000 * 4);
});
+
+
+test("audio range preserves loop phase, tempo and intersected fades from the full programme", { skip: !hasMediaBinaries }, async () => {
+ const root = await mkdtemp(join(tmpdir(), "hypit-audio-range-"));
+ try {
+ const resources = new MemoryResourceStore();
+ const source = await resources.put(rampWav(4800), "audio/wav");
+ const plan = sealAudioProgramPlan({
+ frameRate: { numerator: 30, denominator: 1 }, frameCount: 60,
+ sampleRate: 48000, sampleFrames: 96000,
+ clips: [{ id: "loop", artifact: source, targetStartSample: 0, targetEndSampleExclusive: 96000,
+ sourceSampleFrames: 4800, sourceStartSample: 0, sourceEndSampleExclusive: 4800,
+ sourceLoop: true, sourcePhaseSample: 1700, playbackRate: 1.25, pitch: "preserve", gain: 0.8,
+ fadeInSamples: 48000, fadeOutSamples: 30000 }], mix: { normalize: false, limiter: "none" },
+ });
+ const pcm = async (name: string, range?: { startFrame: number; endFrameExclusive: number }) => {
+ const value = await fulfillInline(resources, need(`need:${name}`, mediaPipelineCapabilities.renderAudio,
+ mediaTypes.timelineAudio, canonicalize({ plan, ...(range === undefined ? {} : { range }) })));
+ verifyTimelineAudio(value);
+ const audio = value as unknown as TimelineAudio;
+ const path = join(root, `${name}.wav`), raw = join(root, `${name}.raw`);
+ await writeFile(path, (await resources.get(audio.artifact.resource))!);
+ await run("ffmpeg", ["-v", "error", "-y", "-i", path, "-f", "s16le", raw]);
+ return { bytes: await readFile(raw), samples: audio.sampleFrames };
+ };
+ const full = await pcm("full");
+ const range = await pcm("range", { startFrame: 15, endFrameExclusive: 45 });
+ assert.equal(range.samples, 48000);
+ const expected = full.bytes.subarray(24000 * 4, 72000 * 4);
+ assert.equal(range.bytes.length, expected.length);
+ let maximumError = 0;
+ for (let offset = 0; offset < expected.length; offset += 2) {
+ maximumError = Math.max(maximumError, Math.abs(range.bytes.readInt16LE(offset) - expected.readInt16LE(offset)));
+ }
+ // Different final filter block boundaries can round float PCM to the adjacent s16 value.
+ assert.ok(maximumError <= 1, `Selected audio differs by ${maximumError} PCM units`);
+ } finally { await rm(root, { recursive: true, force: true }); }
+});
diff --git a/packages/render-hyperframes/README.md b/packages/render-hyperframes/README.md
index 5806bac3..25312dcf 100644
--- a/packages/render-hyperframes/README.md
+++ b/packages/render-hyperframes/README.md
@@ -32,6 +32,23 @@ contract can feed the render Surface. Conversely, targeting Composition never de
rendering exists only when the author declares and the Build targets the video output.
`@hypit/provider-hyperframes-local` is the first concrete visual implementation. It stages the
-document's exact `BlobRef` dependencies, lets HyperFrames partition the finite frame domain across
+document's exact `BlobRef` dependencies, partitions the requested frame domain across
configured Chrome workers, emits a silent MP4 and rejects output unless ffprobe proves one H.264
stream with the declared canvas, rational frame rate and frame count.
+
+Select a contiguous interval using zero-based, half-open frame bounds:
+
+```xml
+<render:Video id="preview" composition={main.composition} semantic={speech.semantic}
+ start-frame="240" end-frame-exclusive="360"/>
+```
+
+At 30 fps this renders seconds 8–12, with 120 output frames. Write both bounds, or omit both to
+render the whole programme. The HTML and animation clock remain unchanged. Visual and audio Needs
+receive the same range; mux consumes their selected outputs. `workers` belongs in the local
+Provider's Runtime configuration.
+
+In TypeScript, `hyperframesVisualRequest(document, { range })` constructs the visual request;
+`createRenderHyperframesFragment(true)` accepts a `MediaFrameRange` input and connects it to visual
+and audio requests. The AWS Lambda Provider currently declines range requests. Selection limits
+final rendering work; it does not prune upstream generation dependencies.
diff --git a/packages/render-hyperframes/src/component.ts b/packages/render-hyperframes/src/component.ts
index e6ae095c..4c8bd2d7 100644
--- a/packages/render-hyperframes/src/component.ts
+++ b/packages/render-hyperframes/src/component.ts
@@ -1,3 +1,4 @@
+import type { MediaFrameRange } from "@hypit/media";
import { plannedNeedInputs } from "@hypit/component-kit";
import type { ComponentPackage } from "@hypit/component-kit";
import type { StoredValue } from "@hypit/protocol";
@@ -7,17 +8,18 @@ import { renderHyperframesCapabilities, renderHyperframesProducers } from "./man
/** Declares the visual Need. It contains no renderer, queue, credentials or deployment choice. */
export const renderHyperframesComponent = {
- producers: [{
- producer: renderHyperframesProducers.requestVisual,
+ producers: [renderHyperframesProducers.requestVisual, renderHyperframesProducers.requestVisualRange].map((producer) => ({
+ producer,
handler: ({ inputs }) => ({
outputs: {},
needs: {
- visual: hyperframesVisualRequest(inline(inputs.document!.value, "HyperframesDocument") as never),
+ visual: hyperframesVisualRequest(inline(inputs.document!.value, "HyperframesDocument") as never,
+ inputs.range === undefined ? {} : { range: inline(inputs.range.value, "MediaFrameRange") as MediaFrameRange }),
},
}),
- }],
- plannedNeeds: [{
- producer: renderHyperframesProducers.requestVisual,
+ })),
+ plannedNeeds: [renderHyperframesProducers.requestVisual, renderHyperframesProducers.requestVisualRange].map((producer) => ({
+ producer,
port: "visual",
capability: renderHyperframesCapabilities.renderVisual,
plan({ state, step }) {
@@ -26,7 +28,7 @@ export const renderHyperframesComponent = {
present(specification) {
return { fields: {}, references: {} };
},
- }],
+ })),
} satisfies ComponentPackage;
function inline(value: StoredValue, subject: string): unknown {
diff --git a/packages/render-hyperframes/src/fragment.ts b/packages/render-hyperframes/src/fragment.ts
index 772dfea9..e938d6ce 100644
--- a/packages/render-hyperframes/src/fragment.ts
+++ b/packages/render-hyperframes/src/fragment.ts
@@ -1,3 +1,4 @@
+import { mediaTypes } from "@hypit/media";
import { artifactTypes } from "@hypit/artifact";
import { semanticTrackProducers, semanticTrackTypes } from "@hypit/semantic-track";
import { compositionTypes } from "@hypit/composition";
@@ -12,61 +13,67 @@ import {
const input = (name: string) => ({ kind: "fragment-input" as const, name });
const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
-export const renderHyperframesFragment = sealGraphFragment({
- inputs: [
- { name: "composition", type: compositionTypes.composition },
- { name: "semantic", type: semanticTrackTypes.track },
- ],
- operations: [
- {
- id: "project-space",
- producer: semanticTrackProducers.projectProgramSpace,
- inputs: { track: input("semantic") },
- result: { kind: "output", name: "space" },
- },
- {
- id: "compile-document",
- producer: hyperframesProducers.compile,
- inputs: { composition: input("composition"), space: operation("project-space") },
- result: { kind: "output", name: "document" },
- },
- {
- id: "request-visual-render",
- producer: renderHyperframesProducers.requestVisual,
- inputs: { document: operation("compile-document") },
- result: { kind: "need", name: "visual" },
- },
- {
- id: "compile-audio-program",
- producer: mediaPipelineProducers.planAudio,
- inputs: { composition: input("composition"), space: operation("project-space") },
- result: { kind: "output", name: "plan" },
- },
- {
- id: "request-audio-render",
- producer: mediaPipelineProducers.renderAudio,
- inputs: { plan: operation("compile-audio-program") },
- result: { kind: "need", name: "audio" },
- },
- {
- id: "request-mux",
- producer: mediaPipelineProducers.mux,
- inputs: {
- visual: operation("request-visual-render"),
- audio: operation("request-audio-render"),
+export function createRenderHyperframesFragment(selectedRange = false) {
+ return sealGraphFragment({
+ inputs: [
+ { name: "composition", type: compositionTypes.composition },
+ { name: "semantic", type: semanticTrackTypes.track },
+ ...(selectedRange ? [{ name: "range", type: mediaTypes.frameRange }] : []),
+ ],
+ operations: [
+ {
+ id: "project-space",
+ producer: semanticTrackProducers.projectProgramSpace,
+ inputs: { track: input("semantic") },
+ result: { kind: "output", name: "space" },
},
- result: { kind: "need", name: "media" },
- },
- {
- id: "project-video",
- producer: mediaPipelineProducers.projectMuxed,
- inputs: { media: operation("request-mux") },
- result: { kind: "output", name: "video" },
- },
- ],
- exports: [{
- name: "video",
- type: artifactTypes.blob,
- root: operation("project-video"),
- }],
-});
+ {
+ id: "compile-document",
+ producer: hyperframesProducers.compile,
+ inputs: { composition: input("composition"), space: operation("project-space") },
+ result: { kind: "output", name: "document" },
+ },
+ {
+ id: "request-visual-render",
+ producer: selectedRange ? renderHyperframesProducers.requestVisualRange : renderHyperframesProducers.requestVisual,
+ inputs: { document: operation("compile-document"), ...(selectedRange ? { range: input("range") } : {}) },
+ result: { kind: "need", name: "visual" },
+ },
+ {
+ id: "compile-audio-program",
+ producer: mediaPipelineProducers.planAudio,
+ inputs: { composition: input("composition"), space: operation("project-space") },
+ result: { kind: "output", name: "plan" },
+ },
+ {
+ id: "request-audio-render",
+ producer: selectedRange ? mediaPipelineProducers.renderAudioRange : mediaPipelineProducers.renderAudio,
+ inputs: { plan: operation("compile-audio-program"), ...(selectedRange ? { range: input("range") } : {}) },
+ result: { kind: "need", name: "audio" },
+ },
+ {
+ id: "request-mux",
+ producer: mediaPipelineProducers.mux,
+ inputs: {
+ visual: operation("request-visual-render"),
+ audio: operation("request-audio-render"),
+ },
+ result: { kind: "need", name: "media" },
+ },
+ {
+ id: "project-video",
+ producer: mediaPipelineProducers.projectMuxed,
+ inputs: { media: operation("request-mux") },
+ result: { kind: "output", name: "video" },
+ },
+ ],
+ exports: [{
+ name: "video",
+ type: artifactTypes.blob,
+ root: operation("project-video"),
+ }],
+ });
+
+}
+
+export const renderHyperframesFragment = createRenderHyperframesFragment();
diff --git a/packages/render-hyperframes/src/index.ts b/packages/render-hyperframes/src/index.ts
index 55717a9a..c141a273 100644
--- a/packages/render-hyperframes/src/index.ts
+++ b/packages/render-hyperframes/src/index.ts
@@ -1,5 +1,6 @@
-export { renderHyperframesFragment } from "./fragment.js";
+export { renderHyperframesFragment, createRenderHyperframesFragment } from "./fragment.js";
export { renderHyperframesComponent } from "./component.js";
export { renderHyperframesCapabilities, renderHyperframesManifest, renderHyperframesMarkupSurfaces, renderHyperframesModuleRef, renderHyperframesProducers } from "./manifest.js";
-export { hyperframesVisualRequest } from "./product.js";
+export { hyperframesVisualRequest, verifyHyperframesVisualRequest } from "./product.js";
+export type { HyperframesVisualRequest } from "./product.js";
export { decodeHyperframesRenderSurface } from "./surface.js";
diff --git a/packages/render-hyperframes/src/manifest.ts b/packages/render-hyperframes/src/manifest.ts
index 9a43914e..045b57ee 100644
--- a/packages/render-hyperframes/src/manifest.ts
+++ b/packages/render-hyperframes/src/manifest.ts
@@ -21,6 +21,7 @@ export const renderHyperframesCapabilities = {
renderVisual: { module: renderHyperframesModuleRef, name: "render-visual" },
} satisfies Record<string, CapabilityRef>;
export const renderHyperframesProducers = {
+ requestVisualRange: { module: renderHyperframesModuleRef, name: "request-visual-range" },
requestVisual: { module: renderHyperframesModuleRef, name: "request-visual-render" },
} satisfies Record<string, ProducerRef>;
@@ -28,7 +29,7 @@ export const renderHyperframesMarkupSurfaces = [{
name: "video",
tag: "Video",
mode: "structured",
- outputs: [],
+ outputs: [mediaTypes.frameRange],
vocabulary: {
summary:
"Renders one Composition on one SemanticTrack into a final video, publishing the muxed result as a BlobArtifact.",
@@ -41,6 +42,8 @@ export const renderHyperframesMarkupSurfaces = [{
{ name: "semantic", kind: "reference", required: true,
accepts: [semanticTrackTypes.track],
summary: "Selects the SemanticTrack whose derived duration and frame rate every rendered Product is bound to." },
+ { name: "start-frame", kind: "literal", required: false, summary: "First original programme frame to render; requires end-frame-exclusive." },
+ { name: "end-frame-exclusive", kind: "literal", required: false, summary: "First excluded frame; requires start-frame." },
],
ports: [
{ name: "video", type: artifactTypes.blob,
@@ -48,7 +51,7 @@ export const renderHyperframesMarkupSurfaces = [{
],
example: '<render:Video id="final" composition={main.composition} semantic={speech.semantic}/>',
notes: [
- "All three attributes are required; the element accepts no children and no text content.",
+ "id, composition and semantic are required; write both frame bounds to select a range; the element accepts no children and no text content.",
"The visual render, the audio render and the mux are three separate Needs, each realized by a Provider this package does not choose.",
"The published Artifact carries no duration or lineage metadata, so a consumer that needs stream facts requests explicit media inspection.",
],
@@ -84,5 +87,15 @@ export const renderHyperframesManifest: ModuleManifest = {
returns: mediaTypes.renderedVisual,
}],
},
+ {
+ name: renderHyperframesProducers.requestVisualRange.name,
+ inputs: [{ name: "document", type: hyperframesTypes.document }, { name: "range", type: mediaTypes.frameRange }],
+ outputs: [],
+ needs: [{
+ name: "visual",
+ capability: renderHyperframesCapabilities.renderVisual,
+ returns: mediaTypes.renderedVisual,
+ }],
+ },
],
};
diff --git a/packages/render-hyperframes/src/product.ts b/packages/render-hyperframes/src/product.ts
index 9422687a..c72b769c 100644
--- a/packages/render-hyperframes/src/product.ts
+++ b/packages/render-hyperframes/src/product.ts
@@ -1,10 +1,29 @@
import type { CanonicalValue } from "@hypit/protocol";
import { assertHyperframesDocument } from "@hypit/hyperframes";
import type { HyperframesDocument } from "@hypit/hyperframes";
+import { verifyMediaFrameRange } from "@hypit/media";
+import type { MediaFrameRange } from "@hypit/media";
-export function hyperframesVisualRequest(document: HyperframesDocument): CanonicalValue {
+export type HyperframesVisualRequest = {
+ readonly document: HyperframesDocument;
+ readonly range?: MediaFrameRange;
+};
+
+export function verifyHyperframesVisualRequest(value: unknown): asserts value is HyperframesVisualRequest {
+ if (value === null || typeof value !== "object" || Array.isArray(value)
+ || Object.keys(value).some((key) => key !== "document" && key !== "range")) {
+ throw new Error("HyperFrames visual request requires document and an optional range");
+ }
+ const request = value as HyperframesVisualRequest;
+ assertHyperframesDocument(request.document);
+ if (request.range !== undefined) verifyMediaFrameRange(request.range, request.document.frameCount);
+}
+
+export function hyperframesVisualRequest(document: HyperframesDocument, options: { readonly range?: MediaFrameRange } = {}): CanonicalValue {
assertHyperframesDocument(document);
+ if (options.range !== undefined) verifyMediaFrameRange(options.range, document.frameCount);
return {
document,
+ ...(options.range === undefined ? {} : { range: options.range }),
};
}
diff --git a/packages/render-hyperframes/src/surface.ts b/packages/render-hyperframes/src/surface.ts
index bc4a8a69..7ece8af5 100644
--- a/packages/render-hyperframes/src/surface.ts
+++ b/packages/render-hyperframes/src/surface.ts
@@ -1,13 +1,13 @@
import { semanticTrackTypes } from "@hypit/semantic-track";
import { compositionTypes } from "@hypit/composition";
-import type { Composition } from "@hypit/composition";
+import { mediaTypes, verifyMediaFrameRange } from "@hypit/media";
import type {
StructuredElement,
StructuredSurfaceHandler,
MarkupAttributeValue,
} from "@hypit/markup";
-import { renderHyperframesFragment } from "./fragment.js";
+import { createRenderHyperframesFragment } from "./fragment.js";
function stringAttribute(element: StructuredElement, name: string): string {
const value = element.attributes[name];
@@ -25,7 +25,9 @@ function referenceAttribute(element: StructuredElement, name: string): string {
export const decodeHyperframesRenderSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
const names = Object.keys(element.attributes).sort();
- if (names.join(",") !== "composition,id,semantic") throw new Error(`${element.name} requires exactly composition, id and semantic`);
+ if (names.some((name) => !["composition", "id", "semantic", "start-frame", "end-frame-exclusive"].includes(name))) {
+ throw new Error(`${element.name} contains unsupported attributes`);
+ }
if (element.children.some((child) => child.kind === "element" || child.value.trim().length > 0)) {
throw new Error(`${element.name} does not accept children`);
}
@@ -46,15 +48,25 @@ export const decodeHyperframesRenderSurface: StructuredSurfaceHandler = ({ eleme
|| semantic.type.name !== semanticTrackTypes.track.name) {
throw new Error(`${element.name}.semantic must reference SemanticTrack`);
}
+ const selected = element.attributes["start-frame"] !== undefined || element.attributes["end-frame-exclusive"] !== undefined;
+ const frame = (name: string): number => {
+ const text = stringAttribute(element, name);
+ if (!/^\d+$/u.test(text)) throw new Error(`${element.name}.${name} must be a non-negative integer`);
+ return Number(text);
+ };
+ const range = selected ? { startFrame: frame("start-frame"), endFrameExclusive: frame("end-frame-exclusive") } : undefined;
+ if (range !== undefined) verifyMediaFrameRange(range);
+ const fragment = createRenderHyperframesFragment(selected);
+ const rangeId = `${id}.frame-range`;
return {
- records: [],
+ records: range === undefined ? [] : [{ id: rangeId, type: mediaTypes.frameRange, value: { kind: "inline", value: range }, range: element.range }],
components: [{
id,
- fragment: renderHyperframesFragment.id,
- inputs: { composition: composition.ref, semantic: semantic.ref },
+ fragment: fragment.id,
+ inputs: { composition: composition.ref, semantic: semantic.ref, ...(selected ? { range: { kind: "record" as const, id: rangeId } } : {}) },
outputs: { video: `${id}.video` },
range: element.range,
}],
- fragments: [renderHyperframesFragment],
+ fragments: [fragment],
};
};
diff --git a/packages/render-hyperframes/test/render.test.ts b/packages/render-hyperframes/test/render.test.ts
index 7fc5ff2e..19965ede 100644
--- a/packages/render-hyperframes/test/render.test.ts
+++ b/packages/render-hyperframes/test/render.test.ts
@@ -45,6 +45,7 @@ import {
renderHyperframesCapabilities,
renderHyperframesComponent,
renderHyperframesFragment,
+ createRenderHyperframesFragment,
renderHyperframesManifest,
renderHyperframesMarkupSurfaces,
renderHyperframesModuleRef,
@@ -332,7 +333,8 @@ function source(text: string): AuthorSourceUnit {
};
}
-test("the final rendered video is an ordinary BlobArtifact that can feed another author component", async () => {
+for (const selectedRange of [false, true]) {
+test(`the ${selectedRange ? "selected" : "full"} rendered video remains an ordinary BlobArtifact for downstream components`, async () => {
const sourceClosure = createResolvedClosure([
...videoContractManifests,
hyperframesManifest,
@@ -374,7 +376,7 @@ test("the final rendered video is an ordinary BlobArtifact that can feed another
<import as="render" from="@hypit/render-hyperframes@1"/>
<import as="media" from="@hypit/media-pipeline@1"/>
<fixture:Composition/>
- <render:Video id="final" composition={composition} semantic={semantic}/>
+ <render:Video id="final" composition={composition} semantic={semantic} ${selectedRange ? 'start-frame="15" end-frame-exclusive="45"' : ""}/>
<media:ExtractFrame id="poster" source={final.video} video="primary-moving" at="last"/>
</svml>`),
closure: sourceClosure,
@@ -392,12 +394,37 @@ test("the final rendered video is an ordinary BlobArtifact that can feed another
assert.deepEqual(state.plan.steps.map((step) => step.producer.name).sort(), [
"project-program-space",
hyperframesProducers.compile.name,
- renderHyperframesProducers.requestVisual.name,
+ selectedRange ? renderHyperframesProducers.requestVisualRange.name : renderHyperframesProducers.requestVisual.name,
mediaPipelineProducers.planAudio.name,
- mediaPipelineProducers.renderAudio.name,
+ selectedRange ? mediaPipelineProducers.renderAudioRange.name : mediaPipelineProducers.renderAudio.name,
mediaPipelineProducers.mux.name,
mediaPipelineProducers.projectMuxed.name,
mediaPipelineProducers.inspect.name,
mediaPipelineProducers.extractFrame.name,
].sort());
});
+}
+
+
+test("selected render frames reach both visual and audio Needs through the ordinary Build graph", async () => {
+ const range = { startFrame: 15, endFrameExclusive: 45 };
+ const rangeRecord = await admitRecord(closure, sealRecord({ id: "selection", type: mediaTypes.frameRange,
+ value: stored(range) }), validatorRegistry());
+ const program = link(closure, [compositionRecord, semanticRecord, rangeRecord]);
+ const fragment = createRenderHyperframesFragment(true);
+ const selected = elaborateGraphFragment(program, fragment, {
+ id: "selected", fragment: fragment.id, inputs: {
+ composition: { kind: "record", id: compositionRecord.id },
+ semantic: { kind: "record", id: semanticRecord.id },
+ range: { kind: "record", id: rangeRecord.id },
+ },
+ });
+ const selectedGraph = sealCompiledGraph(bindAuthorFragment(selected, { video: "selected.video" }));
+ const result = await new NodeDriver({ producers: producerRegistry(), validators: validatorRegistry() }).run(
+ start(program, selectedGraph, sealBuildRequest({ targets: [{ output: "selected.video" }] })),
+ );
+ assert.equal(result.state.needs.length, 2);
+ for (const need of result.state.needs) assert.deepEqual((need.constraints as { range: unknown }).range, range);
+ assert.throws(() => hyperframesVisualRequest(compileHyperframesDocument(composition, space),
+ { range: { startFrame: 0, endFrameExclusive: 61 } }), /frame range/);
+});
diff --git a/packages/runtime-host-node/src/index.ts b/packages/runtime-host-node/src/index.ts
index 9d8283ec..dd867247 100644
--- a/packages/runtime-host-node/src/index.ts
+++ b/packages/runtime-host-node/src/index.ts
@@ -10,6 +10,7 @@ import type { BuildDefinition, BuildState, CapabilityRef, Need, StoredValue } fr
import type {
BuildCatalogDescriptor,
BuildCompletion,
+ BuildExecutionStop,
CapacityReservation,
CredentialAcquisition,
CredentialRef,
@@ -50,6 +51,7 @@ export type BuildView = {
readonly outcome?: BuildCompletion["outcome"];
readonly issue?: { readonly scope: "result" | "cleanup"; readonly message: string };
readonly cancellationRequested: boolean;
+ readonly stop?: BuildExecutionStop;
readonly source?: { readonly path: string };
readonly run?: { readonly path: string };
readonly targets: readonly string[];
diff --git a/packages/runtime-local/README.md b/packages/runtime-local/README.md
index 1e755d8b..5fe230e4 100644
--- a/packages/runtime-local/README.md
+++ b/packages/runtime-local/README.md
@@ -58,8 +58,25 @@ resources declared by their Commands constrain execution. An Endpoint instance o
default. A Profile `pool` is only for instances that really share one account, deployment or compute
quota; exact-model limits may narrow it further. Build identity is not a capacity resource and creates
no second queue.
-Cancellation prevents new work and makes a best effort to cancel an external operation already submitted;
-completed output is never rolled back.
+Claims may carry `units` (default 1): one render Need can occupy one request slot and four browser
+slots at once. The same admission rule applies to total Provider capacity, exact models, and local
+compute resources. SQLite retains the weighted reservation across Worker turns and restarts. This
+coordinates Builds sharing this Runtime's Execution Store; it does not enforce a service's quotas
+across other machines. Request-frequency limits are a separate Provider policy.
+
+Runtime first persists a `stop` request for either user cancellation or execution failure. Its first
+cause and reason are retained; repeated cancellation cannot replace a recorded failure. The Worker
+resumes that stop after a restart without starting new Needs or storing control flags in Operation
+failure codes. It requests cancellation of already submitted Operations once.
+If cancellation is only accepted or unsupported, Runtime polls the same remote work until it ends,
+retaining its capacity and working Resources. A failed Build also settles unfinished Operations before
+writing its final Result and cleaning up. Completed output is never rolled back. An unknown submission
+acknowledgement remains visible as `submission-unknown`; it needs external confirmation, not an automatic
+retry, expiry or forced release.
+
+HypiHub can be the explicitly selected gateway for users without their own service keys. A bound
+Provider's authentication, quota or transport error never changes that selection. Separate Kie and
+HypiHub accounts use separate pools even when they implement the same model.
Without `hypit.results.json`, the official video Distribution selects the filesystem adapter at the
project's `.hypit/results` directory, with no cloud account or service. Runtime Local opens that default
diff --git a/packages/runtime-local/src/config.ts b/packages/runtime-local/src/config.ts
index 7351addd..51fb9b99 100644
--- a/packages/runtime-local/src/config.ts
+++ b/packages/runtime-local/src/config.ts
@@ -9,10 +9,12 @@ import {
import type { NodePackageSelectionRequest } from "@hypit/package-loader-node";
import { EndpointRegistry, NodeDriver } from "@hypit/driver-node";
import type { EndpointFulfillment, EndpointRegistrar, EndpointScheduling } from "@hypit/endpoint-kit";
+import { endpointResourceClaims } from "@hypit/endpoint-kit";
import { assertBuildId, canonicalize, canonicalStringify } from "@hypit/protocol";
import type { CanonicalValue, CapabilityRef, Need } from "@hypit/protocol";
import {
CompositeCredentialStore,
+ capacityUnits,
} from "@hypit/runtime";
import type { CredentialStore, CredentialValue, ResourceStore } from "@hypit/runtime";
import { FileResourceStore } from "@hypit/resource-store-fs";
@@ -496,6 +498,7 @@ class TransientSessionCapacity {
declare(resources: readonly TransientResourceClaim[]): void {
for (const resource of resources) {
+ capacityUnits(resource);
const previous = this.#limits.get(resource.id);
if (previous !== undefined && previous !== resource.limit) {
throw new Error(`Transient Runtime resource ${resource.id} has conflicting limits ${previous} and ${resource.limit}`);
@@ -506,15 +509,16 @@ class TransientSessionCapacity {
async run<T>(resources: readonly TransientResourceClaim[], task: () => Promise<T>): Promise<T> {
const ordered = [...resources].sort((left, right) => left.id.localeCompare(right.id));
- while (ordered.some((resource) => (this.#active.get(resource.id) ?? 0) >= resource.limit)) {
+ for (const resource of ordered) capacityUnits(resource);
+ while (ordered.some((resource) => (this.#active.get(resource.id) ?? 0) + capacityUnits(resource) > resource.limit)) {
await new Promise<void>((resolveWait) => this.#waiters.add(resolveWait));
}
- for (const resource of ordered) this.#active.set(resource.id, (this.#active.get(resource.id) ?? 0) + 1);
+ for (const resource of ordered) this.#active.set(resource.id, (this.#active.get(resource.id) ?? 0) + capacityUnits(resource));
try {
return await task();
} finally {
for (const resource of ordered) {
- const next = (this.#active.get(resource.id) ?? 1) - 1;
+ const next = (this.#active.get(resource.id) ?? capacityUnits(resource)) - capacityUnits(resource);
if (next === 0) this.#active.delete(resource.id);
else this.#active.set(resource.id, next);
}
@@ -563,7 +567,9 @@ export async function openTransientRuntimeConfigExecution(
const resources = registrationOptions.scheduling?.resources ?? [{ id: `endpoint:${id}`, limit: 1 }];
capacity.declare(resources);
endpoints.registerImmediateEndpoint(id, capability, returns, async (context) => {
- return await capacity.run(resources, async () => {
+ const claims = registrationOptions.scheduling === undefined ? resources
+ : endpointResourceClaims(registrationOptions.scheduling, context.need);
+ return await capacity.run(claims, async () => {
await assertReady();
return await handler(context);
});
@@ -867,7 +873,7 @@ async function inspectRuntimeConfig(
diagnostics.push({
severity: "error",
code: "RUNTIME_POOL_CONFLICT",
- message: `${conflict.endpointIds.join(", ")} share ${conflict.resource} but size it ${conflict.limits.join(" and ")}; give them the same defaultConcurrency or different pools`,
+ message: `${conflict.endpointIds.join(", ")} share ${conflict.resource} but size it ${conflict.limits.join(" and ")}; use the same limit for this shared resource or different pools`,
subject: conflict.resource,
});
}
diff --git a/packages/runtime-local/src/control.ts b/packages/runtime-local/src/control.ts
index baf43b27..d9a98c70 100644
--- a/packages/runtime-local/src/control.ts
+++ b/packages/runtime-local/src/control.ts
@@ -49,7 +49,8 @@ function buildView(input: {
...(input.execution?.attention === undefined ? {} : {
issue: { scope: input.execution.attention.step, message: input.execution.attention.error },
}),
- cancellationRequested: input.execution?.cancellation !== undefined,
+ cancellationRequested: input.execution?.stop?.cause === "user-cancelled",
+ ...(input.execution?.stop === undefined ? {} : { stop: input.execution.stop }),
...(input.catalog?.source === undefined ? {} : { source: input.catalog.source }),
...(input.catalog?.run === undefined ? {} : { run: input.catalog.run }),
targets,
@@ -105,7 +106,8 @@ export function createLocalRuntimeControl(
},
async cancel(build, reason) {
if (await options.executionStore.read(build) === undefined) return undefined;
- await options.executionStore.requestCancellation(build, reason);
+ await options.executionStore.requestStop(build, { cause: "user-cancelled",
+ ...(reason === undefined ? {} : { reason }) });
return await inspect(build);
},
close() {
diff --git a/packages/runtime-local/src/result-writer.ts b/packages/runtime-local/src/result-writer.ts
index 30c8d52b..1e5ea284 100644
--- a/packages/runtime-local/src/result-writer.ts
+++ b/packages/runtime-local/src/result-writer.ts
@@ -158,6 +158,9 @@ export function createLocalResultWriter(
`Execution ${execution.build} Result writer is not owned by this process`);
let step: "result" | "cleanup" = "result";
try {
+ const operations = await options.operationStore.list({ build: execution.build });
+ assert(!operations.some((operation) => operation.status === "pending"),
+ `Build ${execution.build} still has unsettled external work`);
await finishResult(execution);
step = "cleanup";
await Promise.resolve(options.clearBuildResources?.(execution.build));
diff --git a/packages/runtime-local/src/worker.ts b/packages/runtime-local/src/worker.ts
index 8f07f8de..27688aa6 100644
--- a/packages/runtime-local/src/worker.ts
+++ b/packages/runtime-local/src/worker.ts
@@ -76,7 +76,7 @@ class CapacityExecutor implements RuntimeCommandExecutor {
const execution = await this.#options.stores.execution.read(build);
assert(execution?.turn?.owner === this.#owner && execution.decision === undefined,
`Build ${build} is not owned by this Worker turn`);
- assert(execution.cancellation === undefined, `Build ${build} is being cancelled`);
+ assert(execution.stop === undefined, `Build ${build} is stopping`);
}
async #executeOnce(
@@ -166,10 +166,10 @@ class CapacityExecutor implements RuntimeCommandExecutor {
}
return result;
} catch (error) {
- await this.#options.stores.execution.releaseCapacity(
- acquired.reservation.build,
- acquired.reservation.command,
- ).catch(() => undefined);
+ const operations = await this.#options.stores.operations.list({ build: context.build, command: descriptor.command.id });
+ if (!operations.some((operation) => operation.status === "pending")) {
+ await this.#options.stores.execution.releaseCapacity(context.build, descriptor.command.id);
+ }
throw error;
}
}
@@ -195,54 +195,57 @@ class DurableLocalWorker {
this.#executorWithCapacity = new CapacityExecutor(executor, options, this.#owner);
}
- async #cancel(execution: BuildExecutionSnapshot): Promise<WorkerTurnResult> {
+ async #finishResult(execution: BuildExecutionSnapshot, outcome: import("@hypit/runtime").BuildOutcome): Promise<WorkerTurnResult> {
+ await this.#options.stores.execution.releaseBuildCapacity(execution.build);
+ const decided = await this.#options.stores.execution.decide(execution.build, this.#owner, outcome);
+ return await this.#options.resultWriter.completeResult(decided);
+ }
+
+ async #settle(execution: BuildExecutionSnapshot): Promise<WorkerTurnResult> {
+ assert(execution.stop !== undefined, `Build ${execution.build} has no stop request`);
const snapshot = await this.#options.stores.builds.read(execution.build);
assert(snapshot !== undefined, `Build ${execution.build} has no durable execution state`);
- const operations = await this.#options.stores.operations.list({ build: execution.build });
- const active = operations
- .filter((item) => item.status === "pending" && item.handle !== undefined);
- for (const operation of active) {
- if (this.#executor.cancelOperation !== undefined) {
- await this.#executor.cancelOperation(snapshot.state, operation).catch(() => undefined);
- } else {
- await this.#options.stores.operations.update(operation.id, { status: "cancelled" });
+ for (const operation of await this.#options.stores.operations.list({ build: execution.build })) {
+ if (operation.status !== "pending") continue;
+ const settled = await this.#executor.cancelOperation?.(snapshot.state, operation).catch(() => undefined);
+ if (settled !== undefined && settled.status !== "pending") {
+ await this.#options.stores.execution.releaseCapacity(execution.build, operation.command);
}
}
- await this.#options.stores.execution.releaseBuildCapacity(execution.build);
- const decided = await this.#options.stores.execution.decide(
- execution.build,
- this.#owner,
- "cancelled",
- execution.cancellation?.reason ?? "cancelled by Runtime",
- );
- return await this.#options.resultWriter.completeResult(decided);
+ const pending = (await this.#options.stores.operations.list({ build: execution.build }))
+ .filter((operation) => operation.status === "pending");
+ if (pending.length > 0) {
+ const now = Date.now();
+ return await this.#options.stores.execution.releaseTurn(execution.build, this.#owner,
+ Math.min(...pending.map((operation) => Math.max(now + 100, operation.wakeAt ?? now + 1_000))), execution.stop);
+ }
+ return await this.#finishResult(execution, execution.stop.cause === "user-cancelled" ? "cancelled" : "failed");
+ }
+
+ async #stopFailed(execution: BuildExecutionSnapshot, reason: string): Promise<WorkerTurnResult> {
+ const stopped = await this.#options.stores.execution.requestStop(execution.build, { cause: "execution-failed", reason });
+ return await this.#settle(stopped);
}
async #finish(execution: BuildExecutionSnapshot, result: ScheduledBuildResult): Promise<WorkerTurnResult> {
const current = await this.#options.stores.execution.read(execution.build);
assert(current?.turn?.owner === this.#owner && current.decision === undefined,
`Execution ${execution.build} is no longer owned by this Worker turn`);
- if (current.cancellation !== undefined) return await this.#cancel(current);
+ if (current.stop !== undefined) return await this.#settle(current);
if (result.status === "complete") {
- await this.#options.stores.execution.releaseBuildCapacity(execution.build);
- const decided = await this.#options.stores.execution.decide(execution.build, this.#owner, "complete");
- return await this.#options.resultWriter.completeResult(decided);
+ return await this.#finishResult(execution, "complete");
}
if (result.status === "failed" || result.outcomes.some((item) => item.status === "error")) {
const reason = result.outcomes.find((item) => item.status === "error")?.message
?? result.state.diagnostics.at(-1)?.message
?? "Core Build failed";
- await this.#options.stores.execution.releaseBuildCapacity(execution.build);
- const decided = await this.#options.stores.execution.decide(execution.build, this.#owner, "failed", reason);
- return await this.#options.resultWriter.completeResult(decided);
+ return await this.#stopFailed(execution, reason);
}
const pending = result.outcomes.filter((item) => item.status === "pending");
const deferred = result.outcomes.filter((item) => item.status === "deferred");
if (pending.length === 0 && deferred.length === 0 && result.blocked.length > 0) {
const reason = result.blocked.map((item) => `${item.reason}: ${item.subject}`).join(", ");
- await this.#options.stores.execution.releaseBuildCapacity(execution.build);
- const decided = await this.#options.stores.execution.decide(execution.build, this.#owner, "failed", reason);
- return await this.#options.resultWriter.completeResult(decided);
+ return await this.#stopFailed(execution, reason);
}
const now = Date.now();
const wakeAt = Math.min(...[
@@ -254,16 +257,12 @@ class DurableLocalWorker {
this.#owner,
Number.isFinite(wakeAt) ? wakeAt : now,
);
- return released.cancellation === undefined ? released : await this.#cancel(released);
+ return released;
}
async #fail(execution: BuildExecutionSnapshot, error: unknown): Promise<WorkerTurnResult> {
- const current = await this.#options.stores.execution.read(execution.build);
- if (current?.cancellation !== undefined) return await this.#cancel(current);
const reason = error instanceof Error ? error.message : String(error);
- await this.#options.stores.execution.releaseBuildCapacity(execution.build);
- const decided = await this.#options.stores.execution.decide(execution.build, this.#owner, "failed", reason);
- return await this.#options.resultWriter.completeResult(decided);
+ return await this.#stopFailed(execution, reason);
}
async #runClaimed(executions: readonly BuildExecutionSnapshot[]): Promise<readonly WorkerTurnResult[]> {
@@ -272,8 +271,8 @@ class DurableLocalWorker {
for (const execution of executions) {
assert(execution.turn?.owner === this.#owner && execution.decision === undefined,
`Execution ${execution.build} was not claimed by this Worker turn`);
- if (execution.cancellation !== undefined) {
- finished.push(await this.#cancel(execution));
+ if (execution.stop !== undefined) {
+ finished.push(await this.#settle(execution));
continue;
}
try {
diff --git a/packages/runtime-local/test/config.test.ts b/packages/runtime-local/test/config.test.ts
index c9903c86..60bad876 100644
--- a/packages/runtime-local/test/config.test.ts
+++ b/packages/runtime-local/test/config.test.ts
@@ -732,7 +732,7 @@ test("providers, doctor and invoke share one resolver: a contested capability is
}
});
-test("doctor reports two Endpoints that share a pool but size it differently", async () => {
+test("doctor reports inconsistent limits for shared pools and capacity resources", async () => {
const root = await mkdtemp(join(tmpdir(), "hypit-runtime-pools-"));
const path = join(root, "hypit.runtime.json");
await writeFile(path, JSON.stringify(profile({
@@ -759,6 +759,7 @@ test("doctor reports two Endpoints that share a pool but size it differently", a
capability: { module: { name: "example.model", version: "1" }, name },
returns,
lifecycle: "immediate",
+ resources: [{ id: "capacity:generation/browsers", limit: concurrency }],
handler: () => ({ value: { kind: "inline" as const, value: null } }),
}],
}),
@@ -766,9 +767,13 @@ test("doctor reports two Endpoints that share a pool but size it differently", a
}));
}
try {
- const conflict = (await preflightRuntimeConfig(path, { registry })).diagnostics.find((item) => item.code === "RUNTIME_POOL_CONFLICT");
- assert.ok(conflict, "the shared pool is reported");
- assert.match(conflict.message, /four, ten share pool:generation but size it 4 and 10/u);
+ const conflicts = (await preflightRuntimeConfig(path, { registry })).diagnostics.filter((item) => item.code === "RUNTIME_POOL_CONFLICT");
+ for (const resource of ["pool:generation", "capacity:generation/browsers"]) {
+ const conflict = conflicts.find((item) => item.subject === resource);
+ assert.ok(conflict, `the shared resource ${resource} is reported`);
+ assert.equal(conflict.message,
+ `four, ten share ${resource} but size it 4 and 10; use the same limit for this shared resource or different pools`);
+ }
} finally {
await rm(root, { recursive: true, force: true });
}
diff --git a/packages/runtime-local/test/local.test.ts b/packages/runtime-local/test/local.test.ts
index badc322b..36c68755 100644
--- a/packages/runtime-local/test/local.test.ts
+++ b/packages/runtime-local/test/local.test.ts
@@ -945,3 +945,89 @@ test("project local runtime remembers the complete package closure across increm
await rm(directory, { recursive: true, force: true });
}
});
+
+for (const cancellation of ["accepted", "unsupported", "failed-build", "host-failure"] as const) {
+ test(`unconfirmed ${cancellation} retains capacity and work until remote termination`, async () => {
+ const directory = await mkdtemp(join(tmpdir(), "hypit-settlement-"));
+ let fixture = projectRuntimeFixture(directory);
+ let failRead = false;
+ let remoteActive = 0, starts = 0, cancels = 0, finished = false;
+ const provider = defineEndpointPackage({ module: providerModule, facet: "generation", instance: "settlement",
+ pool: "shared", defaultConcurrency: 1, capabilities: [{ capability: capabilities.generation, returns: types.generated,
+ lifecycle: "asynchronous", endpoint: {
+ start() { starts++; remoteActive++; return { status: "pending", handle: { job: starts }, wakeAt: Date.now() + 60_000 }; },
+ poll(context) {
+ assert.equal(context.settling, true);
+ if (!finished) return { status: "pending", handle: context.handle, wakeAt: Date.now() };
+ remoteActive--; return { status: "settled" };
+ },
+ cancel() { cancels++; return { status: cancellation === "accepted" ? "accepted" : "unsupported" }; },
+ } }] });
+ const openRuntime = () => createLocalRuntime({ ...fixture, endpoints: [provider],
+ buildStore: {
+ create: (...args) => fixture.buildStore.create(...args),
+ append: (...args) => fixture.buildStore.append(...args),
+ read: async (build) => {
+ if (failRead) { failRead = false; throw new Error("Runtime read interrupted"); }
+ return await fixture.buildStore.read(build);
+ },
+ }, components: [{ producers: [
+ { producer: producers.makePrompt, handler: () => ({ outputs: { prompt: { kind: "inline", value: "hello" } }, needs: {} }) },
+ { producer: producers.requestText, handler: () => ({ outputs: {}, needs: { generation: { prompt: "hello" } } }) },
+ ] }] });
+ let runtime = await openRuntime();
+ try {
+ const first = "bld_20260905T120000001Z_0000000001";
+ const second = "bld_20260905T120000002Z_0000000001";
+ const initial = createGreetingBuild({ targetOutputs: ["generated"] });
+ await runtime.build(durableBuildRequest(directory, first, initial));
+ await runtime.workOnce();
+ if (cancellation === "failed-build" || cancellation === "host-failure") {
+ if (cancellation === "failed-build") {
+ const snapshot = (await fixture.buildStore.read(first))!;
+ const { BuildMachine } = await import("@hypit/core");
+ const machine = new BuildMachine(snapshot.definition, snapshot.facts);
+ const operation = (await fixture.operationStore.list({ build: first }))[0]!;
+ const fact = machine.evaluate({ kind: "command-failed", command: operation.command, code: "EXAMPLE_FAILURE", message: "a sibling failed" });
+ assert.ok(fact); await fixture.buildStore.append(first, fact);
+ } else { failRead = true; }
+ await fixture.executionStore.claim("test-wake", Date.now() + 60_001);
+ await fixture.executionStore.releaseTurn(first, "test-wake", Date.now());
+ } else { await runtime.cancel(first); }
+ await runtime.workOnce();
+ assert.equal((await fixture.operationStore.list({ build: first }))[0]?.status, "pending");
+ assert.equal((await fixture.executionStore.listCapacity()).length, 1);
+ assert.equal((await fixture.executionStore.read(first))?.decision, undefined);
+ const stopped = (await fixture.executionStore.read(first))!.stop!;
+ const isFailure = cancellation === "failed-build" || cancellation === "host-failure";
+ assert.equal(stopped.cause, isFailure ? "execution-failed" : "user-cancelled");
+ assert.equal((await fixture.operationStore.list({ build: first }))[0]?.failure, undefined,
+ "Build stopping must not overwrite the remote Operation's own failure");
+ await runtime.cancel(first, "second cancellation must not replace the first stop");
+ await runtime.cancel(first, "third cancellation");
+ assert.deepEqual((await fixture.executionStore.read(first))?.stop, stopped);
+ await runtime.close();
+ fixture = projectRuntimeFixture(directory);
+ runtime = await openRuntime();
+ assert.deepEqual((await fixture.executionStore.read(first))?.stop, stopped);
+ assert.deepEqual((await runtime.inspect(first))?.stop, stopped);
+ await runtime.build(durableBuildRequest(directory, second, initial));
+ await runtime.workOnce();
+ assert.equal(starts, 1, "the next Need must not start while the cancelled remote work still occupies its slot");
+ assert.equal(remoteActive, 1);
+ finished = true;
+ await new Promise((resolve) => setTimeout(resolve, 120));
+ const completion = await runtime.workOnce();
+ assert.ok(completion !== undefined && "outcome" in completion);
+ assert.equal(completion.outcome, isFailure ? "failed" : "cancelled");
+ assert.equal(completion.reason, stopped.reason);
+ assert.equal((await fixture.operationStore.list({ build: first })).length, 0);
+ assert.equal(remoteActive, 0);
+ assert.equal(cancels, 1, "cancel is attempted once across polling turns");
+ await new Promise((resolve) => setTimeout(resolve, 260));
+ await runtime.workOnce();
+ assert.equal(starts, 2);
+ assert.equal(remoteActive, 1);
+ } finally { await runtime.close(); await rm(directory, { recursive: true, force: true }); }
+ });
+}
diff --git a/packages/runtime/README.md b/packages/runtime/README.md
index 46670f9e..1b1f7620 100644
--- a/packages/runtime/README.md
+++ b/packages/runtime/README.md
@@ -7,7 +7,7 @@ The package defines the small ports used by a runtime:
* `BuildStore` keeps one active Build definition and its accepted facts until the Result is saved and active state is removed.
* `OperationStore` keeps asynchronous external work only while the owning Build is active.
* `PendingBuildStore` owns the short submission transaction before the Build becomes active.
-* `BuildExecutionStore` owns active scheduling facts, the immutable decision, attention and shared capacity reservations.
+* `BuildExecutionStore` owns active scheduling facts, a stop request, the immutable decision, attention and shared capacity reservations.
* `ResourceStore` is the transient byte gateway used during Provider execution.
* `CredentialStore` resolves secrets outside source and build state.
* `RuntimeCommandExecutor` turns the commands regenerated by Core into component or endpoint calls.
@@ -19,3 +19,10 @@ implementation lives in `@hypit/runtime-local`; Node component and endpoint exec
The scheduler never changes graph meaning. Targets and candidates are fixed before execution, and
resource limits only control when an already selected command may run.
+
+
+A Build's `stop` records `user-cancelled` or `execution-failed` and an optional reason. The first request
+is retained across turns and restarts; repeated requests cannot replace it. It prohibits new work,
+but says nothing about whether an external Operation has ended. Only after those Operations settle
+does the Runtime freeze `decision` and finish the Result. Operation failures keep their own meaning;
+error codes do not carry Build control state.
diff --git a/packages/runtime/src/capacity.ts b/packages/runtime/src/capacity.ts
index 0f3bcfd5..72fb62a1 100644
--- a/packages/runtime/src/capacity.ts
+++ b/packages/runtime/src/capacity.ts
@@ -2,9 +2,23 @@
export type CapacityResourceClaim = {
readonly id: string;
readonly limit: number;
+ /** Number of units held by this Command; ordinary requests occupy one. */
+ readonly units?: number;
};
-/** One asynchronous external Operation that currently occupies Provider capacity. */
+export function capacityUnits(resource: CapacityResourceClaim): number {
+ const units = resource.units ?? 1;
+ if (resource.id.trim().length === 0 || !Number.isSafeInteger(resource.limit) || resource.limit < 1
+ || !Number.isSafeInteger(units) || units < 1) {
+ throw new Error(`Capacity ${resource.id} requires a positive integer limit and units`);
+ }
+ if (units > resource.limit) {
+ throw new Error(`Capacity ${resource.id} request needs ${units} units but its limit is ${resource.limit}`);
+ }
+ return units;
+}
+
+/** Capacity held by one executing Command, including a pending external Operation. */
export type CapacityReservation = {
readonly build: string;
readonly command: string;
diff --git a/packages/runtime/src/execution.ts b/packages/runtime/src/execution.ts
index a29de4aa..cbd8be64 100644
--- a/packages/runtime/src/execution.ts
+++ b/packages/runtime/src/execution.ts
@@ -21,6 +21,12 @@ export type BuildExecutionDecision = {
readonly reason?: string;
};
+/** A durable instruction to stop launching work, independent of remote Operation termination. */
+export type BuildExecutionStop = {
+ readonly cause: "user-cancelled" | "execution-failed";
+ readonly reason?: string;
+};
+
export type BuildExecutionAttention = {
readonly step: "result" | "cleanup";
readonly error: string;
@@ -37,14 +43,15 @@ export type BuildResultWriteLease = BuildExecutionTurn;
* The complete active Runtime root for one Build.
*
* It has no persisted lifecycle phase. Scheduling is derived from `wakeAt` and `turn`; the one
- * immutable execution conclusion is `decision`; operator attention is an independent fact.
+ * immutable execution conclusion is `decision`; `stop` records why new work must stop while
+ * existing Operations settle. Operator attention is an independent fact.
*/
export type BuildExecutionSnapshot = BuildExecutionRequest & {
readonly createdAt: number;
readonly wakeAt: number;
readonly turn?: BuildExecutionTurn;
readonly resultWrite?: BuildResultWriteLease;
- readonly cancellation?: { readonly reason?: string };
+ readonly stop?: BuildExecutionStop;
readonly decision?: BuildExecutionDecision;
readonly attention?: BuildExecutionAttention;
};
@@ -73,10 +80,12 @@ export type BuildExecutionStore = {
claim(owner: string, now?: number): Promise<BuildExecutionSnapshot | undefined>;
/** A new owning Worker clears turns left by the previous process; no external action is repeated here. */
reclaimTurns(now?: number): Promise<readonly string[]>;
- releaseTurn(build: string, owner: string, wakeAt: number): Promise<BuildExecutionSnapshot>;
+ /** An unobserved stop wakes the next turn immediately; a settling turn may wait for its next poll. */
+ releaseTurn(build: string, owner: string, wakeAt: number, observedStop?: BuildExecutionStop): Promise<BuildExecutionSnapshot>;
/** Freeze the one conclusion. An execution with a decision can never be claimed again. */
decide(build: string, owner: string, outcome: BuildOutcome, reason?: string): Promise<BuildExecutionSnapshot>;
- requestCancellation(build: string, reason?: string): Promise<BuildExecutionSnapshot>;
+ /** Record the first stop request. Repeated requests cannot replace its cause or reason. */
+ requestStop(build: string, stop: BuildExecutionStop): Promise<BuildExecutionSnapshot>;
setAttention(build: string, attention: BuildExecutionAttention | undefined): Promise<BuildExecutionSnapshot>;
claimResultWrite(build: string, owner: string, now?: number): Promise<BuildExecutionSnapshot | undefined>;
releaseResultWrite(build: string, owner: string): Promise<BuildExecutionSnapshot>;
diff --git a/packages/runtime/src/index.ts b/packages/runtime/src/index.ts
index f4d4d827..64d78d6e 100644
--- a/packages/runtime/src/index.ts
+++ b/packages/runtime/src/index.ts
@@ -9,6 +9,7 @@ export {
} from "./credentials.js";
export type * from "./credentials.js";
export type * from "./capacity.js";
+export { capacityUnits } from "./capacity.js";
export { buildExecutionActivity } from "./execution.js";
export type * from "./execution.js";
export type * from "./environment.js";
diff --git a/packages/runtime/src/operations.ts b/packages/runtime/src/operations.ts
index 24e1a30b..514d2cc7 100644
--- a/packages/runtime/src/operations.ts
+++ b/packages/runtime/src/operations.ts
@@ -40,14 +40,20 @@ export type OperationSnapshot = OperationIdentity & {
readonly progress?: OperationProgress;
readonly completion?: OperationCompletion;
readonly failure?: OperationFailure;
+ /** A cancel call was attempted; subsequent turns only observe the same external work. */
+ readonly cancellationRequested?: true;
};
export type OperationUpdate =
| {
readonly status: "pending";
- readonly handle: CanonicalValue;
+ /** Missing only when submission acknowledgement is unknown; never resubmit automatically. */
+ readonly handle?: CanonicalValue;
readonly wakeAt?: number;
readonly progress?: OperationProgress;
+ /** Local execution failed, but remote settlement has not yet been confirmed. */
+ readonly failure?: OperationFailure;
+ readonly cancellationRequested?: true;
}
| {
readonly status: "completed";
diff --git a/packages/runtime/src/scheduler.ts b/packages/runtime/src/scheduler.ts
index 1fe0bdae..b2856e02 100644
--- a/packages/runtime/src/scheduler.ts
+++ b/packages/runtime/src/scheduler.ts
@@ -1,5 +1,6 @@
import { BuildMachine, reduce } from "@hypit/core";
import type { BuildState } from "@hypit/protocol";
+import { capacityUnits } from "./capacity.js";
import type {
BuildSchedulerOptions,
@@ -96,6 +97,7 @@ export class LocalBuildScheduler {
let cursor = 0;
const resourceLimit = (resource: RuntimeRunnableCommand["resources"][number]): number => {
+ capacityUnits(resource);
const proposed = positiveInteger(resource.limit, `resource ${resource.id} limit`);
const previous = resourceDefaults.get(resource.id);
if (previous !== undefined && previous !== proposed) {
@@ -142,7 +144,7 @@ export class LocalBuildScheduler {
const counts = new Map<string, number>();
for (const item of active.values()) {
for (const resource of item.command.resources) {
- counts.set(resource.id, (counts.get(resource.id) ?? 0) + 1);
+ counts.set(resource.id, (counts.get(resource.id) ?? 0) + capacityUnits(resource));
}
}
return counts;
@@ -158,90 +160,97 @@ export class LocalBuildScheduler {
active.set(key, { build, command, promise });
};
- while (true) {
- const ready = await preparations();
- const counts = resourceCounts();
+ try {
+ while (true) {
+ const ready = await preparations();
+ const counts = resourceCounts();
- while (builds.length > 0) {
- let selected = false;
- for (let offset = 0; offset < builds.length; offset += 1) {
- const index = (cursor + offset) % builds.length;
- const build = builds[index]!;
- const command = (ready.get(build.id) ?? []).find((candidate) =>
- candidate.resources.every((resource) =>
- (counts.get(resource.id) ?? 0) < resourceLimit(resource)));
- if (command === undefined) continue;
- ready.set(build.id, (ready.get(build.id) ?? []).filter((item) =>
- item.command.id !== command.command.id));
- launch(build, command);
- for (const resource of command.resources) {
- counts.set(resource.id, (counts.get(resource.id) ?? 0) + 1);
+ while (builds.length > 0) {
+ let selected = false;
+ for (let offset = 0; offset < builds.length; offset += 1) {
+ const index = (cursor + offset) % builds.length;
+ const build = builds[index]!;
+ const command = (ready.get(build.id) ?? []).find((candidate) =>
+ candidate.resources.every((resource) =>
+ (counts.get(resource.id) ?? 0) + capacityUnits(resource) <= resourceLimit(resource)));
+ if (command === undefined) continue;
+ ready.set(build.id, (ready.get(build.id) ?? []).filter((item) =>
+ item.command.id !== command.command.id));
+ launch(build, command);
+ for (const resource of command.resources) {
+ counts.set(resource.id, (counts.get(resource.id) ?? 0) + capacityUnits(resource));
+ }
+ cursor = (index + 1) % builds.length;
+ selected = true;
+ break;
}
- cursor = (index + 1) % builds.length;
- selected = true;
- break;
+ if (!selected) break;
}
- if (!selected) break;
- }
- if (active.size === 0) break;
- const settled = await Promise.race([...active.values()].map((item) => item.promise));
- active.delete(settled.key);
- const build = settled.build;
- if (settled.execution === undefined) {
- build.stopped = true;
- build.outcomes.push({
- command: settled.command.command.id,
- kind: settled.command.command.kind,
- resources: settled.command.resources.map((resource) => resource.id),
- status: "error",
- message: settled.error instanceof Error ? settled.error.message : String(settled.error),
- });
- continue;
- }
- if (settled.execution.status === "pending") {
- build.stopped = true;
- build.outcomes.push({
- command: settled.command.command.id,
- kind: settled.command.command.kind,
- resources: settled.command.resources.map((resource) => resource.id),
- status: "pending",
- operation: settled.execution.operation,
- ...(settled.execution.wakeAt === undefined ? {} : { wakeAt: settled.execution.wakeAt }),
- });
- continue;
- }
- if (settled.execution.status === "deferred") {
- build.stopped = true;
- build.outcomes.push({
- command: settled.command.command.id,
- kind: settled.command.command.kind,
- resources: settled.command.resources.map((resource) => resource.id),
- status: "deferred",
- wakeAt: settled.execution.wakeAt,
- message: settled.execution.reason,
- });
- continue;
- }
- const event = settled.execution.event;
- try {
- await accept(build, event);
- build.outcomes.push({
- command: settled.command.command.id,
- kind: settled.command.command.kind,
- resources: settled.command.resources.map((resource) => resource.id),
- status: "completed",
- });
- } catch (error) {
- build.stopped = true;
- build.outcomes.push({
- command: settled.command.command.id,
- kind: settled.command.command.kind,
- resources: settled.command.resources.map((resource) => resource.id),
- status: "error",
- message: error instanceof Error ? error.message : String(error),
- });
+ if (active.size === 0) break;
+ const settled = await Promise.race([...active.values()].map((item) => item.promise));
+ active.delete(settled.key);
+ const build = settled.build;
+ if (settled.execution === undefined) {
+ build.stopped = true;
+ build.outcomes.push({
+ command: settled.command.command.id,
+ kind: settled.command.command.kind,
+ resources: settled.command.resources.map((resource) => resource.id),
+ status: "error",
+ message: settled.error instanceof Error ? settled.error.message : String(settled.error),
+ });
+ continue;
+ }
+ if (settled.execution.status === "pending") {
+ build.stopped = true;
+ build.outcomes.push({
+ command: settled.command.command.id,
+ kind: settled.command.command.kind,
+ resources: settled.command.resources.map((resource) => resource.id),
+ status: "pending",
+ operation: settled.execution.operation,
+ ...(settled.execution.wakeAt === undefined ? {} : { wakeAt: settled.execution.wakeAt }),
+ });
+ continue;
+ }
+ if (settled.execution.status === "deferred") {
+ build.stopped = true;
+ build.outcomes.push({
+ command: settled.command.command.id,
+ kind: settled.command.command.kind,
+ resources: settled.command.resources.map((resource) => resource.id),
+ status: "deferred",
+ wakeAt: settled.execution.wakeAt,
+ message: settled.execution.reason,
+ });
+ continue;
+ }
+ const event = settled.execution.event;
+ try {
+ await accept(build, event);
+ build.outcomes.push({
+ command: settled.command.command.id,
+ kind: settled.command.command.kind,
+ resources: settled.command.resources.map((resource) => resource.id),
+ status: "completed",
+ });
+ } catch (error) {
+ build.stopped = true;
+ build.outcomes.push({
+ command: settled.command.command.id,
+ kind: settled.command.command.kind,
+ resources: settled.command.resources.map((resource) => resource.id),
+ status: "error",
+ message: error instanceof Error ? error.message : String(error),
+ });
+ }
}
+
+ } catch (error) {
+ // Do not let a classification/configuration error release capacity beneath other active calls.
+ await Promise.allSettled([...active.values()].map((item) => item.promise));
+ throw error;
}
return builds.map((build) => ({
diff --git a/packages/runtime/src/types.ts b/packages/runtime/src/types.ts
index 87281268..fb3c38ec 100644
--- a/packages/runtime/src/types.ts
+++ b/packages/runtime/src/types.ts
@@ -23,10 +23,7 @@ export type RuntimeRunnableCommand = {
readonly capacityMode?: "active" | "asynchronous";
};
-export type RuntimeResourceClaim = {
- readonly id: string;
- readonly limit: number;
-};
+export type RuntimeResourceClaim = import("./capacity.js").CapacityResourceClaim;
export type RuntimeWorkerRunOptions = {
readonly idlePollMs: number;
diff --git a/packages/store-sqlite/src/store.ts b/packages/store-sqlite/src/store.ts
index 210b087d..dc642115 100644
--- a/packages/store-sqlite/src/store.ts
+++ b/packages/store-sqlite/src/store.ts
@@ -9,12 +9,14 @@ import type {
CommandResult,
} from "@hypit/protocol";
import { assertBuildId } from "@hypit/protocol";
+import { capacityUnits } from "@hypit/runtime";
import type {
PendingBuildCommit,
PendingBuildSubmission,
PendingBuildStore,
BuildExecutionRequest,
BuildExecutionSnapshot,
+ BuildExecutionStop,
BuildExecutionStore,
BuildCatalog,
BuildCatalogDescriptor,
@@ -102,12 +104,16 @@ function parseOperationSnapshot(row: Row): OperationSnapshot {
readonly handle: unknown;
readonly wakeAt?: number;
readonly progress?: OperationSnapshot["progress"];
+ readonly failure?: OperationSnapshot["failure"];
+ readonly cancellationRequested?: true;
} : undefined;
const mutable = row.status === "pending"
? {
handle: pending!.handle,
...(pending!.wakeAt === undefined ? {} : { wakeAt: pending!.wakeAt }),
...(pending!.progress === undefined ? {} : { progress: pending!.progress }),
+ ...(pending!.failure === undefined ? {} : { failure: pending!.failure }),
+ ...(pending!.cancellationRequested === undefined ? {} : { cancellationRequested: true as const }),
}
: row.status === "completed"
? { completion: payload }
@@ -320,9 +326,9 @@ class SqlitePendingBuildStore implements PendingBuildStore {
INSERT INTO hypit_executions (
build_id, component_packages_json, result_location_json, created_at, wake_at,
turn_owner, turn_acquired_at, result_writer_owner, result_writer_acquired_at,
- cancel_requested, cancellation_reason,
+ stop_cause, stop_reason,
decision_outcome, decision_reason, attention_step, attention_error
- ) VALUES (?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, 0, NULL, NULL, NULL, NULL, NULL)
+ ) VALUES (?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL)
`).run(
request.build,
JSON.stringify(request.componentPackages),
@@ -361,6 +367,8 @@ class SqliteOperationStore implements OperationStore {
handle: operation.handle,
...(operation.wakeAt === undefined ? {} : { wakeAt: operation.wakeAt }),
...(operation.progress === undefined ? {} : { progress: operation.progress }),
+ ...(operation.failure === undefined ? {} : { failure: operation.failure }),
+ ...(operation.cancellationRequested === undefined ? {} : { cancellationRequested: true as const }),
})
: operation.status === "completed"
? JSON.stringify(operation.completion)
@@ -421,6 +429,8 @@ class SqliteOperationStore implements OperationStore {
handle: update.handle,
...(update.wakeAt === undefined ? {} : { wakeAt: update.wakeAt }),
...(update.progress === undefined ? {} : { progress: update.progress }),
+ ...(update.failure === undefined ? {} : { failure: update.failure }),
+ ...(update.cancellationRequested === undefined ? {} : { cancellationRequested: true as const }),
})
: update.status === "completed"
? JSON.stringify(update.completion)
@@ -434,9 +444,11 @@ class SqliteOperationStore implements OperationStore {
const mutable = update.status === "pending"
? {
status: "pending" as const,
- handle: copy(update.handle),
+ ...(update.handle === undefined ? {} : { handle: copy(update.handle) }),
...(update.wakeAt === undefined ? {} : { wakeAt: update.wakeAt }),
...(update.progress === undefined ? {} : { progress: copy(update.progress) }),
+ ...(update.failure === undefined ? {} : { failure: copy(update.failure) }),
+ ...(update.cancellationRequested === undefined ? {} : { cancellationRequested: true as const }),
}
: update.status === "completed"
? { status: "completed" as const, completion: copy(update.completion) }
@@ -649,9 +661,10 @@ function parseExecutionSnapshot(row: Row): BuildExecutionSnapshot {
...(typeof row.result_writer_owner === "string" ? {
resultWrite: { owner: row.result_writer_owner, acquiredAt: row.result_writer_acquired_at as number },
} : {}),
- ...(row.cancel_requested === 1 ? {
- cancellation: {
- ...(typeof row.cancellation_reason === "string" ? { reason: row.cancellation_reason } : {}),
+ ...(row.stop_cause === "user-cancelled" || row.stop_cause === "execution-failed" ? {
+ stop: {
+ cause: row.stop_cause,
+ ...(typeof row.stop_reason === "string" ? { reason: row.stop_reason } : {}),
},
} : {}),
...(typeof row.decision_outcome === "string" ? {
@@ -686,9 +699,9 @@ class SqliteBuildExecutionStore implements BuildExecutionStore {
INSERT INTO hypit_executions (
build_id, component_packages_json, result_location_json, created_at, wake_at,
turn_owner, turn_acquired_at, result_writer_owner, result_writer_acquired_at,
- cancel_requested, cancellation_reason,
+ stop_cause, stop_reason,
decision_outcome, decision_reason, attention_step, attention_error
- ) VALUES (?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, 0, NULL, NULL, NULL, NULL, NULL)
+ ) VALUES (?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL)
`).run(request.build, JSON.stringify(request.componentPackages), JSON.stringify(request.result), now, now);
return {
...copy(request),
@@ -734,7 +747,7 @@ class SqliteBuildExecutionStore implements BuildExecutionStore {
});
}
- async releaseTurn(build: string, owner: string, wakeAt: number): Promise<BuildExecutionSnapshot> {
+ async releaseTurn(build: string, owner: string, wakeAt: number, observedStop?: BuildExecutionStop): Promise<BuildExecutionSnapshot> {
nonNegativeInteger(wakeAt, "Execution wakeAt");
return transaction(this.#database, () => {
const row = this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(build) as Row | undefined;
@@ -742,12 +755,11 @@ class SqliteBuildExecutionStore implements BuildExecutionStore {
const current = parseExecutionSnapshot(row);
assert(current.decision === undefined, `Execution ${build} already has a decision`);
assert(current.turn?.owner === owner, `Execution ${build} is not owned by ${owner}`);
- if (current.cancellation !== undefined) return current;
this.#database.prepare(`
UPDATE hypit_executions
SET turn_owner = NULL, turn_acquired_at = NULL, wake_at = ?
WHERE build_id = ? AND turn_owner = ?
- `).run(wakeAt, build, owner);
+ `).run(current.stop !== undefined && observedStop === undefined ? Math.min(wakeAt, Date.now()) : wakeAt, build, owner);
return parseExecutionSnapshot(
this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(build) as Row,
);
@@ -764,10 +776,9 @@ class SqliteBuildExecutionStore implements BuildExecutionStore {
const row = this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(build) as Row | undefined;
if (row === undefined) throw new Error(`Execution ${build} does not exist`);
const current = parseExecutionSnapshot(row);
- const effective = current.cancellation === undefined ? outcome : "cancelled";
- const effectiveReason = effective === "cancelled"
- ? current.cancellation?.reason ?? reason
- : reason;
+ const effective = current.stop === undefined ? outcome
+ : current.stop.cause === "user-cancelled" ? "cancelled" : "failed";
+ const effectiveReason = current.stop === undefined ? reason : current.stop.reason;
if (current.decision !== undefined) {
assert(current.decision.outcome === effective && current.decision.reason === effectiveReason,
`Execution ${build} already has a different decision`);
@@ -863,20 +874,20 @@ class SqliteBuildExecutionStore implements BuildExecutionStore {
});
}
- async requestCancellation(build: string, reason?: string): Promise<BuildExecutionSnapshot> {
+ async requestStop(build: string, stop: BuildExecutionStop): Promise<BuildExecutionSnapshot> {
const now = Date.now();
return transaction(this.#database, () => {
const row = this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(build) as Row | undefined;
if (row === undefined) throw new Error(`Execution ${build} does not exist`);
const current = parseExecutionSnapshot(row);
- if (current.cancellation !== undefined) return current;
+ if (current.stop !== undefined) return current;
if (current.decision !== undefined) return current;
this.#database.prepare(`
UPDATE hypit_executions
SET wake_at = CASE WHEN turn_owner IS NULL THEN ? ELSE wake_at END,
- cancellation_reason = ?, cancel_requested = 1
+ stop_reason = ?, stop_cause = ?
WHERE build_id = ?
- `).run(now, reason ?? null, build);
+ `).run(now, stop.reason ?? null, stop.cause, build);
return parseExecutionSnapshot(
this.#database.prepare("SELECT * FROM hypit_executions WHERE build_id = ?").get(build) as Row,
);
@@ -887,6 +898,8 @@ class SqliteBuildExecutionStore implements BuildExecutionStore {
nonNegativeInteger(request.now, "Capacity acquisition time");
assert(request.resources.length > 0, "Capacity resources are empty");
const resources = [...request.resources].sort((left, right) => left.id.localeCompare(right.id));
+ assert(new Set(resources.map((resource) => resource.id)).size === resources.length, "Capacity resources repeat an id");
+ for (const resource of resources) capacityUnits(resource);
const reservation: CapacityReservation = {
build: request.build,
command: request.command,
@@ -902,12 +915,12 @@ class SqliteBuildExecutionStore implements BuildExecutionStore {
}
for (const resource of resources) {
const count = this.#database.prepare(`
- SELECT COUNT(DISTINCT capacity.rowid) AS count
+ SELECT COALESCE(SUM(COALESCE(json_extract(claim.value, '$.units'), 1)), 0) AS count
FROM hypit_capacity AS capacity, json_each(capacity.resources_json) AS claim
WHERE json_extract(claim.value, '$.id') = ?
`).get(resource.id) as Row;
assert(typeof count.count === "number", `SQLite Capacity count for ${resource.id} is invalid`);
- if (count.count >= resource.limit) {
+ if (count.count + capacityUnits(resource) > resource.limit) {
return {
status: "blocked",
availableAt: request.now + 250,
@@ -977,7 +990,10 @@ function parseCapacityReservation(row: Row): CapacityReservation {
const resources = storedResources.map((resource) => {
assert(typeof resource.id === "string", "SQLite Capacity resource has no id");
assert(typeof resource.limit === "number", `SQLite Capacity resource ${resource.id} has no limit`);
- return { id: resource.id, limit: positiveInteger(resource.limit, `resource ${resource.id} limit`) };
+ const claim = { id: resource.id, limit: positiveInteger(resource.limit, `resource ${resource.id} limit`),
+ ...(resource.units === undefined ? {} : { units: positiveInteger(resource.units as number, `resource ${resource.id} units`) }) };
+ capacityUnits(claim);
+ return claim;
});
const value = {
build: row.build_id,
@@ -1065,8 +1081,8 @@ export class SqliteRuntimeState {
turn_acquired_at INTEGER,
result_writer_owner TEXT,
result_writer_acquired_at INTEGER,
- cancel_requested INTEGER NOT NULL DEFAULT 0 CHECK (cancel_requested IN (0, 1)),
- cancellation_reason TEXT,
+ stop_cause TEXT CHECK (stop_cause IS NULL OR stop_cause IN ('user-cancelled', 'execution-failed')),
+ stop_reason TEXT,
decision_outcome TEXT CHECK (
decision_outcome IS NULL OR decision_outcome IN ('complete', 'failed', 'cancelled')
),
@@ -1115,6 +1131,8 @@ export class SqliteRuntimeState {
if (row === undefined) throw new Error(`Execution ${build} does not exist`);
const current = parseExecutionSnapshot(row);
assert(current.decision !== undefined, `Execution ${build} has no decision`);
+ const pending = this.#database.prepare("SELECT operation_id FROM hypit_operations WHERE build_id = ? AND status = 'pending' LIMIT 1").get(build);
+ assert(pending === undefined, `Build ${build} still has unsettled external work`);
this.#database.prepare("DELETE FROM hypit_capacity WHERE build_id = ?").run(build);
this.#database.prepare("DELETE FROM hypit_operations WHERE build_id = ?").run(build);
this.#database.prepare("DELETE FROM hypit_command_executions WHERE build_id = ?").run(build);
diff --git a/packages/store-sqlite/test/store.test.ts b/packages/store-sqlite/test/store.test.ts
index b48e9a7b..48fa0a84 100644
--- a/packages/store-sqlite/test/store.test.ts
+++ b/packages/store-sqlite/test/store.test.ts
@@ -173,8 +173,8 @@ test("Execution stores scheduling facts, one decision and independent operator a
assert.equal(await state.submissions.read("queued-build"), undefined);
assert.deepEqual((await state.execution.read("queued-build"))?.result, result);
- const cancelling = await state.execution.requestCancellation("queued-build", "no longer needed");
- assert.equal(cancelling.cancellation?.reason, "no longer needed");
+ const cancelling = await state.execution.requestStop("queued-build", { cause: "user-cancelled", reason: "no longer needed" });
+ assert.equal(cancelling.stop?.reason, "no longer needed");
const claimed = await state.execution.claim("worker-a", Date.now());
assert.equal(claimed?.turn?.owner, "worker-a");
const decided = await state.execution.decide("queued-build", "worker-a", "cancelled", "no longer needed");
@@ -310,3 +310,51 @@ test("shared capacity resources are acquired atomically across Builds", async ()
await rm(directory, { recursive: true, force: true });
}
});
+
+test("weighted capacity admits 4 + 2 workers atomically and survives reopening", async () => {
+ const directory = await mkdtemp(join(tmpdir(), "hypit-weighted-capacity-"));
+ const path = join(directory, "runtime.sqlite");
+ let state = new SqliteRuntimeState(path);
+ try {
+ const claim = (build: string, units: number) => state.execution.acquireCapacity({ build, command: "render",
+ resources: [{ id: "pool:render", limit: 3 }, { id: "capacity:render/browsers", limit: 6, units }], now: 100 });
+ assert.equal((await claim("four", 4)).status, "acquired");
+ assert.equal((await claim("two", 2)).status, "acquired");
+ assert.equal((await claim("one", 1)).status, "blocked");
+ assert.equal((await state.execution.listCapacity()).length, 2, "blocked requests must acquire no partial resources");
+ state.close();
+ state = new SqliteRuntimeState(path);
+ assert.equal((await claim("one", 1)).status, "blocked");
+ const restored = await state.execution.listCapacity();
+ assert.equal(restored.find((item) => item.build === "four")?.resources.find((item) => item.id.endsWith("/browsers"))?.units, 4);
+ assert.equal(restored.find((item) => item.build === "two")?.resources.find((item) => item.id.endsWith("/browsers"))?.units, 2);
+ await state.execution.releaseCapacity("two", "render");
+ assert.equal((await claim("three", 3)).status, "blocked");
+ assert.equal((await claim("one", 1)).status, "acquired");
+ await assert.rejects(claim("impossible", 7), /needs 7 units/);
+ } finally { state.close(); await rm(directory, { recursive: true, force: true }); }
+});
+
+
+test("stop requests preserve their first cause, wake an unaware turn, and retain polling delays", async () => {
+ const directory = await mkdtemp(join(tmpdir(), "hypit-stop-request-"));
+ const state = new SqliteRuntimeState(join(directory, "runtime.sqlite"));
+ try {
+ await state.execution.create({ build: "stopping", componentPackages: [], result: resultLocation });
+ await state.execution.claim("worker");
+ const stop = { cause: "execution-failed" as const, reason: "original failure" };
+ await state.execution.requestStop("stopping", stop);
+ assert.deepEqual((await state.execution.requestStop("stopping", { cause: "user-cancelled", reason: "later" })).stop, stop);
+ const wakeAt = Date.now() + 60_000;
+ const unaware = await state.execution.releaseTurn("stopping", "worker", wakeAt);
+ assert.ok(unaware.wakeAt <= Date.now(), "a stop received during execution must be processed promptly");
+ await state.execution.claim("worker");
+ const settling = await state.execution.releaseTurn("stopping", "worker", wakeAt, stop);
+ assert.equal(settling.wakeAt, wakeAt, "a turn that already handled stop must respect its next poll time");
+ await state.execution.requestStop("stopping", { cause: "user-cancelled" });
+ assert.equal((await state.execution.read("stopping"))?.wakeAt, wakeAt);
+ await state.execution.claim("worker", wakeAt);
+ assert.deepEqual((await state.execution.decide("stopping", "worker", "cancelled", "later")).decision,
+ { outcome: "failed", reason: "original failure" });
+ } finally { state.close(); await rm(directory, { recursive: true, force: true }); }
+});
diff --git a/packages/video-cli/README.md b/packages/video-cli/README.md
index cf9f65cd..cfaf4d63 100644
--- a/packages/video-cli/README.md
+++ b/packages/video-cli/README.md
@@ -44,7 +44,7 @@ extracting 16 kHz mono speech audio with ffmpeg). `measure` counts a Segment's p
delivery policy and prints the seconds to write as the literal `duration`; it opens no Profile and
spends nothing. `--runtime <profile>` names the Profile; otherwise the project's `hypit runtime use`
selection is read. Anything the Author Graph declares as an output is a Build, however quickly it
-comes back: pictures, clips and the spoken A-roll (`@hypit/mimo-tts`) carry the identity of the Source
+comes back: pictures, clips and accepted voice references (`@hypit/mimo-speech`) carry the identity of the Source
that produced them, so they are declared in the Source and go through `plan` and `build`. To hear a
voice or learn a passage's real length before authoring the rest, build a Run whose target is that
speech output and reuse it as a Candidate.