@blamejs/blamejs-shop 0.4.88 → 0.4.90

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- v0.4.90 (2026-06-24) — **Credit-account releases and aging now attribute payments to orders correctly, so cancelling a paid order can't erase another order's debt.** Two related accounting fixes for B2B credit accounts, no configuration or schema changes. On a credit account, payments are revolving — they pay down the oldest outstanding charge first across all of a customer's orders. Releasing the hold on a cancelled or returned order previously reduced the balance by that order's full charge without accounting for payments already applied to it, so on an account with more than one order, cancelling an order that a payment had effectively settled drove the balance below what was genuinely owed and silently erased another order's debt from the outstanding total and the aging report. A release now reduces the balance only by the order's still-unpaid amount (its charges minus the payments attributed to it, oldest-first), so a cancelled-but-paid order is a no-op and every other order's genuine debt is preserved. Separately, the aging report was pooling order-scoped releases together with order-agnostic payments into a single oldest-first settlement, so releasing a recent order could settle the oldest charge and report a genuinely past-due balance as current; the report now nets each order's releases against that order's own charges before applying payments oldest-first, so the past-due buckets reflect reality. The outstanding total is unchanged in every case — only the misattribution is corrected. Upgrade to pick it up. **Changed:** *Vendored blamejs framework refreshed to 0.15.20* — The vendored framework moves from 0.15.19 to 0.15.20, with no API or configuration change. It refreshes the bundled Mozilla public-suffix list (used for cookie-scope, same-site, and DMARC/BIMI domain classification), updates the bundled WebAuthn server library to 13.3.2 (improved passkey attestation certificate-path validation), and corrects the vendored-dependency SBOM version metadata so CVE scanners match advisories against the versions actually shipped. **Fixed:** *Releasing a credit-account order caps at its unpaid amount, not its full charge* — creditLimits.releaseHold now reduces the outstanding balance only by the target order's unpaid exposure — its charges and holds, minus its own prior releases, minus the revolving payments attributed to it under an oldest-order-first allocation — capped at the live balance. Previously it reduced the balance by the order's full net charge and ignored payments entirely (payments carry no order reference), so on a multi-order account, cancelling an order that a payment had already settled released credit that was never owed and erased another order's genuine debt from the outstanding total. A cancelled order whose charge has effectively been paid now releases nothing (the request is refused as having no outstanding amount); a genuinely unpaid order still releases its full exposure. The check is a single atomic statement, so it stays correct under concurrent releases and payments. · *Aging report nets order releases against their own order before applying payments* — creditLimits.agingReport no longer pools order-scoped releases with order-agnostic payments into one oldest-first drain. It first nets each order's releases against that order's own charges (a release reverses its own order's charge, never another's), then applies the revolving payment pool oldest-charge-first across what remains. Previously, releasing a recent order could settle the oldest charge in the pooled drain, masking a genuinely past-due balance as current and inverting the aging buckets that drive dunning and collections. The total outstanding is identical to before — only the bucket distribution is corrected — and it uses the same payment-attribution model as the release cap, so a release and the report can never disagree on an order's unpaid amount.
+
+- 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.90",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-imfe0otYErcB8rr2h6KLSGTtStirysptpXETSPY4zLv3bZoIT75Lo1dOvkOav+xL",

package/lib/credit-limits.js

@@ -256,6 +256,44 @@ function create(opts) {
   var _BAL_SUB = "COALESCE((SELECT balance_after_minor FROM credit_transactions " +
                  "WHERE customer_id = ?2 ORDER BY occurred_at DESC LIMIT 1), 0)";
 
+  // The UNPAID exposure of ONE order (?4) — what releaseHold may release
+  // without consuming balance that belongs to OTHER orders' genuine unpaid
+  // charges. Computed PER CHARGE/HOLD ROW (not collapsed per order), row-
+  // for-row identical to the agingReport recompute, so the two surfaces can
+  // never disagree even when an order carries more than one charge/hold row
+  // (a hold plus a capture, or an injected duplicate). The attribution
+  // model: a RELEASE nets only against its OWN order's rows, oldest-first;
+  // a PAYMENT is revolving (order_id=NULL) and drains the post-release row
+  // remainders global oldest-first. So each row's unpaid = its amount,
+  // minus the release applied to it (its own order's release filling that
+  // order's rows oldest-first), minus the FIFO slice of the payment pool
+  // that overlaps the row's position [cum_rem_before, cum_rem_before+rem) on
+  // the global oldest-first number line. An order's unpaid is the SUM of its
+  // rows' unpaid. Expressed as one correlated subquery (nested CTEs + window
+  // functions) so it composes inside the SAME single-statement atomic write
+  // as _BAL_SUB: a concurrent payment/release commits first and this
+  // subquery re-evaluates against it, so race-safety is preserved with no
+  // app-side read-then-write. References ?2 (customer_id) + ?4 (order_id),
+  // both bound by _appendTxnAtomic.
+  var _UNPAID_SUB =
+    "COALESCE((WITH " +
+    "pay AS (SELECT COALESCE(SUM(amount_minor), 0) AS p " +
+    "  FROM credit_transactions WHERE customer_id = ?2 AND kind = 'payment'), " +
+    "rel AS (SELECT order_id, COALESCE(SUM(amount_minor), 0) AS r " +
+    "  FROM credit_transactions WHERE customer_id = ?2 AND kind = 'release' GROUP BY order_id), " +
+    "rows0 AS (SELECT id, order_id, occurred_at, amount_minor, " +
+    "  COALESCE(SUM(amount_minor) OVER (PARTITION BY order_id ORDER BY occurred_at, id " +
+    "    ROWS BETWEEN UNBOUNDED PRECEDING AND 1 PRECEDING), 0) AS cum_own_before " +
+    "  FROM credit_transactions WHERE customer_id = ?2 AND kind IN ('charge', 'hold')), " +
+    "rel_applied AS (SELECT r0.id, r0.order_id, r0.occurred_at, " +
+    "  r0.amount_minor - MAX(0, MIN(r0.amount_minor, COALESCE(rel.r, 0) - r0.cum_own_before)) AS rem " +
+    "  FROM rows0 r0 LEFT JOIN rel ON rel.order_id = r0.order_id), " +
+    "rows1 AS (SELECT order_id, rem, " +
+    "  COALESCE(SUM(rem) OVER (ORDER BY occurred_at, id ROWS BETWEEN UNBOUNDED PRECEDING AND 1 PRECEDING), 0) AS cum_rem_before " +
+    "  FROM rel_applied) " +
+    "SELECT COALESCE(SUM(rem - MAX(0, MIN(cum_rem_before + rem, (SELECT p FROM pay)) - MAX(cum_rem_before, 0))), 0) " +
+    "FROM rows1 WHERE order_id = ?4), 0)";
+
   // Append a ledger transaction ATOMICALLY. The new balance, the
   // strictly-monotonic occurred_at, and the operation's invariant
   // (credit limit / sufficient balance / outstanding charge) are all
@@ -616,27 +654,28 @@ function create(opts) {
         throw closed;
       }
 
-      // Net exposure to this order — charge + hold sums minus prior
-      // release sums — capped at the live balance, computed and written
-      // in ONE atomic statement. The racy read-sum-then-write this
-      // replaced let two concurrent releases (or a release racing a
-      // payment) both read the same remaining/balance and both write,
-      // double-releasing the order and corrupting the running balance.
-      // The guard refuses when nothing is outstanding (never charged /
-      // already fully released) or the balance is drained, so a release
-      // can't drive the ledger negative. Capping at _BAL_SUB stays
-      // defensive against operator-induced ledger drift.
-      var remainingSub = "COALESCE((SELECT SUM(CASE " +
-        "WHEN kind IN ('charge', 'hold') THEN amount_minor " +
-        "WHEN kind = 'release' THEN -amount_minor ELSE 0 END) " +
-        "FROM credit_transactions WHERE customer_id = ?2 AND order_id = ?4), 0)";
-      var toReleaseExpr = "CASE WHEN " + remainingSub + " < " + _BAL_SUB +
-        " THEN " + remainingSub + " ELSE " + _BAL_SUB + " END";
+      // UNPAID exposure of this order — its net charge minus the FIFO
+      // payments attributed to it (_UNPAID_SUB) — capped at the live
+      // balance, computed and written in ONE atomic statement. Subtracting
+      // the payment attribution is the fix for the multi-order over-release:
+      // the cap used to be the order's GROSS net charge and never subtracted
+      // payments (payments are order-agnostic, order_id=NULL), so releasing a
+      // conceptually-paid order in a multi-order account consumed balance
+      // that belonged to OTHER orders' genuine unpaid charges and erased
+      // their debt. Keeping it a single correlated-subquery statement
+      // preserves the original race-safety (a concurrent release/payment
+      // commits first and _UNPAID_SUB / _BAL_SUB re-evaluate against it). The
+      // guard refuses when the order is fully paid / released / never
+      // charged, or the balance is drained, so a release can't drive the
+      // ledger negative. Capping at _BAL_SUB stays defensive against
+      // operator-induced ledger drift.
+      var toReleaseExpr = "CASE WHEN " + _UNPAID_SUB + " < " + _BAL_SUB +
+        " THEN " + _UNPAID_SUB + " ELSE " + _BAL_SUB + " END";
       var written = await _appendTxnAtomic(
         customerId, "release", orderId, null, requested,
         toReleaseExpr,                                   // amount actually released
         _BAL_SUB + " - (" + toReleaseExpr + ")",         // new balance
-        remainingSub + " > 0 AND " + _BAL_SUB + " > 0",  // nothing outstanding / drained -> refuse
+        _UNPAID_SUB + " > 0 AND " + _BAL_SUB + " > 0",   // fully paid/released/drained -> refuse
         [],
       );
       if (!written) {
@@ -759,23 +798,80 @@ function create(opts) {
       }
       var terms = acct.payment_terms_days;
 
-      // Walk all charge/hold rows oldest-first. Apply payments +
-      // releases FIFO against the oldest outstanding amounts. What
-      // remains in each charge row after settlement is the
-      // outstanding slice for that age bucket.
+      // Walk all charge/hold rows oldest-first, then settle in two passes
+      // that honor what each settlement kind actually reverses:
+      //
+      //   1. A RELEASE is intrinsically order-scoped — it reverses ITS
+      //      order's charge — so it nets only against that order's OWN
+      //      charge slices (oldest-first). Pooling releases with payments
+      //      into one global FIFO drain (the prior behavior) let a release
+      //      of a RECENT order settle the OLDEST charge, masking a genuinely
+      //      past-due balance as current and inverting the aging buckets.
+      //   2. A PAYMENT is revolving (order_id=NULL) — it pays down the
+      //      OLDEST outstanding charge first across ALL orders. It drains
+      //      AFTER the per-order release netting, over whatever net slices
+      //      remain.
+      //
+      // This is the SAME attribution model releaseHold's _UNPAID_SUB cap
+      // uses (own-order releases, then global-FIFO payments), so the report
+      // and a release can never disagree on an order's unpaid exposure. The
+      // total is unchanged (charges − releases − payments); only the bucket
+      // distribution is corrected. The (occurred_at, id) ordering matches the
+      // ledger's monotonic stamping and _UNPAID_SUB's FIFO key.
       var chargeRows = (await query(
-        "SELECT amount_minor, occurred_at, order_id FROM credit_transactions " +
+        "SELECT id, amount_minor, occurred_at, order_id FROM credit_transactions " +
         "WHERE customer_id = ?1 AND kind IN ('charge', 'hold') " +
-        "ORDER BY occurred_at ASC",
+        "ORDER BY occurred_at ASC, id ASC",
         [customerId],
       )).rows;
 
-      var settleRow = (await query(
+      // Per-order release totals — netted against that order's own charges.
+      var relRows = (await query(
+        "SELECT order_id, COALESCE(SUM(amount_minor), 0) AS rel FROM credit_transactions " +
+        "WHERE customer_id = ?1 AND kind = 'release' GROUP BY order_id",
+        [customerId],
+      )).rows;
+      var relByOrder = Object.create(null);
+      for (var ri = 0; ri < relRows.length; ri += 1) {
+        relByOrder[relRows[ri].order_id] = relRows[ri].rel;
+      }
+
+      // Order-agnostic payment pool — drains FIFO AFTER release netting.
+      var paySettleRow = (await query(
         "SELECT COALESCE(SUM(amount_minor), 0) AS total FROM credit_transactions " +
-        "WHERE customer_id = ?1 AND kind IN ('payment', 'release')",
+        "WHERE customer_id = ?1 AND kind = 'payment'",
         [customerId],
       )).rows[0];
-      var toSettle = settleRow ? settleRow.total : 0;
+      var toSettle = paySettleRow ? paySettleRow.total : 0;
+
+      var slices = [];
+      for (var si = 0; si < chargeRows.length; si += 1) {
+        slices.push({
+          order_id:    chargeRows[si].order_id,
+          occurred_at: chargeRows[si].occurred_at,
+          remaining:   chargeRows[si].amount_minor,
+        });
+      }
+      // Pass 1: net each order's releases against its OWN charge slices,
+      // oldest-first (slices are already in global oldest-first order).
+      for (var p1 = 0; p1 < slices.length; p1 += 1) {
+        var sRel = slices[p1];
+        var rel  = relByOrder[sRel.order_id] || 0;
+        if (rel > 0) {
+          var rd = rel > sRel.remaining ? sRel.remaining : rel;
+          sRel.remaining -= rd;
+          relByOrder[sRel.order_id] = rel - rd;
+        }
+      }
+      // Pass 2: drain the order-agnostic payment pool FIFO across the
+      // remaining net slices, oldest-first.
+      for (var p2 = 0; p2 < slices.length && toSettle > 0; p2 += 1) {
+        var sPay = slices[p2];
+        if (sPay.remaining <= 0) continue;
+        var pd = toSettle > sPay.remaining ? sPay.remaining : toSettle;
+        sPay.remaining -= pd;
+        toSettle       -= pd;
+      }
 
       var buckets = {};
       buckets[AGE_BUCKETS.CURRENT] = 0;
@@ -784,22 +880,15 @@ function create(opts) {
       buckets[AGE_BUCKETS.D90]     = 0;
 
       var total = 0;
-      for (var i = 0; i < chargeRows.length; i += 1) {
-        var row = chargeRows[i];
-        var remaining = row.amount_minor;
-        if (toSettle > 0) {
-          var settled = toSettle > remaining ? remaining : toSettle;
-          remaining -= settled;
-          toSettle  -= settled;
-        }
+      for (var i = 0; i < slices.length; i += 1) {
+        var remaining = slices[i].remaining;
         if (remaining <= 0) continue;
-        var ageMs   = now - row.occurred_at;
+        var ageMs   = now - slices[i].occurred_at;
         var ageDays = Math.floor(ageMs / MS_PER_DAY);
-        // Bucket by days-past-due so the report reads the same
-        // regardless of the account's payment terms — a net-15 and
-        // a net-60 account both report `current` against not-yet-
-        // due charges, then advance through 30 / 60 / 90+ buckets
-        // measured from the due date.
+        // Bucket by days-past-due so the report reads the same regardless of
+        // the account's payment terms — a net-15 and a net-60 account both
+        // report `current` against not-yet-due charges, then advance through
+        // 30 / 60 / 90+ buckets measured from the due date.
         var pastDue = ageDays - terms;
         var bucket;
         if (pastDue <= 0)        bucket = AGE_BUCKETS.CURRENT;

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,
       };
     },