@osolmaz/pi-workflows 0.13.4 → 0.15.0

package/src/host/client.ts

@@ -0,0 +1,293 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { once } from "node:events";
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import net from "node:net";
+import { fileURLToPath } from "node:url";
+import { workflowStatePath } from "../state/database.js";
+import { canonicalJson, parseJson, type JsonValue } from "../state/json.js";
+import {
+  encodeProtocolLine,
+  hostSocketPath,
+  NdjsonFrameDecoder,
+  parseHostResponse,
+  type HostOperation,
+  type HostRequest,
+  type HostResponse,
+} from "./protocol.js";
+import type {
+  ResolvedControllerInitialization,
+  ResolvedSettingsChange,
+  ResolvedWorkflowLaunch,
+} from "./resolver-entry.js";
+
+const CONNECT_TIMEOUT_MS = 2_000;
+const START_TIMEOUT_MS = 10_000;
+
+export class WorkflowHostClient {
+  readonly clientId: string;
+  readonly databasePath: string;
+  readonly endpoint: string;
+
+  constructor(
+    options: {
+      clientId?: string;
+      databasePath?: string;
+      hostEntryPath?: string;
+      env?: Record<string, string>;
+    } = {},
+  ) {
+    this.clientId = options.clientId ?? `client-${randomUUID()}`;
+    this.databasePath = options.databasePath ?? workflowStatePath();
+    this.endpoint = hostSocketPath(this.databasePath);
+    this.hostEntryPath = options.hostEntryPath;
+    this.env = options.env;
+  }
+
+  private readonly hostEntryPath: string | undefined;
+  private readonly env: Record<string, string> | undefined;
+
+  async request(options: {
+    operation: HostOperation;
+    requestId?: string;
+    idempotencyKey?: string;
+    runId?: string;
+    expectedRevision?: number;
+    payload?: JsonValue;
+  }): Promise<HostResponse> {
+    const request: HostRequest = {
+      schema: "pi-workflows.host-request.v1",
+      requestId: options.requestId ?? randomUUID(),
+      clientId: this.clientId,
+      operation: options.operation,
+      idempotencyKey: options.idempotencyKey ?? randomUUID(),
+      ...(options.runId === undefined ? {} : { runId: options.runId }),
+      ...(options.expectedRevision === undefined
+        ? {}
+        : { expectedRevision: options.expectedRevision }),
+      payload: options.payload ?? {},
+    };
+    return await sendRequest(this.endpoint, request);
+  }
+
+  async resolveWorkflow(options: {
+    cwd: string;
+    workflowRef: string;
+    timeoutMs?: number;
+  }): Promise<ResolvedWorkflowLaunch> {
+    return (await this.runResolver(
+      {
+        schema: "pi-workflows.resolve-request.v1",
+        cwd: options.cwd,
+        workflowRef: options.workflowRef,
+      },
+      options.cwd,
+      "pi-workflows.resolved-launch.v1",
+      options.timeoutMs,
+    )) as unknown as ResolvedWorkflowLaunch;
+  }
+
+  async resolveControllerInitialization(options: {
+    cwd: string;
+    controllerName: string;
+    spec: JsonValue;
+    timeoutMs?: number;
+  }): Promise<ResolvedControllerInitialization> {
+    return (await this.runResolver(
+      {
+        schema: "pi-workflows.controller-initialization-request.v1",
+        cwd: options.cwd,
+        controllerName: options.controllerName,
+        spec: options.spec,
+      },
+      options.cwd,
+      "pi-workflows.resolved-controller-initialization.v1",
+      options.timeoutMs,
+    )) as unknown as ResolvedControllerInitialization;
+  }
+
+  async resolveSettingsChange(options: {
+    cwd: string;
+    workflowRef: string;
+    definitionDigest: string;
+    mountPath: string;
+    current: JsonValue;
+    patch: JsonValue;
+    actorId: string;
+    timeoutMs?: number;
+  }): Promise<ResolvedSettingsChange> {
+    return (await this.runResolver(
+      {
+        schema: "pi-workflows.settings-validation-request.v1",
+        cwd: options.cwd,
+        workflowRef: options.workflowRef,
+        definitionDigest: options.definitionDigest,
+        mountPath: options.mountPath,
+        current: options.current,
+        patch: options.patch,
+        actorId: options.actorId,
+      },
+      options.cwd,
+      "pi-workflows.resolved-settings-change.v1",
+      options.timeoutMs,
+    )) as unknown as ResolvedSettingsChange;
+  }
+
+  private async runResolver(
+    request: JsonValue,
+    cwd: string,
+    expectedSchema: string,
+    timeoutMs = START_TIMEOUT_MS,
+  ): Promise<JsonValue> {
+    const builtEntry = fileURLToPath(new URL("./resolver-entry.js", import.meta.url));
+    const sourceEntry = fileURLToPath(new URL("./resolver-entry.ts", import.meta.url));
+    const args = fs.existsSync(builtEntry)
+      ? [builtEntry]
+      : ["--import", createRequire(import.meta.url).resolve("tsx"), sourceEntry];
+    const child = spawn(process.execPath, args, {
+      cwd,
+      detached: process.platform !== "win32",
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, ...this.env },
+    });
+    let stdout: Buffer = Buffer.alloc(0);
+    let stderr: Buffer = Buffer.alloc(0);
+    let outputError: Error | undefined;
+    const append = (current: Buffer, chunk: Buffer): Buffer => {
+      const next = Buffer.concat([current, chunk]);
+      if (next.byteLength > 1024 * 1024) {
+        outputError = new Error("Workflow resolver output exceeds 1 MiB");
+        stopProcessGroup(child.pid);
+        return current;
+      }
+      return next;
+    };
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout = append(stdout, chunk);
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderr = append(stderr, chunk);
+    });
+    child.stdin.end(canonicalJson(request));
+    const timeout = setTimeout(() => stopProcessGroup(child.pid), timeoutMs);
+    timeout.unref?.();
+    const [code, signal] = (await once(child, "exit")) as [number | null, NodeJS.Signals | null];
+    clearTimeout(timeout);
+    if (outputError !== undefined) throw outputError;
+    if (code !== 0) {
+      const detail = stderr.toString("utf8").trim().slice(0, 2_000);
+      throw new Error(
+        detail || `Workflow resolver exited before completion (code ${code}, signal ${signal})`,
+      );
+    }
+    const value = parseJson(stdout.toString("utf8").trimEnd());
+    if (!isRecord(value) || value.schema !== expectedSchema) {
+      throw new Error("Workflow resolver returned an invalid result envelope");
+    }
+    return value as JsonValue;
+  }
+
+  async ensureRunning(): Promise<HostResponse> {
+    try {
+      return await this.request({
+        operation: "host.status",
+        requestId: `host-status-${randomUUID()}`,
+        idempotencyKey: `host-status-${randomUUID()}`,
+      });
+    } catch {
+      this.startDetached();
+    }
+    const deadline = Date.now() + START_TIMEOUT_MS;
+    let lastError: unknown;
+    while (Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      try {
+        return await this.request({
+          operation: "host.status",
+          requestId: `host-status-${randomUUID()}`,
+          idempotencyKey: `host-status-${randomUUID()}`,
+        });
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    throw new Error(
+      `Workflow host did not become ready: ${lastError instanceof Error ? lastError.message : String(lastError)}`,
+    );
+  }
+
+  private startDetached(): void {
+    const builtEntry = fileURLToPath(new URL("./host-entry.js", import.meta.url));
+    const sourceEntry = fileURLToPath(new URL("./host-entry.ts", import.meta.url));
+    const entry = this.hostEntryPath ?? builtEntry;
+    const args =
+      this.hostEntryPath === undefined && !fs.existsSync(builtEntry)
+        ? ["--import", createRequire(import.meta.url).resolve("tsx"), sourceEntry]
+        : [entry];
+    const child = spawn(process.execPath, [...args, "--database", this.databasePath], {
+      detached: true,
+      stdio: "ignore",
+      env: { ...process.env, ...this.env },
+    });
+    child.unref();
+  }
+}
+
+function stopProcessGroup(pid: number | undefined): void {
+  if (pid === undefined) return;
+  try {
+    if (process.platform !== "win32") process.kill(-pid, "SIGKILL");
+    else process.kill(pid, "SIGKILL");
+  } catch {
+    // The resolver has already exited.
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function sendRequest(endpoint: string, request: HostRequest): Promise<HostResponse> {
+  const socket = net.createConnection(endpoint);
+  const decoder = new NdjsonFrameDecoder();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    await Promise.race([
+      once(socket, "connect"),
+      new Promise<never>((_, reject) => {
+        timer = setTimeout(
+          () => reject(new Error("Workflow host connection timed out")),
+          CONNECT_TIMEOUT_MS,
+        );
+        timer.unref?.();
+      }),
+      once(socket, "error").then(([error]) => Promise.reject(error)),
+    ]);
+    if (!socket.write(encodeProtocolLine(request))) await once(socket, "drain");
+    const response = await new Promise<HostResponse>((resolve, reject) => {
+      const timeout = setTimeout(
+        () => reject(new Error("Workflow host response timed out")),
+        CONNECT_TIMEOUT_MS,
+      );
+      timeout.unref?.();
+      socket.on("data", (chunk: Buffer) => {
+        try {
+          const frame = decoder.push(chunk)[0];
+          if (frame === undefined) return;
+          clearTimeout(timeout);
+          resolve(parseHostResponse(frame));
+        } catch (error) {
+          clearTimeout(timeout);
+          reject(error);
+        }
+      });
+      socket.once("error", reject);
+      socket.once("close", () => reject(new Error("Workflow host closed before responding")));
+    });
+    return response;
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+    socket.destroy();
+  }
+}

package/src/host/controller-worker-entry.ts

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+import { randomUUID } from "node:crypto";
+import { once } from "node:events";
+import { fileURLToPath } from "node:url";
+import { jsonFingerprint } from "../controllers/json.js";
+import { loadControllerFile } from "../controllers/loader.js";
+import { createResultHelpers } from "../controllers/results.js";
+import type {
+  ChildWorkflowRecord,
+  ControllerEffects,
+  ControllerFollowUpResult,
+  ControllerQueueFollowUpRequest,
+  ControllerRemoveFollowUpRequest,
+  ControllerSettingsChangeRequest,
+  ControllerSettingsChangeResult,
+  ControllerWorkflows,
+  EffectApplication,
+  EffectDefinition,
+  EffectObservation,
+  EffectRecord,
+  ReconcileContext,
+  ReconcileResult,
+} from "../controllers/types.js";
+import { parseJson, type JsonValue } from "../state/json.js";
+import { errorMessage } from "../workflows/errors.js";
+import {
+  CONTROLLER_WORKER_LAUNCH_SCHEMA,
+  encodeControllerWorkerLine,
+  parseControllerWorkerResponse,
+  type ControllerWorkerLaunchEnvelope,
+  type ControllerWorkerMessage,
+  type ControllerWorkerOperation,
+  type ControllerWorkerResponse,
+} from "./controller-worker-protocol.js";
+
+const STARTUP_ENV = "PI_WORKFLOWS_CONTROLLER_WORKER_LAUNCH";
+const MAX_FRAME_BYTES = 1024 * 1024;
+
+class ControllerWorkerTransport {
+  private readonly pending = new Map<
+    string,
+    { resolve: (response: ControllerWorkerResponse) => void; reject: (error: Error) => void }
+  >();
+  private buffered = Buffer.alloc(0);
+
+  constructor(private readonly launch: ControllerWorkerLaunchEnvelope) {
+    process.stdin.on("data", (chunk: Buffer) => this.onData(chunk));
+    process.stdin.on("error", (error) => this.failAll(error));
+    process.stdin.resume();
+  }
+
+  async request<T>(operation: ControllerWorkerOperation, payload: JsonValue): Promise<T> {
+    const message: ControllerWorkerMessage = {
+      schema: "pi-workflows.controller-worker-message.v1",
+      launchSchema: this.launch.schema,
+      messageId: randomUUID(),
+      workerEpoch: this.launch.workerEpoch,
+      generation: this.launch.generation,
+      operation,
+      payload,
+    };
+    const response = await this.send(message);
+    if (response.outcome !== "accepted") {
+      throw new Error(response.error ?? `Controller worker ${response.outcome}`);
+    }
+    return response.result as T;
+  }
+
+  close(): void {
+    process.stdin.pause();
+    process.stdin.removeAllListeners("data");
+    process.stdin.removeAllListeners("error");
+    this.failAll(new Error("Controller worker transport closed"));
+  }
+
+  private async send(message: ControllerWorkerMessage): Promise<ControllerWorkerResponse> {
+    const response = new Promise<ControllerWorkerResponse>((resolve, reject) => {
+      this.pending.set(message.messageId, { resolve, reject });
+    });
+    if (!process.stdout.write(encodeControllerWorkerLine(message))) {
+      await once(process.stdout, "drain");
+    }
+    return await response;
+  }
+
+  private onData(chunk: Buffer): void {
+    this.buffered = Buffer.concat([this.buffered, chunk]);
+    if (this.buffered.byteLength > MAX_FRAME_BYTES && !this.buffered.includes(0x0a)) {
+      this.failAll(new Error("Controller worker response exceeds 1 MiB"));
+      return;
+    }
+    for (;;) {
+      const newline = this.buffered.indexOf(0x0a);
+      if (newline < 0) return;
+      const frame = this.buffered.subarray(0, newline);
+      this.buffered = this.buffered.subarray(newline + 1);
+      if (frame.byteLength === 0) continue;
+      try {
+        const response = parseControllerWorkerResponse(frame);
+        const pending = this.pending.get(response.messageId);
+        if (pending === undefined) throw new Error("Controller worker response is unexpected");
+        this.pending.delete(response.messageId);
+        pending.resolve(response);
+      } catch (error) {
+        this.failAll(error instanceof Error ? error : new Error(String(error)));
+      }
+    }
+  }
+
+  private failAll(error: Error): void {
+    for (const pending of this.pending.values()) pending.reject(error);
+    this.pending.clear();
+  }
+}
+
+class HostedControllerEffects implements ControllerEffects {
+  private used = false;
+
+  constructor(
+    private readonly transport: ControllerWorkerTransport,
+    private readonly signal: AbortSignal,
+  ) {}
+
+  async ensure<TRequest>(definition: EffectDefinition<TRequest>): Promise<EffectRecord> {
+    if (this.used) throw new Error("A reconciliation pass may ensure only one external effect");
+    this.used = true;
+    const reservation = await this.transport.request<{ record: EffectRecord; created: boolean }>(
+      "effect.reserve",
+      {
+        key: definition.key,
+        kind: definition.kind,
+        requestFingerprint: jsonFingerprint(definition.request),
+      },
+    );
+    if (["applied", "rejected", "indeterminate"].includes(reservation.record.state)) {
+      return reservation.record;
+    }
+    if (!reservation.created) {
+      const observation = await definition.observe(this.signal);
+      if (observation.state !== "not_applied") {
+        return await this.settleObservation(definition.key, observation);
+      }
+    }
+    let applied: EffectApplication;
+    try {
+      applied = await definition.apply(this.signal);
+    } catch (error) {
+      applied = { state: "indeterminate", error: boundedError(error) };
+    }
+    return await this.transport.request<EffectRecord>("effect.settle", {
+      key: definition.key,
+      state: applied.state,
+      ...(applied.state === "applied" && applied.externalRef !== undefined
+        ? { externalRef: applied.externalRef }
+        : {}),
+      ...(applied.state !== "applied" && applied.error !== undefined
+        ? { error: applied.error }
+        : {}),
+    });
+  }
+
+  private async settleObservation(
+    key: string,
+    observation: EffectObservation,
+  ): Promise<EffectRecord> {
+    return await this.transport.request<EffectRecord>("effect.settle", {
+      key,
+      state: observation.state === "applied" ? "applied" : "indeterminate",
+      ...(observation.state === "applied" && observation.externalRef !== undefined
+        ? { externalRef: observation.externalRef }
+        : {}),
+    });
+  }
+}
+
+class HostedControllerWorkflows implements ControllerWorkflows {
+  constructor(private readonly transport: ControllerWorkerTransport) {}
+
+  async ensure(request: {
+    requestKey: string;
+    workflow: string;
+    input: unknown;
+  }): Promise<ChildWorkflowRecord> {
+    return await this.transport.request<ChildWorkflowRecord>(
+      "workflow.ensure",
+      request as JsonValue,
+    );
+  }
+
+  async changeSettings(
+    request: ControllerSettingsChangeRequest,
+  ): Promise<ControllerSettingsChangeResult> {
+    return await this.transport.request<ControllerSettingsChangeResult>(
+      "workflow.changeSettings",
+      request as unknown as JsonValue,
+    );
+  }
+
+  async queueFollowUp(request: ControllerQueueFollowUpRequest): Promise<ControllerFollowUpResult> {
+    return await this.transport.request<ControllerFollowUpResult>(
+      "workflow.queueFollowUp",
+      request as unknown as JsonValue,
+    );
+  }
+
+  async removeFollowUp(
+    request: ControllerRemoveFollowUpRequest,
+  ): Promise<ControllerFollowUpResult> {
+    return await this.transport.request<ControllerFollowUpResult>(
+      "workflow.removeFollowUp",
+      request as unknown as JsonValue,
+    );
+  }
+}
+
+export async function runControllerWorker(): Promise<number> {
+  const launch = readLaunchEnvelope();
+  const transport = new ControllerWorkerTransport(launch);
+  try {
+    const definition = await loadControllerFile(launch.definitionPath);
+    if (definition.name !== launch.controllerName) {
+      throw new Error(
+        `Controller source name changed: expected ${launch.controllerName}, got ${definition.name}`,
+      );
+    }
+    await transport.request("worker.ready", {});
+    const abort = new AbortController();
+    const timeoutMs = definition.timeoutMs ?? launch.timeoutMs;
+    const timer = setTimeout(
+      () => abort.abort(new Error(`Reconciliation timed out after ${timeoutMs}ms`)),
+      timeoutMs,
+    );
+    try {
+      const context: ReconcileContext<unknown> = {
+        signal: abort.signal,
+        effects: new HostedControllerEffects(transport, abort.signal),
+        workflows: new HostedControllerWorkflows(transport),
+        ...createResultHelpers<unknown>(),
+      };
+      const result = await raceWithAbort(
+        Promise.resolve(definition.reconcile(context, launch.resource)),
+        abort.signal,
+      );
+      validateResult(result);
+      await transport.request("worker.finished", result as unknown as JsonValue);
+    } catch (error) {
+      await transport.request("worker.failed", { error: boundedError(error) });
+    } finally {
+      clearTimeout(timer);
+    }
+    return 0;
+  } finally {
+    transport.close();
+  }
+}
+
+function readLaunchEnvelope(): ControllerWorkerLaunchEnvelope {
+  const encoded = process.env[STARTUP_ENV];
+  if (encoded === undefined) throw new Error("Controller worker launch envelope is missing");
+  const value = parseJson(Buffer.from(encoded, "base64url").toString("utf8"));
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    Array.isArray(value) ||
+    (value as { schema?: unknown }).schema !== CONTROLLER_WORKER_LAUNCH_SCHEMA
+  ) {
+    throw new Error("Controller worker launch envelope is invalid");
+  }
+  return value as unknown as ControllerWorkerLaunchEnvelope;
+}
+
+function validateResult(value: unknown): asserts value is ReconcileResult<unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("Controller reconcile result must be an object");
+  }
+  const result = value as { kind?: unknown; afterMs?: unknown };
+  if (result.kind !== "settled" && result.kind !== "requeue") {
+    throw new Error("Controller reconcile result kind is invalid");
+  }
+  if (
+    result.afterMs !== undefined &&
+    (!Number.isSafeInteger(result.afterMs) || (result.afterMs as number) < 0)
+  ) {
+    throw new Error("Controller reconcile afterMs must be a non-negative safe integer");
+  }
+}
+
+function raceWithAbort<T>(operation: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(signal.reason ?? new Error("Reconciliation aborted"));
+    signal.addEventListener("abort", onAbort, { once: true });
+    operation.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+    if (signal.aborted) onAbort();
+  });
+}
+
+function boundedError(error: unknown): string {
+  const message = errorMessage(error);
+  return message.length <= 8_192 ? message : `${message.slice(0, 8_192)}…`;
+}
+
+async function main(): Promise<void> {
+  try {
+    process.exitCode = await runControllerWorker();
+  } catch (error) {
+    process.stderr.write(`${errorMessage(error)}\n`);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) void main();

package/src/host/controller-worker-protocol.ts

@@ -0,0 +1,104 @@
+import type { ControllerResource } from "../controllers/types.js";
+import { canonicalJson, parseJson, type JsonValue } from "../state/json.js";
+
+export const CONTROLLER_WORKER_LAUNCH_SCHEMA = "pi-workflows.controller-worker-launch.v1" as const;
+export const CONTROLLER_WORKER_MESSAGE_SCHEMA =
+  "pi-workflows.controller-worker-message.v1" as const;
+export const CONTROLLER_WORKER_RESPONSE_SCHEMA =
+  "pi-workflows.controller-worker-response.v1" as const;
+
+export type ControllerWorkerLaunchEnvelope = {
+  schema: typeof CONTROLLER_WORKER_LAUNCH_SCHEMA;
+  workerEpoch: string;
+  hostEpoch: number;
+  generation: number;
+  projectPath: string;
+  definitionPath: string;
+  controllerName: string;
+  resource: ControllerResource;
+  timeoutMs: number;
+};
+
+export type ControllerWorkerOperation =
+  | "worker.ready"
+  | "effect.reserve"
+  | "effect.settle"
+  | "workflow.ensure"
+  | "workflow.changeSettings"
+  | "workflow.queueFollowUp"
+  | "workflow.removeFollowUp"
+  | "worker.finished"
+  | "worker.failed";
+
+export type ControllerWorkerMessage = {
+  schema: typeof CONTROLLER_WORKER_MESSAGE_SCHEMA;
+  launchSchema: typeof CONTROLLER_WORKER_LAUNCH_SCHEMA;
+  messageId: string;
+  workerEpoch: string;
+  generation: number;
+  operation: ControllerWorkerOperation;
+  payload: JsonValue;
+};
+
+export type ControllerWorkerResponse = {
+  schema: typeof CONTROLLER_WORKER_RESPONSE_SCHEMA;
+  messageId: string;
+  outcome: "accepted" | "rejected" | "claimLost";
+  result?: JsonValue;
+  error?: string;
+};
+
+export function encodeControllerWorkerLine(
+  value: ControllerWorkerMessage | ControllerWorkerResponse,
+): Buffer {
+  return Buffer.from(`${canonicalJson(value)}\n`, "utf8");
+}
+
+export function parseControllerWorkerMessage(frame: Buffer): ControllerWorkerMessage {
+  const value = parseJson(frame.toString("utf8"));
+  if (!isRecord(value) || value.schema !== CONTROLLER_WORKER_MESSAGE_SCHEMA) {
+    throw new Error("Invalid controller worker message schema");
+  }
+  if (
+    value.launchSchema !== CONTROLLER_WORKER_LAUNCH_SCHEMA ||
+    typeof value.messageId !== "string" ||
+    typeof value.workerEpoch !== "string" ||
+    !Number.isSafeInteger(value.generation) ||
+    typeof value.operation !== "string" ||
+    !OPERATIONS.has(value.operation as ControllerWorkerOperation) ||
+    !Object.hasOwn(value, "payload")
+  ) {
+    throw new Error("Invalid controller worker message");
+  }
+  return value as ControllerWorkerMessage;
+}
+
+export function parseControllerWorkerResponse(frame: Buffer): ControllerWorkerResponse {
+  const value = parseJson(frame.toString("utf8"));
+  if (!isRecord(value) || value.schema !== CONTROLLER_WORKER_RESPONSE_SCHEMA) {
+    throw new Error("Invalid controller worker response schema");
+  }
+  if (
+    typeof value.messageId !== "string" ||
+    !["accepted", "rejected", "claimLost"].includes(String(value.outcome))
+  ) {
+    throw new Error("Invalid controller worker response");
+  }
+  return value as ControllerWorkerResponse;
+}
+
+const OPERATIONS = new Set<ControllerWorkerOperation>([
+  "worker.ready",
+  "effect.reserve",
+  "effect.settle",
+  "workflow.ensure",
+  "workflow.changeSettings",
+  "workflow.queueFollowUp",
+  "workflow.removeFollowUp",
+  "worker.finished",
+  "worker.failed",
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}