@blamejs/core 0.8.43 → 0.8.49

package/lib/observability.js

@@ -1,58 +1,49 @@
 "use strict";
 /**
- * observability — combined metrics + tracing tap surface.
+ * @module b.observability
+ * @nav    Observability
+ * @title  Observability
  *
- * Framework hot paths previously called metrics.tap + tracing.tap
- * separately, with each module repeating the lazy-require + try/catch
- * boilerplate. This primitive folds the two into one helper:
+ * @intro
+ *   Combined metrics + tracing tap surface — every framework hot
+ *   path uses this one primitive to emit both a span and a counter
+ *   bump in one call, with redact-aware metadata and breadcrumb
+ *   integration into the audit chain.
  *
- *   var obs = require("./observability");
- *   return obs.tap("audit.record",
- *     { action: event.action, outcome: event.outcome },
- *     async function (span) {
- *       // ... operation body ...
- *       return result;
- *     });
- *
- * Behavior:
- *   - tracing.tap wraps fn in a span (spec 9.8). Pass-through is
- *     fn(null) when no tracing registry is active — zero overhead.
- *   - After fn settles (either branch), metrics.tap fires once with
- *     the same name + the same attrs reused as labels. Existing
- *     metrics _tapHandler dispatches still work unchanged because
- *     the labels are the same shape modules previously passed.
- *   - If fn throws (sync) or rejects (async), metrics still fire
- *     before the throw propagates. Operators get the counter bump
- *     even on the failure path — the existing pattern across audit /
- *     vault / queue did the same.
- *
- * Why combine: every framework module that wanted both a span AND a
- * counter previously wrote nested tap wrappers + try/catch. Centralizing
- * keeps the call sites readable, eliminates boot-order drift each
- * module had to reason about, and lets us change tap semantics
- * (e.g. add a third sink) in one place.
+ *   `tap(name, attrs, fn)` wraps `fn` in a tracing span (via
+ *   `b.tracing.tap`) and bumps a metrics counter named `name` (via
+ *   `b.metrics.tap`) when the function settles, on both the success
+ *   and failure branches. `event(name, value, labels)` is the
+ *   fire-and-forget shape — fires the counter only, no span — and
+ *   `safeEvent` wraps it in a try/catch so per-request hot paths
+ *   can't crash the request that triggered them when the metrics
+ *   registry has a misconfigured counter or label name.
  *
- * For fire-and-forget value-noting where wrapping fn doesn't fit —
- * incrementing a counter on a side-effect deep inside an existing
- * function — use `event(name, value, labels)`. Same shape as the
- * legacy metrics.tap call; routes through metrics only (no span).
+ *   `timed(name, fn, labels)` measures wall-clock duration of an
+ *   operation and emits a counter event with `outcome: "ok"` /
+ *   `"fail"` plus `duration_ms` in the labels — the standard pattern
+ *   for per-call SLO tracking. `SEMCONV` carries the OTel
+ *   semantic-convention attribute names (1.27+ stable namespace) so
+ *   operators wiring the framework's tap into an OTel SDK don't
+ *   maintain an aliasing table.
  *
- * Public API:
- *   observability.tap(name, attrs, fn)        → fn's return value
- *   observability.tap(name, fn)               → fn's return value (no attrs)
- *   observability.event(name, value, labels)  → undefined
+ *   `traceContext.parse` / `traceContext.build` parse and emit the
+ *   W3C `traceparent` header per RFC; `traceContext.parseTracestate`
+ *   / `traceContext.buildTracestate` cover the `tracestate` companion
+ *   header (32-entry / 512-char W3C cap). `baggage.parse` /
+ *   `baggage.build` cover the W3C Baggage header for cross-service
+ *   user context (tenant / region / experiment).
  *
- * Tests live in test/layer-0-primitives/observability.test.js.
+ *   The drop-silent contract is intentional — observability runs in
+ *   request hot paths where throwing on a misnamed metric would
+ *   crash the request that triggered the emit. Bad input on
+ *   `event` / `safeEvent` is dropped silently; bad input on `tap`
+ *   throws at boot-time call sites where operators can fix typos
+ *   before they corrupt the span tree AND the metrics route at the
+ *   same time.
  *
- * Parameters:
- *   name: string — used as both the span name AND the metrics tap
- *     name. Convention: dotted lowercase ("audit.record", "queue.enqueue").
- *   attrs: object | null — passed verbatim to tracing.tap as span
- *     attributes AND to metrics.tap as labels. Modules previously
- *     passing two slightly-different objects to the two sinks should
- *     pass one unified shape.
- *   fn: function — sync or async. Return propagates; throws propagate
- *     after metrics fire.
+ * @card
+ *   Combined metrics + tracing tap surface — every framework hot path uses this one primitive to emit both a span and a counter bump in one call, with redact-aware metadata and breadcrumb integration into the audit chain.
  */
 var C = require("./constants");
 var lazyRequire = require("./lazy-require");
@@ -86,6 +77,27 @@ function _safeMetricsTap(name, value, labels) {
 //
 // The handler signature mirrors metrics.tap: (name, value, labels).
 // Pass null to remove the previously-installed handler.
+/**
+ * @primitive b.observability.setTap
+ * @signature b.observability.setTap(handler)
+ * @since     0.7.40
+ * @related   b.observability.tap, b.observability.event
+ *
+ * Install an external tap handler that receives every
+ * `(name, value, labels)` triple in addition to the framework's
+ * metrics module. Wired by `b.otelExport.create()` so an OTLP/HTTP
+ * exporter sees the same hot-path counters the framework emits
+ * internally. Pass `null` to remove the previously-installed handler.
+ *
+ * @example
+ *   b.observability.setTap(function (name, value, labels) {
+ *     console.log("[obs]", name, value, labels);
+ *   });
+ *   b.observability.event("audit.record", 1,
+ *     { action: "auth.login", outcome: "success" });
+ *   // → "[obs] audit.record 1 { action: 'auth.login', outcome: 'success' }"
+ *   b.observability.setTap(null);   // remove
+ */
 function setTap(handler) {
   if (handler !== null && typeof handler !== "function") {
     throw new TypeError("observability.setTap: handler must be a function or null, got " +
@@ -94,6 +106,32 @@ function setTap(handler) {
   _externalTap = handler;
 }
 
+/**
+ * @primitive b.observability.tap
+ * @signature b.observability.tap(name, attrs, fn)
+ * @since     0.7.0
+ * @status    stable
+ * @related   b.observability.event, b.tracing.tap, b.metrics.tap
+ *
+ * Wrap `fn` in a tracing span (via `b.tracing.tap`) and bump a
+ * metrics counter named `name` (via `b.metrics.tap`) when the
+ * function settles. The same `attrs` object becomes both span
+ * attributes and metric labels. Counter fires on both the success
+ * and failure paths so dashboards never miss a failure-rate
+ * increment. The two-arg form `tap(name, fn)` skips attributes.
+ * Throws on bad input — typos in `name` would silently corrupt both
+ * the span tree and the metrics route, so this is a config-time
+ * boundary.
+ *
+ * @example
+ *   var rows = await b.observability.tap("db.query",
+ *     { table: "users" },
+ *     async function (span) {
+ *       span.setAttribute("db.statement", "SELECT id FROM users");
+ *       return await db.queryAll("SELECT id FROM users");
+ *     });
+ *   // span ended, framework_db_query_total bumped by 1
+ */
 function tap(name, attrs, fn) {
   if (typeof attrs === "function") { fn = attrs; attrs = null; }
   // Throw on bad input: tap is called from many call sites and a typo
@@ -133,6 +171,24 @@ function tap(name, attrs, fn) {
 // counter, not a 500. metrics.tap performs its own label-name regex
 // validation; an invalid call surfaces in the metrics module log, not
 // via a thrown exception.
+/**
+ * @primitive b.observability.event
+ * @signature b.observability.event(name, value, labels)
+ * @since     0.7.0
+ * @status    stable
+ * @related   b.observability.tap, b.observability.safeEvent
+ *
+ * Fire-and-forget counter emit — same shape as `b.metrics.tap` but
+ * routed through observability so the operator's external tap
+ * (`setTap`) sees it too. Drop-silent on bad `name` by design: this
+ * runs in hot paths where throwing on a typo would crash the request
+ * that triggered the emit. Use `tap` instead when you also want a
+ * span around the emitting code.
+ *
+ * @example
+ *   b.observability.event("queue.enqueue", 1, { queueName: "email" });
+ *   b.observability.event("error.construct", 1, { class: "DatabaseError" });
+ */
 function event(name, value, labels) {
   if (typeof name !== "string" || name.length === 0) return;
   _safeMetricsTap(name, value, labels);
@@ -143,6 +199,23 @@ function event(name, value, labels) {
 // triggered them when the metrics registry has a misconfigured
 // counter or label name. Replaces the per-file `_emitEvent` helper
 // that 7+ modules previously duplicated.
+/**
+ * @primitive b.observability.safeEvent
+ * @signature b.observability.safeEvent(name, value, labels)
+ * @since     0.7.40
+ * @related   b.observability.event, b.observability.tap
+ *
+ * Wraps `event` in a try/catch so per-request observability emits
+ * cannot crash the request that triggered them when the metrics
+ * registry has a misconfigured counter or label name. Replaces the
+ * per-file `_emitEvent` helper that several modules previously
+ * duplicated.
+ *
+ * @example
+ *   // Inside a request handler — even with a typo in label name,
+ *   // the request still completes.
+ *   b.observability.safeEvent("auth.attempt", 1, { outcome: "success" });
+ */
 function safeEvent(name, value, labels) {
   try { event(name, value, labels); }
   catch (_e) { /* hot-path observability sink — drops silent on internal throws */ }
@@ -164,6 +237,31 @@ function safeEvent(name, value, labels) {
 // The operation name MUST be a stable string (not derived from input)
 // to keep the metric cardinality bounded; operators dynamically
 // scope-naming via prefix should use the labels parameter instead.
+/**
+ * @primitive b.observability.timed
+ * @signature b.observability.timed(name, fn, labels)
+ * @since     0.7.40
+ * @status    stable
+ * @related   b.observability.event, b.observability.tap
+ *
+ * Measure wall-clock duration of a sync or async operation and emit
+ * a counter event with `outcome: "ok"` / `"fail"` plus `duration_ms`
+ * in the labels. Returns the wrapped function's return value
+ * verbatim; on throw, emits the failure event with `error_type` set
+ * to the error's `name` and re-throws. The `name` argument MUST be a
+ * stable string (not derived from input) to keep the metric
+ * cardinality bounded — operators dynamically scoping should put
+ * variable parts into `labels`.
+ *
+ * @example
+ *   var rows = await b.observability.timed("db.query",
+ *     async function () {
+ *       return await db.queryAll("SELECT id FROM users");
+ *     },
+ *     { [b.observability.SEMCONV.DB_OPERATION_NAME]: "select" });
+ *   // → emits db.query with { outcome: "ok", duration_ms: 12,
+ *   //   "db.operation.name": "select" }
+ */
 function timed(name, fn, labels) {
   if (typeof name !== "string" || name.length === 0) {
     throw new TypeError("observability.timed: name must be a non-empty string");

package/lib/openapi.js

@@ -1,42 +1,36 @@
 "use strict";
 /**
- * b.openapi — OpenAPI 3.1 schema-document builder.
+ * @module b.openapi
+ * @nav    Other
+ * @title  Openapi
  *
- * Operators describe their public HTTP surface as an OpenAPI 3.1
- * document the framework can serve at /openapi.json (or any path of
- * their choice) for downstream tooling: API consumers, Postman, code-
- * generators, contract-testing rigs.
+ * @intro
+ *   OpenAPI 3.1 emitter from declarative route declarations + schemas
+ *   (composable with `b.safeSchema`); JSON / YAML output. Operators
+ *   describe their public HTTP surface as an OpenAPI 3.1 document the
+ *   framework serves at `/openapi.json` (or any path) for downstream
+ *   tooling: API consumers, Postman, code-generators, contract-test
+ *   rigs.
  *
- * The builder is FRAMEWORK-FACING: it produces a valid OpenAPI 3.1
- * document, but the operator's hand-written contract is the source of
- * truth — it does NOT auto-walk b.router routes (operators frequently
- * want a smaller / different surface published than what the router
- * exposes internally). Future patch may add `fromRouter()` once the
- * route-shape is stable.
+ *   The builder is FRAMEWORK-FACING: it produces a valid OpenAPI 3.1
+ *   document, but the operator's hand-written contract is the source
+ *   of truth — it does NOT auto-walk `b.router` routes (operators
+ *   frequently want a smaller / different surface published than what
+ *   the router exposes internally).
  *
- * Public surface:
+ *   The builder fluent surface is `path()` / `schema()` / `response()`
+ *   / `parameter()` / `requestBody()` / `header()` / `example()` /
+ *   `security.add()` / `security.require()` / `tag()` / `server()`,
+ *   each returning the builder for chaining. Terminal calls are
+ *   `toJson()` (3.1 JSON document with referential integrity checked
+ *   — every security-scheme reference must resolve), `toJsonString()`,
+ *   `toYaml()`, and `middleware(opts)` which mounts the cached
+ *   document at request-time. Security-scheme builders for bearer /
+ *   basic / apiKey / oauth2 / openIdConnect / mtls / dpop live on
+ *   `b.openapi.security`.
  *
- *   b.openapi.create({ info, servers, externalDocs, tags })
- *     -> builder
- *
- *   builder.path(method, urlPattern, opts)            // add operation
- *   builder.schema(name, schema)                       // reusable component schema
- *   builder.response(name, response)                   // reusable response
- *   builder.parameter(name, parameter)                 // reusable parameter
- *   builder.security.add(name, scheme)                 // add security scheme
- *   builder.security.require(requirement)              // doc-level security
- *   builder.tag({ name, description })                 // tag group
- *   builder.server({ url, description, variables })    // server URL
- *
- *   builder.toJson()        -> OpenAPI 3.1 JSON document
- *   builder.toYaml()        -> YAML serialisation (if vendored YAML present)
- *   builder.middleware(opts) -> request-time middleware that serves the doc
- *
- *   b.openapi.security.{bearer,basic,apiKey,oauth2,openIdConnect,mtls,dpop}
- *     -> security-scheme builders (delegated from openapi-security.js)
- *
- *   b.openapi.schemaWalk(input)
- *     -> safeSchema -> JSON Schema utility (delegated)
+ * @card
+ *   OpenAPI 3.1 emitter from declarative route declarations + schemas (composable with `b.safeSchema`); JSON / YAML output.
  */
 
 var validateOpts          = require("./validate-opts");
@@ -52,6 +46,43 @@ var OpenApiError = defineClass("OpenApiError", { alwaysPermanent: true });
 
 var OPENAPI_VERSION = "3.1.0";
 
+/**
+ * @primitive b.openapi.create
+ * @signature b.openapi.create(opts)
+ * @since     0.6.30
+ * @related   b.openapi.parse, b.asyncapi.create, b.safeSchema
+ *
+ * Build a fluent OpenAPI 3.1 document builder. `opts.info` is required
+ * (`title` + `version`). Returns a chainable builder; terminal calls
+ * are `toJson()`, `toJsonString(indent)`, `toYaml()`, and
+ * `middleware(opts)`. `toJson()` cross-checks every doc-level and
+ * per-operation security requirement against
+ * `components.securitySchemes` and throws
+ * `OpenApiError("openapi/dangling-security")` on a missing scheme.
+ *
+ * @opts
+ *   info:         { title, version, description?, contact?, license? },   // REQUIRED — title + version are non-empty strings
+ *   servers:      array,           // [{ url, description?, variables? }, ...]
+ *   externalDocs: { url, description? },
+ *   tags:         array,           // [{ name, description? }, ...] — seed; builder.tag() appends more
+ *   security:     array,           // doc-level security requirements [{ schemeName: ["scope"] }, ...]
+ *
+ * @example
+ *   var doc = b.openapi.create({
+ *     info:    { title: "Acme API", version: "1.0.0" },
+ *     servers: [{ url: "https://api.acme.example.com" }],
+ *   });
+ *   doc.security.add("bearerAuth", b.openapi.security.bearer({ bearerFormat: "JWT" }));
+ *   doc.path("get", "/users/{id}", {
+ *     summary:    "Fetch a user",
+ *     parameters: [{ name: "id", in: "path", required: true, schema: { type: "string" } }],
+ *     responses:  { "200": { description: "ok" }, "404": { description: "not found" } },
+ *     security:   [{ bearerAuth: [] }],
+ *   });
+ *   var json = doc.toJson();
+ *   json.openapi;           // → "3.1.0"
+ *   json.paths["/users/{id}"].get.summary;   // → "Fetch a user"
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [
@@ -316,17 +347,32 @@ function create(opts) {
   return builder;
 }
 
-// Parse + validate an external OpenAPI 3.1 JSON document. Operators
-// hand a doc that arrived from a downstream integration (consumer
-// hand-edited, contract-test fixture, third-party publish) and want
-// the framework's gate to enforce the same shape rules `toJson` does
-// on builder output.
-//
-// Returns `{ doc, errors[] }`. `doc` is the parsed object (whether
-// valid or not, so the operator can inspect what they got);
-// `errors` is an array of strings — empty on a valid document.
-//
-// Throws (config-time entry-point) on invalid JSON / wrong type.
+/**
+ * @primitive b.openapi.parse
+ * @signature b.openapi.parse(jsonStringOrObject)
+ * @since     0.6.30
+ * @related   b.openapi.create
+ *
+ * Parse + validate an external OpenAPI 3.1 document. Operators hand a
+ * doc that arrived from a downstream integration (consumer hand-
+ * edited, contract-test fixture, third-party publish) and want the
+ * framework's gate to enforce the same shape rules `toJson()`
+ * enforces on builder output. Throws on invalid JSON or non-object
+ * input; otherwise returns `{ doc, errors, valid }`. `errors` is an
+ * array of strings — empty on a valid document. Path keys must start
+ * with `/`, every operation must declare `responses` with a
+ * `description`, path parameters must carry `required: true`, and
+ * doc-level security must reference declared schemes.
+ *
+ * @example
+ *   var result = b.openapi.parse('{"openapi":"3.1.0","info":{"title":"x","version":"1.0.0"}}');
+ *   result.valid;       // → true
+ *   result.errors;      // → []
+ *
+ *   var bad = b.openapi.parse({ openapi: "3.1.0", info: { title: "x", version: "1.0.0" }, paths: { "users": {} } });
+ *   bad.valid;          // → false
+ *   bad.errors[0];      // → 'path "users" must start with \'/\''
+ */
 function parse(jsonStringOrObject) {
   var doc;
   if (typeof jsonStringOrObject === "string") {

package/lib/outbox.js

@@ -102,12 +102,94 @@ function _utcNowExpr(externalDb) {
   return new Date();
 }
 
+// Debezium-shape change-event envelope. Operators integrating with
+// downstream Kafka Connect / Debezium consumers opt-in via
+// `outbox.create({ envelope: "debezium" })`. The envelope wraps the
+// operator's payload as `payload.after` and carries Debezium
+// connector-shape metadata (`source`, `op`, `ts_ms`).
+//
+// Reference: Debezium 2.x ChangeEvent envelope —
+//   { schema: { type, fields, optional, name }, payload: {...} }
+//
+// We don't ship a schema-registry hookup — the payload's schema is
+// "operator-supplied JSON object" by default. Operators integrating
+// with Confluent Schema Registry attach `event.debezium.schema` to
+// override per-event.
+var DEFAULT_DEBEZIUM_CONNECTOR_VERSION = "1.0.0";                                  // allow:raw-byte-literal — version string
+
+function _debeziumSchemaFor(payloadObj) {
+  // Best-effort schema synthesis. Debezium consumers expect a JSON
+  // schema description of `payload`. We emit a permissive object
+  // schema so consumers that don't rely on the schema field still
+  // round-trip the payload cleanly.
+  return {
+    type: "struct",
+    optional: false,
+    name:    "blamejs.outbox.Envelope",
+    fields: [
+      { type: "struct", optional: true, field: "before",
+        name: "blamejs.outbox.Row" },
+      { type: "struct", optional: true, field: "after",
+        name: "blamejs.outbox.Row" },
+      { type: "struct", optional: false, field: "source",
+        name: "blamejs.outbox.Source",
+        fields: [
+          { type: "string", optional: false, field: "connector" },
+          { type: "string", optional: false, field: "version"   },
+          { type: "string", optional: true,  field: "db"        },
+          { type: "string", optional: false, field: "table"     },
+          { type: "int64",  optional: false, field: "ts_ms"     },
+        ],
+      },
+      { type: "string", optional: false, field: "op" },
+      { type: "int64",  optional: false, field: "ts_ms" },
+    ],
+  };
+}
+
+function _toDebeziumEnvelope(rawEvent, opts) {
+  // rawEvent is the operator-shape `{ topic, payload, key, headers,
+  // attempts, id }` we already pass to plain publishers. We adapt
+  // it here so existing operator schemas work unchanged.
+  var payload = rawEvent.payload && typeof rawEvent.payload === "object"
+    ? rawEvent.payload : { value: rawEvent.payload };
+  var op = (rawEvent.headers && typeof rawEvent.headers === "object" &&
+            typeof rawEvent.headers["debezium-op"] === "string")
+    ? rawEvent.headers["debezium-op"]
+    : "c";  // default: create. Operators emit u (update) / d (delete) via headers.
+  var nowMs = Date.now();
+  return {
+    schema: _debeziumSchemaFor(payload),
+    payload: {
+      before: (payload && payload.before) || null,
+      after:  (payload && payload.after !== undefined) ? payload.after : payload,
+      source: {
+        connector: opts.connectorName || "blamejs",
+        version:   opts.connectorVersion || DEFAULT_DEBEZIUM_CONNECTOR_VERSION,
+        db:        opts.dbName || null,
+        table:     rawEvent.topic,                      // topic is the table-shape stable identifier
+        ts_ms:     nowMs,
+      },
+      op:    op,
+      ts_ms: nowMs,
+      // Operator-shape passthrough: `key` / `headers` / `attempts`
+      // travel as Debezium-extension fields so consumers that need
+      // them aren't forced to fabricate.
+      key:      rawEvent.key       || null,
+      headers:  rawEvent.headers   || null,
+      attempts: rawEvent.attempts  || 0,
+      eventId:  rawEvent.id        || null,
+    },
+  };
+}
+
 function create(opts) {
   validateOpts.requireObject(opts, "outbox", OutboxError);
   validateOpts(opts, [
     "externalDb", "table", "publisher",
     "pollIntervalMs", "batchSize", "maxAttempts",
     "retryBackoff", "audit", "name",
+    "envelope", "connectorName", "connectorVersion", "dbName",
   ], "outbox.create");
 
   if (!opts.externalDb || typeof opts.externalDb.transaction !== "function") {
@@ -148,6 +230,15 @@ function create(opts) {
   var auditOn        = opts.audit !== false;
   var externalDb     = opts.externalDb;
   var publisher      = opts.publisher;
+  var envelope       = opts.envelope || "raw";
+  if (envelope !== "raw" && envelope !== "debezium") {
+    throw new OutboxError("outbox/bad-envelope",
+      "outbox.create: envelope must be 'raw' (default) or 'debezium', got " +
+      JSON.stringify(envelope));
+  }
+  var connectorName    = opts.connectorName || "blamejs";
+  var connectorVersion = opts.connectorVersion || DEFAULT_DEBEZIUM_CONNECTOR_VERSION;
+  var dbName           = opts.dbName || null;
 
   function _backoffMs(attempts) {
     var ms = backoffInitial * Math.pow(backoffFactor, Math.max(0, attempts - 1));
@@ -326,7 +417,14 @@ function create(opts) {
           headers:  row.headers ? safeJson.parse(row.headers, { maxBytes: C.BYTES.mib(1) }) : null,
           attempts: row.attempts,
         };
-        await publisher(event);
+        var publishEvent = (envelope === "debezium")
+          ? _toDebeziumEnvelope(event, {
+              connectorName:    connectorName,
+              connectorVersion: connectorVersion,
+              dbName:           dbName,
+            })
+          : event;
+        await publisher(publishEvent);
         await _markPublished(row.id);
         _emitMetric("published", 1);
       } catch (e) {