@blamejs/blamejs-shop 0.0.64 → 0.0.66

package/CHANGELOG.md

@@ -8,6 +8,10 @@ upgrading across more than a few patches at a time.
 
 ## v0.0.x
 
+- v0.0.66 (2026-05-22) — **Ten new primitives: site redirects, cost layers, payment retries, pick lists, preorder, discount allocation, currency rounding, credit limits, theme assets, business hours.** Ten primitives ship in one release covering warehouse operations (pick lists, FIFO/LIFO inventory cost layers), commerce (preorder, currency rounding rules, discount allocation breakdown), B2B (credit limits with net-30 terms + aging), payment recovery (payment retries with failure-code-aware policy), and storefront infrastructure (site redirects, theme assets registry, business-hours calculator). **Added:** *`siteRedirects` primitive — operator-defined 301/302/307/308 redirects* — `bShop.siteRedirects.create({ query? })` returns `{ defineRedirect, resolveForPath, recordHit, listRedirects, getRedirect, updateRedirect, archiveRedirect, unarchiveRedirect, topHits, cleanupExpired }`. Match kinds: exact / prefix / regex. Regex patterns refused if they carry backreferences (`\1`-`\9`) or lookahead/lookbehind to keep catastrophic-backtracking out of the live table. `resolveForPath` walks exact > prefix (longest source_path wins, slug ASC tiebreak) > regex (slug ASC). `target_url` accepts /-rooted internal paths OR full https:// via `b.safeUrl`. Migration `0119_site_redirects.sql`. · *`costLayers` primitive — FIFO / LIFO / weighted-average inventory cost tracking* — `bShop.costLayers.create({ query?, catalog? })` returns `{ setMethod, getMethod, recordReceipt, consumeForSale, recordReversal, currentLayers, cogsForOrder, cogsForPeriod }`. Method enum: fifo / lifo / weighted_average. FIFO consumes oldest layers first; LIFO newest; weighted_average computes the mean of remaining layers. Each receipt adds a cost layer with `quantity_remaining` + `unit_cost_minor`. `consumeForSale` returns `{ consumed_layers: [...], total_cogs_minor, currency }` and refuses on insufficient on-hand. `recordReversal` restores stock on returns by adding back to a layer. Per-SKU strict-monotonic `occurred_at` clock so same-millisecond receipts can't tie on the FIFO/LIFO ordering key. Migration `0121_cost_layers.sql`. · *`paymentRetries` primitive — failure-code-aware retry orchestration for one-time payments* — `bShop.paymentRetries.create({ query?, payment? })` returns `{ defineRetryPolicy, enrollFailure, tickRetries, recordRetryOutcome, unenrollPayment, statusForPayment, historyForPayment, policiesForFailureCode, metricsForPolicy }`. Distinct from `dunning` (subscriptions only). Failure-code-aware: `insufficient_funds` → wait 24h + retry; `card_declined` → wait 7d + retry once; `invalid_card` → terminal-at-enrollment. `tickRetries` walks `next_retry_at <= now` rows and dispatches via composed payment.retry. `terminal_after_attempts` exhausts an enrollment + flips `abandoned` status. Migration `0120_payment_retries.sql`. · *`pickLists` primitive — warehouse pick-list workflow* — `bShop.pickLists.create({ query?, order, orderTracking?, inventoryLocations? })` returns `{ generateList, getList, listLists, confirmLine, markListComplete, cancelList, discrepanciesFor }`. Generated from N open orders for a given warehouse, sorted by aisle/sku/priority/order_id (materialized into a `sequence_number` column so picker walk order is durable across reads). Optional `inventoryLocations.binForSku` probe for aisle position. `markListComplete` fans out shipment creation via composed `orderTracking.createShipment` per-order. Migration `0118_pick_lists.sql`. · *`preorder` primitive — pre-launch reservations distinct from backorder* — `bShop.preorder.create({ query?, catalog?, order? })` returns `{ defineCampaign, reserve, getReservation, reservationsForCustomer, cancelReservation, convertReservationToOrder, launchCampaign, closeCampaign, availability, getCampaign }`. Backorder = sku exists but out-of-stock; preorder = sku not yet released. `defineCampaign({ slug, sku, launch_at, charge_at?, max_units_available?, deposit_minor?, full_price_minor })`. `launchCampaign` triggers auto-conversion of all active reservations via composed `order.createFromCart`. Cancelled reservations free capacity for re-reservation. Migration `0124_preorder.sql`. · *`discountAllocation` primitive — per-line allocation of order-level discounts* — `bShop.discountAllocation.create({ query })` returns `{ allocate, recordAllocation, allocationsForOrder, reverseAllocation, metricsForKind }`. Order has $20 off the total — primitive distributes across lines for accounting + refund precision. Kinds: proportional / equal / by_subtotal / by_quantity. Half-even rounding via `b.money.fromMinorUnits(...).multiply([num, den])`; remainder lands deterministically on highest-subtotal line. `reverseAllocation` produces per-line refund amounts that re-sum to the original total. Migration `0129_discount_allocation.sql`. · *`currencyRounding` primitive — per-currency display rounding rules* — `bShop.currencyRounding.create({ query? })` returns `{ defineRule, getRule, listRules, roundFor, updateRule, archiveRule, historyForCurrency, round }`. Distinct from `currencyDisplay` (FX rate cache) — this is the rounding behavior applied at checkout. CHF rounds to nearest 0.05; SEK to nearest 0.10; JPY whole units. Modes: half_up / half_even / half_down / ceiling / floor. `applies_to` enum: display_only / cart_total / line_total / all. Pure `_round(amount, step, mode)` exported as `currencyRounding.round` for direct composition without the factory. Migration `0132_currency_rounding.sql`. · *`creditLimits` primitive — B2B credit accounts with net-30 / net-60 terms + aging report* — `bShop.creditLimits.create({ query?, customers? })` returns `{ defineAccount, getAccount, listAccounts, updateAccount, suspendAccount, reinstateAccount, chargeOrder, releaseHold, recordPayment, availableCredit, outstandingBalance, agingReport }`. `chargeOrder` checks available credit, refuses on insufficient (no row written). `releaseHold` restores credit on cancel. `agingReport({ customer_id })` returns balance by days-past-due bucket (current / 30d / 60d / 90d+). Payments + releases FIFO-settle against oldest charges. FSM: active / suspended / closed. Migration `0122_credit_limits.sql`. · *`themeAssets` primitive — operator-uploaded theme asset registry* — `bShop.themeAssets.create({ query? })` returns `{ registerAsset, getAsset, assetsForTheme, assetsByKind, updateAsset, archiveAsset, assignToTheme, recordImpression, metricsForAsset, cleanupOrphans }`. Asset kinds: font / logo / hero_image / favicon / banner_image / og_image / icon / custom. Content-addressed via `sha3_512` digest (validated as lowercase 128-char hex). `source_url` gated via `b.safeUrl` (https-only + /-rooted internal). `cleanupOrphans({ days_idle })` archives assets not assigned to any active theme. Migration `0131_theme_assets.sql`. · *`businessHours` primitive — operator-defined business-hour windows with DST-correct math* — `bShop.businessHours.create({ query? })` returns `{ defineSchedule, isOpenAt, nextOpenAt, nextCloseAt, weekSummary, addException, removeException, addHoliday, listSchedules, archiveSchedule }`. Per-day open/close times in IANA timezone, plus per-date exceptions + holidays. `Intl.DateTimeFormat` for tz-correct calendar math (DST-correct via Intl, no manual offset arithmetic). Two-pass `_wallClockToEpochMs` algorithm converges across DST folds. `nextOpenAt` skips holidays + closed days. Migration `0127_business_hours.sql`.
+
+- v0.0.65 (2026-05-22) — **Twenty new primitives: address validation, auto discount, captcha gate, catalog drafts, cookie consent, customer roles, cycle counting, delivery estimate, email warmup, metered usage, price display, product bulk ops, purchase orders, quotes, recommendations, reorder thresholds, shipping zones, split shipments, trust badges, webhook receiver.** Twenty primitives ship in one release. Covers per-customer self-serve flows (cookie consent, captcha gate, address validation), operator-side catalog tooling (drafts, bulk ops, reorder thresholds, purchase orders, cycle counting, delivery estimate, shipping zones), commerce primitives (auto discount, quotes, recommendations, price display, split shipments, metered usage, trust badges), and integrations (webhook receiver, email warmup, customer roles). **Added:** *`addressValidation` primitive — cache + lookup for address-validation API results* — `bShop.addressValidation.create({ query? })` returns `{ recordValidation, lookupCached, signatureFor, recordSuggestion, lookupSuggestions, cleanupExpired, metricsForSource, validationsForOrder }`. Input signature derived via `namespaceHash('address-validation-input', canonical(input))` so the same address normalizes to one cache row. Source enum: `usps / smarty / lob / google / melissa / manual`. Classification enum: `residential / commercial / po_box / military / unknown`. Migration `0115_address_validation.sql`. · *`autoDiscount` primitive — automatic discounts without coupon codes* — `bShop.autoDiscount.create({ query?, catalog?, customerSegments? })` returns `{ defineRule, getRule, listRules, updateRule, archiveRule, evaluate, recordApplication, metricsForRule }`. Trigger kinds: `cart_total_min / item_count_min / sku_purchase`. Value kinds: `percent_off / amount_off_total / amount_off_each / free_shipping / bogo`. Priority + max_redemptions + customer segment gating. Migration `0107_auto_discount.sql`. · *`captchaGate` primitive — CAPTCHA verification at high-risk entrypoints* — `bShop.captchaGate.create({ query? })` returns `{ registerProvider, verifyToken, recordOutcome, metricsForProvider, ... }`. Provider enum: `turnstile / hcaptcha / recaptcha_v2 / recaptcha_v3`. reCAPTCHA v3 gets a threshold-score floor (basis-points). Secret hashed via `namespaceHash('captcha-secret', ...)`; session id hashed before write. Provider-callback-driven verify; operator's worker calls the actual provider endpoint. Migration `0114_captcha_gate.sql`. · *`catalogDrafts` primitive — staging workflow for catalog mutations* — `bShop.catalogDrafts.create({ query?, catalog })` returns `{ openDraft, stageChange, listChanges, removeChange, previewMerged, publishDraft, cancelDraft, rollbackDraft, listDrafts, historyForSku }`. Stage N changes against catalog (create / update / archive products + variants + prices + tags + inventory); publish atomically. 7-day rollback window. Pre-flight validates every change against the live catalog before writing anything. Migration `0112_catalog_drafts.sql`. · *`cookieConsent` primitive — GDPR / ePrivacy consent management* — `bShop.cookieConsent.create({ query? })` returns `{ recordConsent, getConsentFor, withdrawConsent, categoryAllowed, metricsForBanner, cleanupOlderThan, registerPolicyVersion }`. Categories: strictly-necessary (always on) + functional + analytics + marketing + preferences. DNT / Sec-GPC headers force implicit deny on marketing + analytics regardless of recorded consent. Policy-version bump flags older session consents for re-prompt. Session id hashed before write. Migration `0103_cookie_consent.sql`. · *`customerRoles` primitive — B2B company-account roles + capabilities* — `bShop.customerRoles.create({ query?, customers? })` returns `{ defineRole, assignRole, unassignRole, rolesForEmployee, employeesForCompany, hasCapability, recordOrderApproval, listRoles, updateRole, archiveRole }`. Capabilities: `can_view_orders / can_place_order / can_approve_order / can_manage_users / can_view_pricing / can_apply_payment_terms / can_request_quote / can_view_invoices`. UNIQUE(company, employee) so an employee carries one role per company. Migration `0101_customer_roles.sql`. · *`cycleCounting` primitive — physical inventory cycle counts* — `bShop.cycleCounting.create({ query?, catalog, inventoryLocations? })` returns `{ defineCount, worksheetFor, recordCount, finalizeCount, cancelCount, discrepanciesFor, listCounts, historyForSku, getCount }`. Kinds: `rotating / abc / full`. `finalizeCount({ apply_adjustments })` writes adjustments through `inventoryLocations.adjustStock` with `reason='cycle-count:<slug>'` so the audit row carries the count slug. Migration `0108_cycle_counting.sql`. · *`deliveryEstimate` primitive — PDP + cart delivery-window calculator* — `bShop.deliveryEstimate.create({ query?, inventoryLocations?, shippingZones? })` returns `{ defineCarrierTransit, defineCutoff, defineHoliday, definePostalZone, estimate, estimateForCart, listTransits, listCutoffs, listHolidays, archiveTransit, archiveHoliday }`. Calendar math is Intl-DateTimeFormat-driven (DST-correct); weekend + region-holiday skips applied separately to origin ship-by + destination delivery-by. Migration `0117_delivery_estimate.sql`. · *`emailWarmup` primitive — gradual SMTP IP/domain warmup* — `bShop.emailWarmup.create({ query?, now? })` returns `{ defineSchedule, canSend, recordSends, recordEngagement, currentDay, pauseSchedule, resumeSchedule, archiveSchedule, listSchedules, getSchedule, metricsForSchedule }`. Daily targets array (Day 1: 50, Day 2: 100, etc.) cap outbound volume to build sender reputation. Day-index math computed against UTC midnight of `start_date`. Migration `0116_email_warmup.sql`. · *`meteredUsage` primitive — usage-based subscription billing* — `bShop.meteredUsage.create({ query?, subscriptions?, subscriptionBilling? })` returns `{ defineMeter, recordUsage, usageForPeriod, periodSummary, recordPeriodInvoice, listMeters, updateMeter, archiveMeter }`. Tier schedule for tiered pricing (first 1000 free, next 10000 at $0.001, ...). `recordUsage` idempotency_key dedups re-submitted events. `recordPeriodInvoice` queues invoice line via subscriptionBilling. Migration `0095_metered_usage.sql`. · *`priceDisplay` primitive — per-region tax-included / tax-excluded display modes* — `bShop.priceDisplay.create({ query?, tax?, taxRates?, geolocation? })` returns `{ defineRule, getModeFor, formatPrice, defineCustomerOverride, clearCustomerOverride, customerOverride, listRules, updateRule, archiveRule }`. Resolution priority: customer-override > customer_status_in > country default. Compose `tax.calculateInclusive / calculateExclusive` for the breakdown. Migration `0097_price_display.sql`. · *`productBulkOps` primitive — bulk product mutations with pre-flight + audit* — `bShop.productBulkOps.create({ query?, catalog, maxBulkRows? })` returns `{ bulkSetPrice, bulkAdjustPrice, bulkArchive, bulkUnarchive, bulkAddTag, bulkRemoveTag, bulkSetInventory, previewFilter, auditTrail, categories, tags }`. Filter `{ skus?, vendor_slug?, category?, tag_any?, tag_all? }`. Pre-flight cap default 1000, ceiling 10000. Half-up rounding on percent adjustments; floored at 0. Process-local monotonic `_now` so back-to-back audit rows sort newest-first reliably. Migration `0104_product_bulk_ops.sql`. · *`purchaseOrders` primitive — operator-facing POs to vendors* — `bShop.purchaseOrders.create({ query?, vendors?, inventoryReceive? })` returns `{ createDraft, submitToVendor, confirmByVendor, recordPartialReceipt, closePO, cancelPO, getPO, listPOs, linesForPO, update }`. FSM `draft → submitted → confirmed → partially_received → received → closed`. `recordPartialReceipt` composes `inventoryReceive.draft + apply` for restock. `closePO` refuses unless all lines fully received. Migration `0099_purchase_orders.sql`. · *`quotes` primitive — B2B RFQ / quote flow* — `bShop.quotes.create({ query?, cart?, order? })` returns `{ requestQuote, respondToQuote, customerAccept, customerReject, cancelQuote, convertToOrder, getQuote, quotesForCustomer, pendingResponse, listExpired, markExpired }`. FSM `requested → responded → accepted → converted` with `rejected / expired / cancelled` terminal branches. `convertToOrder` composes `order.createFromCart` using the quoted prices. Accepts either `lines` or `cart_id` (via cart aggregator). Migration `0102_quotes.sql`. · *`recommendations` primitive — storefront product recommendation engine* — `bShop.recommendations.create({ query?, catalog, analytics?, recentlyViewed? })` returns `{ recommendForProduct, recommendForCart, recommendForCustomer, recommendForCategory, setOverride, removeOverride, listOverrides, recordImpression, recordClick, recordConversion, metricsForKind }`. Override layer reads first then falls through co-purchase → category-popular → random-in-stock. Session id namespace-hashed before write. Migration `0105_recommendations.sql`. · *`reorderThresholds` primitive — per-SKU + per-location reorder thresholds + PO suggestions* — `bShop.reorderThresholds.create({ query?, catalog, inventoryLocations?, vendors? })` returns `{ defineThreshold, evaluate, scanAll, proposePurchaseOrder, recordVelocity, updateThreshold, archiveThreshold, listThresholds }`. Velocity-driven suggested_qty = `gap + ceil(units_per_day * lead_time_days)`. Partial-UNIQUE on `(sku, location_code)` for active rows. Migration `0098_reorder_thresholds.sql`. · *`shippingZones` primitive — operator-defined shipping zones + rate tables* — `bShop.shippingZones.create({ query? })` returns `{ defineZone, getZone, listZones, updateZone, archiveZone, rateFor, zoneForDestination }`. Region match: country-only or country + region. `rateFor` half-open `[min_weight, max_weight)` + `[min_order, max_order)` bucketing across rate rows; returns all matches sorted by rate ascending. Migration `0106_shipping_zones.sql`. · *`splitShipments` primitive — one-order N-shipment planning* — `bShop.splitShipments.create({ query?, order, orderTracking, backorder?, inventoryLocations? })` returns `{ planSplit, executeSplit, mergeShipments, splitsForOrder, recommendStrategy }`. Strategies: `availability / location / vendor / manual`. `executeSplit` writes shipment rows via `orderTracking.createShipment`. `mergeShipments` combines source shipments into a target. Migration `0096_split_shipments.sql`. · *`trustBadges` primitive — storefront trust seals + certifications* — `bShop.trustBadges.create({ query? })` returns `{ defineBadge, activeForPlacement, listAll, getBadge, updateBadge, archiveBadge, renderHtml, recordImpression, recordClick, impressionCount, clickCount }`. Placements: header / footer / pdp / cart_review / checkout / order_confirmation. SVG payload sanitized via `b.guardSvg`; link_url through `b.safeUrl`. Multiple badges can stack at one placement, sorted priority-DESC. Migration `0111_trust_badges.sql`. · *`webhookReceiver` primitive — inbound HMAC-signed webhook acceptor* — `bShop.webhookReceiver.create({ query?, now? })` returns `{ defineSource, verifyAndPersist, markProcessed, markFailed, unprocessedEvents, eventsForSource, getEvent, purgeOlderThan, rotateSecret, archiveSource, getSource, listSources }`. HMAC-SHA-256 verification + replay-window timestamps + idempotency_key dedup. Rotation carries a 24h grace window where deliveries signed under the old secret still verify. Plaintext secret returned once at `defineSource` / `rotateSecret`; storage holds only the namespaceHash digest. Migration `0110_webhook_receiver.sql`. **Fixed:** *`productBulkOps` — monotonic `_now` so back-to-back audit rows sort newest-first reliably* — Same Date.now() resolution issue that affected several earlier primitives — replaced with a process-local monotonic clock that bumps by 1ms on collision. The audit-trail `ORDER BY occurred_at DESC, id DESC` listing now returns rows in the correct insertion order even under same-millisecond bulk operations.
+
 - v0.0.64 (2026-05-22) — **Two new primitives: compliance export + live chat.** `complianceExport` is the GDPR / CCPA / LGPD subject-access-request export + deletion lifecycle. `liveChat` is the real-time customer-service queue with operator assignment and per-session messages. **Added:** *`complianceExport` primitive — GDPR / CCPA / LGPD subject-access-request export + deletion lifecycle* — `bShop.complianceExport.create({ query?, customers, order?, orderNotes?, subscriptions?, addresses?, paymentMethods?, supportTickets?, loyalty? })` returns `{ requestExport, requestDeletion, getRequest, listRequests, fulfillRequest, dispatchExport, processDeletion, dismissRequest, auditForCustomer }`. Composes injected per-domain readers via a `forCustomerExport(customer_id)` / `forCustomerDeletion(customer_id, { dry_run })` contract; the primitive owns the request row, the scope/section filtering, and the dry-run-vs-wet posture. Scope enum: `full / orders_only / identity_only`. Jurisdiction enum: `gdpr / ccpa / lgpd / other`. Status FSM: `received / processing / fulfilled / delivered / dismissed`. Migration `0109_compliance_export.sql`. · *`liveChat` primitive — real-time customer-service queue* — `bShop.liveChat.create({ query? })` returns `{ openSession, enqueueSession, assignToOperator, recordMessage, closeSession, getSession, messagesForSession, operatorQueue, waitingQueue, operatorWorkload, markOperatorAvailable, markOperatorAway, cleanupAbandoned }`. Six-state FSM: queued / assigned / active / waiting / closed / abandoned. Visitor session id + email hashed via `namespaceHash` under `live-chat-visitor` / `live-chat-email` namespaces; raw values never persist. Process-local monotonic `_now` so back-to-back operator assignments and message inserts paginate stably. `cleanupAbandoned({ idle_minutes })` reaps idle sessions. Migration `0113_live_chat.sql`.
 
 - v0.0.63 (2026-05-22) — **Three new primitives: invoice renderer, store credit, error log.** Three primitives ship in this release. `invoiceRenderer` produces operator + customer-facing formal invoices (HTML for PDF conversion + plain text + sequential invoice numbers). `storeCredit` is the per-customer account-bound credit wallet, distinct from gift cards (no code). `errorLog` is the operator-side HTTP error event log with top-404 / top-5xx / slow-render dashboards. **Added:** *`invoiceRenderer` primitive — formal accounting invoices with sequential numbers* — `bShop.invoiceRenderer.create({ query?, order })` returns `{ nextInvoiceNumber, renderHtml, recordInvoice, invoicesForOrder, getInvoiceByNumber }`. `nextInvoiceNumber({ series? })` returns sequential `INV-YYYY-NNNNNN`-shaped id with per-series counter. `renderHtml({ order_id, locale?, series?, due_days? })` returns the full HTML invoice with operator + customer addresses, line items, tax breakdown, totals, payment terms, due date. All operator + customer input fields HTML-escaped via `b.template.escapeHtml`. `recordInvoice` writes the audit row carrying `html_size` + `sha3_512` digest. Migration `0093_invoice_renderer.sql` (`invoice_renderings` + `invoice_sequence` tables). · *`storeCredit` primitive — per-customer account-bound credit wallet* — `bShop.storeCredit.create({ query? })` returns `{ credit, debit, expire, balance, history, transactionsForOrder, expiringWithin, bulkBalance, cleanupExpired }`. Distinct from `giftCardLedger` — store credit is account-bound, no code. `credit` source enum: `refund / goodwill / promotional / manual / loyalty_redemption`. `debit` refuses overdraft. `balance_after_minor` denormalized per row so current balance is O(1). `cleanupExpired({ now })` scheduler-callable: walks expired rows + adds offsetting expire entries. `expiringWithin({ customer_id, days })` lists balance set to expire so the storefront can prompt the customer. Migration `0094_store_credit.sql`. · *`errorLog` primitive — HTTP error event log with operator dashboards* — `bShop.errorLog.create({ query? })` returns `{ recordError, top404Paths, top5xxErrors, slowRenders, errorById, byStatus, metrics }`. Drop-silent on bad input — hot-path observability sink; throwing here would crash the request that triggered the log entry. Session id always hashed via `namespaceHash('error-log-session', ...)` before write. `top404Paths({ from, to, limit })` and `top5xxErrors({ from, to, limit })` power operator dead-link cleanup + upstream-health dashboards. `slowRenders({ from, to, limit, p99_threshold_ms? })` surfaces requests over the operator-configured p99 budget. `metrics` returns counts + p50 / p95 / p99 response time percentiles. Migration `0100_error_log.sql`.

package/lib/address-validation.js

@@ -0,0 +1,529 @@
+"use strict";
+/**
+ * @module shop.addressValidation
+ * @title  Address validation + autocomplete proxy cache — stores
+ *         operator-supplied normalization results so repeat lookups
+ *         against the same address don't re-pay the carrier API.
+ *
+ * @intro
+ *   The primitive does not call USPS / Smarty / Lob / Google / Melissa
+ *   itself. The operator wires the actual provider call; this
+ *   primitive is the storage + cache layer. The operator hands the
+ *   primitive:
+ *
+ *     - `input`  — the raw address (or address-suggest prefix) the
+ *                  user typed.
+ *     - `normalized_address` — what the carrier normalized it to.
+ *     - `deliverable` / `classification` / `dpv_match` — the
+ *                  carrier's verdict.
+ *     - `source` — which carrier produced the answer
+ *                  (`usps / smarty / lob / google / melissa / manual`).
+ *     - `expires_at` — operator-chosen ms-epoch when the cached row
+ *                  goes stale and `lookupCached` should fall through
+ *                  to a fresh provider call.
+ *
+ *   The same raw address must hit the same cache row, even when the
+ *   operator's call site renders the input object with the keys in a
+ *   different order or with a slightly different shape. The primitive
+ *   derives `input_signature` from
+ *
+ *     b.crypto.namespaceHash("address-validation-input",
+ *                            b.safeJson.canonical(input))
+ *
+ *   so map-order / whitespace fluctuation hashes identically. The
+ *   schema's UNIQUE on `input_signature` makes `recordValidation` an
+ *   upsert: a second call against the same signature overwrites the
+ *   prior row (operators tuning expiry mid-flight get deterministic
+ *   semantics).
+ *
+ *   Surface:
+ *     recordValidation({ input, normalized_address, deliverable,
+ *                        classification, dpv_match?, source,
+ *                        order_id?, expires_at })
+ *     lookupCached(input)
+ *     recordSuggestion({ partial_input, suggestions, expires_at })
+ *     lookupSuggestions(partial_input)
+ *     cleanupExpired({ now? })
+ *     metricsForSource({ slug, from, to })
+ *     validationsForOrder(order_id)
+ *
+ *   Composes:
+ *     - `b.crypto.namespaceHash`  — SHA3-512 of the canonical input
+ *                                   under the address-validation
+ *                                   namespace.
+ *     - `b.safeJson.canonical`    — deterministic JSON serialization
+ *                                   (keys sorted, no NaN / Infinity).
+ *     - `b.uuid.v7`               — row PKs.
+ *
+ *   Storage:
+ *     - `address_validations` + `address_suggestions_cache`
+ *       (migration `0115_address_validation.sql`).
+ *
+ * @primitive addressValidation
+ * @related   b.crypto, b.safeJson, b.uuid, shop.addresses, shop.geolocation
+ */
+
+var bShop;
+function _b() {
+  if (!bShop) bShop = require("./index");
+  return bShop.framework;
+}
+
+// ---- constants ----------------------------------------------------------
+
+var INPUT_NAMESPACE = "address-validation-input";
+
+var SOURCES = Object.freeze([
+  "usps", "smarty", "lob", "google", "melissa", "manual",
+]);
+
+var CLASSIFICATIONS = Object.freeze([
+  "residential", "commercial", "po_box", "military", "unknown",
+]);
+
+var MAX_NORMALIZED_JSON_LEN = 16 * 1024;
+var MAX_PARTIAL_INPUT_LEN   = 512;
+var MAX_SUGGESTIONS_JSON_LEN = 32 * 1024;
+var MAX_DPV_LEN             = 16;
+var MAX_ORDER_ID_LEN        = 128;
+
+// ---- validators ---------------------------------------------------------
+
+function _input(value, label) {
+  label = label || "input";
+  if (value == null) {
+    throw new TypeError("addressValidation: " + label + " is required");
+  }
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError("addressValidation: " + label + " must be a plain object");
+  }
+  return value;
+}
+
+function _msEpoch(n, label) {
+  if (typeof n !== "number" || !isFinite(n) || n < 0 || !Number.isInteger(n)) {
+    throw new TypeError(
+      "addressValidation: " + label + " must be a non-negative integer ms-epoch"
+    );
+  }
+  return n;
+}
+
+function _bool(v, label) {
+  if (typeof v !== "boolean") {
+    throw new TypeError("addressValidation: " + label + " must be a boolean");
+  }
+  return v;
+}
+
+function _source(s) {
+  if (typeof s !== "string" || SOURCES.indexOf(s) === -1) {
+    throw new TypeError(
+      "addressValidation: source must be one of " + JSON.stringify(SOURCES) +
+      ", got " + JSON.stringify(s)
+    );
+  }
+  return s;
+}
+
+function _classification(s) {
+  if (typeof s !== "string" || CLASSIFICATIONS.indexOf(s) === -1) {
+    throw new TypeError(
+      "addressValidation: classification must be one of " +
+      JSON.stringify(CLASSIFICATIONS) + ", got " + JSON.stringify(s)
+    );
+  }
+  return s;
+}
+
+function _dpvMatch(s) {
+  if (s == null) return null;
+  if (typeof s !== "string" || !s.length) {
+    throw new TypeError("addressValidation: dpv_match must be a non-empty string or null");
+  }
+  if (s.length > MAX_DPV_LEN) {
+    throw new TypeError(
+      "addressValidation: dpv_match must be <= " + MAX_DPV_LEN + " characters"
+    );
+  }
+  if (/[\x00-\x1F\x7F]/.test(s)) {
+    throw new TypeError("addressValidation: dpv_match must not contain control bytes");
+  }
+  return s;
+}
+
+function _orderId(s) {
+  if (s == null) return null;
+  if (typeof s !== "string" || !s.length) {
+    throw new TypeError("addressValidation: order_id must be a non-empty string or null");
+  }
+  if (s.length > MAX_ORDER_ID_LEN) {
+    throw new TypeError(
+      "addressValidation: order_id must be <= " + MAX_ORDER_ID_LEN + " characters"
+    );
+  }
+  if (/[\x00-\x1F\x7F]/.test(s)) {
+    throw new TypeError("addressValidation: order_id must not contain control bytes");
+  }
+  return s;
+}
+
+function _normalizedAddress(v) {
+  if (v == null || typeof v !== "object" || Array.isArray(v)) {
+    throw new TypeError(
+      "addressValidation: normalized_address must be a plain object"
+    );
+  }
+  var json;
+  try { json = _b().safeJson.canonical(v); }
+  catch (e) {
+    throw new TypeError(
+      "addressValidation: normalized_address must be JSON-serializable — " + e.message
+    );
+  }
+  if (json.length > MAX_NORMALIZED_JSON_LEN) {
+    throw new TypeError(
+      "addressValidation: normalized_address canonical-JSON must be <= " +
+      MAX_NORMALIZED_JSON_LEN + " bytes"
+    );
+  }
+  return json;
+}
+
+function _partialInput(s) {
+  if (typeof s !== "string" || !s.length) {
+    throw new TypeError("addressValidation: partial_input must be a non-empty string");
+  }
+  if (s.length > MAX_PARTIAL_INPUT_LEN) {
+    throw new TypeError(
+      "addressValidation: partial_input must be <= " + MAX_PARTIAL_INPUT_LEN + " characters"
+    );
+  }
+  if (/[\x00-\x1F\x7F]/.test(s)) {
+    throw new TypeError("addressValidation: partial_input must not contain control bytes");
+  }
+  return s;
+}
+
+function _suggestions(v) {
+  if (!Array.isArray(v)) {
+    throw new TypeError("addressValidation: suggestions must be an array");
+  }
+  var json;
+  try { json = _b().safeJson.canonical(v); }
+  catch (e) {
+    throw new TypeError(
+      "addressValidation: suggestions must be JSON-serializable — " + e.message
+    );
+  }
+  if (json.length > MAX_SUGGESTIONS_JSON_LEN) {
+    throw new TypeError(
+      "addressValidation: suggestions canonical-JSON must be <= " +
+      MAX_SUGGESTIONS_JSON_LEN + " bytes"
+    );
+  }
+  return json;
+}
+
+function _now() { return Date.now(); }
+
+// ---- signature helper --------------------------------------------------
+
+function _signatureForInput(input) {
+  _input(input, "input");
+  var canonical;
+  try { canonical = _b().safeJson.canonical(input); }
+  catch (e) {
+    throw new TypeError(
+      "addressValidation: input must be JSON-serializable — " + e.message
+    );
+  }
+  return _b().crypto.namespaceHash(INPUT_NAMESPACE, canonical);
+}
+
+// ---- row -> wire conversions -------------------------------------------
+
+function _parseNormalized(raw) {
+  try { return JSON.parse(raw); }
+  catch (_e) {
+    throw new Error(
+      "addressValidation: normalized_address_json column is malformed JSON — storage corruption"
+    );
+  }
+}
+
+function _rowToValidation(row) {
+  if (!row) return null;
+  return {
+    id:                  row.id,
+    input_signature:     row.input_signature,
+    normalized_address:  _parseNormalized(row.normalized_address_json),
+    deliverable:         Number(row.deliverable) === 1,
+    classification:      row.classification,
+    dpv_match:           row.dpv_match == null ? null : row.dpv_match,
+    source:              row.source,
+    order_id:            row.order_id == null ? null : row.order_id,
+    expires_at:          Number(row.expires_at),
+    occurred_at:         Number(row.occurred_at),
+  };
+}
+
+function _rowToSuggestion(row) {
+  if (!row) return null;
+  var parsed;
+  try { parsed = JSON.parse(row.suggestions_json); }
+  catch (_e) {
+    throw new Error(
+      "addressValidation: suggestions_json column is malformed JSON — storage corruption"
+    );
+  }
+  return {
+    id:            row.id,
+    partial_input: row.partial_input,
+    suggestions:   parsed,
+    expires_at:    Number(row.expires_at),
+    occurred_at:   Number(row.occurred_at),
+  };
+}
+
+// ---- factory -----------------------------------------------------------
+
+function create(opts) {
+  opts = opts || {};
+  var query = opts.query;
+  if (!query) {
+    query = function (sql, params) { return _b().externalDb.query(sql, params); };
+  }
+
+  async function _getValidationBySig(sig) {
+    var r = await query(
+      "SELECT * FROM address_validations WHERE input_signature = ?1",
+      [sig],
+    );
+    return r.rows[0] || null;
+  }
+
+  async function _getSuggestionByInput(p) {
+    var r = await query(
+      "SELECT * FROM address_suggestions_cache WHERE partial_input = ?1",
+      [p],
+    );
+    return r.rows[0] || null;
+  }
+
+  return {
+    SOURCES:         SOURCES,
+    CLASSIFICATIONS: CLASSIFICATIONS,
+
+    // Stamp a normalization result against the input that produced it.
+    // The schema's UNIQUE on input_signature makes this an upsert: a
+    // second call against the same input overwrites the prior row.
+    // Operators tune cache lifetime by raising / lowering `expires_at`
+    // on each fresh write — the cache is operator-managed, not
+    // primitive-managed.
+    recordValidation: async function (input) {
+      if (!input || typeof input !== "object") {
+        throw new TypeError("addressValidation.recordValidation: input object required");
+      }
+      var sig            = _signatureForInput(input.input);
+      var normalizedJson = _normalizedAddress(input.normalized_address);
+      var deliverable    = _bool(input.deliverable, "deliverable");
+      var classification = _classification(input.classification);
+      var dpvMatch       = _dpvMatch(input.dpv_match == null ? null : input.dpv_match);
+      var source         = _source(input.source);
+      var orderId        = _orderId(input.order_id == null ? null : input.order_id);
+      var expiresAt      = _msEpoch(input.expires_at, "expires_at");
+      var occurredAt     = input.occurred_at == null ? _now() : _msEpoch(input.occurred_at, "occurred_at");
+
+      // Upsert. Existing row -> overwrite every operator-supplied
+      // column AND refresh `occurred_at` so `metricsForSource` reflects
+      // the latest provider call. The id stays stable so any external
+      // reference doesn't dangle.
+      var existing = await _getValidationBySig(sig);
+      if (existing) {
+        await query(
+          "UPDATE address_validations SET " +
+          "normalized_address_json = ?1, deliverable = ?2, classification = ?3, " +
+          "dpv_match = ?4, source = ?5, order_id = ?6, expires_at = ?7, occurred_at = ?8 " +
+          "WHERE input_signature = ?9",
+          [
+            normalizedJson, deliverable ? 1 : 0, classification,
+            dpvMatch, source, orderId, expiresAt, occurredAt, sig,
+          ],
+        );
+        return _rowToValidation(await _getValidationBySig(sig));
+      }
+
+      var id = _b().uuid.v7();
+      await query(
+        "INSERT INTO address_validations " +
+        "(id, input_signature, normalized_address_json, deliverable, classification, " +
+        " dpv_match, source, order_id, expires_at, occurred_at) " +
+        "VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)",
+        [
+          id, sig, normalizedJson, deliverable ? 1 : 0, classification,
+          dpvMatch, source, orderId, expiresAt, occurredAt,
+        ],
+      );
+      return _rowToValidation(await _getValidationBySig(sig));
+    },
+
+    // Look up a cached validation by the raw input shape. Returns the
+    // hydrated row when fresh, `null` when either no row exists OR the
+    // row's `expires_at` is at-or-before now (expired rows are surfaced
+    // as a cache miss so the caller falls through to a fresh provider
+    // call). `cleanupExpired` actually deletes the row; this method
+    // never mutates.
+    lookupCached: async function (input) {
+      var sig = _signatureForInput(input);
+      var row = await _getValidationBySig(sig);
+      if (!row) return null;
+      var hydrated = _rowToValidation(row);
+      if (hydrated.expires_at <= _now()) return null;
+      return hydrated;
+    },
+
+    // Compute the cache signature for a raw input — exposed so
+    // operators can pre-hash and key external storage off the same
+    // shape without re-running the canonical-JSON pipeline.
+    signatureFor: function (input) {
+      return _signatureForInput(input);
+    },
+
+    // Autocomplete cache: a partial-input string -> array of
+    // operator-opaque suggestion objects. Same upsert + expiry shape
+    // as the validations table.
+    recordSuggestion: async function (input) {
+      if (!input || typeof input !== "object") {
+        throw new TypeError("addressValidation.recordSuggestion: input object required");
+      }
+      var partial         = _partialInput(input.partial_input);
+      var suggestionsJson = _suggestions(input.suggestions);
+      var expiresAt       = _msEpoch(input.expires_at, "expires_at");
+      var occurredAt      = input.occurred_at == null ? _now() : _msEpoch(input.occurred_at, "occurred_at");
+
+      var existing = await _getSuggestionByInput(partial);
+      if (existing) {
+        await query(
+          "UPDATE address_suggestions_cache SET " +
+          "suggestions_json = ?1, expires_at = ?2, occurred_at = ?3 " +
+          "WHERE partial_input = ?4",
+          [suggestionsJson, expiresAt, occurredAt, partial],
+        );
+        return _rowToSuggestion(await _getSuggestionByInput(partial));
+      }
+
+      var id = _b().uuid.v7();
+      await query(
+        "INSERT INTO address_suggestions_cache " +
+        "(id, partial_input, suggestions_json, expires_at, occurred_at) " +
+        "VALUES (?1, ?2, ?3, ?4, ?5)",
+        [id, partial, suggestionsJson, expiresAt, occurredAt],
+      );
+      return _rowToSuggestion(await _getSuggestionByInput(partial));
+    },
+
+    lookupSuggestions: async function (partialInput) {
+      var partial = _partialInput(partialInput);
+      var row = await _getSuggestionByInput(partial);
+      if (!row) return null;
+      var hydrated = _rowToSuggestion(row);
+      if (hydrated.expires_at <= _now()) return null;
+      return hydrated;
+    },
+
+    // Delete every row in both tables whose expires_at has elapsed.
+    // Returns `{ validations, suggestions, now }` so operators can
+    // surface a "swept N stale entries" admin metric. Idempotent —
+    // a second call immediately after the first returns zero counts.
+    cleanupExpired: async function (input) {
+      input = input || {};
+      var now = input.now == null ? _now() : _msEpoch(input.now, "now");
+      var rV = await query(
+        "DELETE FROM address_validations WHERE expires_at <= ?1",
+        [now],
+      );
+      var rS = await query(
+        "DELETE FROM address_suggestions_cache WHERE expires_at <= ?1",
+        [now],
+      );
+      return {
+        validations: rV.rowCount != null ? Number(rV.rowCount) : 0,
+        suggestions: rS.rowCount != null ? Number(rS.rowCount) : 0,
+        now:         now,
+      };
+    },
+
+    // Aggregate per-source counts over the [from, to] window keyed
+    // on `occurred_at`. `slug` (the operator-facing arg name from the
+    // spec) carries the source enum value; the result splits by
+    // classification + deliverable so operators can spot a carrier
+    // whose classification mix drifts.
+    metricsForSource: async function (input) {
+      if (!input || typeof input !== "object") {
+        throw new TypeError("addressValidation.metricsForSource: input object required");
+      }
+      var source = _source(input.slug);
+      var from   = _msEpoch(input.from, "from");
+      var to     = _msEpoch(input.to,   "to");
+      if (to < from) {
+        throw new TypeError("addressValidation.metricsForSource: to must be >= from");
+      }
+      var rows = (await query(
+        "SELECT classification, deliverable, COUNT(*) AS row_count " +
+        "FROM address_validations " +
+        "WHERE source = ?1 AND occurred_at >= ?2 AND occurred_at <= ?3 " +
+        "GROUP BY classification, deliverable " +
+        "ORDER BY classification ASC, deliverable ASC",
+        [source, from, to],
+      )).rows;
+      var out = [];
+      var total = 0;
+      for (var i = 0; i < rows.length; i += 1) {
+        var r = rows[i];
+        var n = Number(r.row_count);
+        total += n;
+        out.push({
+          source:         source,
+          classification: r.classification,
+          deliverable:    Number(r.deliverable) === 1,
+          count:          n,
+        });
+      }
+      return { source: source, from: from, to: to, total: total, buckets: out };
+    },
+
+    // Every validation row tagged with the given order_id, in
+    // recorded-newest-first order. Operators present this list as the
+    // audit trail for "show me every address normalization we paid
+    // for on order X." Rows the operator never stamped with an
+    // order_id are silently excluded.
+    validationsForOrder: async function (orderId) {
+      if (typeof orderId !== "string" || !orderId.length) {
+        throw new TypeError("addressValidation.validationsForOrder: order_id must be a non-empty string");
+      }
+      if (orderId.length > MAX_ORDER_ID_LEN) {
+        throw new TypeError(
+          "addressValidation.validationsForOrder: order_id must be <= " + MAX_ORDER_ID_LEN + " characters"
+        );
+      }
+      var rows = (await query(
+        "SELECT * FROM address_validations WHERE order_id = ?1 " +
+        "ORDER BY occurred_at DESC, id DESC",
+        [orderId],
+      )).rows;
+      var out = [];
+      for (var i = 0; i < rows.length; i += 1) {
+        out.push(_rowToValidation(rows[i]));
+      }
+      return out;
+    },
+  };
+}
+
+module.exports = {
+  create:          create,
+  SOURCES:         SOURCES,
+  CLASSIFICATIONS: CLASSIFICATIONS,
+  INPUT_NAMESPACE: INPUT_NAMESPACE,
+};