@aifinpay/agent 2.3.0 → 2.5.0

package/dist/spendLedger.js

@@ -1,182 +1,575 @@
-// Making a daily spending cap mean something.
-//
-// The cap was a number compared against a ring buffer in one object's memory.
-// Two consequences, both of which defeat it entirely.
-//
-// A new process starts at zero. An agent that restarts — a crash loop, a
-// deploy, a cron that runs it hourly — gets its full daily allowance again each
-// time, and the "daily" cap becomes a per-process cap.
-//
-// And the check was separate from the record: `checkBudget()` read the total,
-// the payment happened, and only then was the cost added. Two calls in flight
-// at once both read the same total, both passed, and both paid. The cap held
-// only for an agent making one call at a time, which is not the kind of agent
-// this SDK is for.
-//
-// So a cap now goes through reserve → commit or release, where the reservation
-// is what the next check sees. A reservation that is never resolved — the
-// process died mid-payment — expires, because the alternative is an agent that
-// loses its budget to a crash and cannot spend again until tomorrow.
-//
-// Durability is engaged only when a daily cap is actually set. A library that
-// writes to a user's disk because it was imported would be rude; one that
-// promises a daily limit and forgets it on restart is worse.
-import { randomUUID } from "node:crypto";
-import { mkdir, readFile, writeFile, rename, open, unlink } from "node:fs/promises";
+// Daily caps use reserve → confirmed commit or proven nonpayment release.
+// Unknown outcomes never expire: a process restart is not evidence of no payment.
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, open, unlink } from "node:fs/promises";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-/** How long a reservation survives without being committed or released. */
-const RESERVATION_TTL_MS = 5 * 60_000;
-function liveTotal(entries, windowMs, now) {
-    const cutoff = now - windowMs;
-    return entries.filter((e) => e.at >= cutoff && (!e.expiresAt || e.expiresAt > now)).reduce((s, e) => s + e.usd, 0);
+import { dirname, join, resolve } from "node:path";
+import bs58 from "bs58";
+const RESERVATION_MARKER_MS = 5 * 60_000;
+const LOCK_TIMEOUT_MS = 5_000;
+const BINDING_FIELDS = [
+    "apiBaseUrl",
+    "paymentIssuer",
+    "payer",
+    "merchantId",
+    "scope",
+    "resource",
+    "networkMode",
+    "chain",
+    "asset",
+    "token",
+    "grossAmount",
+    "quoteId",
+];
+function validBinding(binding) {
+    const b = binding;
+    const optional = [
+        "walletIdentity",
+        "solanaAdmissionRateUsd",
+        "solanaMaxFeeLamports",
+        "solanaTransactionFeeLamports",
+        "quoteAdmissionVersion",
+    ];
+    return (!!binding &&
+        typeof binding === "object" &&
+        Object.keys(binding).every((k) => BINDING_FIELDS.includes(k) || optional.includes(k)) &&
+        (!Object.hasOwn(binding, "walletIdentity") ||
+            (typeof binding.walletIdentity === "string" &&
+                !!binding.walletIdentity)) &&
+        (b.quoteAdmissionVersion === undefined ||
+            (b.quoteAdmissionVersion === "1" &&
+                b.chain.startsWith("solana:") &&
+                b.grossAmount === "0" &&
+                b.quoteId === "quote-admission")) &&
+        ((b.solanaAdmissionRateUsd === undefined &&
+            b.solanaMaxFeeLamports === undefined &&
+            b.solanaTransactionFeeLamports === undefined) ||
+            (b.chain?.startsWith("solana:") &&
+                typeof b.solanaAdmissionRateUsd === "string" &&
+                /^(?:0|[1-9][0-9]*)(?:\.[0-9]{1,18})?$/.test(b.solanaAdmissionRateUsd) &&
+                Number(b.solanaAdmissionRateUsd) > 0 &&
+                Number(b.solanaAdmissionRateUsd) < 100000 &&
+                typeof b.solanaMaxFeeLamports === "string" &&
+                /^[1-9][0-9]*$/.test(b.solanaMaxFeeLamports) &&
+                typeof b.solanaTransactionFeeLamports === "string" &&
+                /^(?:0|[1-9][0-9]*)$/.test(b.solanaTransactionFeeLamports) &&
+                BigInt(b.solanaTransactionFeeLamports) <= BigInt(b.solanaMaxFeeLamports))) &&
+        BINDING_FIELDS.every((k) => typeof binding[k] === "string" && !!binding[k]));
+}
+function sameBinding(left, right) {
+    return (!!left &&
+        left.walletIdentity === right.walletIdentity &&
+        left.quoteAdmissionVersion === right.quoteAdmissionVersion &&
+        left.solanaAdmissionRateUsd === right.solanaAdmissionRateUsd &&
+        left.solanaMaxFeeLamports === right.solanaMaxFeeLamports &&
+        left.solanaTransactionFeeLamports === right.solanaTransactionFeeLamports &&
+        BINDING_FIELDS.every((k) => left[k] === right[k]));
+}
+function purchaseKey(binding) {
+    // Exact chain/token binding is retained, but changing rail cannot rebuy unresolved access.
+    return createHash("sha256")
+        .update(JSON.stringify([
+        binding.apiBaseUrl,
+        binding.paymentIssuer,
+        binding.walletIdentity ?? binding.payer,
+        binding.merchantId,
+        binding.scope,
+        binding.resource,
+        binding.networkMode,
+    ]))
+        .digest("hex");
+}
+function admissionAccessKey(binding) {
+    // An unknown admission cannot be bypassed by changing live/test or rail.
+    return purchaseKey({ ...binding, networkMode: "quote-access" });
+}
+function finiteNonnegative(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function validateCost(usd, cap, windowMs, binding) {
+    if (!finiteNonnegative(usd) ||
+        !(Number.isFinite(cap) && cap > 0) ||
+        !(Number.isFinite(windowMs) && windowMs > 0) ||
+        (binding !== undefined && !validBinding(binding)) ||
+        binding?.quoteAdmissionVersion !== undefined)
+        throw new Error("Invalid spending reservation parameters");
 }
 function prune(entries, windowMs, now) {
-    const cutoff = now - windowMs;
-    // Drop what has aged out of the window, and reservations nobody resolved.
-    return entries.filter((e) => e.at >= cutoff && (!e.expiresAt || e.expiresAt > now));
-}
-/**
- * In-process ledger. Correct for one process, forgotten on restart.
- *
- * Kept because it is the right answer when no daily cap is set — there is
- * nothing to remember — and because a test should not need a filesystem.
- */
+    // Retain confirmed-but-unreceipted purchases too; never silently remove their guard.
+    return entries.filter((e) => e.binding !== undefined || e.expiresAt !== undefined || e.receiptPending === true || e.at >= now - windowMs);
+}
+function liveTotal(entries, windowMs, now) {
+    return entries.filter((e) => e.expiresAt !== undefined || e.at >= now - windowMs).reduce((sum, e) => sum + e.usd, 0);
+}
+function reserveEntry(entries, usd, cap, windowMs, binding, admissionId) {
+    validateCost(usd, cap, windowMs, binding);
+    const now = Date.now(), live = prune(entries, windowMs, now);
+    const admission = admissionId ? live.find((e) => e.id === admissionId) : undefined;
+    if (admissionId &&
+        (!admission?.quoteAdmission ||
+            admission.quoteAdmission.phase !== "pending" ||
+            !admission.quoteAdmission.quoteJson ||
+            !binding ||
+            !sameAdmissionPurchase(admission.quoteAdmission.originalBinding, binding) ||
+            JSON.parse(admission.quoteAdmission.quoteJson).quote_id !== binding.quoteId ||
+            admission.txRef ||
+            admission.usd !== 0))
+        throw new Error("Monetary reservation disagrees with the durable quote admission");
+    if (binding &&
+        live.some((e) => e.id !== admissionId &&
+            e.binding &&
+            (e.expiresAt !== undefined || e.receiptPending === true) &&
+            (purchaseKey(e.binding) === purchaseKey(binding) ||
+                (e.quoteAdmission && admissionAccessKey(e.quoteAdmission.originalBinding) === admissionAccessKey(binding)))))
+        throw new Error("Unresolved purchase; recover its existing payment before buying again");
+    if (liveTotal(live, windowMs, now) + usd > cap)
+        return { entries: live, result: null };
+    if (admission) {
+        admission.usd = usd;
+        admission.at = now;
+        admission.binding = { ...binding };
+        admission.quoteAdmission.phase = "monetary";
+        admission.quoteAdmission.wasReserved = true;
+        return { entries: live, result: admission.id };
+    }
+    const id = randomUUID();
+    live.push({
+        id,
+        usd,
+        at: now,
+        expiresAt: now + RESERVATION_MARKER_MS,
+        ...(binding ? { binding: { ...binding } } : {}),
+    });
+    return { entries: live, result: id };
+}
+function commitEntry(entries, id, actualUsd) {
+    if (actualUsd !== undefined && !finiteNonnegative(actualUsd))
+        throw new Error("Invalid confirmed spending amount");
+    const entry = entries.find((e) => e.id === id);
+    if (!entry)
+        throw new Error("Spending reservation is missing; reconciliation is required");
+    if (entry.quoteAdmission && entry.quoteAdmission.phase !== "monetary")
+        throw new Error("Quote admission is not a monetary reservation");
+    if (entry.failure && actualUsd !== undefined && actualUsd !== entry.usd)
+        throw new Error("Finalized failure debit is immutable");
+    if (actualUsd !== undefined)
+        entry.usd = actualUsd;
+    if (entry.expiresAt !== undefined)
+        entry.at = Date.now();
+    delete entry.expiresAt;
+}
+function boundEntry(entries, id, txRef, binding, allowFailure = false) {
+    const entry = entries.find((e) => e.id === id);
+    if (!entry ||
+        (entry.failure && !allowFailure) ||
+        !validBinding(binding) ||
+        !sameBinding(entry.binding, binding) ||
+        entry.txRef !== txRef)
+        throw new Error("Recovery disagrees with the original spending reservation");
+    return entry;
+}
+function finalizeFailureEntry(entries, id, txRef, binding, feeUsd) {
+    const entry = entries.find((e) => e.id === id);
+    if (!entry ||
+        !validBinding(binding) ||
+        !sameBinding(entry.binding, binding) ||
+        entry.txRef !== txRef ||
+        !binding.solanaAdmissionRateUsd ||
+        !binding.solanaMaxFeeLamports ||
+        !finiteNonnegative(feeUsd) ||
+        feeUsd > entry.usd)
+        throw new Error("Finalized failure disagrees with the original spending reservation");
+    if (entry.failure) {
+        if (entry.usd !== feeUsd)
+            throw new Error("Finalized failure debit is immutable");
+        return;
+    }
+    if (entry.expiresAt === undefined)
+        throw new Error("Confirmed successful spending cannot become a failed debit");
+    // A late proof does not move the original admission into a new daily window.
+    // The immutable identity survives indefinitely; only its original timestamp
+    // decides whether this proven fee is counted in the current spending window.
+    entry.usd = feeUsd;
+    delete entry.expiresAt;
+    entry.failure = true;
+    delete entry.receiptPending;
+}
+function validTxRef(txRef, binding) {
+    if (!binding.chain.startsWith("solana:"))
+        return /^0x[0-9a-fA-F]{64}$/.test(txRef);
+    try {
+        return bs58.decode(txRef).length === 64 && bs58.encode(bs58.decode(txRef)) === txRef;
+    }
+    catch {
+        return false;
+    }
+}
+function prepareEntry(entries, id, txRef, binding) {
+    const entry = entries.find((e) => e.id === id);
+    if (!entry ||
+        (entry.quoteAdmission && entry.quoteAdmission.phase !== "monetary") ||
+        entry.expiresAt === undefined ||
+        !sameBinding(entry.binding, binding) ||
+        !validTxRef(txRef, binding) ||
+        (entry.txRef !== undefined && entry.txRef !== txRef))
+        throw new Error("Prepared transaction disagrees with the spending reservation");
+    entry.txRef = txRef;
+    entry.receiptPending = true;
+}
+function releaseEntries(entries, id) {
+    if (entries.some((e) => e.id === id && e.expiresAt === undefined))
+        throw new Error("Confirmed spending cannot be released");
+    const entry = entries.find((e) => e.id === id);
+    if (entry?.quoteAdmission) {
+        if (entry.quoteAdmission.phase !== "monetary")
+            throw new Error("Quote admission requires proof-bound closure");
+        // A proven prebroadcast failure can retry its original admission, never a new nonce.
+        entry.usd = 0;
+        entry.binding = { ...entry.quoteAdmission.originalBinding };
+        entry.quoteAdmission.phase = "pending";
+        delete entry.txRef;
+        delete entry.receiptPending;
+        return entries;
+    }
+    return entries.filter((e) => e.id !== id);
+}
+function sameAdmissionPurchase(original, binding) {
+    return (purchaseKey(original) === purchaseKey(binding) &&
+        ["payer", "chain", "asset", "token", "walletIdentity"].every((k) => original[k] === binding[k]));
+}
+function validAdmission(a) {
+    const x = a;
+    return (!!x &&
+        typeof x === "object" &&
+        typeof x.id === "string" &&
+        !!x.id &&
+        typeof x.ownerContext === "string" &&
+        !!x.ownerContext &&
+        x.ownerContext.length <= 65536 &&
+        typeof x.requestBody === "string" &&
+        !!x.requestBody &&
+        x.requestBody.length <= 65536 &&
+        typeof x.statement === "string" &&
+        !!x.statement &&
+        x.statement.length <= 65536 &&
+        (x.quoteJson === undefined ||
+            (typeof x.quoteJson === "string" && !!x.quoteJson && x.quoteJson.length <= 1048576)) &&
+        ["pending", "monetary", "terminal"].includes(x.phase) &&
+        (x.wasReserved === undefined || x.wasReserved === true) &&
+        validBinding(x.originalBinding) &&
+        x.originalBinding.quoteAdmissionVersion === "1" &&
+        (x.phase === "terminal" ? ["not-admitted", "expired-unbroadcast"].includes(x.terminal) : x.terminal === undefined));
+}
+async function beginAdmission(entries, binding, ownerContext, create) {
+    if (!validBinding(binding) || binding.quoteAdmissionVersion !== "1")
+        throw new Error("Invalid quote admission binding");
+    const existing = entries.find((e) => e.binding &&
+        (e.expiresAt !== undefined || e.receiptPending) &&
+        (purchaseKey(e.binding) === purchaseKey(binding) ||
+            (e.quoteAdmission && admissionAccessKey(e.quoteAdmission.originalBinding) === admissionAccessKey(binding))));
+    if (existing) {
+        if (!existing.quoteAdmission ||
+            existing.quoteAdmission.phase !== "pending" ||
+            !sameBinding(existing.binding, binding) ||
+            existing.quoteAdmission.ownerContext !== ownerContext)
+            throw new Error("Unresolved purchase or changed owner context; reconcile the original admission");
+        return structuredClone(existing.quoteAdmission);
+    }
+    const id = randomUUID(), result = {
+        id,
+        ownerContext,
+        ...(await create()),
+        phase: "pending",
+        originalBinding: { ...binding },
+    };
+    if (!validAdmission(result))
+        throw new Error("Malformed quote admission");
+    entries.push({
+        id,
+        usd: 0,
+        at: Date.now(),
+        expiresAt: Date.now() + RESERVATION_MARKER_MS,
+        binding: { ...binding },
+        quoteAdmission: result,
+    });
+    return structuredClone(result);
+}
+function boundAdmission(entries, id, binding, context) {
+    const entry = entries.find((e) => e.id === id);
+    if (!entry?.quoteAdmission ||
+        !sameBinding(entry.binding, binding) ||
+        entry.quoteAdmission.ownerContext !== context ||
+        entry.txRef ||
+        entry.usd !== 0)
+        throw new Error("Quote admission phase or owner binding mismatch");
+    return entry.quoteAdmission;
+}
+function adoptAdmission(entries, id, binding, context, quoteJson) {
+    const a = boundAdmission(entries, id, binding, context);
+    if (a.phase !== "pending" || (a.quoteJson !== undefined && a.quoteJson !== quoteJson))
+        throw new Error("Original quote admission is immutable");
+    a.quoteJson = quoteJson;
+    if (!validAdmission(a))
+        throw new Error("Malformed adopted quote");
+}
+function closeAdmission(entries, id, binding, context, terminal, quoteJson) {
+    const a = boundAdmission(entries, id, binding, context);
+    if (a.phase === "terminal" && a.terminal === terminal && a.quoteJson === quoteJson)
+        return;
+    if (a.phase !== "pending" ||
+        a.wasReserved ||
+        a.quoteJson !== quoteJson ||
+        (terminal === "not-admitted" ? quoteJson !== undefined : !quoteJson))
+        throw new Error("Ambiguous admission cannot be closed without original nonbroadcast evidence");
+    a.phase = "terminal";
+    a.terminal = terminal;
+    delete entries.find((e) => e.id === id).expiresAt;
+}
+function validateEntries(data) {
+    if (!Array.isArray(data) ||
+        data.some((e) => !e ||
+            typeof e !== "object" ||
+            typeof e.id !== "string" ||
+            !e.id ||
+            !finiteNonnegative(e.usd) ||
+            !finiteNonnegative(e.at) ||
+            (e.expiresAt !== undefined && !finiteNonnegative(e.expiresAt)) ||
+            (e.binding !== undefined && !validBinding(e.binding)) ||
+            (e.quoteAdmission !== undefined &&
+                (!validAdmission(e.quoteAdmission) ||
+                    e.quoteAdmission.id !== e.id ||
+                    (e.quoteAdmission.phase !== "monetary" &&
+                        (!sameBinding(e.binding, e.quoteAdmission.originalBinding) ||
+                            e.usd !== 0 ||
+                            e.txRef ||
+                            e.receiptPending)) ||
+                    (e.quoteAdmission.phase === "terminal") !==
+                        (e.expiresAt === undefined && e.quoteAdmission.phase !== "monetary"))) ||
+            (e.binding?.quoteAdmissionVersion !== undefined && !e.quoteAdmission) ||
+            (e.txRef !== undefined && (!e.binding || !validTxRef(e.txRef, e.binding))) ||
+            (e.receiptPending !== undefined && (typeof e.receiptPending !== "boolean" || !e.txRef)) ||
+            (e.failure !== undefined &&
+                (e.failure !== true ||
+                    e.expiresAt !== undefined ||
+                    e.receiptPending !== undefined ||
+                    !e.binding?.solanaAdmissionRateUsd ||
+                    !e.txRef))))
+        throw new Error("Spending ledger is malformed; refusing to reset the budget");
+    if (new Set(data.map((e) => e.id)).size !== data.length)
+        throw new Error("Spending ledger contains duplicate reservations");
+    const pendingKeys = data
+        .filter((e) => e.quoteAdmission && (e.expiresAt !== undefined || e.receiptPending))
+        .map((e) => admissionAccessKey(e.quoteAdmission.originalBinding));
+    if (new Set(pendingKeys).size !== pendingKeys.length)
+        throw new Error("Spending ledger contains duplicate quote admissions");
+    return data;
+}
+/** One-process implementation; use one shared instance or the local file ledger. */
 export class MemorySpendLedger {
     entries = [];
-    async reserve(usd, cap, windowMs) {
-        const now = Date.now();
-        this.entries = prune(this.entries, windowMs, now);
-        if (liveTotal(this.entries, windowMs, now) + usd > cap)
-            return null;
-        const id = randomUUID();
-        this.entries.push({ id, usd, at: now, expiresAt: now + RESERVATION_TTL_MS });
-        return id;
+    tail = Promise.resolve();
+    serial(fn) {
+        const task = this.tail.then(fn);
+        this.tail = task.catch(() => undefined);
+        return task;
     }
-    async commit(id, actualUsd) {
-        const e = this.entries.find((x) => x.id === id);
-        if (!e)
-            return;
-        if (typeof actualUsd === "number" && Number.isFinite(actualUsd))
-            e.usd = actualUsd;
-        delete e.expiresAt;
+    reserve(usd, cap, windowMs, binding, admissionId) {
+        return this.serial(() => {
+            const next = reserveEntry(this.entries, usd, cap, windowMs, binding, admissionId);
+            this.entries = next.entries;
+            return next.result;
+        });
     }
-    async release(id) {
-        this.entries = this.entries.filter((x) => x.id !== id);
+    commit(id, actualUsd) {
+        return this.serial(() => commitEntry(this.entries, id, actualUsd));
     }
-    async total(windowMs) {
-        return liveTotal(this.entries, windowMs, Date.now());
-    }
-}
-/**
- * A ledger on disk, so a restart does not hand the agent its allowance again.
- *
- * Read-modify-write is guarded by an exclusive lock file, which is atomic on a
- * local filesystem: `open(..., "wx")` either creates the file or fails, with no
- * window in between. That covers several processes on one host, which is what
- * a restart, a cron and a worker pool actually are.
- *
- * It does NOT cover several hosts — a lock file on a network filesystem is not
- * a lock. An agent fleet spanning machines should pass its own SpendLedger
- * backed by something that can answer for all of them; that is why this is an
- * interface rather than a class the SDK insists on.
- */
+    release(id) {
+        return this.serial(() => {
+            this.entries = releaseEntries(this.entries, id);
+        });
+    }
+    total(windowMs) {
+        return this.serial(() => liveTotal(this.entries, windowMs, Date.now()));
+    }
+    prepare(id, txRef, binding) {
+        return this.serial(() => prepareEntry(this.entries, id, txRef, binding));
+    }
+    assertRecovery(id, txRef, binding) {
+        return this.serial(() => {
+            boundEntry(this.entries, id, txRef, binding, true);
+        });
+    }
+    complete(id, txRef, binding) {
+        return this.serial(() => {
+            const entry = boundEntry(this.entries, id, txRef, binding);
+            commitEntry(this.entries, id);
+            delete entry.receiptPending;
+        });
+    }
+    finalizeFailure(id, txRef, binding, feeUsd) {
+        return this.serial(() => finalizeFailureEntry(this.entries, id, txRef, binding, feeUsd));
+    }
+    beginQuoteAdmission(binding, context, create) {
+        return this.serial(() => beginAdmission(this.entries, binding, context, create));
+    }
+    adoptQuoteAdmission(id, binding, context, quoteJson) {
+        return this.serial(() => adoptAdmission(this.entries, id, binding, context, quoteJson));
+    }
+    closeQuoteAdmission(id, binding, context, terminal, quoteJson) {
+        return this.serial(() => closeAdmission(this.entries, id, binding, context, terminal, quoteJson));
+    }
+}
+/** Shared cap for processes on one local filesystem; never a cross-host lock. */
 export class FileSpendLedger {
     path;
     constructor(path) {
         this.path = path;
     }
-    /** Default location, one file per agent address. */
     static forAgent(address) {
         const base = process.env.AIFINPAY_STATE_DIR || join(homedir(), ".aifinpay");
         return new FileSpendLedger(join(base, "spend", `${address.toLowerCase()}.json`));
     }
     async withLock(fn) {
-        await mkdir(dirname(this.path), { recursive: true });
+        const directoryPath = resolve(dirname(this.path));
+        await mkdir(directoryPath, { recursive: true, mode: 0o700 });
+        // Another process, or an earlier failed sync, may have just created these
+        // entries. Existing directories therefore also need ancestor durability.
+        for (let current = directoryPath;; current = dirname(current)) {
+            const directory = await open(current, "r");
+            try {
+                await directory.sync();
+            }
+            finally {
+                await directory.close();
+            }
+            if (dirname(current) === current)
+                break;
+        }
         const lockPath = `${this.path}.lock`;
-        // Spin briefly rather than failing: contention here is two of our own
-        // calls, and they are milliseconds apart.
         let handle;
-        const deadline = Date.now() + 5_000;
+        const deadline = Date.now() + LOCK_TIMEOUT_MS;
         for (;;) {
             try {
-                handle = await open(lockPath, "wx");
+                handle = await open(lockPath, "wx", 0o600);
                 break;
             }
             catch (e) {
                 if (e.code !== "EEXIST")
                     throw e;
-                if (Date.now() > deadline) {
-                    // A lock this old belongs to a process that died holding it. Breaking
-                    // it risks a lost update; refusing to ever break it means one crash
-                    // disables the cap permanently, which is worse.
-                    await unlink(lockPath).catch(() => { });
-                    continue;
-                }
-                await new Promise((r) => setTimeout(r, 5 + Math.floor(Math.random() * 15)));
+                if (Date.now() >= deadline)
+                    throw new Error("Spending ledger lock is held; stop all users and reconcile before owner lock recovery");
+                await new Promise((resolve) => setTimeout(resolve, 5 + Math.floor(Math.random() * 15)));
             }
         }
+        const temporary = `${this.path}.${process.pid}.${randomUUID()}.tmp`;
         try {
-            let entries = [];
+            let entries;
             try {
-                entries = JSON.parse(await readFile(this.path, "utf8"));
-                if (!Array.isArray(entries))
-                    entries = [];
+                entries = validateEntries(JSON.parse(await readFile(this.path, "utf8")));
             }
-            catch {
-                // Absent or unreadable. Starting from empty is the only option, and it
-                // errs toward letting a payment through rather than blocking one — the
-                // same direction the old in-memory behaviour erred, every restart.
+            catch (e) {
+                if (e.code !== "ENOENT")
+                    throw e;
                 entries = [];
             }
-            const { entries: next, result } = fn(entries);
-            // Write to a sibling and rename: a crash mid-write leaves the previous
-            // ledger intact rather than a truncated one.
-            const tmp = `${this.path}.${process.pid}.tmp`;
-            await writeFile(tmp, JSON.stringify(next), "utf8");
-            await rename(tmp, this.path);
+            const { entries: next, result } = await fn(entries);
+            validateEntries(next);
+            const file = await open(temporary, "wx", 0o600);
+            try {
+                await file.writeFile(JSON.stringify(next), "utf8");
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+            await rename(temporary, this.path);
+            const directory = await open(dirname(this.path), "r");
+            try {
+                await directory.sync();
+            }
+            finally {
+                await directory.close();
+            }
             return result;
         }
         finally {
-            await handle.close().catch(() => { });
-            await unlink(lockPath).catch(() => { });
+            try {
+                await unlink(temporary).catch((e) => {
+                    if (e.code !== "ENOENT")
+                        throw e;
+                });
+            }
+            finally {
+                try {
+                    await handle.close();
+                }
+                finally {
+                    // Only this acquired lock is removed, never one guessed stale from age.
+                    await unlink(lockPath);
+                }
+            }
         }
     }
-    async reserve(usd, cap, windowMs) {
-        return this.withLock((entries) => {
-            const now = Date.now();
-            const live = prune(entries, windowMs, now);
-            if (liveTotal(live, windowMs, now) + usd > cap) {
-                return { entries: live, result: null };
-            }
-            const id = randomUUID();
-            live.push({ id, usd, at: now, expiresAt: now + RESERVATION_TTL_MS });
-            return { entries: live, result: id };
-        });
+    async reserve(usd, cap, windowMs, binding, admissionId) {
+        return this.withLock((entries) => reserveEntry(entries, usd, cap, windowMs, binding, admissionId));
     }
     async commit(id, actualUsd) {
         await this.withLock((entries) => {
-            for (const e of entries) {
-                if (e.id === id) {
-                    if (typeof actualUsd === "number" && Number.isFinite(actualUsd))
-                        e.usd = actualUsd;
-                    delete e.expiresAt;
-                }
-            }
+            commitEntry(entries, id, actualUsd);
             return { entries, result: undefined };
         });
     }
     async release(id) {
-        await this.withLock((entries) => ({
-            entries: entries.filter((e) => e.id !== id),
-            result: undefined,
-        }));
+        await this.withLock((entries) => ({ entries: releaseEntries(entries, id), result: undefined }));
     }
     async total(windowMs) {
         return this.withLock((entries) => {
-            const now = Date.now();
-            const live = prune(entries, windowMs, now);
-            return { entries: live, result: liveTotal(live, windowMs, now) };
+            const live = prune(entries, windowMs, Date.now());
+            return { entries: live, result: liveTotal(live, windowMs, Date.now()) };
+        });
+    }
+    async prepare(id, txRef, binding) {
+        await this.withLock((entries) => {
+            prepareEntry(entries, id, txRef, binding);
+            return { entries, result: undefined };
+        });
+    }
+    async assertRecovery(id, txRef, binding) {
+        await this.withLock((entries) => {
+            boundEntry(entries, id, txRef, binding, true);
+            return { entries, result: undefined };
+        });
+    }
+    async complete(id, txRef, binding) {
+        await this.withLock((entries) => {
+            const entry = boundEntry(entries, id, txRef, binding);
+            commitEntry(entries, id);
+            delete entry.receiptPending;
+            return { entries, result: undefined };
+        });
+    }
+    async finalizeFailure(id, txRef, binding, feeUsd) {
+        await this.withLock((entries) => {
+            finalizeFailureEntry(entries, id, txRef, binding, feeUsd);
+            return { entries, result: undefined };
+        });
+    }
+    async beginQuoteAdmission(binding, context, create) {
+        return this.withLock(async (entries) => ({
+            entries,
+            result: await beginAdmission(entries, binding, context, create),
+        }));
+    }
+    async adoptQuoteAdmission(id, binding, context, quoteJson) {
+        await this.withLock((entries) => {
+            adoptAdmission(entries, id, binding, context, quoteJson);
+            return { entries, result: undefined };
+        });
+    }
+    async closeQuoteAdmission(id, binding, context, terminal, quoteJson) {
+        await this.withLock((entries) => {
+            closeAdmission(entries, id, binding, context, terminal, quoteJson);
+            return { entries, result: undefined };
         });
     }
 }