@bitkyc08/opencodex 2.58.0 → 2.60.0

package/src/lib/spend-reservation-ledger.ts

@@ -24,11 +24,10 @@
  * released. Minting a new root id mints no new budget because the identity and pool scopes
  * still hold the spend.
  *
- * SUPPORTED TOPOLOGY: this guarantees a single proxy process against its own journal. The
- * file is append-friendly, but nothing here serializes two live processes writing it, so a
- * second proxy sharing the same OPENCODEX_HOME is explicitly outside the guarantee -- that
- * needs a shared store with cross-process atomicity and is declared out of scope rather
- * than implied.
+ * SUPPORTED TOPOLOGY: one live writer owns one OPENCODEX_HOME journal. Every server and
+ * direct shared-ledger caller must hold the state-directory SQLite lease before replay,
+ * append or compaction. Independent homes remain independent; multi-host shared storage
+ * still needs a distributed transaction boundary and is outside this local lease.
  *
  * Five properties this file owes its callers. Each one was absent in the first draft, and a
  * budget that can be bypassed is worse than no budget because it looks like protection:
@@ -54,15 +53,24 @@
  *    that are re-applied to an EXISTING file rather than trusted from its creation.
  */
 
-import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { appendFileSync, chmodSync, closeSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
 import { createHash, randomBytes } from "node:crypto";
 import { dirname, join } from "node:path";
 // Definition-site import, not the ../config barrel -- same reasoning as
 // src/quota/reset-seen-store.ts: the barrel pulls ~154 modules into a hot path.
 import { getConfigDir } from "../config/paths";
+// Type-only, so it is erased before this module has a runtime import graph at all. The
+// config SHAPE is what this file needs; the config loader is what the note above keeps out.
+import type { OcxSpendConfig, OcxSpendScopeConfig } from "../types/config";
 import { assertNotRealHomeUnderTest } from "./test-home-guard";
 // Windows chmod does not remove inherited ACEs; this is the repository's icacls path.
 import { hardenSecretPath } from "./windows-secret-acl";
+import { assertSpendLedgerOwnerHeld, assertStorageOwned, bindSpendLedgerOwnerHome, mintSpendLedgerStorage, onSpendLedgerOwnerReleased, resetSpendLedgerOwnerBindingForTest, SpendLedgerOwnerError, spendLedgerOwnerSnapshot, spendLedgerStoragePath, type SpendLedgerStorage } from "./spend-ledger-owner";
+
+// The singleton belongs to the state directory it was built for. Releasing ownership hands that
+// directory to whoever comes next, so the in-memory copy goes with it and the next construction
+// replays the journal.
+onSpendLedgerOwnerReleased(() => { sharedLedger = undefined; });
 
 export const SPEND_LEDGER_JOURNAL_FILENAME = "spend-ledger.jsonl";
 /**
@@ -147,6 +155,24 @@ export interface SpendReservationRequest {
   /** Enforceable output ceiling -- max_output_tokens or the model's documented cap. */
   readonly outputCeilingTokens: number;
   readonly at?: number;
+  /**
+   * This send has ALREADY left for upstream and is being recorded rather than admitted.
+   *
+   * Some transports report their physical sends after the fact -- the passthrough ladder
+   * reports through `onSendsConsumed`, and an adapter's inner retries are counted when they
+   * finish. For those, a ceiling cannot refuse anything: the tokens are spent. Refusing to
+   * BOOK them is the worse answer, and it is not hypothetical -- it is a fixpoint. The send
+   * that would cross the ceiling gets dropped from the total, the total stays just under the
+   * limit forever, the scope never reads as exhausted, and the ceiling never fires again for
+   * any request. So a recorded send skips the limit check and takes the scope over its
+   * ceiling, which is what makes the NEXT request refusable.
+   *
+   * It skips the durability refusal for the same reason: a journal that could not be written
+   * is a reason to report degradation, never a reason to forget spend that really happened.
+   * Identity, capacity and journal-integrity denials still apply -- those say the ledger
+   * cannot account for the send at all, which no flag here can change.
+   */
+  readonly alreadySent?: boolean;
 }
 
 /**
@@ -370,7 +396,70 @@ function hardenLedgerFile(path: string, options: { readonly force?: boolean } =
   } catch { /* best-effort: a non-owner cannot chmod */ }
 }
 
-export function createFileSpendJournal(path: string): SpendJournal {
+/**
+ * Fault injection for the journal's own filesystem steps. Internal test contract, not config.
+ *
+ * The compaction cleanup only runs when a step after the exclusive create fails, and there is no
+ * portable way to make a validate, harden or rename fail on demand. Without a seam the cleanup
+ * would ship asserted by reading alone, which is how a failure path stays broken.
+ */
+export type SpendJournalFaultStep = "stat" | "create" | "write" | "validate" | "harden" | "rename";
+
+let journalFaultForTests: ((step: SpendJournalFaultStep, temp: string) => void) | undefined;
+
+export function setSpendJournalFaultForTests(
+  fault: ((step: SpendJournalFaultStep, temp: string) => void) | undefined,
+): void {
+  journalFaultForTests = fault;
+}
+
+/**
+ * Does a directory entry exist here, whatever it points at?
+ *
+ * `existsSync` follows the link, so a symlink whose target is absent reads as "no file" and an
+ * append then creates that target somewhere else entirely. The entry itself is what decides
+ * whether the safety check runs.
+ */
+function ledgerEntryExists(path: string): boolean {
+  try {
+    journalFaultForTests?.("stat", path);
+    lstatSync(path);
+    return true;
+  } catch (error) {
+    // Only a genuinely absent entry is absent. Treating every failure as "no file" meant a
+    // permission denial or an I/O error skipped assertSafeLedgerFile entirely and let the
+    // append proceed against whatever is actually there, which is the case that check exists
+    // for. An entry we cannot inspect is a refusal, not an empty slot.
+    //
+    // Raised as the module's typed error rather than the raw fs error: the path and errno of a
+    // state file are not something a client should be handed.
+    if ((error as NodeJS.ErrnoException | null)?.code === "ENOENT") return false;
+    throw new SpendLedgerOwnerError(
+      "SPEND_LEDGER_OWNER_UNAVAILABLE",
+      "Spend-ledger storage could not be inspected safely.",
+      { cause: error },
+    );
+  }
+}
+
+function assertSafeLedgerFile(path: string): void {
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1
+    || (process.platform !== "win32" && stat.uid !== process.getuid!())) {
+    throw new SpendLedgerOwnerError(
+      "SPEND_LEDGER_OWNER_UNAVAILABLE",
+      "Spend-ledger storage could not be opened safely.",
+    );
+  }
+}
+
+/**
+ * The production journal. Its location comes from the owned state directory and every touch
+ * proves that ownership, so there is no entrypoint here that writes a caller-chosen path.
+ */
+export function createOwnedFileSpendJournal(storage: SpendLedgerStorage): SpendJournal {
+  assertStorageOwned(storage);
+  const path = spendLedgerStoragePath(storage);
   const ensureDir = (): string => {
     const dir = dirname(path);
     // The guard runs before any mutation so a rejected write leaves nothing behind.
@@ -380,26 +469,66 @@ export function createFileSpendJournal(path: string): SpendJournal {
   };
   return {
     read(): string[] {
-      if (!existsSync(path)) return [];
+      assertStorageOwned(storage);
+      if (!ledgerEntryExists(path)) return [];
+      assertSafeLedgerFile(path);
       // Replay is once per process and is the moment a journal inherited from an older build
       // or a restored backup first passes through here.
       hardenLedgerFile(path, { force: true });
       return readFileSync(path, "utf8").split("\n").filter((line) => line.length > 0);
     },
     append(line: string): void {
+      assertStorageOwned(storage);
       ensureDir();
-      const created = !existsSync(path);
+      const created = !ledgerEntryExists(path);
+      if (!created) assertSafeLedgerFile(path);
       appendFileSync(path, line + "\n", { encoding: "utf8", mode: 0o600 });
+      assertSafeLedgerFile(path);
       hardenLedgerFile(path, { force: created });
     },
     rewrite(lines: string[]): void {
+      assertStorageOwned(storage);
       ensureDir();
       // Same directory, so the rename is atomic on the same filesystem: a crash mid-compaction
       // leaves either the old journal or the new one, never a half-written ledger.
-      const temp = `${path}.compact-${process.pid}`;
-      writeFileSync(temp, lines.map((line) => line + "\n").join(""), { encoding: "utf8", mode: 0o600 });
-      hardenLedgerFile(temp, { force: true });
-      renameSync(temp, path);
+      if (ledgerEntryExists(path)) assertSafeLedgerFile(path);
+      const temp = `${path}.compact-${process.pid}-${randomBytes(6).toString("hex")}`;
+      // The creation is INSIDE the cleanup, not before it. The name carries random bytes, so a
+      // failure anywhere after the entry exists used to leave a uniquely named file and the next
+      // attempt made another: repeated failures accumulated instead of overwriting one fixed
+      // name. Only an entry this call created is removed, so a name that turned out to belong to
+      // something else is left alone, and the original journal and the primary error survive.
+      let fd: number | undefined;
+      let created = false;
+      let renamed = false;
+      try {
+        // Exclusive create FIRST, so "this entry is ours" is a fact rather than a guess about
+        // which error a combined write threw. EEXIST leaves created false and the name is left
+        // alone; every failure after this point is cleaned because the entry is provably ours,
+        // including a write that stopped partway through.
+        journalFaultForTests?.("create", temp);
+        fd = openSync(temp, "wx", 0o600);
+        created = true;
+        journalFaultForTests?.("write", temp);
+        writeFileSync(fd, lines.map((line) => line + "\n").join(""), { encoding: "utf8" });
+        closeSync(fd);
+        fd = undefined;
+        journalFaultForTests?.("validate", temp);
+        assertSafeLedgerFile(temp);
+        journalFaultForTests?.("harden", temp);
+        hardenLedgerFile(temp, { force: true });
+        journalFaultForTests?.("rename", temp);
+        renameSync(temp, path);
+        renamed = true;
+      } finally {
+        if (fd !== undefined) {
+          try { closeSync(fd); } catch { /* the compaction failure is the one to report */ }
+        }
+        if (created && !renamed) {
+          try { unlinkSync(temp); } catch { /* same */ }
+        }
+      }
+      assertSafeLedgerFile(path);
       hardenLedgerFile(path, { force: true });
     },
   };
@@ -412,17 +541,26 @@ export function createFileSpendJournal(path: string): SpendJournal {
  * recorded spend, which would hand every scope a fresh allowance -- so it is a file, not a
  * per-process value.
  */
-export function loadOrCreateSpendLedgerSalt(path: string): string {
-  if (existsSync(path)) {
+export function loadOrCreateSpendLedgerSalt(storage: SpendLedgerStorage): string {
+  assertStorageOwned(storage);
+  const path = spendLedgerStoragePath(storage);
+  if (ledgerEntryExists(path)) {
+    assertSafeLedgerFile(path);
     hardenLedgerFile(path, { force: true });
     const existing = readFileSync(path, "utf8").trim();
     if (/^[0-9a-f]{32,}$/.test(existing)) return existing;
+    throw new SpendLedgerOwnerError(
+      "SPEND_LEDGER_OWNER_UNAVAILABLE",
+      "Spend-ledger storage could not be opened safely.",
+    );
   }
   const dir = dirname(path);
+  assertStorageOwned(storage);
   assertNotRealHomeUnderTest(dir);
   mkdirSync(dir, { recursive: true, mode: 0o700 });
   const salt = randomBytes(32).toString("hex");
-  writeFileSync(path, salt + "\n", { encoding: "utf8", mode: 0o600 });
+  writeFileSync(path, salt + "\n", { encoding: "utf8", mode: 0o600, flag: "wx" });
+  assertSafeLedgerFile(path);
   hardenLedgerFile(path, { force: true });
   return salt;
 }
@@ -468,6 +606,20 @@ export interface SpendReservationLedger {
   prune(now?: number): void;
   /** Whether this send id is already known, and therefore refused. */
   knows(sendId: string): boolean;
+  /**
+   * Replace the live policy.
+   *
+   * Every figure already accounted survives: raising, lowering or clearing a ceiling changes
+   * what is REFUSED from here on and never what was spent. Rebuilding the ledger instead
+   * would replay the journal into a second set of maps while the first still holds this
+   * process's open reservations, and the two would then disagree about what is in flight.
+   */
+  reconfigure(next: SpendReservationPolicy): void;
+  /**
+   * The policy in force. A live read, not a copy: a caller that formats a refusal has to name
+   * the ceiling this ledger would enforce on the NEXT request, not the one it was built with.
+   */
+  readonly policy: SpendReservationPolicy;
   /** Journal writes that failed; a nonzero count means durability is degraded. */
   readonly persistFailures: number;
   /**
@@ -494,14 +646,25 @@ export function createSpendReservationLedger(options: {
    * no file anyone could correlate.
    */
   readonly salt?: string;
+  /**
+   * Shared production ledgers prove their exact ownership before reading or changing
+   * accounting. Identity, not just the directory name: a handle kept across a release and a
+   * reacquire describes a journal another writer may have changed in between.
+   */
+  readonly assertOwnedAccounting?: () => void;
 } = {}): SpendReservationLedger {
-  const policy = options.policy ?? DEFAULT_SPEND_RESERVATION_POLICY;
+  // Mutable because the ceilings are operator configuration, and configuration is reloadable.
+  // The three bounds below are read through functions for the same reason: a value captured
+  // at construction would answer for the policy this ledger was BUILT with, and an operator
+  // who raised a bound would keep the old one until the process restarted.
+  let policy = options.policy ?? DEFAULT_SPEND_RESERVATION_POLICY;
   const journal = options.journal;
   const now = options.now ?? (() => Date.now());
   const salt = options.salt ?? "";
-  const maxTrackedScopes = policy.maxTrackedScopes ?? DEFAULT_MAX_TRACKED_SCOPES;
-  const maxTrackedSends = policy.maxTrackedSends ?? DEFAULT_MAX_TRACKED_SENDS;
-  const compactAfterRecords = policy.compactAfterRecords ?? DEFAULT_COMPACT_AFTER_RECORDS;
+  const assertOwnedAccounting = options.assertOwnedAccounting;
+  const maxTrackedScopes = (): number => policy.maxTrackedScopes ?? DEFAULT_MAX_TRACKED_SCOPES;
+  const maxTrackedSends = (): number => policy.maxTrackedSends ?? DEFAULT_MAX_TRACKED_SENDS;
+  const compactAfterRecords = (): number => policy.compactAfterRecords ?? DEFAULT_COMPACT_AFTER_RECORDS;
   const scopes = new Map<string, ScopeState>();
   const reservations = new Map<string, Reservation>();
   let persistFailures = 0;
@@ -553,7 +716,8 @@ export function createSpendReservationLedger(options: {
       journal.append(JSON.stringify(record));
       recordsOnDisk += 1;
       return true;
-    } catch {
+    } catch (error) {
+      if (error instanceof SpendLedgerOwnerError) throw error;
       // In-memory state still bounds this process; the counter is how a caller learns the
       // restart guarantee degraded instead of discovering it after the fact.
       persistFailures += 1;
@@ -753,7 +917,7 @@ export function createSpendReservationLedger(options: {
    */
   const compact = (at: number): void => {
     const rewrite = journal?.rewrite;
-    if (!journal || !rewrite || recordsOnDisk < compactAfterRecords) return;
+    if (!journal || !rewrite || recordsOnDisk < compactAfterRecords()) return;
     const checkpoint: JournalRecord = {
       v: 1,
       kind: "checkpoint",
@@ -780,7 +944,8 @@ export function createSpendReservationLedger(options: {
     try {
       rewrite.call(journal, [JSON.stringify(checkpoint)]);
       recordsOnDisk = 1;
-    } catch {
+    } catch (error) {
+      if (error instanceof SpendLedgerOwnerError) throw error;
       // Compaction is maintenance, not accounting: a failed rewrite leaves the previous
       // journal intact and every figure in it still replayable.
       persistFailures += 1;
@@ -791,12 +956,12 @@ export function createSpendReservationLedger(options: {
   const makeRoom = (refs: readonly ScopeRef[], at: number): SpendDenial | undefined => {
     evictSends(at, false);
     evictScopes(at, false);
-    while (reservations.size >= maxTrackedSends) {
+    while (reservations.size >= maxTrackedSends()) {
       if (evictSends(at, true) === 0) return { reason: "tracking-capacity-exhausted" };
     }
     let fresh = 0;
     for (const ref of refs) if (!scopes.has(scopeKey(ref.scope, ref.alias))) fresh += 1;
-    while (scopes.size + fresh > maxTrackedScopes) {
+    while (scopes.size + fresh > maxTrackedScopes()) {
       if (evictScopes(at, true) === 0) {
         return { reason: "tracking-capacity-exhausted", scope: refs[0]?.scope };
       }
@@ -805,11 +970,15 @@ export function createSpendReservationLedger(options: {
   };
 
   return {
-    get persistFailures() { return persistFailures; },
-    get corruptRecords() { return corruptRecords; },
-    get degraded() { return persistFailures > 0 || corruptRecords > 0; },
+    // Every figure this ledger reports describes a journal it must still own. Reporting one
+    // after ownership ended is the same error as writing then, with a quieter symptom.
+    get persistFailures() { assertOwnedAccounting?.(); return persistFailures; },
+    get corruptRecords() { assertOwnedAccounting?.(); return corruptRecords; },
+    get degraded() { assertOwnedAccounting?.(); return persistFailures > 0 || corruptRecords > 0; },
+    get policy() { assertOwnedAccounting?.(); return policy; },
 
     reserve(request: SpendReservationRequest): SpendReservationDecision {
+      assertOwnedAccounting?.();
       const tokens = sanitizeTokens(request.inputTokens) + sanitizeTokens(request.outputCeilingTokens);
       const at = request.at ?? now();
       const send = aliasFor("send", request.sendId);
@@ -834,7 +1003,9 @@ export function createSpendReservationLedger(options: {
       // reservation booked on the scopes that would have passed. Reading state without
       // creating it matters here -- a denied request must not leave a tracked scope behind.
       for (const ref of refs) {
-        const limit = limitFor(ref.scope);
+        // A recorded send has no limit to fail: it already happened, and the point of booking
+        // it is to let the total go OVER the ceiling so the next request can be refused.
+        const limit = request.alreadySent === true ? undefined : limitFor(ref.scope);
         if (limit === undefined) continue;
         const state = scopes.get(scopeKey(ref.scope, ref.alias));
         const projected = (state ? state.settled + state.reserved + state.unresolved : 0) + tokens;
@@ -853,7 +1024,7 @@ export function createSpendReservationLedger(options: {
       // limit a failed write refuses the request rather than admitting one that a restart
       // would forget -- which is exactly the disk-full and permission case durability is for.
       const durable = append({ v: 1, kind: "reserve", send, targets: refs, tokens, at });
-      if (!durable && enforced) {
+      if (!durable && enforced && request.alreadySent !== true) {
         return { reserved: false, denial: { reason: "reserve-not-durable", sendId: request.sendId } };
       }
       applyReserve(send, refs, tokens, at);
@@ -862,6 +1033,7 @@ export function createSpendReservationLedger(options: {
     },
 
     markDispatched(sendId: string): boolean {
+      assertOwnedAccounting?.();
       const send = aliasFor("send", sendId);
       const reservation = reservations.get(send);
       if (!reservation || reservation.status !== "open") return false;
@@ -872,6 +1044,7 @@ export function createSpendReservationLedger(options: {
     },
 
     abandon(sendId: string): boolean {
+      assertOwnedAccounting?.();
       const send = aliasFor("send", sendId);
       const reservation = reservations.get(send);
       // Only an UNDISPATCHED reservation may be released for free. Once bytes have left for
@@ -884,6 +1057,7 @@ export function createSpendReservationLedger(options: {
     },
 
     settle(sendId: string, usage: SpendUsage): boolean {
+      assertOwnedAccounting?.();
       const send = aliasFor("send", sendId);
       const reservation = reservations.get(send);
       if (!reservation || !isLive(reservation.status)) return false;
@@ -895,6 +1069,7 @@ export function createSpendReservationLedger(options: {
     },
 
     markLost(sendId: string): boolean {
+      assertOwnedAccounting?.();
       const send = aliasFor("send", sendId);
       const reservation = reservations.get(send);
       if (!reservation || !isLive(reservation.status)) return false;
@@ -905,10 +1080,14 @@ export function createSpendReservationLedger(options: {
     },
 
     knows(sendId: string): boolean {
+      assertOwnedAccounting?.();
       return reservations.has(aliasFor("send", sendId));
     },
 
     snapshot(scope: SpendScope, scopeId: string): ScopeSpendSnapshot | undefined {
+      // Reading accounting from a handle whose ownership has ended is as wrong as writing it:
+      // the figures describe a journal this process no longer owns.
+      assertOwnedAccounting?.();
       const state = scopes.get(scopeKey(scope, aliasFor(scope, scopeId)));
       if (!state) return undefined;
       return {
@@ -920,39 +1099,157 @@ export function createSpendReservationLedger(options: {
     },
 
     exhausted(scope: SpendScope, scopeId: string): boolean {
+      assertOwnedAccounting?.();
       const state = scopes.get(scopeKey(scope, aliasFor(scope, scopeId)));
       return state !== undefined && isExhausted(scope, state);
     },
 
     prune(at: number = now()): void {
+      assertOwnedAccounting?.();
       // Removal requires BOTH inactive and not exhausted inside the window. An
       // exhausted-but-idle scope that was dropped would be recreated fresh under the
       // same id -- the exact laundering the ceiling exists to stop.
       evictSends(at, false);
       evictScopes(at, false);
     },
+
+    reconfigure(next: SpendReservationPolicy): void {
+      assertOwnedAccounting?.();
+      policy = next;
+    },
   };
 }
 
 let sharedLedger: SpendReservationLedger | undefined;
+/**
+ * The operator policy in effect. Held beside the ledger rather than inside it because the
+ * ledger is built lazily: a configured ceiling has to be remembered from startup until the
+ * first request that actually reserves, and an install that configures nothing must still
+ * open no journal.
+ */
+let sharedPolicy: SpendReservationPolicy = DEFAULT_SPEND_RESERVATION_POLICY;
+
+/** Whether any scope carries a ceiling -- that is, whether anything at all can be refused. */
+export function spendCeilingsConfigured(policy: SpendReservationPolicy = sharedPolicy): boolean {
+  return policy.root.maxTokens !== undefined
+    || policy.identity.maxTokens !== undefined
+    || policy.pool.maxTokens !== undefined;
+}
+
+/** The policy the process-wide ledger enforces right now. */
+export function sharedSpendPolicy(): SpendReservationPolicy {
+  return sharedPolicy;
+}
+
+const spendScopeLimitFromConfig = (scope: OcxSpendScopeConfig | undefined): SpendScopeLimit =>
+  scope?.maxTokens !== undefined && Number.isFinite(scope.maxTokens) && scope.maxTokens > 0
+    ? { maxTokens: Math.trunc(scope.maxTokens) }
+    : {};
+
+/**
+ * The ledger policy an operator's `spend` section asks for.
+ *
+ * An absent section, an empty one, and one whose every ceiling is absent all produce the
+ * unconfigured default: observe-only accounting that refuses nothing. That equivalence is the
+ * load-bearing part. This ledger is on and journaling by default, so shipping a default
+ * ceiling would start refusing real traffic on the first upgrade that ran this code, against
+ * a number nobody chose. There is deliberately no default figure here at all.
+ */
+export function spendPolicyFromConfig(spend: OcxSpendConfig | undefined): SpendReservationPolicy {
+  const retentionDays = spend?.retentionDays;
+  return {
+    root: spendScopeLimitFromConfig(spend?.root),
+    identity: spendScopeLimitFromConfig(spend?.identity),
+    pool: spendScopeLimitFromConfig(spend?.pool),
+    retentionMs: retentionDays !== undefined && Number.isFinite(retentionDays) && retentionDays > 0
+      ? Math.trunc(retentionDays) * 24 * 60 * 60_000
+      : DEFAULT_SPEND_RESERVATION_POLICY.retentionMs,
+  };
+}
+
+/**
+ * Apply an operator policy to the process-wide ledger.
+ *
+ * Startup calls this with the loaded config, and a reload may call it again: the ledger keeps
+ * every figure it has already accounted, so changing a ceiling changes what is refused from
+ * here on and never what was spent. It does not CREATE the ledger -- an install that
+ * configures no ceiling must not open a journal merely because the server started.
+ */
+export function configureSharedSpendLedger(policy: SpendReservationPolicy): void {
+  // Recording a policy value touches no journal, so it needs no ownership. Changing a ledger
+  // that already exists does, because that ledger is a live view of an owned directory.
+  if (sharedLedger) {
+    assertSpendLedgerOwnerHeld();
+    bindSpendLedgerOwnerHome();
+  }
+  sharedPolicy = policy;
+  sharedLedger?.reconfigure(policy);
+}
 
 /**
  * Process-wide ledger backed by the journal under OPENCODEX_HOME. Created lazily so
  * importing the module -- or running a request path that never reserves -- touches no
- * disk.
+ * disk. One directory at a time, not one directory for the life of the process: the singleton
+ * is discarded when its ownership ends, so a later directory replays its own journal rather
+ * than inheriting figures from the previous one.
  */
 export function sharedSpendLedger(): SpendReservationLedger {
+  assertSpendLedgerOwnerHeld();
+  bindSpendLedgerOwnerHome();
   if (!sharedLedger) {
-    const home = getConfigDir();
+    // Minted by the owner module from the directory it actually owns, and carrying the exact
+    // ownership they were minted under. Nothing here chooses a path or supplies its own guard.
+    const journalStorage = mintSpendLedgerStorage(SPEND_LEDGER_JOURNAL_FILENAME);
+    const saltStorage = mintSpendLedgerStorage(SPEND_LEDGER_SALT_FILENAME);
+    const journalPath = spendLedgerStoragePath(journalStorage);
+    const saltPath = spendLedgerStoragePath(saltStorage);
+    const assertOwnedAccounting = (): void => {
+      assertStorageOwned(journalStorage);
+      if (ledgerEntryExists(journalPath)) assertSafeLedgerFile(journalPath);
+      if (ledgerEntryExists(saltPath)) assertSafeLedgerFile(saltPath);
+    };
     sharedLedger = createSpendReservationLedger({
-      journal: createFileSpendJournal(join(home, SPEND_LEDGER_JOURNAL_FILENAME)),
-      salt: loadOrCreateSpendLedgerSalt(join(home, SPEND_LEDGER_SALT_FILENAME)),
+      journal: createOwnedFileSpendJournal(journalStorage),
+      salt: loadOrCreateSpendLedgerSalt(saltStorage),
+      policy: sharedPolicy,
+      assertOwnedAccounting,
     });
   }
   return sharedLedger;
 }
 
-/** Test seam. Production never discards the ledger: that would reset a spent budget. */
+const MAX_DIAGNOSTIC_ERROR_COUNT = 1_000_000;
+
+/** Scalar-only and side-effect-free: reading diagnostics never constructs or replays. */
+export function spendLedgerDiagnosticsSnapshot(): {
+  readonly ownership: "held" | "unheld";
+  readonly initialized: boolean;
+  readonly configured: boolean;
+  readonly degraded: boolean;
+  readonly persistFailures: number;
+  readonly corruptRecords: number;
+} {
+  const ledger = sharedLedger;
+  const bounded = (value: number): number => Math.min(MAX_DIAGNOSTIC_ERROR_COUNT, Math.max(0, value));
+  return {
+    ...spendLedgerOwnerSnapshot(),
+    initialized: ledger !== undefined,
+    configured: spendCeilingsConfigured(sharedPolicy),
+    degraded: ledger?.degraded ?? false,
+    persistFailures: bounded(ledger?.persistFailures ?? 0),
+    corruptRecords: bounded(ledger?.corruptRecords ?? 0),
+  };
+}
+
+/**
+ * Test seam for discarding the singleton outright.
+ *
+ * Production discards it too, but only with the ownership it belongs to, which is what
+ * `onSpendLedgerOwnerReleased` does. Neither path resets a spent budget: the journal is the
+ * durable record and the next construction replays it.
+ */
 export function resetSharedSpendLedgerForTest(): void {
   sharedLedger = undefined;
+  sharedPolicy = DEFAULT_SPEND_RESERVATION_POLICY;
+  resetSpendLedgerOwnerBindingForTest();
 }

package/src/lib/windows-system-proxy.ts

@@ -16,7 +16,7 @@ import { decodeWindowsTextBytes } from "./windows-text";
 const INTERNET_SETTINGS_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Internet Settings";
 
 export type WindowsSystemProxyResult =
-  | { kind: "proxy"; url: string }
+  | { kind: "proxy"; httpUrl?: string; httpsUrl?: string }
   | { kind: "disabled" }
   | { kind: "socks-only" }
   | { kind: "unsupported" }
@@ -63,35 +63,40 @@ export function readWindowsProxyRegistry(): WindowsProxyRegistryValues | null {
 
 /**
  * `ProxyServer` is either a bare `host:port` (applies to every scheme) or a semicolon list of
- * `scheme=host:port` entries. Prefer the https entry, then http; a SOCKS-only value cannot be
- * mirrored into HTTP_PROXY/HTTPS_PROXY.
+ * `scheme=host:port` entries. Bare values apply to both HTTP and HTTPS destinations; per-scheme
+ * values retain their WinINET scope. A SOCKS-only value cannot be mirrored into HTTP(S)_PROXY.
  */
-export function parseWindowsProxyServer(value: string): { kind: "proxy"; url: string } | { kind: "socks-only" } | { kind: "disabled" } {
+export function parseWindowsProxyServer(value: string): Extract<WindowsSystemProxyResult, { kind: "proxy" | "socks-only" | "disabled" }> {
   const trimmed = value.trim();
   if (!trimmed) return { kind: "disabled" };
-  if (!trimmed.includes("=")) return normalize(trimmed);
+  if (!trimmed.includes("=")) {
+    const url = normalize(trimmed);
+    return url ? { kind: "proxy", httpUrl: url, httpsUrl: url } : { kind: "disabled" };
+  }
   const entries = new Map<string, string>();
   for (const part of trimmed.split(";")) {
     const eq = part.indexOf("=");
     if (eq <= 0) continue;
     entries.set(part.slice(0, eq).trim().toLowerCase(), part.slice(eq + 1).trim());
   }
-  const candidate = entries.get("https") || entries.get("http");
-  if (candidate) return normalize(candidate);
+  const httpUrl = normalize(entries.get("http") ?? "");
+  const httpsUrl = normalize(entries.get("https") ?? "");
+  if (httpUrl || httpsUrl) return { kind: "proxy", ...(httpUrl && { httpUrl }), ...(httpsUrl && { httpsUrl }) };
   if (entries.has("socks")) return { kind: "socks-only" };
   return { kind: "disabled" };
 }
 
-function normalize(hostPort: string): { kind: "proxy"; url: string } | { kind: "disabled" } {
+function normalize(hostPort: string): string | undefined {
+  if (!hostPort) return undefined;
   const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(hostPort) ? hostPort : `http://${hostPort}`;
   try {
     const url = new URL(withScheme);
-    if (!url.hostname || (url.protocol !== "http:" && url.protocol !== "https:")) return { kind: "disabled" };
+    if (!url.hostname || (url.protocol !== "http:" && url.protocol !== "https:")) return undefined;
     // Keep userinfo: a credentialed proxy is valid in HTTP_PROXY. Only the log strips it.
     const auth = url.username ? `${url.username}${url.password ? `:${url.password}` : ""}@` : "";
-    return { kind: "proxy", url: `${url.protocol}//${auth}${url.host}` };
+    return `${url.protocol}//${auth}${url.host}`;
   } catch {
-    return { kind: "disabled" };
+    return undefined;
   }
 }