@bitkyc08/opencodex 2.15.1 → 2.16.0

package/src/integrations/omp-yaml-source.ts

@@ -200,7 +200,12 @@ export function patchOmpYamlSource(
 
   let patched = `${text.slice(0, startOffset)}${text.slice(endOffset)}`;
   if (mutation.removeEmptyProviders) {
-    const remaining = Bun.YAML.parse(patched) as { providers?: unknown } | null;
+    let remaining: { providers?: unknown } | null;
+    try {
+      remaining = Bun.YAML.parse(patched) as { providers?: unknown } | null;
+    } catch {
+      return null;
+    }
     if (remaining && Object.hasOwn(remaining, "providers")) {
       const provider = remaining.providers;
       const empty = provider === null || (

package/src/integrations/serialize.ts

@@ -221,10 +221,89 @@ export function renderToml(document: Record<string, unknown>, prefix = ""): stri
   return `${[scalars.join("\n"), tables.join("\n\n")].filter(Boolean).join("\n\n")}\n`;
 }
 
+/**
+ * Ceiling on container nesting for json documents, shared by the parse-time
+ * scanner (config-io.ts) and the serializer walk below. One constant on
+ * purpose: the walk must accept every document the scanner admits, or a file
+ * the classifier reported as recoverable would refuse at rewrite time. Real
+ * configs nest a handful of levels.
+ */
+export const MAX_JSON_NESTING = 1000;
+
+/** Error messages carry the path to the offending value; keep them readable. */
+function clampPath(path: string): string {
+  return path.length > 200 ? `${path.slice(0, 100)}…${path.slice(-100)}` : path;
+}
+
+/**
+ * JSON.stringify writes a non-finite number as `null` and -0 as `0`; any
+ * other finite double round-trips value-exactly (literal-level rounding is
+ * the parse-time scanner's concern), so those two are exactly what this walk
+ * refuses — refusing more turned a state the classifier had promised as
+ * recoverable into a permanent refusal. Documents read from disk are already
+ * guarded at parse time, and the writer's merge layer JSON-clones documents —
+ * normalizing these values — before serializing, so on the apply/disable path
+ * this walk is unreachable for them: it guards the direct serializers
+ * (preview/export builders), same posture as the YAML and TOML renderers
+ * above, and enforces the nesting ceiling for every json caller before the
+ * recursive JSON.stringify can turn depth into a RangeError.
+ *
+ * Iterative frames instead of recursion or a node stack: depth AND size of
+ * the document are inputs under the writer of the config file. Recursion made
+ * a deep file a RangeError-500; materializing every node with its path made a
+ * wide file allocate a large multiple of its size. Frames keep memory
+ * proportional to nesting depth, and path strings exist only for the
+ * containers on the current path plus the failing value itself.
+ */
+function assertJsonNumbersRoundTrip(document: unknown, rootPath: string): void {
+  const refuse = (value: number, path: string): never => {
+    throw new UnserializableValueError(Object.is(value, -0)
+      ? `JSON cannot rewrite -0 at ${clampPath(path)} without changing it to 0`
+      : `JSON cannot rewrite the number at ${clampPath(path)} without changing it to null`);
+  };
+  if (typeof document === "number" && (!Number.isFinite(document) || Object.is(document, -0))) {
+    refuse(document, rootPath);
+  }
+  type Frame = { container: unknown; keys: string[] | null; index: number; prefix: string };
+  const frames: Frame[] = [];
+  const pushContainer = (value: unknown, prefix: string) => {
+    if (Array.isArray(value)) frames.push({ container: value, keys: null, index: 0, prefix });
+    else if (isPlainRecord(value)) frames.push({ container: value, keys: Object.keys(value), index: 0, prefix });
+  };
+  pushContainer(document, rootPath);
+  while (frames.length > 0) {
+    const frame = frames[frames.length - 1]!;
+    const length = frame.keys ? frame.keys.length : (frame.container as unknown[]).length;
+    if (frame.index >= length) { frames.pop(); continue; }
+    const i = frame.index;
+    frame.index += 1;
+    const child = frame.keys
+      ? (frame.container as Record<string, unknown>)[frame.keys[i]!]
+      : (frame.container as unknown[])[i];
+    const childPath = () => frame.keys
+      ? (frame.prefix === "$" ? frame.keys[i]! : `${frame.prefix}.${frame.keys[i]!}`)
+      : `${frame.prefix}[${i}]`;
+    if (typeof child === "number") {
+      if (!Number.isFinite(child) || Object.is(child, -0)) refuse(child, childPath());
+      continue;
+    }
+    if (typeof child === "object" && child !== null) {
+      if (frames.length >= MAX_JSON_NESTING) {
+        throw new UnserializableValueError(
+          `the document nests deeper than ${MAX_JSON_NESTING} levels at ${clampPath(childPath())}, which JSON serialization cannot rewrite safely`);
+      }
+      pushContainer(child, childPath());
+    }
+  }
+}
+
 /** Every serializer returns text ending in exactly one newline. */
 export function serializeDocument(document: unknown, format: ConfigFormat): string {
   switch (format) {
-    case "json": return `${JSON.stringify(document, null, 2)}\n`;
+    case "json": {
+      assertJsonNumbersRoundTrip(document, "$");
+      return `${JSON.stringify(document, null, 2)}\n`;
+    }
     case "json5": return `${Bun.JSON5.stringify(document, null, 2)}\n`;
     case "yaml": return renderYaml(document);
     case "toml": {

package/src/integrations/state.ts

@@ -134,9 +134,15 @@ function recordedFragmentFingerprint(
 /**
  * The two-axis rule: the recorded bytes or fragments prove nobody changed
  * what we may rewrite, and the contribution hash proves our catalog has not
- * moved on. OMP is the sole fragment-scoped client because its writer patches
- * only `providers.opencodex`; every whole-document serializer retains the
- * whole-file fingerprint guard.
+ * moved on. Three classes of client (revising the unconditional whole-file
+ * rule of devlog 260802_client_toggle_api/021 §3 for json — #1631):
+ * OMP is fragment-scoped because its writer patches only
+ * `providers.opencodex`, so the whole-file check is skipped entirely;
+ * strict-json clients keep the whole-file check but downgrade a drift with
+ * intact owned fragments to `stale`, because a rewrite there can lose only
+ * formatting (comments cannot parse, non-round-tripping numbers are refused
+ * by the serializer); every comment-capable whole-document serializer (yaml,
+ * json5, toml) retains the whole-file fingerprint guard as a hard conflict.
  */
 export function classifyIntegration(input: {
   fileText: string | null;
@@ -180,12 +186,37 @@ export function classifyIntegration(input: {
     return { state: "conflict", reason: "unowned-key" };
   }
   const clientId = input.clientId ?? input.record.clientId;
-  if (clientId !== "omp" && fingerprint(input.fileText ?? "") !== input.record.fileFingerprint) {
-    return { state: "conflict", reason: "foreign-edit" };
-  }
+  /*
+   * Checked BEFORE file-level drift: an edit INSIDE an owned fragment is a
+   * conflict no matter what the rest of the file looks like, so the sibling-
+   * edit exemption below can never mask it.
+   */
   if (recordedFragmentFingerprint(input.parsed, input.record) !== input.record.blockFingerprint) {
     return { state: "conflict", reason: "foreign-edit" };
   }
+  if (clientId !== "omp" && fingerprint(input.fileText ?? "") !== input.record.fileFingerprint) {
+    /*
+     * The file changed since we wrote it, but every fragment we own is still
+     * byte-for-byte what we put there — a sibling edit, not tampering. Apply
+     * rewrites the WHOLE document, so for comment-capable formats (yaml,
+     * json5, toml) it would drop comments the user wrote next to us: fail
+     * closed there. Strict JSON cannot carry comments — a commented file
+     * never reaches this branch because parsing already failed — so the only
+     * possible loss is formatting normalization: everything a rewrite would
+     * actually change (numbers that would not round-trip, duplicate members
+     * a rewrite would delete) is PARSE_FAILED in parseConfig and classifies
+     * as unsafe long before this branch, exactly like comments. Refusing
+     * forever over formatting
+     * dead-ends the integration on the user's first own config edit (#1631).
+     * Report drift instead; a re-apply merges into the parsed document as it
+     * stands and re-owns the file. This also lets disable proceed on a
+     * drifted file — removal still touches only the recorded fragment paths.
+     */
+    if (EXPORT_CLIENTS[clientId].format !== "json") {
+      return { state: "conflict", reason: "foreign-edit" };
+    }
+    return { state: "stale" };
+  }
   return input.record.blockFingerprint === fingerprint(canonicalContribution(input.contribution))
     ? { state: "current" }
     : { state: "stale" };

package/src/integrations/writer.ts

@@ -213,7 +213,8 @@ function preflight(input: IntegrationWriteInput) {
   const before = target.before;
   const parsed = parseConfig(before, exportSpec.format);
   if (parsed === PARSE_FAILED) {
-    return { failed: refuse(clientId, "unsafe", "unsafe", `${configPath} could not be parsed`) } as const;
+    return { failed: refuse(clientId, "unsafe", "unsafe",
+      `${configPath} could not be parsed, or holds something opencodex cannot rewrite without changing it (a non-finite number, a large integer or a tiny one a rewrite would round, -0, a duplicate member, or nesting deeper than 1000 levels)`) } as const;
   }
   const contribution = exportSpec.buildContribution(exportContextOf(input));
   // A record proves ownership of the file it was written FOR. Matching only by
@@ -368,8 +369,15 @@ export function disableIntegration(input: IntegrationWriteInput): WriteOutcome {
         : `${configPath} cannot be changed safely`);
   }
 
-  // current | stale only: the file fingerprint still matches our record, so the
-  // recorded paths are exactly what we put there.
+  /*
+   * current | stale only. What makes the removal safe is the BLOCK
+   * fingerprint, not the file fingerprint: the classifier verified the values
+   * at the recorded paths are byte-for-byte what we wrote, so removing them
+   * cannot take a user edit with them. The file itself may have drifted — a
+   * json client classifies a sibling edit as stale (#1631) — which is why the
+   * removal runs against the document as parsed NOW, and the re-serialize is
+   * value-safe because non-round-tripping numbers were refused at parse time.
+   */
   const { doc, removed } = removeFragments(
     parsed,
     record!.fragmentPaths,

package/src/lab/automation/orchestrator.ts

@@ -1,5 +1,6 @@
 import { readConfigDiagnostics } from "../../config";
 import { registerCurrentServerResourceCleanup } from "../../lib/server-resource-ownership";
+import { registerOptionalShutdownHook } from "../../lib/optional-shutdown-hooks";
 import { queryLabStatus } from "../query";
 import { rebuildLabProjection } from "../projection/rebuild";
 import { planLabAutomationRuns } from "./planner";
@@ -90,10 +91,12 @@ export function setLabAutomationDispatchDeps(deps: AutomationDispatchDeps): () =
 
   let released = false;
   let detachServerCleanup = () => {};
+  let detachShutdownHook = () => {};
   const release = () => {
     if (released) return;
     released = true;
     detachServerCleanup();
+    detachShutdownHook();
     const current = dispatchDepsByConfigDir.get(key);
     if (current?.token !== token) return;
     dispatchDepsByConfigDir.delete(key);
@@ -104,6 +107,13 @@ export function setLabAutomationDispatchDeps(deps: AutomationDispatchDeps): () =
     }
   };
   detachServerCleanup = registerCurrentServerResourceCleanup(release);
+  // Shutdown teardown is registered here, at activation, so `server/lifecycle.ts` never has
+  // to import Lab in order to stop it. Scoped to this configDir, unlike the previous
+  // unscoped call from the shutdown path.
+  detachShutdownHook = registerOptionalShutdownHook(`lab-automation:${key}`, () => {
+    requestLabAutomationShutdown();
+    stopLabAutomationScheduler(deps.configDir);
+  });
   return release;
 }
 
@@ -399,6 +409,15 @@ export function startLabAutomationScheduler(configDir?: string): void {
     if (currentOwner) existing.ownerToken = currentOwner;
     return;
   }
+  // The scheduler owns a live interval, so its teardown must be registered here rather
+  // than only in setLabAutomationDispatchDeps: the management API and the CLI can start a
+  // scheduler without ever installing dispatch deps (lab-automation-routes.ts
+  // applySchedulerPolicy, cli/lab.ts), and core no longer imports this module to stop it.
+  // Without this registration such a scheduler survives drainAndShutdown.
+  registerOptionalShutdownHook(`lab-automation-scheduler:${key}`, () => {
+    requestLabAutomationShutdown();
+    stopLabAutomationScheduler(configDir);
+  });
   shutdownRequested = false;
   const { policy, routes } = loadLabAutomationConfig(configDir);
   const now = Date.now();

package/src/lib/lab-activation.ts

@@ -0,0 +1,161 @@
+/**
+ * Compatibility Lab activation.
+ *
+ * The proxy core does not import Lab. This module is the seam that does, and the startup
+ * composition root calls it only when the install actually uses Lab, so a user with no
+ * routing profile and no automation executes no Lab code and starts no Lab timer.
+ *
+ * Activation is SYNCHRONOUS by design. Three audit rounds established that a deferred
+ * activation window is unpatchable: `routeModelInternal` is sync, and so is the
+ * subagent-fallback chain that calls `routeModel`, so those callers have nowhere to await.
+ * During such a window a policy alias would be silently dropped from a fallback chain and
+ * the subagent would run on a different model than the operator configured. Registration
+ * therefore completes before `startServer` returns, inside the same synchronous turn as
+ * `Bun.serve`, so no request can observe an unregistered slot.
+ *
+ * See devlog/_plan/260814_lab_core_decoupling/080_activation_is_synchronous.md
+ *
+ * Startup degrades, explicit operator action reports. This asymmetry is deliberate: an
+ * invalid automation config disables automation with a warning here, but the management
+ * API and CLI paths that start a scheduler leave `LabAutomationError` to surface (the
+ * management route maps it to a 400). Someone who just toggled automation should see the
+ * validation error; someone merely starting the proxy should not lose unrelated traffic.
+ *
+ * @internal host integration only
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { labAutomationPolicyPath } from "../lab/paths";
+import type { OcxConfig } from "../types";
+import { LabAutomationError } from "../lab/automation/types";
+import { registerLabPassiveRouteLinker } from "./lab-passive-linker-registration";
+import { setCompatibilityEvidenceProvider } from "../routing/compatibility/provider-slot";
+import { labCompatibilityEvidenceProvider } from "../routing/compatibility/lab-evidence-provider";
+import {
+  setLabAutomationDispatchDeps,
+  startLabAutomationScheduler,
+} from "../lab/automation/orchestrator";
+import { createProductionLabRouteExecutor } from "./lab-live-route-production";
+
+/** Activation records keyed by configDir, so one process can own several configs. */
+const activated = new Map<string, Array<() => void>>();
+
+const activationKey = (configDir?: string): string => configDir ?? "";
+
+function readJsonIfPresent(path: string): unknown {
+  try {
+    if (!existsSync(path)) return null;
+    return JSON.parse(readFileSync(path, "utf8")) as unknown;
+  } catch {
+    // A malformed or unreadable file means "not enabled": this detector must never throw
+    // during startup, and must never import Lab persistence to answer the question.
+    return null;
+  }
+}
+
+/**
+ * True when Lab automation is enabled on disk.
+ *
+ * Mirrors `loadLabAutomationConfig` precedence deliberately: the current authority is the
+ * combined `automation-config.json`, with `automation-policy.json` as the legacy fallback.
+ * Reading only the legacy file would miss every install that enabled automation through
+ * the current dashboard.
+ */
+export function labAutomationEnabledOnDisk(configDir?: string): boolean {
+  const legacyPath = labAutomationPolicyPath(configDir);
+  const combined = readJsonIfPresent(join(dirname(legacyPath), "automation-config.json"));
+  if (combined && typeof combined === "object") {
+    const policy = (combined as { policy?: unknown }).policy;
+    if (policy && typeof policy === "object") {
+      return (policy as { enabled?: unknown }).enabled === true;
+    }
+  }
+  const legacy = readJsonIfPresent(legacyPath);
+  if (legacy && typeof legacy === "object") {
+    return (legacy as { enabled?: unknown }).enabled === true;
+  }
+  return false;
+}
+
+/** True when this install actually uses Lab: any routing profile, or automation enabled. */
+export function labActivationRequired(config: OcxConfig, configDir?: string): boolean {
+  if (Object.keys(config.routingProfiles ?? {}).length > 0) return true;
+  return labAutomationEnabledOnDisk(configDir);
+}
+
+/**
+ * Register Lab into the core slots. Idempotent per configDir and safe to call again after
+ * a routing profile is created at runtime.
+ */
+export function activateLab(config: OcxConfig, configDir?: string): void {
+  const key = activationKey(configDir);
+  // INVARIANT: activation is all-or-nothing and reason-independent. Every slot is
+  // registered here regardless of WHY activation was required, which is what makes this
+  // key safe as configDir alone -- an automation-only activation still installs the
+  // compatibility provider a later profile needs. If any registration ever becomes
+  // conditional on the activation reason, this key must include that reason, or the early
+  // return will silently skip it forever.
+  if (activated.has(key)) return;
+
+  const detach: Array<() => void> = [];
+  detach.push(registerLabPassiveRouteLinker(configDir));
+  detach.push(setCompatibilityEvidenceProvider(labCompatibilityEvidenceProvider));
+
+  const routeExecutor = createProductionLabRouteExecutor({ configDir, loadConfig: () => config });
+  detach.push(setLabAutomationDispatchDeps({ configDir, loadConfig: () => config, routeExecutor }));
+
+  // Record the activation BEFORE the scheduler start. startLabAutomationScheduler runs the
+  // full automation normalizer, which throws on any field violation, and this call sits on
+  // the startup path of every install that has a routing profile. Storing the record first
+  // means a throw cannot orphan the detach receipts and leave slots registered with no
+  // activation record -- which would let a later activateLab register them a second time.
+  activated.set(key, detach);
+
+  if (labAutomationEnabledOnDisk(configDir)) {
+    try {
+      startLabAutomationScheduler(configDir);
+    } catch (err) {
+      // Neither a malformed automation file nor a busy state lock may take the proxy down
+      // at startup. Lab automation stays off for this run; routing, evidence, and every
+      // other subsystem keep working.
+      //
+      // The two causes get different messages because they need different actions, and a
+      // lock-contention failure reported as "invalid config" sends the operator to fix a
+      // file that is fine. Contention can also stall startup by up to the 5s lock wait.
+      const code = err instanceof LabAutomationError ? err.code : null;
+      if (code === "state_lock_busy" || code === "state_lock_failed") {
+        console.warn(
+          "[lab] Lab automation did not start: another process holds the automation state lock."
+          + " Automation stays off for this run and will be retried on the next start.",
+        );
+      } else {
+        console.warn(
+          "[lab] Lab automation is disabled for this run because its configuration could not be"
+          + " loaded:",
+          err instanceof Error ? err.message : err,
+        );
+      }
+    }
+  }
+}
+
+/** True when this configDir has been activated. */
+export function isLabActivated(configDir?: string): boolean {
+  return activated.has(activationKey(configDir));
+}
+
+/**
+ * Test-only teardown. Deactivation is deliberately NOT a production path: tearing an
+ * activation down mid-run would finalize in-flight automation as ineligible rather than
+ * cancelled, and the orchestrator's shutdown signal is process-global. An install that
+ * creates then deletes a profile keeps Lab resident until restart, which does not affect
+ * users who never opted in.
+ */
+export function resetLabActivationForTests(): void {
+  for (const [key, detach] of [...activated]) {
+    activated.delete(key);
+    for (const release of [...detach].reverse()) {
+      try { release(); } catch { /* teardown is best-effort */ }
+    }
+  }
+}

package/src/lib/lab-passive-linker-registration.ts

@@ -0,0 +1,26 @@
+/**
+ * Registers Compatibility Lab's passive route-subject linker into the core slot.
+ *
+ * Imported only from the Lab activation path, never from the request path. This module
+ * lives outside `src/lab/` for the same reason the other `src/lib/lab-*.ts` host
+ * integrations do: it is the seam between core and the subsystem, not the subsystem.
+ *
+ * @internal host integration only
+ */
+import { setPassiveRouteLinker } from "../server/passive-route-linker";
+import { resolveProductionRouteSubject } from "../routing/compatibility/subject";
+
+/** Install the Lab linker. Returns a detach function. */
+export function registerLabPassiveRouteLinker(configDir?: string): () => void {
+  return setPassiveRouteLinker((config, providerName, modelId, routed, inboundWire) => {
+    const subject = resolveProductionRouteSubject(
+      config,
+      providerName,
+      modelId,
+      routed,
+      inboundWire,
+      configDir,
+    );
+    return subject ? subject.subjectId : null;
+  });
+}

package/src/lib/optional-shutdown-hooks.ts

@@ -0,0 +1,57 @@
+/**
+ * Core-owned registry for optional-subsystem shutdown work.
+ *
+ * The proxy core must not import an optional subsystem merely to be able to stop it.
+ * Compatibility Lab is the first case: `server/lifecycle.ts` imported
+ * `lab/automation/orchestrator` for two teardown calls, and that single edge closed an
+ * import cycle (`routing/compatibility/assemble` → `routing/quota` → `providers/quota` →
+ * `codex/auth-api` → `codex/native-main-admission` → `server/lifecycle` → Lab) that pulled
+ * ~69 `src/lab/` modules into the graph of every install, including installs with no
+ * routing profile at all.
+ *
+ * A subsystem registers its teardown when it activates. A process that never activates it
+ * registers nothing, so shutdown does no work and loads no module.
+ *
+ * Hooks are synchronous and best-effort by contract: `drainAndShutdown` runs under an
+ * absolute deadline, so a hook that throws must not prevent its siblings — or
+ * `server.stop` — from running.
+ *
+ * See devlog/_plan/260814_lab_core_decoupling/010_lifecycle_shutdown_registry.md
+ */
+
+type ShutdownHook = () => void;
+
+const hooks = new Map<string, ShutdownHook>();
+
+/**
+ * Register (or replace) the teardown for one optional subsystem.
+ *
+ * Keyed so repeated activation of the same subsystem cannot accumulate duplicate hooks.
+ * Returns a detach function so an owner-scoped lease can release its registration.
+ */
+export function registerOptionalShutdownHook(key: string, hook: ShutdownHook): () => void {
+  hooks.set(key, hook);
+  return () => {
+    // Only detach our own registration: a later activation may have replaced it.
+    if (hooks.get(key) === hook) hooks.delete(key);
+  };
+}
+
+/** Run every registered teardown. Never throws. */
+export function runOptionalShutdownHooks(): void {
+  for (const [key, hook] of [...hooks]) {
+    try {
+      hook();
+    } catch (err) {
+      console.warn(
+        `[shutdown] optional subsystem "${key}" teardown failed:`,
+        err instanceof Error ? err.message : err,
+      );
+    }
+  }
+}
+
+/** Test-only reset so an isolated lifecycle test does not inherit registrations. */
+export function resetOptionalShutdownHooksForTests(): void {
+  hooks.clear();
+}

package/src/lib/translator-budget.ts

@@ -71,6 +71,40 @@ export interface TranslatorBudget {
 
 const retainedEventOwnership = new WeakMap<object, { budget: TranslatorBudget; bytes: number }>();
 
+/**
+ * Charge one event appended to an incrementally materialized adapter-event batch.
+ * The newest event owns the closing array bracket; moving that byte from the old
+ * tail keeps in-order release accounting equal to the still-retained JSON array.
+ */
+export function retainTranslatedEvent<T extends object>(
+  event: T,
+  budget: TranslatorBudget,
+  previousTail?: object,
+): void {
+  if (retainedEventOwnership.has(event)) {
+    throw new Error("translated event is already retained");
+  }
+  if (previousTail === event) {
+    throw new Error("incremental translated event tail must be a distinct object");
+  }
+  const previousOwnership = previousTail === undefined
+    ? undefined
+    : retainedEventOwnership.get(previousTail);
+  if (
+    previousTail !== undefined
+    && (!previousOwnership || previousOwnership.budget !== budget || previousOwnership.bytes < 2)
+  ) {
+    throw new Error("incremental translated event tail is not retained by this budget");
+  }
+
+  const serializedBytes = Buffer.byteLength(JSON.stringify(event));
+  budget.chargeRetained(serializedBytes + (previousTail === undefined ? 2 : 1), {
+    kind: "retained_collectors",
+  });
+  if (previousOwnership) previousOwnership.bytes -= 1;
+  retainedEventOwnership.set(event, { budget, bytes: serializedBytes + 2 });
+}
+
 /**
  * Charge a materialized adapter-event batch and attach its lease to the events themselves.
  * A copied event array (for example terminal-guard collection) preserves the event objects, so