@bitkyc08/opencodex 2.10.0 → 2.10.1

package/src/codex/catalog-admission.ts

@@ -0,0 +1,197 @@
+/**
+ * Minimal catalog admission for the management refresh path.
+ *
+ * The r2 #1 catalog incident left gather and native writes in one awaited
+ * callback. WP9 needs generation and filesystem-target evidence before it can
+ * split those phases, but importing WP12 authority would make WP9 depend on a
+ * later phase. This reader therefore captures only the exact resident config,
+ * its cooperating generation, and identities for catalog-owned targets.
+ */
+import { createHmac, randomBytes } from "node:crypto";
+import { join, resolve } from "node:path";
+
+import { observeConfigGeneration } from "../config";
+import type { OcxConfig } from "../types";
+import type {
+  CatalogAdmissionSnapshot,
+  CatalogConvergeRequestInput,
+  ConfigGeneration,
+  ConvergeRequest,
+} from "./convergence-types";
+import {
+  catalogBackupPathFor,
+  legacyCatalogBackupPath,
+  samePath,
+} from "./catalog/parsing";
+import { readRootTomlString } from "./paths";
+import {
+  acceptCatalogGatherSourcePath,
+  captureAndSealCatalogHomeSelection,
+  captureCatalogGatherTargetIdentity,
+  createCatalogGatherEvidenceSession,
+  readCatalogGatherSource,
+  sealCatalogGatherEvidenceSession,
+} from "./catalog/filesystem-evidence";
+
+/**
+ * Construct the one request shape permitted for management catalog refreshes.
+ * Callers choose the deadline only; they cannot widen scope or choose direction.
+ */
+export function createCatalogConvergeRequest({
+  deadlineMs,
+}: CatalogConvergeRequestInput): ConvergeRequest {
+  if (!Number.isSafeInteger(deadlineMs) || deadlineMs <= 0) {
+    throw new TypeError("Catalog convergence deadlineMs must be a positive safe integer.");
+  }
+
+  return {
+    action: "converge",
+    scope: "catalog",
+    reason: "management-mutation",
+    mode: "automatic",
+    deadlineMs,
+  };
+}
+
+const CONFIG_IDENTITY_KEY = randomBytes(32);
+const configReferenceIdentities = new WeakMap<object, string>();
+let nextConfigReferenceIdentity = 0;
+
+function encodeLengthPrefixed(value: string): string {
+  return `${Buffer.byteLength(value, "utf8")}:${value}`;
+}
+
+function canonicalConfigEncoding(value: unknown, ancestors = new Set<object>()): string {
+  if (value === null) return "null";
+  switch (typeof value) {
+    case "undefined": return "undefined";
+    case "boolean": return value ? "boolean:1" : "boolean:0";
+    case "string": return `string:${encodeLengthPrefixed(value)}`;
+    case "number": {
+      if (!Number.isFinite(value)) throw new TypeError("Catalog config identity cannot encode a non-finite number.");
+      return `number:${Object.is(value, -0) ? "-0" : String(value)}`;
+    }
+    case "bigint":
+    case "function":
+    case "symbol":
+      throw new TypeError(`Catalog config identity cannot encode ${typeof value}.`);
+    case "object": break;
+  }
+
+  if (ancestors.has(value)) throw new TypeError("Catalog config identity cannot encode a cyclic graph.");
+  if (Object.getOwnPropertySymbols(value).length > 0) {
+    throw new TypeError("Catalog config identity cannot encode symbol keys.");
+  }
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      const items = Array.from({ length: value.length }, (_, index) => (
+        Object.hasOwn(value, index)
+          ? `item:${canonicalConfigEncoding(value[index], ancestors)}`
+          : "hole"
+      ));
+      return `array:${value.length}:${items.map(encodeLengthPrefixed).join("")}`;
+    }
+    const keys = Object.keys(value).sort();
+    const entries = keys.map(key => {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (!descriptor || !("value" in descriptor)) {
+        throw new TypeError("Catalog config identity cannot encode accessor properties.");
+      }
+      return `${encodeLengthPrefixed(key)}${encodeLengthPrefixed(canonicalConfigEncoding(descriptor.value, ancestors))}`;
+    });
+    return `object:${keys.length}:${entries.join("")}`;
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+function keyedConfigIdentity(domain: string, payload: string): string {
+  return createHmac("sha256", CONFIG_IDENTITY_KEY)
+    .update(encodeLengthPrefixed(domain))
+    .update(encodeLengthPrefixed(payload))
+    .digest("hex");
+}
+
+function catalogConfigIdentity(
+  config: Readonly<OcxConfig>,
+  generation: ConfigGeneration,
+): CatalogAdmissionSnapshot["configIdentity"] {
+  let referenceIdentity = configReferenceIdentities.get(config);
+  if (!referenceIdentity) {
+    nextConfigReferenceIdentity += 1;
+    referenceIdentity = keyedConfigIdentity("catalog-config-reference-v1", String(nextConfigReferenceIdentity));
+    configReferenceIdentities.set(config, referenceIdentity);
+  }
+  return Object.freeze({
+    referenceIdentity,
+    generation: Object.freeze({ ...generation }),
+    snapshotIdentity: keyedConfigIdentity("catalog-config-snapshot-v1", canonicalConfigEncoding(config)),
+  });
+}
+
+/**
+ * Capture the catalog-only evidence WP9 can validate without consulting WP12.
+ * The config reference is retained verbatim; no persisted config re-read may
+ * replace the object already held by the management callback.
+ */
+export function captureCatalogAdmissionSnapshot(
+  config: Readonly<OcxConfig>,
+): CatalogAdmissionSnapshot {
+  const generation = observeConfigGeneration();
+  if (generation.kind === "absent") {
+    /*
+     * Absence is refused HERE and admitted elsewhere, and the difference is the
+     * lock. Codex write admission may carry an absent generation because it goes
+     * on to take the config transaction and read a real zero inside it. Catalog
+     * gather has no such transaction — by contract it holds no lock and writes
+     * nothing — so it has no way to turn absence into an observation. Refusing
+     * is the only honest answer available to it.
+     *
+     * The wording matters beyond this line: `admissionFailure` in
+     * management-convergence.ts classifies this throw by matching its MESSAGE,
+     * and an unrecognized one becomes a non-retryable `failed/disk` instead of
+     * the retryable skip a missing coordinator has always produced. Keeping the
+     * "config generation is database" phrasing preserves that projection — a
+     * caller that could simply try again should still be told to.
+     */
+    throw new Error("Cannot capture Codex catalog admission: config generation is database (absent).");
+  }
+  if (generation.kind !== "ready") {
+    throw new Error(`Cannot capture Codex catalog admission: config generation is ${generation.reason}.`);
+  }
+
+  const evidenceSession = createCatalogGatherEvidenceSession();
+  const homeSelection = captureAndSealCatalogHomeSelection(evidenceSession);
+  const configPath = join(homeSelection.canonicalCodexHome, "config.toml");
+  acceptCatalogGatherSourcePath(evidenceSession, "catalog-target-selection", configPath);
+  const configBytes = readCatalogGatherSource(evidenceSession, "catalog-target-selection");
+  const configuredCatalogPath = configBytes === null
+    ? null
+    : readRootTomlString(Buffer.from(configBytes).toString("utf8"), "model_catalog_json");
+  const defaultCatalogPath = join(homeSelection.canonicalCodexHome, "opencodex-catalog.json");
+  const catalogPath = configuredCatalogPath
+    ? resolve(homeSelection.canonicalCodexHome, configuredCatalogPath)
+    : defaultCatalogPath;
+  const backupPaths = [
+    catalogBackupPathFor(catalogPath),
+    ...(samePath(catalogPath, defaultCatalogPath) ? [legacyCatalogBackupPath()] : []),
+  ];
+  const targets = {
+    catalog: captureCatalogGatherTargetIdentity(evidenceSession, catalogPath),
+    cache: captureCatalogGatherTargetIdentity(
+      evidenceSession,
+      join(homeSelection.canonicalCodexHome, "models_cache.json"),
+    ),
+    catalogBackups: backupPaths.map(path => captureCatalogGatherTargetIdentity(evidenceSession, path)),
+  };
+  const sourceEvidence = sealCatalogGatherEvidenceSession(evidenceSession);
+
+  return {
+    config,
+    generation: generation.generation,
+    configIdentity: catalogConfigIdentity(config, generation.generation),
+    targets,
+    sourceEvidence,
+  };
+}

package/src/codex/catalog-write-serialization.ts

@@ -0,0 +1,241 @@
+/**
+ * K — the permanent catalog serialization primitive.
+ *
+ * Round 4 of the audit killed the idea that "the replacement happens under a
+ * lock" is enough. The retained `/api/sync` chain reads the active catalog,
+ * captures it, awaits provider gathering, and only then writes from that
+ * captured state (`src/codex/catalog/sync.ts:513,520,526,565`). If convergence
+ * publishes Y while that await is pending, taking a lock afterwards does not
+ * make the captured X fresh — the writer legally overwrites Y while holding it.
+ * So K serializes the whole read-transform-write transaction, either by
+ * recomputing under K or by revalidating complete evidence under K, not by
+ * guarding the last rename.
+ *
+ * The second defect that round found was subtler: an opaque TypeScript permit
+ * type proves a permit-bearing call path EXISTS. It cannot prove the callback
+ * still holds K. A leaked permit used after its callback returned type-checks
+ * perfectly. So the type is not the mechanism — this module owns a private
+ * active-permit registry, and every mutator asks it at runtime whether the
+ * permit it holds is still live for the home it is about to write.
+ *
+ * K is permanent and is NOT WP11's native write lock. It never reads or
+ * advances the native pair. Order is `N -> K -> C`; there is no `C -> K` and no
+ * `K -> N` (`005_contract.md:660-762`).
+ *
+ * Design record: devlog/_plan/260804_codex_write_substrate/005_contract.md §3.
+ */
+import { chmodSync, lstatSync, realpathSync } from "node:fs";
+
+import { Database } from "bun:sqlite";
+
+import {
+  CodexUserIdentityRefusal,
+  resolveCodexCatalogSerializationDatabasePath,
+  resolveEffectiveUserIdentity,
+} from "./user-identity";
+
+/**
+ * Authorization to perform the fixed sequence of catalog mutations inside ONE
+ * K acquisition.
+ *
+ * Deliberately carries no usable field. Holding this object is necessary but
+ * never sufficient: `assertCatalogWritePermit` is what actually decides, by
+ * looking the object up in a registry this module alone can write. A forged
+ * cast, a prototype copy, or a symbol clone produces a value of this type that
+ * every writer refuses.
+ */
+export interface CatalogWritePermit {
+  readonly [catalogWritePermitBrand]: true;
+}
+
+declare const catalogWritePermitBrand: unique symbol;
+
+export type CatalogSerializationOutcome<T> =
+  | { kind: "completed"; value: T }
+  | { kind: "unavailable"; reason: "busy" | "database" | "unsafe-path" };
+
+export class CatalogWritePermitRefusal extends Error {
+  readonly code = "CODEX_CATALOG_WRITE_PERMIT_REFUSED";
+
+  constructor(message: string) {
+    super(message);
+    this.name = "CatalogWritePermitRefusal";
+  }
+}
+
+interface PermitRegistration {
+  /** The exact canonical CODEX_HOME whose artifacts this acquisition may write. */
+  readonly canonicalCodexHome: string;
+  /** Identifies the acquisition, so a permit cannot outlive its transaction. */
+  readonly transactionId: string;
+  live: boolean;
+}
+
+/**
+ * The registry is a module-private WeakMap keyed by permit IDENTITY. There is
+ * no exported constructor, brand value, or registration API, so the only way to
+ * obtain a registered permit is to be inside a live callback.
+ */
+const activePermits = new WeakMap<object, PermitRegistration>();
+
+let acquisitionCounter = 0;
+
+function isBusy(error: unknown): boolean {
+  const code = error && typeof error === "object" && "code" in error
+    ? String((error as { code?: unknown }).code)
+    : "";
+  const message = error instanceof Error ? error.message : String(error);
+  return code === "SQLITE_BUSY" || code === "SQLITE_LOCKED"
+    || /database (?:is|table is) locked/i.test(message);
+}
+
+/**
+ * The runtime proof every low-level catalog/backup/cache mutator must obtain
+ * before its FIRST filesystem mutation — including temp creation, hardening,
+ * unlink, link, rename, truncate, or replacement.
+ *
+ * `owningCodexHome` is supplied by the caller rather than inferred from the
+ * target's parent directory, because an accepted configured catalog target may
+ * be absolute and outside CODEX_HOME entirely.
+ */
+export function assertCatalogWritePermit(
+  permit: CatalogWritePermit,
+  owningCodexHome: string,
+): void {
+  const registration = activePermits.get(permit as unknown as object);
+  if (!registration) {
+    throw new CatalogWritePermitRefusal(
+      "The catalog write permit was not minted by the serialization owner.",
+    );
+  }
+  if (!registration.live) {
+    throw new CatalogWritePermitRefusal(
+      "The catalog write permit belongs to a released acquisition.",
+    );
+  }
+  if (registration.canonicalCodexHome !== owningCodexHome) {
+    throw new CatalogWritePermitRefusal(
+      "The catalog write permit authorizes a different CODEX_HOME.",
+    );
+  }
+}
+
+/**
+ * Acquire K for one canonical CODEX_HOME and run `write` while it is held.
+ *
+ * Synchronous by contract: the callback performs no provider request, runtime
+ * probe, OAuth refresh, subprocess, or awaited work. It may enter
+ * `withExpectedConfigGenerationSync` — that is the `K -> C` edge.
+ *
+ * `busy_timeout = 0` with `BEGIN IMMEDIATE` makes contention fail fast and
+ * typed; the outer async orchestration decides whether to retry within its
+ * deadline. Blocking here would hold K across an unbounded wait.
+ */
+export function withCatalogWriteSerialization<T>(
+  canonicalCodexHome: string,
+  write: (permit: CatalogWritePermit) => T,
+): CatalogSerializationOutcome<T> {
+  let databasePath: string;
+  try {
+    databasePath = resolveCodexCatalogSerializationDatabasePath(
+      resolveEffectiveUserIdentity(),
+      canonicalCodexHome,
+    );
+  } catch (error) {
+    if (error instanceof CodexUserIdentityRefusal) {
+      return { kind: "unavailable", reason: "unsafe-path" };
+    }
+    return { kind: "unavailable", reason: "database" };
+  }
+
+  let database: Database | undefined;
+  let transactionOpen = false;
+  let registration: PermitRegistration | undefined;
+  let permit: CatalogWritePermit | undefined;
+
+  try {
+    let databaseWasAbsent = false;
+    try {
+      const before = lstatSync(databasePath);
+      if (before.isSymbolicLink() || !before.isFile()) {
+        return { kind: "unavailable", reason: "unsafe-path" };
+      }
+      if (process.platform !== "win32") {
+        const uid = process.getuid?.();
+        if (uid === undefined || before.uid !== uid || (before.mode & 0o777) !== 0o600) {
+          return { kind: "unavailable", reason: "unsafe-path" };
+        }
+      }
+    } catch (cause) {
+      const code = cause && typeof cause === "object" && "code" in cause
+        ? String((cause as { code?: unknown }).code)
+        : "";
+      if (code !== "ENOENT") throw cause;
+      databaseWasAbsent = true;
+    }
+
+    database = new Database(databasePath, { create: true });
+    if (databaseWasAbsent) {
+      try { chmodSync(databasePath, 0o600); } catch { /* Windows applies ACLs in WP11. */ }
+    }
+    const opened = lstatSync(databasePath);
+    if (opened.isSymbolicLink() || !opened.isFile()
+      || realpathSync.native(databasePath) !== databasePath) {
+      return { kind: "unavailable", reason: "unsafe-path" };
+    }
+
+    database.exec("PRAGMA busy_timeout = 0; BEGIN IMMEDIATE");
+    transactionOpen = true;
+
+    acquisitionCounter += 1;
+    registration = {
+      canonicalCodexHome,
+      transactionId: `${process.pid}:${acquisitionCounter}`,
+      live: true,
+    };
+    // A bare object: nothing about it is guessable or reconstructable, because
+    // authority lives in the registry entry rather than in the value.
+    permit = {} as CatalogWritePermit;
+    activePermits.set(permit as unknown as object, registration);
+
+    let value: T;
+    try {
+      value = write(permit);
+    } finally {
+      // Revoke BEFORE the transaction is released, so a mutator racing the
+      // release can never find a live permit without a live lock. This runs on
+      // the throwing path too, which is the case a `finally`-less version gets
+      // wrong.
+      registration.live = false;
+      activePermits.delete(permit as unknown as object);
+    }
+
+    database.exec("COMMIT");
+    transactionOpen = false;
+    return { kind: "completed", value };
+  } catch (error) {
+    if (transactionOpen) {
+      try { database?.exec("ROLLBACK"); } catch { /* close releases the transaction */ }
+      transactionOpen = false;
+    }
+    if (registration?.live) {
+      registration.live = false;
+      if (permit) activePermits.delete(permit as unknown as object);
+    }
+    if (error instanceof CodexUserIdentityRefusal) {
+      return { kind: "unavailable", reason: "unsafe-path" };
+    }
+    if (isBusy(error)) return { kind: "unavailable", reason: "busy" };
+    // A callback failure is the caller's error, not a lock outcome: K acquired
+    // fine. Reporting it as `unavailable` would tell the caller to retry
+    // something that will fail identically.
+    throw error;
+  } finally {
+    try { database?.close(); } catch { /* acquisition already finished */ }
+  }
+}
+
+/** Test-only: prove a leaked permit is dead without reaching into the registry. */
+export function isCatalogWritePermitLive(permit: CatalogWritePermit): boolean {
+  return activePermits.get(permit as unknown as object)?.live === true;
+}

package/src/codex/catalog.ts

@@ -2,7 +2,7 @@
 // Public surface preserved exactly; importers keep using "src/codex/catalog".
 export { isMediaGenerationModelId, shouldExposeRoutedModel, readCodexCatalogPath, readCatalog, normalizeRoutedCatalogEntry, catalogModelSlug, filterSupportedNativeSlugs, catalogModelSupportsReasoningSummaries } from "./catalog/parsing";
 export type { CatalogModel, MultiAgentMode } from "./catalog/parsing";
-export { NATIVE_OPENAI_MODELS, nativeOpenAiContextWindow, disabledNativeSlugs, visibleNativeSlugs, desktopVisibleNativeSlugs, nativeModelRows, applyNativeVisibility, upstreamNativeEntry, nativeOpenAiSlugs, listCatalogNativeSlugs, nativeReasoningEfforts, nativeDefaultReasoningEffort } from "./catalog/metadata";
+export { NATIVE_OPENAI_MODELS, nativeOpenAiContextWindow, disabledNativeSlugs, visibleNativeSlugs, desktopVisibleNativeSlugs, nativeModelRows, applyNativeVisibility, upstreamNativeEntry, nativeOpenAiSlugs, listCatalogNativeSlugs, nativeReasoningEfforts, nativeDefaultReasoningEffort, shouldIncludeAccountBoundNativeOpenAi, shouldIncludeNativeOpenAi } from "./catalog/metadata";
 export { isSpawnableCodexCandidate, codexExecInvocation, loadBundledCodexCatalog, materializeBundledCodexCatalog, loadCatalogTemplate } from "./catalog/bundled";
 export { nativeEffortClamp, shouldApplyNativeEffortClamp, catalogModelEfforts, codexSupportedReasoningEfforts, clampedDefaultEffort, clampEntryToCodexSupportedEfforts, clampCatalogModelsToCodexSupport } from "./catalog/effort";
 export { applyProviderConfigHints, isDatedVariantId, filterCatalogVisibleModels, gatherRoutedModels, clearGatherRoutedModelsInflight, augmentRoutedModelsWithRegistryOpenAiApiRows, augmentRoutedModelsWithJawcodeMetadata } from "./catalog/provider-fetch";
@@ -10,3 +10,4 @@ export { deriveComboCatalogModel, exactComboCatalogSlugs, getLastComboCatalogOmi
 export type { ComboCatalogOmission, ComboCatalogOmissionReason } from "./catalog/aggregation";
 export { MAX_SPAWN_AGENT_MODEL_OVERRIDES, effectiveSubagentRoster, buildCatalogEntries, resetCatalogRuntimeStateForTests, orderForSubagents, mergeCatalogEntriesForSync, syncCatalogModels, restoreCodexCatalog, invalidateCodexModelsCache } from "./catalog/sync";
 export type { SpawnAgentSurface, SubagentRosterExclusionReason, EffectiveSubagentModel, SubagentRosterExclusion, EffectiveSubagentRoster } from "./catalog/sync";
+export { accountBoundNativeDisplayName, accountBoundNativeModelSlugs, CODEX_ACCOUNT_BOUND_CATALOG_KIND, trustedAccountBoundNativeCatalogSlug, visibleCodexAccountSelectors } from "./catalog/account-models";