@hypit/hypit 0.1.3 → 0.1.5

package/packages/runtime-local/src/host.ts

@@ -5,6 +5,7 @@ import type {
 } from "@hypit/runtime-host-node";
 import { hypitHostStateRoot } from "@hypit/runtime-host-node";
 import { resolve } from "node:path";
+import { superviseBuilds } from "./supervisor.js";
 
 import {
   createRuntimeControlFromConfig,
@@ -82,8 +83,8 @@ export async function openLocalRuntimeHost(
       },
       programs: {
         up: async (programOptions) => await bringManagedProgramsUp(profile, { ...programOptions, packageRoot, ...distribution }),
-        down: async () => await takeManagedProgramsDown(profile, { packageRoot, ...distribution }),
-        report: async () => await reportManagedPrograms(profile, { packageRoot, ...distribution }),
+        down: async (scope) => await takeManagedProgramsDown(profile, { ...scope, packageRoot, ...distribution }),
+        report: async (scope) => await reportManagedPrograms(profile, { ...scope, packageRoot, ...distribution }),
       },
     };
   };
@@ -102,7 +103,7 @@ export async function openLocalRuntimeHost(
       };
     },
     controller,
-    createRuntime: async () => await createRuntimeFromConfig(profile, { packageRoot: basePackageRoot, ...distribution }),
+    createRuntime: async (scope) => await createRuntimeFromConfig(profile, { packageRoot: basePackageRoot, ...distribution, ...scope }),
     openControl: async (options) => await createRuntimeControlFromConfig(profile, {
       packageRoot: basePackageRoot,
       ...distribution,
@@ -121,16 +122,19 @@ export async function openLocalRuntimeHost(
       packageRoot: basePackageRoot,
       ...distribution,
       ...(options?.onProgress === undefined ? {} : { onProgress: options.onProgress }),
+      ...(options?.endpoints === undefined ? {} : { endpoints: options.endpoints }),
     }),
     preflight: async (options) => await preflightRuntimeConfig(profile, {
       packageRoot: basePackageRoot,
       ...distribution,
       ...(options?.capabilities === undefined ? {} : { capabilities: options.capabilities }),
+      ...(options?.endpoints === undefined ? {} : { endpoints: options.endpoints }),
     }),
     doctor: async (options) => await doctorRuntimeConfig(profile, {
       packageRoot: basePackageRoot,
       ...distribution,
       ...(options?.capabilities === undefined ? {} : { capabilities: options.capabilities }),
+      ...(options?.endpoints === undefined ? {} : { endpoints: options.endpoints }),
     }),
     providers: async (capabilities) => await describeRuntimeConfigProviders(profile, capabilities, {
       packageRoot: basePackageRoot,
@@ -140,34 +144,50 @@ export async function openLocalRuntimeHost(
       packageRoot: basePackageRoot,
       ...distribution,
     }),
-    invoke: async (need, resources) => await invokeRuntimeConfigNeed(profile, need, resources, {
+    invoke: async (need, resources, observation) => await invokeRuntimeConfigNeed(profile, need, resources, {
       packageRoot: basePackageRoot,
       ...distribution,
+      ...observation,
     }),
     openTransientExecution: async () => await openTransientRuntimeConfigExecution(profile, {
       packageRoot: basePackageRoot,
       ...distribution,
     }),
-    runWorker: async (readyFile, owner) => {
-      let runtime: Awaited<ReturnType<typeof createRuntimeFromConfig>> | undefined;
+    runWorker: async (readyFile, owner, execution) => {
       const abort = new AbortController();
-      const stop = (): void => abort.abort();
+      const stop = (): void => { abort.abort(); };
+      // A Build never survives loss of its supervisor by silently changing code owners.
+      const disconnected = (): never => process.exit(1);
+      const message = (value: unknown): void => {
+        if (typeof value === "object" && value !== null && "kind" in value && value.kind === "stop-execution") stop();
+      };
       process.once("SIGTERM", stop);
       process.once("SIGINT", stop);
+      if (execution !== undefined) {
+        process.once("disconnect", disconnected);
+        process.on("message", message);
+      }
       try {
-        runtime = await createRuntimeFromConfig(profile, {
-          packageRoot: basePackageRoot,
-          ...distribution,
-        });
-        await runtime.work({
-          idlePollMs: 250,
-          signal: abort.signal,
-          ready: async () => await markRuntimeProcessReady(readyFile, owner),
-        });
+        if (execution !== undefined) {
+          const { executeBuilds } = await import("./executor.js");
+          await executeBuilds(execution.dataRoot, abort.signal);
+        } else {
+          const paths = await resolveRuntimeConfigPaths(profile, { packageRoot: basePackageRoot, ...distribution });
+          await superviseBuilds({
+            profile, dataRoot: paths.dataRoot, readyFile, owner,
+            launch: hostOptions.workerLaunch, signal: abort.signal,
+            ready: async () => await markRuntimeProcessReady(readyFile, owner),
+          });
+        }
+      } catch (error) {
+        if (execution !== undefined && process.connected) process.send?.({ kind: "execution-error", message: error instanceof Error ? error.message : String(error) });
+        throw error;
       } finally {
         process.removeListener("SIGTERM", stop);
         process.removeListener("SIGINT", stop);
-        await runtime?.close();
+        process.removeListener("disconnect", disconnected);
+        process.removeListener("message", message);
+        if (execution !== undefined && process.connected) process.disconnect();
       }
     },
   };

package/packages/runtime-local/src/log.ts

@@ -0,0 +1,48 @@
+import { createReadStream } from "node:fs";
+import { appendFile, mkdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { readExecutionLog } from "@hypit/runtime";
+import type { ExecutionLogEvent, ExecutionLogRecord, ExecutionLogView } from "@hypit/runtime";
+
+export type LocalExecutionLogs = {
+  record(build: string, command: string, event: ExecutionLogEvent): Promise<void>;
+  open(build: string): Promise<AsyncIterable<Uint8Array> | undefined>;
+  read(build: string, lines: number): Promise<ExecutionLogView | undefined>;
+};
+
+/** Append-only Build evidence. Queues coordinate writes, not execution or historical lookup. */
+export function fileExecutionLogs(workDirectory: (build: string) => string): LocalExecutionLogs {
+  const pending = new Map<string, Promise<void>>();
+  const failures = new Map<string, unknown>();
+  const path = (build: string) => join(workDirectory(build), "execution.jsonl");
+  const open = async (build: string): Promise<AsyncIterable<Uint8Array> | undefined> => {
+    await pending.get(build);
+    if (failures.has(build)) throw new Error(`Build ${build} execution log could not be saved`, { cause: failures.get(build) });
+    try { await stat(path(build)); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined; throw error; }
+    // Open only when the Repository consumes the stream, so a failed destination opens no source handle.
+    return (async function* () { yield* createReadStream(path(build)); })();
+  };
+  return {
+    async record(build, command, event) {
+      const record: ExecutionLogRecord = { ...event, format: "hypit.execution-log@1", time: Date.now(), command };
+      const write = (pending.get(build) ?? Promise.resolve()).then(async () => {
+        await mkdir(workDirectory(build), { recursive: true });
+        await appendFile(path(build), `${JSON.stringify(record)}\n`, "utf8");
+      }).catch((error) => { failures.set(build, error); });
+      pending.set(build, write);
+      await write;
+      if (pending.get(build) === write) pending.delete(build);
+    },
+    open,
+    async read(build, lines) {
+      const chunks = await open(build);
+      try { return chunks === undefined ? undefined : await readExecutionLog(chunks, lines); }
+      catch (error) {
+        // The Result may have finished and cleaned work between opening an active view and reading it.
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+        throw error;
+      }
+    },
+  };
+}

package/packages/runtime-local/src/programs.ts

@@ -36,6 +36,7 @@ export type ManagedProgramReport = {
 export type ManagedProgramProgress = {
   readonly id: string;
   readonly phase: "checking" | "installing" | "starting" | "waiting" | "ready";
+  readonly logPath?: string;
 };
 
 export type ManagedProgramOptions = LoadRuntimeConfigOptions & {
@@ -45,6 +46,7 @@ export type ManagedProgramOptions = LoadRuntimeConfigOptions & {
   readonly onProgress?: (event: ManagedProgramProgress) => void;
   /** When present, operate only programs backing at least one demanded capability. */
   readonly capabilities?: readonly CapabilityRef[];
+  readonly endpoints?: readonly string[];
 };
 
 function independentPrograms(programs: readonly { instance: string; program: ManagedProgram }[]) {
@@ -97,24 +99,31 @@ async function readPid(root: string, program: ManagedProgram): Promise<number |
   }
 }
 
-function run(root: string, command: ManagedProgramCommand): Promise<{ ok: boolean; detail: string }> {
-  return new Promise((resolve) => {
-    const child = spawn(command.command, [...command.args], {
-      cwd: command.cwd ?? root,
-      env: { ...process.env, ...command.env },
-      shell: false,
-      windowsHide: true,
-      stdio: ["ignore", "pipe", "pipe"],
+async function run(root: string, command: ManagedProgramCommand, logPath: string): Promise<{ ok: boolean; detail: string }> {
+  const log = await open(logPath, "a+");
+  try {
+    const offset = (await log.stat()).size;
+    const exit = await new Promise<{ code: number | null; error?: string }>((resolve) => {
+      const child = spawn(command.command, [...command.args], {
+        cwd: command.cwd ?? root,
+        env: { ...process.env, ...command.env },
+        shell: false,
+        windowsHide: true,
+        stdio: ["ignore", log.fd, log.fd],
+      });
+      child.on("error", (error) => resolve({ code: null, error: error.message }));
+      child.on("close", (code) => resolve({ code }));
     });
-    let output = "";
-    child.stdout.on("data", (chunk: Buffer) => { output += chunk.toString(); });
-    child.stderr.on("data", (chunk: Buffer) => { output += chunk.toString(); });
-    child.on("error", (error) => resolve({ ok: false, detail: error.message }));
-    child.on("close", (code) => resolve({
-      ok: code === 0,
-      detail: code === 0 ? "" : (output.trim().split("\n").at(-1) ?? `exited ${code}`),
-    }));
-  });
+    if (exit.code === 0) return { ok: true, detail: "" };
+    const end = (await log.stat()).size;
+    const start = Math.max(offset, end - 8192);
+    const tail = Buffer.alloc(end - start);
+    const { bytesRead } = await log.read(tail, 0, tail.length, start);
+    const line = tail.subarray(0, bytesRead).toString().trim().split(/\r?\n/u).at(-1);
+    return { ok: false, detail: exit.error ?? (line || `exited ${exit.code}`) };
+  } finally {
+    await log.close();
+  }
 }
 
 /**
@@ -254,20 +263,23 @@ async function bringUp(
   }
 
   let installed = false;
+  const logPath = join(directory(root, program), "program.log");
+  const installLogPath = join(directory(root, program), "install.log");
   if (program.installation !== undefined) {
     const installation = await program.installation.probe();
-    if (installation.state !== "ready") {
-      onProgress?.({ id: program.id, phase: "installing" });
+    if (installation.state !== "ready" || program.installation.prepareBeforeStart === true) {
       await mkdir(directory(root, program), { recursive: true });
+      await rotateLog(installLogPath);
+      onProgress?.({ id: program.id, phase: "installing", logPath: installLogPath });
       for (const command of program.installation.commands) {
-        const result = await run(root, command);
+        const result = await run(root, command, installLogPath);
         if (!result.ok) {
-          return { ...base, action: "unchanged", state: initial, detail: `${command.command} failed: ${result.detail}` };
+          return { ...base, action: "unchanged", state: initial, logPath: installLogPath, detail: `${command.command} failed: ${result.detail}` };
         }
       }
       const after = await program.installation.probe();
       if (after.state !== "ready") {
-        return { ...base, action: "unchanged", state: initial, detail: `installation is ${after.state}: ${after.detail}` };
+        return { ...base, action: "unchanged", state: initial, logPath: installLogPath, detail: `installation is ${after.state}: ${after.detail}` };
       }
       installed = true;
     }
@@ -276,12 +288,16 @@ async function bringUp(
     // Nothing to keep running: installation was the whole job.
     const state = await program.probe();
     if (state.state === "ready") onProgress?.({ id: program.id, phase: "ready" });
-    return { ...base, action: state.state === "ready" && installed ? "installed" : "unchanged", state };
+    return {
+      ...base,
+      action: state.state === "ready" && installed ? "installed" : "unchanged",
+      state,
+      ...(installed ? { logPath: installLogPath } : {}),
+    };
   }
 
-  onProgress?.({ id: program.id, phase: "starting" });
+  onProgress?.({ id: program.id, phase: "starting", logPath });
   await mkdir(directory(root, program), { recursive: true });
-  const logPath = join(directory(root, program), "program.log");
   await rotateLog(logPath);
   const log = await open(logPath, "a");
   try {

package/packages/runtime-local/src/result-writer.ts

@@ -150,7 +150,9 @@ export function createLocalResultWriter(
               ...(operation.failure === undefined ? {} : { failure: operation.failure }),
             };
           });
+          const executionLog = await options.executionLogs?.open(execution.build);
           await reopened.writer.finish({
+            ...(executionLog === undefined ? {} : { executionLog }),
             operations,
             outcome: execution.decision.outcome,
             ...(execution.decision.reason === undefined ? {} : { failure: execution.decision.reason }),

package/packages/runtime-local/src/runtime.ts

@@ -153,6 +153,7 @@ export async function createLocalRuntime(
     validators,
   });
   const resultWriter = createLocalResultWriter({
+    ...(options.executionLogs === undefined ? {} : { executionLogs: options.executionLogs }),
     buildStore: options.buildStore,
     operationStore: options.operationStore,
     commandExecutionStore: options.commandExecutionStore,
@@ -165,6 +166,8 @@ export async function createLocalRuntime(
     openBuildResultRepository,
   });
   const worker = createDurableLocalWorker(driver, {
+    ...(options.executionBuild === undefined ? {} : { executionBuild: options.executionBuild }),
+    ...(options.executionLogs === undefined ? {} : { executionLogs: options.executionLogs }),
     stores: {
       builds: options.buildStore,
       operations: options.operationStore,
@@ -174,7 +177,6 @@ export async function createLocalRuntime(
     resourceStore: options.resourceStore,
     ...(options.resourceStoreForBuild === undefined ? {} : { resourceStoreForBuild: options.resourceStoreForBuild }),
     openBuildResultRepository,
-    ...(options.assertEnvironment === undefined ? {} : { assertEnvironment: options.assertEnvironment }),
     installComponentPackages,
     resultWriter,
   });
@@ -183,7 +185,9 @@ export async function createLocalRuntime(
     endpoints: options.endpoints ?? [],
   });
   const control = createLocalRuntimeControl({
+    ...(options.executionLogs === undefined ? {} : { executionLogs: options.executionLogs }),
     buildStore: options.buildStore,
+    commandExecutionStore: options.commandExecutionStore,
     buildCatalog,
     operationStore: options.operationStore,
     executionStore: options.executionStore,
@@ -256,6 +260,7 @@ export async function createLocalRuntime(
     const resultRequest = request.result;
     const executionRequest = {
       build: request.id,
+      ...(options.executionContext === undefined ? {} : { context: options.executionContext }),
       componentPackages: [...new Set(request.componentPackages ?? [])].sort(),
       result: resultRequest.repository,
     } as const;
@@ -268,6 +273,7 @@ export async function createLocalRuntime(
       try {
         const publishedOutputs = request.catalog.publishedOutputs.map((published) => ({
           name: published.name,
+          ...(published.displayName === undefined ? {} : { displayName: published.displayName }),
           output: published.ref.id,
         }));
         const names = new Map<string, string>();
@@ -291,6 +297,7 @@ export async function createLocalRuntime(
           targets,
           publishedOutputs,
           ...(resultRequest.forwards === undefined ? {} : { forwards: resultRequest.forwards }),
+          ...(resultRequest.resourceReferences === undefined ? {} : { resourceReferences: resultRequest.resourceReferences }),
         });
       } finally {
         await opened.close?.();
@@ -329,11 +336,8 @@ export async function createLocalRuntime(
     ...credentialControl,
     ...resultWriter,
     build: runBuild,
-    async workOnce() {
-      return await worker.runOnce();
-    },
-    async work(workOptions) {
-      await worker.run(workOptions);
+    async workOnce(workOptions) {
+      return await worker.runOnce(workOptions);
     },
     close() {
       return options.close?.();

package/packages/runtime-local/src/supervisor.ts

@@ -0,0 +1,142 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { setTimeout as pause } from "node:timers/promises";
+import { SqliteRuntimeState } from "@hypit/store-sqlite";
+import type { RuntimeWorkerLaunch } from "./worker-process.js";
+import { createRuntimeResultWriter, localExecutionContext, readRuntimeWorkerOptions, statePath } from "./config.js";
+
+type Carrier = { readonly child: ChildProcess; readonly builds: Set<string>; readonly ready: Promise<void>;
+  done: Promise<void>; exited: boolean; stopping: boolean; completed: number; rssBytes: number };
+
+/** Owns execution-carrier lifetimes, not project implementations. */
+export async function superviseBuilds(options: {
+  readonly profile: string;
+  readonly dataRoot: string;
+  readonly readyFile: string;
+  readonly owner: string;
+  readonly launch: RuntimeWorkerLaunch;
+  readonly signal: AbortSignal;
+  readonly ready: () => Promise<void>;
+}): Promise<void> {
+  const { executionMemoryMb } = await readRuntimeWorkerOptions(options.profile);
+  const memoryBudget = executionMemoryMb * 1024 * 1024;
+  const state = new SqliteRuntimeState(statePath(options.dataRoot));
+  const carriers = new Set<Carrier>();
+  let accepting: Carrier | undefined;
+  const considerRetirement = (carrier: Carrier): void => {
+    // Retire accumulated completed work. Live work alone is not a reason to multiply
+    // processes, and a cold process above the budget must still be able to accept work.
+    if (accepting === carrier && carrier.completed > 0 && carrier.rssBytes >= memoryBudget) {
+      accepting = undefined;
+      process.stderr.write(`Executor ${carrier.child.pid}: draining at ${Math.ceil(carrier.rssBytes / 1024 / 1024)} MiB; active Builds continue in place\n`);
+    }
+  };
+  const finishInterrupted = async (build: string, reason: string): Promise<void> => {
+    const current = await state.execution.read(build);
+    if (current === undefined) return;
+    const decided = await state.execution.interrupt(build, reason);
+    try {
+      const writer = createRuntimeResultWriter(options.dataRoot, localExecutionContext(current.context));
+      try { await writer.completeResult(decided); }
+      finally { await writer.close(); }
+    } catch (error) {
+      await state.execution.setAttention(build, { step: "result", error: error instanceof Error ? error.message : String(error) });
+    }
+  };
+  const launch = (): Carrier => {
+    const child = spawn(options.launch.command, [
+      ...options.launch.args, "_worker", options.profile,
+      "--ready-file", options.readyFile, "--worker-owner", options.owner,
+      "--execution-root", options.dataRoot,
+    ], {
+      stdio: ["ignore", "inherit", "inherit", "ipc"], windowsHide: true,
+      // Node's CommonJS evaluation callback needs this for scoped dynamic import().
+      env: { ...process.env, NODE_OPTIONS: [process.env.NODE_OPTIONS, "--experimental-vm-modules"].filter(Boolean).join(" ") },
+    });
+    let detail: string | undefined;
+    let ready!: () => void;
+    let rejectReady!: (error: Error) => void;
+    let reports = Promise.resolve();
+    const carrier: Carrier = { child, builds: new Set(), ready: new Promise((resolve, reject) => { ready = resolve; rejectReady = reject; }),
+      done: Promise.resolve(), exited: false, stopping: false, completed: 0, rssBytes: 0 };
+    child.on("message", (message: unknown) => {
+      if (typeof message !== "object" || message === null || !("kind" in message)) return;
+      if (message.kind === "executor-ready") ready();
+      if ("rssBytes" in message && typeof message.rssBytes === "number" && Number.isFinite(message.rssBytes)) {
+        carrier.rssBytes = message.rssBytes;
+        considerRetirement(carrier);
+      }
+      if (message.kind === "execution-error" && "message" in message && typeof message.message === "string") detail = message.message;
+      if (message.kind === "build-finished" && "build" in message && typeof message.build === "string") {
+        const build = message.build;
+        reports = reports.then(async () => {
+          if (!carrier.builds.has(build)) throw new Error(`Unassigned Build ${build} reported completion`);
+          if ("error" in message && typeof message.error === "string") await finishInterrupted(build, message.error);
+          carrier.builds.delete(build);
+          carrier.completed++;
+          considerRetirement(carrier);
+        });
+        void reports.catch((error) => { detail = String(error); child.kill(); });
+      }
+    });
+    const exited = new Promise<void>((resolve) => {
+      child.once("error", (error) => { detail = error.message; rejectReady(error); });
+      child.once("close", (code, signal) => {
+        carrier.exited = true;
+        detail ??= `Build executor exited (${signal ?? code ?? "unknown"}); create a new Build to continue`;
+        rejectReady(new Error(detail)); resolve();
+      });
+    });
+    carrier.done = exited.then(async () => {
+      await reports.catch(() => undefined);
+      for (const build of carrier.builds) await finishInterrupted(build, detail!);
+    }).finally(() => {
+      carriers.delete(carrier);
+      if (accepting === carrier) accepting = undefined;
+    });
+    void carrier.done.catch((error) => { process.stderr.write(`Executor: ${String(error)}\n`); });
+    carriers.add(carrier);
+    return carrier;
+  };
+  try {
+    await state.execution.reclaimResultWrites();
+    for (const execution of await state.execution.list()) {
+      if (execution.decision === undefined && execution.startedAt !== undefined) {
+        await finishInterrupted(execution.build, "Build executor was lost; its code context is gone. Create a new Build to continue");
+      } else if (execution.decision !== undefined && execution.attention === undefined) {
+        await state.execution.setAttention(execution.build, { step: "result", error: "Result writing was interrupted; run hypit result finish <build-id>" });
+      }
+    }
+    await state.execution.reclaimActionCapacity();
+    await options.ready();
+    while (!options.signal.aborted) {
+      for (const carrier of carriers) {
+        if (carrier.builds.size !== 0 || carrier.stopping || carrier.exited) continue;
+        carrier.stopping = true;
+        if (carrier.child.connected) carrier.child.send({ kind: "stop-execution" }, () => undefined);
+        if (accepting === carrier) accepting = undefined;
+      }
+      for (const build of await state.execution.listUnstarted()) {
+        if (options.signal.aborted) break;
+        accepting ??= launch();
+        const carrier = accepting;
+        await carrier.ready;
+        if (carrier.exited) break;
+        if (accepting !== carrier) continue;
+        await state.execution.start(build);
+        carrier.builds.add(build);
+        try {
+          await new Promise<void>((resolve, reject) => carrier.child.send({ kind: "start-build", build }, (error) => error ? reject(error) : resolve()));
+        } catch (error) {
+          await finishInterrupted(build, `Build dispatch failed: ${String(error)}; create a new Build to continue`);
+          carrier.builds.delete(build);
+          if (accepting === carrier) accepting = undefined;
+        }
+      }
+      await pause(100, undefined, { signal: options.signal }).catch((error) => { if (!options.signal.aborted) throw error; });
+    }
+  } finally {
+    for (const { child } of carriers) if (child.connected) child.send({ kind: "stop-execution" }, () => undefined);
+    await Promise.allSettled([...carriers].map(({ done }) => done));
+    state.close();
+  }
+}

package/packages/runtime-local/src/types.ts

@@ -21,13 +21,16 @@ import type {
 } from "@hypit/runtime-host-node";
 
 export type CreateLocalRuntimeOptions = {
+  /** Already assigned by the local coordinator. Embeddings omit this and start fresh work. */
+  readonly executionBuild?: string;
+  readonly executionContext?: import("@hypit/protocol").CanonicalValue;
+  readonly executionLogs?: import("./log.js").LocalExecutionLogs;
   readonly buildStore: BuildStore;
   /** Host presentation metadata only; never part of Core state. */
   readonly buildCatalog: BuildCatalog;
   readonly operationStore: OperationStore;
   /** Durable receipt boundary: one immediate Command is never invoked twice for one Build. */
   readonly commandExecutionStore: import("@hypit/runtime").CommandExecutionStore;
-  readonly assertEnvironment?: () => Awaitable<void>;
   readonly executionStore: import("@hypit/runtime").BuildExecutionStore;
   readonly removeActiveBuild: (build: string) => Awaitable<BuildCompletion>;
   /** Atomic submission boundary: external preparation is never a claimable partial Build. */
@@ -49,7 +52,9 @@ export type CreateLocalRuntimeOptions = {
 };
 
 export type CreateLocalRuntimeControlOptions = {
+  readonly executionLogs?: import("./log.js").LocalExecutionLogs;
   readonly buildStore: BuildStore;
+  readonly commandExecutionStore: import("@hypit/runtime").CommandExecutionStore;
   readonly buildCatalog?: BuildCatalog;
   readonly operationStore: OperationStore;
   readonly executionStore: BuildExecutionStore;
@@ -59,6 +64,7 @@ export type CreateLocalRuntimeControlOptions = {
 };
 
 export type CreateLocalResultWriterOptions = {
+  readonly executionLogs?: import("./log.js").LocalExecutionLogs;
   readonly buildStore: BuildStore;
   readonly operationStore: OperationStore;
   readonly commandExecutionStore: import("@hypit/runtime").CommandExecutionStore;
@@ -83,7 +89,8 @@ export type LocalBuildOptions = Parameters<RuntimeHostExecution["build"]>[1];
 export type LocalBuildSubmission = RuntimeHostBuildSubmission;
 
 export type LocalRuntime = RuntimeHostExecution & {
-  workOnce(): Promise<BuildExecutionSnapshot | BuildCompletion | undefined>;
+  /** Advance owned or unstarted work only. Process lifecycle belongs to the Runtime Host. */
+  workOnce(options?: { readonly build?: string; readonly hydrated?: () => void }): Promise<BuildExecutionSnapshot | BuildCompletion | undefined>;
 };
 
 /** Active execution control that never opens the selected ResourceStore. */