Clone any viral video with AI agents. Not just a script, the whole workflow: swap the face, the words, the B-roll, ship 100 variants in one command, and get your 100M views.
TypeScript agentic-aiaiai-agentsai-videocompilerdslffmpeggenerative-aillmmarkup-languagemonorepoplugin-systemprogramming-languagetext-to-videotypescriptvideovideo-automationvideo-clonevideo-editingvideo-generation
feat(runtime): render selected ranges with weighted capacity
kashorinefc8bd56e79a
diff --git a/packages/cli/src/commands/execution.ts b/packages/cli/src/commands/execution.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mdindex 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 theplanning 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 artifactbytes 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.tsindex 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.tsindex 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.tsindex 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 iitem.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.tsindex 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.tsindex 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.tsindex 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 callerconst [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 terminalassert.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.mdindex 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` andoptional 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 thesame handler in a disposable authoring execution with no Build, Result or recoverable Operation. It is adiff --git a/packages/endpoint-kit/src/index.ts b/packages/endpoint-kit/src/index.tsindex 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): Enid: `capacity:${options.pool}/${capacity}`,limit: exactConcurrency,},+ ...(capability.resources ?? []),],},};diff --git a/packages/hyperframes/src/document.ts b/packages/hyperframes/src/document.tsindex 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.tsindex 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.mdindex 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 packageowns the byte-level implementations of the eight current operations:diff --git a/packages/media-execution/src/execute.ts b/packages/media-execution/src/execute.tsindex 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): ProjectSpeechEvidenceAudioNeefunction 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 5bbfd30b..80c120a3 100644--- a/packages/media/src/index.ts+++ b/packages/media/src/index.ts@@ -11,3 +11,5 @@ export { compositableSurfaceSchema, fontArtifactSchema, fontStackSchema, mediaInexport { 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.tsindex 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.tsindex 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: CreateAwsLambdaHyperfoutputKey: 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: CreateAwsLambdaHyperftry {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: CreateAwsLambdaHyperfregion,});} 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: CreateAwsLambdaHyperfunit: "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.tsindex 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", aconst 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.mdindex 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 theResource 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 typedSurface it decodes the exact bytes and checks declared dimensions, still/frame timing, SDR/sRGB andopaque/straight-alpha facts. These checks validate the typed rendering input; they do not createcontent 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 neverrenders program audio; `@hypit/provider-media-local` separately prepares `TimelineAudio` and muxesthe 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 pinnedHyperFrames CLI's `browser ensure`; its probe resolves and starts that browser and checksffprobe 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.+```tsconst 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 foruntrusted documents or community renderer implementations.diff --git a/packages/provider-hyperframes-local/package.json b/packages/provider-hyperframes-local/package.jsonindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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("&", "&").replaceAll(""", '"').replaceAll("<", "<").replaceAll(">", ">");+ };+ 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.tsnew file mode 100644index 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.mdindex 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 moddefault the Endpoint instance is the shared-resource identity. Set Profile `pool` only when multipleEndpoint instances really use the same account or deployment quota. Another Provider is independentunless 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-resourcelimits, 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 Runtimeservice packages and selections. The `.svml` Module Closure separately contains only the modelManifests 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.tsindex 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.tsindex 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 bassert.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 massert.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 massert.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.tsindex 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 siconst 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.mdindex 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 derendering 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 acrossconfigured Chrome workers, emits a silent MP4 and rejects output unless ffprobe proves one H.264stream 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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 anotherassert.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.tsindex 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 } frimport 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.mdindex 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 odefault. A Profile `pool` is only for instances that really share one account, deployment or computequota; exact-model limits may narrow it further. Build identity is not a capacity resource and createsno 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 theproject's `.hypit/results` directory, with no cloud account or service. Runtime Local opens that defaultdiff --git a/packages/runtime-local/src/config.ts b/packages/runtime-local/src/config.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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", acapability: { 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.tsindex 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 incremawait 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.mdindex 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 execThe scheduler never changes graph meaning. Targets and candidates are fixed before execution, andresource 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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_executionsSET 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_executionsSET 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 countFROM hypit_capacity AS capacity, json_each(capacity.resources_json) AS claimWHERE 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.tsindex 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 aassert.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.mdindex 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 pdelivery policy and prints the seconds to write as the literal `duration`; it opens no Profile andspends 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 Sourcethat produced them, so they are declared in the Source and go through `plan` and `build`. To hear avoice or learn a passage's real length before authoring the rest, build a Run whose target is thatspeech output and reuse it as a Candidate.