@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
480 lines (454 loc) • 19.6 kB
text/typescript
/**
* 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, CodexWriteLockSkipReason } from "./codex-write-lock";
import { HUB_GATED_SKIP_MESSAGE } from "./desired-state";
import { siblingSkipMessage } from "./sibling-start";
import { inspectCodexCoordinatorPath } from "./coordinator-doctor";
import { JOURNAL_PATH } from "./journal";
import { updateIntegrationRecord } from "./integration-record";
import { CODEX_CONFIG_PATH, CODEX_PROFILE_PATH } from "./paths";
import type {
CodexArtifactId,
CodexProvenanceEntry,
CodexProvenanceLedger,
} from "./convergence-types";
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: "adopt" }
| { 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" };
if (residue.kind === "residue" && !coordinatorIsStableZeroByte) return { kind: "adopt" };
/*
* 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 (error) {
if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
throw error;
}
}
export function captureCodexPreImages(): CodexPreImages {
return {
config: readOrNull(CODEX_CONFIG_PATH),
profile: readOrNull(CODEX_PROFILE_PATH),
journal: readOrNull(JOURNAL_PATH),
};
}
/**
* How many transactions of evidence the ledger keeps.
*
* Each transaction appends three entries, and a `present` baseline embeds the artifact's exact
* bytes as base64 — a 25 KB `config.toml` is ~34 KB per entry, so roughly 100 KB per transaction.
* A machine that syncs on every start would grow this file without limit, and it is re-read and
* re-serialized on every append, so the cost is quadratic rather than merely large.
*
* A ledger is evidence, not an archive. The most recent transactions are the ones anyone
* diagnoses against, so the window keeps those and drops the oldest.
*/
export const CODEX_PROVENANCE_MAX_TRANSACTIONS = 16;
/**
* How many serialized bytes of evidence the ledger keeps.
*
* The transaction window alone bounds the ledger only if each transaction is small, and a
* baseline embeds the artifact's exact bytes. Those artifacts sit outside this proxy's trust
* boundary: a native `config.toml` grown to hundreds of megabytes is copied into the record as
* base64 and re-serialized on every append, so a single oversized file turns a 16-transaction
* window into a multi-gigabyte write.
*
* The size is derived from the window above rather than picked: the 25 KB `config.toml` that
* comment describes measures 100.8 KiB per transaction, so a full 16-transaction window is
* 1.58 MiB. 4 MiB leaves that ordinary window untouched with room to spare while still refusing
* the pathological case, and a regression test pins the ordinary window so the two cannot drift
* apart silently.
*/
export const CODEX_PROVENANCE_MAX_BYTES = 4 * 1024 * 1024;
/**
* Measure the representation the integration-record writer actually emits.
*
* The minimal wrapper reproduces the final indentation depth of `provenance.entries`, including
* structured unknown extension fields preserved from older records. Its fixed wrapper makes this
* slightly conservative as a ledger-only ceiling, which is preferable to admitting an entry that
* expands past the limit when `JSON.stringify(record, null, 2)` writes it.
*/
function serializedProvenanceBytes(
entries: readonly CodexProvenanceEntry[],
ledger: CodexProvenanceLedger | undefined,
): number {
return Buffer.byteLength(`${JSON.stringify({
version: 1,
provenance: { ...ledger, entries },
}, null, 2)}\n`, "utf-8");
}
function provenanceBaseline(bytes: string | null): CodexProvenanceEntry["baseline"] {
if (bytes === null) return { kind: "absent" };
return {
kind: "present",
sha256: createHash("sha256").update(bytes).digest("hex"),
bytesBase64: Buffer.from(bytes).toString("base64"),
};
}
function provenancePostImage(path: string): string | null {
try {
return createHash("sha256").update(readFileSync(path)).digest("hex");
} catch {
return null;
}
}
/**
* Keep the newest transactions that fit both the transaction window and the byte ceiling, whole.
*
* Trimming by ENTRY count would cut a transaction in half and leave evidence that says a
* transaction touched two artifacts when it touched three — worse than dropping it outright,
* because a partial record still reads as complete. Order is preserved; only whole transactions
* are removed.
*
* The byte ceiling applies the same rule: a transaction that does not fit is omitted whole,
* including the newest one — a record silently truncated to fit would be read as a faithful
* pre-image. An oversized transaction is skipped rather than ending the scan, so one pathological
* artifact cannot erase the smaller transactions that still fit and are still diagnosable.
*/
export function boundProvenanceEntries(
entries: readonly CodexProvenanceEntry[],
maxTransactions = CODEX_PROVENANCE_MAX_TRANSACTIONS,
maxBytes = CODEX_PROVENANCE_MAX_BYTES,
ledger?: CodexProvenanceLedger,
): readonly CodexProvenanceEntry[] {
const transactions = new Map<string, CodexProvenanceEntry[]>();
for (const entry of entries) {
const transaction = transactions.get(entry.txId);
if (transaction) transaction.push(entry);
else transactions.set(entry.txId, [entry]);
}
const order = [...transactions.keys()];
if (order.length <= maxTransactions) {
const baselineBytes = entries.reduce(
(total, entry) => total + (entry.baseline.kind === "present" ? entry.baseline.bytesBase64.length : 0),
0,
);
if (
baselineBytes <= maxBytes
&& serializedProvenanceBytes(entries, ledger) <= maxBytes
) return entries;
}
// Newest first, so the transactions anyone diagnoses against are the ones that fit.
const keep = new Set<string>();
let baselineBytes = 0;
for (let i = order.length - 1; i >= 0 && keep.size < maxTransactions; i--) {
const txId = order[i]!;
const txEntries = transactions.get(txId)!;
// Measure the embedded pre-images first: a pathological baseline is refused without
// serializing it, so the ceiling does not itself allocate the payload it exists to reject.
const transactionBaselineBytes = txEntries.reduce(
(total, entry) => total + (entry.baseline.kind === "present" ? entry.baseline.bytesBase64.length : 0),
0,
);
if (baselineBytes + transactionBaselineBytes > maxBytes) continue;
const candidateKeep = new Set(keep);
candidateKeep.add(txId);
// Reuse the already-grouped transactions: this avoids another full-ledger filter on each
// iteration while preserving the original transaction and entry order.
const candidateEntries = order.flatMap(id =>
candidateKeep.has(id) ? transactions.get(id)! : []
);
if (serializedProvenanceBytes(candidateEntries, ledger) > maxBytes) continue;
baselineBytes += transactionBaselineBytes;
keep.add(txId);
}
if (keep.size === order.length) return entries;
return entries.filter(entry => keep.has(entry.txId));
}
/** Append evidence for an already-committed native transaction, best-effort. */
export function recordCodexNativeTransactionProvenance(
preImages: CodexPreImages,
txId: string,
) {
const at = new Date().toISOString();
const surfaces: readonly [CodexArtifactId, string, string | null][] = [
[{ kind: "config" }, CODEX_CONFIG_PATH, preImages.config],
[{ kind: "generated-profile" }, CODEX_PROFILE_PATH, preImages.profile],
[{ kind: "injection-journal" }, JOURNAL_PATH, preImages.journal],
];
const entries: readonly CodexProvenanceEntry[] = surfaces.map(([artifact, path, baseline]) => ({
artifact,
baseline: provenanceBaseline(baseline),
postImage: provenancePostImage(path),
txId,
at,
}));
return updateIntegrationRecord(record => {
const previousLedger = record.provenance;
// Unknown ledger extensions are forward-compatible and must be preserved. If those fixed
// fields alone exceed the ceiling, no entry selection can make the write compliant. Keep the
// existing record byte-for-byte instead of deleting all known evidence and rewriting the
// same oversized extension on every native transaction.
if (
previousLedger
&& serializedProvenanceBytes([], previousLedger) > CODEX_PROVENANCE_MAX_BYTES
) return record;
return {
...record,
provenance: {
...previousLedger,
entries: boundProvenanceEntries(
[...(previousLedger?.entries ?? []), ...entries],
CODEX_PROVENANCE_MAX_TRANSACTIONS,
CODEX_PROVENANCE_MAX_BYTES,
previousLedger,
),
},
};
});
}
/**
* 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: CodexWriteLockSkipReason; message: string;
} {
if (result.status === "skipped") {
return {
success: true,
status: "skipped",
skippedReason: result.reason,
// Four distinct facts, four sentences. The hub gate in particular must not borrow the
// toggle's wording — that is the phantom "integration is OFF" report from #4236.
message: result.reason === "hub-gated"
? `${HUB_GATED_SKIP_MESSAGE} No Codex config, catalog, cache, or history was changed.`
: result.reason === "sibling"
? `${siblingSkipMessage()} No Codex config, catalog, cache, or history was changed.`
: 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}`,
};
}