@blamejs/core 0.7.104 → 0.7.105

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.7.x
 
+- **0.7.105** (2026-05-06) — `b.compliance.sanctions` — sanctions-list screening primitive. Operators handling KYC / payment / customer-onboarding flows screen names against the U.S. Treasury OFAC SDN list, EU CSL, UK HMT consolidated list, UN 1267 list, or operator-defined lists. The framework owns indexing + match algorithm; the operator owns the daily fetch + format-specific parsing (the framework intentionally does not vendor the list — it changes daily and has legal-distribution implications). **`b.compliance.sanctions.create({ entries, algorithm, fuzzy, ... })`** returns a screener with `screen(input)` (single record), `screenBulk(inputs)` (batch), `snapshot()` (rule-version digest for audit trails), `reload(newEntries)` (atomic index swap with diff), `entryById(id)` (lookup), and `size()`. Three match strategies: `exact` (fastest, no fuzz), `jaro-winkler` (default, threshold 0.85), `levenshtein` (edit-distance with cap). Match output: `{ match: bool, hits: [{ entryId, name, matchedOn, score, reason, listed, programs }], algorithm, ruleVersion, screenedAt }`. **`b.compliance.sanctions.fuzzy`** — pure algorithmic core: `normalize` (Unicode diacritic strip + lowercase + whitespace collapse), `tokenize`, `levenshtein` (cap + early-exit), `jaro` / `jaroWinkler`, `tokenSetSimilarity` (order-invariant bag-of-tokens), `substringContains` (token-bounded), `initialsMatch`. **`b.compliance.sanctions.aliases.expand(name, opts)`** — alias-expansion helper covering nicknames (Bill ↔ William, Mike ↔ Michael), transliteration variants (Mohamed ↔ Mohammed), reverse-order forms (Smith John / Smith, John), and initials (J. Smith). 32 built-in name pairs plus operator-extensible `extraPairs`. **`b.compliance.sanctions.fetcher.create({ screener, fetch, intervalMs, onRefreshed, onError })`** — periodic refresh worker that runs the operator's `fetch` callback, validates a non-empty result, and atomically reloads the screener via `screener.reload`. Audit emissions on every refresh state (`compliance.sanctions.refresh.started` / `completed` / `skipped` / `failed`). **Parser shims** for the canonical public list formats: `parseOfacCsvRow` / `parseOfacAliasRow` / `mergeAliases` (OFAC SDN), `parseEuCslEntry` (EU Consolidated Sanctions List XML), `parseUn1267Entry` (UN Security Council XML). Audit emissions: `compliance.sanctions.screened` (every screen call), `compliance.sanctions.matched` (when hits > 0). Test coverage: 39 cases across normalize / tokenize / Levenshtein / Jaro-Winkler / token-set / substring / initials / screen exact + jw + levenshtein / type filter / bulk / snapshot / reload / alias expansion / fetcher tick + failure modes.
+
 - **0.7.104** (2026-05-06) — `b.dsr` Data Subject Rights workflow primitive (~2000 LoC). End-to-end coordinator for GDPR Article 15-22 / CCPA / CPRA / LGPD / PIPEDA / UK-GDPR data-subject requests. **`b.dsr.create({ ticketStore, posture, identityResolver, sources, ... })`** returns a workflow instance with full ticket lifecycle: `submit(input)` resolves subject identity via the operator-supplied `identityResolver`, computes a posture-aware deadline (gdpr 30d / ccpa 45d / lgpd-br 15d / pipl-cn 15d / pipeda-ca 30d / appi-jp 30d / pdpa-sg 30d / uk-gdpr 30d), and persists a pending ticket. `process(ticketId, opts)` orchestrates per-source `query` (for access / portability / rectification) or `erase` (for erasure) callbacks; partial source failures land the ticket in `partially_completed` state with per-source error capture. `cancel` / `reject` (with required reason per GDPR) advance to terminal states. `expireOverdue()` sweep marks deadline-overdue tickets as `expired`. Seven request types: `access` / `erasure` / `portability` / `rectification` / `restriction` / `object` / `automated-decision`. **Verification ladder** (`minimal` / `secondary` / `strong`) per GDPR Art. 12(6) — minimum required level by request type with operator override; erasure / portability / rectification require `secondary` by default. **Receipt builder** (`buildReceipt(ticketId)`) — emits a canonical `blamejs.dsr.receipt/1` JSON envelope for completed/cancelled/rejected/expired tickets with optional operator-side `receiptSigner` hook for cryptographic attestation. **Portability bundle builder** (`buildPortabilityBundle(ticket)`) — `blamejs.dsr.portability/1` JSON shape with per-source data for access / portability requests. **Two ticket-store backends** ship: `memoryTicketStore()` for development / tests, `dbTicketStore({ db, table })` for production (auto-provisions a SQLite table with subject_email + status indexes, includes a `purgeExpired()` retention sweep). Audit emissions on every state transition (`dsr.ticket.submitted` / `in_progress` / `completed` / `partial` / `cancelled` / `rejected` / `expired` plus per-source `dsr.source.queried` / `erased` / `failed`). Test coverage: 38 cases across submit / process / cancel / reject / list / expire / portability / verification ladder / receipt / store backends.
 
 - **0.7.103** (2026-05-06) — W3C distributed tracing suite. End-to-end OTel-shaped tracing without a vendored OTel SDK: tracestate + Baggage parsers, span builder, OTLP/JSON exporter, HTTP-server span middleware, log correlation. **`b.observability.traceContext.parseTracestate / buildTracestate`** — W3C Trace Context §3.3 vendor data: enforces vendor-key shape (lcase-alnum + `_-*/`, optional `<tenant>@<system>`), value charset (printable ASCII excluding `,` and `=`), 32-entry cap, 512-char total cap, dup-key-keep-first per §3.3.1.5. **`b.observability.baggage.parse / build`** — W3C Baggage spec parser + builder for operator-supplied context (tenantId, region, experimentId, etc.) propagated across service boundaries. RFC 7230 tchar key grammar, percent-encoded UTF-8 values, optional per-entry properties (`key=value;property=value`), 64-entry / 8192-char caps. **`b.observability.tracer.create({ service, resource, onEnd })`** — OTel-shaped span builder. `tracer.start(name, opts)` returns a span with `setAttribute` / `setAttributes` / `addEvent` / `recordException` / `setStatus` / `end` / `isRecording` / `toJSON`. OTLP/JSON-compatible output (Trace v1) with `traceId` / `spanId` / `parentSpanId` / `name` / `kind` / `startTimeUnixNano` / `endTimeUnixNano` / `attributes` / `events` / `status` / `resource` / `scope` / `droppedAttributesCount` / `droppedEventsCount`. Attribute caps (128 keys, 1024-char values), event cap (128) per OTLP defaults. `tracer.startChildOf(parent, name)` derives child spans sharing the trace context. **`b.observability.tracer.spanToTraceparent(span)`** — emits the canonical W3C `traceparent` for outbound propagation. **`b.observability.otlpExporter.create({ endpoint, ... })`** — buffered OTLP/HTTP JSON span exporter. Batches spans (default 200), flushes on size + interval (default 5s), retries 5xx + 408/429 with exponential backoff, drops oldest on queue overflow (default 4096). Custom `fetchImpl` opt for testing or non-default HTTP transports; `allowedProtocols` opt for cleartext dev collectors. **`b.middleware.tracePropagate`** extended to also read inbound `tracestate` and stamp `req.trace.tracestate` as the parsed entries array (or `[]` when missing); when `setResponseHeader: true`, echoes both `traceparent` and `tracestate` on the response. **`b.middleware.spanHttpServer({ tracer, ... })`** — auto-creates a root server span per HTTP request, populates OTel `SEMCONV.HTTP_*` / `URL_*` / `SERVER_*` / `CLIENT_*` attributes, attaches the span to `req.span`, ends on response close, fires `onEnd(span.toJSON())` for export. `ignorePaths` (string + RegExp) keeps healthz / static-asset routes out of span volume; `captureRequestHeaders` / `captureResponseHeaders` lift named headers into the span as `http.request.header.*` / `http.response.header.*` attributes. **`b.middleware.traceLogCorrelation({ logger })`** — wraps a `b.log` instance for the request lifetime so every `info()` / `warn()` / `error()` / etc. emission inside the handler auto-includes `trace_id` + `span_id` from the active context (via `req.trace` + `req.span`). Pass-through when no trace context present. Internal sweep: `safeBuffer.TRACE_ID_HEX_RE` / `SPAN_ID_HEX_RE` / `RFC7230_TCHAR_RE` extracted as shared regex constants; `guard-mime` / `middleware/headers` / `observability` consolidated against the new shared constants.

package/lib/compliance-sanctions-aliases.js

@@ -0,0 +1,167 @@
+"use strict";
+/**
+ * Alias-expansion helpers for sanctions screening.
+ *
+ * The OFAC SDN list / EU CSL / UK HMT consolidated list publish a
+ * primary name + a small set of formal aliases per entry. Real-world
+ * input doesn't match those forms exactly: people use nicknames
+ * (Bill / William, Mike / Michael), transliteration variants
+ * (Mohamed / Mohammed / Muhammad), and initials (J. Smith).
+ *
+ * This module expands a candidate name into the set of plausible
+ * forms that should screen-match against the same SDN entry. Operators
+ * call expand() before screen() to broaden the match scope:
+ *
+ *   var aliases = b.compliance.sanctions.aliases.expand("Bill J. Smith");
+ *   var result = screener.screen({
+ *     name:    "Bill J. Smith",
+ *     aliases: aliases,
+ *   });
+ *
+ * The expansion is deterministic + idempotent. Operators with
+ * domain-specific names (Cyrillic / Arabic) extend via opts.extra.
+ */
+
+var fuzzy = require("./compliance-sanctions-fuzzy");
+
+// Common nickname → formal-name pairs. The framework ships a focused
+// table for English/European names; operators with non-Western lists
+// extend via opts.extraPairs at expand() time.
+var NICKNAME_PAIRS = Object.freeze([
+  ["bill",     "william"],
+  ["bob",      "robert"],
+  ["dick",     "richard"],
+  ["mike",     "michael"],
+  ["nick",     "nicholas"],
+  ["tom",      "thomas"],
+  ["jim",      "james"],
+  ["jack",     "john"],
+  ["chris",    "christopher"],
+  ["dan",      "daniel"],
+  ["dave",     "david"],
+  ["matt",     "matthew"],
+  ["alex",     "alexander"],
+  ["sam",      "samuel"],
+  ["pat",      "patrick"],
+  ["tony",     "anthony"],
+  ["ben",      "benjamin"],
+  ["joe",      "joseph"],
+  ["ed",       "edward"],
+  ["fred",     "frederick"],
+  ["greg",     "gregory"],
+  ["liz",      "elizabeth"],
+  ["beth",     "elizabeth"],
+  ["meg",      "margaret"],
+  ["maggie",   "margaret"],
+  ["kate",     "katherine"],
+  ["kathy",    "katherine"],
+  ["sue",      "susan"],
+  ["jen",      "jennifer"],
+  ["jenny",    "jennifer"],
+  ["nat",      "natalie"],
+  ["mohamed",  "mohammed"],
+  ["muhammad", "mohammed"],
+  ["abd",      "abdul"],
+  ["abu",      "abou"],
+  ["yusuf",    "yousef"],
+  ["yasin",    "yaseen"],
+  ["hussein",  "hussain"],
+]);
+
+function _expandNickname(token) {
+  var alts = [];
+  var lower = token.toLowerCase();
+  for (var i = 0; i < NICKNAME_PAIRS.length; i++) {
+    var pair = NICKNAME_PAIRS[i];
+    if (lower === pair[0]) alts.push(pair[1]);
+    else if (lower === pair[1]) alts.push(pair[0]);
+  }
+  return alts;
+}
+
+function _expandInitials(tokens) {
+  // Build "J. Smith" / "JS" forms
+  var alts = [];
+  if (tokens.length >= 2) {
+    var first = tokens[0];
+    var rest = tokens.slice(1).join(" ");
+    if (first.length > 1) {
+      // J Smith / J. Smith
+      alts.push(first.charAt(0) + " " + rest);
+      alts.push(first.charAt(0) + ". " + rest);
+    }
+    // Last + first
+    alts.push(tokens[tokens.length - 1] + " " + tokens.slice(0, -1).join(" "));
+    // Last, First
+    alts.push(tokens[tokens.length - 1] + ", " + tokens.slice(0, -1).join(" "));
+  }
+  if (tokens.length === 2) {
+    // Initials-only "JS"
+    alts.push(tokens[0].charAt(0) + tokens[1].charAt(0));
+  }
+  return alts;
+}
+
+function _expandTokenLevel(tokens) {
+  // For each token, swap with each plausible nickname/transliteration,
+  // emit the resulting full name.
+  var alts = [];
+  for (var i = 0; i < tokens.length; i++) {
+    var swaps = _expandNickname(tokens[i]);
+    for (var j = 0; j < swaps.length; j++) {
+      var newTokens = tokens.slice();
+      newTokens[i] = swaps[j];
+      alts.push(newTokens.join(" "));
+    }
+  }
+  return alts;
+}
+
+function expand(name, opts) {
+  opts = opts || {};
+  if (typeof name !== "string" || name.length === 0) return [];
+  var tokens = fuzzy.tokenize(name);
+  if (tokens.length === 0) return [];
+  var seen = Object.create(null);
+  var out = [];
+  function _add(s) {
+    if (typeof s !== "string" || s.length === 0) return;
+    var key = fuzzy.normalize(s);
+    if (key.length === 0) return;
+    if (seen[key]) return;
+    seen[key] = true;
+    out.push(s);
+  }
+  // 1. The original (normalised)
+  _add(tokens.join(" "));
+  // 2. Initial-form variants
+  var initials = _expandInitials(tokens);
+  for (var i = 0; i < initials.length; i++) _add(initials[i]);
+  // 3. Token-level nickname/transliteration swaps
+  var swaps = _expandTokenLevel(tokens);
+  for (var j = 0; j < swaps.length; j++) _add(swaps[j]);
+  // 4. Operator-supplied extras
+  if (Array.isArray(opts.extra)) {
+    for (var k = 0; k < opts.extra.length; k++) _add(opts.extra[k]);
+  }
+  if (Array.isArray(opts.extraPairs)) {
+    for (var p = 0; p < opts.extraPairs.length; p++) {
+      var pair = opts.extraPairs[p];
+      if (!Array.isArray(pair) || pair.length !== 2) continue;
+      for (var ti = 0; ti < tokens.length; ti++) {
+        var lower = tokens[ti].toLowerCase();
+        if (lower === pair[0]) {
+          var nt1 = tokens.slice(); nt1[ti] = pair[1]; _add(nt1.join(" "));
+        } else if (lower === pair[1]) {
+          var nt2 = tokens.slice(); nt2[ti] = pair[0]; _add(nt2.join(" "));
+        }
+      }
+    }
+  }
+  return out;
+}
+
+module.exports = {
+  expand:          expand,
+  NICKNAME_PAIRS:  NICKNAME_PAIRS,
+};

package/lib/compliance-sanctions-fetcher.js

@@ -0,0 +1,206 @@
+"use strict";
+/**
+ * b.compliance.sanctions.fetcher — periodic sanctions-list refresh
+ * helper.
+ *
+ * The framework intentionally does NOT vendor the sanctions list (it
+ * changes daily and has legal-distribution implications). Operators
+ * fetch from the canonical source on a schedule + reload the screener.
+ * This module wraps the schedule + comparison + reload-trigger logic
+ * so operators write one fetch callback instead of orchestrating it.
+ *
+ *   var fetcher = b.compliance.sanctions.fetcher.create({
+ *     screener:        sdnScreener,                // from sanctions.create
+ *     intervalMs:      C.TIME.hours(24),
+ *     fetch:           async function () {
+ *       // Operator-supplied: hits treasury.gov, parses CSV, returns
+ *       // canonical entry array.
+ *       var rows = await downloadSdnCsv();
+ *       return rows.map(b.compliance.sanctions.parseOfacCsvRow);
+ *     },
+ *     onRefreshed:     function (diff) {
+ *       log.info("SDN list refreshed", diff);
+ *     },
+ *     onError:         function (err) {
+ *       pagerDuty.alert("SDN list fetch failed", err);
+ *     },
+ *   });
+ *   fetcher.start();
+ *   ...
+ *   await fetcher.shutdown();
+ *
+ * Behavior:
+ *   - On each tick, run fetch(); if it returns a non-empty array,
+ *     swap the screener's index via screener.reload(entries).
+ *   - If fetch() throws or returns empty, skip the swap and emit an
+ *     audit event; the screener keeps the previous index. Operators
+ *     can configure onError for paging.
+ *   - Initial run is opt-in via opts.fetchOnStart (default true);
+ *     operators that prefer to seed the screener from a cached file
+ *     at boot pass false.
+ *
+ * Audit emissions:
+ *   compliance.sanctions.refresh.started   — every tick
+ *   compliance.sanctions.refresh.completed — successful refresh + diff
+ *   compliance.sanctions.refresh.skipped   — tick returned empty
+ *   compliance.sanctions.refresh.failed    — fetch threw
+ */
+
+var C = require("./constants");
+var lazyRequire = require("./lazy-require");
+var safeAsync = require("./safe-async");
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var SanctionsFetcherError = defineClass("SanctionsFetcherError", { alwaysPermanent: true });
+
+var audit = lazyRequire(function () { return require("./audit"); });
+var observability = lazyRequire(function () { return require("./observability"); });
+
+function create(opts) {
+  validateOpts.requireObject(opts, "compliance.sanctions.fetcher", SanctionsFetcherError);
+  validateOpts(opts, [
+    "screener", "intervalMs", "fetch",
+    "onRefreshed", "onError",
+    "fetchOnStart", "audit",
+  ], "compliance.sanctions.fetcher.create");
+
+  if (!opts.screener || typeof opts.screener.reload !== "function") {
+    throw new SanctionsFetcherError("sanctions-fetcher/bad-screener",
+      "fetcher.create: screener must be a sanctions.create() instance");
+  }
+  if (typeof opts.fetch !== "function") {
+    throw new SanctionsFetcherError("sanctions-fetcher/bad-fetch",
+      "fetcher.create: fetch must be an async function returning entry[]");
+  }
+  validateOpts.optionalPositiveFinite(opts.intervalMs,
+    "fetcher.create: intervalMs", SanctionsFetcherError, "sanctions-fetcher/bad-opts");
+  validateOpts.optionalFunction(opts.onRefreshed,
+    "fetcher.create: onRefreshed", SanctionsFetcherError, "sanctions-fetcher/bad-opts");
+  validateOpts.optionalFunction(opts.onError,
+    "fetcher.create: onError", SanctionsFetcherError, "sanctions-fetcher/bad-opts");
+
+  var intervalMs   = opts.intervalMs   || C.TIME.hours(24);
+  var fetchOnStart = opts.fetchOnStart !== false;
+  var auditOn      = opts.audit !== false;
+  var screener     = opts.screener;
+  var fetchFn      = opts.fetch;
+
+  var handle  = null;
+  var stopping = false;
+  var lastSuccess = null;
+  var lastError = null;
+  var refreshCount = 0;
+  var failureCount = 0;
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent */ }
+  }
+
+  function _emitMetric(verb, n) {
+    try { observability().safeEvent("compliance.sanctions.fetcher." + verb, n || 1, {}); }
+    catch (_e) { /* drop-silent */ }
+  }
+
+  async function _tick() {
+    if (stopping) return;
+    _emitAudit("compliance.sanctions.refresh.started", "success", {
+      algorithm: screener.algorithm,
+    });
+    var entries;
+    try {
+      entries = await fetchFn();
+    } catch (e) {
+      failureCount += 1;
+      lastError = (e && e.message) || String(e);
+      _emitAudit("compliance.sanctions.refresh.failed", "failure", {
+        error: lastError, algorithm: screener.algorithm,
+      });
+      _emitMetric("failed", 1);
+      if (typeof opts.onError === "function") {
+        try { opts.onError(e); } catch (_e2) { /* operator hook */ }
+      }
+      return;
+    }
+    if (!Array.isArray(entries) || entries.length === 0) {
+      _emitAudit("compliance.sanctions.refresh.skipped", "success", {
+        reason: "fetch-returned-empty", algorithm: screener.algorithm,
+      });
+      _emitMetric("skipped", 1);
+      return;
+    }
+    var diff;
+    try { diff = screener.reload(entries); }
+    catch (e) {
+      failureCount += 1;
+      lastError = (e && e.message) || String(e);
+      _emitAudit("compliance.sanctions.refresh.failed", "failure", {
+        error: lastError, phase: "reload", algorithm: screener.algorithm,
+      });
+      _emitMetric("failed", 1);
+      if (typeof opts.onError === "function") {
+        try { opts.onError(e); } catch (_e2) { /* operator hook */ }
+      }
+      return;
+    }
+    refreshCount += 1;
+    lastSuccess = Date.now();
+    _emitAudit("compliance.sanctions.refresh.completed", "success", {
+      algorithm: screener.algorithm,
+      added:     diff.addedIds.length,
+      removed:   diff.removedIds.length,
+      newSize:   diff.newSize,
+    });
+    _emitMetric("completed", 1);
+    if (typeof opts.onRefreshed === "function") {
+      try { opts.onRefreshed(diff); } catch (_e2) { /* operator hook */ }
+    }
+  }
+
+  function start() {
+    if (handle) return;
+    stopping = false;
+    if (fetchOnStart) {
+      // Fire-and-forget; the periodic ticker handles the rest.
+      _tick().catch(function () { /* drop-silent — see _tick */ });
+    }
+    handle = safeAsync.repeating(function () {
+      _tick().catch(function () { /* drop-silent */ });
+    }, intervalMs, { name: "sanctions-fetcher" });
+  }
+
+  async function shutdown() {
+    stopping = true;
+    if (handle) { handle.stop(); handle = null; }
+  }
+
+  function stats() {
+    return {
+      lastSuccess:  lastSuccess,
+      lastError:    lastError,
+      refreshCount: refreshCount,
+      failureCount: failureCount,
+      running:      handle !== null,
+    };
+  }
+
+  return {
+    start:      start,
+    shutdown:   shutdown,
+    stats:      stats,
+    // Test hook
+    _tickOnce:  _tick,
+  };
+}
+
+module.exports = {
+  create:                  create,
+  SanctionsFetcherError:   SanctionsFetcherError,
+};

package/lib/compliance-sanctions-fuzzy.js

@@ -0,0 +1,297 @@
+"use strict";
+/**
+ * Fuzzy name-matching primitives for sanctions screening.
+ *
+ * Operators screening names against the OFAC SDN list / EU CSL /
+ * UK HMT consolidated list need to handle:
+ *   - Transliteration variations (Mohamed / Mohammed / Muhammad)
+ *   - Order-of-name variations (Smith John vs John Smith)
+ *   - Initials vs full names (J. Smith vs John Smith)
+ *   - Diacritical noise (Müller vs Muller)
+ *   - Substring containment (the SDN entry "Acme Corp" matches a
+ *     local record "Acme Corp Limited")
+ *
+ * This module exports the algorithmic core; b.compliance.sanctions
+ * orchestrates parser/index/match against it.
+ *
+ * Functions:
+ *   normalize(name)            → canonical lowercase form, diacritics
+ *                                 stripped, multi-space collapsed
+ *   tokenize(name)             → array of normalized tokens
+ *   levenshtein(a, b, capDist) → edit distance with O(min(a,b)) memory
+ *                                 + early-exit when distance > capDist
+ *   jaroWinkler(a, b, prefix)  → 0..1 similarity score per Jaro-Winkler
+ *                                 (1996); operators typically threshold
+ *                                 at >= 0.85 for "probable match"
+ *   tokenSetSimilarity(a, b)   → bag-of-tokens overlap with token-pair
+ *                                 Jaro-Winkler scoring; resilient to
+ *                                 word order and missing/extra terms
+ *
+ * Performance: worst-case O(n*m) for Levenshtein (n,m = string lengths),
+ * O(n*m) for Jaro-Winkler. Operators screening against a list of N
+ * entries should pre-filter on token-set overlap before computing
+ * Jaro-Winkler on every candidate.
+ */
+
+var validateOpts = require("./validate-opts");
+var { defineClass } = require("./framework-error");
+
+var FuzzyError = defineClass("FuzzyError", { alwaysPermanent: true });
+
+// ---- normalize ----
+
+// Diacritic-stripping table — covers the most common Latin Unicode
+// ranges. The framework intentionally ships a focused table (not a
+// full Unicode normalizer) so the LoC is bounded; operators with
+// non-Latin lists install ICU normalizer in their pre-processing.
+var _DIACRITIC_MAP = {
+  "à":"a","á":"a","â":"a","ã":"a","ä":"a","å":"a","ą":"a","ă":"a",
+  "ç":"c","ć":"c","č":"c","ĉ":"c",
+  "ď":"d","đ":"d",
+  "è":"e","é":"e","ê":"e","ë":"e","ę":"e","ě":"e","ĕ":"e",
+  "ğ":"g","ĝ":"g","ġ":"g",
+  "ĥ":"h",
+  "ì":"i","í":"i","î":"i","ï":"i","ı":"i","į":"i",
+  "ĵ":"j",
+  "ķ":"k",
+  "ĺ":"l","ľ":"l","ł":"l","ļ":"l",
+  "ñ":"n","ń":"n","ň":"n","ņ":"n",
+  "ò":"o","ó":"o","ô":"o","õ":"o","ö":"o","ø":"o","ő":"o",
+  "ŕ":"r","ř":"r",
+  "ś":"s","š":"s","ş":"s","ș":"s","ŝ":"s",
+  "ť":"t","ţ":"t","ț":"t",
+  "ù":"u","ú":"u","û":"u","ü":"u","ū":"u","ů":"u","ű":"u","ŭ":"u",
+  "ŵ":"w",
+  "ý":"y","ÿ":"y","ŷ":"y",
+  "ź":"z","ż":"z","ž":"z",
+  "ß":"ss","æ":"ae","œ":"oe",
+  "À":"A","Á":"A","Â":"A","Ã":"A","Ä":"A","Å":"A",
+  "Ç":"C","È":"E","É":"E","Ê":"E","Ë":"E",
+  "Ì":"I","Í":"I","Î":"I","Ï":"I",
+  "Ñ":"N",
+  "Ò":"O","Ó":"O","Ô":"O","Õ":"O","Ö":"O","Ø":"O",
+  "Ù":"U","Ú":"U","Û":"U","Ü":"U",
+  "Ý":"Y","Ÿ":"Y",
+  "Ž":"Z","Š":"S",
+};
+
+function normalize(name) {
+  if (typeof name !== "string") return "";
+  // 1. Strip diacritics
+  var stripped = "";
+  for (var i = 0; i < name.length; i++) {
+    var ch = name.charAt(i);
+    stripped += _DIACRITIC_MAP[ch] || ch;
+  }
+  // 2. Lowercase
+  var lower = stripped.toLowerCase();
+  // 3. Strip punctuation other than hyphen + apostrophe (preserved
+  //    inside names like O'Brien / Al-Faisal)
+  var punctStripped = lower.replace(/[^\p{Letter}\p{Number}'\- ]+/gu, " ");        // allow:regex-no-length-cap — caller bounds total input via tokenize() length cap
+  // 4. Collapse whitespace
+  var collapsed = punctStripped.replace(/\s+/g, " ").trim();
+  return collapsed;
+}
+
+function tokenize(name) {
+  if (typeof name !== "string") return [];
+  if (name.length > MAX_INPUT_LEN) {
+    throw new FuzzyError("fuzzy/input-too-long",
+      "tokenize: input exceeds " + MAX_INPUT_LEN + " char cap");
+  }
+  var n = normalize(name);
+  if (n.length === 0) return [];
+  return n.split(" ").filter(function (t) { return t.length > 0; });
+}
+
+var MAX_INPUT_LEN = 512;                                                           // allow:raw-byte-literal — name length sanity cap (operators can override fuzzy.create)
+
+// ---- Levenshtein with cap + early-exit ----
+
+function levenshtein(a, b, capDist) {
+  if (typeof a !== "string" || typeof b !== "string") {
+    throw new FuzzyError("fuzzy/bad-input",
+      "levenshtein: a + b must be strings");
+  }
+  // Trivial cases
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+
+  // Cap (Math.abs(a.length - b.length) is the lower bound; if this
+  // already exceeds cap we can skip the full DP)
+  if (typeof capDist === "number" && capDist >= 0) {
+    var lengthDelta = Math.abs(a.length - b.length);
+    if (lengthDelta > capDist) return capDist + 1;
+  }
+
+  // Two-row DP: O(min(a.length, b.length)) memory.
+  var s = a.length <= b.length ? a : b;
+  var t = a.length <= b.length ? b : a;
+  var prev = new Array(s.length + 1);
+  var curr = new Array(s.length + 1);
+  for (var i = 0; i <= s.length; i++) prev[i] = i;
+  for (var j = 1; j <= t.length; j++) {
+    curr[0] = j;
+    var rowMin = j;
+    for (var k = 1; k <= s.length; k++) {
+      var cost = s.charAt(k - 1) === t.charAt(j - 1) ? 0 : 1;
+      curr[k] = Math.min(
+        prev[k]     + 1,        // deletion
+        curr[k - 1] + 1,        // insertion
+        prev[k - 1] + cost      // substitution
+      );
+      if (curr[k] < rowMin) rowMin = curr[k];
+    }
+    if (typeof capDist === "number" && rowMin > capDist) return capDist + 1;
+    var swap = prev; prev = curr; curr = swap;
+  }
+  return prev[s.length];
+}
+
+// ---- Jaro and Jaro-Winkler ----
+
+function jaro(a, b) {
+  if (typeof a !== "string" || typeof b !== "string") return 0;
+  if (a === b) return a.length === 0 ? 0 : 1;
+  if (a.length === 0 || b.length === 0) return 0;
+  var matchWindow = Math.max(0, Math.floor(Math.max(a.length, b.length) / 2) - 1);  // allow:raw-byte-literal — Jaro match-window formula
+  var aMatched = new Array(a.length).fill(false);
+  var bMatched = new Array(b.length).fill(false);
+  var matches = 0;
+  for (var i = 0; i < a.length; i++) {
+    var lo = Math.max(0, i - matchWindow);
+    var hi = Math.min(b.length - 1, i + matchWindow);
+    for (var j = lo; j <= hi; j++) {
+      if (bMatched[j]) continue;
+      if (a.charAt(i) !== b.charAt(j)) continue;
+      aMatched[i] = true;
+      bMatched[j] = true;
+      matches += 1;
+      break;
+    }
+  }
+  if (matches === 0) return 0;
+  // Count transpositions
+  var t = 0;
+  var k = 0;
+  for (var ii = 0; ii < a.length; ii++) {
+    if (!aMatched[ii]) continue;
+    while (!bMatched[k]) k += 1;
+    if (a.charAt(ii) !== b.charAt(k)) t += 1;
+    k += 1;
+  }
+  var transpositions = t / 2;
+  return (matches / a.length + matches / b.length +
+          (matches - transpositions) / matches) / 3;                                // allow:raw-byte-literal — Jaro 3-term formula
+}
+
+function jaroWinkler(a, b, prefixWeight) {
+  // prefixWeight defaults to 0.1 per the original Winkler paper;
+  // operators can lower to reduce prefix bias.
+  var w = (typeof prefixWeight === "number" && isFinite(prefixWeight))
+    ? prefixWeight : 0.1;
+  if (w < 0 || w > 0.25) {
+    throw new FuzzyError("fuzzy/bad-prefix-weight",
+      "jaroWinkler: prefixWeight must be in [0, 0.25]");
+  }
+  var j = jaro(a, b);
+  if (j === 0) return 0;
+  // Common prefix up to 4 chars (Winkler's cap)
+  var maxPrefix = 4;                                                               // allow:raw-byte-literal — Jaro-Winkler prefix cap (Winkler 1990)
+  var prefixLen = 0;
+  var max = Math.min(a.length, b.length, maxPrefix);
+  for (var i = 0; i < max; i++) {
+    if (a.charAt(i) !== b.charAt(i)) break;
+    prefixLen += 1;
+  }
+  return j + prefixLen * w * (1 - j);
+}
+
+// ---- Token-set similarity ----
+
+function tokenSetSimilarity(a, b, opts) {
+  opts = opts || {};
+  var prefixWeight = opts.prefixWeight;
+  var threshold    = (typeof opts.threshold === "number" && isFinite(opts.threshold))
+    ? opts.threshold : 0.85;
+  var tokensA = tokenize(a);
+  var tokensB = tokenize(b);
+  if (tokensA.length === 0 || tokensB.length === 0) return 0;
+  // Greedy bipartite matching: for each token in A, find the best
+  // unmatched B token; sum & average. This is O(n*m) but the typical
+  // name has ≤ 5 tokens so it's bounded.
+  var bUsed = new Array(tokensB.length).fill(false);
+  var matchedScores = [];
+  for (var i = 0; i < tokensA.length; i++) {
+    var bestScore = 0;
+    var bestIdx = -1;
+    for (var j = 0; j < tokensB.length; j++) {
+      if (bUsed[j]) continue;
+      var s = jaroWinkler(tokensA[i], tokensB[j], prefixWeight);
+      if (s > bestScore) { bestScore = s; bestIdx = j; }
+    }
+    if (bestIdx !== -1 && bestScore >= threshold) {
+      bUsed[bestIdx] = true;
+      matchedScores.push(bestScore);
+    }
+  }
+  if (matchedScores.length === 0) return 0;
+  // Token-set similarity: average of the matched-pair scores, weighted
+  // by coverage of the smaller-token-side.
+  var avg = matchedScores.reduce(function (a2, b2) { return a2 + b2; }, 0) /
+            matchedScores.length;
+  var coverage = matchedScores.length / Math.min(tokensA.length, tokensB.length);
+  return avg * coverage;
+}
+
+// ---- Container helpers ----
+
+// substringContains — true when the normalized form of `needle` is a
+// whitespace-bounded substring of the normalized form of `haystack`.
+// Useful for catching SDN entries like "Acme Corp" inside a fuller
+// local record like "Acme Corp Limited Liability Company".
+function substringContains(haystack, needle) {
+  var nh = " " + normalize(haystack) + " ";
+  var nn = " " + normalize(needle) + " ";
+  return nh.indexOf(nn) !== -1;
+}
+
+// initialsMatch — true when the normalized form of `a` is shaped like
+// "J Smith" / "J. Smith" / "JS" and matches the leading-character
+// pattern of `b`. Catches the common "screen-typo" pattern where the
+// user typed an initial instead of a full first name.
+function initialsMatch(a, b) {
+  var ta = tokenize(a);
+  var tb = tokenize(b);
+  if (ta.length === 0 || tb.length === 0) return false;
+  if (ta.length !== tb.length) return false;
+  for (var i = 0; i < ta.length; i++) {
+    var x = ta[i];
+    var y = tb[i];
+    if (x === y) continue;
+    // Match if either side is a single char and matches the other's
+    // first char.
+    if (x.length === 1 && y.startsWith(x)) continue;
+    if (y.length === 1 && x.startsWith(y)) continue;
+    return false;
+  }
+  return true;
+}
+
+module.exports = {
+  normalize:           normalize,
+  tokenize:            tokenize,
+  levenshtein:         levenshtein,
+  jaro:                jaro,
+  jaroWinkler:         jaroWinkler,
+  tokenSetSimilarity:  tokenSetSimilarity,
+  substringContains:   substringContains,
+  initialsMatch:       initialsMatch,
+  FuzzyError:          FuzzyError,
+  MAX_INPUT_LEN:       MAX_INPUT_LEN,
+};
+// note: validateOpts intentionally not used in this file (pure
+// algorithmic helpers); imported only to keep the require shape
+// consistent with sister modules.
+void validateOpts;

package/lib/compliance-sanctions.js

@@ -0,0 +1,569 @@
+"use strict";
+/**
+ * b.compliance.sanctions — sanctions-list screening.
+ *
+ * Operators handling KYC / payment / customer-onboarding flows screen
+ * names against the U.S. Treasury OFAC Specially Designated Nationals
+ * list, the EU Consolidated Sanctions List (CSL), the UK HMT
+ * consolidated list, the UN 1267 Al-Qaida/Taliban list, and adjacent
+ * regulatory lists. The framework owns the indexing + match algorithm;
+ * the operator owns the daily fetch + format-specific parsing.
+ *
+ *   var screener = b.compliance.sanctions.create({
+ *     entries:    parsedSdnList,    // operator-supplied
+ *     algorithm:  "ofac-sdn",       // | "eu-csl" | "uk-hmt" | "un-1267" |
+ *                                    //   "custom"
+ *     fuzzy: {
+ *       enabled:   true,
+ *       threshold: 0.85,            // Jaro-Winkler threshold; 0..1
+ *       strategy:  "jaro-winkler",  // | "levenshtein" | "exact"
+ *       maxLevenshtein: 3,          // max edit distance per "levenshtein"
+ *     },
+ *     audit:      true,
+ *   });
+ *
+ *   var result = await screener.screen({
+ *     name:        "John Smith",
+ *     dateOfBirth: "1980-01-15",
+ *     country:     "US",
+ *     type:        "individual",    // | "entity" | "vessel" | "aircraft"
+ *     aliases:     ["J Smith", "Jonny Smith"],
+ *   });
+ *   // → {
+ *   //     match: true | false,
+ *   //     hits:  [{ entryId, name, score, reason, listed, programs }],
+ *   //     screenedAt, algorithm, ruleVersion,
+ *   //   }
+ *
+ * Entry shape (operator parses raw list into this canonical shape):
+ *   {
+ *     id:           "OFAC-12345",
+ *     primaryName:  "JOHN SMITH",
+ *     aliases:      ["J SMITH", "JONNY SMITH"],
+ *     type:         "individual" | "entity" | "vessel" | "aircraft",
+ *     programs:     ["SDGT", "RUSSIA-EO13662"],   // sanction programs
+ *     listedAt:     "2024-03-15",
+ *     country:      "RU",
+ *     dateOfBirth:  ["1980-01-15"],               // optional disambiguator
+ *     remarks:      "...",
+ *     // operator-side fields preserved verbatim:
+ *     raw:          <any>,
+ *   }
+ *
+ * Audit emissions (audit namespace `compliance`):
+ *   compliance.sanctions.screened   — every screen() call (match or no-match)
+ *   compliance.sanctions.matched    — every screen() with at least one hit
+ *
+ * The framework does NOT vendor the list itself: list contents change
+ * daily and have legal-distribution implications. Operators fetch from
+ * the source (treasury.gov for OFAC, sanctionsmap.eu for EU CSL,
+ * gov.uk for HMT, scsanctions.un.org for UN 1267) on a daily schedule
+ * and pass the parsed array.
+ */
+
+var lazyRequire = require("./lazy-require");
+var validateOpts = require("./validate-opts");
+var fuzzy = require("./compliance-sanctions-fuzzy");
+var aliases = require("./compliance-sanctions-aliases");
+var fetcher = require("./compliance-sanctions-fetcher");
+var { defineClass } = require("./framework-error");
+
+var SanctionsError = defineClass("SanctionsError", { alwaysPermanent: true });
+
+var audit = lazyRequire(function () { return require("./audit"); });
+var observability = lazyRequire(function () { return require("./observability"); });
+
+var VALID_ALGORITHMS = Object.freeze([
+  "ofac-sdn",   // U.S. Treasury Specially Designated Nationals
+  "eu-csl",     // EU Consolidated Sanctions List
+  "uk-hmt",     // UK HM Treasury consolidated
+  "un-1267",    // UN Security Council 1267/1989/2253
+  "custom",     // operator-defined list
+]);
+
+var VALID_STRATEGIES = Object.freeze([
+  "jaro-winkler",
+  "levenshtein",
+  "exact",
+]);
+
+var VALID_TYPES = Object.freeze([
+  "individual",
+  "entity",
+  "vessel",
+  "aircraft",
+]);
+
+// ---- Parser shims ----
+//
+// Operators feed pre-parsed entries to create(); the framework also
+// ships parser shims for the common public formats. Parsers run on
+// the operator side (network fetch + format conversion) and return
+// the canonical entry shape. The framework's parsers are minimal:
+// just enough to extract id + primaryName + aliases + programs from
+// the canonical XML/JSON shape that each sanctions authority ships.
+
+// OFAC SDN — the Treasury distributes XML and CSV; we accept the
+// parsed CSV-row shape (operator runs b.parsers.safeCsv). Each row:
+//   { ent_num, SDN_Name, SDN_Type, Program, Title, Call_Sign, ... }
+function parseOfacCsvRow(row) {
+  if (!row || typeof row !== "object") return null;
+  if (!row.SDN_Name || row.ent_num === undefined) return null;
+  return {
+    id:           "OFAC-" + String(row.ent_num),
+    primaryName:  String(row.SDN_Name).trim(),
+    aliases:      [],     // OFAC distributes aliases in a separate alt-names file
+    type:         _ofacTypeToCanonical(row.SDN_Type),
+    programs:     row.Program ? String(row.Program).split(";").map(function (s) { return s.trim(); }).filter(Boolean) : [],
+    country:      row.Country ? String(row.Country).trim() : null,
+    listedAt:     row.Publish_Date ? String(row.Publish_Date) : null,
+    remarks:      row.Remarks ? String(row.Remarks) : null,
+    raw:          row,
+  };
+}
+
+function _ofacTypeToCanonical(t) {
+  switch (String(t || "").toLowerCase()) {
+    case "individual": return "individual";
+    case "entity":     return "entity";
+    case "vessel":     return "vessel";
+    case "aircraft":   return "aircraft";
+    default:           return "entity";
+  }
+}
+
+// OFAC alias rows from the alt-names file:
+//   { ent_num, alt_num, alt_type, alt_name, alt_remarks }
+// merged into the primary entry by operator code via mergeAliases().
+function parseOfacAliasRow(row) {
+  if (!row || typeof row !== "object") return null;
+  if (row.ent_num === undefined || !row.alt_name) return null;
+  return {
+    entId:    "OFAC-" + String(row.ent_num),
+    altType:  String(row.alt_type || "aka"),
+    altName:  String(row.alt_name).trim(),
+    remarks:  row.alt_remarks ? String(row.alt_remarks) : null,
+  };
+}
+
+function mergeAliases(entries, aliasRows) {
+  if (!Array.isArray(entries)) return [];
+  if (!Array.isArray(aliasRows)) return entries;
+  var byId = Object.create(null);
+  for (var i = 0; i < entries.length; i++) byId[entries[i].id] = entries[i];
+  for (var j = 0; j < aliasRows.length; j++) {
+    var alias = aliasRows[j];
+    var entry = byId[alias.entId];
+    if (entry) entry.aliases.push(alias.altName);
+  }
+  return entries;
+}
+
+// EU CSL — the EU distributes XML; operator parses with b.parsers.safeXml
+// and feeds the per-entity dict (subjectType, nameAlias, regulation, etc.)
+function parseEuCslEntry(entity) {
+  if (!entity || typeof entity !== "object") return null;
+  var nameAliases = entity.nameAlias || entity.NAMEALIAS || [];
+  if (!Array.isArray(nameAliases)) nameAliases = [nameAliases];
+  if (nameAliases.length === 0) return null;
+  var primary = nameAliases[0];
+  return {
+    id:          "EU-CSL-" + String(entity.logicalId || entity.LOGICALID || ""),
+    primaryName: String(primary.wholeName || primary.WHOLENAME || "").trim(),
+    aliases:     nameAliases.slice(1).map(function (a) {
+      return String(a.wholeName || a.WHOLENAME || "").trim();
+    }).filter(Boolean),
+    type:        _euTypeToCanonical(entity.subjectType || entity.SUBJECTTYPE),
+    programs:    entity.regulation ? [String(entity.regulation)] : [],
+    country:     entity.country || null,
+    listedAt:    entity.designationDate || null,
+    remarks:     entity.remark || null,
+    raw:         entity,
+  };
+}
+
+function _euTypeToCanonical(t) {
+  switch (String(t || "").toLowerCase()) {
+    case "person":   return "individual";
+    case "enterprise": return "entity";
+    case "vessel":   return "vessel";
+    case "aircraft": return "aircraft";
+    default:         return "entity";
+  }
+}
+
+// UN 1267 list — XML-based, similar to EU shape but different field
+// names. Operators parse the XML root then feed individual entries.
+function parseUn1267Entry(entry) {
+  if (!entry || typeof entry !== "object") return null;
+  var name = entry.NAME || entry.name || entry.FIRST_NAME || "";
+  if (!name) return null;
+  var aliases = [];
+  if (Array.isArray(entry.ALIASES)) aliases = entry.ALIASES.slice();
+  else if (typeof entry.ALIAS_NAMES === "string") {
+    aliases = entry.ALIAS_NAMES.split(";").map(function (s) { return s.trim(); }).filter(Boolean);
+  }
+  return {
+    id:          "UN-1267-" + String(entry.REFERENCE_NUMBER || entry.DATAID || ""),
+    primaryName: String(name).trim(),
+    aliases:     aliases,
+    type:        entry.NAME_TYPE === "Entity" ? "entity" : "individual",
+    programs:    ["UN-1267"],
+    country:     entry.COUNTRY || entry.NATIONALITY || null,
+    listedAt:    entry.LISTED_ON || null,
+    remarks:     entry.COMMENTS || null,
+    raw:         entry,
+  };
+}
+
+// ---- Index + screen ----
+
+function _normalizeEntry(e) {
+  // Defensive copy + normalise primaryName/aliases for fast match.
+  var norm = {
+    id:           e.id,
+    primaryName:  e.primaryName || "",
+    aliases:      Array.isArray(e.aliases) ? e.aliases.slice() : [],
+    type:         e.type || "entity",
+    programs:     Array.isArray(e.programs) ? e.programs.slice() : [],
+    country:      e.country || null,
+    listedAt:     e.listedAt || null,
+    dateOfBirth:  Array.isArray(e.dateOfBirth) ? e.dateOfBirth.slice() : (e.dateOfBirth ? [e.dateOfBirth] : []),
+    remarks:      e.remarks || null,
+    raw:          e.raw || null,
+  };
+  // Pre-tokenize for the matcher
+  norm._allNamesNormalized = [norm.primaryName].concat(norm.aliases)
+    .map(fuzzy.normalize)
+    .filter(function (s) { return s.length > 0; });
+  return norm;
+}
+
+function create(opts) {
+  validateOpts.requireObject(opts, "compliance.sanctions", SanctionsError);
+  validateOpts(opts, [
+    "entries", "algorithm", "fuzzy", "audit", "ruleVersion",
+  ], "compliance.sanctions.create");
+
+  if (!Array.isArray(opts.entries)) {
+    throw new SanctionsError("sanctions/no-entries",
+      "compliance.sanctions.create: entries must be an array");
+  }
+  var algorithm = opts.algorithm || "custom";
+  if (VALID_ALGORITHMS.indexOf(algorithm) === -1) {
+    throw new SanctionsError("sanctions/bad-algorithm",
+      "compliance.sanctions.create: algorithm must be one of " +
+      VALID_ALGORITHMS.join(", "));
+  }
+  var fuzzyOpts = opts.fuzzy || {};
+  if (typeof fuzzyOpts !== "object" || Array.isArray(fuzzyOpts)) {
+    throw new SanctionsError("sanctions/bad-fuzzy",
+      "compliance.sanctions.create: fuzzy must be an object");
+  }
+  var fuzzyEnabled = fuzzyOpts.enabled !== false;
+  var fuzzyThreshold = (typeof fuzzyOpts.threshold === "number" && isFinite(fuzzyOpts.threshold))
+    ? fuzzyOpts.threshold : 0.85;
+  if (fuzzyThreshold < 0 || fuzzyThreshold > 1) {
+    throw new SanctionsError("sanctions/bad-threshold",
+      "compliance.sanctions.create: fuzzy.threshold must be in [0, 1]");
+  }
+  var fuzzyStrategy = fuzzyOpts.strategy || "jaro-winkler";
+  if (VALID_STRATEGIES.indexOf(fuzzyStrategy) === -1) {
+    throw new SanctionsError("sanctions/bad-strategy",
+      "compliance.sanctions.create: fuzzy.strategy must be one of " +
+      VALID_STRATEGIES.join(", "));
+  }
+  var maxLevenshtein = (typeof fuzzyOpts.maxLevenshtein === "number" && isFinite(fuzzyOpts.maxLevenshtein))
+    ? fuzzyOpts.maxLevenshtein : 3;                                                // allow:raw-byte-literal — default edit-distance cap (operator-tunable)
+  var auditOn = opts.audit !== false;
+  var ruleVersion = opts.ruleVersion || ("entries:" + opts.entries.length);
+
+  // Index — normalize all entries up front (O(N*M) once) so screen()
+  // is O(N*K) where K is the number of names+aliases per entry. For a
+  // 30k-entry list with ~3 aliases each, the index uses ~90k normalized
+  // strings.
+  var index = opts.entries.map(_normalizeEntry);
+
+  function _emitAudit(action, outcome, metadata) {
+    if (!auditOn) return;
+    try {
+      audit().safeEmit({
+        action:   action,
+        outcome:  outcome,
+        metadata: metadata || {},
+      });
+    } catch (_e) { /* drop-silent — audit sink */ }
+  }
+
+  function _emitMetric(verb, n, labels) {
+    try { observability().safeEvent("compliance.sanctions." + verb, n || 1, labels || {}); }
+    catch (_e) { /* drop-silent */ }
+  }
+
+  function _exactMatch(qNorm, candidate) {
+    for (var i = 0; i < candidate._allNamesNormalized.length; i++) {
+      if (candidate._allNamesNormalized[i] === qNorm) return 1.0;
+    }
+    return 0;
+  }
+
+  function _jaroWinklerMatch(qNorm, candidate) {
+    var bestScore = 0;
+    var bestName = "";
+    for (var i = 0; i < candidate._allNamesNormalized.length; i++) {
+      var name = candidate._allNamesNormalized[i];
+      var s = fuzzy.tokenSetSimilarity(qNorm, name, {
+        threshold: fuzzyThreshold,
+      });
+      if (s > bestScore) {
+        bestScore = s;
+        bestName = name;
+      }
+      // Also try direct Jaro-Winkler on the whole strings
+      var s2 = fuzzy.jaroWinkler(qNorm, name);
+      if (s2 > bestScore) {
+        bestScore = s2;
+        bestName = name;
+      }
+      // Substring containment scores 0.92 (high but below exact)
+      if (fuzzy.substringContains(name, qNorm)) {
+        if (0.92 > bestScore) { bestScore = 0.92; bestName = name; }                // allow:raw-byte-literal — substring-match score weight
+      }
+      if (fuzzy.substringContains(qNorm, name)) {
+        if (0.92 > bestScore) { bestScore = 0.92; bestName = name; }                // allow:raw-byte-literal — substring-match score weight
+      }
+    }
+    return { score: bestScore, name: bestName };
+  }
+
+  function _levenshteinMatch(qNorm, candidate) {
+    var bestScore = 0;
+    var bestName = "";
+    for (var i = 0; i < candidate._allNamesNormalized.length; i++) {
+      var name = candidate._allNamesNormalized[i];
+      var dist = fuzzy.levenshtein(qNorm, name, maxLevenshtein);
+      if (dist > maxLevenshtein) continue;
+      // Distance → score: distance 0 → 1.0; distance maxLev → 0.0.
+      var maxLen = Math.max(qNorm.length, name.length);
+      if (maxLen === 0) continue;
+      var score = Math.max(0, 1 - dist / maxLen);
+      if (score > bestScore) { bestScore = score; bestName = name; }
+    }
+    return { score: bestScore, name: bestName };
+  }
+
+  function screen(input) {
+    if (!input || typeof input !== "object") {
+      throw new SanctionsError("sanctions/bad-input",
+        "screen: input must be an object");
+    }
+    if (typeof input.name !== "string" || input.name.length === 0) {
+      throw new SanctionsError("sanctions/no-name",
+        "screen: input.name is required");
+    }
+    if (input.name.length > fuzzy.MAX_INPUT_LEN) {
+      throw new SanctionsError("sanctions/name-too-long",
+        "screen: input.name exceeds " + fuzzy.MAX_INPUT_LEN + " char cap");
+    }
+    if (input.type !== undefined && VALID_TYPES.indexOf(input.type) === -1) {
+      throw new SanctionsError("sanctions/bad-type",
+        "screen: input.type must be one of " + VALID_TYPES.join(", "));
+    }
+    var queryName = fuzzy.normalize(input.name);
+    var queryAliases = Array.isArray(input.aliases)
+      ? input.aliases.map(fuzzy.normalize).filter(function (s) { return s.length > 0; })
+      : [];
+    var queryNames = [queryName].concat(queryAliases);
+
+    var hits = [];
+    var screenedAt = Date.now();
+
+    for (var c = 0; c < index.length; c++) {
+      var candidate = index[c];
+      // Type filter: when input.type is set, skip candidates of
+      // the wrong type unless candidate is an entity (entities can
+      // be matched regardless to catch operator-side type errors).
+      if (input.type && candidate.type !== input.type &&
+          candidate.type !== "entity") {
+        continue;
+      }
+
+      var bestForCandidate = { score: 0, name: "" };
+      for (var qi = 0; qi < queryNames.length; qi++) {
+        var qn = queryNames[qi];
+        var match;
+        if (!fuzzyEnabled || fuzzyStrategy === "exact") {
+          var exact = _exactMatch(qn, candidate);
+          match = { score: exact, name: candidate.primaryName };
+        } else if (fuzzyStrategy === "jaro-winkler") {
+          match = _jaroWinklerMatch(qn, candidate);
+        } else {
+          match = _levenshteinMatch(qn, candidate);
+        }
+        if (match.score > bestForCandidate.score) {
+          bestForCandidate = match;
+        }
+      }
+      if (bestForCandidate.score >= fuzzyThreshold) {
+        hits.push({
+          entryId:   candidate.id,
+          name:      candidate.primaryName,
+          matchedOn: bestForCandidate.name,
+          score:     bestForCandidate.score,
+          reason:    bestForCandidate.score >= 0.99 ? "exact-or-near-exact" :
+                     bestForCandidate.score >= 0.92 ? "substring-or-token-match" :
+                     "fuzzy",
+          listed:    candidate.listedAt,
+          programs:  candidate.programs,
+          type:      candidate.type,
+          country:   candidate.country,
+        });
+      }
+    }
+    // Sort hits by descending score
+    hits.sort(function (a, b) { return b.score - a.score; });
+
+    var matched = hits.length > 0;
+    var result = {
+      match:        matched,
+      hits:         hits,
+      query:        { name: input.name, type: input.type || null,
+                      country: input.country || null,
+                      dateOfBirth: input.dateOfBirth || null },
+      screenedAt:   screenedAt,
+      algorithm:    algorithm,
+      ruleVersion:  ruleVersion,
+      strategy:     fuzzyEnabled ? fuzzyStrategy : "exact",
+      threshold:    fuzzyThreshold,
+    };
+    _emitAudit("compliance.sanctions.screened", "success", {
+      algorithm: algorithm, matched: matched,
+      hits: hits.length, ruleVersion: ruleVersion,
+    });
+    if (matched) {
+      _emitAudit("compliance.sanctions.matched", "success", {
+        algorithm: algorithm, hits: hits.length,
+        topScore: hits[0].score, topProgram: hits[0].programs && hits[0].programs[0],
+      });
+      _emitMetric("matched", 1, { algorithm: algorithm });
+    }
+    _emitMetric("screened", 1, { algorithm: algorithm });
+    return result;
+  }
+
+  function size() { return index.length; }
+  function entryById(id) {
+    for (var i = 0; i < index.length; i++) {
+      if (index[i].id === id) return index[i];
+    }
+    return null;
+  }
+
+  // screenBulk — convenience wrapper that screens an array of inputs
+  // and returns the per-input result array. Operators screening a
+  // batch of records (KYC list import, periodic re-screen of existing
+  // customers) call this once instead of looping; the wrapper still
+  // emits one audit event per input so the audit chain stays per-row.
+  function screenBulk(inputs) {
+    if (!Array.isArray(inputs)) {
+      throw new SanctionsError("sanctions/bad-bulk",
+        "screenBulk: inputs must be an array");
+    }
+    var out = [];
+    for (var i = 0; i < inputs.length; i++) {
+      out.push(screen(inputs[i]));
+    }
+    return out;
+  }
+
+  // snapshot — returns a content-derived hash + count of the active
+  // rule index, useful for compliance audit trails ("we screened
+  // ticket X against rule snapshot SHA-3 abcd..."). The snapshot is a
+  // truncated SHA-3-512 of the sorted entry ids; collisions are
+  // ignorable for the audit-trail use case (operators store the
+  // ruleVersion + entry count alongside).
+  function snapshot() {
+    var crypto = require("crypto");
+    var ids = index.map(function (e) { return e.id; }).sort();
+    var hash = crypto.createHash("sha3-512");
+    for (var i = 0; i < ids.length; i++) hash.update(ids[i]);
+    return {
+      algorithm:    algorithm,
+      ruleVersion:  ruleVersion,
+      entryCount:   index.length,
+      digest:       hash.digest("hex").slice(0, 32),                                // allow:raw-byte-literal — first 32 hex chars (128 bits) of SHA-3 digest, sufficient for snapshot identity
+      digestAlg:    "sha3-512-trunc128",
+      capturedAt:   Date.now(),
+    };
+  }
+
+  // reload — atomically swap the index to a fresh entry list. Returns
+  // a diff describing how the index changed (added / removed). The
+  // operator's daily-fetch worker uses this; the swap is atomic from
+  // the caller's perspective (screen() always sees the old or new
+  // index, never a partial state).
+  function reload(newEntries) {
+    if (!Array.isArray(newEntries)) {
+      throw new SanctionsError("sanctions/bad-reload",
+        "reload: newEntries must be an array");
+    }
+    var oldIds = Object.create(null);
+    for (var i = 0; i < index.length; i++) oldIds[index[i].id] = true;
+    var newIndex = newEntries.map(_normalizeEntry);
+    var newIds = Object.create(null);
+    for (var j = 0; j < newIndex.length; j++) newIds[newIndex[j].id] = true;
+    var added = [];
+    var removed = [];
+    for (var k = 0; k < newIndex.length; k++) {
+      if (!oldIds[newIndex[k].id]) added.push(newIndex[k].id);
+    }
+    for (var l = 0; l < index.length; l++) {
+      if (!newIds[index[l].id]) removed.push(index[l].id);
+    }
+    // Atomic swap (single reference assignment)
+    index = newIndex;
+    ruleVersion = "entries:" + index.length + ";reloadedAt:" + Date.now();
+    _emitAudit("compliance.sanctions.reloaded", "success", {
+      added: added.length, removed: removed.length,
+      newSize: index.length, ruleVersion: ruleVersion,
+    });
+    _emitMetric("reloaded", 1, { algorithm: algorithm });
+    return {
+      addedIds:    added,
+      removedIds:  removed,
+      newSize:     index.length,
+      ruleVersion: ruleVersion,
+    };
+  }
+
+  return {
+    screen:        screen,
+    screenBulk:    screenBulk,
+    snapshot:      snapshot,
+    reload:        reload,
+    size:          size,
+    entryById:     entryById,
+    algorithm:     algorithm,
+    ruleVersion:   ruleVersion,
+    threshold:     fuzzyThreshold,
+    strategy:      fuzzyEnabled ? fuzzyStrategy : "exact",
+    // Exposed for tests + advanced operator workflows
+    _index:        index,
+  };
+}
+
+module.exports = {
+  create:              create,
+  parseOfacCsvRow:     parseOfacCsvRow,
+  parseOfacAliasRow:   parseOfacAliasRow,
+  mergeAliases:        mergeAliases,
+  parseEuCslEntry:     parseEuCslEntry,
+  parseUn1267Entry:    parseUn1267Entry,
+  fuzzy:               fuzzy,
+  aliases:             aliases,
+  fetcher:             fetcher,
+  VALID_ALGORITHMS:    VALID_ALGORITHMS,
+  VALID_STRATEGIES:    VALID_STRATEGIES,
+  VALID_TYPES:         VALID_TYPES,
+  SanctionsError:      SanctionsError,
+};

package/lib/compliance.js

@@ -29,6 +29,7 @@
  */
 
 var lazyRequire = require("./lazy-require");
+var sanctions = require("./compliance-sanctions");
 var { ComplianceError } = require("./framework-error");
 
 var audit = lazyRequire(function () { return require("./audit"); });
@@ -305,6 +306,7 @@ module.exports = {
   posturesByDomain:       posturesByDomain,
   posturesByJurisdiction: posturesByJurisdiction,
   list:                   list,
+  sanctions:              sanctions,
   KNOWN_POSTURES:         KNOWN_POSTURES,
   REGIME_MAP:             REGIME_MAP,
   ComplianceError:        ComplianceError,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.7.104",
+  "version": "0.7.105",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cyclonedx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:5afd6c98-92aa-4383-a13c-7d4aed07fdbc",
+  "serialNumber": "urn:uuid:503d52be-ebde-43d9-99cf-866e8585557a",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-06T11:00:18.264Z",
+    "timestamp": "2026-05-06T11:23:52.585Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.7.104",
+      "bom-ref": "@blamejs/core@0.7.105",
       "type": "library",
       "name": "blamejs",
-      "version": "0.7.104",
+      "version": "0.7.105",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.7.104",
+      "purl": "pkg:npm/%40blamejs/core@0.7.105",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.7.104",
+      "ref": "@blamejs/core@0.7.105",
       "dependsOn": []
     }
   ]