@blamejs/blamejs-shop 0.4.104 → 0.4.105

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- v0.4.105 (2026-06-25) — **A loyalty points balance is now an exactly-once, tamper-evident running ledger instead of a stored counter updated alongside its history.** A customer's loyalty balance, lifetime points, and tier were held in a stored account row and updated in a statement separate from the transaction-history insert. On a backend without interactive transactions, a failure between those two writes could leave the balance and the history disagreeing, and there was no way to make a points credit exactly-once with a stored counter. Every loyalty mutation — earn, redeem, expire, adjust, credit, and the refund-time reverse/restore credits — is now a single guarded insert into the transaction ledger that also carries the new running balance, lifetime, and tier, so the balance change and its audit row are one write with no window to half-apply. The running balance is read from the ledger tip rather than a separate counter, redemptions refuse an overdraft inside that one statement, and concurrent writes to the same customer are serialized by a per-customer chain so two redemptions can never both spend the same points. Each ledger row is linked into a per-customer SHA3-512 hash chain, so the history is tamper-evident and can be verified end to end (the loyalty addition to the store-credit and gift-card ledger tamper-evidence). Balances, tiers, the points ratios, and the entire loyalty API are unchanged; the running-balance columns are added by a migration that anchors each existing customer to their current trusted balance without replaying history. The account row is kept as a denormalized mirror for the tier leaderboard and tier-expiry, refreshed after each write and never on a balance decision path. **Changed:** *Loyalty balance, lifetime, and tier are computed from a single guarded ledger write* — The loyalty balance, lifetime points, and tier are no longer a stored counter mutated next to a separate history insert. Each earn / redeem / expire / adjust / credit and each refund-time reverse or restore is now one guarded insert into the loyalty transaction ledger that records the event and carries the resulting running balance, lifetime, and tier in the same row — so a balance change and its audit entry are a single write that cannot half-apply, and a points credit is exactly-once and crash-safe. The current balance is read from the latest ledger row; a redemption's overdraft refusal lives inside that insert; and concurrent writes to one customer are serialized so two redemptions can't both spend the same balance. The customer's balances, tier, the points-per-dollar and redemption ratios, and the public loyalty API are all unchanged. · *Loyalty history is now a tamper-evident hash chain with a verifyChain audit* — Each loyalty transaction row is linked to the previous one for the same customer by a SHA3-512 hash chain, the same tamper-evidence the store-credit and gift-card ledgers already carry. A new verifyChain audit recomputes the chain to prove no past row was edited or re-ordered. A schema migration adds the running-balance and chain columns and anchors every existing customer to their current trusted balance — it copies the live balance verbatim rather than replaying history, so a balance is never recomputed (and never corrupted) during the upgrade. The migration applies automatically on deploy; no operator action is required.
+
 - v0.4.104 (2026-06-25) — **Compare-and-swap atomic claims across the framework now decide won/lost through the shared row-count primitive instead of hand-rolled checks.** Throughout the framework, an atomic claim on a single-statement-per-request backend is a guarded write — UPDATE ... WHERE the row is still in its expected state, or a conditional INSERT — whose affected-row count decides whether this caller won the race (exactly one row) or lost and must no-op. That won/lost decision was hand-rolled at each site as a Number(result.rowCount || 0) === 1 check, which silently treats a result carrying no recognizable row-count as a lost race. Every such site (104 across commissions, redemption caps, inventory and stock-transfer claims, fulfillment and replenishment leases, gift-card and loyalty ledger writes, webhook delivery leases, and more) now routes that decision through the framework's shared row-count primitive, which owns the exactly-one-row check and the cross-adapter row-count field naming, and surfaces an indeterminate result instead of silently counting it as lost. On the production database path the affected-row count is always reported, so there is no behavior change; the change centralizes the interpretation and makes an otherwise-silent indeterminate result observable. No configuration changes and no schema changes. **Changed:** *Atomic compare-and-swap claims use the shared row-count primitive for their won/lost decision* — Compare-and-swap atomic claims — the guarded UPDATE / conditional INSERT pattern used wherever two requests can race the same row on a backend without interactive transactions — previously decided won-versus-lost with a hand-written row-count comparison at each call site, and a result that carried no recognizable row-count was silently taken as a lost race. These claims now make that decision through the framework's shared row-count primitive, which centralizes the exactly-one-row check and the adapter-specific row-count field naming and raises an error on an indeterminate result rather than treating it as a loss. Because the production database always reports the affected-row count, the won/lost outcome is unchanged on every real path; the benefit is one consistent, audited interpretation and a previously-silent indeterminate result now surfacing. A hand-rolled cross-adapter row-count extraction in the webhook delivery-retry lease is removed in favor of the same primitive.
 
 - v0.4.103 (2026-06-25) — **A return refund that exceeds the order's remaining refundable balance is now refused cleanly, instead of failing at the payment provider.** The direct refund console refuses an over-refund up front: it compares the requested amount against the order's remaining refundable balance and returns a clear 'more than is still refundable' error before any money moves. The provider-backed return (RMA) refund path skipped that check — it issued the RMA's approved amount straight to the payment provider, relying on the provider to reject anything past the captured charge. The result was a late, opaque provider-failure error (and a returns workflow left mid-flight) instead of the clean, actionable refusal the console gives. The RMA refund path now applies the same remaining-balance guard before calling the provider: an approved amount greater than what remains refundable — including a return stacked on top of an earlier partial refund — is refused with the same clear message, the return is left in its received state so the operator can re-approve a corrected amount, and the payment provider is never dialed. A refund of an already-refunded return continues to return the existing conflict response. No configuration changes. **Fixed:** *Return (RMA) refunds honor the order's remaining-balance cap before reaching the payment provider* — A provider-backed return refund issued the return's approved amount directly to Stripe or PayPal with no remaining-balance check, so an amount larger than what was still refundable on the order — for example a return approved for more than the order total, or stacked on top of an earlier partial refund — failed only at the payment provider, surfacing as an opaque provider-failure error rather than the clean refusal the direct refund console returns. The return refund path now compares the approved amount against the order's remaining refundable balance first: an over-cap amount is refused with a clear message, the return stays in its received state so a corrected amount can be re-approved, and the provider is never called. A refund attempt on an already-refunded return still returns the existing conflict response.

package/README.md

@@ -81,7 +81,7 @@ Every primitive is composed on the vendored blamejs surface — no npm runtime d
 | **`lib/quotes.js`** | Request-for-quote negotiation. A signed-in customer requests a quote from the cart (line quantities + an optional message); the operator responds from the console with per-line pricing and a validity window; the customer reviews and accepts or declines from `/account/quotes` or through a single-use capability link (`/quote/:token` — the token is stored only as a namespaced hash and compared timing-safe). Accepting converts through the normal order path — inventory holds are placed first and rolled back if order creation fails — and every status change replays a `b.fsm` lifecycle (requested → responded → accepted / declined / expired / withdrawn / converted), with expiry enforced at accept time so a stale price is never honored. A scheduled sweep also transitions quotes past their validity window to `expired` (so the console's expired filter reflects the real lifecycle), operators can reprice an open quote (the customer's existing link shows the new pricing) or convert a verbally-approved one to an order with a recorded reason, and the customer view renders the operator's per-line notes and the validity date. |
 | **`lib/addresses.js`** | Per-customer address book at `/account/addresses` — add / edit / set default shipping or billing / remove. One-default-per-role invariant (promoting clears the prior). Every by-id route confirms the address belongs to the signed-in customer before acting (a guessed id returns 404). `b.guardUuid` ids, 2-char ISO country. |
 | **`lib/returns.js`** | Self-serve RMAs. Customer requests a return against their own order at `/account/orders/:id/return` (items + reason, ownership-checked, lines built from the order's own records) and tracks status at `/account/returns`. Operators work `/admin/returns` — approve (refund amount) / mark received / refund / reject — over the pending → approved → received → refunded FSM; illegal transitions are 409, bad ids 404. |
-| **`lib/loyalty.js`** + **`lib/loyalty-earn-rules.js`** + **`lib/loyalty-redemption.js`** | Customer rewards. `loyalty` owns the points balance, lifetime total, tier (bronze → platinum on operator-tunable thresholds), and an audited transaction ledger. `loyalty-earn-rules` defines how points are minted (per-dollar-spent, per-order, signup, birthday, …) keyed to lifecycle events; `loyalty-redemption` is the reward catalog customers spend points against. Customers see all of it at `/account/loyalty` — balance + tier, the earn rules in plain language, the reward catalog with a one-click Redeem, past redemptions, and the paginated earn/redeem ledger (login-gated). Paid orders award points automatically: the order FSM's paid transition fans out to the earn rules fire-and-forget, deduped on the order id so a re-delivered payment webhook never double-credits. At checkout a signed-in customer can spend points for a credit against the order total — valued by the redemption ratio (100 points = $1 default), capped at the order's worth and the balance, debited once behind a balance-guarded SQL decrement, stacking with any gift-card credit; surplus points stay in the balance. |
+| **`lib/loyalty.js`** + **`lib/loyalty-earn-rules.js`** + **`lib/loyalty-redemption.js`** | Customer rewards. `loyalty` owns the points balance, lifetime total, tier (bronze → platinum on operator-tunable thresholds), and an audited transaction ledger — the balance, lifetime, and tier ride that ledger as a per-customer running snapshot written in one guarded row per event (exactly-once, with no separate counter to fall out of step), linked into a per-customer SHA3-512 hash chain like the gift-card and store-credit ledgers, with `loyalty.verifyChain(customerId)` to recompute it end to end. `loyalty-earn-rules` defines how points are minted (per-dollar-spent, per-order, signup, birthday, …) keyed to lifecycle events; `loyalty-redemption` is the reward catalog customers spend points against. Customers see all of it at `/account/loyalty` — balance + tier, the earn rules in plain language, the reward catalog with a one-click Redeem, past redemptions, and the paginated earn/redeem ledger (login-gated). Paid orders award points automatically: the order FSM's paid transition fans out to the earn rules fire-and-forget, deduped on the order id so a re-delivered payment webhook never double-credits. At checkout a signed-in customer can spend points for a credit against the order total — valued by the redemption ratio (100 points = $1 default), capped at the order's worth and the balance, debited once behind a balance-guarded SQL decrement, stacking with any gift-card credit; surplus points stay in the balance. |
 | **`lib/referrals.js`** + **`lib/referral-leaderboard.js`** | Refer-a-friend with two-sided rewards. `referrals` issues each customer an 8-character code (32-glyph confusion-resistant alphabet via `b.crypto.generateBytes`) and tracks each referred friend through the funnel (invited → visited → joined → converted); referred emails are stored hash-only (`b.crypto.namespaceHash`), never plaintext. `referral-leaderboard` sits on top for top-referrer rankings + operator-tunable tier bonuses. Customers see all of it at `/account/referrals` — their code, an absolute shareable link, the friends they've referred (funnel stage + dates, no personal data), and an in-account leaderboard (rank + initials only). A public `/r/<code>` landing captures an inbound referral into a short-lived sealed first-party cookie (first-touch), which attributes the new customer to the referrer when they sign up by passkey / Google / Apple — self-referral and double-attribution guarded. When a referred customer's first order reaches paid, the order FSM's paid transition marks that referral converted and bumps the referrer's count fire-and-forget, deduped on the order id so a re-delivered webhook never double-counts; guest orders and a customer's later orders don't qualify. Issuing the payout itself (gift card / store credit / loyalty points) is an explicit operator action via the referrals reward API, so the reward instrument and any fraud review stay the operator's. |
 | **`lib/product-compare.js`** | Side-by-side product comparison, no sign-in required. Each product page gets an "Add to compare" / "Remove from compare" control; `POST /compare/toggle` adds or removes the product and `GET /compare` renders the comparison table — image, price, availability, and the per-product attributes resolved through the catalog. The basket is keyed on the visitor's existing sealed session cookie (a signed-in shopper's customer id rides alongside), capped at four products (a fifth add is refused with a notice rather than silently dropping one), and is idempotent. Products that go archived or out of stock resolve out of the table with a remove control instead of breaking the render; an empty basket shows a friendly empty state. `POST /compare/clear` empties it. Linked from the footer on every page. |
 | **`lib/bundles.js`** | Sell products together at a set price. A product page shows the bundles it belongs to as a "Bundle & save" offer — the member products, the bundle price, and the saving against the parts. `POST /cart/bundle` adds the whole bundle in one action: the price is recomputed from the live catalog and allocated across the member lines (proportional to list price, remainder on the last line) so the cart subtotal matches the quoted price. The add is atomic — an archived or out-of-stock member shows the bundle unavailable and adds nothing rather than a partial set; an unpriceable bundle (missing member price / currency mismatch) is shown unavailable, never a 500. The client sends only the bundle code; the server prices it. The offer renders identically from the edge worker and the container. |

package/SECURITY.md

@@ -319,15 +319,18 @@ 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 and store-credit ledgers are hash-chained, fork-proof,
-  and verifiable.** Every ledger entry — credits, debits, and
+- **The gift-card, store-credit, and loyalty 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
+  keyed per card (gift cards) or per customer (store credit, loyalty), 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, and each loyalty / gift-card /
+  store-credit balance change is written in that same single guarded row,
+  so a points or balance mutation is exactly-once even on a backend without
+  interactive transactions. `giftCardLedger.verifyChain(cardId)` /
+  `storeCredit.verifyChain(customerId)` / `loyalty.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

package/lib/asset-manifest.json

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

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 (!b.sql.casWon(dec).won) {
-        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,
       };
     },
 
@@ -396,13 +540,22 @@ function create(opts) {
       );
       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 };
     },
 
@@ -475,18 +628,24 @@ function create(opts) {
         );
         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 (!b.sql.casWon(upd).won) {
+      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 };
+    },
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/blamejs-shop",
-  "version": "0.4.104",
+  "version": "0.4.105",
   "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": {