@bitkyc08/opencodex 2.12.0 → 2.13.0

package/src/lab/fabric/patch.ts

@@ -0,0 +1,79 @@
+import { FABRIC_LIMITS, SYNTHETIC_VALUE_PATH } from "./constants";
+import { assertSafeRelativePosixPath, writeScratchFileUtf8 } from "./scratch";
+import { FabricTaskError, type SyntheticPatchV1 } from "./types";
+
+const ALLOWED_KEYS = new Set(["schemaVersion", "operations"]);
+const OP_KEYS = new Set(["op", "path", "contentUtf8"]);
+
+/** Parse and validate a synthetic-patch producer payload. */
+export function parseSyntheticPatchV1(raw: unknown): SyntheticPatchV1 {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new FabricTaskError("malformed producer outcome: patch must be object", "malformed_producer_outcome", "harness");
+  }
+  const obj = raw as Record<string, unknown>;
+  for (const key of Object.keys(obj)) {
+    if (!ALLOWED_KEYS.has(key)) {
+      throw new FabricTaskError(`malformed producer outcome: unknown field ${key}`, "malformed_producer_outcome", "harness");
+    }
+  }
+  if (obj.schemaVersion !== 1) {
+    throw new FabricTaskError("malformed producer outcome: schemaVersion", "malformed_producer_outcome", "harness");
+  }
+  if (!Array.isArray(obj.operations)) {
+    throw new FabricTaskError("malformed producer outcome: operations", "malformed_producer_outcome", "harness");
+  }
+  if (obj.operations.length !== 1) {
+    throw new FabricTaskError("exactly one patch operation is required", "malformed_producer_outcome", "harness");
+  }
+  const opRaw = obj.operations[0];
+  if (!opRaw || typeof opRaw !== "object" || Array.isArray(opRaw)) {
+    throw new FabricTaskError("malformed producer outcome: operation", "malformed_producer_outcome", "harness");
+  }
+  const op = opRaw as Record<string, unknown>;
+  for (const key of Object.keys(op)) {
+    if (!OP_KEYS.has(key)) {
+      throw new FabricTaskError(`malformed producer outcome: unknown op field ${key}`, "malformed_producer_outcome", "harness");
+    }
+  }
+  if (op.op !== "replace" || typeof op.path !== "string" || typeof op.contentUtf8 !== "string") {
+    throw new FabricTaskError("malformed producer outcome: replace shape", "malformed_producer_outcome", "harness");
+  }
+  try {
+    assertSafeRelativePosixPath(op.path);
+  } catch (error) {
+    if (error instanceof FabricTaskError) throw error;
+    throw new FabricTaskError("patch path escapes scratch", "sandbox_violation", "harness");
+  }
+  if (op.path !== SYNTHETIC_VALUE_PATH) {
+    throw new FabricTaskError("patch path must be src/value.txt", "behavioral_failure", "route");
+  }
+  const contentBytes = Buffer.byteLength(op.contentUtf8, "utf8");
+  if (contentBytes > FABRIC_LIMITS.maxAggregateIoBytes) {
+    throw new FabricTaskError("patch content exceeds io budget", "budget_exhausted", "environment");
+  }
+  return {
+    schemaVersion: 1,
+    operations: [{ op: "replace", path: SYNTHETIC_VALUE_PATH, contentUtf8: op.contentUtf8 }],
+  };
+}
+
+/** Apply a validated synthetic patch inside the scratch tree under budget limits. */
+export function applySyntheticPatch(scratchRoot: string, patch: SyntheticPatchV1): { bytesWritten: number; filesTouched: number; patchOperations: number } {
+  if (patch.operations.length > FABRIC_LIMITS.maxPatchOperations) {
+    throw new FabricTaskError("too many patch operations", "budget_exhausted", "environment");
+  }
+  let bytesWritten = 0;
+  for (const operation of patch.operations) {
+    bytesWritten += writeScratchFileUtf8(
+      scratchRoot,
+      operation.path,
+      operation.contentUtf8,
+      FABRIC_LIMITS.maxAggregateIoBytes,
+    );
+  }
+  return {
+    bytesWritten,
+    filesTouched: patch.operations.length,
+    patchOperations: patch.operations.length,
+  };
+}

package/src/lab/fabric/producer-child.ts

@@ -0,0 +1,139 @@
+import {
+  FABRIC_LIMITS,
+  SYNTHETIC_AFTER_UTF8,
+  SYNTHETIC_BEFORE_UTF8,
+  SYNTHETIC_VALUE_PATH,
+} from "./constants";
+import {
+  encodeProducerProtocolLine,
+  FABRIC_PRODUCER_PROTOCOL_MAX_BYTES,
+  FABRIC_PRODUCER_REQUEST_MAX_BYTES,
+  type ProducerParentRequest,
+} from "./producer-protocol";
+import type { FabricHarnessProducerKind, SyntheticPatchV1 } from "./types";
+
+function writeLine(message: Parameters<typeof encodeProducerProtocolLine>[0]): void {
+  process.stdout.write(encodeProducerProtocolLine(message));
+}
+
+function correctPatch(): SyntheticPatchV1 {
+  return {
+    schemaVersion: 1,
+    operations: [{ op: "replace", path: SYNTHETIC_VALUE_PATH, contentUtf8: SYNTHETIC_AFTER_UTF8 }],
+  };
+}
+
+function wrongPatch(): SyntheticPatchV1 {
+  return {
+    schemaVersion: 1,
+    operations: [{ op: "replace", path: SYNTHETIC_VALUE_PATH, contentUtf8: "wrong\n" }],
+  };
+}
+
+async function runHarness(
+  kind: FabricHarnessProducerKind,
+  scratchRoot: string,
+  totalTimeoutMs: number,
+  inactivityTimeoutMs: number,
+): Promise<SyntheticPatchV1> {
+  switch (kind) {
+    case "deterministic_correct":
+      return correctPatch();
+    case "deterministic_wrong":
+      return wrongPatch();
+    case "infinite_sync":
+      while (true) {
+        /* terminated by parent */
+      }
+    case "never_resolve":
+      while (true) {
+        await Bun.sleep(Math.max(25, Math.min(1_000, Math.floor(inactivityTimeoutMs * 0.75))));
+      }
+    case "mutate_after_delay": {
+      await Bun.sleep(totalTimeoutMs + Math.max(250, inactivityTimeoutMs));
+      const { writeFileSync, mkdirSync } = await import("node:fs");
+      const { join, dirname } = await import("node:path");
+      mkdirSync(join(scratchRoot, dirname(SYNTHETIC_VALUE_PATH)), { recursive: true });
+      writeFileSync(join(scratchRoot, SYNTHETIC_VALUE_PATH), "late\n");
+      return correctPatch();
+    }
+    case "periodic_activity": {
+      const intervalMs = Math.max(10, Math.min(200, Math.floor(inactivityTimeoutMs * 0.4)));
+      const iterations = Math.max(3, Math.min(20, Math.floor((totalTimeoutMs * 0.7) / intervalMs)));
+      for (let i = 0; i < iterations; i++) {
+        writeLine({ type: "activity" });
+        await Bun.sleep(intervalMs);
+      }
+      return correctPatch();
+    }
+    case "activity_until_total": {
+      const intervalMs = Math.max(10, Math.min(50, Math.floor(inactivityTimeoutMs * 0.25)));
+      while (true) {
+        writeLine({ type: "activity" });
+        await Bun.sleep(intervalMs);
+      }
+    }
+    case "flood_stdout":
+      while (true) {
+        process.stdout.write("x".repeat(4096));
+      }
+    default:
+      throw new Error(`unsupported harness kind: ${kind as string}`);
+  }
+}
+
+async function runExecutorModule(
+  modulePath: string,
+  executorInput: unknown,
+  reportActivity: () => void,
+): Promise<SyntheticPatchV1> {
+  const mod = await import(modulePath) as { execute: (input: unknown) => Promise<SyntheticPatchV1> | SyntheticPatchV1 };
+  if (typeof mod.execute !== "function") throw new Error("executor module missing execute export");
+  const input = {
+    ...(executorInput as Record<string, unknown>),
+    reportActivity,
+  };
+  return await Promise.resolve(mod.execute(input));
+}
+
+async function main(): Promise<void> {
+  const raw = await Bun.stdin.text();
+  if (Buffer.byteLength(raw, "utf8") > FABRIC_PRODUCER_REQUEST_MAX_BYTES) {
+    writeLine({
+      type: "error",
+      code: "budget_exhausted",
+      message: "request payload exceeds protocol limit",
+      attribution: "environment",
+    });
+    process.exit(1);
+    return;
+  }
+  const req = JSON.parse(raw) as ProducerParentRequest;
+  const totalTimeoutMs = req.totalTimeoutMs ?? FABRIC_LIMITS.totalTimeoutMs;
+  const inactivityTimeoutMs = req.inactivityTimeoutMs ?? FABRIC_LIMITS.inactivityTimeoutMs;
+  let patch: SyntheticPatchV1;
+  const reportActivity = () => writeLine({ type: "activity" });
+  if (req.harnessKind) {
+    patch = await runHarness(
+      req.harnessKind as FabricHarnessProducerKind,
+      req.scratchRoot,
+      totalTimeoutMs,
+      inactivityTimeoutMs,
+    );
+  } else if (req.executorModulePath) {
+    patch = await runExecutorModule(req.executorModulePath, req.executorInput, reportActivity);
+  } else {
+    throw new Error("child request missing harnessKind or executorModulePath");
+  }
+  writeLine({ type: "result", patch });
+}
+
+main().catch((error: unknown) => {
+  writeLine({
+    type: "error",
+    code: "harness_failure",
+    message: error instanceof Error ? error.message : String(error),
+    attribution: "harness",
+  });
+  process.exit(1);
+});

package/src/lab/fabric/producer-isolate.ts

@@ -0,0 +1,276 @@
+import { spawn, type ChildProcess } from "node:child_process";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { FABRIC_LIMITS } from "./constants";
+import {
+  FABRIC_PRODUCER_PROTOCOL_MAX_BYTES,
+  FABRIC_PRODUCER_REQUEST_MAX_BYTES,
+  FABRIC_PRODUCER_STDERR_MAX_BYTES,
+  parseProducerProtocolLine,
+  type IsolatedProducerResult,
+} from "./producer-protocol";
+import type { FabricHarnessProducerKind, FabricPatchExecutorInput, SyntheticPatchV1 } from "./types";
+import { FabricTaskError } from "./types";
+
+const CHILD_ENTRY = join(dirname(fileURLToPath(import.meta.url)), "producer-child.ts");
+
+type FabricProducerIsolationLimits = {
+  totalTimeoutMs: number;
+  inactivityTimeoutMs: number;
+};
+
+let testIsolationLimits: FabricProducerIsolationLimits | undefined;
+
+interface IsolateRequest {
+  harnessKind?: FabricHarnessProducerKind;
+  executorModulePath?: string;
+  scratchRoot: string;
+  totalTimeoutMs: number;
+  inactivityTimeoutMs: number;
+  executorInput?: FabricPatchExecutorInput;
+  now?: () => number;
+}
+
+function minimalChildEnv(scratchRoot: string): Record<string, string> {
+  return {
+    TZ: "UTC",
+    NO_COLOR: "1",
+    OCX_FABRIC_SCRATCH_ROOT: scratchRoot,
+  };
+}
+
+function killChild(child: ChildProcess): void {
+  try {
+    child.kill("SIGKILL");
+  } catch {
+    /* ignore */
+  }
+}
+
+/** Run a fabric patch producer in an isolated child process with parent-owned timeouts. */
+export async function runIsolatedFabricProducer(request: IsolateRequest): Promise<IsolatedProducerResult> {
+  const now = request.now ?? (() => Date.now());
+  let lastActivityAt = now();
+
+  return await new Promise<IsolatedProducerResult>((resolve, reject) => {
+    let child: ChildProcess;
+    try {
+      child = spawn(process.execPath, ["run", CHILD_ENTRY], {
+        env: minimalChildEnv(request.scratchRoot),
+        stdio: ["pipe", "pipe", "pipe"],
+      });
+    } catch (error) {
+      reject(new FabricTaskError(
+        error instanceof Error ? error.message : String(error),
+        "harness_failure",
+        "harness",
+      ));
+      return;
+    }
+
+    let stdoutBuffer = "";
+    let stderrBytes = 0;
+    let settled = false;
+    let receivedResult: SyntheticPatchV1 | undefined;
+    let killReason: FabricTaskError | undefined;
+
+    const finish = (fn: () => void) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(totalTimer);
+      clearTimeout(inactivityTimer);
+      fn();
+    };
+
+    const settleTimeout = (error: FabricTaskError) => {
+      if (settled) return;
+      killReason = error;
+      killChild(child);
+    };
+
+    const armInactivity = () => {
+      clearTimeout(inactivityTimer);
+      inactivityTimer = setTimeout(() => {
+        settleTimeout(new FabricTaskError("inactivity timeout exceeded", "inactivity_timeout", "environment"));
+      }, request.inactivityTimeoutMs);
+    };
+
+    let inactivityTimer: ReturnType<typeof setTimeout> = setTimeout(() => {
+      settleTimeout(new FabricTaskError("inactivity timeout exceeded", "inactivity_timeout", "environment"));
+    }, request.inactivityTimeoutMs);
+
+    const totalTimer = setTimeout(() => {
+      settleTimeout(new FabricTaskError("total timeout exceeded", "timeout", "environment"));
+    }, request.totalTimeoutMs);
+
+    const handleProtocolLine = (line: string) => {
+      try {
+        const message = parseProducerProtocolLine(line);
+        if (message.type === "activity") {
+          lastActivityAt = now();
+          armInactivity();
+          return;
+        }
+        if (message.type === "result") {
+          if (settled) return;
+          receivedResult = message.patch;
+          finish(() => resolve({ patch: message.patch, lastActivityAt }));
+          return;
+        }
+        if (message.type === "error") {
+          const fabricCode = message.code === "inactivity_timeout"
+            ? "inactivity_timeout"
+            : message.code === "timeout"
+              ? "timeout"
+              : message.code === "sandbox_violation"
+                ? "sandbox_violation"
+                : message.code === "budget_exhausted"
+                  ? "budget_exhausted"
+                  : "harness_failure";
+          const attribution = message.attribution === "environment" ? "environment" : "harness";
+          const fabricError = new FabricTaskError(message.message, fabricCode, attribution);
+          finish(() => reject(fabricError));
+          killChild(child);
+          return;
+        }
+      } catch (error) {
+        settleTimeout(new FabricTaskError(
+          error instanceof Error ? error.message : String(error),
+          "harness_failure",
+          "harness",
+        ));
+      }
+    };
+
+    const consumeStdout = (chunk: string) => {
+      stdoutBuffer += chunk;
+      if (Buffer.byteLength(stdoutBuffer, "utf8") > FABRIC_PRODUCER_PROTOCOL_MAX_BYTES) {
+        settleTimeout(new FabricTaskError("producer protocol output exceeded limit", "budget_exhausted", "environment"));
+        stdoutBuffer = "";
+        return;
+      }
+      let newlineIdx = stdoutBuffer.indexOf("\n");
+      while (newlineIdx >= 0) {
+        const line = stdoutBuffer.slice(0, newlineIdx);
+        stdoutBuffer = stdoutBuffer.slice(newlineIdx + 1);
+        handleProtocolLine(line);
+        newlineIdx = stdoutBuffer.indexOf("\n");
+      }
+    };
+
+    child.stdout?.on("data", (chunk: Buffer | string) => {
+      consumeStdout(chunk.toString("utf8"));
+    });
+
+    child.stdout?.on("error", (error) => {
+      if (settled) return;
+      finish(() => reject(new FabricTaskError(error.message, "harness_failure", "harness")));
+    });
+
+    child.stderr?.on("data", (chunk: Buffer | string) => {
+      stderrBytes += Buffer.byteLength(chunk.toString("utf8"), "utf8");
+      if (stderrBytes > FABRIC_PRODUCER_STDERR_MAX_BYTES) {
+        stderrBytes = FABRIC_PRODUCER_STDERR_MAX_BYTES;
+      }
+    });
+
+    child.on("error", (error) => {
+      finish(() => reject(new FabricTaskError(error.message, "harness_failure", "harness")));
+    });
+
+    child.stdin?.on("error", (error: NodeJS.ErrnoException) => {
+      if (settled || error.code === "EPIPE") return;
+      killChild(child);
+      finish(() => reject(new FabricTaskError(error.message, "harness_failure", "harness")));
+    });
+
+    const payload = JSON.stringify({
+      harnessKind: request.harnessKind,
+      executorModulePath: request.executorModulePath,
+      scratchRoot: request.scratchRoot,
+      totalTimeoutMs: request.totalTimeoutMs,
+      inactivityTimeoutMs: request.inactivityTimeoutMs,
+      executorInput: request.executorInput
+        ? {
+            routeContext: request.executorInput.routeContext,
+            destination: request.executorInput.destination,
+            routeSubject: request.executorInput.routeSubject,
+            scratchRoot: request.executorInput.scratchRoot,
+          }
+        : undefined,
+    });
+    if (Buffer.byteLength(payload, "utf8") > FABRIC_PRODUCER_REQUEST_MAX_BYTES) {
+      killChild(child);
+      finish(() => reject(new FabricTaskError("producer request exceeds protocol limit", "budget_exhausted", "environment")));
+      return;
+    }
+
+    try {
+      child.stdin?.write(payload);
+      child.stdin?.end();
+    } catch (error) {
+      killChild(child);
+      finish(() => reject(new FabricTaskError(
+        error instanceof Error ? error.message : String(error),
+        "harness_failure",
+        "harness",
+      )));
+      return;
+    }
+
+    child.on("close", (code, signal) => {
+      if (settled) return;
+      if (killReason) {
+        finish(() => reject(killReason!));
+        return;
+      }
+      if (receivedResult) {
+        finish(() => resolve({ patch: receivedResult!, lastActivityAt }));
+        return;
+      }
+      if (stdoutBuffer.trim()) {
+        try {
+          handleProtocolLine(stdoutBuffer.trim());
+          if (receivedResult) return;
+        } catch {
+          /* fall through */
+        }
+      }
+      if (signal === "SIGKILL") {
+        finish(() => reject(new FabricTaskError("total timeout exceeded", "timeout", "environment")));
+        return;
+      }
+      finish(() => reject(new FabricTaskError(
+        code === 0 ? "isolated producer returned no result" : `isolated producer exited (${code ?? signal ?? "unknown"})`,
+        "harness_failure",
+        "harness",
+      )));
+    });
+  });
+}
+
+/** Internal test seam. Production callers cannot arm it without the test-home guard. */
+export function setFabricProducerIsolationLimitsForTests(limits?: FabricProducerIsolationLimits): void {
+  if (process.env.OCX_TEST_HOME_GUARD !== "1") {
+    throw new Error("fabric isolation limits can only be overridden by the test harness");
+  }
+  if (limits && (
+    !Number.isFinite(limits.totalTimeoutMs)
+    || !Number.isFinite(limits.inactivityTimeoutMs)
+    || limits.totalTimeoutMs <= 0
+    || limits.inactivityTimeoutMs <= 0
+    || limits.inactivityTimeoutMs >= limits.totalTimeoutMs
+  )) {
+    throw new Error("invalid fabric test isolation limits");
+  }
+  testIsolationLimits = limits ? { ...limits } : undefined;
+}
+
+/** Default isolation limits for fabric producer child processes. */
+export function fabricProducerIsolationLimits(): FabricProducerIsolationLimits {
+  if (testIsolationLimits) return { ...testIsolationLimits };
+  return {
+    totalTimeoutMs: FABRIC_LIMITS.totalTimeoutMs,
+    inactivityTimeoutMs: FABRIC_LIMITS.inactivityTimeoutMs,
+  };
+}

package/src/lab/fabric/producer-protocol.ts

@@ -0,0 +1,61 @@
+import type { SyntheticPatchV1 } from "./types";
+
+/** Maximum bytes accepted from child stdout for the fabric producer protocol. */
+export const FABRIC_PRODUCER_PROTOCOL_MAX_BYTES = 64 * 1024;
+
+/** Maximum stderr bytes retained for harness diagnostics. */
+export const FABRIC_PRODUCER_STDERR_MAX_BYTES = 4 * 1024;
+
+/** Maximum request payload size on child stdin. */
+export const FABRIC_PRODUCER_REQUEST_MAX_BYTES = 64 * 1024;
+
+export type ProducerChildMessage =
+  | { type: "activity" }
+  | { type: "result"; patch: SyntheticPatchV1 }
+  | { type: "error"; code: string; message: string; attribution: "harness" | "environment" };
+
+export interface ProducerParentRequest {
+  harnessKind?: string;
+  executorModulePath?: string;
+  scratchRoot: string;
+  executorInput?: unknown;
+  /** Parent-owned budgets are passed through so synthetic harness timing can scale in tests. */
+  totalTimeoutMs?: number;
+  inactivityTimeoutMs?: number;
+}
+
+export interface IsolatedProducerResult {
+  patch: SyntheticPatchV1;
+  lastActivityAt: number;
+}
+
+/** Serialize one protocol line to stdout (newline-delimited JSON). */
+export function encodeProducerProtocolLine(message: ProducerChildMessage): string {
+  return `${JSON.stringify(message)}\n`;
+}
+
+/** Parse one protocol line from the child. Malformed lines throw. */
+export function parseProducerProtocolLine(line: string): ProducerChildMessage {
+  const trimmed = line.trim();
+  if (!trimmed) {
+    throw new Error("empty protocol line");
+  }
+  const parsed = JSON.parse(trimmed) as ProducerChildMessage;
+  if (!parsed || typeof parsed !== "object" || typeof parsed.type !== "string") {
+    throw new Error("malformed protocol message");
+  }
+  switch (parsed.type) {
+    case "activity":
+      return { type: "activity" };
+    case "result":
+      if (!parsed.patch || typeof parsed.patch !== "object") throw new Error("malformed result patch");
+      return parsed as ProducerChildMessage;
+    case "error":
+      if (typeof parsed.code !== "string" || typeof parsed.message !== "string") {
+        throw new Error("malformed error message");
+      }
+      return parsed as ProducerChildMessage;
+    default:
+      throw new Error(`unknown protocol type: ${(parsed as { type: string }).type}`);
+  }
+}