@blamejs/blamejs-shop 0.4.18 → 0.4.19

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.4.x
 
+- v0.4.19 (2026-06-06) — **Wishlist alerts fire once per event instead of repeating daily, stale digests catch up with a single email, and webhook delivery stops throttling itself.** A set of notification and delivery fixes. Back-in-stock and price-drop wishlist alerts now fire only when something actually changes — a steadily in-stock item no longer re-alerts every day. A wishlist digest whose schedule fell behind sends one catch-up email instead of one per minute until current. Outbound webhook delivery no longer counts its own rate-limit refusals against the limit (which kept the throttle tripped once hit), retrying an exhausted delivery no longer duplicates its dead-letter record, and the blog RSS feed renders correctly when a post title or body contains dollar-sign sequences. **Fixed:** *Back-in-stock and price-drop alerts fire on the change, not the state* — The wishlist alert sweep evaluated the current state of each item, so anything in stock re-alerted every wishlister on every sweep — the daily dedupe window just made the flood daily. Alerts now track the last-observed state per customer and item: back-in-stock fires only on an out-of-stock-to-in-stock transition, price-drop only when the price falls below the level already alerted, and a recovered price re-arms the alert. A steadily in-stock item never re-fires. The weekly cap and dedupe are also enforced atomically, so two overlapping sweeps can't double-send past the cap. · *A stale digest enrollment catches up with one email* — A wishlist digest whose next-send time had fallen far behind advanced one period per scheduler tick and sent an email each time — a subscriber could receive dozens of digests in an hour while the schedule caught up. Catching up now snaps the schedule to the present and sends at most one digest. · *Webhook delivery rate limiting no longer feeds on its own refusals* — The outbound webhook rate-limit gate counted its own refusal records toward the limit, so once an endpoint tripped the throttle it could stay tripped indefinitely, and every suppressed attempt persisted another row. Refusals are no longer counted by the gate and collapse to a single record per endpoint per window. · *Retrying an exhausted webhook delivery is idempotent* — Manually retrying a delivery that had already exhausted its attempts inserted a fresh dead-letter record on every click. Retry of an exhausted or already-delivered delivery now answers as a clean no-op, and the dead-letter table enforces one record per delivery. · *The RSS feed renders posts containing dollar-sign sequences* — The feed assembled items with a plain string replacement, which gives `$` sequences special meaning — a post title or body containing a dollar sign followed by a backtick or ampersand could corrupt the entire feed XML. The feed now uses the same literal splice the page renderers use. The feed's author field also no longer exposes an internal identifier; it carries the shop name, matching the blog pages.
+
 - v0.4.18 (2026-06-06) — **Staff accounts: per-operator credentials with owner, manager, and viewer roles — the shared admin key becomes break-glass.** The admin console gains multi-operator support. Create staff accounts at the new Operators screen, each with its own password and optional API key, and assign a least-privilege role: owner (everything, including operator management), manager (catalog, orders, customers, marketing), or viewer (read-only). Role enforcement happens at the admin write layer on every state-changing request — a viewer is refused the write itself, not just the menu link. The shared ADMIN_API_KEY keeps working as the bootstrap and break-glass owner credential, so upgrading can never lock a store out; once staff accounts exist, treat it like a recovery key. **Added:** *Operators console with per-operator credentials* — `/admin/operators` creates and disables staff accounts. Each operator gets their own password (Argon2id) and optionally a personal API key for the JSON surface, shown once at creation. The screen lists who created each operator and when; disabling one takes effect on their very next request — the signed-in session re-reads the live account row, so there is no revocation lag. · *Owner / manager / viewer roles, enforced on the write itself* — Every admin mutation passes a single permission gate keyed to the action being performed: owner holds every permission including operator management and settings; manager covers catalog, orders, customers, and marketing; viewer holds none — every POST, PUT, and DELETE is refused with a 403, regardless of how the request arrives (browser form or bearer JSON). Read screens remain available to any authenticated operator. Role-denied attempts are recorded in the audit chain alongside every operator-management action. · *Bootstrap and break-glass: the shared key still works* — `ADMIN_API_KEY` resolves to the owner role exactly as before — a store with no operator rows behaves identically to the previous release, and the first staff account is created while signed in with the shared key. Unknown sign-in attempts burn a real password verification against a fixed dummy hash, so response timing does not reveal whether an account exists.
 
 - v0.4.17 (2026-06-06) — **Email campaigns: consent-gated broadcasts to the newsletter list, with one-click unsubscribe and a send ledger that never re-mails.** The admin console gains an Email campaigns screen: author a broadcast, target a mailing audience, preview it, test-send to yourself, and send. Consent is the design center — the recipient set resolves at send time from the newsletter list (the only place a deliverable address exists; customer accounts keep only an email hash), every recipient is re-checked against the unsubscribe flag and the marketing suppression list at the moment their message sends, and every message carries one-click unsubscribe headers plus an in-body link. Sending drains in rate-bounded batches on the scheduled tick, one bad address never aborts a campaign, and a per-recipient ledger makes a resumed send never deliver twice. **Added:** *Campaign console: author, preview, test-send, send* — `/admin/campaigns` lists campaigns with status and delivered / failed / skipped counts, and a campaign editor takes a subject and a Markdown-or-plaintext body. The body renders escape-by-default with an https-only link gate — the same rendering discipline as the blog — so markup or script in a body lands as inert text in the inbox and in the console list. Preview and an operator-addressed test send are available before any real send. · *Consent resolved per recipient, at the send moment* — The reachable-recipient count shown before sending is computed live from the newsletter list, excluding anyone unsubscribed or on the marketing suppression list — and the same two checks run again for each recipient at the moment their message sends, so someone who unsubscribes mid-broadcast is skipped. Customer accounts keep only an email hash by design, so the newsletter list is the only deliverable-address source and the console says exactly how many recipients are reachable. · *One-click unsubscribe on every broadcast* — Every campaign message carries the RFC 8058 `List-Unsubscribe` / `List-Unsubscribe-Post` headers (so mail clients show their native unsubscribe control), an RFC 2919 `List-Id`, and an in-body unsubscribe link through the existing newsletter opt-out flow. · *Rate-bounded, resumable sending* — Sends drain in batches on the scheduled tick with a reserved hourly budget, so a large campaign spreads out rather than bursting. Each recipient's outcome lands in a send ledger keyed uniquely per campaign and recipient — a send interrupted by the rate budget or a restart resumes where it left off and never mails anyone twice. A failing address is counted and shown, never fatal to the rest of the campaign.

package/lib/asset-manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.4.18",
+  "version": "0.4.19",
   "assets": {
     "css/admin.css": {
       "integrity": "sha384-6k53cvkRrxMgmeStLIoLjVXZQHqIJgTmv1Izd8TYhh1HOC4POgE6GCvx1bsalyEP",

package/lib/webhooks.js

@@ -214,27 +214,59 @@ function create(opts) {
     return await _attempt(deliveryId, endpointRow, eventType, payloadJson);
   }
 
+  // The marker a refusal row carries in `last_error`. Rows bearing it are
+  // EXCLUDED from the rate-limit count — a refusal is the gate's own
+  // output, not a real delivery, so counting it would let the gate
+  // perpetuate its own throttle: once tripped, the refusal rows alone keep
+  // the window "full" and every subsequent send is refused forever even
+  // after the real deliveries age out.
+  var RATE_LIMITED_MARKER = "rate-limited";
+
   async function _checkRateLimit(endpointRow) {
     var limit = endpointRow.rate_limit_per_minute;
     if (typeof limit !== "number" || !isFinite(limit) || limit <= 0) return true;
     var windowStart = nowFn() - RATE_WINDOW_MS;
     var r = await query(
-      "SELECT count(*) AS n FROM webhook_deliveries WHERE endpoint_id = ?1 AND created_at > ?2",
-      [endpointRow.id, windowStart],
+      "SELECT count(*) AS n FROM webhook_deliveries " +
+      "WHERE endpoint_id = ?1 AND created_at > ?2 " +
+      "AND (last_error IS NULL OR last_error != ?3)",
+      [endpointRow.id, windowStart, RATE_LIMITED_MARKER],
     );
     var n = (r.rows[0] && (r.rows[0].n != null ? r.rows[0].n : r.rows[0]["count(*)"])) || 0;
     return n < limit;
   }
 
+  // Surface a single refusal row per endpoint per window so the operator
+  // sees the throttle in the admin feed — but DON'T grow the table by one
+  // row per suppressed attempt. A flood of suppressed events against a
+  // wedged receiver would otherwise write unbounded refusal rows. When a
+  // recent refusal row already exists for this endpoint, refresh its
+  // last_attempted_at (collapse) instead of inserting another.
   async function _persistRateLimited(endpointRow, eventType, payloadJson) {
-    var deliveryId = b.uuid.v7();
     var ts = nowFn();
+    var windowStart = ts - RATE_WINDOW_MS;
+    var existing = await query(
+      "SELECT id FROM webhook_deliveries " +
+      "WHERE endpoint_id = ?1 AND last_error = ?2 AND created_at > ?3 " +
+      "ORDER BY created_at DESC LIMIT 1",
+      [endpointRow.id, RATE_LIMITED_MARKER, windowStart],
+    );
+    if (existing.rows[0]) {
+      var existingId = existing.rows[0].id;
+      await query(
+        "UPDATE webhook_deliveries SET last_attempted_at = ?1, event_type = ?2, payload_json = ?3 " +
+        "WHERE id = ?4",
+        [ts, eventType, payloadJson, existingId],
+      );
+      return await _getDelivery(existingId);
+    }
+    var deliveryId = b.uuid.v7();
     await query(
       "INSERT INTO webhook_deliveries " +
       "(id, endpoint_id, event_type, payload_json, attempts, last_status, last_error, " +
       " last_attempted_at, created_at) " +
       "VALUES (?1, ?2, ?3, ?4, 0, NULL, ?5, ?6, ?7)",
-      [deliveryId, endpointRow.id, eventType, payloadJson, "rate-limited", ts, ts],
+      [deliveryId, endpointRow.id, eventType, payloadJson, RATE_LIMITED_MARKER, ts, ts],
     );
     return await _getDelivery(deliveryId);
   }
@@ -311,6 +343,13 @@ function create(opts) {
     // per-endpoint feed still surfaces the failure. The DLQ row
     // carries the full payload so replayFromDlq can re-queue
     // without consulting the original delivery.
+    //
+    // Idempotent per delivery: the INSERT...SELECT writes only when no
+    // dead-letter row already exists for this delivery_id. Without it, a
+    // manual retry of an already-exhausted delivery dropped a duplicate
+    // DLQ row on every click. The migration 0215 UNIQUE(delivery_id) is
+    // the schema backstop; this guard avoids relying on a swallowed
+    // constraint error.
     var dlqId = b.uuid.v7();
     var firstAttemptedAt;
     var r = await query(
@@ -322,7 +361,8 @@ function create(opts) {
       "INSERT INTO webhook_dlq " +
       "(id, endpoint_id, delivery_id, event_type, payload_json, attempts, " +
       " last_status, last_error, first_attempted_at, last_attempted_at, dropped_at) " +
-      "VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)",
+      "SELECT ?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11 " +
+      "WHERE NOT EXISTS (SELECT 1 FROM webhook_dlq WHERE delivery_id = ?3)",
       [dlqId, endpointRow.id, deliveryId, eventType, payloadJson, attempts,
        lastStatus, lastError, firstAttemptedAt, ts, ts],
     );
@@ -443,6 +483,16 @@ function create(opts) {
         _uuid(deliveryId, "delivery id");
         var d = await _getDelivery(deliveryId);
         if (!d) return null;
+        // An exhausted delivery (attempts at/over the max) has already
+        // moved to the DLQ — re-attempting it would push attempts past the
+        // max and drop a DUPLICATE DLQ row on every click. Answer a no-op
+        // (return the row unchanged) so the operator UI shows the existing
+        // state; re-queuing an exhausted delivery is `replayFromDlq`, not
+        // `retry`. A successfully-delivered row is likewise a no-op.
+        var attempts = Number(d.attempts || 0);
+        if (attempts >= MAX_ATTEMPTS || d.delivered_at != null) {
+          return d;
+        }
         var endpoint = await _getEndpoint(d.endpoint_id);
         if (!endpoint) return null;
         return await _attempt(deliveryId, endpoint, d.event_type, d.payload_json);

package/lib/wishlist-alerts.js

@@ -550,16 +550,6 @@ function create(opts) {
 
   // ---- scanAndDispatch internals ----------------------------------------
 
-  async function _countAlertsThisWeek(customerId, now) {
-    var since = now - MS_PER_WEEK;
-    var r = await query(
-      "SELECT COUNT(*) AS n FROM wishlist_alerts_sent "
-      + "WHERE customer_id = ?1 AND occurred_at >= ?2",
-      [customerId, since],
-    );
-    return Number((r.rows[0] || {}).n || 0);
-  }
-
   async function _hasRecentFire(customerId, sku, policySlug, now) {
     var since = now - DEDUPE_WINDOW_MS;
     var r = await query(
@@ -571,6 +561,81 @@ function create(opts) {
     return r.rows.length > 0;
   }
 
+  // Last-observed state for a (customer, sku, policy) tuple — the memory
+  // that turns a current-state read into a transition read. NULL when the
+  // scanner has never seen this tuple.
+  async function _lastState(customerId, sku, policySlug) {
+    var r = await query(
+      "SELECT last_in_stock, last_alerted_bps FROM wishlist_alert_state "
+      + "WHERE customer_id = ?1 AND sku = ?2 AND policy_slug = ?3 LIMIT 1",
+      [customerId, sku, policySlug],
+    );
+    var row = r.rows[0];
+    if (!row) return { last_in_stock: null, last_alerted_bps: null };
+    return {
+      last_in_stock:    row.last_in_stock    == null ? null : Number(row.last_in_stock),
+      last_alerted_bps: row.last_alerted_bps == null ? null : Number(row.last_alerted_bps),
+    };
+  }
+
+  // Upsert the observed state for a tuple. Only the columns named in
+  // `patch` are written; the row's other column keeps its prior value
+  // (read once here so the UNIQUE-keyed REPLACE doesn't clobber the
+  // sibling column). `inStock` / `alertedBps` are 0/1/null and int/null.
+  async function _recordState(customerId, sku, policySlug, patch, now) {
+    var prior = await _lastState(customerId, sku, policySlug);
+    var inStock    = Object.prototype.hasOwnProperty.call(patch, "last_in_stock")
+      ? patch.last_in_stock
+      : prior.last_in_stock;
+    var alertedBps = Object.prototype.hasOwnProperty.call(patch, "last_alerted_bps")
+      ? patch.last_alerted_bps
+      : prior.last_alerted_bps;
+    // INSERT-or-UPDATE on the UNIQUE(customer_id, sku, policy_slug) key.
+    await query(
+      "INSERT INTO wishlist_alert_state "
+      + "(customer_id, sku, policy_slug, last_in_stock, last_alerted_bps, updated_at) "
+      + "VALUES (?1, ?2, ?3, ?4, ?5, ?6) "
+      + "ON CONFLICT (customer_id, sku, policy_slug) DO UPDATE SET "
+      + "last_in_stock = ?4, last_alerted_bps = ?5, updated_at = ?6",
+      [customerId, sku, policySlug, inStock, alertedBps, now],
+    );
+  }
+
+  // Atomic dedupe + weekly-cap CLAIM. Writes the sent-ledger row in a
+  // single conditional INSERT that refuses when (a) a fire for the same
+  // (customer, sku, policy) already landed inside the dedupe window, or
+  // (b) the customer is at/over the weekly cap. Because the guard and the
+  // write are one statement, two concurrent sweeps can't both pass the
+  // read and then both insert — the second's INSERT...SELECT sees the
+  // first's row and matches zero rows. Returns true when this call won
+  // the claim. Mirrors the conditional-UPDATE house pattern
+  // (catalog.inventory.adjustOnHand / hold).
+  async function _claimLedgerRow(id, customerId, policySlug, sku, now, weeklyCap) {
+    var dedupeSince = now - DEDUPE_WINDOW_MS;
+    var weekSince   = now - MS_PER_WEEK;
+    // `weeklyCap` null → no cap; encode as a sentinel the SQL treats as
+    // "always under cap" by comparing against a value the count can never
+    // reach when cap is absent.
+    var capActive = weeklyCap != null ? 1 : 0;
+    var capValue  = weeklyCap != null ? weeklyCap : 0;
+    var r = await query(
+      "INSERT INTO wishlist_alerts_sent (id, customer_id, policy_slug, sku, channel, occurred_at) "
+      + "SELECT ?1, ?2, ?3, ?4, 'email', ?5 "
+      + "WHERE NOT EXISTS ("
+      + "  SELECT 1 FROM wishlist_alerts_sent "
+      + "  WHERE customer_id = ?2 AND sku = ?4 AND policy_slug = ?3 AND occurred_at >= ?6"
+      + ") "
+      + "AND ("
+      + "  ?7 = 0 OR ("
+      + "    SELECT COUNT(*) FROM wishlist_alerts_sent "
+      + "    WHERE customer_id = ?2 AND occurred_at >= ?8"
+      + "  ) < ?9"
+      + ")",
+      [id, customerId, policySlug, sku, now, dedupeSince, capActive, weekSince, capValue],
+    );
+    return Number(r.rowCount || 0) === 1;
+  }
+
   // Walk every wishlist entry that has a non-null variant_id. Whole-
   // product (variant_id IS NULL) rows are skipped at v1 — the policy
   // evaluator can't resolve a single sku for them, and the operator-
@@ -596,9 +661,18 @@ function create(opts) {
     return defaultCurrency;
   }
 
-  // Evaluate a single (entry, policy) pair. Returns either:
-  //   { fire: true,  sku, payload }    — dispatch + ledger
-  //   { fire: false, reason }          — accounted as `skipped`
+  // Evaluate a single (entry, policy) pair against the TRANSITION from
+  // the last-observed state, not the current state in isolation. Returns:
+  //   { fire: true,  sku, payload, state }  — dispatch + ledger; `state`
+  //                                            is the observed-state patch
+  //                                            to persist (always applied,
+  //                                            fire or not).
+  //   { fire: false, reason, sku?, state? } — accounted as `skipped`; a
+  //                                            present `state` patch is
+  //                                            still persisted so the next
+  //                                            sweep reads a fresh baseline.
+  // The last-observed { last_in_stock, last_alerted_bps } for the tuple is
+  // loaded internally once the sku resolves (null fields when never seen).
   async function _evaluate(entry, policy, now) {
     // Map variant → sku.
     var variant;
@@ -608,12 +682,14 @@ function create(opts) {
     var sku = variant.sku;
     if (typeof sku !== "string" || !sku.length) return { fire: false, reason: "variant_has_no_sku" };
 
+    var prior = await _lastState(entry.customer_id, sku, policy.slug);
+
     if (policy.trigger === "price_drop") {
       var currency = await _resolveCurrency(entry.customer_id);
       var current;
       try { current = await catalog.prices.current(entry.variant_id, currency); }
       catch (_e) { current = null; }
-      if (!current) return { fire: false, reason: "no_current_price" };
+      if (!current) return { fire: false, reason: "no_current_price", sku: sku };
       var history;
       try { history = await catalog.prices.history(entry.variant_id, currency); }
       catch (_e) { history = []; }
@@ -624,16 +700,29 @@ function create(opts) {
         var h = history[i];
         if (h.effective_until != null) { baseline = h; break; }
       }
-      if (!baseline) return { fire: false, reason: "no_baseline_price" };
+      if (!baseline) return { fire: false, reason: "no_baseline_price", sku: sku };
       var baseAmt = Number(baseline.amount_minor);
       var curAmt  = Number(current.amount_minor);
       if (!(baseAmt > 0) || !(curAmt >= 0) || curAmt >= baseAmt) {
-        return { fire: false, reason: "no_drop" };
+        // No drop in effect — the price recovered to/above baseline. Clear
+        // the last-alerted level so a fresh drop later is a transition.
+        return { fire: false, reason: "no_drop", sku: sku, state: { last_alerted_bps: null } };
       }
       // Percent-off in basis points: ((base - cur) / base) * 10000.
       var bps = Math.floor(((baseAmt - curAmt) * 10000) / baseAmt);
       var threshold = Number(policy.threshold.percent_off_bps_min);
-      if (bps < threshold) return { fire: false, reason: "below_threshold" };
+      if (bps < threshold) {
+        // Below the policy gate — not an alertable drop. Don't touch the
+        // last-alerted level (a shallow dip after a deep alerted drop
+        // shouldn't reset the baseline and re-arm a re-fire).
+        return { fire: false, reason: "below_threshold", sku: sku };
+      }
+      // Transition gate: fire only on a NEW or DEEPER drop than the level
+      // we last alerted. A steady drop at the same depth must not re-fire,
+      // dedupe window or not.
+      if (prior.last_alerted_bps != null && bps <= prior.last_alerted_bps) {
+        return { fire: false, reason: "no_deeper_drop", sku: sku };
+      }
       return {
         fire: true,
         sku:  sku,
@@ -644,6 +733,12 @@ function create(opts) {
           new_amount_minor:  curAmt,
           discount_bps:      bps,
         },
+        // `state` is the always-record observation (none here — recording
+        // the alerted level happens only on a committed send, below).
+        // `alertedBps` is recorded post-send so a lost claim / failed
+        // mailer doesn't suppress a legitimate later re-fire.
+        state:      {},
+        alertedBps: bps,
       };
     }
 
@@ -651,9 +746,14 @@ function create(opts) {
       var inv;
       try { inv = await catalog.inventory.get(sku); }
       catch (_e) { inv = null; }
-      if (!inv) return { fire: false, reason: "inventory_unresolvable" };
+      if (!inv) return { fire: false, reason: "inventory_unresolvable", sku: sku };
       var available = Number(inv.stock_on_hand || 0) - Number(inv.stock_held || 0);
-      if (!(available > 0)) return { fire: false, reason: "still_out_of_stock" };
+      var inStockNow = available > 0 ? 1 : 0;
+      if (inStockNow === 0) {
+        // Out of stock — record the observed state so a later restock is a
+        // 0 -> 1 transition.
+        return { fire: false, reason: "still_out_of_stock", sku: sku, state: { last_in_stock: 0 } };
+      }
       // Optional dep — when wired, suppress if the customer is already
       // subscribed via the PDP "notify me" toggle. The dispatcher can
       // only know the customer's email when we know they're a logged-
@@ -668,7 +768,19 @@ function create(opts) {
         var sub;
         try { sub = await stockAlerts.isSubscribedByCustomer({ customer_id: entry.customer_id, sku: sku }); }
         catch (_e) { sub = null; }
-        if (sub && sub.subscribed === true) return { fire: false, reason: "duplicate_via_stock_alerts" };
+        // Still record the in-stock observation so the transition baseline
+        // tracks reality even when the stockAlerts path owns the send.
+        if (sub && sub.subscribed === true) {
+          return { fire: false, reason: "duplicate_via_stock_alerts", sku: sku, state: { last_in_stock: 1 } };
+        }
+      }
+      // Transition gate: fire only on the out -> in EDGE. A first
+      // observation (prior unknown) or a steady in-stock state records the
+      // observation but does not fire — there is no restock event to
+      // announce when we never saw the item go out.
+      var isRestock = prior.last_in_stock === 0;
+      if (!isRestock) {
+        return { fire: false, reason: "no_restock_transition", sku: sku, state: { last_in_stock: 1 } };
       }
       return {
         fire: true,
@@ -677,6 +789,7 @@ function create(opts) {
           variant_id: entry.variant_id,
           available:  available,
         },
+        state: { last_in_stock: 1 },
       };
     }
 
@@ -722,8 +835,10 @@ function create(opts) {
       no_baseline_price:            0,
       no_current_price:             0,
       no_drop:                      0,
+      no_deeper_drop:               0,
       below_threshold:              0,
       still_out_of_stock:           0,
+      no_restock_transition:        0,
       inventory_unresolvable:       0,
       variant_unresolvable:         0,
       variant_has_no_sku:           0,
@@ -738,19 +853,25 @@ function create(opts) {
       for (var pp = 0; pp < scannablePolicies.length; pp += 1) {
         var policy = scannablePolicies[pp];
 
-        // Cheapest cuts first.
+        // Cheapest cut first.
         var optedOut = await isUnsubscribedFromTrigger(entry.customer_id, policy.trigger);
         if (optedOut) { skipped += 1; skippedBy.unsubscribed += 1; continue; }
 
-        if (policy.max_alerts_per_week_per_customer != null) {
-          var weekN = await _countAlertsThisWeek(entry.customer_id, now);
-          if (weekN >= policy.max_alerts_per_week_per_customer) {
-            skipped += 1; skippedBy.weekly_cap_reached += 1; continue;
-          }
+        // Evaluate against the TRANSITION from the last-observed state —
+        // a steady in-stock / steady-depth-drop state never re-fires. The
+        // sku isn't known until the variant resolves inside _evaluate, so
+        // it loads the prior state for the resolved tuple itself.
+        var v = await _evaluate(entry, policy, now);
+
+        // Persist the always-record observation (current in-stock state /
+        // a cleared drop) regardless of fire, so the next sweep reads a
+        // fresh baseline even when this one didn't send. An empty patch
+        // (a price_drop fire — its alerted level is recorded only after a
+        // committed send) is a no-op, so skip the write.
+        if (v.sku && v.state && Object.keys(v.state).length > 0) {
+          await _recordState(entry.customer_id, v.sku, policy.slug, v.state, now);
         }
 
-        // Evaluate the policy condition.
-        var v = await _evaluate(entry, policy, now);
         if (!v.fire) {
           skipped += 1;
           if (skippedBy[v.reason] != null) skippedBy[v.reason] += 1;
@@ -758,13 +879,10 @@ function create(opts) {
           continue;
         }
 
-        // Per-(customer, sku, policy) recent-fire suppression.
-        var dup = await _hasRecentFire(entry.customer_id, v.sku, policy.slug, now);
-        if (dup) { skipped += 1; skippedBy.recent_dedupe += 1; continue; }
-
         candidates += 1;
 
-        // Resolve the customer's email. Absent → no_email, skipped.
+        // Resolve the customer's email. Absent → no_email, skipped — we
+        // never claim a ledger row we can't send.
         var customerEmail = null;
         if (emailForCustomer) {
           try { customerEmail = await emailForCustomer(entry.customer_id); }
@@ -774,6 +892,27 @@ function create(opts) {
           skipped += 1; skippedBy.no_email += 1; continue;
         }
 
+        // Atomic dedupe + weekly-cap CLAIM. The conditional INSERT is the
+        // serialization point: two concurrent sweeps can't both pass the
+        // dedupe/cap guard and then both write — the loser's INSERT...
+        // SELECT sees the winner's row and matches zero rows.
+        var id = b.uuid.v7();
+        var ts = _monotonicTs(now);
+        var claimed = await _claimLedgerRow(
+          id, entry.customer_id, policy.slug, v.sku, ts,
+          policy.max_alerts_per_week_per_customer,
+        );
+        if (!claimed) {
+          // Lost the claim — either a recent dedupe fire or the weekly
+          // cap. Distinguish for accurate accounting (read-only; the
+          // mutation already serialized at the INSERT).
+          var dup = await _hasRecentFire(entry.customer_id, v.sku, policy.slug, ts);
+          skipped += 1;
+          if (dup) skippedBy.recent_dedupe += 1;
+          else     skippedBy.weekly_cap_reached += 1;
+          continue;
+        }
+
         // Resolve a product title for the email. Best-effort — falls
         // through to the sku string when the catalog read fails.
         var productTitle = v.sku;
@@ -810,20 +949,20 @@ function create(opts) {
           dispatchOk = true;
         } catch (_e4) {
           // Drop-silent at the row level — a flapping mailer must not
-          // poison the rest of the scan. Account in skipped.
+          // poison the rest of the scan. Release the claimed ledger row
+          // so a later sweep retries instead of being suppressed by the
+          // dedupe window for a send that never happened.
+          await query("DELETE FROM wishlist_alerts_sent WHERE id = ?1", [id]);
           skipped += 1; skippedBy.email_dispatch_failed += 1; continue;
         }
         if (!dispatchOk) continue;
 
-        // Ledger write — the source of truth for "we already fired
-        // this alert" + the dedupe window.
-        var id = b.uuid.v7();
-        var ts = _monotonicTs(now);
-        await query(
-          "INSERT INTO wishlist_alerts_sent (id, customer_id, policy_slug, sku, channel, occurred_at) "
-          + "VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
-          [id, entry.customer_id, policy.slug, v.sku, "email", ts],
-        );
+        // Committed send — record the alerted depth so the same drop
+        // depth is steady on the next sweep (price_drop only; the
+        // back_in_stock observation was already recorded above).
+        if (v.alertedBps != null) {
+          await _recordState(entry.customer_id, v.sku, policy.slug, { last_alerted_bps: v.alertedBps }, ts);
+        }
         sent += 1;
       }
     }

package/lib/wishlist-digest.js

@@ -972,7 +972,20 @@ function create(opts) {
         "VALUES (?1, ?2, ?3, ?4)",
         [sentId, enrollment.id, sentItemCount, sentAt],
       );
+      // Advance the cadence. The normal step is one period past the
+      // current next_dispatch_at — that keeps the schedule aligned to its
+      // target weekday / day-of-month when the tick fires on time. But a
+      // STALE enrollment (the cron was down, or the customer enrolled long
+      // ago) has a next_dispatch_at many periods in the past; advancing it
+      // one period at a time would leave it still due, so the very next
+      // tick re-fires, and a subscriber gets one digest per tick until the
+      // schedule catches up — a flood. Instead, when one period still
+      // doesn't clear `now`, snap straight to the next occurrence strictly
+      // after `now`. The catch-up costs at most ONE digest, never a storm.
       var nextDispatchAt = _advanceByOnePeriod(schedule, Number(enrollment.next_dispatch_at));
+      if (nextDispatchAt <= now) {
+        nextDispatchAt = _nextDispatchAt(schedule, now);
+      }
       await query(
         "UPDATE wishlist_digest_enrollments SET next_dispatch_at = ?1 WHERE id = ?2",
         [nextDispatchAt, enrollment.id],

package/package.json

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