@blamejs/blamejs-shop 0.4.103 → 0.4.105

package/lib/loyalty.js

@@ -154,6 +154,51 @@ function _validateThresholds(thresholds) {
 
 function _now() { return Date.now(); }
 
+// ---- chain hashing ------------------------------------------------------
+//
+// loyalty_transactions is a per-customer running-balance hash chain (the
+// gift-card-ledger / store-credit-ledger model). Each mutating row carries the
+// running balance_after_points + lifetime_after_points + tier_after, written by
+// the SAME guarded INSERT that records the event, so the balance change and the
+// audit row are one write — the stored-column two-statement window (and the
+// double-credit-on-revert hazard it forced) is structurally gone. A SHA3-512
+// chain (prev_hash + row_hash, fenced by UNIQUE(customer_id, prev_hash)) makes
+// the running snapshot tamper-evident and serializes concurrent writers.
+//
+//   row_hash = SHA3-512(prev_hash || canonical-json(row-fields))
+//
+// order_id and restored_points are EXCLUDED from the hashed fields: both are
+// mutated AFTER the row is inserted (linkRedemptionToOrder stamps order_id;
+// reverse/restore advance restored_points), so hashing them would report a
+// false tamper on every linked redemption and every restore.
+var SHA3_512_HEX_LEN = 128;
+var ZERO_HASH = "0".repeat(SHA3_512_HEX_LEN);
+
+function _rowFieldsForHash(row) {
+  return {
+    id:                    row.id,
+    customer_id:           row.customer_id,
+    transaction_type:      row.transaction_type,
+    points:                Number(row.points),
+    source:                row.source == null ? null : row.source,
+    notes:                 row.notes == null ? null : row.notes,
+    balance_after_points:  Number(row.balance_after_points),
+    lifetime_after_points: Number(row.lifetime_after_points),
+    tier_after:            row.tier_after,
+    occurred_at:           Number(row.occurred_at),
+    // order_id + restored_points EXCLUDED — both mutated post-insert.
+  };
+}
+
+function _computeRowHash(prevHash, rowFields) {
+  var canonical = b.auditChain.canonicalize(rowFields, ["prev_hash", "row_hash"]);
+  var preimage  = Buffer.concat([
+    Buffer.from(prevHash, "hex"),
+    Buffer.from(canonical, "utf8"),
+  ]);
+  return b.crypto.sha3Hash(preimage);
+}
+
 // ---- factory ------------------------------------------------------------
 
 function create(opts) {
@@ -205,17 +250,6 @@ function create(opts) {
     return r.rows[0] || null;
   }
 
-  async function _writeTx(customerId, type, points, source, orderId, notes, ts) {
-    var id = b.uuid.v7();
-    await query(
-      "INSERT INTO loyalty_transactions " +
-      "(id, customer_id, transaction_type, points, source, order_id, notes, occurred_at) " +
-      "VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)",
-      [id, customerId, type, points, source, orderId, notes, ts],
-    );
-    return id;
-  }
-
   async function _ensureAccountRow(customerId, ts) {
     // INSERT OR IGNORE is idempotent — repeated calls land a single
     // row. We don't bump `updated_at` on the existing-row path; the
@@ -228,23 +262,133 @@ function create(opts) {
     );
   }
 
-  // SQL fragment that derives the tier from a lifetime-points
-  // expression evaluated INSIDE the UPDATE statement, so balance,
-  // lifetime, and tier all move in one atomic write off the row's
-  // live value rather than a stale snapshot. `lifetimeExpr` is the
-  // post-mutation lifetime SQL (e.g. `lifetime_points + ?2`). The
-  // operator-tunable thresholds bind as literals — they're validated
-  // non-negative integers at factory time, never operator input here,
-  // so inlining them keeps the CASE a single self-contained
-  // expression without widening the bound-parameter list per call.
-  // Mirrors computeTier's highest-threshold-first ladder so the SQL
-  // and JS classifications never diverge.
-  function _tierCase(lifetimeExpr) {
-    return "CASE" +
-      " WHEN (" + lifetimeExpr + ") >= " + thresholds.platinum + " THEN 'platinum'" +
-      " WHEN (" + lifetimeExpr + ") >= " + thresholds.gold     + " THEN 'gold'" +
-      " WHEN (" + lifetimeExpr + ") >= " + thresholds.silver   + " THEN 'silver'" +
-      " ELSE 'bronze' END";
+  // O(1) chain-tip read: the latest row by (customer_id, occurred_at DESC,
+  // id DESC) carries the running balance/lifetime/tier snapshot AFTER it.
+  // No SUM at read time. Falls through to a bronze zero-tip when the customer
+  // has no rows (a brand-new account anchors its chain from ZERO on the first
+  // write). A legacy/genesis NULL row_hash coerces to ZERO_HASH so the first
+  // hashed row anchors the chain (the lazy genesis anchor).
+  async function _readLatest(customerId) {
+    var r = await query(
+      "SELECT id, balance_after_points, lifetime_after_points, tier_after, occurred_at, row_hash " +
+      "FROM loyalty_transactions WHERE customer_id = ?1 " +
+      "ORDER BY occurred_at DESC, id DESC LIMIT 1",
+      [customerId],
+    );
+    if (!r.rows.length) {
+      return { id: null, balance: 0, lifetime: 0, tier: "bronze",
+               occurred_at: null, row_hash: ZERO_HASH };
+    }
+    var row = r.rows[0];
+    return {
+      id:          row.id,
+      balance:     Number(row.balance_after_points),
+      lifetime:    Number(row.lifetime_after_points),
+      tier:        row.tier_after,
+      occurred_at: Number(row.occurred_at),
+      row_hash:    row.row_hash == null ? ZERO_HASH : row.row_hash,
+    };
+  }
+
+  // Strict-monotonic per-customer occurred_at: two writes in the same ms (or a
+  // backdated write) would tie and make the tip ambiguous, so a colliding
+  // timestamp bumps to prior + 1. Non-colliding (future) timestamps land as
+  // requested.
+  function _resolveOccurredAt(requestedTs, latestTs) {
+    if (latestTs == null) return requestedTs;
+    if (requestedTs > latestTs) return requestedTs;
+    return latestTs + 1;
+  }
+
+  // Re-derive the tip this many times when the chain-parent fence refuses an
+  // INSERT (a concurrent write claimed the slot). Each fence round lets exactly
+  // one racing writer win, so the cap is sized well beyond realistic same-
+  // customer fan-in; a genuine non-collision insert error re-throws on attempt
+  // one (the tip is unchanged), so a high cap never spins on a real failure.
+  var CHAIN_WRITE_ATTEMPTS = 64;
+
+  // One fenced write attempt off a freshly-read tip. Every event kind writes
+  // through here so every row joins the per-customer chain. The chain-parent
+  // fence (UNIQUE(customer_id, prev_hash)) makes the app-computed prev_hash /
+  // row_hash safe: a row derived from a stale tip collides instead of forking
+  // the chain or persisting a stale balance_after. The overdraft / underflow
+  // gate stays INSIDE the statement (correlated subquery against the live tip,
+  // never an app-side check) so a refusal is a zero-row no-op. Returns one of
+  // { written }, { refused } (guard said no), { collided } (tip moved — retry).
+  async function _attemptChainedWrite(customerId, d) {
+    var id = b.uuid.v7();
+    var rowHash = _computeRowHash(d.prevHash, {
+      id:                    id,
+      customer_id:           customerId,
+      transaction_type:      d.type,
+      points:                d.points,
+      source:                d.source,
+      notes:                 d.notes,
+      balance_after_points:  d.balanceAfter,
+      lifetime_after_points: d.lifetimeAfter,
+      tier_after:            d.tierAfter,
+      occurred_at:           d.ts,
+    });
+    var balSub =
+      "COALESCE((SELECT balance_after_points FROM loyalty_transactions " +
+      "WHERE customer_id = ?2 ORDER BY occurred_at DESC, id DESC LIMIT 1), 0)";
+    try {
+      var res = await query(
+        "INSERT INTO loyalty_transactions " +
+        "(id, customer_id, transaction_type, points, source, order_id, notes, occurred_at, " +
+        "balance_after_points, lifetime_after_points, tier_after, prev_hash, row_hash) " +
+        "SELECT ?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13 " +
+        "WHERE " + (d.guard ? d.guard.replace(/__BAL__/g, balSub) : "1"),
+        [id, customerId, d.type, d.points, d.source, d.orderId, d.notes, d.ts,
+          d.balanceAfter, d.lifetimeAfter, d.tierAfter, d.prevHash, rowHash],
+      );
+      if (Number(res.rowCount || 0) === 0) return { refused: true };
+      return { written: { id: id, points: d.points, balance: d.balanceAfter,
+                          lifetime: d.lifetimeAfter, tier: d.tierAfter, occurred_at: d.ts } };
+    } catch (e) {
+      // State-agnostic collision detection — never error-message matching (the
+      // prod D1 bridge redacts the SQLite UNIQUE text to a generic HTTP 500).
+      // If the tip advanced past the parent we tried to chain off, a competing
+      // write claimed our slot — retry; otherwise the insert failed for another
+      // reason — re-throw.
+      var after = await _readLatest(customerId);
+      if (after.row_hash !== d.prevHash) return { collided: true };
+      throw e;
+    }
+  }
+
+  // Run a chained write with bounded tip-contention retries. `derive(tip)` maps
+  // the freshly-read tip to the concrete row fields; each fence collision
+  // re-reads + re-derives so the values that land are always consistent with
+  // the parent they chain off. Returns the written row, or { refused: true }
+  // when the in-statement guard rejected it against the live tip.
+  async function _writeChained(customerId, derive) {
+    for (var attempt = 0; attempt < CHAIN_WRITE_ATTEMPTS; attempt += 1) {
+      var latest = await _readLatest(customerId);
+      var d = derive(latest);
+      d.prevHash = latest.row_hash;
+      var r = await _attemptChainedWrite(customerId, d);
+      if (r.collided) continue;
+      if (r.refused) return { refused: true };
+      return r.written;
+    }
+    var contention = new Error("loyalty: persistent chain-tip contention — retry the write");
+    contention.code = "LOYALTY_CONTENTION";
+    throw contention;
+  }
+
+  // Best-effort refresh of the loyalty_accounts mirror from a freshly-written
+  // tip. The mirror is NOT authoritative and NOT on any mutation's decision
+  // path — balance() and every guard read the chain tip; the mirror exists only
+  // for the cross-customer tierLeaderboard and the operator tier_expires_at
+  // time-bound. Runs OUTSIDE the atomicity boundary: a crash here leaves money
+  // exactly-once correct and the next advancing write re-syncs it.
+  async function _refreshMirror(customerId, w, ts) {
+    await query(
+      "UPDATE loyalty_accounts SET balance_points = ?1, lifetime_points = ?2, " +
+      "tier = ?3, updated_at = ?4 WHERE customer_id = ?5",
+      [w.balance, w.lifetime, w.tier, ts, customerId],
+    );
   }
 
   return {
@@ -277,29 +421,31 @@ function create(opts) {
       var orderId    = input.order_id != null ? _uuid(input.order_id, "order_id") : null;
       var notes      = _notes(input.notes);
 
-      var ts = _now();
-      await _ensureAccountRow(customerId, ts);
-      // Snapshot the tier ONLY to report `tier_changed` — the balance /
-      // lifetime / tier mutation itself is relative-atomic below, so a
-      // concurrent earn can't clobber this credit (the lost-update the
-      // absolute write suffered). The tier is recomputed in-SQL off the
-      // row's live `lifetime_points`, not this stale snapshot.
-      var before = await _readAccount(customerId);
-      await query(
-        "UPDATE loyalty_accounts SET balance_points = balance_points + ?1, " +
-        "lifetime_points = lifetime_points + ?1, " +
-        "tier = " + _tierCase("lifetime_points + ?1") + ", " +
-        "updated_at = ?2 WHERE customer_id = ?3",
-        [points, ts, customerId],
-      );
-      await _writeTx(customerId, "earn", points, source, orderId, notes, ts);
-
-      var after = await _readAccount(customerId);
+      var requested = _now();
+      await _ensureAccountRow(customerId, requested);
+      // Balance + lifetime + tier all ride the SAME guarded chained INSERT off
+      // the freshly-read tip — there is no stored-column second statement to
+      // lose. earn advances lifetime and recomputes the tier off the new
+      // lifetime; `tier_changed` compares the chain's before/after tiers (both
+      // from the tip, no separate snapshot read).
+      var tierBefore;
+      var w = await _writeChained(customerId, function (latest) {
+        tierBefore = latest.tier;
+        var lifeAfter = latest.lifetime + points;
+        return {
+          type: "earn", points: points, source: source, orderId: orderId, notes: notes,
+          balanceAfter:  latest.balance + points,
+          lifetimeAfter: lifeAfter,
+          tierAfter:     computeTier(lifeAfter),
+          ts:            _resolveOccurredAt(requested, latest.occurred_at),
+        };
+      });
+      await _refreshMirror(customerId, w, requested);
       return {
-        balance:      after.balance_points,
-        lifetime:     after.lifetime_points,
-        tier:         after.tier,
-        tier_changed: after.tier !== before.tier,
+        balance:      w.balance,
+        lifetime:     w.lifetime,
+        tier:         w.tier,
+        tier_changed: w.tier !== tierBefore,
       };
     },
 
@@ -312,43 +458,41 @@ function create(opts) {
       var orderId    = input.order_id != null ? _uuid(input.order_id, "order_id") : null;
       var notes      = _notes(input.notes);
 
-      var ts = _now();
-      await _ensureAccountRow(customerId, ts);
-      var before = await _readAccount(customerId);
-      if (before.balance_points < points) {
+      var requested = _now();
+      await _ensureAccountRow(customerId, requested);
+      // The overdraft refusal lives INSIDE the guarded INSERT (balSub + points
+      // >= 0, where points is the negative burn delta) — never an app-side
+      // pre-check — so two concurrent redemptions can't double-spend off a
+      // stale snapshot: the chain-parent fence serializes them and the loser
+      // re-reads the winner's smaller balance and is refused. Lifetime is not
+      // affected; redemption spends from the running balance only.
+      var w = await _writeChained(customerId, function (latest) {
+        return {
+          type: "redeem", points: -points, source: "redeem", orderId: orderId, notes: notes,
+          balanceAfter:  latest.balance - points,
+          lifetimeAfter: latest.lifetime,
+          tierAfter:     latest.tier,
+          ts:            _resolveOccurredAt(requested, latest.occurred_at),
+          guard:         "__BAL__ + ?4 >= 0",
+        };
+      });
+      if (w.refused) {
         var ins = new Error("loyalty.redeem: insufficient balance");
         ins.code = "LOYALTY_INSUFFICIENT_BALANCE";
         throw ins;
       }
-
-      // Atomic decrement guarded by a balance check at the SQL tier so
-      // two concurrent redemptions can't double-spend. Lifetime is not
-      // affected — redemption spends from the running balance only.
-      var dec = await query(
-        "UPDATE loyalty_accounts SET balance_points = balance_points - ?1, " +
-        "updated_at = ?2 WHERE customer_id = ?3 AND balance_points >= ?1",
-        [points, ts, customerId],
-      );
-      if (dec.rowCount === 0) {
-        var raced = new Error("loyalty.redeem: insufficient balance");
-        raced.code = "LOYALTY_INSUFFICIENT_BALANCE";
-        throw raced;
-      }
-
-      var txId = await _writeTx(customerId, "redeem", -points, "redeem", orderId, notes, ts);
-
-      var after = await _readAccount(customerId);
+      await _refreshMirror(customerId, w, requested);
+      var acct = await _readAccount(customerId);
       return {
-        balance:         after.balance_points,
-        lifetime:        after.lifetime_points,
-        tier:            after.tier,
-        tier_expires_at: after.tier_expires_at,
-        // Ledger row id of this burn — checkout debits points BEFORE its
-        // order exists (the debit is the double-spend gate) and links the
-        // row to the order afterwards via linkRedemptionToOrder, or
-        // compensates via reverseRedemptionById when the checkout dies
-        // before the order is created.
-        tx_id:           txId,
+        balance:         w.balance,
+        lifetime:        w.lifetime,
+        tier:            w.tier,
+        tier_expires_at: acct ? acct.tier_expires_at : null,
+        // Ledger row id of this burn — checkout debits points BEFORE its order
+        // exists (the debit is the double-spend gate) and links the row to the
+        // order afterwards via linkRedemptionToOrder, or compensates via
+        // reverseRedemptionById when the checkout dies before the order exists.
+        tx_id:           w.id,
       };
     },
 
@@ -366,7 +510,7 @@ function create(opts) {
         "WHERE id = ?2 AND transaction_type = 'redeem' AND order_id IS NULL",
         [oid, tid],
       );
-      return Number(res.rowCount || 0) === 1;
+      return b.sql.casWon(res).won;
     },
 
     // Reverse ONE redeem burn by its ledger row id — the compensation edge
@@ -394,15 +538,24 @@ function create(opts) {
         "WHERE id = ?2 AND restored_points = 0",
         [spent, row.id],
       );
-      if (Number(claim.rowCount || 0) === 0) return { restored_points: 0 };   // lost the claim
+      if (!b.sql.casWon(claim).won) return { restored_points: 0 };   // lost the claim
       await _ensureAccountRow(row.customer_id, ts);
-      await query(
-        "UPDATE loyalty_accounts SET balance_points = balance_points + ?1, " +
-        "updated_at = ?2 WHERE customer_id = ?3",
-        [spent, ts, row.customer_id],
-      );
-      await _writeTx(row.customer_id, "redeem", spent, "redeem-reversal", null,
-        "restored ref=tx:" + row.id, ts);
+      // Forward-only credit-back: ONE chained +spent row off the live tip
+      // (lifetime untouched). The restored_points claim above is the
+      // serialization point, so a double-fire wins no claim and appends
+      // nothing — exactly-once. There is no revert anywhere, so the
+      // two-statement double-credit-on-revert hazard is structurally gone.
+      var w = await _writeChained(row.customer_id, function (latest) {
+        return {
+          type: "redeem", points: spent, source: "redeem-reversal", orderId: null,
+          notes:         "restored ref=tx:" + row.id,
+          balanceAfter:  latest.balance + spent,
+          lifetimeAfter: latest.lifetime,
+          tierAfter:     latest.tier,
+          ts:            _resolveOccurredAt(ts, latest.occurred_at),
+        };
+      });
+      await _refreshMirror(row.customer_id, w, ts);
       return { restored_points: spent };
     },
 
@@ -473,20 +626,26 @@ function create(opts) {
           "WHERE id = ?2 AND restored_points = ?3",
           [target, row.id, already],
         );
-        if (Number(claim.rowCount || 0) === 0) continue;   // lost the claim
+        if (!b.sql.casWon(claim).won) continue;   // lost the claim
         await _ensureAccountRow(row.customer_id, ts);
-        // Credit BALANCE only — lifetime is untouched (a redeem never moved
-        // lifetime; restoring it mustn't either). Relative-atomic so a
-        // concurrent earn/redeem can't clobber it.
-        await query(
-          "UPDATE loyalty_accounts SET balance_points = balance_points + ?1, " +
-          "updated_at = ?2 WHERE customer_id = ?3",
-          [delta, ts, row.customer_id],
-        );
-        // Positive `redeem`-type ledger row so the trail nets to the
-        // un-refunded spend. `source` distinguishes it from the original burn.
-        await _writeTx(row.customer_id, "redeem", delta, "redeem-reversal", oid,
-          "restored ref=order:" + oid, ts);
+        // Forward-only credit-back: ONE chained +delta row off the live tip,
+        // BALANCE only (lifetime untouched — a redeem never moved it, so the
+        // restore mustn't either). The restored_points claim above is the
+        // serialization point; there is no revert, so no double-credit hazard.
+        // `source='redeem-reversal'` distinguishes it from the original burn so
+        // the scan above never re-reads it. _writeChained is awaited before the
+        // loop advances, so `delta`/`oid`/`ts` are stable inside the derive.
+        var wRestore = await _writeChained(row.customer_id, function (latest) {
+          return {
+            type: "redeem", points: delta, source: "redeem-reversal", orderId: oid,
+            notes:         "restored ref=order:" + oid,
+            balanceAfter:  latest.balance + delta,
+            lifetimeAfter: latest.lifetime,
+            tierAfter:     latest.tier,
+            ts:            _resolveOccurredAt(ts, latest.occurred_at),
+          };
+        });
+        await _refreshMirror(row.customer_id, wRestore, ts);
         restoredTotal += delta;
       }
       return { restored_points: restoredTotal };
@@ -501,47 +660,38 @@ function create(opts) {
       var source     = _source(input.source);
       var notes      = _notes(input.notes);
 
-      var ts = _now();
-      await _ensureAccountRow(customerId, ts);
-      // Snapshot the pre-adjust tier only to report `tier_changed`. The
-      // mutation is relative-atomic with an underflow guard at the SQL
-      // tier so two concurrent adjustments can't lose an update or drive
-      // the balance negative past each other.
-      var before = await _readAccount(customerId);
-
-      // Positive adjustments also increment lifetime — operators
-      // crediting a customer for a service recovery should see that
-      // credit count toward tier. Negative adjustments do NOT
-      // decrement lifetime (otherwise a clawback could downgrade tier
-      // retroactively, which is a customer-facing surprise). The
-      // lifetime delta is therefore the positive part of `delta`.
+      var requested = _now();
+      await _ensureAccountRow(customerId, requested);
+      // Positive adjustments increment lifetime (operator goodwill counts
+      // toward tier) and recompute the tier; negative adjustments do NOT move
+      // lifetime (no retroactive tier downgrade) and are guarded so the balance
+      // can't go below zero (balSub + delta >= 0, delta negative) — the loser
+      // of a concurrent over-draw re-reads the live balance and is refused.
       var lifetimeDelta = delta > 0 ? delta : 0;
-      // Conditional UPDATE: the row mutates ONLY when the post-adjust
-      // balance stays non-negative, checked against the row's LIVE
-      // balance (not the stale snapshot). A racing concurrent adjust
-      // that already spent the balance makes this match zero rows, so
-      // we surface the same insufficient-balance refusal rather than
-      // writing a ledger row that diverges from the account.
-      var upd = await query(
-        "UPDATE loyalty_accounts SET balance_points = balance_points + ?1, " +
-        "lifetime_points = lifetime_points + ?2, " +
-        "tier = " + _tierCase("lifetime_points + ?2") + ", " +
-        "updated_at = ?3 WHERE customer_id = ?4 AND balance_points + ?1 >= 0",
-        [delta, lifetimeDelta, ts, customerId],
-      );
-      if (Number(upd.rowCount || 0) === 0) {
+      var tierBefore;
+      var w = await _writeChained(customerId, function (latest) {
+        tierBefore = latest.tier;
+        var lifeAfter = latest.lifetime + lifetimeDelta;
+        return {
+          type: "adjust", points: delta, source: source, orderId: null, notes: notes,
+          balanceAfter:  latest.balance + delta,
+          lifetimeAfter: lifeAfter,
+          tierAfter:     delta > 0 ? computeTier(lifeAfter) : latest.tier,
+          ts:            _resolveOccurredAt(requested, latest.occurred_at),
+          guard:         delta < 0 ? "__BAL__ + ?4 >= 0" : undefined,
+        };
+      });
+      if (w.refused) {
         var ins = new Error("loyalty.adjust: adjustment would underflow balance");
         ins.code = "LOYALTY_INSUFFICIENT_BALANCE";
         throw ins;
       }
-      await _writeTx(customerId, "adjust", delta, source, null, notes, ts);
-
-      var after = await _readAccount(customerId);
+      await _refreshMirror(customerId, w, requested);
       return {
-        balance:      after.balance_points,
-        lifetime:     after.lifetime_points,
-        tier:         after.tier,
-        tier_changed: after.tier !== before.tier,
+        balance:      w.balance,
+        lifetime:     w.lifetime,
+        tier:         w.tier,
+        tier_changed: w.tier !== tierBefore,
       };
     },
 
@@ -564,21 +714,22 @@ function create(opts) {
       var source     = _source(input.source);
       var notes      = _notes(input.notes);
 
-      var ts = _now();
-      await _ensureAccountRow(customerId, ts);
-      await query(
-        "UPDATE loyalty_accounts SET balance_points = balance_points + ?1, " +
-        "updated_at = ?2 WHERE customer_id = ?3",
-        [points, ts, customerId],
-      );
-      await _writeTx(customerId, "adjust", points, source, null, notes, ts);
-
-      var after = await _readAccount(customerId);
-      return {
-        balance:  after.balance_points,
-        lifetime: after.lifetime_points,
-        tier:     after.tier,
-      };
+      var requested = _now();
+      await _ensureAccountRow(customerId, requested);
+      // Forward-only +points chained row, BALANCE only — never moves lifetime
+      // and never recomputes tier (giving redeemed points back must not inflate
+      // the tier-driving total above what was actually earned).
+      var w = await _writeChained(customerId, function (latest) {
+        return {
+          type: "adjust", points: points, source: source, orderId: null, notes: notes,
+          balanceAfter:  latest.balance + points,
+          lifetimeAfter: latest.lifetime,
+          tierAfter:     latest.tier,
+          ts:            _resolveOccurredAt(requested, latest.occurred_at),
+        };
+      });
+      await _refreshMirror(customerId, w, requested);
+      return { balance: w.balance, lifetime: w.lifetime, tier: w.tier };
     },
 
     expire: async function (input) {
@@ -592,55 +743,49 @@ function create(opts) {
       }
       var reason     = _source(input.reason);
 
-      var ts = _now();
-      await _ensureAccountRow(customerId, ts);
-      var before = await _readAccount(customerId);
-
-      // Expiry caps at the current balance — operators schedule annual
-      // sweeps that compute "points older than 365d" from the ledger;
-      // when the live balance is already smaller than the requested
-      // expire amount (because of an interim redemption), we expire
-      // only what's there rather than refusing.
-      var toExpire = points > before.balance_points ? before.balance_points : points;
-      if (toExpire === 0) {
-        // No-op write the ledger row anyway so the audit trail
-        // records that the operator ran the sweep and found nothing.
-        await _writeTx(customerId, "expire", 0, reason, null, "", ts);
+      var requested = _now();
+      await _ensureAccountRow(customerId, requested);
+      // Cap at the LIVE balance on every attempt (an interim redemption may
+      // have shrunk it) — expire only what's there, never refusing. A zero-cap
+      // (empty balance) still writes a points:0 breadcrumb so the audit trail
+      // records the sweep ran. Lifetime is untouched. The chained row carries
+      // the new running balance, so there is no stored-column second statement.
+      var w = await _writeChained(customerId, function (latest) {
+        var toExpire = points > latest.balance ? latest.balance : points;
         return {
-          balance:  before.balance_points,
-          lifetime: before.lifetime_points,
-          tier:     before.tier,
-          expired:  0,
+          type: "expire", points: -toExpire, source: reason, orderId: null, notes: "",
+          balanceAfter:  latest.balance - toExpire,
+          lifetimeAfter: latest.lifetime,
+          tierAfter:     latest.tier,
+          ts:            _resolveOccurredAt(requested, latest.occurred_at),
+          // toExpire is capped at the same tip so the debit never underflows;
+          // the guard is belt-and-braces against a racing debit (which would
+          // instead collide on the fence and re-cap on retry).
+          guard:         "__BAL__ + ?4 >= 0",
         };
-      }
-
-      await query(
-        "UPDATE loyalty_accounts SET balance_points = balance_points - ?1, " +
-        "updated_at = ?2 WHERE customer_id = ?3 AND balance_points >= ?1",
-        [toExpire, ts, customerId],
-      );
-      await _writeTx(customerId, "expire", -toExpire, reason, null, "", ts);
-
-      var after = await _readAccount(customerId);
+      });
+      await _refreshMirror(customerId, w, requested);
       return {
-        balance:  after.balance_points,
-        lifetime: after.lifetime_points,
-        tier:     after.tier,
-        expired:  toExpire,
+        balance:  w.balance,
+        lifetime: w.lifetime,
+        tier:     w.tier,
+        expired:  -w.points,
       };
     },
 
     balance: async function (customerId) {
       _uuid(customerId, "customer_id");
-      var row = await _readAccount(customerId);
-      if (!row) {
-        return { balance: 0, lifetime: 0, tier: "bronze", tier_expires_at: null };
-      }
+      // Authoritative balance/lifetime/tier come from the chain tip (O(1) on
+      // the running index), NOT the advisory loyalty_accounts mirror. Only
+      // tier_expires_at — an operator time-bound the ledger doesn't carry — is
+      // read from the mirror.
+      var tip  = await _readLatest(customerId);
+      var acct = await _readAccount(customerId);
       return {
-        balance:         row.balance_points,
-        lifetime:        row.lifetime_points,
-        tier:            row.tier,
-        tier_expires_at: row.tier_expires_at,
+        balance:         tip.balance,
+        lifetime:        tip.lifetime,
+        tier:            tip.tier,
+        tier_expires_at: acct ? acct.tier_expires_at : null,
       };
     },
 
@@ -652,8 +797,14 @@ function create(opts) {
         throw new TypeError("loyalty.history: limit must be an integer in [1, 500]");
       }
       var cursor = opts2.cursor;
+      // Exclude the per-customer chain-genesis anchor (the migration backfill
+      // row, id 'genesis-<customer_id>', points 0) — it carries the running-
+      // balance snapshot for the chain, not a real customer transaction. A real
+      // uuid.v7 id never starts with 'genesis-', so this excludes only the
+      // anchor (filtering by id-prefix, not by source: an operator source could
+      // legitimately be 'chain-genesis').
       var sql = "SELECT id, customer_id, transaction_type, points, source, order_id, notes, occurred_at " +
-                "FROM loyalty_transactions WHERE customer_id = ?1";
+                "FROM loyalty_transactions WHERE customer_id = ?1 AND id NOT LIKE 'genesis-%'";
       var params = [customerId];
       if (cursor != null) {
         if (typeof cursor !== "number" || !Number.isInteger(cursor) || cursor < 0) {
@@ -700,6 +851,70 @@ function create(opts) {
       var r = await query(sql, params);
       return r.rows;
     },
+
+    // Walk a customer's running-balance chain and recompute every row_hash to
+    // prove no row was edited or re-ordered after the fact (the loyalty leg of
+    // the money-ledger tamper-evidence). Mirrors gift-card-ledger.verifyChain:
+    // a NULL-row_hash legacy/genesis prefix is skipped until the first hashed
+    // row anchors the chain; a populated all-NULL ledger is `unanchored` (the
+    // shape a full rewrite produces), not "valid". An optional trusted
+    // { count, head } anchor additionally rules out a tail truncation. Verifies
+    // over _rowFieldsForHash — the SAME tuple the writer hashes (order_id +
+    // restored_points excluded), so a linked redemption or a restore can't
+    // false-tamper. O(n); operator-audit use, not hot-path.
+    verifyChain: async function (customerId, opts) {
+      _uuid(customerId, "customer_id");
+      opts = opts || {};
+      var anchor = null;
+      if (opts.anchor != null) {
+        if (typeof opts.anchor !== "object"
+            || typeof opts.anchor.count !== "number" || !Number.isInteger(opts.anchor.count) || opts.anchor.count < 1
+            || typeof opts.anchor.head !== "string" || opts.anchor.head.length !== SHA3_512_HEX_LEN) {
+          throw new TypeError("loyalty.verifyChain: anchor must be { count: positive integer, head: " + SHA3_512_HEX_LEN + "-hex-char string }");
+        }
+        anchor = opts.anchor;
+      }
+      var rows = (await query(
+        "SELECT * FROM loyalty_transactions WHERE customer_id = ?1 ORDER BY occurred_at ASC, id ASC",
+        [customerId],
+      )).rows;
+      var legacyPrefix = 0, anchored = false, prevHash = ZERO_HASH;
+      for (var i = 0; i < rows.length; i += 1) {
+        var row = rows[i];
+        if (!anchored && row.row_hash == null) { legacyPrefix += 1; continue; }
+        anchored = true;
+        var breakBase = { ok: false, rows_verified: i - legacyPrefix, legacy_prefix: legacyPrefix,
+                          break_at: i, break_row_id: row.id };
+        if (row.row_hash == null) return Object.assign(breakBase, { reason: "unhashed row after chain anchor" });
+        if (row.prev_hash !== prevHash) {
+          return Object.assign(breakBase, { reason: "prev_hash mismatch", expected: prevHash, actual: row.prev_hash });
+        }
+        var computed = _computeRowHash(prevHash, _rowFieldsForHash(row));
+        if (computed !== row.row_hash) {
+          return Object.assign(breakBase, { reason: "row_hash mismatch", expected: computed, actual: row.row_hash });
+        }
+        prevHash = row.row_hash;
+      }
+      if (!anchored && rows.length > 0) {
+        return { ok: false, rows_verified: 0, legacy_prefix: legacyPrefix, break_at: 0,
+                 break_row_id: rows[0].id, reason: "unanchored chain (no hashed row in a populated ledger)" };
+      }
+      if (anchor) {
+        if (rows.length < anchor.count) {
+          return { ok: false, rows_verified: rows.length - legacyPrefix, legacy_prefix: legacyPrefix,
+                   anchor_checked: true, reason: "row count below anchor (possible tail truncation)",
+                   expected_count: anchor.count, actual_count: rows.length };
+        }
+        var anchorRow = rows[anchor.count - 1];
+        if (anchorRow.row_hash !== anchor.head) {
+          return { ok: false, rows_verified: rows.length - legacyPrefix, legacy_prefix: legacyPrefix,
+                   anchor_checked: true, reason: "anchor head mismatch (chain replaced below snapshot)",
+                   expected: anchor.head, actual: anchorRow.row_hash };
+        }
+      }
+      return { ok: true, rows_verified: rows.length - legacyPrefix, legacy_prefix: legacyPrefix,
+               head: prevHash, anchor_checked: !!anchor };
+    },
   };
 }