@blamejs/core 0.8.42 → 0.8.49

package/lib/i18n.js

@@ -1,62 +1,60 @@
 "use strict";
 /**
- * b.i18n — translation + locale negotiation primitive.
+ * @module b.i18n
+ * @nav    Tools
+ * @title  i18n
  *
- * Built on Node 24's bundled `Intl.*` (PluralRules, NumberFormat,
- * DateTimeFormat, RelativeTimeFormat, ListFormat, DisplayNames). Zero
- * vendoring, zero CLDR data shipped — the runtime owns it.
+ * @intro
+ *   ICU MessageFormat + CLDR Plural Rules + locale-aware Intl
+ *   formatters with translation lookup. Built on Node 24's bundled
+ *   `Intl.*` (`PluralRules`, `NumberFormat`, `DateTimeFormat`,
+ *   `RelativeTimeFormat`, `ListFormat`, `DisplayNames`) — zero
+ *   vendoring, zero CLDR data shipped, the runtime owns it.
  *
- *   var i = b.i18n.create({
- *     defaultLocale: "en",
- *     locales:       ["en", "es", "fr", "ja", "ar"],
- *     translations:  {
- *       en: { greeting: "Hello, {name}!", items: { one: "{count} item", other: "{count} items" } },
- *       es: { greeting: "¡Hola, {name}!" },
- *     },
- *   });
+ *   Lookup chain: `t("nav.home", vars, { locale })` walks the
+ *   subtag-stripped chain (`pt-BR` → `pt`), then falls through to the
+ *   configured `fallbackLocale` and finally `defaultLocale` unless
+ *   `fallbackLocale: null` (strict "this locale or miss"). Plural-
+ *   shaped values use CLDR cardinal keys (`zero` / `one` / `two` /
+ *   `few` / `many` / `other`); `other` is mandatory and validated at
+ *   load. Ordinal plurals route through a separate `Intl.PluralRules({
+ *   type: "ordinal" })` cache via `to(key, count)`.
  *
- *   i.t("greeting", { name: "Alice" });               // → "Hello, Alice!"
- *   i.tn("items", 5);                                 // → "5 items"
- *   i.formatNumber(1234.5, { style: "currency", currency: "USD" });
- *   i.formatRelative(-5, "minute");                   // → "5 minutes ago"
+ *   Translation file format (JSON loaded eagerly from `opts.dir` or
+ *   inline via `opts.translations`):
  *
- *   router.use(i.middleware());
- *   // ...later
- *   res.locals.t("greeting", { name: req.user.name });
+ *     {
+ *       "greeting": "Hello, {name}!",
+ *       "items":   { "one": "{count} item", "other": "{count} items" },
+ *       "nav":     { "home": "Home", "about": "About" }
+ *     }
  *
- * Translation file format (JSON):
+ *   ICU MessageFormat (`{name, plural, ...}` / `{name, select, ...}` /
+ *   `{name, selectordinal, ...}`) is auto-detected by `t()`; operators
+ *   force the path with `t(key, vars, { messageFormat: true })`. The
+ *   companion `b.i18n.messageFormat` namespace exposes the parser /
+ *   formatter for use outside an instance.
  *
- *   {
- *     "greeting": "Hello, {name}!",
- *     "items":   { "one": "{count} item", "other": "{count} items" },
- *     "nav":     { "home": "Home", "about": "About" }
- *   }
+ *   Validation policy:
+ *     - `create()` throws on bad opts (boot).
+ *     - Bad BCP 47 locale at any boundary → throw at call site.
+ *     - `t(missingKey)` → return the key + emit `i18n.missing`
+ *       observability event (never throws unless `missingKey: "throw"`).
+ *     - Plural shape missing `other` → throw at load time.
+ *     - Missing interpolation var renders as literal `{var}` unless
+ *       `interpolation.strict: true`.
+ *     - `formatNumber` / `formatDate` / `formatRelative` / `formatList`
+ *       throw at call site on a non-finite value or unparseable date.
+ *     - Middleware `Accept-Language` parse error falls back to the
+ *       default locale; the request never crashes on a bad header.
  *
- *   - Plural-shaped values use CLDR cardinal keys (zero/one/two/few/
- *     many/other). `other` is mandatory — caught at load.
- *   - Nested keys use dotted paths in t() (e.g. "nav.home").
- *   - {var} interpolation; missing vars render as literal {var} unless
- *     `interpolation.strict: true`.
+ *   Security stance: translation values come from operator-controlled
+ *   files, not user input. `{var}` interpolation does NOT html-escape;
+ *   `b.template` already escapes at render time. For non-template
+ *   contexts, pass `interpolation.escape: fn`.
  *
- * Validation policy:
- *
- *   - create() opts                           → throw at boot
- *   - bad locale tag at any boundary          → throw at call site
- *   - t(missingKey)                           → return key + observability event
- *   - t() with bad locale override            → throw at call site (programming bug)
- *   - plural shape missing 'other'            → throw at load time
- *   - interpolation missing var               → render literal {var}
- *   - format* bad input                       → throw at call site
- *   - middleware Accept-Language parse error  → fall back to defaultLocale
- *
- * Security stance: translation values come from operator-controlled
- * files, not user input. {var} interpolation does NOT html-escape;
- * `b.template` already escapes when rendered. Operators using t() in
- * non-template contexts pass `interpolation.escape`.
- *
- * No audit-chain integration: i18n is not operator-action shaped (no
- * state mutation). Routing observability events (missing key, locale
- * fallback, formatter cache misses) is enough.
+ * @card
+ *   ICU MessageFormat + CLDR Plural Rules + locale-aware Intl formatters with translation lookup.
  */
 
 var fs = require("node:fs");
@@ -371,6 +369,61 @@ function _makeFormatterCache(make, kind, emitObs) {
 
 // ---- Public create ----
 
+/**
+ * @primitive b.i18n.create
+ * @signature b.i18n.create(opts)
+ * @since     0.6.0
+ * @status    stable
+ * @related   b.template.render
+ *
+ * Build an i18n instance bound to a fixed `locales` set. The returned
+ * object exposes translation (`t` / `tn` / `to` / `has`), Intl
+ * formatters (`formatNumber` / `formatDate` / `formatRelative` /
+ * `formatList` / `displayName`), locale state (`setLocale` /
+ * `locale` / `locales()` / `dir()`), translation introspection
+ * (`translations(locale)`), and an Express-shaped `middleware()` that
+ * negotiates the request locale (resolver → query → cookie →
+ * `Accept-Language`) and binds `req.t` / `req.tn` / `req.to` /
+ * `req.dir` / `res.locals.t` etc. for handlers.
+ *
+ * Throws `I18nError` at boot on a malformed locale tag, a
+ * `defaultLocale` not present in `locales`, a plural-shaped entry
+ * missing `other`, an unknown CLDR plural key, or a missing
+ * translation file when `dir` is supplied without `lazyLoad`.
+ *
+ * @opts
+ *   defaultLocale:   string,                       // BCP 47 tag; required, must appear in locales
+ *   locales:         [string],                     // BCP 47 tags; required, non-empty
+ *   fallbackLocale:  string | null,                // null = strict; default = defaultLocale
+ *   translations:    { [locale: string]: object }, // inline trees (mutually exclusive with dir)
+ *   dir:             string,                       // load <dir>/<locale>.json (mutually exclusive with translations)
+ *   eagerLocales:    [string],                     // with lazyLoad: which locales to load at create
+ *   lazyLoad:        boolean,                      // with dir: load other locales on first lookup; default false
+ *   interpolation:   { start?: string, end?: string, escape?: fn, strict?: boolean },
+ *   missingKey:      "return-key" | "throw" | (key, locale) => string,
+ *   onMissingKey:    (key, locale) => void,        // observability hook (best-effort)
+ *   rtlLanguages:    [string],                     // override the framework default RTL list
+ *   observability:   { event: (name, value, labels) => void },
+ *   clock:           () => number,                 // ms-since-epoch override (testing)
+ *
+ * @example
+ *   var i = b.i18n.create({
+ *     defaultLocale: "en",
+ *     locales:       ["en", "es", "fr", "ja", "ar"],
+ *     translations: {
+ *       en: { greeting: "Hello, {name}!", items: { one: "{count} item", other: "{count} items" } },
+ *       es: { greeting: "Hola, {name}!" },
+ *     },
+ *   });
+ *
+ *   i.t("greeting", { name: "Alice" });                                 // → "Hello, Alice!"
+ *   i.tn("items", 5);                                                   // → "5 items"
+ *   i.t("greeting", { name: "Ana" }, { locale: "es" });                 // → "Hola, Ana!"
+ *   i.formatNumber(1234.5, { style: "currency", currency: "USD" });     // → "$1,234.50"
+ *   i.formatRelative(-5, "minute");                                     // → "5 minutes ago"
+ *   i.dir({ locale: "ar" });                                            // → "rtl"
+ *   i.has("nav.missing");                                               // → false
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/iab-mspa.js

@@ -1,41 +1,30 @@
 "use strict";
 /**
- * b.iabMspa — IAB Multi-State Privacy Agreement / Global Privacy
- * Platform (GPP) universal opt-out signal codec.
+ * @module b.iabMspa
+ * @nav    Compliance
+ * @title  IAB MSPA
  *
- * GPP (https://github.com/InteractiveAdvertisingBureau/Global-
- * Privacy-Platform) is the IAB's successor to the patchwork of
- * per-state US privacy strings. A GPP string carries multiple
- * sections separated by `~`, each tagged with a section ID. The
- * MSPA-relevant sections are the US national + state sections
- * (USNAT, USCA, USVA, USCO, USCT, USUT) carrying:
+ * @intro
+ *   IAB Multi-State Privacy Agreement signal — encode/decode opt-out
+ *   preferences for state privacy laws (CCPA, CPA, etc.).
  *
- *   - SaleOptOut, SharingOptOut, TargetedAdvertisingOptOut, Sensitive-
- *     DataProcessingOptOuts, KnownChildSensitiveData
- *   - GPC (Global Privacy Control browser signal mirror)
- *   - MSPA service-provider / opted-in flags
+ *   The IAB Global Privacy Platform (GPP) is the successor to the
+ *   patchwork of per-state US privacy strings. A GPP string carries
+ *   multiple sections separated by `~`, each tagged with a section
+ *   ID. The MSPA-relevant sections cover the US national + state
+ *   regimes (USNAT, USCA, USVA, USCO, USCT, USUT, plus 2025-26
+ *   additions) and carry sale / sharing / targeted-ads /
+ *   sensitive-data / child-data opt-out flags alongside the W3C
+ *   `Sec-GPC` browser-signal mirror.
  *
- * Public API:
+ *   The framework ships a partial-correct decoder (the binary tag
+ *   layout is operator-side via the IAB's gpp-cmp libraries), an
+ *   opt-out evaluator that returns `mustHonor` across in-scope
+ *   sections, a throw-on-must-honor refusal helper, and a header
+ *   reader for the `Sec-GPC: 1` universal opt-out signal.
  *
- *   b.iabMspa.parseGpp(gppString) -> { header, sections }
- *     header:  { version, sectionIds[], gpcSignal? }
- *     sections: [{ id, optOuts: { sale, sharing, targetedAds, ... } }]
- *
- *   b.iabMspa.checkOptOut(parsed, opts) -> { mustHonor, signals }
- *     opts: { dataUse: "sale" | "sharing" | "targeted-ads" |
- *             "sensitive" | "child-data", state? }
- *     Returns mustHonor=true when ANY in-scope section signals an
- *     opt-out for the requested use; signals lists which section IDs
- *     produced the verdict.
- *
- *   b.iabMspa.refuseProcessing(parsed, opts)
- *     Throws IabMspaError when mustHonor → operator's data-flow code
- *     halts at the same point a CCPA "do-not-sell" header would.
- *
- *   b.iabMspa.gpcFromHeaders(req) -> bool
- *     Reads the W3C `Sec-GPC: 1` browser header (RFC draft-davidson-
- *     httpbis-gpc-00). Universal opt-out per California CCPA / CPRA
- *     §1798.135(b)(1) and Colorado, Connecticut, etc.
+ * @card
+ *   IAB Multi-State Privacy Agreement signal — encode/decode opt-out preferences for state privacy laws (CCPA, CPA, etc.).
  */
 
 var audit = require("./audit");
@@ -63,6 +52,26 @@ var SECTION_IDS = {
 var ALL_SECTIONS = Object.keys(SECTION_IDS).map(Number);
 var DATA_USES = ["sale", "sharing", "targeted-ads", "sensitive", "child-data"];
 
+/**
+ * @primitive b.iabMspa.parseGpp
+ * @signature b.iabMspa.parseGpp(gppString)
+ * @since     0.8.44
+ * @related   b.iabMspa.checkOptOut, b.iabMspa.refuseProcessing
+ *
+ * Parse the framing of a GPP string into `{ header, sections }`. The
+ * decoder splits on `~`, identifies each section by its positional
+ * claim in the header's section-ID list, and exposes the per-section
+ * raw payloads. The framework deliberately does not decode the
+ * binary section layout — operator-side libraries
+ * (`@iabtechlab/gpp-cmp`) own that surface and populate
+ * `section.optOuts`. Throws on missing input or strings exceeding
+ * the 8192-char defensive cap.
+ *
+ * @example
+ *   var parsed = b.iabMspa.parseGpp("DBABBg.7.8");
+ *   parsed.header.sectionIds;     // → [7, 8]
+ *   parsed.sections.length;       // → 0  (no payload segments yet)
+ */
 function parseGpp(gppString) {
   if (typeof gppString !== "string" || gppString.length === 0) {
     throw IabMspaError.factory("BAD_INPUT",
@@ -115,6 +124,37 @@ function parseGpp(gppString) {
   return { header: header, sections: sections };
 }
 
+/**
+ * @primitive b.iabMspa.checkOptOut
+ * @signature b.iabMspa.checkOptOut(parsed, opts)
+ * @since     0.8.44
+ * @related   b.iabMspa.parseGpp, b.iabMspa.refuseProcessing
+ *
+ * Walk the parsed GPP sections and return `{ mustHonor, signals }`
+ * for the requested data-use category. `mustHonor` is `true` when
+ * ANY in-scope section signals an opt-out for that use; `signals`
+ * lists the section labels that produced the verdict. Operators
+ * narrow the search to a specific state by passing `opts.state`.
+ * Sections whose `optOuts` field hasn't been populated by an
+ * operator-side decoder are skipped (no false positives from
+ * missing data).
+ *
+ * @opts
+ *   dataUse: "sale" | "sharing" | "targeted-ads" | "sensitive" | "child-data",
+ *   state:   string,                       // optional GPP section label
+ *
+ * @example
+ *   var parsed = {
+ *     header: { sectionIds: [8] },
+ *     sections: [
+ *       { id: 8, idLabel: "usca", raw: "",
+ *         optOuts: { sale: true, sharing: false, targetedAds: true } },
+ *     ],
+ *   };
+ *   var verdict = b.iabMspa.checkOptOut(parsed, { dataUse: "sale" });
+ *   verdict.mustHonor;   // → true
+ *   verdict.signals;     // → ["usca"]
+ */
 function checkOptOut(parsed, opts) {
   if (!parsed || typeof parsed !== "object" || !Array.isArray(parsed.sections)) {
     throw IabMspaError.factory("BAD_PARSED",
@@ -140,6 +180,28 @@ function checkOptOut(parsed, opts) {
   return { mustHonor: signals.length > 0, signals: signals };
 }
 
+/**
+ * @primitive b.iabMspa.refuseProcessing
+ * @signature b.iabMspa.refuseProcessing(parsed, opts)
+ * @since     0.8.44
+ * @related   b.iabMspa.checkOptOut, b.iabMspa.parseGpp
+ *
+ * Throw `IabMspaError` when `checkOptOut` returns `mustHonor:true`
+ * — wires the framework's opt-out signal into the operator's
+ * data-flow code at the same point a CCPA do-not-sell header would
+ * halt processing. Audits the refusal under
+ * `iabmspa.processing_refused` before throwing. Returns the verdict
+ * object on the no-opt-out path so the caller can inspect signals.
+ *
+ * @opts
+ *   dataUse: "sale" | "sharing" | "targeted-ads" | "sensitive" | "child-data",
+ *   state:   string,                       // optional GPP section label
+ *
+ * @example
+ *   var parsed = { header: { sectionIds: [] }, sections: [] };
+ *   var verdict = b.iabMspa.refuseProcessing(parsed, { dataUse: "sale" });
+ *   verdict.mustHonor;   // → false  (no signals → no throw)
+ */
 function refuseProcessing(parsed, opts) {
   var rv = checkOptOut(parsed, opts);
   if (rv.mustHonor) {
@@ -159,6 +221,24 @@ function refuseProcessing(parsed, opts) {
   return rv;
 }
 
+/**
+ * @primitive b.iabMspa.gpcFromHeaders
+ * @signature b.iabMspa.gpcFromHeaders(req)
+ * @since     0.8.44
+ * @related   b.iabMspa.checkOptOut, b.iabMspa.refuseProcessing
+ *
+ * Read the W3C `Sec-GPC: 1` browser header from an inbound request.
+ * Returns `true` when the user's browser is asserting the universal
+ * opt-out signal (mandatory under California CCPA / CPRA
+ * §1798.135(b)(1) and Colorado, Connecticut, etc.). Defensive
+ * against missing `req`/`headers` shapes — never throws.
+ *
+ * @example
+ *   var req = { headers: { "sec-gpc": "1" } };
+ *   b.iabMspa.gpcFromHeaders(req);              // → true
+ *   b.iabMspa.gpcFromHeaders({ headers: {} });  // → false
+ *   b.iabMspa.gpcFromHeaders(null);             // → false
+ */
 function gpcFromHeaders(req) {
   if (!req || !req.headers) return false;
   var h = req.headers["sec-gpc"];

package/lib/iab-tcf.js

@@ -1,7 +1,40 @@
 "use strict";
 /**
- * b.iabTcf — IAB Europe Transparency & Consent Framework v2.3 consent
- * string parser + disclosedVendors validator.
+ * @module b.iabTcf
+ * @nav    Compliance
+ * @title  IAB TCF
+ *
+ * @intro
+ *   IAB Transparency & Consent Framework v2.3 — TCF string
+ *   parse/encode, vendor list lookup, purpose & special-feature
+ *   checks.
+ *
+ *   Required by TCF Policy v2.3 §III.B.5 (CMP MUST signal which
+ *   vendors received disclosure regardless of consent state).
+ *   Deadline 2026-02-28 is past — Google Ads + every major DSP
+ *   rejects v2.2-shaped strings since that date. EU/UK adtech
+ *   operators that didn't migrate are losing inventory.
+ *
+ *   Consent-string format (TCF v2.3 spec, §A): base64url-no-pad of
+ *   segments separated by `.`:
+ *   `Core | DisclosedVendors | (AllowedVendors) | PublisherTC`.
+ *   Core carries cmpVersion=2, version=4 (TCF v2.3),
+ *   created/lastUpdated, cmpId, vendorListVersion,
+ *   policyVersion=4, special-feature-opts-in, purpose-consents,
+ *   purpose-LIs, vendor-consents bitmap, vendor-LIs bitmap,
+ *   publisher restrictions. DisclosedVendors is REQUIRED in v2.3.
+ *
+ *   The framework does NOT bundle the IAB Global Vendor List —
+ *   operators fetch the versioned JSON from
+ *   https://vendor-list.consensu.org/v3/vendor-list.json and use
+ *   `parsed.core.vendorListVersion` to load the matching cache
+ *   entry.
+ *
+ * @card
+ *   IAB Transparency & Consent Framework v2.3 — TCF string parse/encode, vendor list lookup, purpose & special-feature checks.
+ */
+/*
+ * Original prose retained:
  *
  * Required by TCF Policy v2.3 §III.B.5 (CMP MUST signal which vendors
  * received disclosure regardless of consent state). Deadline 2026-02-28
@@ -205,6 +238,28 @@ function _parseSecondaryVendorSegment(buf, expectedType) {
   return _parseVendorSection(r);
 }
 
+/**
+ * @primitive b.iabTcf.parseString
+ * @signature b.iabTcf.parseString(tcString)
+ * @since     0.8.0
+ * @status    stable
+ * @compliance iab-tcf
+ * @related   b.iabTcf.requireV23Disclosed, b.iabTcf.checkVendor
+ *
+ * Defensively parse a TCF v2.3 consent string (Core + optional
+ * DisclosedVendors / AllowedVendors / PublisherTC segments).
+ * Refuses non-string input, refuses payloads above 64 KiB, and
+ * caps every bit-field to spec-declared widths. Returns a
+ * structured object; per-segment decode failures land in
+ * `errors[]` instead of throwing so a partial parse still serves.
+ *
+ * @example
+ *   var parsed = b.iabTcf.parseString("CPXxRfAPXxRfAAfKABENB-CgAP_AAH_AAA");
+ *   parsed.core.version;
+ *   // → 4
+ *   parsed.errors;
+ *   // → []
+ */
 function parseString(tcString) {
   if (typeof tcString !== "string" || tcString.length === 0) {
     throw IabTcfError.factory("BAD_INPUT",
@@ -261,6 +316,34 @@ function parseString(tcString) {
   };
 }
 
+/**
+ * @primitive b.iabTcf.requireV23Disclosed
+ * @signature b.iabTcf.requireV23Disclosed(tcString, opts)
+ * @since     0.8.0
+ * @status    stable
+ * @compliance iab-tcf
+ * @related   b.iabTcf.parseString, b.iabTcf.checkVendor
+ *
+ * Hard gate the operator wires upstream of every ad-bidder
+ * forward. Throws `IabTcfError` when the core/policy version is
+ * not 4 (i.e. a v2.2 string), when the DisclosedVendors segment
+ * is absent (mandatory since 2026-02-28 per TCF Policy v2.3
+ * §III.B.5), or when base64url decoding fails. Emits
+ * `iabtcf.refused` / `iabtcf.accepted` to the audit chain so the
+ * regulator-facing record exists per request.
+ *
+ * @opts
+ *   audit: boolean,   // default true — emit accept/refuse audit events
+ *
+ * @example
+ *   try {
+ *     var parsed = b.iabTcf.requireV23Disclosed("CPXxRfAPXxRfAAfKABENB-CgAP_AAH_AAA");
+ *     parsed.disclosedVendors.present;
+ *     // → true
+ *   } catch (e) {
+ *     // refuse the ad request
+ *   }
+ */
 function requireV23Disclosed(tcString, opts) {
   opts = opts || {};
   var auditOn = opts.audit !== false;
@@ -329,6 +412,28 @@ function requireV23Disclosed(tcString, opts) {
   return parsed;
 }
 
+/**
+ * @primitive b.iabTcf.checkVendor
+ * @signature b.iabTcf.checkVendor(parsed, vendorId)
+ * @since     0.8.0
+ * @status    stable
+ * @compliance iab-tcf
+ * @related   b.iabTcf.parseString, b.iabTcf.requireV23Disclosed
+ *
+ * Lookup a vendor id in a parsed TCF object. Returns three flags:
+ * `consented` (vendor in `vendorConsents`), `legitimate` (vendor
+ * in `vendorLIs`), `disclosed` (vendor in DisclosedVendors).
+ * Throws `IabTcfError` for malformed `parsed` or non-positive
+ * vendorId.
+ *
+ * @example
+ *   var parsed = b.iabTcf.parseString("CPXxRfAPXxRfAAfKABENB-CgAP_AAH_AAA");
+ *   var verdict = b.iabTcf.checkVendor(parsed, 755);
+ *   verdict.consented;
+ *   // → false
+ *   verdict.disclosed;
+ *   // → false
+ */
 function checkVendor(parsed, vendorId) {
   if (!parsed || !parsed.core) {
     throw IabTcfError.factory("BAD_PARSED",

package/lib/inbox.js

@@ -1,62 +1,45 @@
 "use strict";
 /**
- * b.inbox — transactional dedupe-on-receive.
+ * @module b.inbox
+ * @nav    Production
+ * @title  Inbox
  *
- * Companion to `b.outbox`. Where outbox guarantees at-least-once
- * delivery, inbox lets the receiver guarantee exactly-once handling
- * by recording every (source, messageId) pair in the same transaction
- * as the business state change. If the same event is delivered twice
- * (network retry, replay, broker re-dispatch on consumer failure),
- * the second handler refuses with a duplicate-key constraint and the
- * application sees a clean short-circuit.
+ * @intro
+ *   Transactional dedupe-on-receive for inbound message handlers.
+ *   Companion to `b.outbox`: where outbox guarantees at-least-once
+ *   delivery, inbox lets the receiver guarantee exactly-once handling
+ *   by recording every `(source, messageId)` pair in the same database
+ *   transaction as the business state change. A duplicate redelivery
+ *   (network retry, replay, broker re-dispatch on consumer failure)
+ *   collides with the primary-key constraint and the second handler
+ *   short-circuits cleanly.
  *
- *   var inbox = b.inbox.create({
- *     externalDb:    b.externalDb,
- *     table:         "inbox_events",
- *     retentionDays: 30,                 // sweep older rows
- *     audit:         true,
- *   });
- *
- *   // High-level API — recommended for most callers:
- *   await inbox.handle({
- *     messageId: kafkaEvent.headers["x-event-id"],
- *     source:    "kafka:orders.created.v1",
- *     payload:   kafkaEvent.payload,                // optional, audit only
- *   }, async function (xdb) {
- *     // Business state change runs exactly once per (source, messageId).
- *     await xdb.query("INSERT INTO orders ...", [...]);
- *   });
+ *   Schema (declared via `declareSchema(externalDb)`): `message_id
+ *   TEXT`, `source TEXT`, `received_at TIMESTAMP`, `processed_at
+ *   TIMESTAMP NULL`, `metadata_json JSONB|TEXT`, with `PRIMARY KEY
+ *   (source, message_id)`. Postgres uses `ON CONFLICT … DO NOTHING
+ *   RETURNING` to decide fresh-vs-duplicate in one round-trip; SQLite
+ *   3.35+ uses `INSERT OR IGNORE … RETURNING 1` to avoid the
+ *   `changes()` race when callers issue intervening statements on the
+ *   same transaction handle.
  *
- *   // Low-level API — operator manages the transaction directly:
- *   await b.externalDb.transaction(async function (xdb) {
- *     var fresh = await inbox.recordReceive({
- *       messageId: id, source: "kafka:orders.created",
- *     }, xdb);
- *     if (!fresh) return;                             // duplicate; skip
- *     await xdb.query("INSERT INTO orders ...", [...]);
- *   });
- *
- *   // Schema:
- *   await inbox.declareSchema(b.externalDb);
- *
- *   // Periodic retention sweep (operator wires their scheduler):
- *   await inbox.sweep();
- *
- * Schema columns:
+ *   Defenses on the input side: `messageId` and `source` are bounded
+ *   in length (default 256 chars each) and rejected for NUL / C0 /
+ *   DEL control characters before they reach the primary key — Postgres
+ *   TEXT may truncate at NUL, opening a dedupe-collision attack where
+ *   `"abc\\0attacker"` and `"abc"` collide. `metadata` is JSON-
+ *   serialized through `safeJson` and capped at `maxPayloadBytes`
+ *   (default 64 KiB).
  *
- *   message_id     TEXT     — primary part of the dedupe tuple
- *   source         TEXT     — namespace (kafka topic, queue name, ...)
- *   received_at    TIMESTAMP
- *   processed_at   TIMESTAMP NULL  — set when handle() commits
- *   metadata_json  JSONB / TEXT (operator-supplied audit blob)
+ *   Two APIs: high-level `handle(opts, handler)` opens a transaction,
+ *   records receive, runs the handler exactly once when fresh, marks
+ *   processed, commits — recommended for most callers. Low-level
+ *   `recordReceive(opts, txn)` lets operators manage the transaction
+ *   directly when they need fine-grained control over what runs in
+ *   the dedupe envelope.
  *
- *   PRIMARY KEY (source, message_id)  — enforces idempotence.
- *
- * Picking semantics:
- *   - Postgres backends: ON CONFLICT (source, message_id) DO NOTHING
- *     RETURNING * lets `recordReceive` decide fresh vs duplicate in
- *     a single round-trip.
- *   - SQLite: INSERT OR IGNORE + SELECT changes() to test fresh-ness.
+ * @card
+ *   Transactional dedupe-on-receive for inbound message handlers.
  */
 
 var C = require("./constants");
@@ -90,6 +73,61 @@ function _utcNowExpr(externalDb) {
   return "CURRENT_TIMESTAMP";
 }
 
+/**
+ * @primitive b.inbox.create
+ * @signature b.inbox.create(opts)
+ * @since     0.8.48
+ * @status    stable
+ * @related   b.outbox, b.externalDb, b.audit
+ *
+ * Build an inbox dedupe-store. Returns
+ * `{ declareSchema, recordReceive, markProcessed, handle, sweep,
+ * isFresh, getStats, table, retentionDays }`. Operators call
+ * `declareSchema` once at boot, `handle` per inbound message, and
+ * `sweep` periodically (under their own scheduler) to age out
+ * processed rows past retention.
+ *
+ * @opts
+ *   externalDb:      Object,   // b.externalDb instance (transaction()-shaped)
+ *   table:           string,   // SQL identifier; required
+ *   retentionDays:   number,   // sweep horizon (default 30); unprocessed rows kept 2x as long
+ *   audit:           boolean,  // emit inbox.* audit events (default true)
+ *   maxPayloadBytes: number,   // metadata serialized cap (default 64 KiB)
+ *   messageIdMaxLen: number,   // chars (default 256)
+ *   sourceMaxLen:    number,   // chars (default 256)
+ *
+ * @example
+ *   var inbox = b.inbox.create({
+ *     externalDb:    externalDbInstance,
+ *     table:         "inbox_events",
+ *     retentionDays: 30,
+ *   });
+ *
+ *   await inbox.declareSchema(externalDbInstance);
+ *
+ *   var outcome = await inbox.handle({
+ *     messageId: "evt-9f3c4d",
+ *     source:    "kafka:orders.created.v1",
+ *   }, async function (xdb) {
+ *     await xdb.query("INSERT INTO orders (id) VALUES ($1)", ["o-42"]);
+ *     return { orderId: "o-42" };
+ *   });
+ *   outcome.fresh;             // → true on first delivery, false on replay
+ *   outcome.result.orderId;    // → "o-42"
+ *
+ *   // Replay short-circuits:
+ *   var replay = await inbox.handle({
+ *     messageId: "evt-9f3c4d", source: "kafka:orders.created.v1",
+ *   }, async function () { return { orderId: "should-not-run" }; });
+ *   replay.fresh;              // → false
+ *   replay.result;             // → null
+ *
+ *   var stats = await inbox.getStats({ source: "kafka:orders.created.v1" });
+ *   stats.total;               // → 1
+ *   stats.processed;           // → 1
+ *
+ *   var deleted = await inbox.sweep();   // age out beyond retention
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [