@iislee/opencodex 2.11.0 → 2.35.0

package/src/codex/history-transition.ts

@@ -0,0 +1,105 @@
+/**
+ * Resolve the transition a history job belongs to.
+ *
+ * `updateCodexHistoryTransition` had no production caller, so every completed or
+ * skipped job left the coordinator row permanently `pending` — a transition was
+ * published and never resolved. This is that caller.
+ *
+ * The classification is `020_history_isolation.md:564-572`, applied rather than
+ * reinvented. The two unions do not line up one-to-one, so each outcome is
+ * mapped by hand: a cast across them would compile on the words they share and
+ * lie about the rest.
+ */
+import type { CodexHistoryJobOutcome } from "./history-job";
+import type { CodexHistoryState, CodexTransitionVersion } from "./convergence-types";
+import { updateCodexHistoryTransition } from "./transition-state";
+
+/** The retry budget for a contended terminal CAS. Bounded; never unbounded. */
+const TERMINAL_RETRY_ATTEMPTS = 3;
+const TERMINAL_RETRY_DELAY_MS = 250;
+
+function sleep(ms: number): void {
+  // The caller path here is synchronous after the awaited job, so a spin is the
+  // honest tool — awaiting would be, and this is short.
+  const until = Date.now() + ms;
+  while (Date.now() < until) { /* bounded */ }
+}
+
+function classify(outcome: CodexHistoryJobOutcome, txId: string | null): CodexHistoryState {
+  switch (outcome.kind) {
+    case "converged":
+      return {
+        status: "converged",
+        attempts: 1,
+        nextRetryAt: null,
+        txId,
+        // A zero is durable only when the worker proved the exact DB/manifest
+        // state while H was held. Without proof, keep the counts unknown. Keep
+        // `??`: `||` would discard a verified zero.
+        pendingRows: outcome.proof?.pendingRows ?? null,
+        backupEntries: outcome.proof?.backupEntries ?? null,
+      };
+    case "skipped":
+      // The user opting out is a completed decision, not a failure — converged
+      // with no reason. Marking it blocked would retry what they asked not to do.
+      return { status: "converged", attempts: 0, nextRetryAt: null, txId, pendingRows: null, backupEntries: null };
+    case "blocked":
+      return {
+        status: outcome.reason === "busy" ? "pending" : "blocked",
+        reason: outcome.reason === "busy" ? "db-busy"
+          : outcome.reason === "database" ? "unreadable"
+          : "permission",
+        attempts: 1,
+        // A busy unit retries; the others do not reschedule themselves.
+        nextRetryAt: outcome.reason === "busy"
+          ? new Date(Date.now() + TERMINAL_RETRY_DELAY_MS * 10).toISOString()
+          : null,
+        txId,
+        pendingRows: null,
+        backupEntries: null,
+      };
+    case "failed":
+      return {
+        status: "unknown",
+        reason: outcome.reason === "timeout" ? "timeout"
+          : outcome.reason === "worker-died" ? "worker-died"
+          : "record-write-failed",
+        attempts: 1,
+        nextRetryAt: null,
+        txId,
+        pendingRows: null,
+        backupEntries: null,
+      };
+  }
+}
+
+/**
+ * Publish the terminal state of a history job against the transition it belongs
+ * to. A `conflict` means a newer transition won and is deliberately left alone.
+ * A `busy` terminal CAS retries a bounded number of times; when that exhausts,
+ * the previously persisted `pending` schedule is left intact — the same update
+ * needs the lock that was busy, so it cannot record its own failure
+ * (`005_contract.md:277`), and the retry being out of attempts is itself a
+ * terminal observation.
+ */
+export function resolveCodexHistoryTransition(
+  receipt: CodexTransitionVersion,
+  outcome: CodexHistoryJobOutcome,
+): void {
+  const state = classify(outcome, receipt.currentTxId);
+  for (let attempt = 0; attempt < TERMINAL_RETRY_ATTEMPTS; attempt += 1) {
+    const result = updateCodexHistoryTransition(receipt, state);
+    if (result.kind === "updated") return;
+    if (result.kind === "conflict") {
+      // A newer transition already owns the row. Overwriting it would be the
+      // overtaken job overwriting the winner.
+      return;
+    }
+    if (result.reason === "busy") {
+      if (attempt + 1 < TERMINAL_RETRY_ATTEMPTS) sleep(TERMINAL_RETRY_DELAY_MS * (attempt + 1));
+      continue;
+    }
+    // database / unsafe-path: retried CAS will not help.
+    return;
+  }
+}

package/src/codex/history-worker.ts

@@ -0,0 +1,223 @@
+/**
+ * Worker-thread entry for the Codex history unit.
+ *
+ * Everything mutable about history happens here, behind H: the SQLite rows, the
+ * backup manifest, and every rollout patch. Those three do not share a
+ * transaction — sync writes the manifest before its database transaction, and
+ * restore preflights every rollout, applies database CAS before rollout changes inside one
+ * SQLite transaction, then consumes the manifest after exact readback — so a busy timeout only
+ * ever serialized a third of a state transition. Holding H across the whole unit
+ * is what stops an opposite-direction process overtaking through the other two.
+ *
+ * The message is deliberately thin, and it does NOT carry a direction. A caller
+ * saying which way history should move is exactly what the durable operation
+ * exists to prevent: `syncResumeHistory: false` means leave history alone, apply
+ * targets opencodex only in legacy mode, and legacy recovery is a different
+ * operation from generic restore. So the Worker is told which JOB to run and
+ * reads the operation from the coordinator row itself.
+ *
+ * Homes are carried explicitly because a Worker is a separate process: it does
+ * not inherit the module-load `CODEX_HOME` that `history-provider.ts` resolves
+ * at import time, so a request that leaned on those constants would silently
+ * address the wrong home.
+ *
+ * Design record: devlog/_fin/260804_codex_write_substrate/020_history_isolation.md.
+ */
+import { withHistoryWriteSerialization } from "./history-lock";
+import { loadConfig } from "../config";
+import { shouldSyncCodexOnStart } from "./desired-state";
+import {
+  writeHistoryProviderTransition,
+  writeLegacyOpenaiHistoryRecovery,
+  type HistoryWriteTarget,
+} from "./internal/history-writer";
+import {
+  snapshotCodexHistoryNoop,
+  type CodexHistoryFailureReason,
+  type CodexHistoryVerifiedNoopProof,
+} from "./history-provider";
+
+/**
+ * The durable operation, mirrored into the request for diagnostics only.
+ *
+ * The Worker validates this against what it reads and refuses a mismatch rather
+ * than trusting it — a tampered copy must not be able to turn a restore into an
+ * apply. Structured-clone safe by construction: a closed set of string literals.
+ */
+export type CodexHistoryWorkerOperation =
+  | "skip"
+  | "apply-opencodex"
+  | "migrate-openai"
+  | "restore-openai"
+  | "recover-legacy-openai";
+
+export interface HistoryWorkerRunMessage {
+  readonly type: "run";
+  readonly requestId: string;
+  /** Opaque durable job identity; the Worker refuses work that is not current. */
+  readonly jobId: string;
+  readonly operation: CodexHistoryWorkerOperation;
+  readonly canonicalCodexHome: string;
+  readonly canonicalStateDbPath: string;
+  readonly canonicalBackupPath: string;
+  /** When set, prove this transition's desired direction while H is held. */
+  readonly expectedDesiredEnabled?: boolean;
+  /** Env snapshot: a Worker may not observe parent mutations on every platform. */
+  readonly env?: { readonly CODEX_HOME?: string; readonly OPENCODEX_HOME?: string };
+}
+
+export type HistoryWorkerResult =
+  | { readonly type: "done"; readonly requestId: string; readonly jobId: string;
+      readonly outcome: "converged" | "skipped";
+      readonly rows: number; readonly files: number;
+      readonly proof?: CodexHistoryVerifiedNoopProof }
+  | { readonly type: "blocked"; readonly requestId: string; readonly jobId: string;
+      readonly reason: "busy" | "database" | "unsafe-path" | "desired_disabled" | "desired_enabled" }
+  | { readonly type: "error"; readonly requestId: string; readonly jobId: string;
+      readonly message: string; readonly reason?: CodexHistoryFailureReason;
+      readonly rows?: number; readonly files?: number };
+
+const OPERATIONS: ReadonlySet<string> = new Set<CodexHistoryWorkerOperation>([
+  "skip",
+  "apply-opencodex",
+  "migrate-openai",
+  "restore-openai",
+  "recover-legacy-openai",
+]);
+
+/**
+ * Validate the message before it can reach a writer.
+ *
+ * A malformed message is dropped rather than coerced. Every field is required
+ * and non-empty: an absent path would otherwise fall back to a module-load
+ * constant that points at the wrong home in this process.
+ */
+export function isHistoryWorkerRunMessage(data: unknown): data is HistoryWorkerRunMessage {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return false;
+  const message = data as Record<string, unknown>;
+  const nonEmpty = (value: unknown): value is string =>
+    typeof value === "string" && value.trim().length > 0;
+  return message.type === "run"
+    && nonEmpty(message.requestId)
+    && nonEmpty(message.jobId)
+    && typeof message.operation === "string"
+    && OPERATIONS.has(message.operation)
+    && nonEmpty(message.canonicalCodexHome)
+    && nonEmpty(message.canonicalStateDbPath)
+    && nonEmpty(message.canonicalBackupPath)
+    && (message.expectedDesiredEnabled === undefined || typeof message.expectedDesiredEnabled === "boolean");
+}
+
+/**
+ * Run one history operation under H.
+ *
+ * Exported so the unit can be exercised in-process; the Worker entry below is a
+ * thin adapter over it. `skip` is a real outcome rather than an absence: opting
+ * out of history resume must be recorded, not inferred from nothing happening.
+ */
+export function runHistoryUnitUnderLock(
+  message: HistoryWorkerRunMessage,
+): HistoryWorkerResult {
+  const { requestId, jobId, operation } = message;
+  const target: HistoryWriteTarget = {
+    canonicalStateDbPath: message.canonicalStateDbPath,
+    canonicalBackupPath: message.canonicalBackupPath,
+  };
+
+  if (operation === "skip") {
+    return { type: "done", requestId, jobId, outcome: "skipped", rows: 0, files: 0 };
+  }
+
+  const acquired = withHistoryWriteSerialization(
+    message.canonicalCodexHome,
+    message.canonicalStateDbPath,
+    permit => {
+      if (message.expectedDesiredEnabled !== undefined
+        && shouldSyncCodexOnStart(loadConfig()) !== message.expectedDesiredEnabled) {
+        return { desiredStateChanged: true as const };
+      }
+      if (operation === "recover-legacy-openai") {
+        return writeLegacyOpenaiHistoryRecovery(permit, target);
+      }
+      if (operation === "migrate-openai") {
+        const proof = snapshotCodexHistoryNoop(message.canonicalStateDbPath, message.canonicalBackupPath);
+        if (proof.kind === "verified-noop") return { verifiedNoop: proof } as const;
+      }
+      // apply-opencodex routes history to opencodex; migrate/restore recover only
+      // manifest-backed original metadata. The provider is derived from the operation,
+      // never from a caller; only recover-legacy-openai force-labels bare routed rows.
+      const provider = operation === "apply-opencodex" ? "opencodex" : "openai";
+      return writeHistoryProviderTransition(permit, target, provider);
+    },
+  );
+
+  if (acquired.kind !== "completed") {
+    return { type: "blocked", requestId, jobId, reason: acquired.reason };
+  }
+  const result = acquired.value;
+  if ("desiredStateChanged" in result) {
+    return {
+      type: "blocked",
+      requestId,
+      jobId,
+      reason: message.expectedDesiredEnabled ? "desired_disabled" : "desired_enabled",
+    };
+  }
+  if ("verifiedNoop" in result) {
+    return {
+      type: "done",
+      requestId,
+      jobId,
+      outcome: "converged",
+      rows: 0,
+      files: 0,
+      proof: result.verifiedNoop,
+    };
+  }
+  if (result.failed === true) {
+    return {
+      type: "error",
+      requestId,
+      jobId,
+      message: "history_transition_failed",
+      ...(result.failureReason ? { reason: result.failureReason } : {}),
+      ...(result.rows > 0 || result.files > 0 ? { rows: result.rows, files: result.files } : {}),
+    };
+  }
+  return {
+    type: "done",
+    requestId,
+    jobId,
+    outcome: "converged",
+    rows: result.rows,
+    files: result.files,
+  };
+}
+
+declare const self: Worker;
+
+// Guarded so the module can be imported directly by tests without a Worker host.
+if (typeof self !== "undefined" && typeof (self as { onmessage?: unknown }) === "object") {
+  self.onmessage = (event: MessageEvent<unknown>) => {
+    if (!isHistoryWorkerRunMessage(event.data)) return;
+    const message = event.data;
+    try {
+      if (message.env?.CODEX_HOME) process.env.CODEX_HOME = message.env.CODEX_HOME;
+      if (message.env?.OPENCODEX_HOME) process.env.OPENCODEX_HOME = message.env.OPENCODEX_HOME;
+      self.postMessage(runHistoryUnitUnderLock(message));
+    } catch (error) {
+      self.postMessage({
+        type: "error",
+        requestId: message.requestId,
+        jobId: message.jobId,
+        message: error instanceof Error ? error.message : "history_worker_failed",
+      } satisfies HistoryWorkerResult);
+    } finally {
+      // Close from inside the Worker so the thread begins exiting before the
+      // parent's terminate() races isolate realm reclaim on Windows.
+      try {
+        (self as unknown as { close?: () => void }).close?.();
+      } catch { /* already closing */ }
+    }
+  };
+}