@blamejs/core 0.8.43 → 0.8.49

package/lib/budr.js

@@ -1,38 +1,27 @@
 "use strict";
 /**
- * b.budr — backup, disaster-recovery, RTO/RPO declaration primitive.
+ * @module b.budr
+ * @nav    Production
+ * @title  BC/DR
  *
- * Operators in regulated environments (HIPAA / DORA / ISO 22301:2019 /
- * NIST SP 800-34) must declare their Recovery Time Objective (RTO,
- * how long systems can be down before unacceptable impact) and
- * Recovery Point Objective (RPO, max acceptable data loss). The
- * declaration is auditor-facing — regulators want it on file as part
- * of business-continuity / disaster-recovery documentation.
+ * @intro
+ *   Backup / Disaster-Recovery RTO/RPO declaration primitive for
+ *   regulated workloads (HIPAA / DORA / ISO 22301:2019 / NIST
+ *   SP 800-34). Operators declare their Recovery Time Objective (max
+ *   acceptable downtime) and Recovery Point Objective (max acceptable
+ *   data loss) per service; the framework captures the targets in a
+ *   tamper-evident audit row and exposes them via `list()` / `get()`
+ *   for dashboard / regulator-export use.
  *
- * The framework can't enforce RTO/RPO end-to-end (those depend on
- * downstream backup cadence, replication topology, restore testing).
- * What it can do: capture the operator's declared targets in a
- * tamper-evident audit row + expose them to dashboards.
+ *   The framework cannot enforce end-to-end RTO/RPO — those depend on
+ *   downstream backup cadence, replication topology, and restore
+ *   testing the operator owns. What it does enforce is the shape of
+ *   the declaration (typed targets, BCDR tier vocabulary, regulator
+ *   citation list) so the auditor-facing record stays consistent
+ *   across services.
  *
- * Public API:
- *
- *   b.budr.declare(opts) -> declaration
- *     opts:
- *       service:        operator-named service identifier (string).
- *       rtoMs:          Recovery Time Objective in milliseconds.
- *       rpoMs:          Recovery Point Objective in milliseconds.
- *       tier:           "platinum" / "gold" / "silver" / "bronze"
- *                       (BCDR criticality classification — platinum
- *                       most-critical).
- *       criticality:    "critical" / "high" / "medium" / "low".
- *       owner:          operator-named accountable owner (team / role).
- *       reviewedAt:     timestamp of the most recent operator review.
- *       citations:      array of regulatory citations (e.g. ["dora-art-11", "iso-22301:2019"]).
- *       audit:          bool, default true.
- *
- *   b.budr.list() -> Array<declaration>
- *
- *   b.budr.get(service) -> declaration | null
+ * @card
+ *   Backup / Disaster-Recovery RTO/RPO declaration primitive for regulated workloads (HIPAA / DORA / ISO 22301:2019 / NIST SP 800-34).
  */
 
 var nb = require("./numeric-bounds");
@@ -48,6 +37,45 @@ var CRITICALITIES = ["critical", "high", "medium", "low"];
 
 var declarations = new Map();
 
+/**
+ * @primitive b.budr.declare
+ * @signature b.budr.declare(opts)
+ * @since     0.8.0
+ * @status    stable
+ * @compliance hipaa, dora, soc2
+ * @related   b.budr.get, b.budr.list, b.dora.create
+ *
+ * Register a service's Recovery Time Objective + Recovery Point
+ * Objective targets. Each call replaces the previous declaration for
+ * the same `service` and emits a `budr.declared` audit row carrying
+ * the typed targets, BCDR tier, criticality, owner, and regulator
+ * citations. Throws `BudrError` on bad opts (unknown tier, missing
+ * targets, citation list not an array).
+ *
+ * @opts
+ *   service:     string (1..128 chars, [A-Za-z0-9._:/-]),
+ *   rtoMs:       number  (positive finite integer milliseconds),
+ *   rpoMs:       number  (positive finite integer milliseconds),
+ *   tier:        "platinum" | "gold" | "silver" | "bronze",
+ *   criticality: "critical" | "high" | "medium" | "low",
+ *   owner:       string  (team / role accountable for restore),
+ *   reviewedAt:  number  (ms-since-epoch of last operator review),
+ *   citations:   Array<string>  (e.g. ["dora-art-11", "iso-22301:2019"]),
+ *   audit:       boolean         (default true; set false to skip audit emit),
+ *
+ * @example
+ *   var dec = b.budr.declare({
+ *     service:     "payments-gateway",
+ *     rtoMs:       60 * 60 * 1000,
+ *     rpoMs:       5 * 60 * 1000,
+ *     tier:        "platinum",
+ *     criticality: "critical",
+ *     owner:       "team-payments",
+ *     citations:   ["dora-art-11", "iso-22301:2019"],
+ *   });
+ *   dec.tier;     // → "platinum"
+ *   dec.rtoMs;    // → 3600000
+ */
 function declare(opts) {
   if (!opts || typeof opts !== "object") {
     throw BudrError.factory("BAD_OPTS", "budr.declare: opts required");
@@ -109,12 +137,57 @@ function declare(opts) {
   return declaration;
 }
 
+/**
+ * @primitive b.budr.get
+ * @signature b.budr.get(service)
+ * @since     0.8.0
+ * @status    stable
+ * @related   b.budr.declare, b.budr.list
+ *
+ * Look up the registered declaration for `service`. Returns the
+ * frozen declaration object on hit, `null` on miss or non-string
+ * input. Cheap — purely an in-memory Map lookup.
+ *
+ * @example
+ *   b.budr.declare({
+ *     service: "core-ledger", rtoMs: 1800000, rpoMs: 60000,
+ *     tier: "platinum", criticality: "critical",
+ *   });
+ *   var dec = b.budr.get("core-ledger");
+ *   dec.rpoMs;                    // → 60000
+ *   b.budr.get("not-registered"); // → null
+ */
 function get(service) {
   if (typeof service !== "string") return null;
   var rec = declarations.get(service);
   return rec === undefined ? null : rec;
 }
 
+/**
+ * @primitive b.budr.list
+ * @signature b.budr.list()
+ * @since     0.8.0
+ * @status    stable
+ * @related   b.budr.declare, b.budr.get
+ *
+ * Snapshot of every registered declaration in insertion order.
+ * Returns a fresh array — mutating it does not affect the registry.
+ * Use this to drive a dashboard table or to export the operator's
+ * BCDR posture for an auditor.
+ *
+ * @example
+ *   b.budr.declare({
+ *     service: "payments-gateway", rtoMs: 3600000, rpoMs: 300000,
+ *     tier: "platinum", criticality: "critical",
+ *   });
+ *   b.budr.declare({
+ *     service: "reporting", rtoMs: 14400000, rpoMs: 3600000,
+ *     tier: "silver", criticality: "medium",
+ *   });
+ *   var all = b.budr.list();
+ *   all.length;                   // → 2
+ *   all[0].service;               // → "payments-gateway"
+ */
 function list() {
   return Array.from(declarations.values());
 }

package/lib/bundler.js

@@ -1,80 +1,46 @@
 "use strict";
 /**
- * bundler — content-hashed asset pipeline + manifest, with optional
- * operator-supplied ESM engine for module-graph bundling, tree-shaking,
- * minification, and source maps.
+ * @module b.bundler
+ * @nav    Tools
+ * @title  Bundler
  *
- * What this primitive does:
- *   - Reads each named entry from disk (or runs it through an
- *     operator-supplied engine first for module-graph builds)
- *   - Computes a content hash (SHA3-512, first 16 hex chars)
- *   - Writes the entry to outdir/<name>.<hash>.<ext> for cache-busting
- *   - Emits manifest.json mapping logical name → hashed filename
- *   - Optionally watches entries and rebuilds on change
+ * @intro
+ *   Client-side asset bundler — produces content-hashed
+ *   `dist/<name>.<hash>.<ext>` files plus a `manifest.json` mapping
+ *   logical name to hashed filename. Designed to drop into a static
+ *   server (`b.static`) so cache-busting lives at the filename layer
+ *   and HTML can long-cache hashed paths.
  *
- * Engine surface (new in v0.6.44):
+ *   No-build-step fallback: the default `engine.passthrough` reads
+ *   each entry from disk verbatim, hashes it, and writes the hashed
+ *   copy. Operators with no module-graph need ship their source files
+ *   directly through the bundler and skip the toolchain entirely.
  *
- *   var bundler = b.bundler.create({
- *     entries: { app: "./src/app.js" },
- *     outdir:  "./public/dist",
- *     engine:  engineInstance,        // optional — defaults to passthrough
- *   });
- *
- * `engineInstance` implements:
- *
- *   {
- *     name:       string,                          // logged on build
- *     transform:  async (entryPath, contentBuf) => {
- *       content:   Buffer | string,                 // post-transform output
- *       sourceMap: string | Buffer | null,          // optional .map sibling
- *       imports?:  [string],                        // optional — for graph-aware watch
- *     },
- *   }
- *
- * The default engine is `b.bundler.engine.passthrough` — reads the file
- * verbatim, no transform. This is what every existing `b.bundler.create`
- * call gets without setting `engine`.
+ *   Module-graph / tree-shake / minify / sourcemaps: operators supply
+ *   esbuild (devDependency, never vendored) and adapt it via
+ *   `engine.fromEsbuild(esbuild, opts)` — the framework owns the
+ *   integration seam, the operator brings the heavy machinery. The
+ *   ~10 MB esbuild-wasm blob is intentionally not vendored.
  *
- * For ESM module-graph bundling + tree-shake + minify + sourcemaps,
- * operators supply esbuild themselves (devDependency or operator-side
- * vendored) and adapt it via:
+ *   Hashes are SHA3-512, first 16 hex chars by default (operators
+ *   override via `opts.hashLen` between 4 and 64). Source maps written
+ *   by an engine land as `<hashed>.<ext>.map` siblings.
  *
- *   var esbuild = require("esbuild");
- *   var bundler = b.bundler.create({
- *     entries: { app: "./src/app.js" },
- *     outdir:  "./public/dist",
- *     engine:  b.bundler.engine.fromEsbuild(esbuild, {
- *       bundle:    true,
- *       format:    "esm",
- *       target:    ["chrome120", "firefox120", "safari17"],
- *       minify:    true,
- *       sourcemap: true,
- *     }),
- *   });
+ *   Watch mode: `bundler.watch(callback)` arms `fs.watch` on each
+ *   entry's directory, debounces bursts via `opts.graceMs` (default
+ *   100 ms), and rebuilds the entire entry set on change.
  *
- * The framework intentionally does NOT vendor `esbuild-wasm` itself
- * (the wasm blob is ~10 MB — bigger than every other vendored dep
- * combined; it would 3-5x the @blamejs/core npm tarball for a build-
- * time tool most operators only need at deploy time anyway). Treating
- * esbuild as an operator-supplied driver follows the same pattern as
- * `b.externalDb` and `b.mtlsCa.create({ engine })`: the framework owns
- * the integration seam, the operator brings the heavy machinery.
+ *   Manifest format:
  *
- * Out of scope (true even with the engine surface):
- *   - A bespoke bundler bundled INSIDE the framework. The engine
- *     surface IS the answer; operators wanting esbuild / rollup /
- *     swc / vite wire them through it.
+ *     { "app": "app.4a8c2f1d9e3b7062.js", "styles": "styles.b29f1e7c.css" }
  *
- * Operator with no engine + multi-file ESM source: pre-concat manually
- * and point bundler at the result.
+ *   Integrates with `lib/static.js`: serve `outdir` as a static
+ *   directory; `b.static`'s hashed-path detection sets long-cache
+ *   headers on files that look hashed, and `integrity()` reads the
+ *   manifest to emit Subresource Integrity attributes.
  *
- * Manifest format (manifest.json under outdir):
- *   { "app": "app.4a8c2f1d9e3b7062.js", "styles": "styles.b29f1e7c.css" }
- *
- * Integrates with lib/static.js: serve `outdir` as a static directory;
- * lib/static.js's hashed-path detection sets long-cache headers on
- * files that look hashed, and integrity() reads the manifest to
- * generate Subresource Integrity attributes.
+ * @card
+ *   Client-side asset bundler — produces content-hashed `dist/<name>.<hash>.<ext>` files plus a `manifest.json` mapping logical name to hashed filename.
  */
 
 var path = require("path");
@@ -224,6 +190,60 @@ function _validateEngine(eng) {
   return eng;
 }
 
+/**
+ * @primitive b.bundler.create
+ * @signature b.bundler.create(opts)
+ * @since     0.4.0
+ * @status    stable
+ * @related   b.static.serve
+ *
+ * Build a content-hashed asset pipeline for a fixed set of named
+ * entries. The returned object exposes `build()` (one-shot rebuild,
+ * resolves to `{ outputs, manifestPath, manifest, durationMs }`),
+ * `watch(callback)` (arm `fs.watch` and debounce-rebuild on change),
+ * and `close()` (drop watchers and pending timers).
+ *
+ * Throws `BundlerError` at config time on missing / malformed entries,
+ * missing `outdir`, an out-of-range `hashLen`, or an engine that does
+ * not implement `{ name, transform }`.
+ *
+ * @opts
+ *   entries:  { [name: string]: string },   // logical name → source path
+ *   outdir:   string,                        // dist directory (created if missing, mode 0o755)
+ *   cwd:      string,                        // resolves relative entries / outdir; defaults to process.cwd()
+ *   engine:   { name: string, transform: async (entryPath, contentBuf) => { content, sourceMap?, imports? } },
+ *                                            // defaults to engine.passthrough
+ *   manifest: string | false,                // manifest filename ("manifest.json"), or false to skip
+ *   hash:     boolean,                       // emit <name>.<hash>.<ext>; default true
+ *   hashLen:  number,                        // hex chars in the hash, 4..64; default 16
+ *   graceMs:  number,                        // watch-mode debounce ms; default 100
+ *   log:      object,                        // structured logger ({ info, warn, error })
+ *
+ * @example
+ *   var bundler = b.bundler.create({
+ *     entries: { app: "./src/app.js", styles: "./src/styles.css" },
+ *     outdir:  "./public/dist",
+ *     hashLen: 16,
+ *   });
+ *
+ *   // bundler.build() returns a Promise resolving to:
+ *   //   { outputs: [...], manifest: { app: "app.<hash>.js", styles: "styles.<hash>.css" },
+ *   //     manifestPath: ".../public/dist/manifest.json", durationMs: <number> }
+ *
+ *   // Watch mode — rebuild on edits.
+ *   bundler.watch(function (err, result) {
+ *     if (err) return;
+ *     // result.manifest is the freshly-written name→hashed-filename map
+ *   });
+ *
+ *   // Operator-supplied esbuild for module-graph + tree-shake + minify.
+ *   // var esbuild = require("esbuild");
+ *   // var modGraph = b.bundler.create({
+ *   //   entries: { app: "./src/app.js" },
+ *   //   outdir:  "./public/dist",
+ *   //   engine:  b.bundler.engine.fromEsbuild(esbuild, { minify: true, sourcemap: true }),
+ *   // });
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/cache.js

@@ -1,88 +1,73 @@
 "use strict";
 /**
- * b.cache — operator-facing cache primitive.
+ * @module b.cache
+ * @nav    Data
+ * @title  Cache
  *
- *   var cache = b.cache.create({
- *     namespace:   "session.user",
- *     backend:     "memory",
- *     ttlMs:       C.TIME.minutes(5),
- *     maxEntries:  10000,
- *     maxBytes:    C.BYTES.mib(100),                 // memory backend only
- *     sizeOf:      function (v) { return v.byteLength; },  // optional override
- *     slidingTtl:  true,                              // bump expiresAt on hit
- *     audit:       b.audit,                           // optional
- *   });
- *
- *   await cache.set("u-42", record, { ttlMs: C.TIME.minutes(10), tags: ["user:42", "session"] });
- *   var hit = await cache.get("u-42");
- *
- *   // Memoize / read-through:
- *   var profile = await cache.wrap("u-42", function () {
- *     return db.users.findOne({ _id: "u-42" });
- *   });
- *
- *   // Bulk invalidate (memory backend):
- *   await cache.invalidateTag("user:42");          // purges every entry tagged user:42
- *
- * Surface (returned by create):
+ * @intro
+ *   LRU + TTL cache with operator-supplied namespacing, drop-silent
+ *   key validation on hot-path observability, and pluggable backends
+ *   that share semantics across single-process and clustered nodes.
  *
- *   get(key)                  → value | undefined
- *   set(key, value, opts?)    → void                  (opts: { ttlMs, tags })
- *   del(key)                  → boolean (existed)
- *   has(key)                  → boolean (does NOT bump LRU recency)
- *   clear(opts?)              → number (purged)        (opts: { req, context })
- *   size()                    → number
- *   bytes()                   → number (memory backend only — total stored bytes)
- *   wrap(key, fn, opts?)      → fn's return value      (opts: { ttlMs, singleFlight })
- *   invalidateTag(tag, opts?) → number (purged)        (opts: { req, context })
- *   getTags(key)              → string[] | null
- *   close()                   → void
+ *   Three first-class backends ship in the box:
  *
- * Backends:
+ *     - "memory" (default) — Map + LRU eviction (maxEntries) + bytes
+ *       eviction (maxBytes) + periodic sweep. Single-process accuracy.
+ *     - "cluster" — _blamejs_cache table via cluster-storage. One
+ *       table serves every CacheInstance via "<namespace>:<key>"
+ *       composite key; ON CONFLICT UPSERT for atomic set.
+ *     - "redis" — cache-redis client; sliding TTL via EXPIRE; tag
+ *       wipes via SCAN+DEL on a per-namespace prefix.
  *
- *   "memory" (default) — Map + LRU eviction (maxEntries) + periodic
- *     sweep timer (sweepIntervalMs). Single-process accuracy only.
+ *   A `{ get, set, del, clear, size, close }` operator-supplied
+ *   object is the custom-backend escape hatch (Memcached, in-memory
+ *   harnesses, anything else with the same async surface).
  *
- *   "cluster" — _blamejs_cache table via cluster-storage. PRIMARY KEY
- *     is "<namespace>:<key>" so one table serves every CacheInstance.
- *     UPSERT via ON CONFLICT for atomic set; DELETE WHERE expiresAt
- *     for sweep. JSON-only value serialization.
+ *   Hot-path validation policy:
  *
- *   { get, set, del, clear, size, close } — operator-supplied custom
- *     backend (Redis, Memcached, …). All methods async.
+ *     - create() opts             → throw at boot (config-time)
+ *     - key arg on get/set/del    → throw at call site (programming bug)
+ *     - per-call ttlMs override   → throw at call site (silent footgun
+ *                                   if accepted)
+ *     - audit / observability     → drop silent (hot-path sink)
+ *     - method-after-close        → throw BAD_STATE
  *
- * Validation policy:
+ *   Security defaults that are NOT opt-in:
  *
- *   - create() opts                       → throw at boot
- *   - get/set/del/has/wrap key arg type   → throw at call site (programming bug)
- *   - set value type                      → tolerant (operator decides what to store)
- *   - per-call ttlMs override             → throw at call site (bad ttl is silent footgun)
- *   - audit / observability emit failures → drop silent (hot-path sink)
- *   - method called after close()         → throw BAD_STATE at call site
+ *     - auditClear: true     mass purges are operator-action shaped
+ *     - auditFailures: true  backend errors are signal
+ *     - hot-path get/set/hit/miss/eviction → observability only
+ *       (the audit chain would drown at any reasonable QPS)
  *
- * Security defaults:
+ *   Returned `CacheInstance` shape:
  *
- *   - auditClear: true     — mass purge is operator-action shaped (can hide forensics)
- *   - auditFailures: true  — backend errors are signal
- *   - hot-path get/set/hit/miss/eviction → observability only (audit chain
- *     would drown at any reasonable QPS)
+ *     get(key) → value | undefined
+ *     set(key, value, opts?) → void          (opts: { ttlMs, tags, seal })
+ *     del(key) → boolean
+ *     has(key) → boolean                     (does NOT bump LRU recency)
+ *     clear(opts?) → number                  (opts: { req, context })
+ *     size() → number
+ *     bytes() → number                       (memory backend only)
+ *     wrap(key, fn, opts?) → fn's return     (opts: { ttlMs, singleFlight })
+ *     invalidateTag(tag, opts?) → number     (opts: { req, context })
+ *     getTags(key) → string[] | null
+ *     close() → void
  *
- * The cache supports single-flight wrap (concurrent calls collapse),
- * stale-while-revalidate, LRU + bytes eviction on the memory backend,
- * sliding TTL on hit, tag-based bulk invalidation (memory backend), a
- * shared cluster backend, and a custom-backend escape hatch.
+ *   Stale-while-revalidate, single-flight wrap (concurrent calls
+ *   collapse to one compute), tag-based bulk invalidation (memory +
+ *   cluster), and cross-node invalidation via b.pubsub are all built
+ *   in — operator opts in via the `staleWhileRevalidate` /
+ *   `invalidationPubsub` opts.
  *
- * What is NOT in the box:
+ *   What is NOT in the box: maxBytes on the cluster backend (would
+ *   require an aggregate query per set; operator prunes the shared
+ *   table on their own schedule) and per-entry exact slidingTtl on
+ *   the cluster backend (sliding extends by the cache's defaultTtlMs;
+ *   operators with mixed-TTL writes wanting strict per-entry sliding
+ *   use the memory backend or extend at the application layer).
  *
- *   - maxBytes on the cluster backend — per-row size accounting against
- *     a shared table would mean an aggregate query on every set. The
- *     operator controls cluster-table size with their own pruning if
- *     bytes pressure surfaces.
- *   - Per-entry exact slidingTtl on the cluster backend — sliding works
- *     on cluster but extends by the cache's defaultTtlMs (we don't
- *     store per-row ttl). Operators with mixed-TTL writes wanting
- *     strict per-entry sliding use the memory backend or extend at
- *     the application layer.
+ * @card
+ *   LRU + TTL cache with operator-supplied namespacing, drop-silent key validation on hot-path observability, and pluggable backends that share semantics across single-process and clustered nodes.
  */
 
 var cacheRedis = require("./cache-redis");
@@ -100,6 +85,15 @@ var { CacheError } = require("./framework-error");
 
 var log = boot("cache");
 var observability = lazyRequire(function () { return require("./observability"); });
+// D-L5 — opt-in vault seal for cluster-backend cache values. Lazy so
+// vault-not-initialized in tests with a memory cache doesn't crash
+// at module load.
+var vault = lazyRequire(function () { return require("./vault"); });
+// Marker bytes that prefix sealed values in _blamejs_cache.valueJson —
+// "blamejs:cache.sealed:" + base64-of-vault-sealed-payload. The
+// non-prefixed cache rows pass straight through JSON.parse as before
+// so the seal opt is a strict per-call upgrade with no migration.
+var CACHE_SEAL_PREFIX = "blamejs:cache.sealed:";
 
 var _err = CacheError.factory;
 
@@ -486,7 +480,17 @@ function _clusterBackend(cfg) {
         [newExpires, now, _composedKey(key), now]
       ).catch(function () { /* best-effort */ });
     }
-    try { return safeJson.parse(row.valueJson, { maxBytes: C.BYTES.mib(64) }); }
+    var stored = row.valueJson;
+    // D-L5 — sealed-row decode. Sealed entries are prefixed at write
+    // time so the unseal-on-read path is a strict opt-in: rows
+    // written without seal:true continue parsing as before.
+    if (typeof stored === "string" && stored.indexOf(CACHE_SEAL_PREFIX) === 0) {
+      try {
+        var unsealed = vault().unseal(stored.substring(CACHE_SEAL_PREFIX.length));
+        return safeJson.parse(unsealed, { maxBytes: C.BYTES.mib(64) });
+      } catch (_e) { return undefined; }
+    }
+    try { return safeJson.parse(stored, { maxBytes: C.BYTES.mib(64) }); }
     catch (_e) { return undefined; }
   }
 
@@ -497,6 +501,13 @@ function _clusterBackend(cfg) {
     // changed value, app code treats it as the original" — a subtle
     // freshness bug that's hard to debug.
     var json = safeJson.stringify(value);
+    // D-L5 — opt-in vault seal. When the caller passes seal: true,
+    // wrap the JSON via b.vault.seal (XChaCha20-Poly1305) before
+    // landing in _blamejs_cache.valueJson. The marker prefix is what
+    // get() looks for to know it must unseal on read.
+    if (meta && meta.seal === true) {
+      json = CACHE_SEAL_PREFIX + vault().seal(json);
+    }
     var storedExpires = (expiresAt === Infinity) ? Number.MAX_SAFE_INTEGER : expiresAt;
     var now = clock();
     var ck = _composedKey(key);
@@ -713,6 +724,103 @@ function _customBackend(operatorBackend, cfg) {
 
 // ---- Public create ----
 
+/**
+ * @primitive b.cache.create
+ * @signature b.cache.create(opts)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.pubsub.create, b.audit
+ *
+ * Build a `CacheInstance` bound to a `namespace`. The instance owns
+ * its sweep timer, its backend connection, its single-flight inflight
+ * map, and (when `invalidationPubsub` is supplied) a pubsub
+ * subscription that mirrors `del` / `clear` / `invalidateTag` events
+ * across nodes. Multiple instances coexist — a "session.user" memory
+ * cache and a "billing.invoice" cluster cache share neither keys nor
+ * tags. `close()` releases everything.
+ *
+ * The `backend` opt picks the storage tier: `"memory"` (default,
+ * single-process LRU+TTL), `"cluster"` (shared SQL table for
+ * multi-node coherence), `"redis"` (when `redisUrl` is supplied;
+ * native EXPIRE-based TTL), or an operator-supplied object with
+ * `{ get, set, del, clear, size, close }` for any other store.
+ * Backends are interchangeable from the caller's perspective —
+ * `await cache.get(key)` returns the same shape regardless.
+ *
+ * @opts
+ *   namespace:               string,                       // required; collision domain; must not contain ':'
+ *   backend:                 "memory" | "cluster" | "redis" | object,  // default "memory"
+ *   ttlMs:                   number | Infinity,            // default C.TIME.minutes(5)
+ *   maxEntries:              number | Infinity,            // memory backend cap; default 10000
+ *   maxBytes:                number | Infinity,            // memory backend cap; default Infinity
+ *   sizeOf:                  function(value) -> number,    // memory bytes accounting override
+ *   sweepIntervalMs:         number,                       // expired-entry sweep cadence; default C.TIME.minutes(1); minimum 1000
+ *   staleWhileRevalidate:    boolean,                      // wrap() serves stale + refreshes in background; default false
+ *   slidingTtl:              boolean,                      // bump expiresAt on hit; default false
+ *   auditFailures:           boolean,                      // emit audit on backend errors; default true
+ *   auditClear:              boolean,                      // emit audit on clear / invalidateTag; default true
+ *   audit:                   { emit } | b.audit,           // audit sink override
+ *   observability:           { event } | b.observability,  // metrics sink override
+ *   clock:                   function() -> number,         // Date.now() override (testing)
+ *   invalidationPubsub:      b.pubsub instance,            // cross-node del/clear/tag mirroring
+ *   redisUrl:                string,                       // backend === "redis" only; required there
+ *   redisPassword:           string,                       // backend === "redis" only
+ *   redisUsername:           string,                       // backend === "redis" only
+ *   redisTls:                boolean,                      // backend === "redis" only
+ *   redisCa:                 string | Buffer,              // backend === "redis" only; PEM CA bundle
+ *   redisServername:         string,                       // backend === "redis" only; SNI override
+ *   redisConnectTimeoutMs:   number,                       // backend === "redis" only
+ *   redisCommandTimeoutMs:   number,                       // backend === "redis" only
+ *   redisMaxReconnectAttempts: number,                     // backend === "redis" only
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var C = b.constants;
+ *
+ *   // Simple set/get against the default memory backend.
+ *   var sessions = b.cache.create({
+ *     namespace:  "session.user",
+ *     ttlMs:      C.TIME.minutes(5),
+ *     maxEntries: 10000,
+ *   });
+ *   await sessions.set("u-42", { uid: "u-42", role: "admin" });
+ *   var hit = await sessions.get("u-42");
+ *   // → { uid: "u-42", role: "admin" }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var C = b.constants;
+ *
+ *   // wrap() pattern with per-call TTL override + single-flight.
+ *   // Concurrent callers collapse to one DB read; subsequent reads
+ *   // serve from cache for 10 minutes.
+ *   var profiles = b.cache.create({
+ *     namespace: "billing.profile",
+ *     ttlMs:     C.TIME.minutes(2),
+ *   });
+ *   var profile = await profiles.wrap(
+ *     "u-42",
+ *     function () { return { uid: "u-42", plan: "pro" }; },
+ *     { ttlMs: C.TIME.minutes(10) }
+ *   );
+ *   // → { uid: "u-42", plan: "pro" }
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var C = b.constants;
+ *
+ *   // Cluster-shared cache: every node sees the same entries via the
+ *   // _blamejs_cache table. Tag-based bulk invalidation purges across
+ *   // every namespace member in one call.
+ *   var inventory = b.cache.create({
+ *     namespace: "catalog.item",
+ *     backend:   "cluster",
+ *     ttlMs:     C.TIME.minutes(15),
+ *   });
+ *   await inventory.set("sku-1001", { qty: 42 }, { tags: ["warehouse:east"] });
+ *   var purged = await inventory.invalidateTag("warehouse:east");
+ *   // → 1
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
@@ -885,7 +993,19 @@ function create(opts) {
         }
       }
     }
-    try { await backend.set(key, value, expiresAt, { ttlMs: ttlMs, tags: tags }); }
+    // D-L5 — opt-in vault seal. Strict-shape check: must be the literal
+    // boolean true, not just truthy. Backends that don't support seal
+    // (memory, custom) ignore the flag transparently; cluster backend
+    // wraps valueJson via b.vault.seal before INSERT.
+    var seal = !!(callerOpts && callerOpts.seal === true);
+    if (seal && backend.name !== "cluster") {
+      throw _err("BAD_OPT",
+        "cache.set: seal: true is only supported on the cluster backend " +
+        "(this cache instance uses '" + (backend.name || "custom") + "'). " +
+        "Memory-backed caches do not need seal because the value never reaches disk; " +
+        "custom backends wrap their own at-rest encryption.");
+    }
+    try { await backend.set(key, value, expiresAt, { ttlMs: ttlMs, tags: tags, seal: seal }); }
     catch (e) {
       emitObs("cache.backend.failed", { namespace: namespace, op: "set" });
       _backendFailedAudit("set", e);