@iislee/opencodex 2.11.0 → 2.31.0

package/src/codex/history-worker.ts

@@ -0,0 +1,220 @@
+/**
+ * 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 writes rollouts, then the database, then the manifest
+ * (`src/codex/history-provider.ts:606-648,656-698`) — 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 };
+
+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 return it to
+      // native. The provider is derived from the operation, never from a caller.
+      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 } : {}),
+    };
+  }
+  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 */ }
+    }
+  };
+}

package/src/codex/inject-coordination.ts

@@ -0,0 +1,290 @@
+/**
+ * Coordination helpers for the native Codex write section.
+ *
+ * Split out of `inject.ts` so the injection function keeps reading as the
+ * sequence it is, rather than doubling in length around the lock.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, readFileSync } from "node:fs";
+
+import { atomicWriteFile } from "../config";
+import type { CodexWriteLockResult } from "./codex-write-lock";
+import { inspectCodexCoordinatorPath } from "./coordinator-doctor";
+import { JOURNAL_PATH } from "./journal";
+import { CODEX_CONFIG_PATH, CODEX_PROFILE_PATH } from "./paths";
+import {
+  codexWriteCoordination,
+  type CodexWriteCandidate,
+  type CodexWriteCoordination,
+  type CodexWriteEvidence,
+} from "./write-coordination";
+
+/** Bounded so a stuck holder cannot wedge `ocx start` indefinitely. */
+export const DEFAULT_INJECT_LOCK_TIMEOUT_MS = 5_000;
+
+/**
+ * Can this home be coordinated at all, decided BEFORE any lock attempt?
+ *
+ * The order matters and is not stylistic. `assertInitialStateCanBeCreated`
+ * refuses to create the first coordinator row while native routing residue
+ * exists (`transition-state.ts:268-280`) — correctly, because installing
+ * `{0,null}` over routed bytes would erase the only evidence that an
+ * interrupted transition needs salvage. But "already routed, no coordinator
+ * row" is the state of every install predating this substrate, so a "try the
+ * lock, fall back on refusal" shape would attempt acquisition on the entire
+ * installed base. Deciding first means that refusal path is never entered.
+ *
+ * `legacy-uncoordinated` is a temporary boundary, not a design: the
+ * compatibility-adoption contract (`005_contract.md:709-779`) records an
+ * existing routed home into the coordinator, and once that lands this branch
+ * narrows to homes not yet adopted.
+ */
+export type CodexWriteCoordinationEligibility =
+  | { kind: "coordinated" }
+  | { kind: "legacy-uncoordinated"; reason: string }
+  | { kind: "refused"; reason: string };
+
+/**
+ * A live SQLite creator exposes a zero-byte pathname before BEGIN IMMEDIATE.
+ * Requiring a settled filesystem age makes that scheduling window remain on
+ * the coordinated path while old crash remnants can use the legacy boundary.
+ */
+export const STABLE_ZERO_BYTE_COORDINATOR_AGE_MS = 1_000;
+
+export function codexWriteCoordinationEligibility(deps: {
+  coordinatorPath: () => string;
+  residue: () => { kind: string };
+  integrationRecord: () => { kind: string };
+  nowMs?: () => number;
+}): CodexWriteCoordinationEligibility {
+  let coordinatorExists: boolean;
+  let coordinatorIsStableZeroByte = false;
+  try {
+    const path = deps.coordinatorPath();
+    coordinatorExists = existsSync(path);
+    if (coordinatorExists) {
+      const entry = lstatSync(path);
+      if (entry.isFile() && !entry.isSymbolicLink() && entry.size === 0) {
+        const diagnostic = inspectCodexCoordinatorPath(path);
+        if (diagnostic.kind === "zero-byte") {
+          const lastIdentityChange = Math.max(diagnostic.identity.mtimeMs, diagnostic.identity.ctimeMs);
+          coordinatorIsStableZeroByte = (deps.nowMs?.() ?? Date.now()) - lastIdentityChange
+            >= STABLE_ZERO_BYTE_COORDINATOR_AGE_MS;
+        }
+      }
+    }
+  } catch (error) {
+    return { kind: "refused", reason: `the coordinator path could not be resolved: ${String(error)}` };
+  }
+
+  // Every existing coordinator remains authoritative unless it is proven to be
+  // an old, immutable SQLite-empty remnant. The age gate is part of that proof:
+  // a live creator exposes the same zero-byte pathname briefly before taking N,
+  // and sending that fresh file down the legacy path would bypass its lock.
+  // Non-empty, fresh, unsafe, changed, unversioned, and rowless files therefore
+  // stay coordinated and are validated/refused by the transaction owner.
+  //
+  // We do NOT initialize or adopt it here. Clean homes still enter the
+  // coordinated path, whose SQLite transaction safely initializes it. Routed
+  // or indeterminate legacy homes keep the same uncoordinated compatibility
+  // boundary they would have had if the remnant pathname were absent.
+  if (coordinatorExists && !coordinatorIsStableZeroByte) return { kind: "coordinated" };
+
+  const record = deps.integrationRecord();
+  if (record.kind === "invalid") {
+    return { kind: "refused", reason: "the Codex integration record is invalid" };
+  }
+
+  const residue = deps.residue();
+  if (residue.kind === "clean") return { kind: "coordinated" };
+  /*
+   * Everything else keeps the path it has always had.
+   *
+   * `residue` is a pre-substrate routed home; `indeterminate` means the
+   * classifier could not read what is there — a profile it cannot parse, for
+   * instance, which is an ordinary re-injection over an older file rather than
+   * a hazard.
+   *
+   * Neither may CREATE a coordinator row: doing that over unclassified or
+   * routed bytes would erase the evidence an interrupted transition needs. But
+   * refusing the injection outright, which an earlier draft of this function
+   * did for `indeterminate`, breaks re-injection on homes that work today —
+   * caught by the shipped restore tests rather than by review. Declining to
+   * coordinate is the correct scope of the refusal; declining to write is not.
+   */
+  return {
+    kind: "legacy-uncoordinated",
+    reason: coordinatorIsStableZeroByte
+      ? "the coordinator is a zero-byte non-authoritative remnant and this routed home has not been adopted yet"
+      : residue.kind === "residue"
+      ? "this home was routed before write coordination existed and has not been adopted yet"
+      : "the existing native Codex state could not be classified, so it cannot seed a coordinator row",
+  };
+}
+
+/** The transition row rejected this publication; a conflict, not an exception. */
+export class CodexWriteConflictError extends Error {
+  readonly code = "CODEX_WRITE_CONFLICT";
+  constructor(message: string) {
+    super(message);
+    this.name = "CodexWriteConflictError";
+  }
+}
+
+/**
+ * A write failed AND its compensation failed.
+ *
+ * Carries which surfaces are unrestored, never their contents — this reaches
+ * logs and HTTP responses, and config bytes carry credentials.
+ */
+export class CodexPartialWriteError extends Error {
+  readonly code = "CODEX_PARTIAL_WRITE";
+  constructor(readonly unrestored: readonly string[]) {
+    super(`Native Codex files are in a partial state; unrestored: ${unrestored.join(", ")}.`);
+    this.name = "CodexPartialWriteError";
+  }
+}
+
+function contentIdentity(path: string): string {
+  try {
+    return createHash("sha256").update(readFileSync(path)).digest("hex").slice(0, 32);
+  } catch {
+    return existsSync(path) ? "unreadable" : "absent";
+  }
+}
+
+export interface CodexPreImages {
+  readonly config: string | null;
+  readonly profile: string | null;
+  readonly journal: string | null;
+}
+
+/** `null` means the file was ABSENT, which restoration must reproduce exactly. */
+function readOrNull(path: string): string | null {
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+export function captureCodexPreImages(): CodexPreImages {
+  return {
+    config: readOrNull(CODEX_CONFIG_PATH),
+    profile: readOrNull(CODEX_PROFILE_PATH),
+    journal: readOrNull(JOURNAL_PATH),
+  };
+}
+
+/**
+ * Put back exactly what was there, and report honestly when that fails.
+ *
+ * Every surface is attempted even after one fails: a second failure is worth
+ * knowing about, and stopping early would leave more unrestored than necessary.
+ */
+export function restoreCodexPreImages(
+  pre: CodexPreImages,
+): { complete: boolean; unrestored: readonly string[] } {
+  const unrestored: string[] = [];
+  const surfaces: readonly [string, string, string | null][] = [
+    ["config", CODEX_CONFIG_PATH, pre.config],
+    ["profile", CODEX_PROFILE_PATH, pre.profile],
+    ["journal", JOURNAL_PATH, pre.journal],
+  ];
+  for (const [name, path, bytes] of surfaces) {
+    try {
+      if (bytes === null) {
+        // Absent before, so absent after. A leftover file is not a restoration.
+        if (existsSync(path)) require("node:fs").unlinkSync(path);
+      } else if (readOrNull(path) !== bytes) {
+        atomicWriteFile(path, bytes);
+      }
+    } catch {
+      unrestored.push(name);
+    }
+  }
+  return { complete: unrestored.length === 0, unrestored };
+}
+
+export function buildInjectWitness(
+  candidate: CodexWriteCandidate,
+  nativeInput: string,
+  persistedIdentity: string,
+  generation: CodexWriteEvidence["generation"],
+  observedOwnership: CodexWriteCoordination["observedOwnership"],
+): CodexWriteCoordination {
+  return codexWriteCoordination(
+    candidate,
+    {
+      nativeInputIdentity: createHash("sha256").update(nativeInput).digest("hex"),
+      persistedIdentity,
+      generation,
+      journalIdentity: contentIdentity(JOURNAL_PATH),
+      canonicalTargets: {
+        config: CODEX_CONFIG_PATH,
+        profile: CODEX_PROFILE_PATH,
+        journal: JOURNAL_PATH,
+      },
+    },
+    observedOwnership,
+  );
+}
+
+/**
+ * The under-lock re-read.
+ *
+ * The candidate bytes are fixed — they were computed before acquisition and do
+ * not change — so what is re-read is the EVIDENCE: the native input on disk, the
+ * journal, the generation from the open transaction. A comparison that copied
+ * those forward would match itself and prove nothing.
+ */
+export function recomputeInjectWitness(options: {
+  candidate: CodexWriteCandidate;
+  canonicalTargets: CodexWriteEvidence["canonicalTargets"];
+  persistedIdentity: string;
+  generation: CodexWriteEvidence["generation"];
+  observedOwnership: CodexWriteCoordination["observedOwnership"];
+}): CodexWriteCoordination {
+  const nativeInput = readOrNull(options.canonicalTargets.config) ?? "";
+  return codexWriteCoordination(
+    options.candidate,
+    {
+      nativeInputIdentity: createHash("sha256").update(nativeInput).digest("hex"),
+      persistedIdentity: options.persistedIdentity,
+      generation: options.generation,
+      journalIdentity: contentIdentity(options.canonicalTargets.journal),
+      canonicalTargets: options.canonicalTargets,
+    },
+    options.observedOwnership,
+  );
+}
+
+/** Project a non-acquired lock result into the injection result shape. */
+export function codexInjectLockOutcome(
+  result: Exclude<CodexWriteLockResult<unknown>, { status: "acquired" }>,
+): { success: false; message: string; retryable: boolean } | {
+  success: true; status: "skipped"; skippedReason: "desired_disabled" | "desired_enabled"; message: string;
+} {
+  if (result.status === "skipped") {
+    return {
+      success: true,
+      status: "skipped",
+      skippedReason: result.reason,
+      message: result.reason === "desired_disabled"
+        ? "Codex integration is OFF; no Codex config, catalog, cache, or history was changed."
+        : "Codex integration was re-enabled; native restore was skipped.",
+    };
+  }
+  if (result.status === "busy") {
+    return {
+      success: false,
+      retryable: true,
+      message: `Another process is writing Codex configuration right now (waited ${result.waitedMs}ms). Retry shortly.`,
+    };
+  }
+  return {
+    success: false,
+    retryable: false,
+    message: `Codex configuration was not written: ${result.message}`,
+  };
+}