zklicensing 0.1.0-beta.2 → 0.1.0-beta.21

package/src/licenseStore.ts

@@ -0,0 +1,767 @@
+// Copyright (c) 2025-2026 zkLicensing project developers
+// SPDX-License-Identifier: BUSL-1.1
+
+/**
+ * licenseStore.ts
+ *
+ * Off-chain MerkleMap state for the licensing system.
+ *
+ * Records are keyed by (zkAppAddress, licenseHash). Each LicensingApp deploys
+ * its own on-chain MerkleMap, so a passphrase used on two different apps
+ * produces the same `licenseHash` but two distinct records. Lookups that omit
+ * `zkAppAddress` would collide across apps — every API here takes it.
+ *
+ * Used by:
+ *   - interact.ts / buyLicense.ts (CLI) — reads/writes directly
+ *   - keeperService.ts              — exposes the same logic over HTTP
+ */
+
+import { Bool, Field, MerkleMap, MerkleMapWitness, Poseidon, PublicKey, UInt32, UInt64 } from 'o1js';
+import { GRACE_PERIOD_N, REFUND_WINDOW_N, effectiveExpirySlot } from './contractInterface.js';
+import { computeDeviceSlotsRoot, DEVICE_SLOT_CAP_N, leafFromRecord, leafHash } from './licenseLeaf.js';
+import { PENDING_REAP_SLOTS as _PENDING_REAP_SLOTS, type LicenseRecord as _LicenseRecord, type LicenseStatus as _LicenseStatus } from './licenseRecord.js';
+import { readJsonOr, writeJsonAtomic } from './atomicJson.js';
+
+// The record shape and pure types now live in licenseRecord.ts so browser
+// modules (buyClient, statsClient, countryStats) can consume them without
+// importing Node's `fs`. Re-exported here so existing Node imports of
+// `zklicensing/internal/licenseStore` continue to resolve.
+export type LicenseRecord = _LicenseRecord;
+export type LicenseStatus = _LicenseStatus;
+export type { AgentWaiverRecord } from './licenseRecord.js';
+export const PENDING_REAP_SLOTS = _PENDING_REAP_SLOTS;
+
+export function licenseStorePath(): string {
+  return process.env.LICENSE_STORE_PATH ?? 'licenses.json';
+}
+
+/**
+ * Where records live. Default: the JSON file at licenseStorePath() (the
+ * verify service and SDK users). The keeper installs its SQLite store with
+ * setLicenseStoreBackend, including a lock that works across processes.
+ */
+export type LicenseStoreBackend = {
+  read(): Promise<unknown>;
+  write(records: LicenseRecord[]): Promise<void>;
+  /** Wraps each read-modify-write; default none (in-process lock only). */
+  withLock?<T>(fn: () => Promise<T>): Promise<T>;
+};
+
+const fileBackend: LicenseStoreBackend = {
+  // Missing file → empty store; a damaged file is an error (see atomicJson).
+  read: () => readJsonOr<unknown>(licenseStorePath(), []),
+  write: records => writeJsonAtomic(licenseStorePath(), records),
+};
+let backend: LicenseStoreBackend = fileBackend;
+
+export function setLicenseStoreBackend(b: LicenseStoreBackend | null): void {
+  backend = b ?? fileBackend;
+}
+
+export async function readRecords(): Promise<LicenseRecord[]> {
+  const raw: unknown = await backend.read();
+  if (!Array.isArray(raw)) return [];
+  const records = raw as LicenseRecord[];
+  // Records pre-dating composite keying lack `zkAppAddress` and cannot be
+  // safely matched against any specific zkApp. Drop them with a warning so
+  // bootstrap rebuilds them fresh from on-chain events.
+  const filtered = records.filter(r => typeof r.zkAppAddress === 'string' && r.zkAppAddress.length > 0);
+  if (filtered.length < records.length) {
+    console.warn(`[licenseStore] dropped ${records.length - filtered.length} record(s) missing zkAppAddress — re-bootstrap to recover`);
+  }
+  return filtered;
+}
+
+async function writeRecords(records: LicenseRecord[]): Promise<void> {
+  await backend.write(records);
+}
+
+// Serialize all read-modify-write operations against licenses.json. Each
+// mutating function does (readRecords → mutate → writeRecords); without a lock,
+// two concurrent calls can interleave such that the second one's read predates
+// the first one's write, and the second one's write then clobbers the first.
+// This was visible during archive sync (applyEventsToStore fires many writes
+// back-to-back) racing with /confirm/* writes from buyer flows.
+let writeChain: Promise<void> = Promise.resolve();
+function withWriteLock<T>(fn: () => Promise<T>): Promise<T> {
+  const locked = () => (backend.withLock ? backend.withLock(fn) : fn());
+  const result = writeChain.then(locked, locked);
+  writeChain = result.then(() => {}, () => {});
+  return result;
+}
+
+// Records belonging to a specific zkApp. Each zkApp owns an independent
+// on-chain MerkleMap, so all map operations must filter first.
+function recordsForApp(records: LicenseRecord[], zkAppAddress: string): LicenseRecord[] {
+  return records.filter(r => r.zkAppAddress === zkAppAddress);
+}
+
+// Rebuild the license MerkleMap for a single zkApp. Only inserts entries
+// with expirySlot > 0. The value stored at each key is `leaf.hash()` — the
+// Poseidon commitment over (licenseHash, expirySlot, cap, deviceSlotsRoot,
+// deviceSlotsFilled) — matching what LicensingApp writes. Records that
+// predate device binding rebuild to a leaf with empty slots (see
+// leafFromRecord for the exact defaults); on those records the rebuilt
+// root matches what the old contract wrote, but any mutation call will
+// fail the in-circuit hash check until the missing fields are backfilled
+// from chain events.
+export function buildMap(records: LicenseRecord[], zkAppAddress: string): MerkleMap {
+  const map = new MerkleMap();
+  for (const r of recordsForApp(records, zkAppAddress)) {
+    if (r.expirySlot !== 0) {
+      map.set(Field(r.licenseHash), leafHash(leafFromRecord(r)));
+    }
+  }
+  return map;
+}
+
+// The license expiry the escrow commitment was made against — the expiry at
+// purchase time, before any renewal. `initialExpirySlot` is written at every
+// issue path (prove/buy staging, the licenseIssued event apply); the
+// `expirySlot` fallback only covers legacy records, which cannot have been
+// renewed without also receiving the backfill.
+export function escrowExpirySlot(r: LicenseRecord): number {
+  return r.initialExpirySlot ?? r.expirySlot;
+}
+
+// Rebuild the escrow MerkleMap for a single zkApp:
+// licenseHash → escrowCommitment(amount, slot, buyerKey, initialExpirySlot).
+// Only includes entries with live escrow (not released, not refunded, not an
+// escrowless purchase) and a known buyer. Must match LicensingApp.ts
+// escrowCommitment field-for-field.
+export function buildEscrowMap(records: LicenseRecord[], zkAppAddress: string): MerkleMap {
+  const map = new MerkleMap();
+  for (const r of recordsForApp(records, zkAppAddress)) {
+    if (!r.released && !r.refunded && !r.escrowless && r.purchaseSlot > 0 && r.buyerAddress) {
+      const buyerKey = PublicKey.fromBase58(r.buyerAddress);
+      const commitment = Poseidon.hash([
+        UInt64.from(BigInt(r.purchaseAmount)).value,
+        UInt32.from(r.purchaseSlot).value,
+        buyerKey.x,
+        buyerKey.isOdd.toField(),
+        UInt32.from(escrowExpirySlot(r)).value,
+      ]);
+      map.set(Field(r.licenseHash), commitment);
+    }
+  }
+  return map;
+}
+
+// Serialize a MerkleMapWitness to plain JSON (safe to send over HTTP).
+export function serializeWitness(witness: MerkleMapWitness): {
+  isLefts: boolean[];
+  siblings: string[];
+} {
+  return {
+    isLefts: witness.isLefts.map((b) => b.toBoolean()),
+    siblings: witness.siblings.map((f) => f.toString()),
+  };
+}
+
+// Reconstruct a MerkleMapWitness from serialized JSON.
+export function deserializeWitness(json: {
+  isLefts: boolean[];
+  siblings: string[];
+}): MerkleMapWitness {
+  return new MerkleMapWitness(
+    json.isLefts.map((b: boolean) => Bool(b)),
+    json.siblings.map((s: string) => Field(s))
+  );
+}
+
+// Returns the witness for a licenseHash key in the given zkApp's map.
+export async function getWitness(zkAppAddress: string, licenseHash: string): Promise<{
+  root: string;
+  currentValue: string;
+  witness: MerkleMapWitness;
+  serialized: ReturnType<typeof serializeWitness>;
+}> {
+  const records = await readRecords();
+  const map = buildMap(records, zkAppAddress);
+  const key = Field(licenseHash);
+  const witness = map.getWitness(key);
+  return {
+    root: map.getRoot().toString(),
+    currentValue: map.get(key).toString(),
+    witness,
+    serialized: serializeWitness(witness),
+  };
+}
+
+// Look up a single license record by its composite key.
+export async function getLicense(zkAppAddress: string, licenseHash: string): Promise<LicenseRecord | null> {
+  const records = await readRecords();
+  return records.find(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHash) ?? null;
+}
+
+// Determine the status of a license. A license in the 7-day grace window is
+// still considered 'active' so renewal is not urgently forced.
+export function licenseStatus(record: LicenseRecord | null, currentSlot: number, forkActivationSlot = 0): LicenseStatus {
+  if (!record) return 'unknown';
+  if (record.transferredTo) return 'transferred';
+  if (record.expirySlot === 0) return 'refunded';
+  if (effectiveExpirySlot(record.expirySlot, forkActivationSlot) + GRACE_PERIOD_N < currentSlot) return 'expired';
+  return 'active';
+}
+
+/**
+ * A redeployed app's successor starts with every license of `from` (its
+ * frozen tree, checked on chain): copy them to `to`, marked carriedOverFrom
+ * (not new sales). Refunded and already-present licenses are skipped.
+ * Returns how many were copied.
+ */
+export async function carryOverRecords(from: string, to: string): Promise<number> {
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const present = new Set(records.filter(r => r.zkAppAddress === to).map(r => r.licenseHash));
+    const copies = records
+      .filter(r => r.zkAppAddress === from && r.expirySlot > 0 && !present.has(r.licenseHash))
+      .map((r): LicenseRecord => ({
+        // License state only: the sale, its renewals and its escrow stay on
+        // the earlier deployment's record, so they're counted once.
+        zkAppAddress: to, carriedOverFrom: from,
+        licenseHash: r.licenseHash, expirySlot: r.expirySlot,
+        purchaseSlot: 0, purchaseAmount: '0', txHash: r.txHash, createdAt: r.createdAt,
+        buyerAddress: r.buyerAddress, deviceCap: r.deviceCap, deviceSlotsRoot: r.deviceSlotsRoot,
+        deviceSlotsFilled: r.deviceSlotsFilled, devices: r.devices,
+        initialExpirySlot: r.initialExpirySlot, tier: r.tier,
+        renewedAtLeastOnce: r.renewedAtLeastOnce || (r.renewals?.length ?? 0) > 0 || undefined,
+      }));
+    if (copies.length) await writeRecords([...records, ...copies]);
+    return copies.length;
+  });
+}
+
+/**
+ * A forced retirement left `zkAppAddress`'s escrowed purchases on the
+ * retired contract: marks them stranded (no refund or release follows).
+ * Returns how many.
+ */
+export async function markEscrowStranded(zkAppAddress: string, txHash: string, at = new Date().toISOString()): Promise<number> {
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    let n = 0;
+    for (const r of records) {
+      if (r.zkAppAddress !== zkAppAddress || r.released || r.refunded || r.escrowless || r.escrowStranded || !(r.purchaseSlot > 0)) continue;
+      r.escrowStranded = { txHash, at };
+      n++;
+    }
+    if (n) await writeRecords(records);
+    return n;
+  });
+}
+
+// Add or update a license record (upsert by composite key).
+export async function upsertLicense(record: LicenseRecord): Promise<void> {
+  if (!record.zkAppAddress) {
+    throw new Error('upsertLicense: record.zkAppAddress is required');
+  }
+  // Populate the empty-slot mirror at insert time when the license is capped.
+  // Without this, /confirm/buy writes deviceCap:N but leaves deviceSlotsRoot
+  // and deviceSlotsFilled undefined until the first bind — leafFromRecord's
+  // fallbacks paper over it for hash reconstruction, but every consumer that
+  // reads the mirror directly (preflight logs, /license responses, offline
+  // verify) would see undefined and either misreport or need its own fallback.
+  if ((record.deviceCap ?? 0) > 0 && (record.deviceSlotsRoot === undefined || record.deviceSlotsFilled === undefined)) {
+    refreshSlotMirror(record);
+  }
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const idx = records.findIndex(r => r.zkAppAddress === record.zkAppAddress && r.licenseHash === record.licenseHash);
+    if (idx >= 0) {
+      records[idx] = record;
+    } else {
+      records.push(record);
+    }
+    await writeRecords(records);
+  });
+}
+
+// Update the expirySlot for an existing record (used by renew).
+// `opts.markRenewed` flips renewedAtLeastOnce so stats can detect first-renewal
+// without re-walking events. `opts.renewal` appends to the renewals[] log so
+// stats can compute renewal revenue from the store alone.
+export async function updateExpiry(
+  zkAppAddress: string,
+  licenseHash: string,
+  expirySlot: number,
+  opts: { markRenewed?: boolean; renewal?: { slot: number; amount: string; newExpiry: number; txHash?: string } } = {},
+): Promise<boolean> {
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const record = records.find(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHash);
+    if (!record) return false;
+    record.expirySlot = expirySlot;
+    if (opts.markRenewed) record.renewedAtLeastOnce = true;
+    if (opts.renewal) {
+      const renewals = (record.renewals ??= []);
+      // Dedup by newExpiry — confirm-time and event-sync may both try to log
+      // the same renewal, but each renewal advances expiry by a unique tier
+      // amount, so newExpiry is a stable identifier.
+      if (!renewals.some(r => r.newExpiry === opts.renewal!.newExpiry)) {
+        renewals.push(opts.renewal);
+      }
+    }
+    await writeRecords(records);
+    return true;
+  });
+}
+
+// Clear license and escrow data after a refund. Also flips `refunded`.
+//
+// Two modes:
+//   provisional=false (default, called from archive event-sync on a canonical
+//     refundIssued event): sets refunded=true, zeros expiry/purchase, clears
+//     pending. This is the authoritative confirm — includes upgrading a prior
+//     'fast' flip.
+//   provisional=true (called from the tx-land watcher on first bestchain
+//     observation): sets refunded='fast' and records provisionalFlipAtSlot,
+//     but does NOT zero expirySlot/purchaseSlot yet — those stay live until
+//     the event is canonical, so a reorg revert restores refunded=false
+//     without needing snapshots.
+export async function recordRefund(
+  zkAppAddress: string,
+  licenseHash: string,
+  opts?: { provisional?: boolean; nowSlot?: number },
+): Promise<boolean> {
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const record = records.find(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHash);
+    if (!record) return false;
+    if (opts?.provisional) {
+      // Preserve expirySlot/purchaseSlot for revertability. UI treats
+      // 'fast' as refunded (truthy); circuit ops see 409 via pre-flight
+      // guards if the local state diverges from chain during the window.
+      if (record.refunded !== true) record.refunded = 'fast';
+      if (opts.nowSlot !== undefined) record.provisionalFlipAtSlot = opts.nowSlot;
+    } else {
+      record.expirySlot = 0;
+      record.purchaseSlot = 0;
+      record.purchaseAmount = '0';
+      record.refunded = true;
+      // /confirm/refund wrote pending:true optimistically; the on-chain event
+      // landing is what authorizes clearing it. Without this the SDK poller
+      // (which requires pending===false && status==='refunded') hangs forever.
+      delete record.pending;
+      delete record.pendingPrior;
+      delete record.provedAtSlot;
+      // Any prior 'fast' provisional flip is now confirmed — drop the marker.
+      delete record.provisionalFlipAtSlot;
+    }
+    await writeRecords(records);
+    return true;
+  });
+}
+
+// Mark escrow as released. Preserves purchaseAmount/purchaseSlot so stats can
+// compute released revenue. The `released` flag is the truth signal —
+// buildEscrowMap and getReleasableRecords filter on it directly.
+//
+// Two modes: same semantics as recordRefund above.
+//   provisional=true  → released='fast', provisionalFlipAtSlot=nowSlot
+//   provisional=false → released=true (upgrades any 'fast' state), clears
+//                       provisionalFlipAtSlot
+export async function recordRelease(
+  zkAppAddress: string,
+  licenseHash: string,
+  releaseSlot?: number,
+  txHash?: string,
+  opts?: { provisional?: boolean; nowSlot?: number },
+): Promise<boolean> {
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const record = records.find(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHash);
+    if (!record) return false;
+    if (opts?.provisional) {
+      if (record.released !== true) record.released = 'fast';
+      if (opts.nowSlot !== undefined) record.provisionalFlipAtSlot = opts.nowSlot;
+    } else {
+      record.released = true;
+      delete record.provisionalFlipAtSlot;
+    }
+    if (releaseSlot !== undefined) record.releaseSlot = releaseSlot;
+    if (txHash !== undefined) record.releaseTxHash = txHash;
+    await writeRecords(records);
+    return true;
+  });
+}
+
+// Roll back a provisional 'fast' flip that never got confirmed by the archive.
+// Called by the reorg-revert reaper after REORG_REVERT_AFTER_SLOTS elapses
+// without a canonical event. Only reverts if the field is still 'fast' —
+// confirmed (true) flips are irreversible from this path.
+export async function revertProvisionalFlip(
+  zkAppAddress: string,
+  licenseHash: string,
+  kind: 'release' | 'refund',
+): Promise<boolean> {
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const record = records.find(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHash);
+    if (!record) return false;
+    if (kind === 'release') {
+      if (record.released !== 'fast') return false;
+      record.released = false;
+      delete record.releaseSlot;
+      delete record.releaseTxHash;
+    } else {
+      if (record.refunded !== 'fast') return false;
+      record.refunded = false;
+      // expirySlot/purchaseSlot were never zeroed for provisional refunds, so
+      // nothing to restore there.
+    }
+    // Clear the marker only if no OTHER field is still provisional.
+    if (record.released !== 'fast' && record.refunded !== 'fast') {
+      delete record.provisionalFlipAtSlot;
+    }
+    await writeRecords(records);
+    return true;
+  });
+}
+
+// Clear the pending flag on a record after a chain event confirms it landed.
+export async function confirmRecord(zkAppAddress: string, licenseHash: string): Promise<boolean> {
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const record = records.find(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHash);
+    if (!record) return false;
+    if (!record.pending) return false;
+    delete record.pending;
+    delete record.pendingPrior;
+    delete record.provedAtSlot;
+    await writeRecords(records);
+    return true;
+  });
+}
+
+// Apply a licenseIssued event atomically: confirm any pending /confirm/buy
+// write, backfill initialExpirySlot/tier if missing, or create a fresh record.
+// Doing the whole read-decide-write inside a single lock acquisition avoids the
+// stale-snapshot hazard that would arise if archiveBootstrap called
+// getLicense + confirmRecord + upsertLicense as three separate locked steps —
+// a concurrent write between them could be clobbered by the upsert's
+// pre-confirm snapshot.
+export async function applyLicenseIssued(
+  zkAppAddress: string,
+  licenseHash: string,
+  fields: {
+    expirySlot: number;
+    purchaseSlot: number;
+    purchaseAmount: string;
+    tier?: 'monthly' | 'yearly' | 'fiveYear' | 'perpetual';
+    // True for licenses minted through buyLicenseNoEscrow: funds went straight
+    // to vendor + platform, no escrow entry. Refund CTA must be suppressed.
+    escrowless?: boolean;
+    // Leaf fields carried by LicenseIssuedEvent so a record rehydrated purely
+    // from archive replay (no prior /confirm/buy) reconstructs the exact leaf
+    // hash the circuit committed. Optional so pre-event-extension replays
+    // (which never carried them) still bootstrap — those records will fail
+    // in-circuit hash checks on the next mutation, matching prior behavior.
+    // No ownerPubKeyHash field: the leaf's owner-pubkey commitment IS
+    // `licenseHash` itself (buyLicense asserts them equal), already the key
+    // this function is called with.
+    deviceCap?:         number;
+    deviceSlotsRoot?:   string;
+    deviceSlotsFilled?: number;
+    // Buyer's public key, carried by LicenseIssuedEvent. Required for
+    // buildEscrowMap (funds-release witness reconstruction) AND for
+    // GET /licenses?buyer=<addr> enumeration (the primary UI source for the
+    // "My Licenses" view). Migration-replay callers must look up the
+    // predecessor record's buyerAddress before calling this.
+    buyerAddress:       string;
+  },
+): Promise<void> {
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const record = records.find(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHash);
+    let dirty = false;
+    if (record) {
+      if (record.pending) {
+        delete record.pending;
+        delete record.pendingPrior;
+        delete record.provedAtSlot;
+        dirty = true;
+      }
+      if (record.initialExpirySlot === undefined) {
+        record.initialExpirySlot = fields.expirySlot;
+        dirty = true;
+      }
+      if (!record.tier && fields.tier) {
+        record.tier = fields.tier;
+        dirty = true;
+      }
+      if (fields.escrowless === true && record.escrowless !== true) {
+        record.escrowless = true;
+        dirty = true;
+      }
+      // Backfill leaf fields if the record was created before the event
+      // carried them, or if a prior partial rehydrate is still missing them.
+      if (fields.deviceCap !== undefined && record.deviceCap === undefined) {
+        record.deviceCap = fields.deviceCap;
+        dirty = true;
+      }
+      if (fields.deviceSlotsRoot !== undefined && record.deviceSlotsRoot === undefined) {
+        record.deviceSlotsRoot = fields.deviceSlotsRoot;
+        dirty = true;
+      }
+      if (fields.deviceSlotsFilled !== undefined && record.deviceSlotsFilled === undefined) {
+        record.deviceSlotsFilled = fields.deviceSlotsFilled;
+        dirty = true;
+      }
+      if (record.buyerAddress === undefined) {
+        // Legacy record predating the required-buyerAddress change — backfill
+        // from the fresh event so it becomes enumerable via /licenses?buyer=.
+        record.buyerAddress = fields.buyerAddress;
+        dirty = true;
+      }
+    } else {
+      const inserted: LicenseRecord = {
+        zkAppAddress,
+        licenseHash,
+        expirySlot:        fields.expirySlot,
+        purchaseSlot:      fields.purchaseSlot,
+        purchaseAmount:    fields.purchaseAmount,
+        txHash:            '',
+        createdAt:         new Date().toISOString(),
+        initialExpirySlot: fields.expirySlot,
+        ...(fields.tier ? { tier: fields.tier } : {}),
+        ...(fields.escrowless === true ? { escrowless: true } : {}),
+        ...(fields.deviceCap         !== undefined ? { deviceCap:         fields.deviceCap } : {}),
+        ...(fields.deviceSlotsRoot   !== undefined ? { deviceSlotsRoot:   fields.deviceSlotsRoot } : {}),
+        ...(fields.deviceSlotsFilled !== undefined ? { deviceSlotsFilled: fields.deviceSlotsFilled } : {}),
+        buyerAddress:      fields.buyerAddress,
+      };
+      // Same rationale as upsertLicense: populate the empty-slot mirror on
+      // first insert so the record is immediately queryable without relying
+      // on leafFromRecord's undefined fallbacks.
+      if ((inserted.deviceCap ?? 0) > 0 && (inserted.deviceSlotsRoot === undefined || inserted.deviceSlotsFilled === undefined)) {
+        refreshSlotMirror(inserted);
+      }
+      records.push(inserted);
+      dirty = true;
+    }
+    if (dirty) await writeRecords(records);
+  });
+}
+
+// Apply a licenseRenewed event atomically: clear any pending /confirm/renew
+// write, align expirySlot with the event, and flip renewedAtLeastOnce.
+// Symmetric to applyLicenseIssued — the archive-events path is what closes
+// out a renew that the bestChain sweep missed (tx landed after the sweep's
+// BESTCHAIN_DEPTH window rolled past), and without a pending-clear step here
+// the flag on a landed record could be stuck forever.
+//
+// Does NOT append to renewals[] — that log is populated at /confirm/renew
+// time from the intent (which carries amount + txHash); the archive event
+// carries only newExpiry, so replaying it must not overwrite the richer
+// confirm-time entry.
+export async function applyLicenseRenewed(
+  zkAppAddress: string,
+  licenseHash: string,
+  fields: { newExpiry: number },
+): Promise<boolean> {
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const record = records.find(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHash);
+    if (!record) return false;
+    let dirty = false;
+    if (record.pending) {
+      delete record.pending;
+      delete record.pendingPrior;
+      delete record.provedAtSlot;
+      dirty = true;
+    }
+    if (record.expirySlot !== fields.newExpiry) {
+      record.expirySlot = fields.newExpiry;
+      dirty = true;
+    }
+    if (!record.renewedAtLeastOnce) {
+      record.renewedAtLeastOnce = true;
+      dirty = true;
+    }
+    if (dirty) await writeRecords(records);
+    return true;
+  });
+}
+
+/**
+ * A license moved to a new owner key (transferLicense): the license state
+ * (expiry, cap, bound devices) goes to a record under `to`, with no sale of
+ * its own (the sale and its receipt stay on the original record), listed
+ * under `wallet` (the transfer's sender, the new owner's wallet, which
+ * paid), and the original leaves the licenses tree (expirySlot 0) marked
+ * `transferredTo`.
+ */
+export async function applyLicenseTransferred(
+  zkAppAddress: string,
+  from: string,
+  to: string,
+  opts: { wallet?: string; txHash?: string } = {},
+): Promise<boolean> {
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const old = records.find(r => r.zkAppAddress === zkAppAddress && r.licenseHash === from);
+    if (!old) return false;
+    if (old.transferredTo === to) return true; // already applied
+    const moved: LicenseRecord = {
+      zkAppAddress, licenseHash: to, expirySlot: old.expirySlot, purchaseSlot: 0, purchaseAmount: '0',
+      txHash: opts.txHash ?? '', createdAt: new Date().toISOString(), buyerAddress: opts.wallet ?? '',
+      transferredFrom: from,
+      ...(old.deviceCap !== undefined ? { deviceCap: old.deviceCap } : {}),
+      ...(old.deviceSlotsRoot !== undefined ? { deviceSlotsRoot: old.deviceSlotsRoot } : {}),
+      ...(old.deviceSlotsFilled !== undefined ? { deviceSlotsFilled: old.deviceSlotsFilled } : {}),
+      ...(old.devices ? { devices: old.devices.map(d => ({ ...d })) } : {}),
+      ...(old.escrowless ? { escrowless: true } : {}),
+      ...(old.tier ? { tier: old.tier } : {}),
+    };
+    const existing = records.findIndex(r => r.zkAppAddress === zkAppAddress && r.licenseHash === to);
+    if (existing >= 0) records[existing] = moved; else records.push(moved);
+    old.transferredTo = to;
+    old.expirySlot = 0;
+    delete old.devices;
+    delete old.pending;
+    delete old.pendingPrior;
+    delete old.provedAtSlot;
+    await writeRecords(records);
+    return true;
+  });
+}
+
+// Recompute deviceSlotsRoot + deviceSlotsFilled from the record's mirror after
+// a bind/unbind mutation. `leafFromRecord` uses those two persisted fields when
+// building the on-chain leaf hash; if they drift from the on-chain state the
+// next mutation call fails the in-circuit leaf-hash assert. Mirror the exact
+// packing the circuit uses (packSlotTimes: freedAt in low 32 bits, boundAt in
+// high 32) so the fold matches the on-chain deviceSlotsRoot bit-for-bit.
+function refreshSlotMirror(record: LicenseRecord): void {
+  const devices = record.devices ?? [];
+  const occupied: Field[] = [];
+  const freedAt:  Field[] = [];
+  for (let i = 0; i < DEVICE_SLOT_CAP_N; i++) {
+    const entry = devices.find(d => d.slotIndex === i);
+    const occ = entry?.deviceCommitment ?? '0';
+    occupied.push(Field(occ));
+    const boundAt = BigInt(entry?.boundAtSlot ?? 0);
+    const freed   = BigInt(entry?.freedAtSlot ?? 0);
+    // packSlotTimes(boundAt, freedAt) in licenseLeaf.ts: freedAt low 32, boundAt high 32.
+    const packed  = freed + (boundAt << 32n);
+    freedAt.push(Field(packed));
+  }
+  record.deviceSlotsRoot   = computeDeviceSlotsRoot(occupied, freedAt).toString();
+  record.deviceSlotsFilled = devices.filter(d => d.deviceCommitment !== '0').length;
+}
+
+// Apply a deviceBound event atomically: mirrors the on-chain slot mutation
+// into the record.devices[] array and recomputes deviceSlotsRoot / filled so
+// leafFromRecord reconstructs the exact leaf hash the chain committed.
+//
+// `boundAtSlot` MUST be the circuit's proof-time `globalSlotSinceGenesis` (the
+// value emitted in `DeviceBoundEvent.boundAtSlot`). The block slot when the tx
+// landed is NOT interchangeable: TOLERANCE_WINDOW allows them to differ, and
+// any drift flips the packed `freedAt` field → wrong leaf → root divergence.
+export async function applyDeviceBound(
+  zkAppAddress: string,
+  licenseHash:  string,
+  fields: { slotIndex: number; deviceCommitment: string; boundAtSlot: number },
+): Promise<boolean> {
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const record = records.find(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHash);
+    if (!record) return false;
+    const devices = (record.devices ??= []);
+    // Ensure the array is long enough — pad with empty slots.
+    while (devices.length <= fields.slotIndex) {
+      devices.push({ slotIndex: devices.length, deviceCommitment: '0', boundAtSlot: 0, freedAtSlot: 0 });
+    }
+    devices[fields.slotIndex] = {
+      slotIndex:        fields.slotIndex,
+      deviceCommitment: fields.deviceCommitment,
+      boundAtSlot:      fields.boundAtSlot,
+      freedAtSlot:      0,  // pristine → fresh bind resets freedAt
+    };
+    refreshSlotMirror(record);
+    await writeRecords(records);
+    return true;
+  });
+}
+
+// Apply a deviceUnbound event atomically. Preserves boundAtSlot for audit,
+// stamps freedAtSlot for the cooldown timer the circuit's next bind enforces.
+//
+// `freedAtSlot` MUST be the circuit's proof-time `globalSlotSinceGenesis` (the
+// value emitted in `DeviceUnboundEvent.freedAtSlot`). Same reason as
+// `applyDeviceBound.boundAtSlot`.
+export async function applyDeviceUnbound(
+  zkAppAddress: string,
+  licenseHash:  string,
+  fields: { slotIndex: number; freedAtSlot: number },
+): Promise<boolean> {
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const record = records.find(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHash);
+    if (!record || !record.devices) return false;
+    const slot = record.devices.find(d => d.slotIndex === fields.slotIndex);
+    if (!slot) return false;
+    slot.deviceCommitment = '0';
+    slot.freedAtSlot = fields.freedAtSlot;
+    // boundAtSlot stays as the last bind time — historical / audit.
+    refreshSlotMirror(record);
+    await writeRecords(records);
+    return true;
+  });
+}
+
+// Undo a pending change whose transaction failed on chain or never landed:
+// restore the record it replaced (a renewal or refund), or remove it (a
+// purchase). With `txHash`, only if the pending change is that transaction's.
+export async function revertPending(zkAppAddress: string, licenseHash: string, txHash?: string): Promise<'restored' | 'removed' | false> {
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const idx = records.findIndex(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHash);
+    if (idx < 0) return false;
+    const record = records[idx];
+    if (!record.pending || (txHash !== undefined && record.txHash !== txHash)) return false;
+    const outcome = record.pendingPrior ? 'restored' : 'removed';
+    if (record.pendingPrior) records[idx] = record.pendingPrior;
+    else records.splice(idx, 1);
+    await writeRecords(records);
+    return outcome;
+  });
+}
+
+// Delete a record entirely (used to reap stale pending entries the buyer never submitted).
+export async function deleteRecord(zkAppAddress: string, licenseHash: string): Promise<boolean> {
+  return withWriteLock(async () => {
+    const records = await readRecords();
+    const idx = records.findIndex(r => r.zkAppAddress === zkAppAddress && r.licenseHash === licenseHash);
+    if (idx < 0) return false;
+    records.splice(idx, 1);
+    await writeRecords(records);
+    return true;
+  });
+}
+
+// List pending records whose prove slot is older than `currentSlot - maxAgeSlots`.
+// Used by the reaper to drop records the buyer never actually signed/submitted.
+export async function getStalePendingRecords(currentSlot: number, maxAgeSlots = PENDING_REAP_SLOTS): Promise<LicenseRecord[]> {
+  const records = await readRecords();
+  return records.filter(
+    (r) => r.pending && typeof r.provedAtSlot === 'number' && currentSlot - r.provedAtSlot > maxAgeSlots,
+  );
+}
+
+// Return all records where the refund window has passed and escrow is still live.
+// Filters on the released/refunded flags so we don't re-release or release after refund.
+export async function getReleasableRecords(currentSlot: number): Promise<LicenseRecord[]> {
+  const records = await readRecords();
+  return records.filter(
+    (r) =>
+      !r.released &&
+      !r.refunded &&
+      !r.escrowless &&
+      !r.escrowStranded &&
+      r.purchaseSlot > 0 &&
+      r.zkAppAddress &&
+      currentSlot > r.purchaseSlot + REFUND_WINDOW_N,
+  );
+}