@blamejs/core 0.6.6 → 0.6.11

package/CHANGELOG.md

@@ -8,6 +8,12 @@ upgrading across more than a few patches at a time.
 
 ## v0.6.x
 
+- **0.6.11** (2026-05-01) — wiki example-execution validator: fixture init no longer reaches across module realms (unblocks the npm-publish workflow's wiki-e2e gate, which `npm install --install-links` copies the framework into the wiki's node_modules — two distinct singletons before this fix)
+- **0.6.10** (2026-05-01) — README / SECURITY / CONTRIBUTING / wiki: removed stale version stamps and an inaccurate vendored-dep list; SECURITY now points at `lib/vendor/MANIFEST.json` for the authoritative vendor list; supported-versions table no longer pins to a specific minor; wiki archive example names the digest variable correctly (was `sha256`, output is SHA3-512 hex)
+- **0.6.9** (2026-05-01) — b.archive.zip().digest() returns a SHA3-512 hex string (was SHA-256); operators reconciling against an external SHA-256 must hash the bytes themselves
+- **0.6.8** (2026-05-01) — wiki primitive-section validator: presence + opts diff + example execution against canonical fixture
+- **0.6.7** (2026-05-01) — db.role.switched audit + per-role metrics + API snapshot baseline
+- **0.6.6** (2026-05-01) — request-time DB role binding + Postgres RLS migrations
 - **0.6.5** (2026-05-01) — b.db.declareView + b.externalDb.migrate
 - **0.6.4** (2026-05-01) — wiki schema docs realigned with the actual lib API
 - **0.6.3** (2026-05-01) — externalDb pool tuning + role-aware connect + read-replica routing
@@ -72,7 +78,7 @@ upgrading across more than a few patches at a time.
 
 ## v0.3.x
 
-- **0.3.39** (2026-04-29) — MIGRATING.md generator scans deprecate() calls in lib/
+- **0.3.39** (2026-04-29) — MIGRATING.md generator scans deprecate calls in lib/
 - **0.3.38** (2026-04-29) — LTS-CALENDAR.md publishes the major-cadence + algorithm posture
 - **0.3.37** (2026-04-29) — bundled pure-JS mTLS engine + vendor-update.sh + CHANGELOG + thanks page
 - **0.3.36** (2026-04-29) — prepack guard refuses to publish any path that matches a gitignore rule
@@ -87,15 +93,15 @@ upgrading across more than a few patches at a time.
 - **0.3.27** (2026-04-29) — Dockerfile pre-builds public/dist in deps stage so runtime container boots cleanly under --cap-drop ALL
 - **0.3.26** (2026-04-29) — operator-facing env-var surface, GitHub-side ops docs, contribution standards
 - **0.3.25** (2026-04-29) — env-var surface documented across Dockerfile, docker-compose.prod, DEPLOY.md, README; smoke-test GHCR login fix
-- **0.3.24** (2026-04-29) — CI + release-container workflows brought to hermitstash parity (structured output, multi-arch, cosign, post-publish smoke)
+- **0.3.24** (2026-04-29) — CI + release-container workflows brought (structured output, multi-arch, cosign, post-publish smoke)
 - **0.3.23** (2026-04-29) — _runVault and _runBackup refactored to use b.cliHelpers (sweep complete across the three CLI commands the helper was designed for)
 - **0.3.22** (2026-04-29) — blamejs api-key CLI; b.cliHelpers shared primitive for headless app + reporter shape
 - **0.3.21** (2026-04-29) — blamejs backup CLI: inspect / verify / extract; backup encryption format documented
 - **0.3.20** (2026-04-29) — drop redundant Windows-flaky audit.flush perf assertion
 - **0.3.19** (2026-04-29) — wiki docs for the unwired primitives surface
 - **0.3.18** (2026-04-29) — blamejs vault CLI: seal / unseal / rotate / status
-- **0.3.17** (2026-04-29) — Tier-A validateOpts coverage extended to remaining operator-facing primitives (i18n, bundler, migrations, seeders, template, jobs, cookies, log, mtlsCa, staticServe, handlers, websocket, pqcGate, tracing, metrics — 15 more factories now reject typo'd opts at boot). Coverage is now ~39/lib primitives with the helper; the remaining handful (app-shutdown, chain-writer, dev, error-page, nonce-store, protocol-dispatcher, render, session, pqc-agent) are either internal-only — operators don't construct them directly — or have a single required-key surface where typo guards add no value.
-- **0.3.16** (2026-04-29) — Tier-A config validation, CSRF cookie mode, HTML balance, dynamic Cache-Control, URL canonicalization
+- **0.3.17** (2026-04-29) — validateOpts coverage extended to remaining operator-facing primitives (i18n, bundler, migrations, seeders, template, jobs, cookies, log, mtlsCa, staticServe, handlers, websocket, pqcGate, tracing, metrics — 15 more factories now reject typo'd opts at boot). Coverage is now ~39/lib primitives with the helper; the remaining handful (app-shutdown, chain-writer, dev, error-page, nonce-store, protocol-dispatcher, render, session, pqc-agent) are either internal-only — operators don't construct them directly — or have a single required-key surface where typo guards add no value.
+- **0.3.16** (2026-04-29) — config validation, CSRF cookie mode, HTML balance, dynamic Cache-Control, URL canonicalization
 - **0.3.15** (2026-04-29) — cors: accept Origin: null when Sec-Fetch-Site is same-origin (browsers send opaque Origin: null on form-navigation POSTs from a page whose response sets Referrer-Policy: no-referrer; the Fetch-metadata Sec-Fetch-Site header is the matching disambiguation signal — same-origin or none means accept, anything else stays refused)
 - **0.3.14** (2026-04-29) — Dockerfile hotfix + lint as release gate
 - **0.3.13** (2026-04-29) — CI lint scans + Wolfi container + Trivy two-step + lint cleanup
@@ -132,7 +138,7 @@ upgrading across more than a few patches at a time.
 - **0.2.25** (2026-04-28) — b.slug
 - **0.2.24** (2026-04-28) — b.retry primitive
 - **0.2.23** (2026-04-28) — test helpers consolidate
-- **0.2.22** (2026-04-28) — tier-aware input validation
+- **0.2.22** (2026-04-28) — input validation
 - **0.2.21** (2026-04-28) — defineClass.factory replaces per-module _err wrappers
 - **0.2.20** (2026-04-28) — b.requestHelpers + metrics _normalizeLabelArg
 - **0.2.19** (2026-04-28) — audit.safeEmit replaces per-module _emit wrappers
@@ -194,22 +200,22 @@ upgrading across more than a few patches at a time.
 - **0.1.78** (2026-04-27) — pqc-agent: locked-posture HTTPS agent + http-client refactor — slice 2
 - **0.1.77** (2026-04-27) — pqc-gate: TCP-level PQC enforcement on ClientHello — slice 1
 - **0.1.76** (2026-04-27) — bundler: content-hashed asset pipeline + manifest — complete
-- **0.1.75** (2026-04-27) — dev: file-watch + child-process restart engine — slice 6 ( complete)
+- **0.1.75** (2026-04-27) — dev: file-watch + child-process restart engine — slice 6 (complete)
 - **0.1.74** (2026-04-27) — cli: bin/blamejs + migrate up/down/status — slice 5
 - **0.1.73** (2026-04-27) — migrations: public up/down/status runner — slice 4
 - **0.1.72** (2026-04-27) — cookies: parse/serialize + sealed-value access gate — slice 3
 - **0.1.71** (2026-04-27) — errors-page: rich dev page + safe prod page; middleware shim — slice 2
 - **0.1.70** (2026-04-27) — log: structured JSON logging with request-id correlation — slice 1
-- **0.1.69** (2026-04-27) — scheduler: cron + interval over jobs/queue — slice 5 ( complete)
+- **0.1.69** (2026-04-27) — scheduler: cron + interval over jobs/queue — slice 5 (complete)
 - **0.1.68** (2026-04-27) — mail: generalize http transport, demote resend to thin preset
 - **0.1.67** (2026-04-27) — mail: contract + console/memory/smtp/resend transports — slice 4
 - **0.1.66** (2026-04-26) — jobs (define + enqueue + in-process worker) + createApp wiring — slices 2/3
 - **0.1.65** (2026-04-26) — createApp factory — slice 1
-- **0.1.64** (2026-04-26) — forms + csrfProtect — slice 4 ( complete)
+- **0.1.64** (2026-04-26) — forms + csrfProtect — slice 4 (complete)
 - **0.1.63** (2026-04-26) — staticServe: file serving + ETag + SRI integrity — slice 3
 - **0.1.62** (2026-04-26) — render: HTTP response helpers — slice 2
 - **0.1.61** (2026-04-26) — template engine (eval-free interpreter) — slice 1
-- **0.1.60** (2026-04-26) — auth.jwt with SLH-DSA-SHAKE-256f default — slice 5/5 ( complete)
+- **0.1.60** (2026-04-26) — auth.jwt with SLH-DSA-SHAKE-256f default — slice 5/5 (complete)
 - **0.1.59** (2026-04-26) — middleware.attachUser + middleware.requireAuth — slice 4
 - **0.1.58** (2026-04-26) — auth.passkey (WebAuthn / FIDO2) — slice 3
 - **0.1.57** (2026-04-26) — TOTP defaults match spec (HMAC-SHA512 / 128-byte secret / 8 digits / 30s) + crypto.random truncation fix
@@ -220,7 +226,7 @@ upgrading across more than a few patches at a time.
 - **0.1.52** (2026-04-26) — consent_log integrity parity with audit_log (closes the cluster spec storage move)
 - **0.1.51** (2026-04-26) — queue jobs move to external-db in cluster mode
 - **0.1.50** (2026-04-26) — sessions move to external-db in cluster mode
-- **0.1.49** (2026-04-26) — boot-time vault-key consistency check (closes cluster spec phase 4)
+- **0.1.49** (2026-04-26) — boot-time vault-key consistency check (closes cluster spec)
 - **0.1.48** (2026-04-26) — boot-time audit-tip rollback detection in cluster mode
 - **0.1.47** (2026-04-26) — fix handlers.drain unbounded loop on recursive emit (cluster-mode audit hang)
 - **0.1.46** (2026-04-26) — cluster-mode audit-tip fencing-token guard
@@ -277,7 +283,7 @@ upgrading across more than a few patches at a time.
 - **0.0.18** (2026-04-26) — strip internal-process narrative from framework comments
 - **0.0.17** (2026-04-25) — internal adoption sweep + functional scale helpers
 - **0.0.16** (2026-04-25) — atomic file I/O + safe parsers (XML, CSV)
-- **0.0.15** (2026-04-25) — HTTP middleware: request lifecycle hardening ( begin)
+- **0.0.15** (2026-04-25) — HTTP middleware: request lifecycle hardening (begin)
 - **0.0.14** (2026-04-25) — external DB (Shape B: app-data-only, bring-your-own-client)
 - **0.0.13** (2026-04-25) — log streaming + redaction + bidirectional command channel
 - **0.0.12** (2026-04-25) — queue dispatcher + local SQLite-backed protocol

package/README.md

@@ -17,7 +17,7 @@ The modern Node app is a 1,200-package supply-chain liability with no LTS calend
 
 ## Status
 
-Pre-1.0. Usable end-to-end — operators can build production apps on it today; the surface is still subject to change before 1.0. Recent line is **v0.6.3** ([releases](https://github.com/blamejs/blamejs/releases) · [npm](https://www.npmjs.com/package/@blamejs/core) · [container](https://github.com/blamejs/blamejs/pkgs/container/blamejs-wiki)).
+Pre-1.0. Usable end-to-end — operators can build production apps on it today; the surface is still subject to change before 1.0. The latest release lives on [GitHub](https://github.com/blamejs/blamejs/releases), [npm](https://www.npmjs.com/package/@blamejs/core), and the [container registry](https://github.com/blamejs/blamejs/pkgs/container/blamejs-wiki).
 
 ```js
 var b = require("@blamejs/core");
@@ -41,10 +41,10 @@ var b = require("@blamejs/core");
 
 The framework bundles the surface a typical Node app reaches for. Every primitive listed is callable today; nothing is a stub.
 
-- **Data layer** — SQLite with sealed-by-default columns (`b.db`), migrations, seeders, atomic-file writes; S3 / R2 / B2 / GCS / Azure object store with multipart upload + SSE + bucket ops (`b.storage`, `b.objectStore`); durable queue with priority + cron + flows (`b.queue`, `b.jobs`); cluster-shared cache (`b.cache`).
-- **Identity & access** — passwords (Argon2id), passkeys (WebAuthn), TOTP, JWT (PQ-default), OAuth, sessions, brute-force lockout (`b.auth.*`, `b.session`); RBAC (`b.permissions`); API keys with rotation (`b.apiKey`); break-glass column gates with second-factor + audit (`b.breakGlass`).
+- **Data layer** — SQLite with sealed-by-default columns (`b.db`), migrations, seeders, atomic-file writes; bring-your-own external Postgres / MySQL / etc. with pool tuning + role-aware connect + read-replica routing (`b.externalDb`); declarative role-narrowed views and Postgres row-level-security migrations (`b.db.declareView`, `b.db.declareRowPolicy`); S3 / R2 / B2 / GCS / Azure object store with multipart upload + SSE + bucket ops (`b.storage`, `b.objectStore`); durable queue with priority + cron + flows (`b.queue`, `b.jobs`); cluster-shared cache (`b.cache`).
+- **Identity & access** — passwords (Argon2id), passkeys (WebAuthn), TOTP, JWT (PQ-default), OAuth, sessions, brute-force lockout (`b.auth.*`, `b.session`); RBAC with optional per-role DB binding (`b.permissions`, role-spec `dbRole` field); API keys with rotation (`b.apiKey`); break-glass column gates with second-factor + audit (`b.breakGlass`).
 - **Crypto** — envelope-versioned PQC at rest (ML-KEM-1024 + P-384 hybrid, XChaCha20-Poly1305, SHAKE256), vault sealing, field-level crypto, signed webhooks (SLH-DSA-SHAKE-256f), ECIES API encryption (`b.crypto`, `b.vault`, `b.webhook`); pure-JS mTLS CA, PQC TLS gates inbound + outbound (`b.mtlsCa`, `b.pqcGate`, `b.pqcAgent`).
-- **HTTP** — router with schema-validated routes + OpenAPI publication; full middleware stack (CSRF, CORS, rate-limit, security headers, CSP nonce, body parser, compression, SSE, request log) wired by `createApp`; HTTP/1.1 + HTTP/2 outbound client with SSRF gate, redirects, multipart, interceptors, progress, encrypted cookie jar (`b.httpClient`, `b.ssrfGuard`, `b.safeUrl`).
+- **HTTP** — router with schema-validated routes + OpenAPI publication; full middleware stack (CSRF, CORS, rate-limit, security headers, CSP nonce, body parser, compression, SSE, request log, request-time DB role binding via `b.middleware.dbRoleFor`) wired by `createApp`; HTTP/1.1 + HTTP/2 outbound client with SSRF gate, redirects, multipart, interceptors, progress, encrypted cookie jar (`b.httpClient`, `b.ssrfGuard`, `b.safeUrl`).
 - **Defensive parsers** — `b.safeJson`, `b.safeBuffer`, `b.safeSql`, `b.safeSchema`, `b.parsers` (XML / TOML / YAML / .env), `b.config` (schema-validated env).
 - **Communication** — WebSockets with channel/room fan-out across cluster replicas (`b.websocket`, `b.websocketChannels`); mail with multipart + attachments + DKIM + calendar invites + bounce intake (`b.mail`, `b.mailBounce`); generic notification dispatcher with operator-supplied transports (`b.notify`).
 - **Observability** — tamper-evident audit chain with SLH-DSA-signed checkpoints, metrics, tracing (OTel pass-through when wired), PII redaction, log-stream sinks, OTLP/HTTP-JSON exporter for any OTel-compatible backend (`b.audit`, `b.metrics`, `b.tracing`, `b.redact`, `b.logStream`, `b.otelExport`).

package/lib/api-key.js

@@ -43,14 +43,14 @@
  * Same dual-storage pattern as sessions — local SQLite in single-node
  * mode, external-db in cluster mode, dispatched via cluster-storage.
  *
- * Validation tiers:
+ * Validation policy:
  *
- *   - apiKey.create opts                    → Tier A (throw)
- *   - registry.issue opts                   → Tier A (throw ApiKeyError)
- *   - registry.rotate(id) on missing/revoked → Tier A (throw)
- *   - registry.verify(token) on any failure → Tier C (return null)
- *   - registry.revoke(id) on missing        → Tier C (return false)
- *   - registry.getById(id) on missing       → Tier C (return null)
+ *   - apiKey.create opts                    → throw at config time
+ *   - registry.issue opts                   → throw ApiKeyError at call site
+ *   - registry.rotate(id) on missing/revoked → throw ApiKeyError at call site
+ *   - registry.verify(token) on any failure → return null (tolerant read)
+ *   - registry.revoke(id) on missing        → return false (tolerant read)
+ *   - registry.getById(id) on missing       → return null (tolerant read)
  */
 
 var crypto = require("./crypto");
@@ -69,7 +69,7 @@ var observability = lazyRequire(function () { return require("./observability");
 
 function _emitEvent(name, value, labels) {
   try { observability().event(name, value, labels || {}); }
-  catch (_e) { /* Tier B: hot-path observability sink */ }
+  catch (_e) { /* hot-path observability sink — drops silent on internal throws */ }
 }
 
 var _err = ApiKeyError.factory;
@@ -127,7 +127,7 @@ var DEFAULTS = Object.freeze({
   hashAlgo:         "shake256",
 });
 
-// ---- Tier-A validation helpers ----
+// ---- Config-time validation helpers (throw on bad input) ----
 
 function _isPositiveInt(n) {
   return typeof n === "number" && isFinite(n) && n >= 1 && Math.floor(n) === n;

package/lib/archive.js

@@ -216,11 +216,11 @@ function zip() {
   }
 
   function digest() {
-    // SHA-256 of the produced archive bytes — useful for operator-side
-    // integrity logging on exported bundles. Not vendor-locked to any
-    // particular hash; SHA-256 is universally recognized for content
-    // addressing.
-    return nodeCrypto.createHash("sha256").update(toBuffer()).digest("hex");
+    // SHA3-512 of the produced archive bytes — useful for operator-side
+    // integrity logging on exported bundles. Matches the framework's
+    // PQC-first hash posture; operators reconciling against an external
+    // SHA-256 can hash the bytes themselves.
+    return nodeCrypto.createHash("sha3-512").update(toBuffer()).digest("hex");
   }
 
   return {

package/lib/audit.js

@@ -203,6 +203,8 @@ var FRAMEWORK_NAMESPACES = [
   "backup",     // b.backup
   "breakglass", // b.breakGlass — column-policy / row-enforcement step-up auth (audit namespace lowercased per the validator's `namespace.verb` rule, same convention as b.apiKey → apikey.*)
   "cache",      // b.cache
+  "db",         // b.db / b.middleware.dbRoleFor / b.externalDb.runAs
+                //   (role-switching, RLS-shaped events)
   "dkim",       // b.mail.dkim (DKIM-Signature generation events)
   "mail",       // b.mail (b.mail-bounce uses "system.mail.*")
   "notify",     // b.notify
@@ -709,8 +711,8 @@ function emit(event) {
 // audit outage doesn't crash the request handler. This is that helper,
 // hoisted out so each module can stop redefining it.
 //
-// Tier B (drop-silent): malformed input is dropped without throwing, by
-// design. safeEmit is called from request hot paths where throwing on a
+// Drop-silent on malformed input by design. safeEmit is called from
+// request hot paths where throwing on a
 // missing `action` would mean a malformed audit attempt crashes the
 // request that triggered it — strictly worse than the missing audit
 // row. Operators who need a hard guarantee the event landed should call

package/lib/auth/jwt.js

@@ -247,10 +247,10 @@ async function verify(token, opts) {
     if (typeof opts.clockToleranceSec !== "number" ||
         !isFinite(opts.clockToleranceSec) ||
         opts.clockToleranceSec < 0) {
-      // Tier-A: a negative tolerance over-tightens the window (legit
-      // tokens get rejected as expired or not-yet-valid). A non-finite
-      // value would NaN-poison the comparison. Catch both at config
-      // time rather than producing surprise rejections in production.
+      // Throw at config time: a negative tolerance over-tightens the
+      // window (legit tokens get rejected as expired or not-yet-valid)
+      // and a non-finite value would NaN-poison the comparison. Catch
+      // both here rather than producing surprise rejections in production.
       throw new AuthError("auth-jwt/bad-clock-tolerance",
         "verify: clockToleranceSec must be a non-negative finite number, got " +
         JSON.stringify(opts.clockToleranceSec));

package/lib/break-glass.js

@@ -17,10 +17,10 @@
  *
  * Spec: memory/specs/blamejs-break-glass-spec.md
  *
- * v0.5.0 ships Model A (policy gate) + TOTP factor + Tier-A validation +
- * 14 error codes + audit chain integration. Model B (cryptographic
- * gate via per-row K_row), passkey factor, service-account bypass,
- * and admin tools land in v0.5.1 / v0.5.2 per the phasing plan.
+ * Ships Model A (policy gate) + TOTP factor + config-time input
+ * validation + 14 error codes + audit chain integration. Model B
+ * (cryptographic gate via per-row K_row), passkey factor, service-
+ * account bypass, and admin tools land in subsequent patches.
  *
  * Public API:
  *
@@ -59,8 +59,9 @@ var lockout = lazyRequire(function () { return require("./auth/lockout"); });
 var passkey = lazyRequire(function () { return require("./auth/passkey"); });
 
 // Errors — all 14 codes documented in the spec. `permanent: true`
-// means caller's input is bad (Tier-A); `permanent: false` means
-// transient (factor failed, rate-limited) — caller may retry.
+// means caller's input is bad (config-time / call-site reject);
+// `permanent: false` means transient (factor failed, rate-limited)
+// — caller may retry.
 var BreakGlassError = defineClass("BreakGlassError", { alwaysPermanent: false });
 
 // ---- Defaults (matched to operator-locked decisions) ----

package/lib/cache.js

@@ -51,14 +51,14 @@
  *   { get, set, del, clear, size, close } — operator-supplied custom
  *     backend (Redis, Memcached, …). All methods async.
  *
- * Validation tiers:
+ * Validation policy:
  *
- *   - create() opts                       → Tier A (throw at boot)
- *   - get/set/del/has/wrap key arg type   → Tier A (throw — programming bug)
- *   - set value type                      → C (operator decides what to store)
- *   - per-call ttlMs override             → Tier A (throw — bad ttl is silent footgun)
- *   - audit / observability emit failures → Tier B (drop silent)
- *   - method called after close()         → Tier A (throw BAD_STATE)
+ *   - 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
  *
  * Security defaults:
  *
@@ -114,7 +114,7 @@ var DEFAULTS = Object.freeze({
   auditClear:              true,
 });
 
-// ---- Tier-A validation helpers ----
+// ---- Config-time validation helpers (throw on bad input) ----
 
 function _isFiniteNonNegative(n) {
   return typeof n === "number" && isFinite(n) && n >= 0;
@@ -669,7 +669,7 @@ function create(opts) {
     try {
       if (operatorObs) operatorObs.event(name, 1, labels || {});
       else observability().event(name, 1, labels || {});
-    } catch (_e) { /* Tier B: hot-path observability sink */ }
+    } catch (_e) { /* hot-path observability sink — drops silent on internal throws */ }
   }
 
   function emitAudit(action, info) {

package/lib/constants.js

@@ -18,10 +18,10 @@ var pkg = require("../package.json");
 // reader sees the unit at the call site (`C.TIME.minutes(45)` instead of
 // adding a new FORTY_FIVE_MIN constant). All return integer milliseconds.
 //
-// Tier A validation: these are config-time helpers. Throw on non-finite
-// or negative input so a typo (`C.TIME.minutes(opts.x)` where opts.x is
-// undefined) surfaces at boot instead of silently becoming `NaN` or `0`
-// and shipping a 0ms timeout into production.
+// Throw on non-finite or negative input — these are config-time helpers,
+// so a typo (`C.TIME.minutes(opts.x)` where opts.x is undefined) should
+// surface at boot instead of silently becoming `NaN` or `0` and shipping
+// a 0ms timeout into production.
 function _validateDuration(unit, n) {
   if (typeof n !== "number" || !isFinite(n) || n < 0) {
     throw new TypeError("C.TIME." + unit + ": expected non-negative finite number, got " +
@@ -42,8 +42,8 @@ var TIME = Object.freeze({
 // (KiB/MiB/GiB), since every existing byte literal in the framework
 // already uses 1024 multiplication.
 //
-// Tier A validation: same rationale as TIME — bad input surfaces at the
-// call site, not as a silent NaN cap that disables size limits.
+// Throw on bad input — same rationale as TIME: bad input surfaces at
+// the call site, not as a silent NaN cap that disables size limits.
 function _validateBytes(unit, n) {
   if (typeof n !== "number" || !isFinite(n) || n < 0) {
     throw new TypeError("C.BYTES." + unit + ": expected non-negative finite number, got " +

package/lib/credential-hash.js

@@ -61,13 +61,13 @@
  *   - Transparent rehash via needsRehash() drains old algos at the
  *     pace of organic verify traffic.
  *
- * Validation tiers:
+ * Validation policy:
  *
- *   - hash() opts (algo, params)         → Tier A (throw)
- *   - hash() secret type / length        → Tier A (throw)
- *   - verify() envelope shape unparsable → Tier C (return false)
- *   - verify() unknown algo ID           → Tier C (return false)
- *   - inspect() bad envelope             → Tier C (return null)
+ *   - hash() opts (algo, params)         → throw at call site
+ *   - hash() secret type / length        → throw at call site
+ *   - verify() envelope shape unparsable → return false (tolerant read)
+ *   - verify() unknown algo ID           → return false (tolerant read)
+ *   - inspect() bad envelope             → return null (tolerant read)
  */
 
 var crypto = require("./crypto");
@@ -79,7 +79,7 @@ var observability = lazyRequire(function () { return require("./observability");
 
 function _emitEvent(name, value, labels) {
   try { observability().event(name, value, labels || {}); }
-  catch (_e) { /* Tier B: hot-path observability sink */ }
+  catch (_e) { /* hot-path observability sink — drops silent on internal throws */ }
 }
 
 // Default SHAKE256 output size for newly-issued credentials. 128
@@ -135,7 +135,7 @@ var ID_TO_NAME = Object.freeze({
   0x02: "argon2id",
 });
 
-// ---- Tier-A validation ----
+// ---- Call-site validation (throw on bad input) ----
 
 function _validateSecret(secret) {
   if (typeof secret !== "string" && !Buffer.isBuffer(secret)) {
@@ -223,7 +223,7 @@ async function hash(secret, opts) {
 }
 
 async function verify(secret, envelope) {
-  // Tier C: any malformed input → false. Lets operators write
+  // Tolerant read: any malformed envelope → false. Lets operators write
   //   if (!await ch.verify(s, row.hash)) return res.status(401);
   // without try/catch ceremony. We still reject obvious caller bugs
   // (non-string-or-Buffer secret) loudly because that signals broken

package/lib/db-declare-view.js

@@ -39,7 +39,7 @@
  * typos surface as clear errors at the migrate command, not as silent
  * empty views or grant-to-nonexistent-role footguns.
  *
- * Tier-A validation at declareView() call time:
+ * Throw at declareView() call time on:
  *   - schema, name, source segments → safeSql.validateIdentifier
  *   - column names in redactColumns / sealedColumns / hashColumns →
  *     safeSql.validateIdentifier
@@ -303,7 +303,7 @@ function declareView(opts) {
   var qSource = safeSql.quoteQualified([spec.source.schema, spec.source.name], "postgres");
 
   async function up(xdb, ctx) {
-    // Tier-A boundary: confirm we're on Postgres before any DDL leaves the process.
+    // Boundary throw: confirm we're on Postgres before any DDL leaves the process.
     if (ctx && ctx.externalDb && ctx.backendName) {
       _ensureBackendIsPostgres(ctx.externalDb, ctx.backendName);
     }

package/lib/external-db-migrate.js

@@ -208,7 +208,7 @@ function _emit(audit, action, outcome, info, reason) {
       metadata: info || {},
       reason:   reason || null,
     });
-  } catch (_e) { /* Tier B: drop-silent */ }
+  } catch (_e) { /* drop-silent — audit emit failure must not crash the migration */ }
 }
 
 // ---- Backend resolution ----

package/lib/external-db.js

@@ -58,8 +58,14 @@ var safeAsync = require("./safe-async");
 var safeSql = require("./safe-sql");
 var { ExternalDbError } = require("./framework-error");
 
-var audit = lazyRequire(function () { return require("./audit"); });
-var db    = lazyRequire(function () { return require("./db"); });
+var audit         = lazyRequire(function () { return require("./audit"); });
+var db            = lazyRequire(function () { return require("./db"); });
+var observability = lazyRequire(function () { return require("./observability"); });
+
+function _emitMetric(name, value, labels) {
+  try { observability().event(name, value, labels || {}); }
+  catch (_e) { /* hot-path observability sink — drop silent by design */ }
+}
 
 var _err = ExternalDbError.factory;
 
@@ -104,13 +110,21 @@ class Pool {
         throw e;
       }
     }
-    // At max — wait for a release
-    return new Promise((function (self) {
-      return function (resolve, reject) {
-        var entry = { resolve: resolve, reject: reject };
-        self.waiters.push(entry);
-      };
-    })(this));
+    // At max — wait for a release. The waiter's clock starts now;
+    // when release() resolves the waiter we emit the wait duration so
+    // operators can see backpressure on the pool.
+    var self = this;
+    var waitStartedAt = Date.now();
+    return new Promise(function (resolve, reject) {
+      self.waiters.push({
+        resolve: function (client) {
+          _emitMetric("externaldb.pool.acquire_wait", Date.now() - waitStartedAt,
+            { backend: self.name });
+          resolve(client);
+        },
+        reject:  reject,
+      });
+    });
   }
 
   release(client) {
@@ -318,6 +332,7 @@ async function query(sql, params, opts) {
   _requireInit();
   opts = opts || {};
   var b = _pickBackend(opts);
+  var role = dbRoleContext.getRole();
 
   var t0 = Date.now();
   try {
@@ -344,9 +359,11 @@ async function query(sql, params, opts) {
       });
     }, b.retryConfig);
 
+    var durationMs = Date.now() - t0;
     _emit("system.externaldb.query", "success", {
       backend:        b.name,
-      durationMs:     Date.now() - t0,
+      role:           role,
+      durationMs:     durationMs,
       classification: opts.classification || null,
       rowCount:       result && result.rowCount,
       // SQL is NOT logged by default — may contain sensitive literal values
@@ -355,14 +372,33 @@ async function query(sql, params, opts) {
       // field-crypto on the audit row).
       sql:            opts.includeSqlInAudit ? sql : null,
     });
+    _emitMetric("externaldb.query.success", 1,
+      { backend: b.name, role: role || "(none)" });
+    _emitMetric("externaldb.query.duration_ms", durationMs,
+      { backend: b.name, role: role || "(none)" });
     return result;
   } catch (e) {
+    var failureMs = Date.now() - t0;
     _emit("system.externaldb.query", "failure", {
       backend:        b.name,
-      durationMs:     Date.now() - t0,
+      role:           role,
+      durationMs:     failureMs,
       classification: opts.classification || null,
       errorCode:      e.code || null,
     }, (e && e.message) || String(e));
+    _emitMetric("externaldb.query.failure", 1,
+      { backend: b.name, role: role || "(none)", errorCode: e.code || "(none)" });
+    // Postgres signals authorization-denied as SQLSTATE 42501
+    // (insufficient_privilege). RLS-shaped writes that violate a
+    // policy and GRANT-denied SELECTs both surface this code. The
+    // operator's role-views recipe relies on this signal: a row of
+    // db.role.denied means a request-time role attempted something its
+    // grant or RLS policy forbids — the highest-signal compliance event
+    // the externalDb layer can emit.
+    if (e && e.code === "42501") {
+      _emitMetric("db.role.denied", 1,
+        { backend: b.name, role: role || "(none)" });
+    }
     throw e;
   }
 }
@@ -372,6 +408,7 @@ async function transaction(fn, opts) {
   if (typeof fn !== "function") throw _err("INVALID_FN", "transaction requires a function", true);
   opts = opts || {};
   var b = _pickBackend(opts);
+  var role = dbRoleContext.getRole();
 
   // sessionGucs — per-transaction `SET LOCAL "name" = value` plumbing.
   // Each name validates as a SQL identifier (Postgres GUC names follow
@@ -398,16 +435,30 @@ async function transaction(fn, opts) {
       var result = await fn(txClient);
       await b.commit(client);
       committed = true;
+      var durationMs = Date.now() - t0;
       _emit("system.externaldb.transaction", "success", {
-        backend: b.name, durationMs: Date.now() - t0, classification: opts.classification || null,
+        backend: b.name, role: role, durationMs: durationMs,
+        classification: opts.classification || null,
       });
+      _emitMetric("externaldb.transaction.success", 1,
+        { backend: b.name, role: role || "(none)" });
+      _emitMetric("externaldb.transaction.duration_ms", durationMs,
+        { backend: b.name, role: role || "(none)" });
       return result;
     } catch (e) {
       try { if (!committed) await b.rollback(client); } catch (_e) { /* best effort */ }
+      var failureMs = Date.now() - t0;
       _emit("system.externaldb.transaction", "failure", {
-        backend: b.name, durationMs: Date.now() - t0, classification: opts.classification || null,
+        backend: b.name, role: role, durationMs: failureMs,
+        classification: opts.classification || null,
         errorCode: e.code || null,
       }, (e && e.message) || String(e));
+      _emitMetric("externaldb.transaction.failure", 1,
+        { backend: b.name, role: role || "(none)", errorCode: e.code || "(none)" });
+      if (e && e.code === "42501") {
+        _emitMetric("db.role.denied", 1,
+          { backend: b.name, role: role || "(none)" });
+      }
       throw e;
     } finally {
       b.pool.release(client);
@@ -651,6 +702,7 @@ async function _readQuery(sql, params, opts) {
     throw _err("ALL_REPLICAS_UNHEALTHY",
       "backend '" + b.name + "': all replicas unhealthy and fallback disabled", true);
   }
+  var role = dbRoleContext.getRole();
   var t0 = Date.now();
   try {
     var client = await replica.pool.acquire();
@@ -658,12 +710,18 @@ async function _readQuery(sql, params, opts) {
       var res = await replica.query(client, sql, params || []);
       replica.pool.release(client);
       replica.consecutiveFailures = 0;
+      var durationMs = Date.now() - t0;
       _emit("system.externaldb.read", "success", {
         backend:    b.name,
+        role:       role,
         replicaIdx: replica.index,
-        durationMs: Date.now() - t0,
+        durationMs: durationMs,
         rowCount:   res && res.rowCount,
       });
+      _emitMetric("externaldb.read.success", 1,
+        { backend: b.name, role: role || "(none)", replicaIdx: replica.index });
+      _emitMetric("externaldb.read.duration_ms", durationMs,
+        { backend: b.name, role: role || "(none)", replicaIdx: replica.index });
       return res;
     } catch (e) {
       // Connection-shape errors mark unhealthy + destroy.
@@ -681,10 +739,17 @@ async function _readQuery(sql, params, opts) {
   } catch (e) {
     _emit("system.externaldb.read", "failure", {
       backend:    b.name,
+      role:       role,
       replicaIdx: replica.index,
       durationMs: Date.now() - t0,
       errorCode:  e.code || null,
     }, (e && e.message) || String(e));
+    _emitMetric("externaldb.read.failure", 1,
+      { backend: b.name, role: role || "(none)", errorCode: e.code || "(none)" });
+    if (e && e.code === "42501") {
+      _emitMetric("db.role.denied", 1,
+        { backend: b.name, role: role || "(none)" });
+    }
     // Fallback to primary on a failed replica read when allowed.
     if (b.replicaFallbackToPrimary) {
       return query(sql, params, opts);
@@ -936,6 +1001,27 @@ function runAs(role, fn) {
     }
     safeSql.validateIdentifier(role, { allowReserved: false });
   }
+  // Audit the role transition. runAs has no req, so the actor 5 W's
+  // come from whatever the caller has bound on the audit-context ALS
+  // (log.js requestId, plus any request-bound actor that was set in
+  // an outer scope). Same audit shape as the dbRoleFor middleware
+  // path — forensic walkers can reconstruct the role timeline whether
+  // the binding came from request middleware or a job runner.
+  var previousRole = dbRoleContext.getRole();
+  var newRole = role || null;
+  if (previousRole !== newRole) {
+    audit().safeEmit({
+      action:   "db.role.switched",
+      actor:    {},
+      resource: { kind: "db.role", id: newRole || "(none)" },
+      outcome:  "success",
+      metadata: {
+        previousRole: previousRole,
+        newRole:      newRole,
+        source:       "runAs",
+      },
+    });
+  }
   return dbRoleContext.runWithRole(role || null, fn);
 }
 

package/lib/http-client.js

@@ -480,8 +480,8 @@ function request(opts) {
     return Promise.reject(_makeError(opts && opts.errorClass, "BAD_ARG", "url is required", true));
   }
 
-  // Validate before/after shapes early — Tier-A throw if the operator
-  // passed something un-callable so the bug surfaces at the call site
+  // Validate before/after shapes early — throw at call site if the
+  // operator passed something un-callable so the bug surfaces here
   // rather than inside the request loop.
   if (opts.before !== undefined) {
     if (!Array.isArray(opts.before) || !opts.before.every(function (f) { return typeof f === "function"; })) {
@@ -896,7 +896,7 @@ function _requestH1(transport, u, opts) {
       var bodyBuf = Buffer.isBuffer(opts.body) ? opts.body : Buffer.from(opts.body, "utf8");
       if (onUploadProgress) {
         // Chunked write so progress reports land before req.end().
-        var CHUNK = 64 * 1024;
+        var CHUNK = C.BYTES.kib(64);
         var off = 0;
         while (off < bodyBuf.length) {
           var slice = bodyBuf.slice(off, Math.min(off + CHUNK, bodyBuf.length));