taximeter 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Taximeter
 
+## 0.2.0
+
+### Minor Changes
+
+- Default to rejecting parsed payments for unknown assets. Set `policy.unknownAsset` to `allow` to opt in and configure exact contract-address budgets for custom tokens.
+
+  Replace full ledger replay during payment gating with transactional, rebuildable payment projections and exact timestamp-indexed budget sums. Preserve append-only source records, retry and settlement semantics, and precise rolling-window boundaries. Existing databases migrate to schema version 2 when opened; older 0.1.x clients cannot reopen the migrated schema.
+
 ## 0.1.2
 
 ### Patch Changes

package/README.md

@@ -51,7 +51,7 @@ Open a terminal in this source checkout, with Node 20+ and npm installed.
 You should now see:
 
 ```text
-Taximeter 0.1.2
+Taximeter 0.2.0
 Proxy: http://127.0.0.1:8402
 Dashboard: http://127.0.0.1:8403
 Point an HTTP-proxy-aware agent at http://127.0.0.1:8402.
@@ -116,6 +116,8 @@ their amount before forwarding the payment replay.
 Policy evaluation and reservation share one SQLite transaction, so concurrent
 payments cannot all consume the same remaining capacity.
 Append-only payment, outcome, and diagnostic records derive every total with BigInt.
+Payment checks use an incrementally maintained index of exact budget sums, avoiding
+a replay of all prior payments. The index can be rebuilt from the original log.
 The local dashboard polls that ledger every second and exports the same counted amounts.
 
 An initial 402 challenge is an offer, not spend. Reported settlement counts as
@@ -138,6 +140,11 @@ as text to prevent a spreadsheet application from rounding them.
 
 ## Configuration
 
+When upgrading from 0.1.x, upgrade all writers together. Opening an existing
+ledger builds the new budget index once and upgrades its schema; the source log
+is preserved. Older 0.1.x clients cannot reopen that migrated database. Parsed
+unknown assets now require an explicit opt-in as described below.
+
 No file is required. Start from [the example](taximeter.config.example.json) when
 needed. Precedence, highest first: flags, environment, explicit `--config` file,
 `taximeter.config.json` in the working directory, `~/.taximeter/config.json`, defaults.
@@ -158,6 +165,7 @@ invalid values are rejected with Zod.
 | `policy.allowPayTo` | `[]` | Empty allows all recipients; otherwise exact case-insensitive addresses. |
 | `policy.maxSinglePayment` | `"1000000"` | One USDC per authorization by default; `null` disables the cap. |
 | `policy.maxSingleAsset` | `USDC` | Asset to which the single-payment cap applies. |
+| `policy.unknownAsset` | `"deny"` | `deny` blocks parsed payments whose network and contract are absent from the offline asset registry; `allow` opts in to those assets. |
 | `ports.proxy` | `8402` | Loopback HTTP listener; `0` selects an available port. |
 | `ports.dashboard` | `8403` | Loopback dashboard listener; `0` selects an available port. |
 | `db` | `~/.taximeter/ledger.db` | SQLite path; relative paths resolve against the working directory. |
@@ -168,9 +176,16 @@ All commands accept `--db` and `--config`. Start also accepts `--proxy-port`,
 `TAXIMETER_PORT`, and `TAXIMETER_DASHBOARD_PORT`.
 
 Missing task/agent labels share an **Unattributed** bucket. Supply `Taximeter-Task`
-and `Taximeter-Agent` headers, or SDK options. The local USDC registry recognizes
-Base and Base Sepolia; other contracts remain separate atomic-unit balances with
-unknown decimals. Default USDC budgets do not cap unknown assets.
+and `Taximeter-Agent` headers, or SDK options. The offline asset registry recognizes
+USDC by its network and contract on Base and Base Sepolia. Parsed payments for
+other assets are denied by default with `unknown_asset`; supplied symbols or
+decimal metadata cannot make a token known. Unsupported or unparseable payment
+formats still pass through with a diagnostic.
+
+Custom-token budgets require `policy.unknownAsset: "allow"`. This opts in to parsed
+unknown assets, which remain separate atomic-unit balances with unknown decimals.
+Configure budgets using the exact contract address and, when needed, its network.
+Default USDC budgets do not cap these assets; only matching budgets and caps apply.
 
 A denied replay receives HTTP 402 before it reaches the upstream. For a cap of
 140 atomic units already fully consumed, the response is:
@@ -185,9 +200,10 @@ A denied replay receives HTTP 402 before it reaches the upstream. For a cap of
 }
 ```
 
-Reasons are `host_denied`, `host_not_allowed`, `recipient_not_allowed`,
+Reasons are `host_denied`, `host_not_allowed`, `recipient_not_allowed`, `unknown_asset`,
 `max_single_payment`, `per_task_budget`, `per_agent_budget`, and `global_budget`.
-Host/recipient denials have `budget: null` and `remaining: null`.
+Host, recipient, and unknown-asset denials have `budget: null`, `spent: "0"`, and
+`remaining: null`.
 
 ## What this is not
 

package/SECURITY.md

@@ -7,7 +7,7 @@ on-chain settlement.
 
 ## Supported version
 
-Security fixes currently target the `0.1.0` release line. No older release line
+Security fixes currently target the `0.2.x` release line. No older release line
 is maintained. This policy describes support; it is not a claim that the package
 has already been published or independently audited.
 
@@ -32,6 +32,9 @@ against a hostile agent or another process running as the same user.
 - Unsupported or malformed payment forms pass through with a diagnostic.
   Supported parsing is narrower than the full x402 protocol; see
   [protocol notes](https://github.com/Ding808/taximeter/blob/main/SPEC-NOTES.md).
+- Parsed payments outside the offline asset registry are denied by default.
+  Setting `policy.unknownAsset` to `allow` permits them; only matching contract
+  budgets and caps then apply. Metadata supplied with a payment does not make its asset trusted.
 - HTTPS CONNECT tunnels encrypted bytes without metering their payments.
   Taximeter does not install a certificate authority or intercept TLS.
 - The SDK must wrap the transport inside the payment wrapper. Redirects and

package/dist/{chunk-DWBUWM3G.js → chunk-NXK2MCRO.js}

@@ -81,7 +81,8 @@ var policySchema = z2.strictObject({
   denyHosts: z2.array(labelSchema).default([]),
   allowPayTo: z2.array(labelSchema).default([]),
   maxSinglePayment: amountSchema.nullable().default("1000000"),
-  maxSingleAsset: labelSchema.default("USDC")
+  maxSingleAsset: labelSchema.default("USDC"),
+  unknownAsset: z2.enum(["allow", "deny"]).default("deny")
 });
 var portsSchema = z2.strictObject({
   proxy: z2.number().int().min(0).max(65535).default(8402),
@@ -109,7 +110,8 @@ var configPatchSchema = z2.strictObject({
     denyHosts: z2.array(labelSchema).optional(),
     allowPayTo: z2.array(labelSchema).optional(),
     maxSinglePayment: amountSchema.nullable().optional(),
-    maxSingleAsset: labelSchema.optional()
+    maxSingleAsset: labelSchema.optional(),
+    unknownAsset: z2.enum(["allow", "deny"]).optional()
   }).optional(),
   ports: z2.strictObject({
     proxy: z2.number().int().min(0).max(65535).optional(),
@@ -320,6 +322,23 @@ function spentForBudget(proposed, events, budget, scope, now) {
   return spent.toString();
 }
 function evaluate(proposed, events, config, now) {
+  return evaluateWithState(
+    proposed,
+    {
+      reserved: events.find(
+        (event) => event.paymentKey === proposed.paymentKey && countsAsSpend(event)
+      ),
+      spent: {
+        perTask: config.budgets.perTask ? spentForBudget(proposed, events, config.budgets.perTask, "perTask", now) : "0",
+        perAgent: config.budgets.perAgent ? spentForBudget(proposed, events, config.budgets.perAgent, "perAgent", now) : "0",
+        global: config.budgets.global ? spentForBudget(proposed, events, config.budgets.global, "global", now) : "0"
+      }
+    },
+    config,
+    now
+  );
+}
+function evaluateWithState(proposed, state, config, now) {
   const { policy } = config;
   const host = proposed.host.toLowerCase();
   if (policy.denyHosts.some((value) => value.toLowerCase() === host)) return deny("host_denied");
@@ -327,16 +346,16 @@ function evaluate(proposed, events, config, now) {
     return deny("host_not_allowed");
   if (policy.allowPayTo.length > 0 && !policy.allowPayTo.some((value) => value.toLowerCase() === proposed.payTo.toLowerCase()))
     return deny("recipient_not_allowed");
+  if (policy.unknownAsset === "deny" && !assetMetadata(proposed.network, proposed.asset).decimalsKnown)
+    return deny("unknown_asset");
   if (policy.maxSinglePayment !== null && matchesAsset(policy.maxSingleAsset, proposed) && BigInt(proposed.amount) > BigInt(policy.maxSinglePayment))
     return deny("max_single_payment", policy.maxSinglePayment);
-  const reserved = events.find(
-    (event) => event.paymentKey === proposed.paymentKey && countsAsSpend(event)
-  );
+  const reserved = state.reserved && countsAsSpend(state.reserved) ? state.reserved : void 0;
   for (const scope of ["perTask", "perAgent", "global"]) {
     const budget = config.budgets[scope];
     if (!budget || !matchesAsset(budget.asset, proposed) || budget.network && budget.network !== proposed.network)
       continue;
-    const spent = spentForBudget(proposed, events, budget, scope, now);
+    const spent = state.spent[scope];
     const reservedTime = reserved ? Date.parse(reserved.attemptedAt ?? reserved.ts) : -Infinity;
     const inWindow = reservedTime <= now && (!budget.window || reservedTime >= now - windows[budget.window]);
     const increment = reserved && (reserved.settlementStatus === "confirmed" || inWindow) ? 0n : BigInt(proposed.amount);
@@ -647,8 +666,9 @@ var Meter = class {
     if (!proposed) return {};
     try {
       return this.ledger.transaction(() => {
-        const events = this.ledger.view();
-        const decision = evaluate(proposed, events, this.config, Date.now());
+        const now = Date.now();
+        const state = this.ledger.policyState(proposed, this.config.budgets, now);
+        const decision = evaluateWithState(proposed, state, this.config, now);
         if (!decision.allowed) {
           this.ledger.append(
             paymentEventSchema.parse({
@@ -660,9 +680,7 @@ var Meter = class {
           );
           return { body: decision.body };
         }
-        const previous = events.find(
-          (event) => event.status === "observed" && event.paymentKey === proposed.paymentKey
-        );
+        const previous = state.reserved;
         const payment = previous ?? proposed;
         if (!previous) this.ledger.append(payment);
         const ts = (/* @__PURE__ */ new Date()).toISOString();
@@ -796,32 +814,324 @@ import { mkdirSync } from "fs";
 import { dirname as dirname2 } from "path";
 import Database from "better-sqlite3";
 import { v7 as v73 } from "uuid";
-import { z as z7 } from "zod";
+import { z as z8 } from "zod";
 
 // migrations/001.sql
 var __default = "CREATE TABLE schema_version (version INTEGER PRIMARY KEY);\nINSERT INTO schema_version VALUES (1);\nCREATE TABLE events (\n  id TEXT PRIMARY KEY,\n  ts TEXT NOT NULL,\n  taskId TEXT,\n  agentId TEXT,\n  host TEXT NOT NULL,\n  status TEXT NOT NULL CHECK (status IN ('observed', 'blocked')),\n  paymentKey TEXT NOT NULL,\n  payload TEXT NOT NULL CHECK (json_valid(payload))\n);\nCREATE INDEX events_ts ON events(ts);\nCREATE INDEX events_task ON events(taskId);\nCREATE INDEX events_agent ON events(agentId);\nCREATE INDEX events_host ON events(host);\nCREATE UNIQUE INDEX events_payment ON events(paymentKey) WHERE status = 'observed';\nCREATE TABLE outcomes (\n  id TEXT PRIMARY KEY,\n  ts TEXT NOT NULL,\n  paymentId TEXT NOT NULL REFERENCES events(id),\n  payload TEXT NOT NULL CHECK (json_valid(payload))\n);\nCREATE INDEX outcomes_payment ON outcomes(paymentId);\nCREATE TABLE diagnostics (\n  id TEXT PRIMARY KEY,\n  ts TEXT NOT NULL,\n  payload TEXT NOT NULL CHECK (json_valid(payload))\n);\nCREATE TRIGGER events_no_update BEFORE UPDATE ON events BEGIN SELECT RAISE(ABORT, 'append-only events'); END;\nCREATE TRIGGER events_no_delete BEFORE DELETE ON events BEGIN SELECT RAISE(ABORT, 'append-only events'); END;\nCREATE TRIGGER outcomes_no_update BEFORE UPDATE ON outcomes BEGIN SELECT RAISE(ABORT, 'append-only outcomes'); END;\nCREATE TRIGGER outcomes_no_delete BEFORE DELETE ON outcomes BEGIN SELECT RAISE(ABORT, 'append-only outcomes'); END;\nCREATE TRIGGER diagnostics_no_update BEFORE UPDATE ON diagnostics BEGIN SELECT RAISE(ABORT, 'append-only diagnostics'); END;\nCREATE TRIGGER diagnostics_no_delete BEFORE DELETE ON diagnostics BEGIN SELECT RAISE(ABORT, 'append-only diagnostics'); END;\n";
 
+// migrations/002.sql
+var __default2 = "CREATE TABLE cache_cursors (\n  id INTEGER PRIMARY KEY CHECK (id = 1),\n  eventRowid INTEGER NOT NULL CHECK (eventRowid >= 0),\n  outcomeRowid INTEGER NOT NULL CHECK (outcomeRowid >= 0)\n);\nINSERT INTO cache_cursors VALUES (1, 0, 0);\n\nCREATE TABLE cache_payments (\n  paymentId TEXT PRIMARY KEY REFERENCES events(id),\n  paymentKey TEXT NOT NULL UNIQUE,\n  payload TEXT NOT NULL CHECK (json_valid(payload)),\n  maxAttemptedAt TEXT\n);\n\nCREATE TABLE cache_attempts (\n  paymentId TEXT NOT NULL REFERENCES cache_payments(paymentId),\n  attemptId TEXT NOT NULL,\n  firstTs TEXT NOT NULL,\n  firstId TEXT NOT NULL,\n  winnerTs TEXT NOT NULL,\n  winnerId TEXT NOT NULL,\n  status TEXT NOT NULL CHECK (status IN ('unknown', 'confirmed', 'failed')),\n  payload TEXT NOT NULL CHECK (json_valid(payload)),\n  PRIMARY KEY (paymentId, attemptId)\n);\nCREATE INDEX cache_attempt_selection ON cache_attempts (\n  paymentId, status, firstTs, firstId COLLATE NOCASE, firstId DESC\n);\n\nCREATE TABLE cache_prefix (\n  partitionKey TEXT NOT NULL,\n  prefix TEXT NOT NULL,\n  amount TEXT NOT NULL CHECK (amount <> '' AND amount NOT GLOB '*[^0-9]*'),\n  PRIMARY KEY (partitionKey, prefix)\n) WITHOUT ROWID;\n\nINSERT INTO schema_version VALUES (2);\n";
+
+// src/ledger/cache.ts
+import { z as z7 } from "zod";
+var cursorSchema = z7.object({
+  eventRowid: z7.number().int().nonnegative(),
+  outcomeRowid: z7.number().int().nonnegative()
+});
+var sourceSchema = z7.object({
+  sourceRowid: z7.number().int().positive(),
+  id: z7.string(),
+  payload: z7.string()
+});
+var payloadSchema = z7.object({ payload: z7.string() });
+var paymentRowSchema = z7.object({
+  payload: z7.string(),
+  originalPayload: z7.string(),
+  maxAttemptedAt: z7.iso.datetime().nullable()
+});
+var attemptRowSchema = z7.object({
+  firstTs: z7.iso.datetime(),
+  firstId: z7.uuidv7(),
+  winnerTs: z7.iso.datetime(),
+  winnerId: z7.uuidv7(),
+  status: z7.enum(["unknown", "confirmed", "failed"])
+});
+var prefixRowSchema = z7.object({
+  prefix: z7.string().regex(/^[0-9a-f]{0,16}$/),
+  amount: integerStringSchema
+});
+var scopeSchema = z7.enum(["perTask", "perAgent", "global"]);
+var windowSchema = z7.enum(["1h", "24h", "7d", "30d"]);
+var timeSchema = z7.number().int().min(-864e13).max(864e13);
+var windows2 = {
+  "1h": 36e5,
+  "24h": 864e5,
+  "7d": 6048e5,
+  "30d": 2592e6
+};
+var digits = "0123456789abcdef";
+var bias = 1n << 63n;
+function timeKey(milliseconds) {
+  const value = z7.number().int().parse(milliseconds);
+  const encoded = bias + BigInt(value);
+  if (encoded < 0n || encoded >= 1n << 64n) throw new Error("Timestamp outside cache index range");
+  return encoded.toString(16).padStart(16, "0");
+}
+function partition(payment, scope) {
+  const attribution = scope === "perTask" ? payment.taskId : scope === "perAgent" ? payment.agentId : null;
+  return JSON.stringify([scope, attribution ?? null, payment.network, payment.asset.toLowerCase()]);
+}
+function order2(left, right) {
+  return left.ts.localeCompare(right.ts) || left.id.localeCompare(right.id);
+}
+var LedgerCache = class {
+  constructor(database) {
+    this.database = database;
+  }
+  database;
+  statements = /* @__PURE__ */ new Map();
+  statement(sql) {
+    let statement = this.statements.get(sql);
+    if (!statement) {
+      statement = this.database.prepare(sql);
+      this.statements.set(sql, statement);
+    }
+    return statement;
+  }
+  /** The caller holds an immediate transaction throughout synchronization and budget gating. */
+  synchronize() {
+    const cursor = cursorSchema.parse(
+      this.statement("SELECT eventRowid, outcomeRowid FROM cache_cursors WHERE id = 1").get()
+    );
+    let eventRowid = cursor.eventRowid;
+    let outcomeRowid = cursor.outcomeRowid;
+    const eventQuery = this.statement(
+      "SELECT rowid AS sourceRowid, id, payload FROM events WHERE rowid > ? ORDER BY rowid LIMIT 256"
+    );
+    for (let batch = eventQuery.all(eventRowid); batch.length > 0; batch = eventQuery.all(eventRowid)) {
+      for (const input of batch) {
+        const row = sourceSchema.parse(input);
+        const payment = paymentEventSchema.parse(JSON.parse(row.payload));
+        if (payment.id !== row.id)
+          throw new Error("Payment row identity does not match its payload");
+        if (payment.status === "observed") {
+          const derived = paymentEventSchema.parse({
+            ...payment,
+            settlement_unknown: payment.settlementStatus === "unknown"
+          });
+          const inserted = this.statement(
+            "INSERT OR IGNORE INTO cache_payments (paymentId, paymentKey, payload, maxAttemptedAt) VALUES (?, ?, ?, NULL)"
+          ).run(payment.id, payment.paymentKey, JSON.stringify(derived));
+          if (inserted.changes > 0) this.changeContribution(void 0, derived);
+        }
+        eventRowid = row.sourceRowid;
+      }
+    }
+    const outcomeQuery = this.statement(
+      "SELECT rowid AS sourceRowid, id, payload FROM outcomes WHERE rowid > ? ORDER BY rowid LIMIT 256"
+    );
+    for (let batch = outcomeQuery.all(outcomeRowid); batch.length > 0; batch = outcomeQuery.all(outcomeRowid)) {
+      for (const input of batch) {
+        const row = sourceSchema.parse(input);
+        const outcome = outcomeSchema.parse(JSON.parse(row.payload));
+        if (outcome.id !== row.id)
+          throw new Error("Outcome row identity does not match its payload");
+        this.applyOutcome(outcome);
+        outcomeRowid = row.sourceRowid;
+      }
+    }
+    if (eventRowid !== cursor.eventRowid || outcomeRowid !== cursor.outcomeRowid) {
+      this.statement("UPDATE cache_cursors SET eventRowid = ?, outcomeRowid = ? WHERE id = 1").run(
+        eventRowid,
+        outcomeRowid
+      );
+    }
+  }
+  rebuild() {
+    this.database.exec(
+      "DELETE FROM cache_prefix; DELETE FROM cache_attempts; DELETE FROM cache_payments; UPDATE cache_cursors SET eventRowid = 0, outcomeRowid = 0 WHERE id = 1"
+    );
+    this.synchronize();
+  }
+  reservation(paymentKey) {
+    const key = z7.string().min(1).parse(paymentKey);
+    const row = payloadSchema.optional().parse(this.statement("SELECT payload FROM cache_payments WHERE paymentKey = ?").get(key));
+    return row ? paymentEventSchema.parse(JSON.parse(row.payload)) : void 0;
+  }
+  spent(proposed, inputScope, inputWindow, now) {
+    const payment = paymentEventSchema.parse(proposed);
+    const scope = scopeSchema.parse(inputScope);
+    const window = windowSchema.optional().parse(inputWindow);
+    const end = timeSchema.parse(now);
+    const key = partition(payment, scope);
+    const upper = this.prefixTotal(key, end);
+    const lower = window ? this.prefixTotal(key, end - windows2[window] - 1) : 0n;
+    const result = upper - lower;
+    if (result < 0n) throw new Error("Cached budget total is inconsistent");
+    return result.toString();
+  }
+  applyOutcome(outcome) {
+    const row = paymentRowSchema.optional().parse(
+      this.statement(
+        "SELECT c.payload, c.maxAttemptedAt, e.payload AS originalPayload FROM cache_payments c JOIN events e ON e.id = c.paymentId WHERE c.paymentId = ?"
+      ).get(outcome.paymentId)
+    );
+    if (!row) return;
+    const previous = paymentEventSchema.parse(JSON.parse(row.payload));
+    const original = paymentEventSchema.parse(JSON.parse(row.originalPayload));
+    const attemptId = outcome.attemptId ?? outcome.paymentId;
+    const attempt = attemptRowSchema.optional().parse(
+      this.statement(
+        "SELECT firstTs, firstId, winnerTs, winnerId, status FROM cache_attempts WHERE paymentId = ? AND attemptId = ?"
+      ).get(outcome.paymentId, attemptId)
+    );
+    if (!attempt) {
+      this.statement(
+        "INSERT INTO cache_attempts (paymentId, attemptId, firstTs, firstId, winnerTs, winnerId, status, payload) VALUES (?, ?, ?, ?, ?, ?, ?, ?)"
+      ).run(
+        outcome.paymentId,
+        attemptId,
+        outcome.ts,
+        outcome.id,
+        outcome.ts,
+        outcome.id,
+        outcome.status,
+        JSON.stringify(outcome)
+      );
+    } else {
+      if (order2(outcome, { ts: attempt.firstTs, id: attempt.firstId }) < 0) {
+        this.statement(
+          "UPDATE cache_attempts SET firstTs = ?, firstId = ? WHERE paymentId = ? AND attemptId = ?"
+        ).run(outcome.ts, outcome.id, outcome.paymentId, attemptId);
+      }
+      const newer = order2(outcome, { ts: attempt.winnerTs, id: attempt.winnerId }) > 0;
+      const wins = attempt.status === "confirmed" ? outcome.status === "confirmed" && newer : outcome.status === "confirmed" || newer;
+      if (wins) {
+        this.statement(
+          "UPDATE cache_attempts SET winnerTs = ?, winnerId = ?, status = ?, payload = ? WHERE paymentId = ? AND attemptId = ?"
+        ).run(
+          outcome.ts,
+          outcome.id,
+          outcome.status,
+          JSON.stringify(outcome),
+          outcome.paymentId,
+          attemptId
+        );
+      }
+    }
+    const maxAttemptedAt = outcome.attemptedAt && (!row.maxAttemptedAt || outcome.attemptedAt > row.maxAttemptedAt) ? outcome.attemptedAt : row.maxAttemptedAt;
+    const selected = this.selectedOutcome(outcome.paymentId);
+    const status = original.settlementStatus === "confirmed" ? "confirmed" : selected?.status ?? original.settlementStatus;
+    const current = paymentEventSchema.parse({
+      ...original,
+      ...maxAttemptedAt ? { attemptedAt: maxAttemptedAt } : {},
+      settlementStatus: status,
+      settlement_unknown: status === "unknown",
+      ...selected?.txHash ? { txHash: selected.txHash } : {}
+    });
+    this.changeContribution(previous, current);
+    this.statement(
+      "UPDATE cache_payments SET payload = ?, maxAttemptedAt = ? WHERE paymentId = ?"
+    ).run(JSON.stringify(current), maxAttemptedAt, outcome.paymentId);
+  }
+  selectedOutcome(paymentId) {
+    for (const status of ["confirmed", "unknown"]) {
+      const row2 = payloadSchema.optional().parse(
+        this.statement(
+          "SELECT payload FROM cache_attempts WHERE paymentId = ? AND status = ? ORDER BY firstTs, firstId COLLATE NOCASE, firstId DESC LIMIT 1"
+        ).get(paymentId, status)
+      );
+      if (row2) return outcomeSchema.parse(JSON.parse(row2.payload));
+    }
+    const row = payloadSchema.optional().parse(
+      this.statement(
+        "SELECT payload FROM cache_attempts WHERE paymentId = ? AND status = 'failed' ORDER BY firstTs DESC, firstId COLLATE NOCASE DESC, firstId ASC LIMIT 1"
+      ).get(paymentId)
+    );
+    return row ? outcomeSchema.parse(JSON.parse(row.payload)) : void 0;
+  }
+  changeContribution(previous, current) {
+    const changes = /* @__PURE__ */ new Map();
+    const add = (payment, sign) => {
+      if (!countsAsSpend(payment)) return;
+      const amount = BigInt(payment.amount) * sign;
+      if (amount === 0n) return;
+      const timestamp = timeKey(Date.parse(payment.attemptedAt ?? payment.ts));
+      for (const scope of ["perTask", "perAgent", "global"]) {
+        const key = partition(payment, scope);
+        const nodes = changes.get(key) ?? /* @__PURE__ */ new Map();
+        for (let length = 0; length <= timestamp.length; length += 1) {
+          const prefix = timestamp.slice(0, length);
+          nodes.set(prefix, (nodes.get(prefix) ?? 0n) + amount);
+        }
+        changes.set(key, nodes);
+      }
+    };
+    if (previous) add(previous, -1n);
+    add(current, 1n);
+    for (const [key, nodes] of changes) {
+      const pending = [...nodes].filter(([, amount]) => amount !== 0n);
+      if (pending.length === 0) continue;
+      const existing = /* @__PURE__ */ new Map();
+      for (const input of this.statement(
+        "SELECT prefix, amount FROM cache_prefix WHERE partitionKey = ? AND prefix IN (SELECT value FROM json_each(?))"
+      ).iterate(key, JSON.stringify(pending.map(([prefix]) => prefix)))) {
+        const row = prefixRowSchema.parse(input);
+        existing.set(row.prefix, BigInt(row.amount));
+      }
+      for (const [prefix, delta] of pending) {
+        const next = (existing.get(prefix) ?? 0n) + delta;
+        if (next < 0n) throw new Error("Cached monetary contribution underflow");
+        if (next === 0n) {
+          this.statement("DELETE FROM cache_prefix WHERE partitionKey = ? AND prefix = ?").run(
+            key,
+            prefix
+          );
+        } else {
+          this.statement(
+            "INSERT INTO cache_prefix (partitionKey, prefix, amount) VALUES (?, ?, ?) ON CONFLICT(partitionKey, prefix) DO UPDATE SET amount = excluded.amount"
+          ).run(key, prefix, next.toString());
+        }
+      }
+    }
+  }
+  prefixTotal(key, time) {
+    const timestamp = timeKey(time);
+    const prefixes = [];
+    for (let index = 0; index < timestamp.length; index += 1) {
+      const digit = timestamp[index];
+      if (digit === void 0) throw new Error("Missing timestamp digit");
+      const limit = digits.indexOf(digit);
+      for (let child = 0; child < limit; child += 1) {
+        prefixes.push(`${timestamp.slice(0, index)}${digits[child]}`);
+      }
+    }
+    prefixes.push(timestamp);
+    let sum = 0n;
+    for (const input of this.statement(
+      "SELECT prefix, amount FROM cache_prefix WHERE partitionKey = ? AND prefix IN (SELECT value FROM json_each(?))"
+    ).iterate(key, JSON.stringify(prefixes))) {
+      sum += BigInt(prefixRowSchema.parse(input).amount);
+    }
+    return sum;
+  }
+};
+
 // src/ledger/store.ts
-var rowSchema = z7.object({ payload: z7.string() });
+var rowSchema = z8.object({ payload: z8.string() });
 var Ledger = class {
   database;
+  cache;
   constructor(input) {
-    const path = z7.string().min(1).parse(input);
+    const path = z8.string().min(1).parse(input);
     if (path !== ":memory:") mkdirSync(dirname2(path), { recursive: true, mode: 448 });
     this.database = new Database(path);
     try {
       this.database.pragma("journal_mode = WAL");
       this.database.pragma("foreign_keys = ON");
       this.database.pragma("busy_timeout = 5000");
-      this.database.transaction(() => {
+      this.cache = this.database.transaction(() => {
         const table = this.database.prepare(
           "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'schema_version'"
         ).get();
         if (!table) this.database.exec(__default);
-        const version3 = z7.object({ version: z7.literal(1) }).parse(
+        const version3 = z8.object({ version: z8.union([z8.literal(1), z8.literal(2)]) }).parse(
           this.database.prepare("SELECT MAX(version) AS version FROM schema_version").get()
         );
-        return version3.version;
+        if (version3.version === 1) this.database.exec(__default2);
+        const cache = new LedgerCache(this.database);
+        cache.synchronize();
+        return cache;
       }).immediate();
     } catch (error) {
       this.database.close();
@@ -833,22 +1143,49 @@ var Ledger = class {
   }
   append(input) {
     const event = paymentEventSchema.parse(input);
-    return this.database.prepare(
-      "INSERT OR IGNORE INTO events (id, ts, taskId, agentId, host, status, paymentKey, payload) VALUES (?, ?, ?, ?, ?, ?, ?, ?)"
-    ).run(
-      event.id,
-      event.ts,
-      event.taskId ?? null,
-      event.agentId ?? null,
-      event.host,
-      event.status,
-      event.paymentKey,
-      JSON.stringify(event)
-    ).changes > 0;
+    return this.transaction(() => {
+      const inserted = this.database.prepare(
+        "INSERT OR IGNORE INTO events (id, ts, taskId, agentId, host, status, paymentKey, payload) VALUES (?, ?, ?, ?, ?, ?, ?, ?)"
+      ).run(
+        event.id,
+        event.ts,
+        event.taskId ?? null,
+        event.agentId ?? null,
+        event.host,
+        event.status,
+        event.paymentKey,
+        JSON.stringify(event)
+      ).changes > 0;
+      this.cache.synchronize();
+      return inserted;
+    });
   }
   appendOutcome(input) {
     const outcome = outcomeSchema.parse(input);
-    return this.database.prepare("INSERT OR IGNORE INTO outcomes (id, ts, paymentId, payload) VALUES (?, ?, ?, ?)").run(outcome.id, outcome.ts, outcome.paymentId, JSON.stringify(outcome)).changes > 0;
+    return this.transaction(() => {
+      const inserted = this.database.prepare(
+        "INSERT OR IGNORE INTO outcomes (id, ts, paymentId, payload) VALUES (?, ?, ?, ?)"
+      ).run(outcome.id, outcome.ts, outcome.paymentId, JSON.stringify(outcome)).changes > 0;
+      this.cache.synchronize();
+      return inserted;
+    });
+  }
+  policyState(proposed, budgets, now) {
+    return this.transaction(() => {
+      this.cache.synchronize();
+      return {
+        reserved: this.cache.reservation(proposed.paymentKey),
+        spent: {
+          perTask: budgets.perTask ? this.cache.spent(proposed, "perTask", budgets.perTask.window, now) : "0",
+          perAgent: budgets.perAgent ? this.cache.spent(proposed, "perAgent", budgets.perAgent.window, now) : "0",
+          global: budgets.global ? this.cache.spent(proposed, "global", budgets.global.window, now) : "0"
+        }
+      };
+    });
+  }
+  /** Rebuild disposable projections without modifying the append-only audit log. */
+  rebuildCache() {
+    this.transaction(() => this.cache.rebuild());
   }
   events() {
     return this.database.prepare("SELECT payload FROM events ORDER BY ts, id").all().map((row) => paymentEventSchema.parse(JSON.parse(rowSchema.parse(row).payload)));
@@ -885,10 +1222,10 @@ import {
 } from "http";
 import { request as httpsRequest } from "https";
 import { connect, Socket } from "net";
-import { z as z8 } from "zod";
-var incomingHeadersSchema = z8.record(
-  z8.string(),
-  z8.union([z8.string(), z8.array(z8.string()), z8.undefined()])
+import { z as z9 } from "zod";
+var incomingHeadersSchema = z9.record(
+  z9.string(),
+  z9.union([z9.string(), z9.array(z9.string()), z9.undefined()])
 );
 var sockets = /* @__PURE__ */ new WeakMap();
 function normalizedHeaders(input) {
@@ -922,7 +1259,7 @@ function forwardingHeaders(message, host, upgrade = false) {
   return result;
 }
 function targetFor(request, config) {
-  const reference = z8.string().min(1).parse(request.url);
+  const reference = z9.string().min(1).parse(request.url);
   const absolute = /^https?:\/\//i.test(reference);
   const url = new URL(
     httpUrlSchema.parse(
@@ -931,13 +1268,13 @@ function targetFor(request, config) {
   );
   const suffix = absolute ? reference.replace(/^https?:\/\/[^/?#]*/i, "") : reference.startsWith("/") ? reference : `${url.pathname}${url.search}`;
   const withoutFragment = suffix.split("#", 1)[0] ?? "";
-  const path = z8.string().min(1).parse(withoutFragment.startsWith("/") ? withoutFragment : `/${withoutFragment}`);
+  const path = z9.string().min(1).parse(withoutFragment.startsWith("/") ? withoutFragment : `/${withoutFragment}`);
   return { url, path, resource: httpUrlSchema.parse(`${url.origin}${path}`) };
 }
 function wire(request, target) {
   return {
     url: target.resource,
-    method: z8.string().parse(request.method),
+    method: z9.string().parse(request.method),
     headers: normalizedHeaders(request.headers)
   };
 }
@@ -986,7 +1323,7 @@ function createProxy(options) {
         if (status === 402 && !needsBody) meter.observe(input, upstream);
         if (needsBody)
           reply.on("data", (chunk) => {
-            const bytes = z8.instanceof(Buffer).parse(chunk);
+            const bytes = z9.instanceof(Buffer).parse(chunk);
             length += bytes.length;
             if (length <= 65536) chunks.push(bytes);
             else chunks.length = 0;
@@ -1027,9 +1364,9 @@ function createProxy(options) {
   });
   server.on("connect", (request, client, head) => {
     try {
-      const address = z8.string().regex(/^(?:\[[0-9a-fA-F:]+\]|[^\s/:?#@]+):[0-9]+$/).parse(request.url);
+      const address = z9.string().regex(/^(?:\[[0-9a-fA-F:]+\]|[^\s/:?#@]+):[0-9]+$/).parse(request.url);
       const target = new URL(`http://${address}`);
-      const port = z8.coerce.number().int().min(1).max(65535).parse(target.port || "80");
+      const port = z9.coerce.number().int().min(1).max(65535).parse(target.port || "80");
       const host = target.hostname.replace(/^\[|\]$/g, "");
       meter.diagnose(
         "tls_unmetered",
@@ -1137,13 +1474,13 @@ async function closeProxy(server) {
 }
 
 // src/version.ts
-import { z as z9 } from "zod";
+import { z as z10 } from "zod";
 
 // package.json
-var version = "0.1.2";
+var version = "0.2.0";
 
 // src/version.ts
-var version2 = z9.string().regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/).parse(version);
+var version2 = z10.string().regex(/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/).parse(version);
 
 export {
   integerStringSchema,