@blamejs/blamejs-shop 0.4.88 → 0.4.89

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- v0.4.89 (2026-06-24) — **Store-credit wallet balances are now tamper-evident, and concurrent gift-card ledger writes retry reliably in production.** The store-credit ledger gains the same per-customer cryptographic hash chain the gift-card ledger already carries, so a balance can no longer be silently altered by a direct database edit. Each wallet row now links to the prior one with a SHA3-512 hash over its contents, and a new verifyChain check recomputes the chain and reports the first row that doesn't link — a denormalized balance snapshot was previously a value, not a proof, so a row edit that inflated a balance or a deletion that dropped a debit passed a balance read undetected. The same change makes the balance computation safe under concurrency through a chain-parent fence and a re-read-and-retry on contention. Separately, a latent reliability bug in the gift-card ledger's concurrent-write retry is fixed: it detected a write collision by matching the database's error text, but the production data-layer redacts that text to a generic error, so a genuine collision between two writes against the same gift card could surface as a failed request instead of retrying — both ledgers now detect a collision by re-reading the chain tip, which is robust regardless of how the error is reported. No configuration changes; the store-credit schema additions apply automatically on upgrade. **Added:** *Store-credit ledger is tamper-evident with a per-customer hash chain* — Every store-credit wallet row now carries prev_hash + row_hash columns forming a per-customer SHA3-512 chain: row_hash = SHA3-512(prev_hash || canonical-json(row fields)), anchored at a genesis sentinel for a wallet's first row. A direct database edit that inflates a balance snapshot, or a deletion that drops a debit, breaks the chain at that row. A new storeCredit.verifyChain(customer_id) walks the wallet and returns the first divergence (or confirms the chain is intact); a wallet whose hash columns have all been cleared reads as unanchored rather than trusting the unverifiable rows. Because deleting a chain's most-recent rows leaves the remaining prefix internally consistent — a truncation an append-only chain can't detect on its own — verifyChain optionally accepts a trusted anchor (a row count and head hash captured from an earlier snapshot) and reports a possible truncation when the chain has fallen below it. The balance and occurred-at values are now computed in the application and protected under concurrency by a chain-parent uniqueness fence — a write derived from a stale view of the wallet collides and is retried against the current tip, so the denormalized balance stays exact under concurrent credits, debits, expirations, and the scheduled expiry sweep. **Fixed:** *Concurrent gift-card and store-credit ledger writes retry reliably in production* — The ledger retries a write that loses a race against a concurrent write to the same entity. It previously recognized that collision by matching the database engine's constraint-violation text — but the production data-layer redacts that text to a generic error, so in production a genuine collision was not recognized and the write surfaced as a failed request instead of retrying (the path only worked under the in-memory test engine, where the full error text survives). Both the gift-card ledger and the new store-credit chain now detect a collision by re-reading the chain tip after a failed write: if the tip has advanced past the row the write tried to extend, a competing write claimed the slot and the write is retried; otherwise the original error is surfaced. The retry is now robust regardless of how the underlying error is reported.
+
 - v0.4.88 (2026-06-24) — **Refreshes the vendored framework to 0.15.19 and makes the vendored-dependency SBOM a committed, drift-guarded artifact.** Two supply-chain changes, no application configuration changes. The vendored blamejs framework moves from 0.15.16 to 0.15.19, picking up a set of upstream correctness and confidentiality fixes that ride inside the primitives the store already composes: a rejection on an established encrypted-API session is now returned inside the encrypted session envelope instead of disclosing which check failed in cleartext; stapled-OCSP response-freshness validation is restored; the DPoP proof's request-URI reconstruction now peer-gates forwarded scheme/host headers; the bundled public-suffix list is refreshed; and a family of credential/certificate verifiers continues to fail closed on an unparseable timestamp. Separately, the vendored-dependency SBOM (sbom.vendored.cdx.json) is now committed to the repository and mechanically projected from the vendored manifest, so its component versions can never silently fall behind what actually ships under lib/vendor/: a build gate fails on any drift, and the published, signed SBOM is the same verified file rather than one regenerated at publish time. Upgrade to pick both up. **Added:** *Vendored-dependency SBOM is a committed, drift-guarded artifact* — sbom.vendored.cdx.json — the CycloneDX 1.6 SBOM describing what ships under lib/vendor/ — is now committed to the repository and generated as a deterministic projection of lib/vendor/MANIFEST.json (the source of truth for the vendored version, license, and source). The vendor refresh regenerates it automatically, and a build gate fails if the committed SBOM drifts from the vendored manifest, so its component versions can never silently fall behind the vendored tree — the same protection the changelog, the release-notes rollup, and the asset-manifest already carry. The signed SBOM published as a release asset is now this same verified file rather than one regenerated at publish time, so the artifact downstream scanners consume is byte-reproducible from the committed source. **Changed:** *Vendored blamejs framework refreshed to 0.15.19* — The vendored framework moves from 0.15.16 to 0.15.19. The changes are upstream correctness and confidentiality fixes that ride inside the primitives the store already uses, with no API or configuration change: a rejection on an established encrypted-API session is now encrypted inside the session envelope rather than returned as a cleartext reason that disclosed which check failed; stapled-OCSP response-freshness enforcement (RFC 6960) is restored after a parsing regression had it reject every response; the DPoP htu reconstruction and the new request-host resolver only honor forwarded scheme/host headers from a declared trusted proxy; the bundled Mozilla public-suffix list (used for cookie-scope and same-site decisions) is refreshed to current upstream; and the credential/certificate validity-window verifiers continue to refuse a present-but-unparseable timestamp instead of skipping the check.
 
 - v0.4.87 (2026-06-22) — **Adding a bundle now charges the advertised bundle price even when a member item is already in the cart.** Fixes a pricing bug when adding a product bundle to a cart that already contains one of the bundle's items. Adding a bundle allocates the discounted bundle price across its members and writes each member to the cart at its allocated per-unit price. But when a member variant was already in the cart on its own, the add merged into the existing line and kept that line's standalone list price, so the cart subtotal came out above the advertised bundle price — the shopper was quoted the discounted bundle but charged closer to the full sum of parts. Adding a bundle now adds the bundle's units at the bundle price while preserving any units already in the cart: a fresh bundle add realizes exactly the advertised bundle price, and a bundle added on top of a standalone item keeps that item and adds the bundle at its discounted price (rather than dropping the item or extending the discount to it). No configuration changes; upgrade to pick it up. **Fixed:** *Bundle add honors the bundle price without disturbing existing cart units* — Adding a bundle now adds each member's units at the bundle's allocated per-unit price. On a fresh line the realized subtotal is exactly the advertised bundle price. When the variant is already in the cart, its existing units are kept at their value and the bundle's units are added at the bundle price, so the shopper is neither overcharged (the previous behavior charged the standalone list price for the bundle unit) nor has their existing quantity dropped. Adding the same bundle twice adds two bundles' worth of units. Direct add-to-cart of a standalone item is unchanged.

package/SECURITY.md

@@ -319,15 +319,20 @@ node -e "
   (success / failure / denied) and paginated. Opening the log is itself
   recorded (an `audit.read` row), so reviewing the audit trail leaves
   its own forensic mark.
-- **The gift-card ledger is hash-chained, fork-proof, and verifiable.**
-  Every ledger entry — credits, debits, and expirations alike — links to
-  its predecessor through a per-card SHA3-512 chain, so a direct edit or
-  deletion of a row breaks the linkage. A uniqueness fence (one child per
-  chain tip) makes concurrent writes serialize rather than fork the
-  chain, and `giftCardLedger.verifyChain(cardId)` recomputes a card's
-  chain end to end and reports the first divergence — run it whenever a
-  card's balance is disputed. The overdraft refusal stays inside the same
-  guarded insert, so the integrity device never weakens the balance gate.
+- **The gift-card and store-credit ledgers are hash-chained, fork-proof,
+  and verifiable.** Every ledger entry — credits, debits, and
+  expirations alike — links to its predecessor through a SHA3-512 chain,
+  keyed per card (gift cards) or per customer (store credit), so editing a
+  row or deleting one from the middle breaks the linkage. A uniqueness
+  fence (one child per chain tip) makes concurrent writes serialize rather
+  than fork the chain. `giftCardLedger.verifyChain(cardId)` /
+  `storeCredit.verifyChain(customerId)` recompute a ledger's chain end to
+  end and report the first divergence — run them whenever a balance is
+  disputed; pass a trusted anchor (a row count + head hash from an earlier
+  snapshot) to also catch a truncation that deletes the most-recent rows,
+  which an append-only chain can't detect on its own. The overdraft
+  refusal stays inside the same guarded insert, so the integrity device
+  never weakens the balance gate.
 - **Privacy exports hold the whole record; erasure states a basis per
   domain.** A subject-access export walks every table that keys a row
   by the customer — identity, orders, subscriptions, addresses, saved

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.88",
+  "version": "0.4.89",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-imfe0otYErcB8rr2h6KLSGTtStirysptpXETSPY4zLv3bZoIT75Lo1dOvkOav+xL",

package/lib/gift-card-ledger.js

@@ -242,15 +242,14 @@ function create(opts) {
   }
 
   // How many times a writer re-derives the chain tip when the parent fence
-  // refuses its INSERT (another write landed first). Each retry re-reads
-  // the tip, so contention resolves in one extra round trip per racing
-  // writer; five attempts is far beyond any realistic burst.
-  var CHAIN_WRITE_ATTEMPTS = 5;
-
-  function _isChainFenceCollision(err) {
-    var msg = (err && err.message) || "";
-    return /UNIQUE constraint failed/i.test(msg) && /(prev_hash|chain_parent)/i.test(msg);
-  }
+  // refuses its INSERT (another write landed first). Each fence round lets
+  // exactly ONE racing writer win, so a burst of N concurrent writes to the
+  // SAME card needs up to N rounds — the cap is sized well beyond any
+  // realistic same-card fan-in so a legitimate burst is never dropped with
+  // GIFT_CARD_LEDGER_CONTENTION. A genuine non-collision insert error
+  // re-throws on the first attempt (see _attemptChainedWrite), so a high cap
+  // never spins on a real failure.
+  var CHAIN_WRITE_ATTEMPTS = 64;
 
   // One fenced write attempt against a tip the caller just read. EVERY
   // event kind writes through here so every row participates in the
@@ -295,7 +294,16 @@ function create(opts) {
       if (Number(res.rowCount || 0) === 0) return { refused: true };
       return { written: { id: id, balance_after_minor: d.after, occurred_at: d.ts } };
     } catch (e) {
-      if (_isChainFenceCollision(e)) return { collided: true };
+      // State-agnostic collision detection — never error-message matching:
+      // the production D1 service-binding redacts the SQLite "UNIQUE
+      // constraint failed" text to a generic "HTTP 500", so a message regex
+      // is blind in prod (it would only match under node:sqlite, where the
+      // full text survives). Re-read the tip — if it advanced past the
+      // parent we tried to chain off, a competing write claimed our slot (a
+      // genuine fence collision) and we retry; if the tip is unchanged the
+      // insert failed for another reason, so re-throw.
+      var after = await _readLatest(giftCardId);
+      if (after.row_hash !== latest.row_hash) return { collided: true };
       throw e;
     }
   }
@@ -483,8 +491,26 @@ function create(opts) {
     // leaves behind) fails: an all-NULL chain is unanchored, not valid.
     // An empty ledger (zero rows) is the only no-anchor case that passes.
     // O(n) per card; operator-audit use, not hot-path.
-    verifyChain: async function (giftCardId) {
+    verifyChain: async function (giftCardId, opts) {
       _uuid(giftCardId, "gift_card_id");
+      opts = opts || {};
+      // Optional trusted anchor (opts.anchor = { count, head } from a prior
+      // snapshot's total_rows + last_hash) — the ONLY way to detect a TAIL
+      // TRUNCATION or whole-chain replacement, since an append-only chain
+      // stays internally consistent after its tail is removed. The row at the
+      // snapshot's position must still carry the snapshot's head hash (it
+      // survives later valid appends). Without an anchor, truncation is not
+      // ruled out and anchor_checked:false is reported (operator-audit-log
+      // closes the same gap with signed checkpoints).
+      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("giftCardLedger.verifyChain: anchor must be { count: positive integer, head: " + SHA3_512_HEX_LEN + "-hex-char string }");
+        }
+        anchor = opts.anchor;
+      }
       var r = await query(
         "SELECT * FROM gift_card_ledger WHERE gift_card_id = ?1 " +
         "ORDER BY occurred_at ASC, id ASC",
@@ -551,11 +577,42 @@ function create(opts) {
           reason:         "unanchored chain (no hashed row in a populated ledger)",
         };
       }
+      // Internal walk is clean. With a trusted anchor, also rule out a tail
+      // truncation below the snapshot: the row at the snapshot's position
+      // must still carry the snapshot's head hash, and the chain must not be
+      // shorter than the snapshot.
+      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 || anchorRow.row_hash !== anchor.head) {
+          return {
+            ok:             false,
+            rows_verified:  rows.length - legacyPrefix,
+            legacy_prefix:  legacyPrefix,
+            anchor_checked: true,
+            reason:         "anchor row hash mismatch (possible tail truncation or divergence)",
+            expected:       anchor.head,
+            actual:         anchorRow ? anchorRow.row_hash : null,
+          };
+        }
+      }
       return {
-        ok:            true,
-        rows_verified: rows.length - legacyPrefix,
-        legacy_prefix: legacyPrefix,
-        last_hash:     prevHash,
+        ok:             true,
+        rows_verified:  rows.length - legacyPrefix,
+        legacy_prefix:  legacyPrefix,
+        total_rows:     rows.length,
+        last_hash:      prevHash,
+        anchor_checked: anchor != null,
       };
     },
 

package/lib/store-credit.js

@@ -89,6 +89,12 @@ var PRINTABLE_RE = /^[^\x00-\x1f\x7f]*$/;
 var MAX_BULK_IDS = 500;
 var MS_PER_DAY   = C.TIME.days(1);
 
+var SHA3_512_HEX_LEN = 128;
+// Genesis anchor for a customer's first ledger row. Each customer wallet
+// is its own independent chain — the first row links to ZERO, every
+// subsequent row links to the prior row's row_hash for the SAME customer.
+var ZERO_HASH = "0".repeat(SHA3_512_HEX_LEN);
+
 // ---- validators ---------------------------------------------------------
 
 function _uuid(s, label) {
@@ -137,6 +143,39 @@ function _epochMs(ts, label) {
 
 function _now() { return Date.now(); }
 
+// ---- chain hashing ------------------------------------------------------
+//
+// row_hash = SHA3-512(prev_hash || canonical-json(row-fields)), mirroring
+// shop.giftCardLedger / operator-audit-log. `b.auditChain.canonicalize`
+// (RFC 8785 walker, sorted keys, hash columns excluded) makes the preimage
+// byte-identical across deployments + node versions. Every persisted column
+// except the two hash columns participates, normalized so the write side
+// and `verifyChain` produce identical preimages for the same logical row.
+
+function _rowFieldsForHash(row) {
+  return {
+    id:                  row.id,
+    customer_id:         row.customer_id,
+    kind:                row.kind,
+    amount_minor:        Number(row.amount_minor),
+    source:              row.source == null ? null : row.source,
+    source_ref:          row.source_ref == null ? null : row.source_ref,
+    order_id:            row.order_id == null ? null : row.order_id,
+    balance_after_minor: Number(row.balance_after_minor),
+    expires_at:          row.expires_at == null ? null : Number(row.expires_at),
+    occurred_at:         Number(row.occurred_at),
+  };
+}
+
+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) {
@@ -151,16 +190,24 @@ function create(opts) {
   // aggregation at read time. Falls through to 0 when no rows exist
   // (a customer that has never had a ledger row has zero credit). The id
   // tie-break keeps any legacy same-millisecond rows deterministic; new
-  // writes can't tie — _writeRowAtomic computes a strictly-monotonic
-  // per-customer occurred_at inside the INSERT itself.
+  // writes can't tie — _resolveOccurredAt bumps a colliding timestamp to
+  // prior+1 app-side before the fenced INSERT. Also returns the tip's
+  // row_hash so the write path can chain off it (see _attemptChainedWrite).
   async function _readLatest(customerId) {
     var r = await query(
-      "SELECT balance_after_minor, occurred_at FROM store_credit_ledger " +
+      "SELECT balance_after_minor, occurred_at, row_hash FROM store_credit_ledger " +
       "WHERE customer_id = ?1 ORDER BY occurred_at DESC, id DESC LIMIT 1",
       [customerId],
     );
-    if (!r.rows.length) return { balance: 0, occurred_at: null };
-    return { balance: r.rows[0].balance_after_minor, occurred_at: r.rows[0].occurred_at };
+    if (!r.rows.length) return { balance: 0, occurred_at: null, row_hash: ZERO_HASH };
+    return {
+      balance:     r.rows[0].balance_after_minor,
+      occurred_at: r.rows[0].occurred_at,
+      // A legacy pre-chain row carries NULL row_hash — chain forward from
+      // ZERO so the first hashed row anchors the chain; verifyChain treats
+      // the unhashed legacy prefix as unverifiable rather than trusting it.
+      row_hash:    r.rows[0].row_hash == null ? ZERO_HASH : r.rows[0].row_hash,
+    };
   }
 
   async function _currentBalance(customerId) {
@@ -168,84 +215,101 @@ function create(opts) {
     return latest.balance;
   }
 
-  // Single-statement guarded write — the concurrency spine of the wallet.
-  // The live balance AND the strictly-monotonic per-customer occurred_at
-  // are computed by correlated subqueries INSIDE the INSERT, so two
-  // concurrent writes can never base off the same stale snapshot: the
-  // statements serialize at the database and the second sees the first's
-  // row. (A JS-side read-then-write here double-fulfilled concurrent
-  // debits and silently dropped one of two same-millisecond credits.)
-  // `kind` selects the guard + arithmetic:
-  //   credit — balance_after = live + amount, no balance gate (the in-SQL
-  //            occurred_at is what closes the same-millisecond tie);
-  //   debit  — balance_after = live - amount, gated on live >= amount
-  //            (zero rows = insufficient, or lost the race — same refusal);
-  //   expire — burns MIN(amount, live), gated on live > 0 (zero rows =
-  //            wallet already empty; callers degrade gracefully — by
-  //            design, never a throw).
-  //   sweep  — the scheduled expiry burn. `amount` carries the
-  //            customer's expired-credit total; the still-unburned
-  //            remainder (total minus the live SUM of prior
-  //            SWEEP_SOURCE_REF expire rows) is recomputed INSIDE the
-  //            insert and capped at the live balance, so two concurrent
-  //            sweeps can't both burn the same expired pool. The second
-  //            sweep serializes behind the first's committed row, sees
-  //            zero pending, and matches no rows — never burning the
-  //            still-valid (non-expired) credit left in the wallet.
-  //            Stored as an `expire` row stamped SWEEP_SOURCE_REF.
-  // Returns the written row's resolved values, or null when the guard
-  // refused the write.
-  async function _writeRowAtomic(kind, customerId, amount, source, sourceRef, orderId, expiresAt, requestedTs) {
+  // Strictly-monotonic per-customer occurred_at: a write at or before the
+  // prior row's timestamp is bumped to prior+1, so the denormalized
+  // balance_after snapshot is unambiguous on read. A backdated operator
+  // write still lands at the requested time when there's no collision.
+  function _resolveOccurredAt(requestedTs, latestTs) {
+    if (latestTs == null) return requestedTs;
+    if (requestedTs > latestTs) return requestedTs;
+    return latestTs + 1;
+  }
+
+  // How many times a writer re-derives the chain tip when the parent fence
+  // refuses its INSERT (another write landed first). Each fence round lets
+  // exactly ONE racing writer win, so a burst of N concurrent writes to the
+  // SAME customer needs up to N rounds — the cap is sized well beyond any
+  // realistic same-wallet fan-in (an admin grant + the scheduled expiry
+  // sweep + a checkout debit racing at once) so a legitimate burst is never
+  // dropped with STORE_CREDIT_CONTENTION. A genuine non-collision insert
+  // error re-throws on the first attempt (see _attemptChainedWrite), so a
+  // high cap never spins on a real failure.
+  var CHAIN_WRITE_ATTEMPTS = 64;
+
+  // One fenced write against the tip the caller just read. The live balance
+  // AND the strictly-monotonic occurred_at are computed APP-SIDE and bound
+  // explicitly, together with prev_hash + row_hash so every row participates
+  // in the per-customer hash chain. What makes the app-computed values safe
+  // is the chain-parent fence UNIQUE(customer_id, prev_hash) (migration
+  // 0236): a write derived from a STALE tip collides at the constraint
+  // instead of forking the chain or persisting a balance computed off a
+  // stale snapshot — the caller re-reads and retries. The debit overdraft
+  // gate stays INSIDE the statement (the correlated subquery, never a
+  // JS-side check): with the fence it is defense-in-depth, and it is what
+  // turns a genuine overdraft into a zero-row refusal rather than a retry
+  // loop.
+  //
+  // Collision detection is STATE-AGNOSTIC, never error-message matching:
+  // the production D1 service-binding redacts the SQLite "UNIQUE constraint
+  // failed" text to a generic "HTTP 500", so on ANY insert error we re-read
+  // the tip — if it advanced past the parent we tried to chain off, a
+  // competing write claimed our slot (a genuine fence collision) and we
+  // retry; if the tip is unchanged the insert failed for another reason, so
+  // we re-throw. Returns one of { written }, { refused } (the guard said no
+  // against the live tip), or { collided } (tip moved — retry).
+  async function _attemptChainedWrite(customerId, kind, latest, d) {
     var id = b.uuid.v7();
     var storedKind = kind === "sweep" ? "expire" : kind;
+    var rowHash = _computeRowHash(latest.row_hash, _rowFieldsForHash({
+      id:                  id,
+      customer_id:         customerId,
+      kind:                storedKind,
+      amount_minor:        d.amount,
+      source:              d.source,
+      source_ref:          d.sourceRef,
+      order_id:            d.orderId,
+      balance_after_minor: d.after,
+      expires_at:          d.expiresAt,
+      occurred_at:         d.ts,
+    }));
     var balSub = "COALESCE((SELECT balance_after_minor FROM store_credit_ledger " +
                  "WHERE customer_id = ?2 ORDER BY occurred_at DESC, id DESC LIMIT 1), 0)";
-    var tsSub  = "COALESCE((SELECT occurred_at FROM store_credit_ledger " +
-                 "WHERE customer_id = ?2 ORDER BY occurred_at DESC, id DESC LIMIT 1), 0)";
-    var tsExpr = "CASE WHEN ?8 > " + tsSub + " THEN ?8 ELSE " + tsSub + " + 1 END";
-    var amountExpr, afterExpr, guard;
-    if (kind === "credit") {
-      amountExpr = "?3";
-      afterExpr  = balSub + " + ?3";
-      guard      = "1";
-    } else if (kind === "debit") {
-      amountExpr = "?3";
-      afterExpr  = balSub + " - ?3";
-      guard      = balSub + " >= ?3";
-    } else if (kind === "sweep") {
-      // `?3` is this customer's expired-credit total. Subtract the live
-      // sum of prior sweep-stamped expire rows to get the still-pending
-      // burn, then cap at the live balance — both recomputed at INSERT
-      // time so a racing second sweep sees the first's committed row.
-      var sweptSub = "COALESCE((SELECT SUM(amount_minor) FROM store_credit_ledger " +
-                     "WHERE customer_id = ?2 AND kind = 'expire' AND source_ref = ?5), 0)";
-      var pending  = "(?3 - " + sweptSub + ")";
-      amountExpr   = "CASE WHEN " + balSub + " < " + pending + " THEN " + balSub + " ELSE " + pending + " END";
-      afterExpr    = "CASE WHEN " + balSub + " < " + pending + " THEN 0 ELSE " + balSub + " - " + pending + " END";
-      guard        = pending + " > 0 AND " + balSub + " > 0";
-    } else {            // expire — burn MIN(amount, live balance)
-      amountExpr = "CASE WHEN " + balSub + " < ?3 THEN " + balSub + " ELSE ?3 END";
-      afterExpr  = "CASE WHEN " + balSub + " < ?3 THEN 0 ELSE " + balSub + " - ?3 END";
-      guard      = balSub + " > 0";
+    try {
+      var res = await query(
+        "INSERT INTO store_credit_ledger " +
+        "(id, customer_id, kind, amount_minor, source, source_ref, order_id, balance_after_minor, expires_at, occurred_at, prev_hash, row_hash) " +
+        "SELECT ?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12 " +
+        "WHERE " + (d.guarded ? balSub + " >= ?4" : "1"),
+        [id, customerId, storedKind, d.amount, d.source, d.sourceRef, d.orderId, d.after, d.expiresAt, d.ts, latest.row_hash, rowHash],
+      );
+      if (Number(res.rowCount || 0) === 0) return { refused: true };
+      return { written: { id: id, amount_minor: d.amount, balance_after_minor: d.after, occurred_at: d.ts } };
+    } catch (e) {
+      var after = await _readLatest(customerId);
+      if (after.row_hash !== latest.row_hash) return { collided: true };
+      throw e;
     }
-    var res = await query(
-      "INSERT INTO store_credit_ledger " +
-      "(id, customer_id, kind, amount_minor, source, source_ref, order_id, balance_after_minor, expires_at, occurred_at) " +
-      "SELECT ?1, ?2, ?9, " + amountExpr + ", ?4, ?5, ?6, " + afterExpr + ", ?7, " + tsExpr + " " +
-      "WHERE " + guard,
-      [id, customerId, amount, source, sourceRef, orderId, expiresAt, requestedTs, storedKind],
-    );
-    if (Number(res.rowCount || 0) === 0) return null;
-    var row = (await query(
-      "SELECT amount_minor, balance_after_minor, occurred_at FROM store_credit_ledger WHERE id = ?1",
-      [id],
-    )).rows[0];
-    return {
-      id:                  id,
-      amount_minor:        row.amount_minor,
-      balance_after_minor: row.balance_after_minor,
-      occurred_at:         row.occurred_at,
-    };
+  }
+
+  // Run a chained write with bounded tip-contention retries. `derive` maps
+  // the freshly-read tip to the attempt's concrete fields (it may be async —
+  // the sweep reads its prior-burn sum inside), or returns { noop: true }
+  // for a write that degrades gracefully on an empty / already-settled
+  // wallet. Each fence collision re-reads the tip and re-derives, so the
+  // values that land are always consistent with the parent they chain off.
+  async function _writeChained(customerId, kind, derive) {
+    for (var attempt = 0; attempt < CHAIN_WRITE_ATTEMPTS; attempt += 1) {
+      var latest = await _readLatest(customerId);
+      var d = await derive(latest);
+      if (d.noop) return { noop: true, balance: latest.balance };
+      var r = await _attemptChainedWrite(customerId, kind, latest, d);
+      if (r.collided) continue;
+      if (r.refused) return { refused: true };
+      return r.written;
+    }
+    var contention = new Error("storeCredit." + kind + ": persistent chain-tip contention — retry the write");
+    contention.code = "STORE_CREDIT_CONTENTION";
+    throw contention;
   }
 
   return {
@@ -264,7 +328,18 @@ function create(opts) {
       var requested  = _epochMs(input.occurred_at, "occurred_at");
       if (requested == null) requested = _now();
 
-      var w = await _writeRowAtomic("credit", customerId, amount, source, sourceRef, null, expiresAt, requested);
+      var w = await _writeChained(customerId, "credit", function (latest) {
+        return {
+          amount:    amount,
+          source:    source,
+          sourceRef: sourceRef,
+          orderId:   null,
+          expiresAt: expiresAt,
+          after:     latest.balance + amount,
+          ts:        _resolveOccurredAt(requested, latest.occurred_at),
+          guarded:   false,
+        };
+      });
 
       return {
         id:                  w.id,
@@ -289,11 +364,23 @@ function create(opts) {
       var requested  = _epochMs(input.occurred_at, "occurred_at");
       if (requested == null) requested = _now();
 
-      // The balance gate lives INSIDE the insert — a refused write covers
-      // both "always insufficient" and "a concurrent debit drained it
-      // first", with no window between check and write.
-      var w = await _writeRowAtomic("debit", customerId, amount, null, null, orderId, null, requested);
-      if (!w) {
+      // The balance gate lives INSIDE the insert (defense-in-depth behind
+      // the chain-parent fence) — a refused write covers both "always
+      // insufficient" and "a concurrent debit drained it first", with no
+      // window between check and write.
+      var w = await _writeChained(customerId, "debit", function (latest) {
+        return {
+          amount:    amount,
+          source:    null,
+          sourceRef: null,
+          orderId:   orderId,
+          expiresAt: null,
+          after:     latest.balance - amount,
+          ts:        _resolveOccurredAt(requested, latest.occurred_at),
+          guarded:   true,
+        };
+      });
+      if (w.refused) {
         var insufficient = new Error("storeCredit.debit: amount exceeds available balance");
         insufficient.code = "STORE_CREDIT_INSUFFICIENT_BALANCE";
         throw insufficient;
@@ -334,8 +421,24 @@ function create(opts) {
       // already at zero) is the structured no-op below, never a throw —
       // by design: a no-op expire is a valid outcome of a bulk sweep,
       // and a zero-amount row would violate CHECK(amount_minor > 0).
-      var w = await _writeRowAtomic("expire", customerId, amount, null, reason, null, null, requested);
-      if (!w) {
+      var w = await _writeChained(customerId, "expire", function (latest) {
+        var burn = amount > latest.balance ? latest.balance : amount;
+        // An empty wallet is the structured no-op below, never a throw —
+        // a zero-amount row would violate CHECK(amount_minor > 0), and a
+        // no-op expire is a valid outcome of a bulk sweep.
+        if (burn === 0) return { noop: true };
+        return {
+          amount:    burn,
+          source:    null,
+          sourceRef: reason,
+          orderId:   null,
+          expiresAt: null,
+          after:     latest.balance - burn,
+          ts:        _resolveOccurredAt(requested, latest.occurred_at),
+          guarded:   false,
+        };
+      });
+      if (w.noop) {
         return {
           id:                  null,
           customer_id:         customerId,
@@ -343,7 +446,7 @@ function create(opts) {
           amount_minor:        0,
           requested_minor:     amount,
           reason:              reason,
-          balance_after_minor: await _currentBalance(customerId),
+          balance_after_minor: w.balance,
           occurred_at:         requested,
           noop:                true,
         };
@@ -368,6 +471,124 @@ function create(opts) {
       return { customer_id: customerId, balance_minor: bal };
     },
 
+    // Recompute one customer's hash chain and flag the first divergence —
+    // the tamper-evidence READ side of the chain the writers maintain.
+    // Walks the wallet's rows in (occurred_at, id) order; rows from before
+    // the chain columns existed (NULL row_hash) are tolerated as an
+    // unverifiable legacy PREFIX, but once a hashed row anchors, every
+    // later row must link — an unhashed row after the anchor, a prev_hash
+    // that doesn't name its parent, or a row_hash that doesn't recompute is
+    // a break. A populated ledger that never anchors (every row NULL-hashed
+    // — the shape a full-ledger rewrite leaves behind) fails as unanchored;
+    // an empty ledger is the only no-anchor case that passes. O(n) per
+    // customer; operator-audit use, not hot-path.
+    //
+    // Optional trusted anchor (opts.anchor = { count, head }) — the ONLY
+    // way to detect a TAIL TRUNCATION (deleting the most-recent rows) or a
+    // whole-chain replacement, since an append-only chain stays internally
+    // consistent after its tail is removed (a deleted latest debit makes
+    // balance() revert while the remaining prefix still links). The caller
+    // supplies a count + head captured from a trusted prior snapshot of this
+    // same result (count = total_rows, head = last_hash) — a periodic
+    // operator checkpoint or an out-of-band monitor. The chain row at index
+    // count-1 must still carry that head hash, so a truncation BELOW the
+    // snapshot is caught even after later valid appends. Without an anchor
+    // this verifies INTERNAL consistency only and reports
+    // anchor_checked:false so the caller knows truncation was not ruled out
+    // (operator-audit-log closes the same gap with signed checkpoints).
+    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("storeCredit.verifyChain: anchor must be { count: positive integer, head: " + SHA3_512_HEX_LEN + "-hex-char string }");
+        }
+        anchor = opts.anchor;
+      }
+      var r = await query(
+        "SELECT * FROM store_credit_ledger WHERE customer_id = ?1 " +
+        "ORDER BY occurred_at ASC, id ASC",
+        [customerId],
+      );
+      var rows = r.rows;
+      var legacyPrefix = 0;
+      var anchored = false;
+      var 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)",
+        };
+      }
+      // Internal walk is clean. With a trusted anchor, also rule out a tail
+      // truncation below the snapshot: the row at the snapshot's position
+      // must still carry the snapshot's head hash (it survives later valid
+      // appends), and the chain must not be shorter than the snapshot.
+      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 || anchorRow.row_hash !== anchor.head) {
+          return {
+            ok:             false,
+            rows_verified:  rows.length - legacyPrefix,
+            legacy_prefix:  legacyPrefix,
+            anchor_checked: true,
+            reason:         "anchor row hash mismatch (possible tail truncation or divergence)",
+            expected:       anchor.head,
+            actual:         anchorRow ? anchorRow.row_hash : null,
+          };
+        }
+      }
+      return {
+        ok:             true,
+        rows_verified:  rows.length - legacyPrefix,
+        legacy_prefix:  legacyPrefix,
+        total_rows:     rows.length,
+        last_hash:      prevHash,
+        anchor_checked: anchor != null,
+      };
+    },
+
     history: async function (input) {
       if (!input || typeof input !== "object") {
         throw new TypeError("storeCredit.history: input object required");
@@ -639,8 +860,38 @@ function create(opts) {
         // expired credits are "first-out" from the operator's POV — the
         // schema doesn't track FIFO at row level, so the audit trail
         // reflects what was actually burned.
-        var w = await _writeRowAtomic("sweep", customerId, expiredTotal, null, SWEEP_SOURCE_REF, null, null, now);
-        if (!w) continue;
+        var w = await _writeChained(customerId, "sweep", async function (latest) {
+          // Pending burn = this customer's expired-credit total minus the
+          // sweep's OWN prior output (expire rows stamped SWEEP_SOURCE_REF),
+          // capped at the live balance. The prior-burn sum is read INSIDE
+          // the derive so a fence retry recomputes it against the committed
+          // tip: a racing second sweep collides, re-reads a now-nonzero
+          // swept sum, sees zero pending, and no-ops — never burning the
+          // still-valid (non-expired) credit the first sweep left behind.
+          // Operator expires + debits already reduced the balance; the
+          // balance cap is what keeps the sweep from over-burning a partly
+          // drained wallet, so they must not also be netted out of the
+          // expired pool (only this sweep's own output is).
+          var sweptRow = (await query(
+            "SELECT COALESCE(SUM(amount_minor), 0) AS swept FROM store_credit_ledger " +
+            "WHERE customer_id = ?1 AND kind = 'expire' AND source_ref = ?2",
+            [customerId, SWEEP_SOURCE_REF],
+          )).rows[0];
+          var pending = expiredTotal - Number(sweptRow.swept || 0);
+          if (pending <= 0 || latest.balance <= 0) return { noop: true };
+          var burn = pending > latest.balance ? latest.balance : pending;
+          return {
+            amount:    burn,
+            source:    null,
+            sourceRef: SWEEP_SOURCE_REF,
+            orderId:   null,
+            expiresAt: null,
+            after:     latest.balance - burn,
+            ts:        _resolveOccurredAt(now, latest.occurred_at),
+            guarded:   false,
+          };
+        });
+        if (!w || w.noop || w.refused) continue;
         processed.push({
           id:                  w.id,
           customer_id:         customerId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.4.88",
+  "version": "0.4.89",
   "description": "Open-source framework built on blamejs. Vendored stack, zero npm runtime deps, PQC-first crypto, security-on by default.",
   "main": "lib/index.js",
   "scripts": {