@blamejs/core 0.8.42 → 0.8.49

package/lib/chain-writer.js

@@ -1,50 +1,39 @@
 "use strict";
 /**
- * Chain-writer primitive — race-safe append to a hash-chained log table.
+ * @module b.chainWriter
+ * @nav    Observability
+ * @title  Chain Writer
  *
- * The framework's audit_log AND consent_log have the same shape:
+ * @intro
+ *   Race-safe append to a hash-chained log table. Both `audit_log` and
+ *   `consent_log` share the same row shape — take next monotonic
+ *   counter, read previous row's `rowHash`, seal the logical row via
+ *   field-crypto, materialize null entries for every hashable column
+ *   so canonicalization sees the same key set at write-time and
+ *   verify-time, compute `rowHash` over the sealed content, INSERT
+ *   with `prevHash` / `rowHash` / `nonce` / `fencingToken`.
  *
- *   1. Take the next monotonic counter
- *   2. Compute prevHash from the previous row's rowHash
- *   3. Seal the logical row via field-crypto (sealedFields → vault.seal,
- *      derivedHashes computed)
- *   4. Materialize null entries for every hashable column (so canonicalize
- *      at write-time and verify-time agree on the key set)
- *   5. Compute rowHash over the sealed content (excluding chain bookkeeping)
- *   6. INSERT with prevHash / rowHash / nonce / fencingToken
+ *   The chain-writer extracts that pattern so every consumer gets the
+ *   same race protection. Each instance owns a per-chain Mutex
+ *   serializing read-prev → compute-hash → insert (without it,
+ *   concurrent appends hash against the same prev-tip and fork the
+ *   chain), plus a Once initializing the in-process counter from
+ *   `MAX(monotonicCounter)` on first use.
  *
- * audit.js and consent.js previously each carried their own copy of
- * the chain-write pattern. The duplication produced bugs at the same
- * architectural points: a chain-fork race had to be fixed in audit
- * via Mutex, and consent had the same race because the fix hadn't
- * propagated. Per the framework's "if a task repeats more than once
- * it should be a primitive" rule, the pattern lives here and every
- * chain-writer consumer gets the same safety guarantees automatically.
+ *   Writes route through the cluster-storage dispatcher so the same
+ *   chain definition works on single-node SQLite and on cluster-mode
+ *   external Postgres. `cluster.requireLeader()` runs before the
+ *   mutex; followers reject with `NotLeaderError`. Table names are
+ *   restricted to the `ALLOWED_CHAIN_TABLES` allowlist so a misconfig
+ *   can't point a writer at a non-chain table and corrupt the chain
+ *   semantics.
  *
- * Each chain-writer instance owns:
- *   - The table name (validated via sql-safe.assertOneOf at construction)
- *   - The full column list (for INSERT)
- *   - The hashable column list (for canonicalization)
- *   - A Mutex serializing the chain (read-prev → compute-hash → insert)
- *   - A Once initializing the in-process counter from MAX(monotonicCounter)
+ *   Operators usually don't construct chain-writers directly — `b.audit`
+ *   and `b.consent` each construct one at module load. Direct use is
+ *   for new chain-backed tables registered in `ALLOWED_CHAIN_TABLES`.
  *
- * Writes go through the cluster-storage dispatcher so the same chain
- * definition works in single-node SQLite and cluster-mode external-db.
- *
- * Public API:
- *
- *   chainWriter.create({
- *     table:           "audit_log" | "consent_log" | …,
- *     columnsForInsert: [string],            order matters; INSERT uses this
- *     hashableColumns:  [string],            for canonicalize null-fill
- *     validateAction:   function (event)     optional; throws on invalid input
- *   })
- *
- *   writer.append(logical)                   async; returns { rowHash, prevHash, …logical }
- *   writer._resetForTest()                   re-initializes counter + mutex
- *
- * Operators usually don't construct chain-writers directly; audit and
- * consent each construct one at module load.
+ * @card
+ *   Race-safe append to a hash-chained log table.
  */
 
 var { generateToken, generateBytes } = require("./crypto");
@@ -74,6 +63,42 @@ class ChainWriterError extends FrameworkError {
   }
 }
 
+/**
+ * @primitive b.chainWriter.create
+ * @signature b.chainWriter.create(opts)
+ * @since     0.8.48
+ * @status    stable
+ * @related   b.audit, b.consent, b.auditChain
+ *
+ * Build a chain-writer bound to a single hash-chained table. Returns
+ * `{ table, append, _resetForTest, _getMutexForTest }`. `append(logical)`
+ * is the public surface — async, leader-gated, mutex-serialized; on
+ * success it returns the logical row decorated with the computed
+ * `rowHash` and `prevHash`.
+ *
+ * @opts
+ *   table:            string,    // one of ALLOWED_CHAIN_TABLES (audit_log | consent_log)
+ *   columnsForInsert: string[],  // INSERT column order (every name is identifier-validated)
+ *   hashableColumns:  string[],  // columns that participate in the rowHash canonicalization
+ *   validateInput:    Function,  // optional; (logical) → throws on invalid shape
+ *
+ * @example
+ *   var writer = b.chainWriter.create({
+ *     table:            "audit_log",
+ *     columnsForInsert: ["_id", "monotonicCounter", "recordedAt",
+ *                        "action", "outcome",
+ *                        "prevHash", "rowHash", "nonce", "fencingToken"],
+ *     hashableColumns:  ["_id", "monotonicCounter", "recordedAt",
+ *                        "action", "outcome"],
+ *   });
+ *
+ *   var row = await writer.append({
+ *     action:  "user.login",
+ *     outcome: "success",
+ *   });
+ *   row.rowHash;     // → "<hex sha3-512 digest>"
+ *   row.prevHash;    // → "<previous tip rowHash, or zero-hash on first row>"
+ */
 function create(opts) {
   if (!opts || !opts.table || !Array.isArray(opts.columnsForInsert) ||
       !Array.isArray(opts.hashableColumns)) {

package/lib/circuit-breaker.js

@@ -1,46 +1,69 @@
 "use strict";
 /**
- * b.circuitBreaker — top-level circuit-breaker primitive.
+ * @module b.circuitBreaker
+ * @nav    Production
+ * @title  Circuit Breaker
  *
- * Re-exports the CircuitBreaker class previously only reachable as
- * b.retry.CircuitBreaker, plus a `create(opts)` factory that matches
- * every other framework primitive's `create()` shape. The
- * implementation lives in lib/retry.js to keep the retry-classifier
- * + CircuitBreaker close to each other (they share the
- * isRetryable / observability emit conventions). This module is the
- * top-level surface so operators don't have to know that retry
- * happens to be the home of the circuit-breaker class.
+ * @intro
+ *   Top-level circuit-breaker primitive. Re-exports the CircuitBreaker
+ *   class otherwise reachable as `b.retry.CircuitBreaker`, plus a
+ *   `create(opts)` factory matching every other framework primitive's
+ *   `create()` shape. The implementation lives in `lib/retry.js` so the
+ *   retry classifier and the breaker share the `isRetryable` /
+ *   observability emit conventions; this module is the operator-facing
+ *   surface so callers don't have to know retry is the breaker's home.
  *
- * State machine:
- *   closed   — normal flow; failures count up to failureThreshold
- *   open     — fast-fail every call for cooldownMs
- *   half     — first probe succeeds → close; first probe fails → re-open
+ *   State machine: `closed` (normal flow; failures count up to
+ *   `failureThreshold`), `open` (every call fast-fails for `cooldownMs`),
+ *   `half` (first probe closes the breaker on success or re-opens it
+ *   on failure). Intended for per-target use — one instance per
+ *   upstream service. Sharing a breaker across unrelated targets
+ *   defeats the failure-threshold semantic.
  *
+ * @card
+ *   Top-level circuit-breaker primitive.
+ */
+
+var retry = require("./retry");
+
+/**
+ * @primitive b.circuitBreaker.create
+ * @signature b.circuitBreaker.create(opts)
+ * @since     0.8.48
+ * @status    stable
+ * @related   b.retry, b.httpClient
+ *
+ * Build a circuit-breaker. Returns a CircuitBreaker instance with
+ * `wrap(fn)` (executes `fn` if the breaker is closed; throws RetryError
+ * with `code: "retry/circuit-open"` when open), `state()`, `reset()`,
+ * and `onStateChange(handler)` listener registration. Pass-through
+ * factory: identical instance shape to `b.retry.CircuitBreaker`, with
+ * the framework's `create(opts)` vocabulary.
+ *
+ * @opts
+ *   name:             string,    // identifier used in audit + state-change events
+ *   failureThreshold: number,    // failures in the closed state before opening
+ *   cooldownMs:       number,    // milliseconds the breaker stays open before probing
+ *   successThreshold: number,    // probe successes required to close from half-open
+ *   audit:            Object,    // optional b.audit instance for state-change emission
+ *   onStateChange:    Function,  // ({ name, from, to, at }) → void
+ *
+ * @example
  *   var cb = b.circuitBreaker.create({
- *     name:                 "upstream-billing",
- *     failureThreshold:     5,
- *     cooldownMs:           b.constants.TIME.seconds(30),
- *     successThreshold:     2,
- *     audit:                b.audit,
- *     onStateChange:        function (event) {
- *       // event = { name, from, to, at }
- *       log("breaker " + event.name + " " + event.from + " -> " + event.to);
+ *     name:             "upstream-billing",
+ *     failureThreshold: 5,
+ *     cooldownMs:       30000,
+ *     successThreshold: 2,
+ *     onStateChange:    function (e) {
+ *       // e = { name, from: "closed", to: "open", at: <ms> }
  *     },
  *   });
- *   await cb.wrap(function () { return upstream.callRiskyOp(); });
  *
- * The circuit-breaker is intended for per-target use (one instance
- * per upstream service); operators sharing a breaker across
- * unrelated targets defeat the failure-threshold semantic.
+ *   var result = await cb.wrap(async function () {
+ *     return { ok: true, value: 42 };
+ *   });
+ *   result.value;     // → 42
  */
-
-var retry = require("./retry");
-
-// Pass-through factory — operators get the same instance shape as
-// b.retry.CircuitBreaker but with the framework's `create(opts)`
-// vocabulary. The breaker class is unchanged; this is a thin
-// surface re-export so b.circuitBreaker is operator-discoverable
-// alongside b.retry.
 function create(opts) {
   return new retry.CircuitBreaker(opts || {});
 }

package/lib/cli-helpers.js

@@ -1,50 +1,28 @@
 "use strict";
 /**
- * cli-helpers — shared shape for blamejs CLI subcommands AND for
- * operators writing their own one-shot CLI scripts on top of the
- * framework.
+ * @module b.cliHelpers
+ * @nav    Production
+ * @title  CLI Helpers
  *
- * Three patterns recur across every CLI command (`migrate`, `seed`,
- * `audit`, `vault`, `backup`, `api-key`):
+ * @intro
+ *   Shared shape for blamejs CLI subcommands AND for operators
+ *   writing their own one-shot CLI scripts on top of the framework.
+ *   Three patterns recur across every CLI command (`migrate`, `seed`,
+ *   `audit`, `vault`, `backup`, `api-key`): bootstrap a headless
+ *   `b.createApp` instance from `--data-dir` and shut it down cleanly;
+ *   report success / error / usage with a consistent
+ *   `blamejs <verb> <sub>: <message>` prefix on stderr plus canonical
+ *   exit codes (0 ok, 1 runtime failure, 2 arg error); resolve a
+ *   passphrase from a `--<flag>` or env var into the Buffer shape
+ *   the underlying crypto primitives accept.
  *
- *   1. Bootstrap a headless `b.createApp` instance from `--data-dir`,
- *      operate against vault + DB + audit chain, shut down cleanly.
- *   2. Report success / error / usage with a consistent
- *      `blamejs <verb> <sub>: <message>` prefix on stderr + canonical
- *      exit codes (0 ok, 1 runtime failure, 2 arg error).
- *   3. Resolve a passphrase from `--<flag>` or an env var, encode to
- *      the Buffer the underlying crypto primitive needs.
+ *   The reporter writes through whichever stream `ctx.stdout` /
+ *   `ctx.stderr` point at — `process.stdout` / `process.stderr` in
+ *   production, captured stream stubs in tests — so the same handler
+ *   is testable without spawning a child process.
  *
- *   var cli = b.cliHelpers;
- *
- *   var report = cli.makeReporter(ctx, "blamejs my-tool issue");
- *   if (!args.flags["data-dir"]) return report.usage(MY_USAGE);
- *
- *   var pp = cli.resolvePassphrase(args, ctx, {
- *     flag:   "passphrase",
- *     envVar: "MY_TOOL_PASSPHRASE",
- *   });
- *   if (!pp) return report.error("--passphrase or MY_TOOL_PASSPHRASE is required", 2);
- *
- *   var booted;
- *   try {
- *     booted = await cli.bootApp({
- *       dataDir:   args.flags["data-dir"],
- *       vaultMode: "wrapped",
- *       env:       ctx.env,
- *     });
- *     // do the op against booted.b.X / booted.app.db / etc.
- *     return report.ok("done");
- *   } catch (e) {
- *     return report.error(e.message);
- *   } finally {
- *     if (booted) await booted.app.shutdown();
- *   }
- *
- * The reporter writes through whichever stream `ctx.stdout` / `ctx.stderr`
- * point at — `process.stdout` / `process.stderr` in production, captured
- * stream stubs in tests — so the same handler is testable without
- * spawning a child process.
+ * @card
+ *   Shared shape for blamejs CLI subcommands AND for operators writing their own one-shot CLI scripts on top of the framework.
  */
 
 var lazyRequire = require("./lazy-require");
@@ -66,15 +44,26 @@ function _writeLine(stream, line) {
 }
 
 /**
- * Make a reporter bound to a CLI context + a verb prefix. Every
- * stderr message produced by .error / .usage gets the prefix.
+ * @primitive b.cliHelpers.makeReporter
+ * @signature b.cliHelpers.makeReporter(ctx, prefix)
+ * @since     0.8.0
+ * @status    stable
+ * @related   b.cliHelpers.resolvePassphrase, b.cliHelpers.bootApp
  *
- *   var report = cliHelpers.makeReporter(ctx, "blamejs vault seal");
- *   return report.ok("sealed: " + path);   // stdout, returns 0
- *   return report.error("decrypt failed"); // stderr "blamejs vault seal: decrypt failed", returns 1
- *   return report.error("missing arg", 2); // returns 2 (arg error vs runtime)
- *   return report.usage(VAULT_USAGE);      // stderr USAGE, returns 2
- *   return report.helpStdout(VAULT_USAGE); // stdout USAGE, returns 0 (for `help <verb>`)
+ * Build a reporter bound to a CLI context (`ctx.stdout` /
+ * `ctx.stderr`) and a verb prefix. Every stderr message produced by
+ * `.error` / `.usage` gets the prefix. Methods return canonical
+ * Unix exit codes — `0` for `ok` / `helpStdout`, `1` for `error`
+ * (override via second arg), `2` for `usage` (argument-error
+ * convention).
+ *
+ * @example
+ *   var ctx = { stdout: process.stdout, stderr: process.stderr };
+ *   var report = b.cliHelpers.makeReporter(ctx, "blamejs vault seal");
+ *   var ok   = report.ok("sealed: /data/vault");        // → 0
+ *   var fail = report.error("decrypt failed");          // → 1
+ *   var arg  = report.error("missing --data-dir", 2);   // → 2
+ *   var help = report.usage("Usage: blamejs vault ..."); // → 2
  */
 function makeReporter(ctx, prefix) {
   if (!ctx || typeof ctx !== "object") {
@@ -111,15 +100,35 @@ function makeReporter(ctx, prefix) {
 // ---- Passphrase resolution -----------------------------------------------
 
 /**
- * Resolve a passphrase from a flag or env var into a UTF-8 Buffer
- * (the shape the underlying crypto primitives accept).
+ * @primitive b.cliHelpers.resolvePassphrase
+ * @signature b.cliHelpers.resolvePassphrase(args, ctx, opts)
+ * @since     0.8.0
+ * @status    stable
+ * @related   b.cliHelpers.makeReporter, b.cliHelpers.bootApp
+ *
+ * Resolve a passphrase from a CLI flag (preferred) or an env var
+ * (fallback) into a UTF-8 Buffer — the shape vault / crypto
+ * primitives accept. Returns `null` when neither source produced a
+ * non-empty string; the caller decides whether absence is a hard
+ * error (vault seal) or a soft default (plaintext-mode dev data dir).
  *
- *   cli.resolvePassphrase(args, ctx, { flag: "passphrase", envVar: "BLAMEJS_VAULT_PASSPHRASE" })
- *     → Buffer | null
+ * @opts
+ *   flag:    string  (CLI flag name, e.g. "passphrase" reads args.flags.passphrase),
+ *   envVar:  string  (env var fallback, e.g. "BLAMEJS_VAULT_PASSPHRASE"),
  *
- * Returns `null` when neither source produced a non-empty string. The
- * caller decides whether absence is a hard error (vault seal) or a
- * soft default (operator chose plaintext-mode).
+ * @example
+ *   var args = { flags: { passphrase: "hunter2" } };
+ *   var ctx  = { env: { BLAMEJS_VAULT_PASSPHRASE: "envval" } };
+ *   var pp = b.cliHelpers.resolvePassphrase(args, ctx, {
+ *     flag:   "passphrase",
+ *     envVar: "BLAMEJS_VAULT_PASSPHRASE",
+ *   });
+ *   pp.toString("utf8");     // → "hunter2"  (flag wins over env)
+ *
+ *   var none = b.cliHelpers.resolvePassphrase({ flags: {} }, { env: {} }, {
+ *     flag: "passphrase", envVar: "BLAMEJS_VAULT_PASSPHRASE",
+ *   });
+ *   none;                    // → null
  */
 function resolvePassphrase(args, ctx, opts) {
   opts = opts || {};
@@ -143,26 +152,48 @@ function resolvePassphrase(args, ctx, opts) {
 // ---- Headless app bootstrap ----------------------------------------------
 
 /**
- * Boot a serverless `b.createApp` instance from a data dir so a CLI
- * script (the framework's own subcommands or operator-written tools)
- * can operate against the same vault + DB + audit chain the live app
- * uses, without standing up an HTTP listener.
+ * @primitive b.cliHelpers.bootApp
+ * @signature b.cliHelpers.bootApp(opts)
+ * @since     0.8.0
+ * @status    stable
+ * @related   b.cliHelpers.makeReporter, b.cliHelpers.resolvePassphrase
  *
- *   var booted = await cli.bootApp({
- *     dataDir:   "./data",
- *     vaultMode: "wrapped",   // or "plaintext"; default "wrapped"
- *     env:       process.env, // BLAMEJS_VAULT_PASSPHRASE read from here
- *   });
- *   // booted.b — the framework module
- *   // booted.app — the headless app instance (call .shutdown() to clean up)
+ * Boot a headless `b.createApp` instance from a data dir so a CLI
+ * script (framework subcommand or operator-written tool) can operate
+ * against the same vault + DB + audit chain the live app uses, with
+ * no HTTP listener attached. Returns `{ b, app }` where `b` is the
+ * framework module and `app` is the headless instance — caller MUST
+ * `await booted.app.shutdown()` in a `finally` so SQLite file handles
+ * and the cluster lease release.
+ *
+ * The default DB at-rest mode is `plain` because CLI runs are
+ * short-lived ops that never serve requests; encrypted-at-rest needs
+ * a tmpfs handle that wouldn't survive CLI exit anyway. Operators
+ * running against a production data dir whose DB is encrypted-at-rest
+ * pass `dbAtRest: "encrypted"` and ensure `BLAMEJS_TMPDIR` is set.
  *
- * Caller MUST call `await booted.app.shutdown()` in a `finally` so the
- * SQLite file handles + cluster lease release. The default DB at-rest
- * mode is `plain` because CLI runs are short-lived ops that never
- * serve requests; the encrypted-at-rest mode needs a tmpfs handle that
- * wouldn't survive the CLI exit anyway. Operators running against a
- * production data dir whose DB is encrypted-at-rest set
- * `dbAtRest: "encrypted"` and ensure `BLAMEJS_TMPDIR` is set.
+ * @opts
+ *   dataDir:    string   (filesystem path to the data dir; required),
+ *   vaultMode:  "wrapped" | "plaintext"   (default "wrapped" — wrapped
+ *               reads BLAMEJS_VAULT_PASSPHRASE from `opts.env`),
+ *   dbAtRest:   "plain" | "encrypted"     (default "plain"),
+ *   env:        object    (env-var bag; default process.env),
+ *
+ * @example
+ *   async function run() {
+ *     var booted;
+ *     try {
+ *       booted = await b.cliHelpers.bootApp({
+ *         dataDir:   "./data",
+ *         vaultMode: "plaintext",
+ *         env:       process.env,
+ *       });
+ *       var rows = await booted.app.db.all("SELECT count(*) AS n FROM _blamejs_audit_log");
+ *       return rows[0].n;
+ *     } finally {
+ *       if (booted) await booted.app.shutdown();
+ *     }
+ *   }
  */
 async function bootApp(opts) {
   opts = opts || {};

package/lib/cli.js

@@ -38,6 +38,7 @@ var fs = require("node:fs");
 var os = require("node:os");
 var path = require("path");
 var apiSnapshot = require("./api-snapshot");
+var argParser = require("./arg-parser");
 var auditChain = require("./audit-chain");
 var auditTools = require("./audit-tools");
 var backup = require("./backup");
@@ -75,37 +76,12 @@ function _writeLine(stream, line) {
 
 // Minimal argv parser: positional args + flag map. Supports both
 // `--flag value` and `--flag=value`. Single-dash forms (-v) treated
-// as long aliases to keep the surface predictable.
+// as long aliases to keep the surface predictable. Routed through the
+// reusable b.argParser.parseRaw primitive — every subcommand's hand-
+// written flag validation continues to read the same { pos, flags }
+// shape the cli has always exposed.
 function _parseArgs(argv) {
-  var pos = [];
-  var flags = {};
-  for (var i = 0; i < argv.length; i++) {
-    var tok = argv[i];
-    if (tok === "--") {
-      for (var j = i + 1; j < argv.length; j++) pos.push(argv[j]);
-      break;
-    }
-    if (tok.indexOf("--") === 0) {
-      var name = tok.slice(2);
-      var eq = name.indexOf("=");
-      var val;
-      if (eq !== -1) {
-        val = name.slice(eq + 1);
-        name = name.slice(0, eq);
-      } else if (i + 1 < argv.length && argv[i + 1].indexOf("--") !== 0) {
-        val = argv[++i];
-      } else {
-        val = true; // boolean flag
-      }
-      flags[name] = val;
-    } else if (tok.indexOf("-") === 0 && tok.length === 2) {
-      // -v, -h
-      flags[tok.slice(1)] = true;
-    } else {
-      pos.push(tok);
-    }
-  }
-  return { pos: pos, flags: flags };
+  return argParser.parseRaw(argv);
 }
 
 function _resolvePath(p, cwd) {

package/lib/cloud-events.js

@@ -1,41 +1,37 @@
 "use strict";
 /**
- * CloudEvents 1.0 envelope (cloudevents.io/spec/v1.0).
+ * @module b.cloudEvents
+ * @nav    Communication
+ * @title  CloudEvents
  *
- * A vendor-neutral event-format spec adopted by AWS EventBridge,
- * Knative, Azure Event Grid, Google Eventarc, Datadog, and the
- * CNCF event ecosystem. Operators wrap outbound events from
- * webhook / pubsub / queue boundaries to interop with these
- * consumers without each consumer having to learn a bespoke shape.
+ * @intro
+ *   Produce and consume webhook / pubsub / queue payloads in the
+ *   framework-neutral CNCF CloudEvents v1.0 schema
+ *   (cloudevents.io/spec/v1.0). The spec is adopted by AWS
+ *   EventBridge, Azure Event Grid, Google Eventarc, Knative, Datadog,
+ *   and the wider CNCF ecosystem — wrapping outbound events at
+ *   `b.webhook` / `b.pubsub` / `b.queue` boundaries lets operators
+ *   interop with these consumers without each consumer learning a
+ *   bespoke shape.
  *
- *   var ce = b.cloudEvents.wrap({
- *     source: "/services/orders",
- *     type:   "com.example.order.created",
- *     subject: "order/o-1234",
- *     data:    { id: "o-1234", total: 4250 },
- *   });
- *   // → {
- *   //     specversion: "1.0",
- *   //     id:          "<auto-uuid-v4>",
- *   //     source:      "/services/orders",
- *   //     type:        "com.example.order.created",
- *   //     time:        "2026-05-06T...",
- *   //     subject:     "order/o-1234",
- *   //     datacontenttype: "application/json",
- *   //     data:        { id: "o-1234", total: 4250 },
- *   //   }
- *
- *   var ce = b.cloudEvents.parse(envelope);   // throws on shape violation
- *
- * Spec compliance — REQUIRED attributes (CloudEvents §3.1):
- *   id, source, specversion, type
+ *   `wrap` produces a structured-mode envelope from operator-supplied
+ *   `source` / `type` / `subject` / `data` (and optional `extensions`),
+ *   auto-filling `id` (UUID v4) and `time` (ISO 8601). Buffer payloads
+ *   are routed to the `data_base64` field with a default
+ *   `application/octet-stream` content-type; non-Buffer payloads land
+ *   in `data` with `application/json`. `parse` validates a received
+ *   envelope against the §3.1 required-attribute set, refuses unknown
+ *   `specversion` values and the illegal `data` + `data_base64`
+ *   simultaneous form, decodes base64-mode payloads back to a Buffer,
+ *   and surfaces operator-defined extension attributes separately so
+ *   consumers can route on them without grepping the envelope.
  *
- * OPTIONAL attributes:
- *   datacontenttype, dataschema, subject, time, data, data_base64
+ *   Extension-attribute names follow the §3.1 naming rules
+ *   (lowercase ASCII alnum, 1..20 chars). Names that collide with a
+ *   spec attribute are refused.
  *
- * Operator-defined extension attributes are passed through unchanged
- * if they conform to the spec's naming rules (lowercase ASCII letters
- * + digits, length 1–20).
+ * @card
+ *   Produce and consume webhook / pubsub / queue payloads in the framework-neutral CNCF CloudEvents v1.0 schema (cloudevents.io/spec/v1.0).
  */
 
 var nodeCrypto = require("crypto");
@@ -74,6 +70,47 @@ function _genId() {
 
 // ---- wrap ----
 
+/**
+ * @primitive b.cloudEvents.wrap
+ * @signature b.cloudEvents.wrap(opts)
+ * @since     0.7.45
+ * @status    stable
+ * @related   b.cloudEvents.parse, b.webhook.signer, b.pubsub.create
+ *
+ * Produces a CloudEvents v1.0 structured-mode envelope from
+ * `opts.source` + `opts.type` (the only required inputs). `id` is
+ * auto-filled with a UUID v4 when absent; `time` is auto-filled with
+ * the current ISO 8601 timestamp. Buffer `data` is base64-encoded
+ * into `data_base64` with `application/octet-stream`; non-Buffer
+ * `data` lands in the `data` attribute with `application/json`.
+ * Extension keys must match `[a-z0-9]{1,20}` and must not collide
+ * with a spec attribute — both refusals throw `CloudEventsError` at
+ * config time.
+ *
+ * @opts
+ *   {
+ *     source:           string,         // required; URI-reference per §3.1
+ *     type:             string,         // required; reverse-DNS recommended
+ *     id?:              string,         // default UUID v4
+ *     time?:            string,         // default new Date().toISOString()
+ *     subject?:         string,
+ *     datacontenttype?: string,         // auto: application/json | application/octet-stream
+ *     dataschema?:      string,         // URI of payload schema
+ *     data?:            object|Buffer,  // Buffer routes to data_base64
+ *     extensions?:      object          // keys [a-z0-9]{1,20}, no spec collisions
+ *   }
+ *
+ * @example
+ *   var b = require("blamejs").create();
+ *   var ce = b.cloudEvents.wrap({
+ *     source:  "/services/orders",
+ *     type:    "com.example.order.created",
+ *     subject: "order/o-1234",
+ *     data:    { id: "o-1234", total: 4250 }
+ *   });
+ *   ce.specversion;
+ *   // → "1.0"
+ */
 function wrap(opts) {
   validateOpts.requireObject(opts, "cloudEvents.wrap", CloudEventsError);
   validateOpts.requireNonEmptyString(opts.source,
@@ -140,6 +177,36 @@ function wrap(opts) {
 
 // ---- parse ----
 
+/**
+ * @primitive b.cloudEvents.parse
+ * @signature b.cloudEvents.parse(envelope)
+ * @since     0.7.45
+ * @status    stable
+ * @related   b.cloudEvents.wrap, b.webhook.verifier
+ *
+ * Validates a received CloudEvents v1.0 envelope and returns a
+ * normalized record `{ specversion, id, source, type, time, subject,
+ * datacontenttype, dataschema, data, extensions }`. Throws
+ * `CloudEventsError` for missing required attributes (§3.1),
+ * unsupported `specversion`, the illegal simultaneous `data` +
+ * `data_base64` form (§3.1.1), and base64-decoding failures.
+ * Buffer-mode payloads (`data_base64`) are decoded back to a
+ * `Buffer`; operator-defined extension attributes are surfaced under
+ * `.extensions` so routing can branch on them without scanning the
+ * envelope.
+ *
+ * @example
+ *   var b = require("blamejs").create();
+ *   var record = b.cloudEvents.parse({
+ *     specversion: "1.0",
+ *     id:          "evt-1",
+ *     source:      "/services/orders",
+ *     type:        "com.example.order.created",
+ *     data:        { id: "o-1234", total: 4250 }
+ *   });
+ *   record.type;
+ *   // → "com.example.order.created"
+ */
 function parse(envelope) {
   if (!envelope || typeof envelope !== "object" || Array.isArray(envelope)) {
     throw new CloudEventsError("cloud-events/bad-envelope",