@blamejs/core 0.8.42 → 0.8.49

package/lib/forms.js

@@ -1,39 +1,36 @@
 "use strict";
 /**
- * Forms — CSRF tokens, HTML rendering, server-side validation.
+ * @module b.forms
+ * @nav    HTTP
+ * @title  Forms
  *
- * Three concerns the framework owns at the form layer:
+ * @intro
+ *   HTML form rendering with CSRF token injection, accessible labels,
+ *   field-type dispatch, and shared-spec server-side validation.
  *
- *   1. CSRF tokens. Generation is a 32-byte random hex string;
- *      verification is constant-time. The middleware in
- *      lib/middleware/csrf-protect.js does the actual gating —
- *      this module provides the primitives the operator (or
- *      template) calls to issue a token and embed it.
+ *   `b.forms.render(spec)` emits a complete `<form>` element with
+ *   auto-escaped attributes, a hidden CSRF input, and per-field
+ *   markup for text / email / password / number / checkbox / radio /
+ *   textarea / select / hidden / submit. Every attribute value is
+ *   forced through `escapeAttribute` so a hostile field name or value
+ *   can't break out of the double-quoted attribute context.
  *
- *   2. Form HTML rendering. forms.render({ action, fields, csrfToken })
- *      produces a complete <form> element with auto-escaped attributes,
- *      a hidden CSRF input, and field-type dispatch (text / email /
- *      password / number / checkbox / radio / textarea / select /
- *      hidden / submit). All values pass through escapeAttribute so
- *      the form can't be hijacked by user-supplied attribute payloads.
+ *   `b.forms.validate(spec, body)` walks the same field spec the
+ *   renderer accepts and returns `{ valid, errors, values }` —
+ *   coerced types, required-field checks, length bounds, regex
+ *   pattern, enum membership. Sharing the spec is the point: the
+ *   operator's "this is what the form looks like" and "this is what
+ *   the form expects" stay in lock-step, eliminating the drift class
+ *   where a field gets added to the renderer but not the validator.
  *
- *   3. Server-side validation. forms.validate(spec, body) walks the
- *      same field spec the renderer accepts and returns
- *      { valid, errors, values } — coerced types, required-field
- *      checks, length bounds, regex pattern, enum membership.
+ *   CSRF tokens are 32-byte hex strings from
+ *   `b.crypto.generateToken`; `verifyCsrfToken` is constant-time.
+ *   The middleware in `b.middleware.csrfProtect` does the actual
+ *   request-time gating — this module supplies the issue / verify
+ *   primitives.
  *
- * The renderer + validator share their field spec on purpose: an
- * operator's "this is what the form looks like" is also "this is
- * what the form expects." A change to the spec adjusts both.
- *
- * Public API:
- *
- *   forms.generateCsrfToken()          → "<64 hex chars>"
- *   forms.verifyCsrfToken(submitted, expected) → boolean (timing-safe)
- *   forms.render(spec)                 → string (complete <form>…</form>)
- *   forms.validate(spec, body)         → { valid, errors, values }
- *   forms.escapeAttribute(value)       → string (double-quoted-attr context)
- *   forms.escapeHtml = template.escapeHtml (re-export for convenience)
+ * @card
+ *   HTML form rendering with CSRF token injection, accessible labels, field-type dispatch, and shared-spec server-side validation.
  */
 var C = require("./constants");
 var { generateToken, timingSafeEqual } = require("./crypto");
@@ -55,10 +52,44 @@ var MAX_EMAIL_LENGTH = 254;
 // (and what most servers / proxies enforce) is 8 KiB.
 var MAX_URL_LENGTH   = C.BYTES.kib(8);
 
+/**
+ * @primitive b.forms.generateCsrfToken
+ * @signature b.forms.generateCsrfToken()
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.forms.verifyCsrfToken, b.middleware.csrfProtect
+ *
+ * Returns a 32-byte (64 hex char) random token suitable for embedding
+ * in a hidden form field. Entropy comes from `b.crypto.generateToken`,
+ * which routes through Node's `crypto.randomBytes`. The token is
+ * opaque to the framework — operators store it in the session and
+ * compare via `verifyCsrfToken` on submit.
+ *
+ * @example
+ *   var token = b.forms.generateCsrfToken();
+ *   // → "8f3a1c4b...e7d9"   (64 hex chars)
+ */
 function generateCsrfToken() {
   return generateToken(CSRF_TOKEN_BYTES);
 }
 
+/**
+ * @primitive b.forms.verifyCsrfToken
+ * @signature b.forms.verifyCsrfToken(submitted, expected)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.forms.generateCsrfToken, b.middleware.csrfProtect
+ *
+ * Constant-time comparison of a submitted token against the expected
+ * value. Returns `false` for any non-string input, mismatched length,
+ * or empty submitted token — never throws. Routes through
+ * `b.crypto.timingSafeEqual` so an attacker can't probe character
+ * positions via response-time differences.
+ *
+ * @example
+ *   var ok = b.forms.verifyCsrfToken(req.body.csrf, req.session.csrf);
+ *   // → true  (when both strings are non-empty and byte-identical)
+ */
 function verifyCsrfToken(submitted, expected) {
   if (typeof submitted !== "string" || typeof expected !== "string") return false;
   if (submitted.length === 0 || submitted.length !== expected.length) return false;
@@ -82,6 +113,25 @@ var ATTR_ESCAPE_MAP = {
 };
 var ATTR_ESCAPE_RE = /[&<>"'`=]/g;
 
+/**
+ * @primitive b.forms.escapeAttribute
+ * @signature b.forms.escapeAttribute(value)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.forms.render, b.template.escapeHtml
+ *
+ * Escapes a value for safe interpolation into a double-quoted HTML
+ * attribute context. Stricter than `b.template.escapeHtml`: also
+ * escapes backtick (some browsers parse `` ` `` as an attribute
+ * delimiter under quirks mode) and `=` (defense-in-depth for any
+ * unquoted-attribute slips). `null` / `undefined` become the empty
+ * string. Used internally by `b.forms.render` for every attribute
+ * value; exported for operators rendering their own form fragments.
+ *
+ * @example
+ *   var safe = b.forms.escapeAttribute('a"b<c>d');
+ *   // → "a&quot;b&lt;c&gt;d"
+ */
 function escapeAttribute(value) {
   if (value === null || value === undefined) return "";
   var s = typeof value === "string" ? value : String(value);
@@ -214,6 +264,34 @@ function _renderField(field) {
   return control;
 }
 
+/**
+ * @primitive b.forms.render
+ * @signature b.forms.render(spec)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.forms.validate, b.forms.generateCsrfToken, b.template.escapeHtml
+ *
+ * Renders a complete `<form>` element from a typed spec — method,
+ * action, fields, optional CSRF token. Each field's `type` selects
+ * the input widget (text / email / password / number / checkbox /
+ * radio / textarea / select / hidden / submit). All attribute values
+ * pass through `escapeAttribute`; `spec.csrfToken` (if present) is
+ * embedded as a hidden `_csrf` input. Throws when `spec.action` is
+ * missing / empty or `spec.fields` isn't an array.
+ *
+ * @example
+ *   var html = b.forms.render({
+ *     action:    "/login",
+ *     method:    "POST",
+ *     csrfToken: "8f3a1c4b...e7d9",
+ *     fields: [
+ *       { type: "email",    name: "email",    label: "Email",    required: true },
+ *       { type: "password", name: "password", label: "Password", required: true },
+ *       { type: "submit",   name: "submit",   value: "Sign in" },
+ *     ],
+ *   });
+ *   // → "<form method=\"POST\" action=\"/login\">...<input type=\"hidden\" name=\"_csrf\" .../></form>"
+ */
 function render(spec) {
   if (!spec || typeof spec.action !== "string" || spec.action.length === 0) {
     throw new Error("forms.render: spec.action is required");
@@ -296,6 +374,31 @@ function _isEmpty(v) {
   return v === undefined || v === null || v === "";
 }
 
+/**
+ * @primitive b.forms.validate
+ * @signature b.forms.validate(spec, body)
+ * @since     0.1.0
+ * @status    stable
+ * @related   b.forms.render, b.safeSchema
+ *
+ * Walks the same spec the renderer accepts and validates a submitted
+ * body. Per field: required-field check, type coercion (string /
+ * number / boolean / email / url), `minLength` / `maxLength` bounds,
+ * regex `pattern`, `enum` membership. Returns
+ * `{ valid: boolean, errors: { field: msg, ... }, values: { ... } }`.
+ * The `values` object holds coerced values keyed by field name —
+ * route handlers consume `result.values` directly without re-parsing.
+ *
+ * @example
+ *   var result = b.forms.validate(
+ *     { fields: [
+ *         { type: "email",  name: "email", required: true },
+ *         { type: "number", name: "age",   minLength: 1 },
+ *     ] },
+ *     { email: "ada@example.com", age: "37" }
+ *   );
+ *   // → { valid: true, errors: {}, values: { email: "ada@example.com", age: 37 } }
+ */
 function validate(spec, body) {
   if (!spec || !Array.isArray(spec.fields)) {
     throw new Error("forms.validate: spec.fields must be an array");

package/lib/framework-error.js

@@ -407,6 +407,152 @@ var A2aError              = defineClass("A2aError",              { alwaysPermane
 // missing or malformed router-token, replay (nonce already seen),
 // unauthorized SDL probe. Permanent.
 var GraphqlFederationError = defineClass("GraphqlFederationError", { alwaysPermanent: true });
+// Fda21Cfr11Error covers FDA 21 CFR Part 11 §11.10(e) audit-content
+// shape + §11.50/§11.70 electronic-signature shape violations: missing
+// printedName / dateTimeUtc / signatureMeaning / predicateRule / signed
+// record bind, before/after pair missing on a GxP audit row, signature-
+// algorithm allowlist drift, posture interceptor refusal. Permanent —
+// every case is operator-supplied data shape, not transient.
+var Fda21Cfr11Error       = defineClass("Fda21Cfr11Error",       { alwaysPermanent: true });
+// AuditDailyReviewError covers PCI DSS 4.0 Req 10.4.1.1 daily-review
+// misconfiguration: bad cron / lookback / severity threshold, missing
+// notify callback under threshold-bearing posture, audit-source not
+// queryable. Permanent — config-time errors.
+var AuditDailyReviewError = defineClass("AuditDailyReviewError", { alwaysPermanent: true });
+// AuditSegregationError covers SOX §404 / SOC 2 CC1.3 actor-binding
+// violations: bound-actor mismatch on emit, missing db-role context,
+// trigger-installation failure when sox-404 / soc2 posture demands it.
+// Permanent — operator-misconfig or in-flight identity mismatch.
+var AuditSegregationError = defineClass("AuditSegregationError", { alwaysPermanent: true });
+// DdlChangeControlError covers SOX §404 / PCI-DSS DDL change-control
+// violations: insufficient approvers, approval window violation,
+// signature-mismatch on apply, duplicate approval, application of an
+// already-applied or rejected change. Permanent.
+var DdlChangeControlError = defineClass("DdlChangeControlError", { alwaysPermanent: true });
+// LegalHoldError covers subject-level legal-hold registry violations:
+// missing subjectId, malformed reason/citation, duplicate placement,
+// release-without-placement, bad opts. Permanent — config / API
+// shape errors, not transient.
+var LegalHoldError        = defineClass("LegalHoldError",        { alwaysPermanent: true });
+// WormViolationError covers operator-declared WORM (write-once-read-
+// many) trigger-installation failures and posture-asserted boot
+// gates: declareWorm called on a non-existent table, table requires
+// WORM under sec-17a-4 / finra-4511 / fda-21cfr11 but none declared,
+// operator attempted to drop the WORM trigger outside a sanctioned
+// retention.purge flow. Permanent.
+var WormViolationError    = defineClass("WormViolationError",    { alwaysPermanent: true });
+// SandboxError covers operator-supplied transform-source isolation
+// failures: bad opts at create() (non-string source, non-finite
+// timeoutMs / maxBytes, allowed-list contains a non-allowlisted
+// global), worker-thread spawn failure, timeout exceeded, peak-bytes
+// overrun, non-allowlisted-global access, output-shape-too-large,
+// runtime exceptions inside the transform. Permanent — every case is
+// either operator-misconfig or a transform that the host should
+// refuse rather than retry. Operator decides at the call site whether
+// to surface the refusal as a 4xx or to fall back to a default value.
+var SandboxError          = defineClass("SandboxError",          { alwaysPermanent: true });
+// DlpError — outbound DLP scanner refusal raised by
+// b.redact.installOutboundDlp's interceptors when the classifier verdict
+// is "refuse". Permanent; the request body must be operator-corrected
+// before re-attempt rather than retried as-is.
+var DlpError              = defineClass("DlpError",              { alwaysPermanent: true });
+// AuthBotChallengeError — challenge / escalation refusal raised by
+// b.authBotChallenge when the operator-supplied challengeFn is
+// missing, returns a non-boolean verdict, or throws. Permanent.
+var AuthBotChallengeError = defineClass("AuthBotChallengeError", { alwaysPermanent: true });
+// SessionDeviceBindingError — fingerprint-drift refusal raised by
+// b.sessionDeviceBinding when create-time opts are malformed or the
+// boundKeyResolver returns a non-Buffer. Permanent.
+var SessionDeviceBindingError = defineClass("SessionDeviceBindingError", { alwaysPermanent: true });
+// AcmeError — RFC 8555 ACME + RFC 9773 ACME Renewal Information
+// (ARI) protocol violations raised by b.acme: bad opts at create
+// (non-https directory URL, missing accountKey, malformed audit hook),
+// directory-fetch failure shape, newOrder/finalize/retrieveCert
+// HTTP-status / response-shape errors, ARI window parse failures,
+// retrieveCert returning non-PEM bytes, renewIfDue called before
+// retrieveCert / before ARI URL is reachable. Permanent — every case
+// is operator-misconfig or a CA-side response shape the framework
+// refuses to coerce. withStatusCode so HTTP-shaped failures from the
+// CA surface as a typed status for retry classification.
+var AcmeError             = defineClass("AcmeError",             { withStatusCode: true });
+
+// HpkeError — RFC 9180 Hybrid Public-Key Encryption (lib/crypto-hpke.js).
+// Bad opts at the call site, KEM encap/decap failures, AEAD tag failures.
+var HpkeError             = defineClass("HpkeError",             { alwaysPermanent: true });
+// TlsExporterError — RFC 9266 TLS-Exporter channel binding
+// (lib/tls-exporter.js). Non-TLS sockets, TLS<1.3 sessions, short
+// exporter outputs.
+var TlsExporterError      = defineClass("TlsExporterError",      { alwaysPermanent: true });
+// HttpSigError — RFC 9421 HTTP Message Signatures (lib/http-message-
+// signature.js). Bad opts, missing covered components, unsupported alg.
+var HttpSigError          = defineClass("HttpSigError",          { alwaysPermanent: true });
+// HttpClientError — outbound httpClient streaming primitives
+// (b.httpClient.downloadStream / b.httpClient.uploadMultipartStream).
+// withStatusCode so HTTP-shaped failures (404, 500, 503) carry the
+// upstream status for retry classification. Codes follow the
+// "httpclient/<reason>" shape: hash-mismatch, dest-not-writable,
+// missing-file, http-error, etc.
+var HttpClientError       = defineClass("HttpClientError",       { withStatusCode: true });
+// KeychainError — b.keychain (lib/keychain.js). Bad opts at config time,
+// native-tool exec failure (security / secret-tool / PowerShell
+// CredentialManager), file-fallback unseal / shape failure, oversized
+// native-tool output. alwaysPermanent — every case is operator-misconfig
+// or a host-environment condition the framework refuses to coerce.
+var KeychainError         = defineClass("KeychainError",         { alwaysPermanent: true });
+// WatcherError — b.watcher recursive-fs.watch wrapper (lib/watcher.js).
+// Bad opts at create (non-string root, missing root, bad ignore pattern,
+// non-finite debounceMs, non-function hook), recursive-watch unsupported
+// on the host platform/kernel, fs.watch start failure, pending-event
+// queue overflow under runaway-directory pressure. alwaysPermanent —
+// every case is config-misuse or a host-environment refusal the
+// framework will not coerce.
+var WatcherError          = defineClass("WatcherError",          { alwaysPermanent: true });
+// LocalDbThinError — b.localDb.thin lightweight node:sqlite wrapper
+// (lib/local-db-thin.js). Bad opts at create, node:sqlite unavailable
+// on the host Node build, integrity_check failure under recovery:
+// "refuse", recovery-rename I/O failure, post-close handle reuse, bad
+// SQL passed to prepare/run/query. alwaysPermanent — every case is
+// caller-shape misuse or an irrecoverable on-disk condition.
+var LocalDbThinError      = defineClass("LocalDbThinError",      { alwaysPermanent: true });
+// RouterError covers operator-shape violations on the router primitive:
+// invalid `allowedRedirectOrigins` opt at create time, and cross-origin
+// `res.redirect()` targets that are not on the allowlist. alwaysPermanent
+// — every case is config-time programming bug or an outbound-redirect
+// shape error that retry will not recover.
+var RouterError           = defineClass("RouterError",           { alwaysPermanent: true });
+// WorkerPoolError — b.workerPool (lib/worker-pool.js). Bad opts at
+// config (size / maxQueueDepth / taskTimeoutMs out of range, non-
+// absolute scriptPath, non-function onExit), runtime queue-full,
+// per-task timeout, worker spawn / error / non-zero exit, malformed
+// reply envelope, terminate-aborted tasks. alwaysPermanent — every
+// case is operator-misconfig or worker-script bug; retry without a
+// fix would just repeat the failure.
+var WorkerPoolError       = defineClass("WorkerPoolError",       { alwaysPermanent: true });
+// ArgParserError — b.argParser declarative CLI argument parser
+// (lib/arg-parser.js). Bad opts at create time (unsupported flag type,
+// duplicate flag/alias, malformed flag/command name, prototype-polluting
+// name like __proto__/constructor/prototype), bad parse-time argv (not
+// an array, non-string elements, unknown flag/command, missing required
+// flag, unparseable number/boolean coercion, missing flag value).
+// alwaysPermanent — every case is operator-shape misuse the framework
+// will not coerce; the operator fixes the spec or the argv source.
+var ArgParserError        = defineClass("ArgParserError",        { alwaysPermanent: true });
+// DaemonError — b.daemon (lib/daemon.js). Bad opts at start/stop, pidfile
+// already held by a live PID, spawn failure for detached-fork mode,
+// log-file open failure, kill() failure outside ESRCH. alwaysPermanent —
+// every case is operator-misconfig or a host-environment condition the
+// framework refuses to coerce; transient-shaped failures (process
+// already exited between read and kill) are surfaced as a non-error
+// "stopped: false, reason: stale" return.
+var DaemonError           = defineClass("DaemonError",           { alwaysPermanent: true });
+// SelfUpdateError — b.selfUpdate (lib/self-update.js). Bad opts at
+// poll/verify/swap/rollback, non-2xx releases-feed response, malformed
+// JSON, missing tag_name, signature verify mismatch, atomic-swap or
+// rollback failure, cross-device install failure. alwaysPermanent —
+// every case is operator-misconfig or a release-feed shape the
+// framework refuses to coerce. Operators wrap the call in their own
+// retry policy when polling against a flaky CDN.
+var SelfUpdateError       = defineClass("SelfUpdateError",       { alwaysPermanent: true });
 
 module.exports = {
   FrameworkError:         FrameworkError,
@@ -472,4 +618,27 @@ module.exports = {
   AiInputError:           AiInputError,
   A2aError:               A2aError,
   GraphqlFederationError: GraphqlFederationError,
+  Fda21Cfr11Error:        Fda21Cfr11Error,
+  AuditDailyReviewError:  AuditDailyReviewError,
+  AuditSegregationError:  AuditSegregationError,
+  DdlChangeControlError:  DdlChangeControlError,
+  LegalHoldError:         LegalHoldError,
+  WormViolationError:     WormViolationError,
+  SandboxError:           SandboxError,
+  DlpError:               DlpError,
+  AuthBotChallengeError:  AuthBotChallengeError,
+  SessionDeviceBindingError: SessionDeviceBindingError,
+  AcmeError:              AcmeError,
+  HpkeError:              HpkeError,
+  TlsExporterError:       TlsExporterError,
+  HttpSigError:           HttpSigError,
+  HttpClientError:        HttpClientError,
+  KeychainError:          KeychainError,
+  WatcherError:           WatcherError,
+  LocalDbThinError:       LocalDbThinError,
+  RouterError:            RouterError,
+  WorkerPoolError:        WorkerPoolError,
+  ArgParserError:         ArgParserError,
+  DaemonError:            DaemonError,
+  SelfUpdateError:        SelfUpdateError,
 };

package/lib/framework-schema.js

@@ -1,47 +1,47 @@
 "use strict";
 /**
- * Framework state schema for cluster-mode external storage.
+ * @module b.frameworkSchema
+ * @nav    Production
+ * @title  Framework Schema
  *
- * When cluster mode is active, the framework's audit chain + consent
- * log + audit checkpoints + audit tip live in the operator's external-db
- * (configured via b.externalDb.init). This module owns the DDL for
- * those tables and exposes a single idempotent ensureSchema() entry
- * point that operators (or the framework's leader-acquire hook in a
- * later release) call to create them.
+ * @intro
+ *   Framework-defined SQL schema (audit / sessions / api_keys / cache /
+ *   break-glass / scheduler-ticks / pubsub / rate-limit / seeders /
+ *   etc.) — declarative, migration-aware, and dialect-portable across
+ *   Postgres and SQLite.
  *
- * In external-db the framework tables are prefixed with `_blamejs_`
- * to avoid collision with the operator's app data:
+ *   When cluster mode is active the framework's audit chain, consent
+ *   log, audit checkpoints, audit tip, scheduler ticks, rate-limit
+ *   counters, pubsub fan-out, sessions, jobs, cache, seeders, and
+ *   break-glass policies/grants live in the operator's external
+ *   database (configured via `b.externalDb.init`). This module owns
+ *   the DDL for those tables and exposes a single idempotent entry
+ *   point — `b.frameworkSchema.ensureSchema` — that operators (or the
+ *   framework's leader-acquire hook in a later release) call to create
+ *   them at boot.
  *
- *   audit_log          local-SQLite name
- *   _blamejs_audit_log external-db name
+ *   External-db tables are prefixed with `_blamejs_` so they never
+ *   collide with the operator's application tables:
  *
- * The mapping is exposed via tableName(local) so write-dispatch code
- * (cluster-storage.js) uses a single name reference and the
- * dialect-aware ensureSchema fans out the DDL to either the local-
- * SQLite (db.js's FRAMEWORK_SCHEMA) or the external-db backend.
+ *     audit_log           — local-SQLite name
+ *     _blamejs_audit_log  — external-db name
  *
- * Dialects: Postgres + SQLite. Both support CREATE TABLE IF NOT EXISTS,
- * CREATE INDEX IF NOT EXISTS, and the same column types modulo
- * INTEGER/BIGINT and BLOB/BYTEA differences. MySQL is not currently
- * supported — operators on MySQL must use one of the supported
- * dialects until a MySQL adapter ships.
+ *   `b.frameworkSchema.tableName` exposes the mapping so write-
+ *   dispatch code (`cluster-storage.js`) can use a single name
+ *   reference. `b.frameworkSchema.LOCAL_TO_EXTERNAL` is the frozen
+ *   read-only mapping object.
  *
- * What ensureSchema does NOT do:
- *   - Migrate existing audit_log rows from local SQLite into external-db.
- *     That migration belongs to a separate operator-driven tool.
- *   - Verify chain integrity in external-db. That happens at boot via
- *     the audit module's regular verify() path on every read.
- *   - Install append-only triggers. The framework's tamper-evidence
- *     model is the audit chain's hash linkage + SLH-DSA-signed
- *     checkpoints — triggers would add a defense-in-depth layer
- *     but they're not load-bearing for the threat model. Operators
- *     who want triggers add them per their dialect's syntax.
+ *   Append-only WORM enforcement: `ensureSchema` installs BEFORE
+ *   DELETE / BEFORE UPDATE triggers on `audit_log`, `consent_log`,
+ *   and `audit_checkpoints` — Postgres via plpgsql RAISE EXCEPTION
+ *   functions, SQLite via `RAISE(ABORT, ...)`. Idempotent across
+ *   reboots; any operator-applied DROP TRIGGER is restored on the
+ *   next ensureSchema pass. MySQL is not currently supported —
+ *   operators on MySQL must run on Postgres or SQLite until a MySQL
+ *   adapter ships.
  *
- * Public API:
- *   await frameworkSchema.ensureSchema({ externalDbBackend, dialect })
- *   frameworkSchema.tableName(localName)   external table name lookup
- *   frameworkSchema.LOCAL_TO_EXTERNAL      mapping (read-only)
- *   frameworkSchema.FrameworkSchemaError   error class
+ * @card
+ *   Framework-defined SQL schema (audit / sessions / api_keys / cache / break-glass / scheduler-ticks / pubsub / rate-limit / seeders / etc.) — declarative, migration-aware, and dialect-portable across Postgres and SQLite.
  */
 
 var externalDb = require("./external-db");
@@ -138,6 +138,29 @@ var LOCAL_TO_EXTERNAL = Object.freeze({
   _blamejs_break_glass_grants:   "_blamejs_break_glass_grants",
 });
 
+/**
+ * @primitive b.frameworkSchema.tableName
+ * @signature b.frameworkSchema.tableName(localName)
+ * @since     0.5.0
+ * @status    stable
+ * @related   b.frameworkSchema.ensureSchema
+ *
+ * Translate a local-SQLite table name into the external-db name. The
+ * mapping is the frozen `LOCAL_TO_EXTERNAL` object — tables that already
+ * carry the `_blamejs_` prefix locally pass through unchanged. Cluster
+ * write-dispatch code uses this lookup so the same SQL works against
+ * both backends without per-call branching.
+ *
+ * @example
+ *   b.frameworkSchema.tableName("audit_log");
+ *   // → "_blamejs_audit_log"
+ *
+ *   b.frameworkSchema.tableName("_blamejs_sessions");
+ *   // → "_blamejs_sessions"
+ *
+ *   b.frameworkSchema.tableName("operator_app_table");
+ *   // → "operator_app_table"
+ */
 function tableName(localName) {
   if (Object.prototype.hasOwnProperty.call(LOCAL_TO_EXTERNAL, localName)) {
     return LOCAL_TO_EXTERNAL[localName];
@@ -660,6 +683,42 @@ function _breakGlassGrantsDDL(dialect) {
 
 // ---- ensureSchema ----
 
+/**
+ * @primitive b.frameworkSchema.ensureSchema
+ * @signature b.frameworkSchema.ensureSchema(opts)
+ * @since     0.5.0
+ * @status    stable
+ * @related   b.frameworkSchema.tableName, b.externalDb.init, b.audit
+ *
+ * Create every framework-owned table + index in the operator's
+ * external database, then install append-only WORM triggers on
+ * `_blamejs_audit_log`, `_blamejs_consent_log`, and
+ * `_blamejs_audit_checkpoints`. Idempotent: every DDL uses
+ * `IF NOT EXISTS` and re-running is safe across reboots.
+ *
+ * Returns `{ tables }` with the set of CREATE TABLE names emitted
+ * so the operator can confirm the expected surface landed.
+ *
+ * Throws `FrameworkSchemaError("framework-schema/invalid-config")`
+ * when `externalDbBackend` is missing and
+ * `FrameworkSchemaError("framework-schema/unsupported-dialect")`
+ * when `dialect` is anything other than `postgres` or `sqlite`.
+ *
+ * @opts
+ *   externalDbBackend: string,     // backend name registered with b.externalDb (required)
+ *   dialect:           "postgres"|"sqlite",  // default: "postgres"
+ *
+ * @example
+ *   try {
+ *     var report = await b.frameworkSchema.ensureSchema({
+ *       externalDbBackend: "primary",
+ *       dialect:           "postgres",
+ *     });
+ *     report.tables[0]; // → "_blamejs_audit_log"
+ *   } catch (e) {
+ *     e.code; // → "framework-schema/unsupported-dialect"
+ *   }
+ */
 async function ensureSchema(opts) {
   if (!opts || !opts.externalDbBackend) {
     throw new FrameworkSchemaError(
@@ -706,9 +765,78 @@ async function ensureSchema(opts) {
     }
     created.push(d.create.match(/CREATE TABLE IF NOT EXISTS\s+(\S+)/)[1]);
   }
+
+  // D-M11 — append-only WORM enforcement on audit_log / consent_log /
+  // audit_checkpoints in cluster mode. Local-SQLite path already
+  // installs CREATE TRIGGER IF NOT EXISTS via lib/db.js's
+  // _installAppendOnlyTriggers; Postgres needs equivalent rules
+  // (BEFORE-row triggers raising an exception) so a privileged
+  // cluster-side actor with the framework role can't DELETE / UPDATE
+  // a row out from under the chain. The chain integrity check still
+  // catches it at next boot, but the trigger is the in-band defense.
+  await _installWormTriggers(opts.externalDbBackend, dialect);
+
   return { tables: created };
 }
 
+// D-M11 — WORM enforcement helper. Idempotent: rebuilding triggers
+// per boot is cheap and any operator-applied DROP TRIGGER is restored
+// at the next ensureSchema pass.
+async function _installWormTriggers(backend, dialect) {
+  var wormTables = [
+    LOCAL_TO_EXTERNAL.audit_log,
+    LOCAL_TO_EXTERNAL.consent_log,
+    LOCAL_TO_EXTERNAL.audit_checkpoints,
+  ];
+  for (var i = 0; i < wormTables.length; i++) {
+    var t = wormTables[i];
+    if (dialect === "postgres") {
+      // Per-table trigger function. Postgres rejects the statement
+      // with a SQLSTATE that bubbles up as a query-failure audit row.
+      var fnName = t + "_worm_block";
+      await externalDb.query(
+        "CREATE OR REPLACE FUNCTION " + fnName + "() RETURNS trigger AS $$ " +
+        "BEGIN RAISE EXCEPTION '" + t + " is append-only — % prohibited', TG_OP " +
+        "USING ERRCODE = '0A000'; END; $$ LANGUAGE plpgsql",
+        [], { backend: backend }
+      );
+      await externalDb.query(
+        "DROP TRIGGER IF EXISTS no_delete_" + t + " ON " + t,
+        [], { backend: backend }
+      );
+      await externalDb.query(
+        "CREATE TRIGGER no_delete_" + t + " BEFORE DELETE ON " + t +
+        " FOR EACH ROW EXECUTE FUNCTION " + fnName + "()",
+        [], { backend: backend }
+      );
+      await externalDb.query(
+        "DROP TRIGGER IF EXISTS no_update_" + t + " ON " + t,
+        [], { backend: backend }
+      );
+      await externalDb.query(
+        "CREATE TRIGGER no_update_" + t + " BEFORE UPDATE ON " + t +
+        " FOR EACH ROW EXECUTE FUNCTION " + fnName + "()",
+        [], { backend: backend }
+      );
+    } else {
+      // SQLite cluster path. CREATE TRIGGER IF NOT EXISTS matches the
+      // local-SQLite shape installed by lib/db.js.
+      await externalDb.query(
+        'CREATE TRIGGER IF NOT EXISTS "no_delete_' + t + '" ' +
+        'BEFORE DELETE ON "' + t + '" ' +
+        "BEGIN SELECT RAISE(ABORT, '" + t + " is append-only — DELETE prohibited'); END",
+        [], { backend: backend }
+      );
+      await externalDb.query(
+        'CREATE TRIGGER IF NOT EXISTS "no_update_' + t + '" ' +
+        'BEFORE UPDATE ON "' + t + '" ' +
+        "BEGIN SELECT RAISE(ABORT, '" + t + " is append-only — UPDATE prohibited'); END",
+        [], { backend: backend }
+      );
+    }
+  }
+}
+
 module.exports = {
   ensureSchema:           ensureSchema,
   tableName:              tableName,