@bitkyc08/opencodex 2.36.0 → 2.38.0

package/src/codex/reset-credit-operation-ledger.ts

@@ -0,0 +1,1411 @@
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync } from "node:fs";
+import { Database } from "bun:sqlite";
+import { NestedConfigMutationError, prepareConfigMutationDatabasePathForWrite } from "../config";
+import { initializeConfigGeneration } from "./generation";
+import {
+  compareCodexResetCreditRecoveryGenerationOrder,
+  isCodexResetCreditOperationId,
+  snapshotCodexResetCreditRecoveryGeneration,
+  type CodexResetCreditConsumeCode,
+  type CodexResetCreditRecoveryGeneration,
+  type CodexReservedOperationId,
+} from "./reset-credit-recovery";
+import { isValidCodexAccountId, MAIN_CODEX_ACCOUNT_ID } from "./account-id";
+
+export const MAX_RESET_CREDIT_OPERATION_ACCOUNTS = 128;
+export const MAX_MANUAL_RESET_CREDIT_OPERATION_IDS = 4_096;
+const MANUAL_RESET_CREDIT_HISTORY_HIGH_WATER_MARK = Math.ceil(
+  MAX_MANUAL_RESET_CREDIT_OPERATION_IDS * 0.9,
+);
+let reportedManualHistoryLevel = 0;
+type ResetCreditOperationMigrationFaultForTests = "after_first_write" | null;
+let migrationFaultForTests: ResetCreditOperationMigrationFaultForTests = null;
+const ACCOUNT_KEY_PATTERN = /^[0-9a-f]{64}$/;
+const TERMINAL_STATE_BY_CODE: Readonly<Record<
+  CodexResetCreditConsumeCode,
+  "confirmed" | "stopped"
+>> = Object.freeze({
+  reset: "confirmed",
+  already_redeemed: "confirmed",
+  nothing_to_reset: "stopped",
+  no_credit: "stopped",
+});
+const STATES: ReadonlySet<string> = new Set(["pending", "ambiguous", "confirmed", "stopped"]);
+
+type ResetCreditOperationState = "pending" | "ambiguous" | "confirmed" | "stopped";
+type ResetCreditOperationKind = "recovery" | "manual";
+
+type ResetCreditOperationRecord = Readonly<{
+  accountKey: string;
+  operationKind: ResetCreditOperationKind;
+  credentialGeneration?: number;
+  exhaustionGeneration?: number;
+  operationId: string;
+  joinedOperationId?: string;
+  state: ResetCreditOperationState;
+  code?: CodexResetCreditConsumeCode;
+  createdAt: number;
+  updatedAt: number;
+}>;
+
+type ResetCreditOperationRow = {
+  account_key: unknown;
+  operation_kind: unknown;
+  credential_generation: unknown;
+  exhaustion_generation: unknown;
+  operation_id: unknown;
+  joined_operation_id: unknown;
+  state: unknown;
+  code: unknown;
+  created_at: unknown;
+  updated_at: unknown;
+};
+
+type ManualResetCreditOperationIdRecord = Readonly<{
+  operationId: string;
+  accountKey: string;
+  canonicalOperationId: string;
+  terminalCode?: CodexResetCreditConsumeCode;
+  createdAt: number;
+  updatedAt: number;
+}>;
+
+type ManualResetCreditOperationIdRow = {
+  operation_id: unknown;
+  account_key: unknown;
+  canonical_operation_id: unknown;
+  terminal_code: unknown;
+  created_at: unknown;
+  updated_at: unknown;
+};
+
+export type OpenResetCreditOperationResult =
+  | Readonly<{ kind: "execute"; operationId: CodexReservedOperationId; resumed: boolean }>
+  | Readonly<{ kind: "terminal"; operationId: CodexReservedOperationId; code: CodexResetCreditConsumeCode }>
+  | Readonly<{ kind: "stale-generation" | "unresolved-prior-generation" | "capacity" | "unavailable" }>;
+
+export type UpdateResetCreditOperationResult =
+  | Readonly<{ kind: "updated" }>
+  | Readonly<{ kind: "mismatch" | "unavailable" }>;
+
+export type ManualResetCreditOperationIdentity = Readonly<{
+  accountId: string;
+  chatgptAccountId: string;
+  operationId: string;
+}>;
+
+export type OpenManualResetCreditOperationResult =
+  | Readonly<{ kind: "execute"; operationId: CodexReservedOperationId; resumed: boolean }>
+  | Readonly<{ kind: "terminal"; operationId: CodexReservedOperationId; code: CodexResetCreditConsumeCode }>
+  | Readonly<{ kind: "capacity" | "identity-mismatch" | "unavailable" }>;
+
+const TABLE_NAME = "reset_credit_operations";
+const CREATE_TABLE = `CREATE TABLE main.reset_credit_operations (
+    account_key TEXT PRIMARY KEY,
+    operation_kind TEXT NOT NULL CHECK (operation_kind IN ('recovery', 'manual')),
+    credential_generation INTEGER,
+    exhaustion_generation INTEGER,
+    operation_id TEXT NOT NULL,
+    joined_operation_id TEXT,
+    state TEXT NOT NULL,
+    code TEXT,
+    created_at INTEGER NOT NULL CHECK (created_at >= 0),
+    updated_at INTEGER NOT NULL CHECK (updated_at >= created_at),
+    CHECK (
+      (operation_kind = 'recovery'
+        AND credential_generation IS NOT NULL AND credential_generation >= 0
+        AND exhaustion_generation IS NOT NULL AND exhaustion_generation >= 0
+        AND joined_operation_id IS NULL)
+      OR
+      (operation_kind = 'manual'
+        AND credential_generation IS NULL AND exhaustion_generation IS NULL)
+    ),
+    CHECK (joined_operation_id IS NULL OR joined_operation_id <> operation_id)
+  ) STRICT, WITHOUT ROWID`;
+const EXPECTED_SCHEMA_SQL = CREATE_TABLE.replace("main.", "");
+const MANUAL_ID_TABLE_NAME = "reset_credit_manual_operation_ids";
+const CREATE_MANUAL_ID_TABLE = `CREATE TABLE main.reset_credit_manual_operation_ids (
+    operation_id TEXT PRIMARY KEY,
+    account_key TEXT NOT NULL,
+    canonical_operation_id TEXT NOT NULL,
+    terminal_code TEXT CHECK (
+      terminal_code IS NULL OR terminal_code IN (
+        'reset', 'already_redeemed', 'nothing_to_reset', 'no_credit'
+      )
+    ),
+    created_at INTEGER NOT NULL CHECK (created_at >= 0),
+    updated_at INTEGER NOT NULL CHECK (updated_at >= created_at)
+  ) STRICT, WITHOUT ROWID`;
+const EXPECTED_MANUAL_ID_SCHEMA_SQL = CREATE_MANUAL_ID_TABLE.replace("main.", "");
+const PRIOR_TABLE_NAME = "reset_credit_operations_legacy_v2";
+const PRIOR_CREATE_TABLE = `CREATE TABLE reset_credit_operations (
+    account_key TEXT PRIMARY KEY,
+    operation_kind TEXT NOT NULL CHECK (operation_kind IN ('recovery', 'manual')),
+    credential_generation INTEGER,
+    exhaustion_generation INTEGER,
+    operation_id TEXT NOT NULL,
+    state TEXT NOT NULL,
+    code TEXT,
+    created_at INTEGER NOT NULL CHECK (created_at >= 0),
+    updated_at INTEGER NOT NULL CHECK (updated_at >= created_at),
+    CHECK (
+      (operation_kind = 'recovery'
+        AND credential_generation IS NOT NULL AND credential_generation >= 0
+        AND exhaustion_generation IS NOT NULL AND exhaustion_generation >= 0)
+      OR
+      (operation_kind = 'manual'
+        AND credential_generation IS NULL AND exhaustion_generation IS NULL)
+    )
+  ) STRICT, WITHOUT ROWID`;
+const LEGACY_TABLE_NAME = "reset_credit_operations_legacy_v1";
+const LEGACY_CREATE_TABLE = `CREATE TABLE reset_credit_operations (
+    account_key TEXT PRIMARY KEY,
+    credential_generation INTEGER NOT NULL CHECK (credential_generation >= 0),
+    exhaustion_generation INTEGER NOT NULL CHECK (exhaustion_generation >= 0),
+    operation_id TEXT NOT NULL,
+    state TEXT NOT NULL,
+    code TEXT,
+    created_at INTEGER NOT NULL CHECK (created_at >= 0),
+    updated_at INTEGER NOT NULL CHECK (updated_at >= created_at)
+  ) STRICT, WITHOUT ROWID`;
+const SELECT_ALL = `
+  SELECT account_key, operation_kind, credential_generation,
+         exhaustion_generation, operation_id, joined_operation_id,
+         state, code, created_at, updated_at
+    FROM main.reset_credit_operations
+   ORDER BY account_key
+   LIMIT ${MAX_RESET_CREDIT_OPERATION_ACCOUNTS + 1}`;
+const SELECT_BY_KEY = `
+  SELECT account_key, operation_kind, credential_generation,
+         exhaustion_generation, operation_id, joined_operation_id,
+         state, code, created_at, updated_at
+    FROM main.reset_credit_operations
+   WHERE account_key = ?
+   LIMIT 2`;
+const SELECT_KEY_BY_OPERATION_ID = `
+  SELECT account_key FROM (
+    SELECT account_key
+      FROM main.reset_credit_operations
+     WHERE operation_id = ? OR joined_operation_id = ?
+    UNION
+    SELECT account_key
+      FROM main.reset_credit_manual_operation_ids
+     WHERE operation_id = ?
+  )
+   LIMIT 2`;
+const SELECT_ALL_MANUAL_IDS = `
+  SELECT operation_id, account_key, canonical_operation_id,
+         terminal_code, created_at, updated_at
+    FROM main.reset_credit_manual_operation_ids
+   ORDER BY operation_id
+   LIMIT ${MAX_MANUAL_RESET_CREDIT_OPERATION_IDS + 1}`;
+const SELECT_BOUNDED_MANUAL_ID_COUNT = `
+  SELECT COUNT(*) AS count
+    FROM (
+      SELECT 1
+        FROM main.reset_credit_manual_operation_ids
+       LIMIT ${MAX_MANUAL_RESET_CREDIT_OPERATION_IDS + 1}
+    )`;
+const SELECT_DUPLICATE_RECOVERY_MANUAL_ID = `
+  SELECT operations.operation_id
+    FROM main.reset_credit_operations AS operations
+    JOIN main.reset_credit_manual_operation_ids AS manual_ids
+      ON manual_ids.operation_id = operations.operation_id
+   WHERE operations.operation_kind = 'recovery'
+   LIMIT 1`;
+const SELECT_MANUAL_ID = `
+  SELECT operation_id, account_key, canonical_operation_id,
+         terminal_code, created_at, updated_at
+    FROM main.reset_credit_manual_operation_ids
+   WHERE operation_id = ?
+   LIMIT 2`;
+const SELECT_MANUAL_IDS_BY_CANONICAL = `
+  SELECT operation_id, account_key, canonical_operation_id,
+         terminal_code, created_at, updated_at
+    FROM main.reset_credit_manual_operation_ids
+   WHERE account_key = ? AND canonical_operation_id = ?
+   ORDER BY operation_id
+   LIMIT ${MAX_MANUAL_RESET_CREDIT_OPERATION_IDS + 1}`;
+const INSERT_MANUAL_ID = `
+  INSERT INTO main.reset_credit_manual_operation_ids (
+    operation_id, account_key, canonical_operation_id,
+    terminal_code, created_at, updated_at
+  ) VALUES (?, ?, ?, ?, ?, ?)`;
+const SETTLE_MANUAL_IDS = `
+  UPDATE main.reset_credit_manual_operation_ids
+     SET terminal_code = ?, updated_at = ?
+   WHERE account_key = ? AND canonical_operation_id = ?
+     AND (terminal_code IS NULL OR terminal_code = ?)`;
+const INSERT_RECORD = `
+  INSERT INTO main.reset_credit_operations (
+    account_key, operation_kind, credential_generation, exhaustion_generation,
+    operation_id, joined_operation_id, state, code, created_at, updated_at
+  ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`;
+const REPLACE_RECORD = `
+  UPDATE main.reset_credit_operations
+     SET operation_kind = ?, credential_generation = ?, exhaustion_generation = ?,
+         operation_id = ?, joined_operation_id = ?, state = ?, code = ?,
+         created_at = ?, updated_at = ?
+   WHERE account_key = ?`;
+const UPDATE_RECORD = `
+  UPDATE main.reset_credit_operations
+     SET state = ?, code = ?, updated_at = ?
+   WHERE account_key = ? AND operation_kind = ? AND operation_id = ?
+     AND credential_generation IS ? AND exhaustion_generation IS ?`;
+const JOIN_MANUAL_OPERATION = `
+  UPDATE main.reset_credit_operations
+     SET joined_operation_id = ?, updated_at = ?
+   WHERE account_key = ? AND operation_kind = 'manual' AND operation_id = ?
+     AND joined_operation_id IS NULL AND state IN ('pending', 'ambiguous')`;
+const TOUCH_MANUAL_OPERATION = `
+  UPDATE main.reset_credit_operations
+     SET updated_at = ?
+   WHERE account_key = ? AND operation_kind = 'manual' AND operation_id = ?
+     AND joined_operation_id IS NOT NULL AND state IN ('pending', 'ambiguous')`;
+
+type SchemaObjectRow = {
+  type: unknown;
+  name: unknown;
+  tbl_name: unknown;
+  sql: unknown;
+};
+
+type TableListRow = {
+  schema: unknown;
+  name: unknown;
+  type: unknown;
+  ncol: unknown;
+  wr: unknown;
+  strict: unknown;
+};
+
+type TableColumnRow = {
+  cid: unknown;
+  name: unknown;
+  type: unknown;
+  notnull: unknown;
+  dflt_value: unknown;
+  pk: unknown;
+  hidden: unknown;
+};
+
+const EXPECTED_COLUMNS = Object.freeze([
+  Object.freeze({ name: "account_key", type: "TEXT", notnull: 1, pk: 1 }),
+  Object.freeze({ name: "operation_kind", type: "TEXT", notnull: 1, pk: 0 }),
+  Object.freeze({ name: "credential_generation", type: "INTEGER", notnull: 0, pk: 0 }),
+  Object.freeze({ name: "exhaustion_generation", type: "INTEGER", notnull: 0, pk: 0 }),
+  Object.freeze({ name: "operation_id", type: "TEXT", notnull: 1, pk: 0 }),
+  Object.freeze({ name: "joined_operation_id", type: "TEXT", notnull: 0, pk: 0 }),
+  Object.freeze({ name: "state", type: "TEXT", notnull: 1, pk: 0 }),
+  Object.freeze({ name: "code", type: "TEXT", notnull: 0, pk: 0 }),
+  Object.freeze({ name: "created_at", type: "INTEGER", notnull: 1, pk: 0 }),
+  Object.freeze({ name: "updated_at", type: "INTEGER", notnull: 1, pk: 0 }),
+]);
+
+const MANUAL_ID_COLUMNS = Object.freeze([
+  Object.freeze({ name: "operation_id", type: "TEXT", notnull: 1, pk: 1 }),
+  Object.freeze({ name: "account_key", type: "TEXT", notnull: 1, pk: 0 }),
+  Object.freeze({ name: "canonical_operation_id", type: "TEXT", notnull: 1, pk: 0 }),
+  Object.freeze({ name: "terminal_code", type: "TEXT", notnull: 0, pk: 0 }),
+  Object.freeze({ name: "created_at", type: "INTEGER", notnull: 1, pk: 0 }),
+  Object.freeze({ name: "updated_at", type: "INTEGER", notnull: 1, pk: 0 }),
+]);
+
+const LEGACY_COLUMNS = Object.freeze([
+  Object.freeze({ name: "account_key", type: "TEXT", notnull: 1, pk: 1 }),
+  Object.freeze({ name: "credential_generation", type: "INTEGER", notnull: 1, pk: 0 }),
+  Object.freeze({ name: "exhaustion_generation", type: "INTEGER", notnull: 1, pk: 0 }),
+  Object.freeze({ name: "operation_id", type: "TEXT", notnull: 1, pk: 0 }),
+  Object.freeze({ name: "state", type: "TEXT", notnull: 1, pk: 0 }),
+  Object.freeze({ name: "code", type: "TEXT", notnull: 0, pk: 0 }),
+  Object.freeze({ name: "created_at", type: "INTEGER", notnull: 1, pk: 0 }),
+  Object.freeze({ name: "updated_at", type: "INTEGER", notnull: 1, pk: 0 }),
+]);
+const PRIOR_COLUMNS = Object.freeze([
+  Object.freeze({ name: "account_key", type: "TEXT", notnull: 1, pk: 1 }),
+  Object.freeze({ name: "operation_kind", type: "TEXT", notnull: 1, pk: 0 }),
+  Object.freeze({ name: "credential_generation", type: "INTEGER", notnull: 0, pk: 0 }),
+  Object.freeze({ name: "exhaustion_generation", type: "INTEGER", notnull: 0, pk: 0 }),
+  Object.freeze({ name: "operation_id", type: "TEXT", notnull: 1, pk: 0 }),
+  Object.freeze({ name: "state", type: "TEXT", notnull: 1, pk: 0 }),
+  Object.freeze({ name: "code", type: "TEXT", notnull: 0, pk: 0 }),
+  Object.freeze({ name: "created_at", type: "INTEGER", notnull: 1, pk: 0 }),
+  Object.freeze({ name: "updated_at", type: "INTEGER", notnull: 1, pk: 0 }),
+]);
+
+function accountKey(accountId: string): string {
+  return createHash("sha256").update(`codex-reset-credit-operation\0${accountId}`).digest("hex");
+}
+
+function validateManualAccountId(accountId: string): void {
+  if (accountId !== MAIN_CODEX_ACCOUNT_ID && !isValidCodexAccountId(accountId)) {
+    throw new TypeError("invalid manual reset-credit account");
+  }
+}
+
+function manualPhysicalAccountKey(chatgptAccountId: string): string {
+  const normalized = chatgptAccountId.trim();
+  if (!normalized) throw new TypeError("invalid manual reset-credit credential identity");
+  return createHash("sha256")
+    .update(`codex-reset-credit-manual-physical\0${normalized}`)
+    .digest("hex");
+}
+
+function isGenerationNumber(value: unknown): value is number {
+  return Number.isSafeInteger(value) && Number(value) >= 0;
+}
+
+function parseRecord(row: ResetCreditOperationRow | null): ResetCreditOperationRecord | undefined {
+  if (!row) return undefined;
+  const state = row.state;
+  const code = row.code;
+  const joinedOperationId = row.joined_operation_id;
+  if (typeof row.account_key !== "string" || !ACCOUNT_KEY_PATTERN.test(row.account_key)
+    || (row.operation_kind !== "recovery" && row.operation_kind !== "manual")
+    || !isCodexResetCreditOperationId(row.operation_id)
+    || (joinedOperationId !== null
+      && (!isCodexResetCreditOperationId(joinedOperationId) || joinedOperationId === row.operation_id))
+    || typeof state !== "string" || !STATES.has(state)
+    || !isGenerationNumber(row.created_at)
+    || !isGenerationNumber(row.updated_at)
+    || row.updated_at < row.created_at) {
+    return undefined;
+  }
+  const recovery = row.operation_kind === "recovery";
+  const manual = row.operation_kind === "manual";
+  if (recovery !== (isGenerationNumber(row.credential_generation)
+      && isGenerationNumber(row.exhaustion_generation))
+    || manual !== (row.credential_generation === null
+      && row.exhaustion_generation === null)
+    || (recovery && joinedOperationId !== null)) {
+    return undefined;
+  }
+  const terminal = state === "confirmed" || state === "stopped";
+  if (!terminal && code !== null) return undefined;
+  const terminalState = typeof code === "string"
+    && Object.prototype.hasOwnProperty.call(TERMINAL_STATE_BY_CODE, code)
+    ? TERMINAL_STATE_BY_CODE[code as CodexResetCreditConsumeCode]
+    : undefined;
+  if (terminal !== (terminalState !== undefined)) return undefined;
+  if (terminal && state !== terminalState) return undefined;
+  return Object.freeze({
+    accountKey: row.account_key,
+    operationKind: row.operation_kind,
+    ...(recovery
+      ? {
+          credentialGeneration: row.credential_generation as number,
+          exhaustionGeneration: row.exhaustion_generation as number,
+        }
+      : {}),
+    operationId: row.operation_id,
+    ...(joinedOperationId === null ? {} : { joinedOperationId }),
+    state: state as ResetCreditOperationState,
+    ...(terminal ? { code: code as CodexResetCreditConsumeCode } : {}),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  });
+}
+
+function parseManualIdRecord(
+  row: ManualResetCreditOperationIdRow | null,
+): ManualResetCreditOperationIdRecord | undefined {
+  if (!row) return undefined;
+  const terminalCode = row.terminal_code;
+  if (!isCodexResetCreditOperationId(row.operation_id)
+    || typeof row.account_key !== "string" || !ACCOUNT_KEY_PATTERN.test(row.account_key)
+    || !isCodexResetCreditOperationId(row.canonical_operation_id)
+    || (terminalCode !== null
+      && (typeof terminalCode !== "string"
+        || !Object.prototype.hasOwnProperty.call(TERMINAL_STATE_BY_CODE, terminalCode)))
+    || !isGenerationNumber(row.created_at)
+    || !isGenerationNumber(row.updated_at)
+    || row.updated_at < row.created_at) {
+    return undefined;
+  }
+  return Object.freeze({
+    operationId: row.operation_id,
+    accountKey: row.account_key,
+    canonicalOperationId: row.canonical_operation_id,
+    ...(terminalCode === null ? {} : { terminalCode: terminalCode as CodexResetCreditConsumeCode }),
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  });
+}
+
+function assertColumnLayout(
+  database: Database,
+  tableName: string,
+  expectedColumns: readonly Readonly<{ name: string; type: string; notnull: number; pk: number }>[],
+): void {
+  const tableRows = database.query<TableListRow, []>("PRAGMA main.table_list").all()
+    .filter(row => row.name === tableName);
+  if (tableRows.length !== 1) throw new Error("invalid reset-credit operation ledger table");
+  const table = tableRows[0]!;
+  if (table.schema !== "main" || table.type !== "table" || table.ncol !== expectedColumns.length
+    || table.wr !== 1 || table.strict !== 1) {
+    throw new Error("invalid reset-credit operation ledger table");
+  }
+  const columns = database.query<TableColumnRow, []>(
+    `PRAGMA main.table_xinfo(${tableName})`,
+  ).all();
+  if (columns.length !== expectedColumns.length) {
+    throw new Error("invalid reset-credit operation ledger columns");
+  }
+  for (let index = 0; index < expectedColumns.length; index += 1) {
+    const actual = columns[index]!;
+    const expected = expectedColumns[index]!;
+    if (actual.cid !== index || actual.name !== expected.name || actual.type !== expected.type
+      || actual.notnull !== expected.notnull || actual.dflt_value !== null
+      || actual.pk !== expected.pk || actual.hidden !== 0) {
+      throw new Error("invalid reset-credit operation ledger columns");
+    }
+  }
+}
+
+function assertNoLedgerTriggers(database: Database, tableName: string): void {
+  const mainTrigger = database.query<{ name: unknown }, [string]>(`
+    SELECT name FROM main.sqlite_schema
+     WHERE type = 'trigger' AND tbl_name = ? COLLATE NOCASE LIMIT 1
+  `).get(tableName);
+  const tempTrigger = database.query<{ name: unknown }, [string]>(`
+    SELECT name FROM temp.sqlite_schema
+     WHERE type = 'trigger' AND tbl_name = ? COLLATE NOCASE LIMIT 1
+  `).get(tableName);
+  if (mainTrigger || tempTrigger) throw new Error("reset-credit operation ledger triggers are forbidden");
+}
+
+function failMigrationAfterFirstWriteForTests(): void {
+  if (migrationFaultForTests === "after_first_write") {
+    throw new Error("synthetic reset-credit operation migration failure");
+  }
+}
+
+/** @internal Test-only fault injection after the first transactional migration write. */
+export function setResetCreditOperationMigrationFaultForTests(
+  fault: ResetCreditOperationMigrationFaultForTests,
+): void {
+  if (process.env.OCX_TEST_HOME_GUARD !== "1") {
+    throw new Error("reset-credit operation migration faults require the repository test preload");
+  }
+  migrationFaultForTests = fault;
+}
+
+function migrateLegacyTable(database: Database): void {
+  assertColumnLayout(database, TABLE_NAME, LEGACY_COLUMNS);
+  assertNoLedgerTriggers(database, TABLE_NAME);
+  const legacyRows = database.query<{
+    account_key: unknown;
+    credential_generation: unknown;
+    exhaustion_generation: unknown;
+    operation_id: unknown;
+    state: unknown;
+    code: unknown;
+    created_at: unknown;
+    updated_at: unknown;
+  }, []>(`
+    SELECT account_key, credential_generation, exhaustion_generation, operation_id,
+           state, code, created_at, updated_at
+      FROM main.reset_credit_operations
+     ORDER BY account_key
+     LIMIT ${MAX_RESET_CREDIT_OPERATION_ACCOUNTS + 1}
+  `).all();
+  if (legacyRows.length > MAX_RESET_CREDIT_OPERATION_ACCOUNTS) {
+    throw new Error("invalid reset-credit operation ledger capacity");
+  }
+  const keys = new Set<string>();
+  const operations = new Set<string>();
+  for (const row of legacyRows) {
+    const record = parseRecord({
+      ...row,
+      operation_kind: "recovery",
+      joined_operation_id: null,
+    });
+    if (!record || keys.has(record.accountKey) || operations.has(record.operationId)) {
+      throw new Error("invalid reset-credit operation ledger state");
+    }
+    keys.add(record.accountKey);
+    operations.add(record.operationId);
+  }
+  database.exec(`ALTER TABLE main.${TABLE_NAME} RENAME TO ${LEGACY_TABLE_NAME}`);
+  failMigrationAfterFirstWriteForTests();
+  database.exec(CREATE_TABLE);
+  database.exec(`
+    INSERT INTO main.${TABLE_NAME} (
+      account_key, operation_kind, credential_generation, exhaustion_generation,
+      operation_id, joined_operation_id, state, code, created_at, updated_at
+    )
+    SELECT account_key, 'recovery', credential_generation, exhaustion_generation,
+           operation_id, NULL, state, code, created_at, updated_at
+      FROM main.${LEGACY_TABLE_NAME}
+  `);
+  database.exec(`DROP TABLE main.${LEGACY_TABLE_NAME}`);
+}
+
+function migratePriorTable(database: Database): void {
+  assertColumnLayout(database, TABLE_NAME, PRIOR_COLUMNS);
+  assertNoLedgerTriggers(database, TABLE_NAME);
+  const priorRows = database.query<Omit<ResetCreditOperationRow, "joined_operation_id">, []>(`
+    SELECT account_key, operation_kind, credential_generation, exhaustion_generation,
+           operation_id, state, code, created_at, updated_at
+      FROM main.reset_credit_operations
+     ORDER BY account_key
+     LIMIT ${MAX_RESET_CREDIT_OPERATION_ACCOUNTS + 1}
+  `).all();
+  if (priorRows.length > MAX_RESET_CREDIT_OPERATION_ACCOUNTS) {
+    throw new Error("invalid reset-credit operation ledger capacity");
+  }
+  const keys = new Set<string>();
+  const operations = new Set<string>();
+  for (const row of priorRows) {
+    const record = parseRecord({ ...row, joined_operation_id: null });
+    if (!record || keys.has(record.accountKey) || operations.has(record.operationId)) {
+      throw new Error("invalid reset-credit operation ledger state");
+    }
+    keys.add(record.accountKey);
+    operations.add(record.operationId);
+  }
+  database.exec(`ALTER TABLE main.${TABLE_NAME} RENAME TO ${PRIOR_TABLE_NAME}`);
+  failMigrationAfterFirstWriteForTests();
+  database.exec(CREATE_TABLE);
+  database.exec(`
+    INSERT INTO main.${TABLE_NAME} (
+      account_key, operation_kind, credential_generation, exhaustion_generation,
+      operation_id, joined_operation_id, state, code, created_at, updated_at
+    )
+    SELECT account_key, operation_kind, credential_generation, exhaustion_generation,
+           operation_id, NULL, state, code, created_at, updated_at
+      FROM main.${PRIOR_TABLE_NAME}
+  `);
+  database.exec(`DROP TABLE main.${PRIOR_TABLE_NAME}`);
+}
+
+function isExactLegacySchema(database: Database, schema: SchemaObjectRow): boolean {
+  if (schema.type !== "table" || schema.name !== TABLE_NAME || schema.tbl_name !== TABLE_NAME
+    || schema.sql !== LEGACY_CREATE_TABLE) return false;
+  try {
+    assertColumnLayout(database, TABLE_NAME, LEGACY_COLUMNS);
+    assertNoLedgerTriggers(database, TABLE_NAME);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isExactPriorSchema(database: Database, schema: SchemaObjectRow): boolean {
+  if (schema.type !== "table" || schema.name !== TABLE_NAME || schema.tbl_name !== TABLE_NAME
+    || schema.sql !== PRIOR_CREATE_TABLE) return false;
+  try {
+    assertColumnLayout(database, TABLE_NAME, PRIOR_COLUMNS);
+    assertNoLedgerTriggers(database, TABLE_NAME);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+type PrimaryTableInitialization = "created" | "migrated" | "existing";
+
+function assertCanonicalTable(database: Database): PrimaryTableInitialization {
+  const schemaRows = database.query<SchemaObjectRow, [string, string]>(`
+    SELECT type, name, tbl_name, sql
+      FROM main.sqlite_schema
+     WHERE name = ? COLLATE NOCASE OR tbl_name = ? COLLATE NOCASE
+     ORDER BY type, name
+     LIMIT 4
+  `).all(TABLE_NAME, TABLE_NAME);
+  let initialization: PrimaryTableInitialization;
+  if (schemaRows.length === 0) {
+    database.exec(CREATE_TABLE);
+    initialization = "created";
+  } else if (schemaRows.length === 1 && isExactLegacySchema(database, schemaRows[0]!)) {
+    migrateLegacyTable(database);
+    initialization = "migrated";
+  } else if (schemaRows.length === 1 && isExactPriorSchema(database, schemaRows[0]!)) {
+    migratePriorTable(database);
+    initialization = "migrated";
+  } else if (schemaRows.length !== 1
+    || schemaRows[0]?.type !== "table"
+    || schemaRows[0]?.name !== TABLE_NAME
+    || schemaRows[0]?.tbl_name !== TABLE_NAME
+    || schemaRows[0]?.sql !== EXPECTED_SCHEMA_SQL) {
+    throw new Error("invalid reset-credit operation ledger schema");
+  } else {
+    initialization = "existing";
+  }
+  assertColumnLayout(database, TABLE_NAME, EXPECTED_COLUMNS);
+  assertNoLedgerTriggers(database, TABLE_NAME);
+  return initialization;
+}
+
+function ensureManualIdTable(database: Database, allowCreate: boolean): boolean {
+  const schemaRows = database.query<SchemaObjectRow, [string, string]>(`
+    SELECT type, name, tbl_name, sql
+      FROM main.sqlite_schema
+     WHERE name = ? COLLATE NOCASE OR tbl_name = ? COLLATE NOCASE
+     ORDER BY type, name
+     LIMIT 4
+  `).all(MANUAL_ID_TABLE_NAME, MANUAL_ID_TABLE_NAME);
+  let created = false;
+  if (schemaRows.length === 0) {
+    if (!allowCreate) {
+      throw new Error("missing manual reset-credit operation identity schema");
+    }
+    database.exec(CREATE_MANUAL_ID_TABLE);
+    created = true;
+  } else if (schemaRows.length !== 1
+    || schemaRows[0]?.type !== "table"
+    || schemaRows[0]?.name !== MANUAL_ID_TABLE_NAME
+    || schemaRows[0]?.tbl_name !== MANUAL_ID_TABLE_NAME
+    || schemaRows[0]?.sql !== EXPECTED_MANUAL_ID_SCHEMA_SQL) {
+    throw new Error("invalid manual reset-credit operation identity schema");
+  }
+  assertColumnLayout(database, MANUAL_ID_TABLE_NAME, MANUAL_ID_COLUMNS);
+  assertNoLedgerTriggers(database, MANUAL_ID_TABLE_NAME);
+  return created;
+}
+
+function initializeTable(
+  database: Database,
+  validationScope: ResetCreditOperationKind,
+): Readonly<{
+  recordCount: number;
+  manualIdCount: number;
+}> {
+  const manualSchemaPresentBefore = database.query<{ present: number }, [string, string]>(`
+    SELECT 1 AS present
+      FROM main.sqlite_schema
+     WHERE name = ? COLLATE NOCASE OR tbl_name = ? COLLATE NOCASE
+     LIMIT 1
+  `).get(MANUAL_ID_TABLE_NAME, MANUAL_ID_TABLE_NAME) !== null;
+  const primaryInitialization = assertCanonicalTable(database);
+  if (primaryInitialization !== "existing" && manualSchemaPresentBefore) {
+    throw new Error("invalid partial reset-credit operation ledger schema");
+  }
+  const rows = database.query<ResetCreditOperationRow, []>(SELECT_ALL).all();
+  if (rows.length > MAX_RESET_CREDIT_OPERATION_ACCOUNTS) {
+    throw new Error("invalid reset-credit operation ledger capacity");
+  }
+  const accountKeys = new Set<string>();
+  const operationIds = new Set<string>();
+  const records = new Map<string, ResetCreditOperationRecord>();
+  for (const row of rows) {
+    const record = parseRecord(row);
+    const ids = record ? [record.operationId, ...(record.joinedOperationId ? [record.joinedOperationId] : [])] : [];
+    if (!record || accountKeys.has(record.accountKey) || ids.some(id => operationIds.has(id))) {
+      throw new Error("invalid reset-credit operation ledger state");
+    }
+    accountKeys.add(record.accountKey);
+    records.set(record.accountKey, record);
+    for (const id of ids) operationIds.add(id);
+  }
+
+  const manualTableCreated = ensureManualIdTable(database, primaryInitialization !== "existing");
+  if (manualTableCreated) {
+    for (const record of records.values()) {
+      if (record.operationKind !== "manual") continue;
+      const ids = [record.operationId, ...(record.joinedOperationId ? [record.joinedOperationId] : [])];
+      for (const operationId of ids) {
+        insertManualIdRecord(database, Object.freeze({
+          operationId,
+          accountKey: record.accountKey,
+          canonicalOperationId: record.operationId,
+          ...(record.code === undefined ? {} : { terminalCode: record.code }),
+          createdAt: record.createdAt,
+          updatedAt: record.updatedAt,
+        }));
+      }
+    }
+  }
+
+  const manualIdCount = database.query<{ count: unknown }, []>(SELECT_BOUNDED_MANUAL_ID_COUNT)
+    .get()?.count;
+  if (typeof manualIdCount !== "number" || !Number.isSafeInteger(manualIdCount) || manualIdCount < 0
+    || manualIdCount > MAX_MANUAL_RESET_CREDIT_OPERATION_IDS) {
+    throw new Error("invalid manual reset-credit operation identity capacity");
+  }
+  if (validationScope === "recovery") {
+    if (database.query<{ operation_id: unknown }, []>(SELECT_DUPLICATE_RECOVERY_MANUAL_ID).get()) {
+      throw new Error("duplicate reset-credit operation ids");
+    }
+    return Object.freeze({ recordCount: rows.length, manualIdCount });
+  }
+
+  const manualRows = database.query<ManualResetCreditOperationIdRow, []>(SELECT_ALL_MANUAL_IDS).all();
+  if (manualRows.length !== manualIdCount) throw new Error("invalid manual reset-credit operation identity state");
+  const manualIds = new Map<string, ManualResetCreditOperationIdRecord>();
+  for (const row of manualRows) {
+    const record = parseManualIdRecord(row);
+    if (!record || manualIds.has(record.operationId)) {
+      throw new Error("invalid manual reset-credit operation identity state");
+    }
+    manualIds.set(record.operationId, record);
+  }
+  for (const record of manualIds.values()) {
+    const canonical = manualIds.get(record.canonicalOperationId);
+    if (!canonical || canonical.operationId !== canonical.canonicalOperationId
+      || canonical.accountKey !== record.accountKey
+      || canonical.terminalCode !== record.terminalCode) {
+      throw new Error("invalid manual reset-credit operation identity state");
+    }
+    if (record.terminalCode === undefined) {
+      const current = records.get(record.accountKey);
+      if (!current || current.operationKind !== "manual" || isTerminal(current)
+        || current.operationId !== record.canonicalOperationId) {
+        throw new Error("invalid manual reset-credit operation identity state");
+      }
+    }
+  }
+  for (const record of records.values()) {
+    if (record.operationKind === "recovery") {
+      if (manualIds.has(record.operationId)) {
+        throw new Error("duplicate reset-credit operation ids");
+      }
+      continue;
+    }
+    const expectedIds = [record.operationId, ...(record.joinedOperationId ? [record.joinedOperationId] : [])];
+    for (const operationId of expectedIds) {
+      const identity = manualIds.get(operationId);
+      if (!identity || identity.accountKey !== record.accountKey
+        || identity.canonicalOperationId !== record.operationId
+        || identity.terminalCode !== record.code) {
+        throw new Error("invalid manual reset-credit operation identity state");
+      }
+    }
+  }
+  return Object.freeze({ recordCount: rows.length, manualIdCount });
+}
+
+function readRecord(database: Database, key: string): ResetCreditOperationRecord | undefined {
+  const rows = database.query<ResetCreditOperationRow, [string]>(SELECT_BY_KEY).all(key);
+  if (rows.length > 1) throw new Error("duplicate reset-credit operation records");
+  const row = rows[0];
+  const record = parseRecord(row ?? null);
+  if (row && !record) throw new Error("invalid reset-credit operation record");
+  return record;
+}
+
+function readManualIdRecord(
+  database: Database,
+  operationId: string,
+): ManualResetCreditOperationIdRecord | undefined {
+  const rows = database.query<ManualResetCreditOperationIdRow, [string]>(SELECT_MANUAL_ID)
+    .all(operationId);
+  if (rows.length > 1) throw new Error("duplicate manual reset-credit operation ids");
+  const row = rows[0];
+  const record = parseManualIdRecord(row ?? null);
+  if (row && !record) throw new Error("invalid manual reset-credit operation identity");
+  return record;
+}
+
+function sameManualIdRecord(
+  left: ManualResetCreditOperationIdRecord,
+  right: ManualResetCreditOperationIdRecord,
+): boolean {
+  return left.operationId === right.operationId
+    && left.accountKey === right.accountKey
+    && left.canonicalOperationId === right.canonicalOperationId
+    && left.terminalCode === right.terminalCode
+    && left.createdAt === right.createdAt
+    && left.updatedAt === right.updatedAt;
+}
+
+function assertStoredManualIdRecord(
+  database: Database,
+  expected: ManualResetCreditOperationIdRecord,
+): void {
+  const stored = readManualIdRecord(database, expected.operationId);
+  if (!stored || !sameManualIdRecord(stored, expected)) {
+    throw new Error("manual reset-credit operation identity write did not persist");
+  }
+}
+
+function insertManualIdRecord(
+  database: Database,
+  record: ManualResetCreditOperationIdRecord,
+): void {
+  const result = database.query(INSERT_MANUAL_ID).run(
+    record.operationId,
+    record.accountKey,
+    record.canonicalOperationId,
+    record.terminalCode ?? null,
+    record.createdAt,
+    record.updatedAt,
+  );
+  if (result.changes !== 1) throw new Error("manual reset-credit operation identity insert failed");
+  assertStoredManualIdRecord(database, record);
+}
+
+function operationOwner(database: Database, operationId: string): string | undefined {
+  const rows = database.query<{ account_key: unknown }, [string, string, string]>(SELECT_KEY_BY_OPERATION_ID)
+    .all(operationId, operationId, operationId);
+  if (rows.length > 1) throw new Error("duplicate reset-credit operation ids");
+  const owner = rows[0]?.account_key;
+  if (owner !== undefined && (typeof owner !== "string" || !ACCOUNT_KEY_PATTERN.test(owner))) {
+    throw new Error("invalid reset-credit operation owner");
+  }
+  return owner;
+}
+
+function sameRecord(left: ResetCreditOperationRecord, right: ResetCreditOperationRecord): boolean {
+  return left.accountKey === right.accountKey
+    && left.operationKind === right.operationKind
+    && left.credentialGeneration === right.credentialGeneration
+    && left.exhaustionGeneration === right.exhaustionGeneration
+    && left.operationId === right.operationId
+    && left.joinedOperationId === right.joinedOperationId
+    && left.state === right.state
+    && left.code === right.code
+    && left.createdAt === right.createdAt
+    && left.updatedAt === right.updatedAt;
+}
+
+function assertStoredRecord(
+  database: Database,
+  expected: ResetCreditOperationRecord,
+): void {
+  const stored = readRecord(database, expected.accountKey);
+  if (!stored || !sameRecord(stored, expected)) {
+    throw new Error("reset-credit operation write did not persist the expected record");
+  }
+}
+
+function compareGeneration(
+  record: ResetCreditOperationRecord,
+  generation: CodexResetCreditRecoveryGeneration,
+): -1 | 0 | 1 {
+  return compareCodexResetCreditRecoveryGenerationOrder({
+    accountId: generation.accountId,
+    credentialGeneration: record.credentialGeneration!,
+    exhaustionGeneration: record.exhaustionGeneration!,
+  }, generation);
+}
+
+function isTerminal(record: ResetCreditOperationRecord): boolean {
+  return record.state === "confirmed" || record.state === "stopped";
+}
+
+function isThenable(value: unknown): boolean {
+  return (typeof value === "object" && value !== null) || typeof value === "function"
+    ? typeof (value as { then?: unknown }).then === "function"
+    : false;
+}
+
+type Synchronous<T> = T extends PromiseLike<unknown> ? never : T;
+
+function withLedger<T>(validationScope: ResetCreditOperationKind, operation: (
+  database: Database,
+  recordCount: number,
+  manualIdCount: number,
+) => Synchronous<T>): T {
+  const path = prepareConfigMutationDatabasePathForWrite();
+  let database: Database | undefined;
+  let transactionOpen = false;
+  try {
+    database = new Database(path, { create: true });
+    try { chmodSync(path, 0o600); } catch { /* platform may ignore chmod */ }
+    database.exec("PRAGMA trusted_schema = OFF; PRAGMA busy_timeout = 0; PRAGMA synchronous = FULL; BEGIN IMMEDIATE");
+    transactionOpen = true;
+    initializeConfigGeneration(database);
+    const counts = initializeTable(database, validationScope);
+    const value = operation(database, counts.recordCount, counts.manualIdCount);
+    if (isThenable(value) || !database.inTransaction) {
+      throw new Error("reset-credit operation ledger work escaped its synchronous transaction");
+    }
+    database.exec("COMMIT");
+    transactionOpen = false;
+    return value;
+  } catch (error) {
+    if (transactionOpen) {
+      try { database?.exec("ROLLBACK"); } catch { /* close still releases the write lock */ }
+      transactionOpen = false;
+    }
+    throw error;
+  } finally {
+    try { database?.close(); } catch { /* operation already completed */ }
+  }
+}
+
+function isLedgerBusyError(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 : "";
+  return code === "SQLITE_BUSY" || code === "SQLITE_LOCKED"
+    || /database (?:is|table is) locked/i.test(message);
+}
+
+function warnLedgerUnavailable(error: unknown): void {
+  if (isLedgerBusyError(error)) return;
+  const nested = error instanceof NestedConfigMutationError;
+  // Native SQLite and filesystem errors may contain absolute, account-bearing
+  // paths. Keep this warning categorical rather than forwarding error.message.
+  console.warn(nested
+    ? "[opencodex] Reset-credit operation ledger refused a nested config mutation."
+    : "[opencodex] Reset-credit operation ledger is unavailable.");
+}
+
+function reportManualHistoryCapacity(count: number): void {
+  const level = count >= MAX_MANUAL_RESET_CREDIT_OPERATION_IDS
+    ? MAX_MANUAL_RESET_CREDIT_OPERATION_IDS
+    : count >= MANUAL_RESET_CREDIT_HISTORY_HIGH_WATER_MARK
+      ? MANUAL_RESET_CREDIT_HISTORY_HIGH_WATER_MARK
+      : 0;
+  if (level === 0 || level <= reportedManualHistoryLevel) return;
+  reportedManualHistoryLevel = level;
+  try {
+    console.warn(
+      `[opencodex] Reset-credit manual operation history is at ${count}/${MAX_MANUAL_RESET_CREDIT_OPERATION_IDS} entries${
+        level === MAX_MANUAL_RESET_CREDIT_OPERATION_IDS
+          ? "; new manual operation IDs, including aliases, are disabled until a maintainer expands capacity or applies an approved retirement policy."
+          : "."
+      }`,
+    );
+  } catch {
+    // Count-only operational reporting must never weaken the fail-closed result.
+  }
+}
+
+/**
+ * Throws `TypeError` for a malformed generation or timestamp. Runtime storage
+ * and contention failures are represented by a result kind.
+ */
+export function openResetCreditOperation(
+  generation: CodexResetCreditRecoveryGeneration,
+  now = Date.now(),
+): OpenResetCreditOperationResult {
+  const generationSnapshot = snapshotCodexResetCreditRecoveryGeneration(generation);
+  if (!Number.isSafeInteger(now) || now < 0) throw new TypeError("invalid reset-credit operation timestamp");
+  try {
+    return withLedger("recovery", (database, recordCount) => {
+      const key = accountKey(generationSnapshot.accountId);
+      const current = readRecord(database, key);
+      if (current) {
+        if (current.operationKind !== "recovery") {
+          return Object.freeze({ kind: "unresolved-prior-generation" as const });
+        }
+        const comparison = compareGeneration(current, generationSnapshot);
+        if (comparison > 0) return Object.freeze({ kind: "stale-generation" as const });
+        if (comparison === 0) {
+          if (isTerminal(current)) {
+            return Object.freeze({
+              kind: "terminal" as const,
+              operationId: current.operationId as CodexReservedOperationId,
+              code: current.code!,
+            });
+          }
+          return Object.freeze({
+            kind: "execute" as const,
+            operationId: current.operationId as CodexReservedOperationId,
+            resumed: true,
+          });
+        }
+        if (!isTerminal(current)) return Object.freeze({ kind: "unresolved-prior-generation" as const });
+      } else if (recordCount >= MAX_RESET_CREDIT_OPERATION_ACCOUNTS) {
+        return Object.freeze({ kind: "capacity" as const });
+      }
+
+      const operationId = randomUUID();
+      if (!isCodexResetCreditOperationId(operationId)) throw new Error("runtime generated invalid UUID");
+      if (operationOwner(database, operationId) !== undefined) {
+        throw new Error("duplicate reset-credit operation ids");
+      }
+      const values = [
+        "recovery",
+        generationSnapshot.credentialGeneration,
+        generationSnapshot.exhaustionGeneration,
+        operationId,
+        null,
+        "pending",
+        null,
+        now,
+        now,
+      ] as const;
+      const result = current
+        ? database.query(REPLACE_RECORD).run(...values, key)
+        : database.query(INSERT_RECORD).run(key, ...values);
+      if (result.changes !== 1) throw new Error("reset-credit operation reservation lost ownership");
+      assertStoredRecord(database, Object.freeze({
+        accountKey: key,
+        operationKind: "recovery",
+        credentialGeneration: generationSnapshot.credentialGeneration,
+        exhaustionGeneration: generationSnapshot.exhaustionGeneration,
+        operationId,
+        state: "pending",
+        createdAt: now,
+        updatedAt: now,
+      }));
+      return Object.freeze({
+        kind: "execute" as const,
+        operationId: operationId as CodexReservedOperationId,
+        resumed: false,
+      });
+    });
+  } catch (error) {
+    warnLedgerUnavailable(error);
+    return Object.freeze({ kind: "unavailable" });
+  }
+}
+
+function updateOperation(
+  owner: Readonly<{
+    accountKey: string;
+    operationKind: ResetCreditOperationKind;
+    credentialGeneration?: number;
+    exhaustionGeneration?: number;
+  }>,
+  operationId: string,
+  update: (record: ResetCreditOperationRecord) => ResetCreditOperationRecord | undefined,
+  afterWrite?: (database: Database, updated: ResetCreditOperationRecord) => void,
+): UpdateResetCreditOperationResult {
+  if (!isCodexResetCreditOperationId(operationId)) return Object.freeze({ kind: "mismatch" });
+  try {
+    return withLedger(owner.operationKind, database => {
+      const current = readRecord(database, owner.accountKey);
+      if (!current
+        || current.operationKind !== owner.operationKind
+        || current.credentialGeneration !== owner.credentialGeneration
+        || current.exhaustionGeneration !== owner.exhaustionGeneration
+        || current.operationId !== operationId) {
+        return Object.freeze({ kind: "mismatch" as const });
+      }
+      const updated = update(current);
+      if (!updated) return Object.freeze({ kind: "mismatch" as const });
+      const result = database.query(UPDATE_RECORD).run(
+        updated.state,
+        updated.code ?? null,
+        updated.updatedAt,
+        owner.accountKey,
+        owner.operationKind,
+        operationId,
+        owner.credentialGeneration ?? null,
+        owner.exhaustionGeneration ?? null,
+      );
+      if (result.changes !== 1) throw new Error("reset-credit operation update lost ownership");
+      assertStoredRecord(database, updated);
+      afterWrite?.(database, updated);
+      return Object.freeze({ kind: "updated" as const });
+    });
+  } catch (error) {
+    warnLedgerUnavailable(error);
+    return Object.freeze({ kind: "unavailable" });
+  }
+}
+
+/**
+ * Throws `TypeError` for a malformed generation or timestamp. An invalid
+ * operation id returns `mismatch`; runtime storage failures return `unavailable`.
+ */
+export function markResetCreditOperationAmbiguous(
+  generation: CodexResetCreditRecoveryGeneration,
+  operationId: string,
+  now = Date.now(),
+): UpdateResetCreditOperationResult {
+  if (!Number.isSafeInteger(now) || now < 0) throw new TypeError("invalid reset-credit operation timestamp");
+  const generationSnapshot = snapshotCodexResetCreditRecoveryGeneration(generation);
+  return updateOperation({
+    accountKey: accountKey(generationSnapshot.accountId),
+    operationKind: "recovery",
+    credentialGeneration: generationSnapshot.credentialGeneration,
+    exhaustionGeneration: generationSnapshot.exhaustionGeneration,
+  }, operationId, record => {
+    if (isTerminal(record)) return undefined;
+    return Object.freeze({
+      ...record,
+      state: "ambiguous",
+      code: undefined,
+      updatedAt: Math.max(record.updatedAt, now),
+    });
+  });
+}
+
+/**
+ * Throws `TypeError` for a malformed generation or timestamp. An invalid
+ * operation id or non-terminal code returns `mismatch`; runtime storage
+ * failures return `unavailable`.
+ */
+export function settleResetCreditOperation(
+  generation: CodexResetCreditRecoveryGeneration,
+  operationId: string,
+  code: CodexResetCreditConsumeCode,
+  now = Date.now(),
+): UpdateResetCreditOperationResult {
+  if (!Number.isSafeInteger(now) || now < 0) throw new TypeError("invalid reset-credit operation timestamp");
+  if (!Object.prototype.hasOwnProperty.call(TERMINAL_STATE_BY_CODE, code)) {
+    return Object.freeze({ kind: "mismatch" });
+  }
+  const generationSnapshot = snapshotCodexResetCreditRecoveryGeneration(generation);
+  return updateOperation({
+    accountKey: accountKey(generationSnapshot.accountId),
+    operationKind: "recovery",
+    credentialGeneration: generationSnapshot.credentialGeneration,
+    exhaustionGeneration: generationSnapshot.exhaustionGeneration,
+  }, operationId, record => {
+    if (isTerminal(record)) return record.code === code ? record : undefined;
+    return Object.freeze({
+      ...record,
+      state: TERMINAL_STATE_BY_CODE[code],
+      code,
+      updatedAt: Math.max(record.updatedAt, now),
+    });
+  });
+}
+
+function snapshotManualIdentity(identity: ManualResetCreditOperationIdentity): {
+  accountKey: string;
+  operationId: string;
+} {
+  if (!identity || typeof identity !== "object" || Array.isArray(identity)) {
+    throw new TypeError("manual reset-credit identity must be an object");
+  }
+  const value = identity as unknown as Record<string, unknown>;
+  const hasOwn = Object.prototype.hasOwnProperty;
+  if (!hasOwn.call(value, "accountId")
+    || !hasOwn.call(value, "chatgptAccountId")
+    || !hasOwn.call(value, "operationId")) {
+    throw new TypeError("manual reset-credit identity fields must be own properties");
+  }
+  const accountId = value.accountId;
+  const chatgptAccountId = value.chatgptAccountId;
+  const operationId = value.operationId;
+  if (!isCodexResetCreditOperationId(operationId)) {
+    throw new TypeError("invalid manual reset-credit operation id");
+  }
+  if (typeof accountId !== "string") throw new TypeError("invalid manual reset-credit account");
+  validateManualAccountId(accountId);
+  if (typeof chatgptAccountId !== "string") {
+    throw new TypeError("invalid manual reset-credit credential identity");
+  }
+  return Object.freeze({
+    accountKey: manualPhysicalAccountKey(chatgptAccountId),
+    operationId,
+  });
+}
+
+/**
+ * Reserve or restore one explicit manual redemption intent.
+ *
+ * Throws `TypeError` for malformed identity fields or `now`; these are caller
+ * contract violations. Durable-state and runtime failures return a result kind.
+ */
+export function openManualResetCreditOperation(
+  identity: ManualResetCreditOperationIdentity,
+  now = Date.now(),
+): OpenManualResetCreditOperationResult {
+  const owner = snapshotManualIdentity(identity);
+  if (!Number.isSafeInteger(now) || now < 0) throw new TypeError("invalid reset-credit operation timestamp");
+  try {
+    return withLedger("manual", (database, recordCount, manualIdCount) => {
+      reportManualHistoryCapacity(manualIdCount);
+      const admitNewCallerId = () => {
+        if (manualIdCount >= MAX_MANUAL_RESET_CREDIT_OPERATION_IDS) {
+          return Object.freeze({ kind: "capacity" as const });
+        }
+        const existingOwner = operationOwner(database, owner.operationId);
+        if (existingOwner !== undefined) {
+          return Object.freeze({
+            kind: existingOwner === owner.accountKey ? "unavailable" as const : "identity-mismatch" as const,
+          });
+        }
+        return undefined;
+      };
+
+      const reserve = (replaceCurrent: boolean): OpenManualResetCreditOperationResult => {
+        const rejected = admitNewCallerId();
+        if (rejected) return rejected;
+
+        const record: ResetCreditOperationRecord = Object.freeze({
+          accountKey: owner.accountKey,
+          operationKind: "manual",
+          operationId: owner.operationId,
+          state: "pending",
+          createdAt: now,
+          updatedAt: now,
+        });
+        const values = [
+          "manual",
+          null,
+          null,
+          owner.operationId,
+          null,
+          "pending",
+          null,
+          now,
+          now,
+        ] as const;
+        const result = replaceCurrent
+          ? database.query(REPLACE_RECORD).run(...values, owner.accountKey)
+          : database.query(INSERT_RECORD).run(owner.accountKey, ...values);
+        if (result.changes !== 1) throw new Error("manual reset-credit reservation lost ownership");
+        assertStoredRecord(database, record);
+        insertManualIdRecord(database, Object.freeze({
+          operationId: owner.operationId,
+          accountKey: owner.accountKey,
+          canonicalOperationId: owner.operationId,
+          createdAt: now,
+          updatedAt: now,
+        }));
+        return Object.freeze({
+          kind: "execute" as const,
+          operationId: owner.operationId as CodexReservedOperationId,
+          resumed: false,
+        });
+      };
+
+      const knownIdentity = readManualIdRecord(database, owner.operationId);
+      if (knownIdentity) {
+        if (knownIdentity.accountKey !== owner.accountKey) {
+          return Object.freeze({ kind: "identity-mismatch" as const });
+        }
+        if (knownIdentity.terminalCode !== undefined) {
+          return Object.freeze({
+            kind: "terminal" as const,
+            operationId: knownIdentity.canonicalOperationId as CodexReservedOperationId,
+            code: knownIdentity.terminalCode,
+          });
+        }
+        const current = readRecord(database, owner.accountKey);
+        if (!current || current.operationKind !== "manual" || isTerminal(current)
+          || current.operationId !== knownIdentity.canonicalOperationId) {
+          throw new Error("manual reset-credit operation identity lost its active owner");
+        }
+        return Object.freeze({
+          kind: "execute" as const,
+          operationId: current.operationId as CodexReservedOperationId,
+          resumed: true,
+        });
+      }
+
+      const current = readRecord(database, owner.accountKey);
+      if (current) {
+        if (current.operationKind !== "manual") {
+          return Object.freeze({ kind: "unavailable" as const });
+        }
+        if (!isTerminal(current)) {
+          const rejected = admitNewCallerId();
+          if (rejected) return rejected;
+          insertManualIdRecord(database, Object.freeze({
+            operationId: owner.operationId,
+            accountKey: owner.accountKey,
+            canonicalOperationId: current.operationId,
+            createdAt: now,
+            updatedAt: now,
+          }));
+          const joined: ResetCreditOperationRecord = Object.freeze({
+            ...current,
+            ...(current.joinedOperationId === undefined
+              ? { joinedOperationId: owner.operationId }
+              : {}),
+            updatedAt: Math.max(current.updatedAt, now),
+          });
+          const result = current.joinedOperationId === undefined
+            ? database.query(JOIN_MANUAL_OPERATION).run(
+                owner.operationId,
+                joined.updatedAt,
+                owner.accountKey,
+                current.operationId,
+              )
+            : database.query(TOUCH_MANUAL_OPERATION).run(
+                joined.updatedAt,
+                owner.accountKey,
+                current.operationId,
+              );
+          if (result.changes !== 1) {
+            throw new Error("manual reset-credit join lost ownership");
+          }
+          assertStoredRecord(database, joined);
+          // The upstream request keeps the original durable id. Every caller id
+          // is retained in the identity history; the first alias is also kept on
+          // the current row for compatibility with the previous schema.
+          return Object.freeze({
+            kind: "execute" as const,
+            operationId: current.operationId as CodexReservedOperationId,
+            resumed: true,
+          });
+        }
+        // Deliberate: a distinct caller id after a settled intent represents a
+        // new explicit redemption. Prior ids remain immutable in the history,
+        // so a delayed retry can never be reclassified as this new intent.
+        return reserve(true);
+      }
+      if (recordCount >= MAX_RESET_CREDIT_OPERATION_ACCOUNTS) {
+        return Object.freeze({ kind: "capacity" as const });
+      }
+      return reserve(false);
+    });
+  } catch (error) {
+    warnLedgerUnavailable(error);
+    return Object.freeze({ kind: "unavailable" });
+  }
+}
+
+/**
+ * Mark a reserved manual redemption as ambiguous.
+ *
+ * Throws `TypeError` for malformed identity fields or `now`. A missing or
+ * incompatible durable record returns the existing result kind.
+ */
+export function markManualResetCreditOperationAmbiguous(
+  identity: ManualResetCreditOperationIdentity,
+  now = Date.now(),
+): UpdateResetCreditOperationResult {
+  const owner = snapshotManualIdentity(identity);
+  if (!Number.isSafeInteger(now) || now < 0) throw new TypeError("invalid reset-credit operation timestamp");
+  return updateOperation({ accountKey: owner.accountKey, operationKind: "manual" }, owner.operationId, record => {
+    if (isTerminal(record)) return undefined;
+    return Object.freeze({ ...record, state: "ambiguous", code: undefined, updatedAt: Math.max(record.updatedAt, now) });
+  });
+}
+
+/**
+ * Settle a reserved manual redemption with one terminal consume code.
+ *
+ * Throws `TypeError` for malformed identity fields or `now`; an unsupported
+ * code or incompatible durable record returns `mismatch`.
+ */
+export function settleManualResetCreditOperation(
+  identity: ManualResetCreditOperationIdentity,
+  code: CodexResetCreditConsumeCode,
+  now = Date.now(),
+): UpdateResetCreditOperationResult {
+  const owner = snapshotManualIdentity(identity);
+  if (!Number.isSafeInteger(now) || now < 0) throw new TypeError("invalid reset-credit operation timestamp");
+  if (!Object.prototype.hasOwnProperty.call(TERMINAL_STATE_BY_CODE, code)) {
+    return Object.freeze({ kind: "mismatch" });
+  }
+  return updateOperation({ accountKey: owner.accountKey, operationKind: "manual" }, owner.operationId, record => {
+    if (isTerminal(record)) return record.code === code ? record : undefined;
+    return Object.freeze({
+      ...record,
+      state: TERMINAL_STATE_BY_CODE[code],
+      code,
+      updatedAt: Math.max(record.updatedAt, now),
+    });
+  }, (database, updated) => {
+    const result = database.query(SETTLE_MANUAL_IDS).run(
+      code,
+      updated.updatedAt,
+      owner.accountKey,
+      owner.operationId,
+      code,
+    );
+    if (result.changes < 1) {
+      throw new Error("manual reset-credit terminal identity update lost ownership");
+    }
+    const rows = database.query<ManualResetCreditOperationIdRow, [string, string]>(
+      SELECT_MANUAL_IDS_BY_CANONICAL,
+    ).all(owner.accountKey, owner.operationId);
+    if (rows.length < 1 || rows.length > MAX_MANUAL_RESET_CREDIT_OPERATION_IDS) {
+      throw new Error("invalid manual reset-credit terminal identity set");
+    }
+    for (const row of rows) {
+      const stored = parseManualIdRecord(row);
+      if (!stored || stored.accountKey !== owner.accountKey
+        || stored.canonicalOperationId !== owner.operationId
+        || stored.terminalCode !== code
+        || stored.updatedAt !== updated.updatedAt) {
+        throw new Error("manual reset-credit terminal identity write did not persist");
+      }
+    }
+  });
+}