@blamejs/blamejs-shop 0.4.23 → 0.4.25

package/lib/inventory-receive.js

@@ -78,6 +78,43 @@ var MAX_LIST_LIMIT  = 200;
 var RECEIPT_STATUSES = Object.freeze(["pending", "applied", "reversed"]);
 var RECEIPT_ORDER_KEY = ["received_at:desc", "id:desc"];
 
+// The receipt lifecycle, modelled on b.fsm — the same composition the order /
+// quote / stock-transfer primitives use. The FSM is the single source of truth
+// for which (status, event) pairs are legal:
+//
+//   apply    pending -> applied    (apply; restocks every line)
+//   reverse  applied -> reversed   (reverse; decrements every line back out)
+//
+// Terminal (reversed) declares no outgoing edge, so the machine itself refuses
+// a reverse-after-reverse. `apply` on an already-'applied' receipt is a
+// documented IDEMPOTENT no-op (returns { applied_count: 0 }) — apply() short-
+// circuits to that no-op before consulting the machine, preserving the
+// replay-safe contract callers depend on.
+var RECEIPT_TRANSITIONS = Object.freeze([
+  { from: "pending", to: "applied",  on: "apply" },
+  { from: "applied", to: "reversed", on: "reverse" },
+]);
+
+var _receiptFsm = null;
+function _getReceiptFsm() {
+  if (_receiptFsm) return _receiptFsm;
+  try { b.audit.registerNamespace("fsm"); } catch (_e) { /* idempotent; ignore */ }
+  _receiptFsm = b.fsm.define({
+    name:    "inventory_receipt",
+    initial: "pending",
+    states:  { pending: {}, applied: {}, reversed: {} },
+    transitions: RECEIPT_TRANSITIONS.map(function (t) {
+      return { from: t.from, to: t.to, on: t.on };
+    }),
+  });
+  return _receiptFsm;
+}
+
+function _canReceipt(fromStatus, event) {
+  var fsm = _getReceiptFsm();
+  return fsm.restore({ state: fromStatus, history: [], context: {} }).can(event);
+}
+
 // ---- validators ---------------------------------------------------------
 
 function _id(s, label) {
@@ -293,13 +330,32 @@ function create(opts) {
       if (!receipt) {
         throw new TypeError("inventory-receive.apply: receipt " + receiptId + " not found");
       }
-      if (receipt.status === "applied") {
-        // Idempotent — caller can replay without surprise.
-        return { id: receiptId, applied_count: 0, stock_changes: [] };
-      }
-      if (receipt.status !== "pending") {
+      // Preserve the idempotent no-op on an already-'applied' receipt: the
+      // FSM has no apply edge out of 'applied', so short-circuit here BEFORE
+      // asserting the transition (regression-safe replay contract — callers
+      // replay apply() without surprise).
+      if (!_canReceipt(receipt.status, "apply")) {
+        if (receipt.status === "applied") {
+          return { id: receiptId, applied_count: 0, stock_changes: [] };
+        }
         throw new TypeError("inventory-receive.apply: receipt is " + receipt.status + ", only pending receipts can be applied");
       }
+      // Claim the pending -> applied transition atomically BEFORE restocking.
+      // Two concurrent applies both pass the read above, but only one UPDATE
+      // matches `status = 'pending'`; the loser sees rowCount 0 and returns the
+      // idempotent no-op instead of double-restocking the catalog. (Without
+      // this guard both calls would restock every line, inflating
+      // stock_on_hand.)
+      var ts = _now();
+      var claim = await query(
+        "UPDATE inventory_receipts SET status = 'applied', updated_at = ?1 WHERE id = ?2 AND status = 'pending'",
+        [ts, receiptId],
+      );
+      if (Number(claim.rowCount || 0) !== 1) {
+        // A concurrent call won the claim and is restocking (or already did).
+        // Replay-safe no-op so the loser doesn't double-apply.
+        return { id: receiptId, applied_count: 0, stock_changes: [] };
+      }
       var stockChanges = [];
       var applied      = [];
       try {
@@ -310,8 +366,8 @@ function create(opts) {
           stockChanges.push({ sku: l.sku, qty: l.qty_received });
         }
       } catch (e) {
-        // Undo every successful restock so the database state matches
-        // the pre-apply snapshot. The receipt stays 'pending' so the
+        // Undo every successful restock so the database state matches the
+        // pre-apply snapshot, then release the claim back to 'pending' so the
         // operator can fix the offending line and retry.
         for (var j = applied.length - 1; j >= 0; j -= 1) {
           try {
@@ -321,15 +377,16 @@ function create(opts) {
             );
           } catch (_e3) { /* drop-silent — the original apply error is what the operator needs to fix */ }
         }
+        try {
+          await query(
+            "UPDATE inventory_receipts SET status = 'pending', updated_at = ?1 WHERE id = ?2 AND status = 'applied'",
+            [_now(), receiptId],
+          );
+        } catch (_e4) { /* drop-silent — the original apply error is the operator's signal */ }
         var err = new Error("inventory-receive.apply: restock failed — " + (e && e.message || e));
         err.cause = e;
         throw err;
       }
-      var ts = _now();
-      await query(
-        "UPDATE inventory_receipts SET status = 'applied', updated_at = ?1 WHERE id = ?2",
-        [ts, receiptId],
-      );
       return {
         id:            receiptId,
         applied_count: applied.length,
@@ -352,18 +409,55 @@ function create(opts) {
       if (!receipt) {
         throw new TypeError("inventory-receive.reverse: receipt " + receiptId + " not found");
       }
-      if (receipt.status !== "applied") {
+      if (!_canReceipt(receipt.status, "reverse")) {
         throw new TypeError("inventory-receive.reverse: receipt is " + receipt.status + ", only applied receipts can be reversed");
       }
+      // Claim the applied -> reversed transition atomically BEFORE decrementing.
+      // Two concurrent reverses both pass the read above, but only one UPDATE
+      // matches `status = 'applied'`; the loser refuses, so the shelf is
+      // decremented exactly once. (Without this guard both calls would
+      // decrement every line, destroying unrelated base stock.)
+      var claimTs = _now();
+      var claim = await query(
+        "UPDATE inventory_receipts SET status = 'reversed', updated_at = ?1 WHERE id = ?2 AND status = 'applied'",
+        [claimTs, receiptId],
+      );
+      if (Number(claim.rowCount || 0) !== 1) {
+        throw new TypeError("inventory-receive.reverse: receipt " + receiptId +
+          " is no longer applied (reversed by a concurrent call)");
+      }
       var stockChanges = [];
-      for (var i = 0; i < receipt.lines.length; i += 1) {
-        var l = receipt.lines[i];
-        var ts = _now();
+      var decremented  = [];
+      try {
+        for (var i = 0; i < receipt.lines.length; i += 1) {
+          var l = receipt.lines[i];
+          var ts = _now();
+          await query(
+            "UPDATE inventory SET stock_on_hand = MAX(0, stock_on_hand - ?1), updated_at = ?2 WHERE sku = ?3",
+            [l.qty_received, ts, l.sku],
+          );
+          decremented.push(l);
+          stockChanges.push({ sku: l.sku, qty: -l.qty_received });
+        }
+      } catch (e) {
+        // Compensate the decrements that already landed and release the claim so
+        // the receipt stays eligible for another reverse — otherwise a mid-loop
+        // failure strands it 'reversed' with only a partial stock rollback that
+        // the status check then refuses to retry.
+        for (var c = 0; c < decremented.length; c += 1) {
+          var dl = decremented[c];
+          try {
+            await query(
+              "UPDATE inventory SET stock_on_hand = stock_on_hand + ?1, updated_at = ?2 WHERE sku = ?3",
+              [dl.qty_received, _now(), dl.sku],
+            );
+          } catch (_compErr) { /* best-effort compensation; the claim release below restores retryability */ }
+        }
         await query(
-          "UPDATE inventory SET stock_on_hand = MAX(0, stock_on_hand - ?1), updated_at = ?2 WHERE sku = ?3",
-          [l.qty_received, ts, l.sku],
+          "UPDATE inventory_receipts SET status = 'applied', updated_at = ?1 WHERE id = ?2 AND status = 'reversed'",
+          [_now(), receiptId],
         );
-        stockChanges.push({ sku: l.sku, qty: -l.qty_received });
+        throw e;
       }
       // Append the reason into the receipt notes so the audit trail
       // carries the rationale. Operators that want a richer reversal
@@ -377,9 +471,11 @@ function create(opts) {
           newNotes = newNotes.slice(0, MAX_NOTES_LEN);
         }
       }
+      // Status was already flipped to 'reversed' by the atomic claim above;
+      // this write only stamps the reversal reason into the notes.
       var ts2 = _now();
       await query(
-        "UPDATE inventory_receipts SET status = 'reversed', notes = ?1, updated_at = ?2 WHERE id = ?3",
+        "UPDATE inventory_receipts SET notes = ?1, updated_at = ?2 WHERE id = ?3",
         [newNotes, ts2, receiptId],
       );
       return {

package/lib/inventory-writeoffs.js

@@ -530,41 +530,64 @@ function create(opts) {
         throw new TypeError("inventory-writeoffs.reverseWriteoff: writeoff " + id +
           " is " + row.status + ", only recorded writeoffs can be reversed");
       }
+      // A cost-impact attribution with costLayers unwired is an operator
+      // misconfiguration — refuse up front BEFORE claiming the row, so the
+      // claim only happens on a reversal we can actually complete.
+      if (row.cost_impact_minor != null && costLayers === null) {
+        throw new TypeError("inventory-writeoffs.reverseWriteoff: writeoff " + id +
+          " carries a cost-impact attribution but costLayers is not wired — " +
+          "rewire costLayers before reversing this row");
+      }
+
+      // Claim the recorded -> reversed transition atomically BEFORE restoring
+      // the shelf or the cost-layer pool. Two concurrent reverses both pass the
+      // read above, but only one UPDATE matches `status = 'recorded'`; the
+      // loser refuses, so the shelf restore + cost-layer reversal each run
+      // exactly once. (Without this guard both calls would restore stock and
+      // record a cost-layer reversal, double-restoring.)
+      var ts = _now();
+      var claim = await query(
+        "UPDATE inventory_writeoffs SET status = 'reversed', reversed_at = ?1, " +
+        "reverse_reason = ?2 WHERE id = ?3 AND status = 'recorded'",
+        [ts, reason, id],
+      );
+      if (Number(claim.rowCount || 0) !== 1) {
+        throw new TypeError("inventory-writeoffs.reverseWriteoff: writeoff " + id +
+          " is no longer recorded (reversed by a concurrent call)");
+      }
+
+      // Compensating release of the claim — flips the row back to 'recorded'
+      // so the operator can retry once they've fixed the side-effect failure.
+      async function _releaseClaim() {
+        try {
+          await query(
+            "UPDATE inventory_writeoffs SET status = 'recorded', reversed_at = NULL, " +
+            "reverse_reason = NULL WHERE id = ?1 AND status = 'reversed'",
+            [id],
+          );
+        } catch (_e0) { /* drop-silent — the side-effect error is the operator's signal */ }
+      }
+
       // Restore the shelf. Mirrors the recordWriteoff logic: when
       // location_code is null the original write-off didn't touch a
       // specific shelf, so nothing to restore.
       if (row.location_code != null) {
-        await locations.adjustStock({
-          sku:           row.sku,
-          location_code: row.location_code,
-          delta:         row.quantity,
-          reason:        "writeoff:reverse:" + id,
-        });
+        try {
+          await locations.adjustStock({
+            sku:           row.sku,
+            location_code: row.location_code,
+            delta:         row.quantity,
+            reason:        "writeoff:reverse:" + id,
+          });
+        } catch (e1) {
+          await _releaseClaim();
+          throw e1;
+        }
       }
-      // Restore the cost layer pool when the original write-off
-      // attributed COGS. costLayers may have been unwired since the
-      // original write-off — the operator gets a clear refusal in
-      // that case rather than a silent skip that desynchronizes the
-      // shelf from the cost ledger.
+      // Restore the cost layer pool when the original write-off attributed
+      // COGS. On failure, undo the shelf restore + release the claim so the
+      // operator sees a clean refusal rather than a half-applied reversal.
       if (row.cost_impact_minor != null) {
-        if (costLayers === null) {
-          // Compensating action: undo the shelf restore so the
-          // operator sees a clean refusal rather than a half-applied
-          // reversal.
-          if (row.location_code != null) {
-            try {
-              await locations.adjustStock({
-                sku:           row.sku,
-                location_code: row.location_code,
-                delta:         -row.quantity,
-                reason:        "writeoff:reverse:rollback:" + id,
-              });
-            } catch (_e1) { /* drop-silent — original refusal is the operator's signal */ }
-          }
-          throw new TypeError("inventory-writeoffs.reverseWriteoff: writeoff " + id +
-            " carries a cost-impact attribution but costLayers is not wired — " +
-            "rewire costLayers before reversing this row");
-        }
         try {
           await costLayers.recordReversal({
             order_id: "writeoff:" + id,
@@ -582,44 +605,10 @@ function create(opts) {
               });
             } catch (_e2) { /* drop-silent — the costLayers error is the operator's signal */ }
           }
+          await _releaseClaim();
           throw e;
         }
       }
-      var ts = _now();
-      try {
-        await query(
-          "UPDATE inventory_writeoffs SET status = 'reversed', reversed_at = ?1, " +
-          "reverse_reason = ?2 WHERE id = ?3",
-          [ts, reason, id],
-        );
-      } catch (e3) {
-        if (row.cost_impact_minor != null && costLayers !== null) {
-          // Best-effort compensating: re-consume the cost layer so
-          // the cost ledger doesn't sit in a contradictory state.
-          // Failure here is drop-silent because the original DB
-          // error is what the operator needs to fix; the audit row
-          // on cost_layers still tells the story.
-          try {
-            await costLayers.consumeForSale({
-              sku:      row.sku,
-              quantity: row.quantity,
-              order_id: "writeoff:" + id,
-              line_id:  "1",
-            });
-          } catch (_e4) { /* drop-silent — original DB error is the operator's signal */ }
-        }
-        if (row.location_code != null) {
-          try {
-            await locations.adjustStock({
-              sku:           row.sku,
-              location_code: row.location_code,
-              delta:         -row.quantity,
-              reason:        "writeoff:reverse:rollback:" + id,
-            });
-          } catch (_e5) { /* drop-silent — original DB error is the operator's signal */ }
-        }
-        throw e3;
-      }
       return await _getWriteoffRow(id);
     },
   };

package/lib/loyalty-earn-rules.js

@@ -753,6 +753,122 @@ function create(opts) {
     return { reversed_points: earned, clawed_points: clawed };
   }
 
+  // ---- reverseForEventProRata -----------------------------------------
+
+  // Claw back earned points PROPORTIONALLY to a partial refund — the
+  // refund-by-amount counterpart to reverseForEvent's all-or-nothing (cancel)
+  // claw. A full refund claws every awarded point; a partial refund must claw
+  // only the share the refund covers, or a 10%-refunded order claws 100% of
+  // the points the buyer legitimately earned on the 90% they kept.
+  //
+  // For each award row the target cumulative claw is
+  // floor(points_awarded * refunded_minor / order_total_minor), clamped to
+  // points_awarded. The claw is the delta vs `clawed_points` (the cumulative
+  // already clawed), advanced under a guarded UPDATE keyed on the row's live
+  // value so a concurrent double-fire can't double-claw. A row that reaches
+  // full claw also stamps reversed_at so the binary reverseForEvent treats it
+  // as done. The total delta is then taken off the running balance, floored at
+  // zero (a customer may have spent the points) with the same
+  // re-read-and-retry on a concurrent-spend underflow as reverseForEvent.
+  //
+  // Idempotent + a natural no-op for an order that earned nothing or one
+  // already clawed to the requested proportion. Returns
+  // { reversed_points, clawed_points }: reversed_points is the delta targeted
+  // this call; clawed_points is what actually came off the balance.
+  async function reverseForEventProRata(input) {
+    if (!input || typeof input !== "object") {
+      throw new TypeError("loyaltyEarnRules.reverseForEventProRata: input object required");
+    }
+    var customerId      = _uuid(input.customer_id, "customer_id");
+    var triggerEventRef = _triggerEventRef(input.trigger_event_ref);
+    var refundedMinor   = input.refunded_minor;
+    var orderTotalMinor = input.order_total_minor;
+    if (typeof refundedMinor !== "number" || !Number.isInteger(refundedMinor) || refundedMinor < 0) {
+      throw new TypeError("loyaltyEarnRules.reverseForEventProRata: refunded_minor must be a non-negative integer (minor units)");
+    }
+    if (typeof orderTotalMinor !== "number" || !Number.isInteger(orderTotalMinor) || orderTotalMinor <= 0) {
+      throw new TypeError("loyaltyEarnRules.reverseForEventProRata: order_total_minor must be a positive integer (minor units)");
+    }
+    var effRefunded = refundedMinor > orderTotalMinor ? orderTotalMinor : refundedMinor;
+
+    var rows = (await query(
+      "SELECT id, points_awarded, clawed_points FROM loyalty_earn_log " +
+      "WHERE customer_id = ?1 AND trigger_event_ref = ?2",
+      [customerId, triggerEventRef],
+    )).rows;
+
+    // First pass: claim the proportional delta on each award row. The
+    // guarded UPDATE (clawed_points = expected-prior) serializes a concurrent
+    // double-fire so a slice is claimed once. Sum the claimed deltas — that's
+    // what comes off the balance below.
+    var toClaw = 0;
+    var claimedRows = [];
+    for (var i = 0; i < rows.length; i += 1) {
+      var row = rows[i];
+      var awarded = Number(row.points_awarded || 0);
+      if (awarded <= 0) continue;
+      var already = Number(row.clawed_points || 0);
+      var target  = Math.floor((awarded * effRefunded) / orderTotalMinor);
+      if (target > awarded) target = awarded;
+      var delta = target - already;
+      if (delta <= 0) continue;
+      var ts = _now();
+      var nowFull = target >= awarded;
+      var claim = await query(
+        "UPDATE loyalty_earn_log SET clawed_points = ?1, " +
+        "reversed_at = CASE WHEN ?2 = 1 THEN ?3 ELSE reversed_at END " +
+        "WHERE id = ?4 AND clawed_points = ?5",
+        [target, nowFull ? 1 : 0, ts, row.id, already],
+      );
+      if (Number(claim.rowCount || 0) === 0) continue;   // lost the claim
+      toClaw += delta;
+      claimedRows.push({ id: row.id, delta: delta, prior: already });
+    }
+    if (toClaw <= 0) {
+      return { reversed_points: 0, clawed_points: 0 };
+    }
+
+    // Take the claimed total off the running balance, floored at zero, same
+    // re-read-and-retry discipline as reverseForEvent. On a non-floor failure
+    // release the claimed slices so a later reversal can re-attempt, then
+    // surface the original error.
+    var clawed = 0;
+    if (loyaltyHandle && typeof loyaltyHandle.adjust === "function"
+        && typeof loyaltyHandle.balance === "function") {
+      try {
+        for (var attempt = 0; attempt < 3; attempt += 1) {
+          var bal = await loyaltyHandle.balance(customerId);
+          var claw = Math.min(toClaw, Number((bal && bal.balance) || 0));
+          if (claw <= 0) break;
+          try {
+            await loyaltyHandle.adjust({
+              customer_id: customerId,
+              points:      -claw,
+              source:      "earn-reversal",
+              notes:       "reversed ref=" + triggerEventRef + " partial",
+            });
+            clawed = claw;
+            break;
+          } catch (err) {
+            if (!(err && err.code === "LOYALTY_INSUFFICIENT_BALANCE")) throw err;
+          }
+        }
+      } catch (clawErr) {
+        for (var r = 0; r < claimedRows.length; r += 1) {
+          try {
+            await query(
+              "UPDATE loyalty_earn_log SET clawed_points = ?1, reversed_at = NULL WHERE id = ?2",
+              [claimedRows[r].prior, claimedRows[r].id],
+            );
+          } catch (_releaseErr) { /* drop-silent — the original failure is the signal */ }
+        }
+        throw clawErr;
+      }
+    }
+
+    return { reversed_points: toClaw, clawed_points: clawed };
+  }
+
   // ---- metricsForRule -------------------------------------------------
 
   async function metricsForRule(input) {
@@ -873,6 +989,7 @@ function create(opts) {
     evaluateForEvent:  evaluateForEvent,
     awardForEvent:     awardForEvent,
     reverseForEvent:   reverseForEvent,
+    reverseForEventProRata: reverseForEventProRata,
     metricsForRule:    metricsForRule,
     applyBatch:        applyBatch,
   };

package/lib/loyalty.js

@@ -346,6 +346,85 @@ function create(opts) {
       };
     },
 
+    // Restore points a customer SPENT as a checkout tender when the order
+    // that spent them is refunded — the symmetric counterpart to the
+    // gift-card-spend restore. `redeem` debited the balance at checkout
+    // against `order_id`; a refund returns money to the buyer, so the points
+    // they tendered have to come back to their balance or the refund silently
+    // burns them (inconsistent with the gift-card spend, which IS restored).
+    //
+    // PROPORTIONAL to the refund: the target cumulative restore per redeem row
+    // is floor(spent_points * refunded_minor / order_total_minor), clamped to
+    // the points spent, so a partial refund restores only the covered share
+    // and a partial-then-final sequence converges exactly on the points spent.
+    // The credit is the delta vs `restored_points` (the cumulative already
+    // restored), advanced under a guarded UPDATE keyed on the row's live value
+    // so a concurrent double-fire can't double-restore. Balance only —
+    // lifetime is NOT touched (redeem never decremented it, so the restore
+    // mustn't inflate it and retroactively promote a tier). A new positive
+    // `redeem` ledger row records each restore so the audit trail nets to the
+    // un-refunded spend.
+    //
+    // Idempotent + a natural no-op for an order that tendered no points (no
+    // redeem rows) or one already restored to the requested proportion.
+    // Returns { restored_points } — the points credited back this call.
+    restoreRedemption: async function (orderId, input) {
+      var oid = _uuid(orderId, "order_id");
+      input = input || {};
+      var refundedMinor   = input.refunded_minor;
+      var orderTotalMinor = input.order_total_minor;
+      if (typeof refundedMinor !== "number" || !Number.isInteger(refundedMinor) || refundedMinor < 0) {
+        throw new TypeError("loyalty.restoreRedemption: refunded_minor must be a non-negative integer (minor units)");
+      }
+      if (typeof orderTotalMinor !== "number" || !Number.isInteger(orderTotalMinor) || orderTotalMinor <= 0) {
+        throw new TypeError("loyalty.restoreRedemption: order_total_minor must be a positive integer (minor units)");
+      }
+      var effRefunded = refundedMinor > orderTotalMinor ? orderTotalMinor : refundedMinor;
+
+      var rows = (await query(
+        "SELECT id, customer_id, points, restored_points FROM loyalty_transactions " +
+        "WHERE order_id = ?1 AND transaction_type = 'redeem'",
+        [oid],
+      )).rows;
+      var restoredTotal = 0;
+      for (var i = 0; i < rows.length; i += 1) {
+        var row = rows[i];
+        // `points` on a redeem row is the NEGATIVE delta; the spend is its
+        // magnitude.
+        var spent = Math.abs(Number(row.points || 0));
+        if (spent <= 0) continue;
+        var already = Number(row.restored_points || 0);
+        var target  = Math.floor((spent * effRefunded) / orderTotalMinor);
+        if (target > spent) target = spent;
+        var delta = target - already;
+        if (delta <= 0) continue;
+        var ts = _now();
+        // Claim the slice: advance restored_points from its expected prior
+        // value so a concurrent restore can't double-credit.
+        var claim = await query(
+          "UPDATE loyalty_transactions SET restored_points = ?1 " +
+          "WHERE id = ?2 AND restored_points = ?3",
+          [target, row.id, already],
+        );
+        if (Number(claim.rowCount || 0) === 0) 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);
+        restoredTotal += delta;
+      }
+      return { restored_points: restoredTotal };
+    },
+
     adjust: async function (input) {
       if (!input || typeof input !== "object") {
         throw new TypeError("loyalty.adjust: input object required");

package/lib/newsletter.js

@@ -30,7 +30,10 @@
  *   - `consumeUnsubscribeToken(plaintext)` — single-use exchange.
  *     Marks the token consumed and stamps
  *     `newsletter_signups.unsubscribed_at` for the linked signup.
- *     Returns a structured result with one of the error codes
+ *     When an `emailSuppressions` handle is wired into `create`, it
+ *     also adds the address to the marketing-scope suppression list
+ *     so every other marketing flow honours the opt-out. Returns a
+ *     structured result with one of the error codes
  *     `"not-found" | "already-consumed" | "expired"`, or `"ok"`
  *     on success.
  *   - `resubscribe({ email })` — clears `unsubscribed_at` for an
@@ -115,6 +118,18 @@ function create(opts) {
     query = function (sql, params) { return b.externalDb.query(sql, params); };
   }
 
+  // Optional marketing-suppression handle. When wired, an unsubscribe
+  // feeds the suppression list (marketing scope) so EVERY other
+  // marketing flow — wishlist alerts, abandoned-cart, review requests —
+  // honours the opt-out, not just the newsletter broadcast that reads
+  // `unsubscribed_at` directly. Without it the unsubscribe still stamps
+  // `unsubscribed_at` (newsletter broadcasts respect that), but the
+  // suppression list is the single source of truth other flows consult.
+  var emailSuppressions = opts.emailSuppressions || null;
+  if (emailSuppressions && typeof emailSuppressions.add !== "function") {
+    throw new TypeError("newsletter.create: opts.emailSuppressions must expose add when wired");
+  }
+
   return {
     EMAIL_NAMESPACE: EMAIL_NAMESPACE,
 
@@ -258,9 +273,31 @@ function create(opts) {
         [now, row.signup_id],
       );
       var signup = (await query(
-        "SELECT email_hash FROM newsletter_signups WHERE id = ?1 LIMIT 1",
+        "SELECT email_hash, email_normalized FROM newsletter_signups WHERE id = ?1 LIMIT 1",
         [row.signup_id],
       )).rows[0];
+
+      // Feed the suppression list so every OTHER marketing flow (wishlist
+      // alerts, abandoned-cart, review requests) stops mailing this
+      // address — not just the newsletter broadcast that reads
+      // `unsubscribed_at`. The signup row persists the plaintext
+      // `email_normalized` precisely so the operator can act on the
+      // address; pass it through verbatim. Best-effort: a suppression
+      // write failure must not turn a successful unsubscribe into an
+      // error page — the `unsubscribed_at` stamp already landed and the
+      // broadcast path honours it.
+      if (emailSuppressions && signup && typeof signup.email_normalized === "string" && signup.email_normalized.length) {
+        try {
+          await emailSuppressions.add({
+            email:            signup.email_normalized,
+            suppression_type: "unsubscribe",
+            scope:            "marketing",
+            source:           "newsletter-unsubscribe",
+            reason:           "one-click unsubscribe",
+          });
+        } catch (_eSup) { /* drop-silent — unsubscribe already committed */ }
+      }
+
       return {
         ok:         true,
         error:      "ok",

package/lib/operator-audit-log.js

@@ -309,6 +309,20 @@ function create(opts) {
     query = function (sql, params) { return b.externalDb.query(sql, params); };
   }
 
+  // Single-writer discipline for the append path. `record()` reads the
+  // chain head, derives prev_hash + row_hash from it, then INSERTs — a
+  // read-derive-write sequence that is NOT atomic across the three
+  // awaits. Two concurrent record() calls would otherwise both read the
+  // same head, both stamp the same prev_hash, and fork the chain — which
+  // verifyChain() then reports as a prev_hash mismatch, indistinguishable
+  // from a real tamper. Serializing the whole body behind a per-instance
+  // mutex collapses the window: the second writer blocks until the first
+  // has committed its row, so it reads the freshly-advanced head. In-
+  // process only — it narrows the fork window to a single isolate, the
+  // same bound the framework chain primitive carries; the checkpoint
+  // anchoring below remains the cross-isolate / full-rewrite defense.
+  var appendMutex = new b.safeAsync.Mutex();
+
   async function _currentHead() {
     var r = await query(
       "SELECT row_hash, occurred_at, id FROM operator_audit_events " +
@@ -331,6 +345,8 @@ function create(opts) {
     if (!input || typeof input !== "object") {
       throw new TypeError("operatorAuditLog.record: input object required");
     }
+    // Validate OUTSIDE the lock — a bad-input throw shouldn't hold the
+    // append serializer, and validation touches no shared chain state.
     var actorType    = _actorType(input.actor_type);
     var actorId      = _ident(input.actor_id,      "actor_id",      IDENT_RE, MAX_ACTOR_ID_LEN);
     var action       = _ident(input.action,        "action",        ACTION_RE, MAX_ACTION_LEN);
@@ -341,6 +357,9 @@ function create(opts) {
     var ipHash       = _ipHash(input.ip_hash);
     var uaClass      = _uaClass(input.ua_class);
 
+    // Acquire the append mutex for the head-read → hash → INSERT body so
+    // the chain advances under a single writer.
+    return appendMutex.runExclusive(async function () {
     var head      = await _currentHead();
     var prevHash  = head.row_hash;
     var id        = b.uuid.v7();
@@ -398,6 +417,7 @@ function create(opts) {
       prev_hash:     prevHash,
       row_hash:      rowHash,
     };
+    });
   }
 
   // -- listByActor -------------------------------------------------------