@hypit/hypit 0.0.1 → 0.1.1

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

@@ -0,0 +1,441 @@
+import { spawn } from "node:child_process";
+import { mkdir, open, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+
+import type { CapabilityRef } from "@hypit/protocol";
+import type { ManagedProgram, ManagedProgramCommand, ManagedProgramState } from "@hypit/runtime-kit";
+
+import { declaredManagedPrograms } from "./config.js";
+import type { LoadRuntimeConfigOptions } from "./config.js";
+import { processAlive, stopProcessTree } from "./process-control.js";
+import { processErrorLogPath } from "./process-logs.js";
+
+export type ManagedProgramAction =
+  | "already-running"
+  | "installed"
+  | "started"
+  | "stopped"
+  | "not-ours"
+  | "nothing-to-stop"
+  | "unchanged";
+
+export type ManagedProgramReport = {
+  readonly id: string;
+  /** The configured Endpoint that declared this external program. */
+  readonly endpoint: string;
+  /** What this call did. Absent when it was only asked to look. */
+  readonly action?: ManagedProgramAction;
+  readonly state: ManagedProgramState;
+  /** Why the action fell short. Never a copy of what `state` already says. */
+  readonly detail?: string;
+  readonly logPath?: string;
+  readonly pid?: number;
+};
+
+export type ManagedProgramProgress = {
+  readonly id: string;
+  readonly phase: "checking" | "installing" | "starting" | "waiting" | "ready";
+};
+
+export type ManagedProgramOptions = LoadRuntimeConfigOptions & {
+  /** How long to wait for a started program to answer its probe. Default 300000. */
+  readonly maxWaitMs?: number;
+  /** Human-facing progress only; never changes program selection or lifecycle. */
+  readonly onProgress?: (event: ManagedProgramProgress) => void;
+  /** When present, operate only programs backing at least one demanded capability. */
+  readonly capabilities?: readonly CapabilityRef[];
+};
+
+function independentPrograms(programs: readonly { instance: string; program: ManagedProgram }[]) {
+  const owners = new Map<string, string>();
+  for (const item of programs) {
+    const found = owners.get(item.program.id);
+    if (found !== undefined) {
+      throw new Error(
+        `Endpoints ${found} and ${item.instance} declare the same Managed Program ${item.program.id}; `
+        + "each Endpoint must declare its own lifecycle identity",
+      );
+    }
+    owners.set(item.program.id, item.instance);
+  }
+  return programs;
+}
+
+function directory(root: string, program: ManagedProgram): string {
+  return program.stateRoot ?? join(root, "programs", program.id);
+}
+
+const LOG_ROTATE_BYTES = 10 * 1024 * 1024;
+
+function nodeError(error: unknown, code: string): boolean {
+  return error instanceof Error && "code" in error && error.code === code;
+}
+
+async function rotateLog(path: string): Promise<void> {
+  let size = 0;
+  try {
+    size = (await stat(path)).size;
+  } catch (error) {
+    if (!nodeError(error, "ENOENT")) throw error;
+  }
+  if (size <= LOG_ROTATE_BYTES) return;
+  const previous = `${path}.previous`;
+  await rm(previous, { force: true });
+  await rename(path, previous);
+}
+
+async function readPid(root: string, program: ManagedProgram): Promise<number | undefined> {
+  try {
+    const text = await readFile(join(directory(root, program), "process.pid"), "utf8");
+    const pid = Number.parseInt(text.trim(), 10);
+    if (!Number.isSafeInteger(pid) || pid < 1) throw new Error(`External program ${program.id} pid file is invalid`);
+    return pid;
+  } catch (error) {
+    if (nodeError(error, "ENOENT")) return undefined;
+    throw error;
+  }
+}
+
+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"],
+    });
+    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}`),
+    }));
+  });
+}
+
+/**
+ * Poll until the program answers as itself. `down` is expected while it loads
+ * weights; `mismatch` is not, and stops the wait — a program that is answering
+ * with another identity will not become the right one by waiting.
+ */
+/** POSIX: its own session, and stdio already pointed at the log. */
+async function startDetached(start: ManagedProgramCommand, root: string, logFd: number): Promise<number | undefined> {
+  const child = spawn(start.command, [...start.args], {
+    cwd: start.cwd ?? root,
+    env: { ...process.env, ...start.env },
+    shell: false,
+    detached: true,
+    windowsHide: true,
+    stdio: ["ignore", logFd, logFd],
+  });
+  child.unref();
+  return child.pid;
+}
+
+/** A PowerShell single-quoted literal, which escapes by doubling the quote and nothing else. */
+function powershellLiteral(value: string): string {
+  return `'${value.replaceAll("'", "''")}'`;
+}
+
+/**
+ * One command line, quoted the way the C runtime parses it back into `argv`.
+ *
+ * `Start-Process -ArgumentList` given an array joins its elements with a space and quotes none of
+ * them, so an argument holding a space arrives as several: `node -e '<script>' <path>` reaches node
+ * as `-e` followed by the first word of the script, and node exits on the syntax error. Given one
+ * string it passes that string through as the command line, which is what this builds.
+ */
+function windowsCommandLine(args: readonly string[]): string {
+  return args.map((value) => {
+    if (value !== "" && !/[\s"]/u.test(value)) return value;
+    // A quote is escaped by the backslashes before it, so those double; a trailing run doubles too,
+    // because the closing quote would otherwise escape itself against them.
+    const escaped = value.replace(/(\\*)"/gu, '$1$1\\"').replace(/(\\*)$/u, "$1$1");
+    return `"${escaped}"`;
+  }).join(" ");
+}
+
+/**
+ * Windows: a console of its own, hidden, so the launching console's destruction does not take it.
+ *
+ * The script travels as one `-EncodedCommand` blob, so no quoting of ours crosses a shell boundary.
+ * Feeding it on stdin instead looks equivalent and is not: `-Command -` parses what it reads a
+ * statement at a time, so an argument holding a newline — `node -e` with a real script in it — ends
+ * the statement early and PowerShell exits having run nothing, with no process id and nothing on
+ * stderr to say why. Base64 has no line structure to trip over.
+ *
+ * `Start-Process` refuses to send both streams to one file, so the error stream gets its own beside
+ * the log; `-PassThru` reports the new process, which is the pid everything after this waits on and
+ * stores.
+ */
+export async function startWithOwnConsole(
+  start: ManagedProgramCommand,
+  root: string,
+  logPath: string,
+): Promise<{ readonly pid?: number; readonly detail?: string }> {
+  const errorPath = processErrorLogPath(logPath);
+  const environment = Object.entries(start.env ?? {})
+    .map(([name, value]) => `$env:${name} = ${powershellLiteral(String(value))}`).join("\n");
+  const argumentList = start.args.length === 0
+    ? ""
+    : ` -ArgumentList ${powershellLiteral(windowsCommandLine(start.args))}`;
+  const script = [
+    "$ErrorActionPreference = 'Stop'",
+    environment,
+    `$p = Start-Process -FilePath ${powershellLiteral(start.command)}${argumentList}`
+      + ` -WorkingDirectory ${powershellLiteral(start.cwd ?? root)}`
+      + ` -RedirectStandardOutput ${powershellLiteral(logPath)}`
+      + ` -RedirectStandardError ${powershellLiteral(errorPath)}`
+      + " -WindowStyle Hidden -PassThru",
+    "[Console]::Out.Write($p.Id)",
+  ].filter((line) => line.length > 0).join("\n");
+
+  const shell = await new Promise<{ readonly out: string; readonly err: string }>((settle) => {
+    const encoded = Buffer.from(script, "utf16le").toString("base64");
+    const child = spawn("powershell.exe", ["-NoProfile", "-NonInteractive", "-EncodedCommand", encoded], {
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    let out = "";
+    let err = "";
+    const done = (): void => {
+      settle({ out: out.trim(), err: err.trim() });
+      child.stdout.destroy();
+      child.stderr.destroy();
+    };
+    child.stdout.on("data", (chunk: Buffer) => { out += chunk.toString("utf8"); });
+    child.stderr.on("data", (chunk: Buffer) => { err += chunk.toString("utf8"); });
+    child.on("error", (cause: Error) => { err = cause.message; done(); });
+    // `close` waits for the streams as well as the exit, and the process this shell launches can be
+    // holding an inherited copy of them: it outlives the shell by design, so those pipes stay open
+    // and `close` never arrives. The shell writes the id before it exits, so `exit` plus a moment
+    // for the pipe to drain is what settles this, and `close` still settles it first when it comes.
+    child.on("exit", () => { setTimeout(done, 250).unref(); });
+    child.on("close", done);
+  });
+  const pid = Number(shell.out);
+  if (Number.isSafeInteger(pid) && pid > 0) return { pid };
+  // `Start-Process` writes its refusal to the error stream and prints no id. Carrying it out is what
+  // separates a launch that was refused from one whose process died immediately after starting.
+  return { detail: shell.err === "" ? "Start-Process reported no process id" : shell.err.replaceAll(/\s+/gu, " ") };
+}
+
+async function waitForReady(program: ManagedProgram, pid: number, maxWaitMs: number): Promise<ManagedProgramState> {
+  const deadline = Date.now() + maxWaitMs;
+  let state = await program.probe();
+  while (state.state === "down" && processAlive(pid) && Date.now() < deadline) {
+    await sleep(1000);
+    state = await program.probe();
+  }
+  return state;
+}
+
+async function bringUp(
+  root: string,
+  program: ManagedProgram,
+  endpoint: string,
+  maxWaitMs: number,
+  onProgress?: (event: ManagedProgramProgress) => void,
+): Promise<ManagedProgramReport> {
+  const base = { id: program.id, endpoint };
+  onProgress?.({ id: program.id, phase: "checking" });
+  const initial = await program.probe();
+  if (initial.state === "ready") {
+    onProgress?.({ id: program.id, phase: "ready" });
+    return { ...base, action: "already-running", state: initial };
+  }
+  if (initial.state === "mismatch") {
+    // Never start a second copy beside a program that is already answering.
+    return { ...base, action: "unchanged", state: initial };
+  }
+
+  let installed = false;
+  if (program.installation !== undefined) {
+    const installation = await program.installation.probe();
+    if (installation.state !== "ready") {
+      onProgress?.({ id: program.id, phase: "installing" });
+      await mkdir(directory(root, program), { recursive: true });
+      for (const command of program.installation.commands) {
+        const result = await run(root, command);
+        if (!result.ok) {
+          return { ...base, action: "unchanged", state: initial, 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}` };
+      }
+      installed = true;
+    }
+  }
+  if (program.start === undefined) {
+    // 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 };
+  }
+
+  onProgress?.({ id: program.id, phase: "starting" });
+  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 {
+    // Outliving this process is the point, and what grants it differs by platform.
+    //
+    // POSIX wants its own session, which `detached` gives.
+    //
+    // Windows ties a process's lifetime to the console it is attached to. A child spawned from here
+    // inherits this one, so when the launching `node` exits its console is destroyed and every
+    // process on it is sent CTRL_CLOSE_EVENT and terminated. `unref` does not change that — it
+    // removes an event-loop reference and nothing else — so the service reported ready, answered one
+    // health probe, and was gone by the next command, with no error anywhere to read.
+    //
+    // What it needs is a console of its own, hidden. `detached` on Windows means DETACHED_PROCESS,
+    // which is no console at all, and then the first console grandchild — `uv` re-execing Python,
+    // Python opening workers — allocates a fresh visible one. `Start-Process -WindowStyle Hidden`
+    // creates a new console and hides it, which is the combination neither spawn option reaches.
+    const started = process.platform === "win32"
+      ? await startWithOwnConsole(program.start, root, logPath)
+      : { pid: await startDetached(program.start, root, log.fd) };
+    if (started.pid === undefined) {
+      const refusal = "detail" in started && started.detail !== undefined ? `: ${started.detail}` : "";
+      return {
+        ...base,
+        action: "unchanged",
+        state: initial,
+        detail: `${program.start.command} did not start${refusal}`,
+        logPath,
+      };
+    }
+    const child = { pid: started.pid };
+    onProgress?.({ id: program.id, phase: "waiting" });
+    const state = await waitForReady(program, child.pid, maxWaitMs);
+    if (state.state === "ready") onProgress?.({ id: program.id, phase: "ready" });
+    const alive = processAlive(child.pid);
+    if (alive) await writeFile(join(directory(root, program), "process.pid"), `${child.pid}\n`);
+    return {
+      ...base,
+      action: state.state === "ready" ? (alive ? "started" : "already-running") : "unchanged",
+      state,
+      ...(alive ? { pid: child.pid } : {}),
+      logPath,
+      ...(state.state === "ready" ? {} : {
+        detail: alive ? `see ${logPath}` : `process exited; see ${logPath}`,
+      }),
+    };
+  } finally {
+    await log?.close();
+  }
+}
+
+/** Install when needed and start every external program the Runtime Profile implies. */
+export async function bringManagedProgramsUp(
+  path: string,
+  options: ManagedProgramOptions = {},
+): Promise<{ readonly dataRoot: string; readonly programs: readonly ManagedProgramReport[] }> {
+  const { dataRoot, programs } = await declaredManagedPrograms(path, options);
+  // A fresh Runtime has no data directory yet. External commands may use it as
+  // their working directory, so create it before the first install/start.
+  await mkdir(dataRoot, { recursive: true });
+  const reports = await Promise.all(independentPrograms(programs).map(async ({ instance, program }) =>
+    await bringUp(dataRoot, program, instance, options.maxWaitMs ?? 300_000, options.onProgress)));
+  return { dataRoot, programs: reports };
+}
+
+/** Stop programs whose machine-level process records say Hypit started them. */
+export async function takeManagedProgramsDown(
+  path: string,
+  options: ManagedProgramOptions = {},
+): Promise<{ readonly dataRoot: string; readonly programs: readonly ManagedProgramReport[] }> {
+  const { dataRoot, programs } = await declaredManagedPrograms(path, options);
+  const reports = await Promise.all(independentPrograms(programs).map(async ({ instance, program }): Promise<ManagedProgramReport> => {
+    const base = { id: program.id, endpoint: instance };
+    const pid = await readPid(dataRoot, program);
+    if (pid === undefined || !processAlive(pid)) {
+      if (pid !== undefined) await rm(join(directory(dataRoot, program), "process.pid"), { force: true });
+      const state = await program.probe();
+      return state.state === "down"
+        ? { ...base, action: "nothing-to-stop", state }
+        // Someone else's process, or one started by hand. Killing it is not this
+        // command's business; saying so is.
+        : { ...base, action: "not-ours", state, detail: `${program.id} is running without a Hypit process record` };
+    }
+    const term = await stopProcessTree(pid);
+    if (term === "denied") {
+      return {
+        ...base,
+        action: "unchanged",
+        state: await program.probe(),
+        pid,
+        detail: `process ${pid} is running but this environment cannot stop it`,
+      };
+    }
+    if (term === "gone") {
+      await rm(join(directory(dataRoot, program), "process.pid"), { force: true });
+      const state = await program.probe();
+      return state.state === "down"
+        ? { ...base, action: "nothing-to-stop", state }
+        : { ...base, action: "not-ours", state, detail: `${program.id} is now served by another process` };
+    }
+    const deadline = Date.now() + 15_000;
+    while (processAlive(pid) && Date.now() < deadline) await sleep(200);
+    if (processAlive(pid)) {
+      if (await stopProcessTree(pid, true) === "denied") {
+        return {
+          ...base,
+          action: "unchanged",
+          state: await program.probe(),
+          pid,
+          detail: `process ${pid} ignored graceful termination and cannot be force-stopped`,
+        };
+      }
+      const forceDeadline = Date.now() + 2_000;
+      while (processAlive(pid) && Date.now() < forceDeadline) await sleep(50);
+      if (processAlive(pid)) {
+        return {
+          ...base,
+          action: "unchanged",
+          state: await program.probe(),
+          pid,
+          detail: `process ${pid} remained alive after forced termination`,
+        };
+      }
+    }
+    await rm(join(directory(dataRoot, program), "process.pid"), { force: true });
+    return { ...base, action: "stopped", state: await program.probe(), pid };
+    }));
+  return { dataRoot, programs: reports };
+}
+
+/** Probe every external program without changing anything. */
+export async function reportManagedPrograms(
+  path: string,
+  options: ManagedProgramOptions = {},
+): Promise<{ readonly dataRoot: string; readonly programs: readonly ManagedProgramReport[] }> {
+  const { dataRoot, programs } = await declaredManagedPrograms(path, options);
+  const reports = await Promise.all(independentPrograms(programs).map(async ({ instance, program }): Promise<ManagedProgramReport> => {
+    const state = await program.probe();
+    const pid = await readPid(dataRoot, program);
+    const logPath = join(directory(dataRoot, program), "program.log");
+    let hasLog = false;
+    try {
+      await stat(logPath);
+      hasLog = true;
+    } catch (error) {
+      if (!nodeError(error, "ENOENT")) throw error;
+    }
+    return {
+      id: program.id,
+      endpoint: instance,
+      state,
+      ...(pid !== undefined && processAlive(pid) ? { pid } : {}),
+      ...(hasLog ? { logPath } : {}),
+    };
+  }));
+  return { dataRoot, programs: reports };
+}

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

@@ -0,0 +1,246 @@
+import { randomUUID } from "node:crypto";
+import { BuildMachine } from "@hypit/core";
+import { isStreamingResourceStore } from "@hypit/runtime";
+import type {
+  BuildExecutionSnapshot,
+  BuildSnapshot,
+  OperationSnapshot,
+} from "@hypit/runtime";
+import type { CommandResult } from "@hypit/protocol";
+import type { BuildResultWriter } from "@hypit/build-result";
+
+import type {
+  CreateLocalResultWriterOptions,
+  LocalResultWriter,
+} from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+function operationEvent(operation: OperationSnapshot): CommandResult | undefined {
+  if (operation.status === "pending") return undefined;
+  if (operation.status === "completed") {
+    assert(operation.completion !== undefined, `Operation ${operation.id} has no completion`);
+    return {
+      kind: "need-fulfilled",
+      command: operation.command,
+      value: operation.completion.value,
+    };
+  }
+  if (operation.status === "failed") {
+    assert(operation.failure !== undefined, `Operation ${operation.id} has no failure`);
+    return {
+      kind: "command-failed",
+      command: operation.command,
+      code: operation.failure.code,
+      message: operation.failure.message,
+    };
+  }
+  return {
+    kind: "command-failed",
+    command: operation.command,
+    code: "CANCELLED",
+    message: `Operation ${operation.id} was cancelled by the Runtime capacity controller`,
+  };
+}
+
+/**
+ * Result writing only consumes already accepted execution facts and transient bytes. It cannot load
+ * Producers or Endpoints and it never changes the frozen execution decision.
+ */
+export function createLocalResultWriter(
+  options: CreateLocalResultWriterOptions,
+): LocalResultWriter {
+  const owner = randomUUID();
+  const openWriter = async (execution: BuildExecutionSnapshot): Promise<{
+    readonly writer: BuildResultWriter;
+    readonly manifest: import("@hypit/build-result").BuildResultManifest;
+    close(): Promise<void>;
+  }> => {
+    const opened = await options.openBuildResultRepository(execution.result);
+    try {
+      const [writer, manifest] = await Promise.all([
+        opened.repository.openWriter(execution.build),
+        opened.repository.read(execution.build),
+      ]);
+      assert(writer !== undefined && manifest !== undefined, `Build ${execution.build} has no Result draft`);
+      return {
+        writer,
+        manifest,
+        close: async () => await opened.close?.(),
+      };
+    } catch (error) {
+      await opened.close?.();
+      throw error;
+    }
+  };
+
+  const acceptStoredResults = async (build: string): Promise<BuildSnapshot> => {
+    const snapshot = await options.buildStore.read(build);
+    assert(snapshot !== undefined, `Build ${build} has no durable execution state`);
+    const machine = new BuildMachine(snapshot.definition, snapshot.facts);
+    const accept = async (event: CommandResult): Promise<void> => {
+      if (!machine.view().outstanding.some((command) => command.id === event.command)) return;
+      const fact = machine.evaluate(event);
+      if (fact === undefined) return;
+      await options.buildStore.append(build, fact);
+      machine.commit();
+    };
+    const events = [
+      ...(await options.commandExecutionStore.list(build)).flatMap((receipt) =>
+        receipt.status === "completed" && receipt.event !== undefined ? [receipt.event] : []),
+      ...(await options.operationStore.list({ build })).flatMap((operation) => operationEvent(operation) ?? []),
+    ];
+    // Preserve already validated sibling outputs before a failure closes Core's outstanding work.
+    for (const event of events.filter((event) => event.kind !== "command-failed")) await accept(event);
+    for (const event of events.filter((event) => event.kind === "command-failed")) await accept(event);
+    const accepted = await options.buildStore.read(build);
+    assert(accepted !== undefined, `Build ${build} disappeared while accepting stored results`);
+    return accepted;
+  };
+
+  const syncResult = async (
+    execution: BuildExecutionSnapshot,
+    state: import("@hypit/protocol").BuildState,
+  ): Promise<void> => {
+    const result = await openWriter(execution);
+    try {
+      if (result.manifest.outcome !== undefined) return;
+      const resources = options.resourceStoreForBuild?.(execution.build) ?? options.resourceStore;
+      await result.writer.sync({
+        state,
+        resources: {
+          open: async (artifact) => {
+            if (isStreamingResourceStore(resources)) return await resources.open(artifact.resource);
+            const bytes = await resources.get(artifact.resource);
+            return bytes === undefined ? undefined : (async function* () { yield bytes; })();
+          },
+        },
+      });
+    } finally {
+      await result.close();
+    }
+  };
+
+  const finishResult = async (execution: BuildExecutionSnapshot): Promise<void> => {
+    assert(execution.decision !== undefined, `Execution ${execution.build} has no decision`);
+    const opened = await openWriter(execution);
+    let closed = false;
+    try {
+      if (opened.manifest.outcome === undefined) {
+        await opened.close();
+        closed = true;
+        const snapshot = await acceptStoredResults(execution.build);
+        await syncResult(execution, snapshot.state);
+        const reopened = await openWriter(execution);
+        try {
+          const operations = (await options.operationStore.list({ build: execution.build })).map((operation) => {
+            return {
+              ...(operation.request === undefined ? {} : { need: { id: operation.request.need.id, capability: operation.request.need.capability } }),
+              ...(operation.createdAt === undefined ? {} : { createdAt: operation.createdAt }),
+              ...(operation.acknowledgedAt === undefined ? {} : { acknowledgedAt: operation.acknowledgedAt }),
+              ...(operation.endedAt === undefined ? {} : { endedAt: operation.endedAt }),
+              ...(operation.progress === undefined ? {} : { progress: operation.progress }),
+              ...(operation.cancellation === undefined ? {} : { cancellation: operation.cancellation }),
+              operation: operation.id, command: operation.command, endpoint: operation.endpoint, status: operation.status,
+              ...(operation.pool === undefined ? {} : { pool: operation.pool }),
+              ...(operation.credentials === undefined ? {} : { credentials: operation.credentials }),
+              ...(operation.receipt === undefined ? {} : { receipt: operation.receipt }),
+              ...(operation.failure === undefined ? {} : { failure: operation.failure }),
+            };
+          });
+          await reopened.writer.finish({
+            operations,
+            outcome: execution.decision.outcome,
+            ...(execution.decision.reason === undefined ? {} : { failure: execution.decision.reason }),
+          });
+        } finally {
+          await reopened.close();
+        }
+        return;
+      }
+      await opened.writer.finish({
+        outcome: execution.decision.outcome,
+        ...(execution.decision.reason === undefined ? {} : { failure: execution.decision.reason }),
+      });
+    } finally {
+      if (!closed) await opened.close();
+    }
+  };
+
+  const writeResultAndCleanup = async (execution: BuildExecutionSnapshot) => {
+    assert(execution.decision !== undefined, `Execution ${execution.build} has no decision`);
+    assert(execution.resultWrite?.owner === owner,
+      `Execution ${execution.build} Result writer is not owned by this process`);
+    let step: "result" | "cleanup" = "result";
+    try {
+      await finishResult(execution);
+      step = "cleanup";
+      await Promise.resolve(options.clearBuildResources?.(execution.build));
+      return await options.removeActiveBuild(execution.build);
+    } catch (error) {
+      const reason = error instanceof Error ? error.message : String(error);
+      try {
+        await options.executionStore.setAttention(execution.build, { step, error: reason });
+      } catch (attentionError) {
+        await options.executionStore.releaseResultWrite(execution.build, owner).catch(() => undefined);
+        throw attentionError;
+      }
+      return await options.executionStore.releaseResultWrite(execution.build, owner);
+    }
+  };
+
+  const claimResultWrite = async (build: string): Promise<BuildExecutionSnapshot> => {
+    const claimed = await options.executionStore.claimResultWrite(build, owner);
+    if (claimed !== undefined) return claimed;
+    const current = await options.executionStore.read(build);
+    assert(current !== undefined, `Execution ${build} does not exist`);
+    assert(current.decision !== undefined, `Execution ${build} has no decision`);
+    assert(current.resultWrite === undefined,
+      `Execution ${build} Result write is already owned by another process`);
+    throw new Error(`Execution ${build} could not be claimed for Result writing`);
+  };
+
+  const completeResult = async (initial: BuildExecutionSnapshot) =>
+    await writeResultAndCleanup(await claimResultWrite(initial.build));
+
+  const discardSubmission = async (build: string): Promise<boolean> => {
+    const submission = await options.submissionStore.read(build);
+    if (submission === undefined) return false;
+    const opened = await options.openBuildResultRepository(submission.result);
+    try {
+      await opened.repository.removeIncomplete(build);
+    } finally {
+      await opened.close?.();
+    }
+    await Promise.resolve(options.clearBuildResources?.(build));
+    await options.submissionStore.discard(build);
+    return true;
+  };
+
+  return {
+    sync: syncResult,
+    async finishResult(build) {
+      const execution = await options.executionStore.read(build);
+      if (execution === undefined) return undefined;
+      assert(execution.decision !== undefined,
+        `Build ${build} is still executing; its Result cannot be finished yet`);
+      const finished = await writeResultAndCleanup(await claimResultWrite(build));
+      return "createdAt" in finished
+        ? {
+            id: build,
+            outcome: finished.decision!.outcome,
+            ...(finished.attention === undefined ? {} : {
+              issue: { scope: finished.attention.step, message: finished.attention.error },
+            }),
+          }
+        : { id: build, outcome: finished.outcome };
+    },
+    discardSubmission,
+    completeResult,
+    close() {
+      return options.close?.();
+    },
+  };
+}