@blamejs/core 0.8.42 → 0.8.49

package/lib/retention.js

@@ -1,59 +1,46 @@
 "use strict";
 /**
- * retention — operator-declared data retention rules with periodic sweep.
+ * @module b.retention
+ * @nav    Compliance
+ * @title  Retention
  *
- * GDPR / HIPAA / PCI / industry-specific compliance regimes all share
- * the shape: "data of class X stored beyond TTL Y must be either
- * deleted or anonymized". The framework provides the building blocks
- * (b.cryptoField.eraseRow for crypto-erasure of sealed columns,
- * b.scheduler for the wake cadence, b.audit for the chain). retention
- * ties them into one operator-facing primitive.
+ * @intro
+ *   Row-level retention floors per regulatory regime. GDPR Art. 17,
+ *   HIPAA 45 CFR §164.530(j), PCI-DSS Req. 3.1, SOX §802 and friends
+ *   all share the shape: "data of class X stored beyond TTL Y must be
+ *   either deleted or anonymized". `b.retention` ties the framework's
+ *   building blocks (`b.cryptoField.eraseRow` for crypto-erasure of
+ *   sealed columns, `b.scheduler` for cadence, `b.audit` for the
+ *   chain, `b.legalHold` for per-subject holds) into one
+ *   operator-facing primitive that emits delete / erase / soft-delete
+ *   jobs at expiry.
  *
- *   var rules = b.retention.create({
- *     db:    b.db,
- *     audit: b.audit,
- *   });
- *
- *   rules.declare({
- *     name:     "users.notes-ttl",
- *     table:    "users",
- *     ageField: "createdAt",          // milliseconds-since-epoch column
- *     ttlMs:    C.TIME.days(90),
- *     action:   "erase",              // "erase" (b.cryptoField.eraseRow) | "delete"
- *     batchSize: 500,                 // rows-per-sweep iteration; default 500
- *   });
- *
- *   // Operator wires the sweep cadence:
- *   scheduler.schedule({
- *     name:  "retention.sweep",
- *     every: C.TIME.hours(1),
- *     run:   function () { return rules.runAll(); },
- *   });
- *
- *   // Or run on demand (operator CLI / one-shot):
- *   var summary = await rules.run("users.notes-ttl");
- *   // → { name, scanned, processed, action, durationMs, errors: [] }
+ *   Action vocabulary per row: `"erase"` (sealed columns + derived
+ *   hashes go to NULL, `__erasedAt` set, row remains for FK / audit
+ *   reference — cleartext is unrecoverable even with a vault key);
+ *   `"delete"` (full row DELETE — for tables with no FK / audit
+ *   reference); `"soft-delete"` (writes a deletion timestamp into
+ *   `softDeleteField` — typical "trash bin" pattern); `"warn"` (audit
+ *   only, no row write — used as an early stage in multi-stage
+ *   schedules); `function(row)` (escape hatch for joined / conditional
+ *   retention). Cascades follow `rule.cascade[]` foreign-key edges so
+ *   a parent erase fans out into child rows in the same sweep.
  *
- * Audit posture (audit namespace "retention"):
- *   - retention.rule.declared    — once per declare() call
- *   - retention.sweep.started    — at the top of each runAll()/run()
- *   - retention.row.processed    — per row, with metadata.action
- *   - retention.sweep.completed  — at the end with row counts
- *   - retention.sweep.failed     — when the rule's SQL throws
+ *   `b.compliance.set(posture)` cascades into `applyPosture` here, so
+ *   the active posture's `audit_log` minimum-retention floor becomes
+ *   the default `ttlMs` for any rule the operator declares without an
+ *   explicit value. `complianceFloor(posture, candidateTtlMs)`
+ *   surfaces those minimums for app-side conditional logic.
  *
- * Erase vs delete:
- *   - "erase" (default): sealed columns + derived hashes go to NULL,
- *     `__erasedAt` is set. Row stays for FK / audit reference. Per
- *     GDPR Art. 17 the cleartext is unrecoverable even with a vault
- *     key (no ciphertext to decrypt).
- *   - "delete": full row DELETE. Use when no FK / audit reference
- *     blocks the row from going.
+ *   Audit events (namespace `retention`): `rule.declared`,
+ *   `sweep.started`, `row.processed` (with `action`), `row.warned`,
+ *   `row.legal_hold_skipped`, `sweep.completed`, `sweep.failed`,
+ *   `sweep.skipped_concurrent`. Each sweep is single-flighted per
+ *   rule name so a slow run cannot be re-entered by the next
+ *   scheduler tick.
  *
- * Operators with COMPLEX retention (multi-table joins, conditional
- * rules) use action: function(row) async — the framework calls back
- * with each candidate row and the operator's function performs the
- * write. This is the escape hatch; the table+ageField+ttlMs shape
- * covers the common case.
+ * @card
+ *   Row-level retention floors per regulatory regime.
  */
 var C = require("./constants");
 var lazyRequire = require("./lazy-require");
@@ -63,6 +50,7 @@ var { defineClass } = require("./framework-error");
 
 var audit = lazyRequire(function () { return require("./audit"); });
 var cryptoField = require("./crypto-field");
+var legalHold = lazyRequire(function () { return require("./legal-hold"); });
 
 var RetentionError = defineClass("RetentionError", { alwaysPermanent: true });
 var _err = RetentionError.factory;
@@ -127,6 +115,13 @@ function _validateRule(rule) {
   if (rule.legalHoldField !== undefined) {
     _validateRuleIdentifier(rule.legalHoldField, "rule.legalHoldField");
   }
+  if (rule.subjectField !== undefined &&
+      (typeof rule.subjectField !== "string" || rule.subjectField.length === 0)) {
+    throw _err("BAD_RULE", "rule.subjectField must be a non-empty string");
+  }
+  if (rule.subjectField !== undefined) {
+    _validateRuleIdentifier(rule.subjectField, "rule.subjectField");
+  }
   if (rule.cascade !== undefined) {
     if (!Array.isArray(rule.cascade) || rule.cascade.length === 0) {
       throw _err("BAD_RULE", "rule.cascade must be a non-empty array of { table, foreignKey } entries");
@@ -163,6 +158,37 @@ function _validateRule(rule) {
   }
 }
 
+/**
+ * @primitive  b.retention.create
+ * @signature  b.retention.create(opts)
+ * @since      0.6.14
+ * @status     stable
+ * @compliance gdpr, hipaa, pci-dss, sox-404, soc2, dora, nis2
+ * @related    b.retention.complianceFloor, b.retention.applyPosture, b.cryptoField.eraseRow, b.legalHold
+ *
+ * Build a retention controller bound to a database handle. Returns an
+ * object with `declare(rule)`, `run(name, runOpts?)`, `runAll(runOpts?)`,
+ * `preview(name)`, and `list()`. Audit emit is on by default; pass
+ * `audit: false` for a quiet controller in tests.
+ *
+ * @opts
+ *   db:    object,                                // b.db handle, must expose .prepare(sql)
+ *   audit: boolean | object,                      // true | false | a b.audit instance
+ *
+ * @example
+ *   var rules = b.retention.create({ db: b.db, audit: true });
+ *   rules.declare({
+ *     name:     "users.notes-ttl",
+ *     table:    "users",
+ *     ageField: "createdAt",
+ *     ttlMs:    C.TIME.days(90),
+ *     action:   "erase",
+ *     batchSize: 500,
+ *     legalHoldField: "__legalHold",
+ *   });
+ *   var summary = await rules.run("users.notes-ttl");
+ *   // → { name, scanned, processed, action: "erase", durationMs, errors: [] }
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, ["db", "audit"], "retention");
@@ -384,9 +410,25 @@ function create(opts) {
           if (rule.legalHoldField && row[rule.legalHoldField]) {
             summary.legalHoldsHonored++;
             _emit("retention.row.legal_hold_skipped",
-              { name: name, table: rule.table, rowId: row._id }, "warning");
+              { name: name, table: rule.table, rowId: row._id,
+                source: "per-row-field" }, "warning");
             continue;
           }
+          // Subject-level legal-hold registry consult. When the rule
+          // names a subjectField (typical for user-keyed retention
+          // tables), the central registry is authoritative. Honors
+          // the same skip semantics as the per-row field.
+          if (rule.subjectField && row[rule.subjectField]) {
+            var holdsRegistry = legalHold._getSingleton();
+            if (holdsRegistry && holdsRegistry.isHeld(row[rule.subjectField])) {
+              summary.legalHoldsHonored++;
+              _emit("retention.row.legal_hold_skipped",
+                { name: name, table: rule.table, rowId: row._id,
+                  source: "subject-registry",
+                  subjectId: row[rule.subjectField] }, "warning");
+              continue;
+            }
+          }
           var action = _stageForRow(rule, row, startedAt);
           if (!action) { summary.skipped++; continue; }
           var actionLabel = typeof action === "function" ? "custom" : action;
@@ -487,6 +529,29 @@ var COMPLIANCE_RETENTION_FLOOR_MS = Object.freeze({
 // Operator passes a posture name + a candidate ttlMs; returns the
 // effective ttl that meets-or-exceeds the floor. Throws if posture is
 // unknown so typos surface at config time.
+/**
+ * @primitive  b.retention.complianceFloor
+ * @signature  b.retention.complianceFloor(posture, candidateTtlMs)
+ * @since      0.7.24
+ * @status     stable
+ * @compliance pci-dss, hipaa, sox-404, soc2, dora, nis2, cra
+ * @related    b.retention.applyPosture, b.retention.create, b.compliance
+ *
+ * Take a regulatory posture name and a candidate TTL; return the
+ * effective TTL that meets-or-exceeds the regime's minimum-retention
+ * floor. Floors come from `COMPLIANCE_RETENTION_FLOOR_MS` (PCI-DSS
+ * §10.7.1: 12 months online; HIPAA 45 CFR §164.316(b)(2)(i): 6 years;
+ * SOX §802: 7 years; DORA Art. 17: 5 years; NIS2 Art. 23: 3 years;
+ * CRA Art. 14: 5 years; LGPD-BR / APPI-JP / PDPA-SG / UK-GDPR variants
+ * matched). Throws on an unknown posture so config-time typos surface.
+ *
+ * @example
+ *   var ttl = b.retention.complianceFloor("hipaa", b.C.TIME.days(180));
+ *   // → 189216000000 (HIPAA's 6-year floor wins over the 180-day candidate)
+ *
+ *   var sox = b.retention.complianceFloor("sox", 0);
+ *   // → 220752000000 (Sarbanes-Oxley §802 — 7 years)
+ */
 function complianceFloor(posture, candidateTtlMs) {
   if (typeof posture !== "string") {
     throw new RetentionError("retention/bad-posture",
@@ -504,9 +569,72 @@ function complianceFloor(posture, candidateTtlMs) {
   return candidateTtlMs > floor ? candidateTtlMs : floor;
 }
 
+// applyPosture — F-POSTURE-1 cascade hook. b.compliance.set(posture)
+// calls this to merge posture defaults into retention's state. The
+// retention module itself doesn't carry per-instance global defaults;
+// the cascade's job here is to surface the posture's audit-log
+// retention floor as the value rules.declare() uses when an operator
+// hasn't passed an explicit ttlMs. Returns the recognized floor (ms)
+// or null when the posture has no retention floor.
+/**
+ * @primitive  b.retention.applyPosture
+ * @signature  b.retention.applyPosture(posture)
+ * @since      0.7.24
+ * @status     stable
+ * @compliance pci-dss, hipaa, sox-404, soc2, dora, nis2, cra
+ * @related    b.retention.complianceFloor, b.retention.activePosture, b.compliance
+ *
+ * Cascade hook called by `b.compliance.set(posture)`. Records the
+ * posture name and its `audit_log` retention floor as module state so
+ * subsequent `complianceFloor` callers without an explicit posture
+ * argument inherit the active value. Returns `null` for an empty
+ * input or a posture with no retention floor; otherwise returns
+ * `{ posture, floorMs }`.
+ *
+ * @example
+ *   b.compliance.set("hipaa");
+ *   b.retention.applyPosture("hipaa");
+ *   // → { posture: "hipaa", floorMs: 189216000000 }
+ *   b.retention.activePosture();
+ *   // → "hipaa"
+ */
+function applyPosture(posture) {
+  if (typeof posture !== "string" || posture.length === 0) return null;
+  var floor = COMPLIANCE_RETENTION_FLOOR_MS[posture];
+  STATE.activePosture = posture;
+  STATE.activeFloorMs = (typeof floor === "number") ? floor : null;
+  return { posture: posture, floorMs: STATE.activeFloorMs };
+}
+
+// Module-level state — read by complianceFloor() callers that omit the
+// posture argument (lookup falls back to the active cascade-set value).
+var STATE = { activePosture: null, activeFloorMs: null };
+
+/**
+ * @primitive  b.retention.activePosture
+ * @signature  b.retention.activePosture()
+ * @since      0.7.24
+ * @status     stable
+ * @related    b.retention.applyPosture, b.compliance.current
+ *
+ * Read the posture name set by the most recent `applyPosture` call,
+ * or `null` if `b.compliance.set` has never run on this process.
+ * Used by audit-dashboard tooling to surface "this deployment is
+ * pinned to <posture>" without crossing into `b.compliance` directly.
+ *
+ * @example
+ *   var p = b.retention.activePosture();
+ *   if (p === null) console.log("no compliance posture pinned");
+ *   else            console.log("active posture:", p);
+ *   // → "hipaa"
+ */
+function activePosture() { return STATE.activePosture; }
+
 module.exports = {
   create:                         create,
   complianceFloor:                complianceFloor,
+  applyPosture:                   applyPosture,
+  activePosture:                  activePosture,
   COMPLIANCE_RETENTION_FLOOR_MS:  COMPLIANCE_RETENTION_FLOOR_MS,
   RetentionError:                 RetentionError,
 };

package/lib/retry.js

@@ -1,35 +1,40 @@
 "use strict";
 /**
- * b.retry — exponential-backoff retry + circuit breaker.
+ * @module b.retry
+ * @nav    Production
+ * @title  Retry
  *
- * Two layers of resilience for any operation that may fail transiently:
+ * @intro
+ *   Retry plus circuit-breaker primitives — exponential backoff with
+ *   jitter, half-open probe, and built-in classification of OS network
+ *   error codes plus retryable HTTP status codes.
  *
- *   1. PER-CALL retry (withRetry) — exponential backoff with jitter.
- *      Default classifier targets HTTP 408/425/429/5xx and Node net-layer
- *      error codes. Caller can override `opts.isRetryable` for non-network
- *      semantics (e.g. operator-defined flush() in handlers).
+ *   `b.retry.withRetry(fn, opts)` wraps a single call: exponential
+ *   backoff (`baseDelayMs * 2^(attempt-1)`, capped at `maxDelayMs`)
+ *   with cryptographic jitter so a thundering-herd of retrying clients
+ *   does not realign on the same boundary. The default classifier
+ *   targets HTTP 408 / 425 / 429 / 5xx and the Node net-layer codes
+ *   (`ECONNRESET`, `ECONNREFUSED`, `ECONNABORTED`, `ETIMEDOUT`,
+ *   `EPIPE`, `EAGAIN`, `ENOTFOUND`, `ENETUNREACH`); callers with
+ *   non-network semantics override via `opts.isRetryable`. The retry
+ *   loop honors `opts.signal` (AbortSignal) so a caller who aborts
+ *   mid-retry is unblocked immediately rather than waiting out the
+ *   backoff.
  *
- *   2. PER-TARGET circuit breaker (CircuitBreaker) — N consecutive
- *      failures opens the circuit (fast-fail for the cooldown window).
- *      After cooldown the breaker enters half-open: probe successes close
- *      it, a probe failure reopens it.
+ *   `b.retry.CircuitBreaker` is the per-target sibling: N consecutive
+ *   failures opens the circuit, opening fast-fails subsequent calls
+ *   for `cooldownMs`, then a half-open state lets one probe call
+ *   through. M consecutive probe successes close the circuit; one
+ *   probe failure reopens it. Permanent errors (`err.permanent`) do
+ *   not trip the breaker — those are caller bugs, not backend health
+ *   issues. Both primitives are side-effect-free on success and
+ *   compose with `b.safeAsync.withTimeout` and any caller-side
+ *   instrumentation. HTTP-client auto-retry is intentionally not
+ *   provided here so timeout, idempotency, and body-replay decisions
+ *   stay explicit at the call site.
  *
- * Both are intentionally side-effect-free in the success path — they
- * compose freely with `safeAsync.withTimeout`, AbortSignals, and any
- * caller-side instrumentation.
- *
- * Validation policy:
- *
- *   - withRetry opts at first call            → throw at call site
- *   - CircuitBreaker constructor opts         → throw at call site
- *   - backoffDelay(attempt) attempt argument  → throw at call site
- *   - isRetryable(err) defensive read         → tolerant (return defaults)
- *   - onRetry callback throw                  → drop silent (hot-path sink)
- *   - breaker internal _onSuccess/_onFailure  → drop silent (hot-path sink)
- *
- * HTTP-client auto-retry is intentionally NOT provided here. Callers
- * wrap their own outbound calls in `b.retry.withRetry(...)` to keep
- * timeout/idempotency/body-replay decisions explicit.
+ * @card
+ *   Retry plus circuit-breaker primitives — exponential backoff with jitter, half-open probe, and built-in classification of OS network error codes plus retryable HTTP status codes.
  */
 
 var C = require("./constants");
@@ -187,6 +192,30 @@ function _validateBreakerOpts(name, opts) {
 
 // ---- Public surface ----
 
+/**
+ * @primitive b.retry.isRetryable
+ * @signature b.retry.isRetryable(err)
+ * @since     0.5.0
+ * @related   b.retry.withRetry, b.retry.backoffDelay
+ *
+ * Default classifier — returns `true` when an error looks transient
+ * and worth retrying, `false` otherwise. Honors `err.permanent` and
+ * `err.isObjectStoreError && err.permanent`; recognizes retryable HTTP
+ * status codes (408 / 425 / 429 / 5xx) and Node net-layer codes
+ * (`ECONNRESET`, `ECONNREFUSED`, `ECONNABORTED`, `ETIMEDOUT`, `EPIPE`,
+ * `EAGAIN`, `ENOTFOUND`, `ENETUNREACH`). Defensive read — missing
+ * fields return `false` rather than throwing, so a malformed error
+ * never crashes the retry loop.
+ *
+ * @example
+ *   var transient = new Error("timeout");
+ *   transient.code = "ETIMEDOUT";
+ *   b.retry.isRetryable(transient);   // → true
+ *
+ *   var fatal = new Error("bad request");
+ *   fatal.statusCode = 400;
+ *   b.retry.isRetryable(fatal);       // → false
+ */
 // Tolerant read of err shape; missing fields → false.
 function isRetryable(err) {
   if (!err) return false;
@@ -202,13 +231,30 @@ function isRetryable(err) {
   return false;                                   // default: not retryable (avoid masking bugs)
 }
 
-// Throw on bad input: attempt must be a positive int; opts (when supplied)
-// must have non-neg-finite baseDelayMs/maxDelayMs and finite jitterFactor
-// in [0,1]. We don't full-validate opts here every call (hot path) —
-// defaults are frozen, so the only way a bad opts reaches here is via
-// withRetry which already validated, OR a caller using backoffDelay
-// directly. For that
-// direct case we still validate the attempt arg loudly.
+/**
+ * @primitive b.retry.backoffDelay
+ * @signature b.retry.backoffDelay(attempt, opts)
+ * @since     0.5.0
+ * @related   b.retry.withRetry, b.retry.isRetryable
+ *
+ * Compute the backoff in milliseconds for a given (1-based) `attempt`
+ * number. Exponential growth `baseDelayMs * 2^(attempt-1)` capped at
+ * `maxDelayMs`, then subtract a cryptographic jitter sample scaled by
+ * `jitterFactor` so retrying clients do not realign on the same
+ * boundary. Throws TypeError when `attempt` is not a positive integer.
+ * `opts` defaults to `b.retry.DEFAULT_RETRY` when absent.
+ *
+ * @opts
+ *   baseDelayMs:  number,   // initial backoff (default 100)
+ *   maxDelayMs:   number,   // cap between attempts (default 10s)
+ *   jitterFactor: number,   // 0..1; 0 = no jitter, 1 = full jitter (default 0.5)
+ *
+ * @example
+ *   var d1 = b.retry.backoffDelay(1, { baseDelayMs: 100, maxDelayMs: 1000, jitterFactor: 0 });
+ *   d1;                       // → 100
+ *   var d3 = b.retry.backoffDelay(3, { baseDelayMs: 100, maxDelayMs: 1000, jitterFactor: 0 });
+ *   d3;                       // → 400
+ */
 function backoffDelay(attempt, opts) {
   if (!_isPositiveInt(attempt)) {
     throw new TypeError("retry.backoffDelay: attempt must be a positive integer, got " +
@@ -224,6 +270,43 @@ function backoffDelay(attempt, opts) {
   return Math.floor(capped - jitter);
 }
 
+/**
+ * @primitive b.retry.withRetry
+ * @signature b.retry.withRetry(fn, opts)
+ * @since     0.5.0
+ * @related   b.retry.isRetryable, b.retry.backoffDelay
+ *
+ * Run `fn(attempt)` with exponential backoff plus jitter. Retries up
+ * to `maxAttempts` while the classifier reports the failure transient;
+ * on a non-retryable error or after the final attempt the underlying
+ * error rethrows. Honors `opts.signal` so an AbortSignal cancels the
+ * backoff sleep. The `opts.onRetry` hook is invoked between attempts
+ * with `{ attempt, delay, error }`; throws inside the hook are
+ * captured and surfaced as `retry.onRetry.threw` observability events
+ * — the retry loop itself never crashes.
+ *
+ * @opts
+ *   maxAttempts:  number,    // total tries incl. first (default 5)
+ *   baseDelayMs:  number,    // initial backoff (default 100)
+ *   maxDelayMs:   number,    // cap between attempts (default 10s)
+ *   jitterFactor: number,    // 0..1 (default 0.5)
+ *   isRetryable:  function,  // override classifier (default b.retry.isRetryable)
+ *   onRetry:      function,  // ({ attempt, delay, error }) -> void
+ *   signal:       object,    // AbortSignal — cancels the backoff sleep
+ *
+ * @example
+ *   var attempts = 0;
+ *   var result = await b.retry.withRetry(async function () {
+ *     attempts += 1;
+ *     if (attempts < 2) {
+ *       var err = new Error("nope");
+ *       err.code = "ECONNRESET";
+ *       throw err;
+ *     }
+ *     return "ok";
+ *   }, { maxAttempts: 3, baseDelayMs: 1, maxDelayMs: 1, jitterFactor: 0 });
+ *   result;                  // → "ok"
+ */
 async function withRetry(fn, opts) {
   if (typeof fn !== "function") {
     throw new TypeError("retry.withRetry: fn must be a function, got " + typeof fn);