@blamejs/core 0.8.42 → 0.8.49

package/lib/ai-pref.js

@@ -1,48 +1,29 @@
 "use strict";
 /**
- * b.aiPref — IETF AIPREF Working Group Content-Usage HTTP response
- * header + robots.txt grammar + Cloudflare Content Signals Policy +
- * Pay-Per-Crawl (HTTP 402) coordination.
- *
- * IETF AIPREF (Authors / Information Providers' Preference for AI
- * Use) draft-ietf-aipref-attach-04 (deadline ⏰ 2026-08) defines a
- * machine-readable Content-Usage HTTP response header that signals
- * the operator's AI-training / AI-inference / AI-snippet preferences
- * to crawlers. Cloudflare's Content Signals Policy + Pay-Per-Crawl
- * (HTTP 402) is the de-facto baseline that Cloudflare adopted ahead
- * of the IETF spec finalizing.
- *
- * Public API:
- *
- *   b.aiPref.middleware(opts) -> middleware(req, res, next)
- *     opts:
- *       train:          "allow" | "deny" | "paid" — default "deny"
- *       infer:          "allow" | "deny" | "paid" — default "allow"
- *       snippet:        "allow" | "deny"          — default "allow"
- *       price:          { amountUsd, perTokens? } when any of
- *                       train/infer is "paid".
- *       cloudflareSignals: bool, default true — emit the Cloudflare
- *                       Content-Signals header alongside Content-Usage.
- *       robotsContext:  "default" | "<user-agent>" — emit
- *                       per-user-agent rules in robots.txt rather
- *                       than the catch-all default.
- *
- *   b.aiPref.robotsBlock(opts) -> string
- *     Returns a robots.txt block per AIPREF §3 grammar:
- *
- *       User-agent: GPTBot
- *       Content-Usage: train=deny, infer=allow, snippet=allow
- *
- *   b.aiPref.serializeHeader(opts) -> string
- *     Returns the Content-Usage HTTP response header value.
- *
- *   b.aiPref.parseHeader(value) -> { train, infer, snippet, price? }
- *     Parses an inbound Content-Usage header (used when the framework
- *     plays the role of crawler: respect declared preferences).
- *
- *   b.aiPref.refusePaidCrawl(req, res, opts)
- *     Convenience: emits HTTP 402 Payment Required with the price
- *     manifest in the Cloudflare-compatible JSON body.
+ * @module b.aiPref
+ * @nav    AI
+ * @title  Ai Pref
+ *
+ * @intro
+ *   AIPREF (RFC draft) signal — operators publish a machine-readable
+ *   preference about AI training / agent crawling / etc.
+ *
+ *   Wires three coordinating surfaces into one primitive: the IETF
+ *   AIPREF `Content-Usage` HTTP response header
+ *   (draft-ietf-aipref-attach-04, deadline 2026-08), the matching
+ *   robots.txt grammar, and Cloudflare's Content Signals Policy +
+ *   Pay-Per-Crawl (HTTP 402). Operators declare train / infer /
+ *   snippet preferences once; the middleware emits both the
+ *   `Content-Usage` header and Cloudflare's `CF-Content-Signals`
+ *   alongside.
+ *
+ *   Inbound parsing closes the loop when the framework plays the role
+ *   of crawler — `parseHeader` decodes a peer's preferences so the
+ *   caller can refuse training / pay the per-crawl price / respect a
+ *   snippet=deny.
+ *
+ * @card
+ *   AIPREF (RFC draft) signal — operators publish a machine-readable preference about AI training / agent crawling / etc.
  */
 
 var audit = require("./audit");
@@ -80,6 +61,38 @@ function _validate(opts) {
   return { train: train, infer: infer, snippet: snippet, price: opts.price || null };
 }
 
+/**
+ * @primitive b.aiPref.serializeHeader
+ * @signature b.aiPref.serializeHeader(opts)
+ * @since     0.8.44
+ * @related   b.aiPref.middleware, b.aiPref.parseHeader, b.aiPref.robotsBlock
+ *
+ * Render the AIPREF `Content-Usage` HTTP response header value from
+ * an operator preference object. Output is an RFC 8941 structured-
+ * fields list of `train=...`, `infer=...`, `snippet=...` pairs, plus
+ * `price-usd` / `per-tokens` when any axis is `paid`. Throws when the
+ * preferences are inconsistent (e.g. `train=paid` with no price).
+ *
+ * @opts
+ *   train:    "allow" | "deny" | "paid",   // default "deny"
+ *   infer:    "allow" | "deny" | "paid",   // default "allow"
+ *   snippet:  "allow" | "deny",            // default "allow"
+ *   price:    { amountUsd: number, perTokens?: number },
+ *
+ * @example
+ *   var v = b.aiPref.serializeHeader({
+ *     train:   "deny",
+ *     infer:   "allow",
+ *     snippet: "allow",
+ *   });
+ *   // → "train=deny, infer=allow, snippet=allow"
+ *
+ *   var paid = b.aiPref.serializeHeader({
+ *     train: "paid", infer: "paid", snippet: "allow",
+ *     price: { amountUsd: 0.001, perTokens: 1000 },
+ *   });
+ *   // → "train=paid, infer=paid, snippet=allow, price-usd=0.001000, per-tokens=1000"
+ */
 function serializeHeader(opts) {
   var v = _validate(opts);
   // RFC 8941 structured-fields list of token=token pairs. AIPREF §4.2.
@@ -97,6 +110,33 @@ function serializeHeader(opts) {
   return parts.join(", ");
 }
 
+/**
+ * @primitive b.aiPref.parseHeader
+ * @signature b.aiPref.parseHeader(value)
+ * @since     0.8.44
+ * @related   b.aiPref.serializeHeader, b.aiPref.middleware
+ *
+ * Parse an inbound `Content-Usage` header value into the typed
+ * preference shape. Used when the framework acts as a crawler and
+ * must respect a publisher's declared preferences. Unknown axes are
+ * dropped silently so a forward-compatible publisher can advertise
+ * future fields without breaking older clients. Throws when the
+ * value is missing or exceeds the 1024-char defensive cap.
+ *
+ * @example
+ *   var p = b.aiPref.parseHeader(
+ *     "train=deny, infer=allow, snippet=allow"
+ *   );
+ *   p.train;     // → "deny"
+ *   p.infer;     // → "allow"
+ *   p.snippet;   // → "allow"
+ *
+ *   var paid = b.aiPref.parseHeader(
+ *     "train=paid, infer=allow, snippet=allow, price-usd=0.001000, per-tokens=1000"
+ *   );
+ *   paid.price.amountUsd;   // → 0.001
+ *   paid.price.perTokens;   // → 1000
+ */
 function parseHeader(value) {
   if (typeof value !== "string" || value.length === 0) {
     throw AiPrefError.factory("BAD_HEADER", "aiPref.parseHeader: value required");
@@ -127,6 +167,35 @@ function parseHeader(value) {
   return out;
 }
 
+/**
+ * @primitive b.aiPref.robotsBlock
+ * @signature b.aiPref.robotsBlock(opts)
+ * @since     0.8.44
+ * @related   b.aiPref.serializeHeader, b.aiPref.middleware
+ *
+ * Render an AIPREF §3 robots.txt block: a `User-agent:` line followed
+ * by a `Content-Usage:` line carrying the same grammar as the HTTP
+ * header. Authors who serve robots.txt as a static file paste the
+ * output verbatim. The `userAgent` opt defaults to the catch-all `*`;
+ * pass `"GPTBot"` / `"ClaudeBot"` / etc. for per-crawler rules. UA
+ * strings are capped at 256 chars.
+ *
+ * @opts
+ *   train:     "allow" | "deny" | "paid",
+ *   infer:     "allow" | "deny" | "paid",
+ *   snippet:   "allow" | "deny",
+ *   price:     { amountUsd: number, perTokens?: number },
+ *   userAgent: string,                     // default "*"
+ *
+ * @example
+ *   var block = b.aiPref.robotsBlock({
+ *     userAgent: "GPTBot",
+ *     train:     "deny",
+ *     infer:     "allow",
+ *     snippet:   "allow",
+ *   });
+ *   // → "User-agent: GPTBot\nContent-Usage: train=deny, infer=allow, snippet=allow\n"
+ */
 function robotsBlock(opts) {
   var v = _validate(opts);
   var ua = opts.userAgent || "*";
@@ -152,6 +221,34 @@ function _cfSignalsHeader(v) {
   return parts.join("; ");
 }
 
+/**
+ * @primitive b.aiPref.middleware
+ * @signature b.aiPref.middleware(opts)
+ * @since     0.8.44
+ * @related   b.aiPref.serializeHeader, b.aiPref.refusePaidCrawl, b.aiPref.robotsBlock
+ *
+ * Build an HTTP middleware that emits `Content-Usage` (and, by
+ * default, the Cloudflare `CF-Content-Signals` mirror) on every
+ * response. Wires the operator's AI-training / inference / snippet
+ * preferences into the request lifecycle so every page advertises
+ * the same posture without per-route plumbing.
+ *
+ * @opts
+ *   train:             "allow" | "deny" | "paid",
+ *   infer:             "allow" | "deny" | "paid",
+ *   snippet:           "allow" | "deny",
+ *   price:             { amountUsd: number, perTokens?: number },
+ *   cloudflareSignals: boolean,            // default true
+ *
+ * @example
+ *   var aiPrefMw = b.aiPref.middleware({
+ *     train:   "deny",
+ *     infer:   "allow",
+ *     snippet: "allow",
+ *   });
+ *   // mount aiPrefMw on every public route — emits Content-Usage +
+ *   // CF-Content-Signals headers on each response.
+ */
 function middleware(opts) {
   var v = _validate(opts);
   var emitCf = opts.cloudflareSignals !== false;
@@ -167,6 +264,32 @@ function middleware(opts) {
   };
 }
 
+/**
+ * @primitive b.aiPref.refusePaidCrawl
+ * @signature b.aiPref.refusePaidCrawl(req, res, opts)
+ * @since     0.8.44
+ * @related   b.aiPref.middleware, b.aiPref.serializeHeader
+ *
+ * Emit HTTP 402 Payment Required with the price manifest in the
+ * Cloudflare-compatible JSON body. Operator route handlers detect
+ * an unmonetized AI crawler (via UA / signed-token absence / etc.)
+ * and call this helper to surface the price + contact channel
+ * uniformly. Audits the refusal under
+ * `aipref.paid_crawl_refused`.
+ *
+ * @opts
+ *   price:    { amountUsd: number, perTokens?: number },
+ *   contact:  string,                      // optional pricing contact
+ *
+ * @example
+ *   function handler(req, res) {
+ *     b.aiPref.refusePaidCrawl(req, res, {
+ *       price:   { amountUsd: 0.005, perTokens: 1000 },
+ *       contact: "https://example.test/ai-licensing",
+ *     });
+ *   }
+ *   // → res.statusCode === 402; body is JSON { error: "payment_required", ... }
+ */
 function refusePaidCrawl(req, res, opts) {
   if (!opts || !opts.price || typeof opts.price.amountUsd !== "number") {
     throw AiPrefError.factory("BAD_PRICE",

package/lib/api-key.js

@@ -1,56 +1,37 @@
 "use strict";
 /**
- * b.apiKey — operator-facing API-key issuance, verification, revocation,
- * and rotation.
+ * @module b.apiKey
+ * @nav    Identity
+ * @title  API Keys
  *
- *   var keys = b.apiKey.create({
- *     namespace:        "live",
- *     audit:            b.audit,                  // optional
- *     trackLastUsedAt:  false,                    // default
- *   });
- *
- *   var issued = await keys.issue({
- *     ownerId:   "user-42",
- *     scopes:    ["read:users", "write:posts"],
- *     metadata:  { name: "Mobile app v3" },
- *     expiresAt: Date.now() + b.constants.TIME.days(90),
- *   });
- *   // issued.key  — "bk_live_<idHex>_<secretHex>"  (returned ONCE)
- *   // issued.id   — "<idHex>"
- *
- *   var record = await keys.verify(req.headers["x-api-key"]);
- *   // → { id, ownerId, scopes, metadata, ... } or null
- *
- *   await keys.revoke(id);
- *   var rotated = await keys.rotate(id);          // new secret; old stops working
- *   var owned   = await keys.listForOwner("user-42");
- *
- * Token format (Stripe-style, prefix-recognizable):
- *
- *     <prefix>_<namespace>_<idHex>_<secretHex>
- *
- * Example: `bk_live_5b9e7c8a4f2d1e3a_8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d`
+ * @intro
+ *   Long-lived API token primitives — generate / verify / revoke /
+ *   rotate; sealed at rest; per-key scope + rate-limit. Tokens are
+ *   Stripe-style prefix-recognizable strings of the form
+ *   `<prefix>_<namespace>_<idHex>_<secretHex>` so a leaked credential
+ *   is identifiable on sight (secret-scanner allowlists, log-grep
+ *   for `bk_live_`).
  *
- * - prefix    operator-supplied; default "bk". Visual marker.
- * - namespace operator-supplied; lets multiple key registries coexist
- *             (e.g. "live"/"test", "v1"/"v2") without collision.
- * - idHex     opaque random hex; PRIMARY KEY component (DB lookup).
- * - secretHex opaque random hex; never re-derivable. Stored as
- *             SHA3-512 hash, constant-time-compared on verify.
+ *   Storage: framework table `_blamejs_api_keys` with sealed columns
+ *   (ownerId / scopes / metadata via cryptoField), `ownerIdHash` for
+ *   indexed `listForOwner`. Same dual-storage pattern as sessions —
+ *   local SQLite in single-node mode, external-db in cluster mode,
+ *   dispatched via cluster-storage. Hash algorithm is operator-
+ *   selectable (SHAKE256 default for high-entropy random secrets;
+ *   Argon2id available for low-entropy deployments). Visibility
+ *   defaults are ON: `auditFailures`, `auditSuccess`, and
+ *   `trackLastUsedAt` all default true so HIPAA §164.312(b) /
+ *   PCI-DSS 10.2.1 / GDPR Art. 32 trails are complete out of the
+ *   box. Operators with extreme verify-rate volume opt OUT
+ *   explicitly.
  *
- * Storage: framework table `_blamejs_api_keys` (sealed columns:
- * ownerId/scopes/metadata; ownerIdHash for indexed listForOwner).
- * Same dual-storage pattern as sessions — local SQLite in single-node
- * mode, external-db in cluster mode, dispatched via cluster-storage.
+ *   Graceful rotation moves the prior secret hash into a
+ *   `secondarySecretHash` slot with a TTL (default 7 days) so
+ *   in-flight clients survive the rotation window without coordinated
+ *   redeploy.
  *
- * Validation policy:
- *
- *   - 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)
+ * @card
+ *   Long-lived API token primitives — generate / verify / revoke / rotate; sealed at rest; per-key scope + rate-limit.
  */
 
 var crypto = require("./crypto");
@@ -179,6 +160,30 @@ function _validateIssueOpts(opts) {
 // Each part is alphanumeric so split-by-underscore is unambiguous as long
 // as prefix/namespace are validated to contain no underscores. We verify
 // that during create.
+
+/**
+ * @primitive b.apiKey.parseFormat
+ * @signature b.apiKey.parseFormat(token)
+ * @since     0.4.9
+ * @status    stable
+ * @related   b.apiKey.create
+ *
+ * Pure parser for the framework's `<prefix>_<namespace>_<idHex>_<secretHex>`
+ * token format. Returns `{ prefix, namespace, idHex, secretHex }` on
+ * a structurally-valid token, `null` otherwise. Never touches the
+ * registry — used by routing code that wants to dispatch a request
+ * to the correct registry (multi-namespace deployments) before
+ * calling `verify()`. Hex parts are not constant-time-compared here;
+ * that happens inside `verify()` against the stored hash.
+ *
+ * @example
+ *   var parts = b.apiKey.parseFormat("bk_live_5b9e7c8a4f2d1e3a_8a7b6c5d4e3f2a1b");
+ *   // → { prefix: "bk", namespace: "live", idHex: "5b9e7c8a4f2d1e3a",
+ *   //     secretHex: "8a7b6c5d4e3f2a1b" }
+ *
+ *   b.apiKey.parseFormat("not-a-token");          // → null
+ *   b.apiKey.parseFormat("bk_live_xyz_zzz");      // → null (non-hex)
+ */
 function parseFormat(token) {
   if (typeof token !== "string" || token.length === 0) return null;
   var parts = token.split("_");
@@ -209,6 +214,62 @@ function _sealForInsert(row) {
 
 // ---- Registry factory ----
 
+/**
+ * @primitive b.apiKey.create
+ * @signature b.apiKey.create(opts)
+ * @since     0.4.9
+ * @status    stable
+ * @compliance hipaa, pci-dss, gdpr, soc2
+ * @related   b.apiKey.parseFormat, b.permissions.create, b.session
+ *
+ * Build an API-key registry bound to a single `namespace`. Returns a
+ * handle exposing async `issue` / `verify` / `revoke` / `rotate` /
+ * `listForOwner` / `getById` / `purgeExpired`. State changes
+ * (`issue` / `revoke` / `rotate` / `purgeExpired`) require leader in
+ * cluster mode; reads (`verify` / `getById` / `listForOwner`) run on
+ * any node. Issued tokens contain the secret material exactly once —
+ * the registry persists only the SHAKE256 / Argon2id hash and a
+ * scrub-safe record without secrets. Operators with multiple key
+ * lifecycles (e.g. `live` / `test`) instantiate one registry per
+ * namespace.
+ *
+ * @opts
+ *   namespace:        string,            // registry namespace (required, no underscores / whitespace)
+ *   prefix:           string,            // token prefix (default "bk", no underscores)
+ *   idBytes:          number,            // bytes of id randomness (default 8 → 16 hex chars)
+ *   secretBytes:      number,            // bytes of secret randomness (default 16 → 32 hex chars)
+ *   trackLastUsedAt:  boolean,           // update lastUsedAt on verify success (default true)
+ *   auditFailures:    boolean,           // emit verify-failure audits (default true)
+ *   auditSuccess:     boolean,           // emit verify/list/get-success audits (default true)
+ *   purgeAfterMs:     number,            // age threshold for purgeExpired (default 90 days)
+ *   hashAlgo:         string,            // "shake256" (default) or "argon2id"
+ *   audit:            b.audit,           // optional audit sink
+ *   clock:            function,          // () → unix ms (test override)
+ *
+ * @example
+ *   var keys = b.apiKey.create({
+ *     namespace: "live",
+ *     audit:     b.audit,
+ *   });
+ *
+ *   var issued = await keys.issue({
+ *     ownerId:   "user-42",
+ *     scopes:    ["read:users", "write:posts"],
+ *     metadata:  { name: "Mobile app v3" },
+ *     expiresAt: Date.now() + b.constants.TIME.days(90),
+ *   });
+ *   // issued.key — "bk_live_5b9e7c8a4f2d1e3a_8a7b6c5d4e3f2a1b" (returned ONCE)
+ *
+ *   var record = await keys.verify(req.headers["x-api-key"]);
+ *   if (!record) return res.writeHead(401).end();
+ *   // → { id, ownerId, scopes, metadata, lastUsedAt, ... }
+ *
+ *   // Graceful rotation — old secret keeps working for 7 days:
+ *   var rotated = await keys.rotate(issued.id, { graceful: true });
+ *
+ *   await keys.revoke(issued.id);                  // immediate cutover
+ *   var owned = await keys.listForOwner("user-42");
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/api-snapshot.js

@@ -1,52 +1,53 @@
 "use strict";
 /**
- * api-snapshot — public API surface walker + breaking-change detector.
+ * @module b.apiSnapshot
+ * @nav    Other
+ * @title  API Snapshot
  *
- * The framework's LTS-contract enforcement at the type level. Walks
- * the framework's module exports recursively, records every member's
- * type, and compares two snapshots to find:
+ * @intro
+ *   Public-API surface walker plus breaking-change detector — the
+ *   framework's LTS-contract enforcement at the type level. Operators
+ *   capture a snapshot of the framework's `module.exports` tree,
+ *   commit it alongside the version bump, and the release workflow's
+ *   `check-api-snapshot.js` gate fails CI when any subsequent change
+ *   removes or retypes a previously-shipped public member.
  *
- *   - removed       a member present in the old snapshot but not the new
- *                   (BREAKING — fails CI)
- *   - typeChanged   a member's category flipped (function → object, etc.)
- *                   (BREAKING — fails CI)
- *   - added         a new member that wasn't in the old snapshot
- *                   (ADDITIVE — does not fail; signals the snapshot is
- *                    out-of-date and the operator should rerun capture)
+ *   Three diff classes:
  *
- *   var snap = b.apiSnapshot.capture(require("@blamejs/core"));
- *   //  { version, frameworkVersion, createdAt,
- *   //    exports: { ... nested tree ... } }
+ *     - `removed`       a member present in the old snapshot but not
+ *                       the new (BREAKING — fails CI)
+ *     - `typeChanged`   a member's category flipped, e.g. function →
+ *                       object, primitive → instance (BREAKING — fails
+ *                       CI)
+ *     - `additive`      a new member that wasn't in the old snapshot
+ *                       (informational — signals the snapshot is out
+ *                       of date and the operator should rerun capture)
  *
- *   b.apiSnapshot.write(snap, "./api-snapshot.json");
- *   var loaded = b.apiSnapshot.read("./api-snapshot.json");
+ *   Walker rules: functions record as
+ *   `{ type: "function", arity: fn.length }`; plain objects recurse
+ *   into enumerable string keys; primitives record as
+ *   `{ type: "primitive", valueType }` without capturing the literal
+ *   value (so a version-string change in `b.version` doesn't fail
+ *   CI); non-plain objects (Map, Set, Buffer, Date, RegExp, Error
+ *   instances) record as `{ type: "instance", ctorName }` without
+ *   recursion; cycles short-circuit as `{ type: "cycle" }`; depth is
+ *   capped at `opts.maxDepth` (default 8). Members whose key starts
+ *   with `_` are skipped — the framework convention for test seams
+ *   and internal helpers.
  *
- *   var diff = b.apiSnapshot.compare(loaded, snap);
- *   //  { breaking: [{ path, kind, was?, is? }],
- *   //    typeChanged: [{ path, was, is }],
- *   //    additive: [{ path, type }] }
+ *   Function-arity changes: a DECREASE in `fn.length` is breaking
+ *   (the operator removed a required parameter). An INCREASE is not
+ *   flagged because adding an optional trailing parameter is additive
+ *   to existing callers.
  *
- *   if (diff.breaking.length > 0 || diff.typeChanged.length > 0) {
- *     console.error(b.apiSnapshot.formatDiff(diff));
- *     process.exit(1);
- *   }
+ *   On-disk format: stable canonical JSON ordered as
+ *   `{ version, frameworkVersion, createdAt, exports }`. The format
+ *   version (`b.apiSnapshot.SNAPSHOT_FORMAT_VERSION`) is checked on
+ *   read so a future schema bump can't silently mis-compare against
+ *   an older baseline.
  *
- * Walker rules:
- *   - Functions record as { type: 'function', arity: fn.length }.
- *     Class constructors are still 'function' — recursive scope walks
- *     prototype only when the operator explicitly opts in via
- *     opts.includeClassPrototypes.
- *   - Plain objects recurse into their own enumerable string keys.
- *   - Primitives (string, number, boolean, null, undefined) record as
- *     { type: 'primitive', valueType: typeof v }. Specific values are
- *     NOT captured — only the type — so a version-string change in
- *     constants doesn't fail CI.
- *   - Members whose key starts with '_' are skipped (test seams,
- *     internal helpers).
- *   - Cycles are detected and short-circuit as { type: 'cycle' }.
- *   - Non-plain objects (Map, Set, Buffer, Date, RegExp, Error, etc.)
- *     are recorded as { type: 'instance', constructor: name } without
- *     recursion — they're terminal nodes.
+ * @card
+ *   Public-API surface walker plus breaking-change detector — the framework's LTS-contract enforcement at the type level.
  */
 
 var fs = require("fs");
@@ -112,6 +113,34 @@ function _walkNode(value, depth, maxDepth, seen, skipUnderscore) {
   return { type: "object", members: members };
 }
 
+/**
+ * @primitive b.apiSnapshot.capture
+ * @signature b.apiSnapshot.capture(target, opts)
+ * @since     0.1.91
+ * @status    stable
+ * @related   b.apiSnapshot.compare, b.apiSnapshot.write
+ *
+ * Walk a module's exports tree and produce a snapshot object
+ * `{ version, frameworkVersion, createdAt, exports }` suitable for
+ * round-tripping through `write` / `read`. The walk is recursive
+ * with cycle detection and a depth cap; underscore-prefixed keys
+ * are skipped by default (override with `skipUnderscore: false`).
+ * Throws `ApiSnapshotError` when the top-level target is not a plain
+ * object — class instances and runtime-built exports can't be walked
+ * by category.
+ *
+ * @opts
+ *   maxDepth:         8,             // recursion ceiling
+ *   skipUnderscore:   true,          // skip `_internal` keys
+ *   frameworkVersion: "0.8.48",      // override target.version
+ *   createdAt:        "2026-05-09T...", // pin for deterministic snapshots
+ *
+ * @example
+ *   var snap = b.apiSnapshot.capture(require("@blamejs/core"));
+ *   // → { version: 1, frameworkVersion: "0.8.48",
+ *   //     createdAt: "2026-05-09T12:00:00.000Z",
+ *   //     exports: { uuid: { type: "object", members: {...} }, ... } }
+ */
 function capture(target, opts) {
   opts = opts || {};
   if (!target || typeof target !== "object") {
@@ -135,6 +164,25 @@ function capture(target, opts) {
   };
 }
 
+/**
+ * @primitive b.apiSnapshot.write
+ * @signature b.apiSnapshot.write(snapshot, filePath)
+ * @since     0.1.91
+ * @status    stable
+ * @related   b.apiSnapshot.read, b.apiSnapshot.capture
+ *
+ * Serialize a snapshot to disk in canonical JSON form (stable
+ * `{ version, frameworkVersion, createdAt, exports }` ordering, mode
+ * 0o644). Returns the filePath written. Throws `ApiSnapshotError`
+ * when the snapshot or path is missing — the release workflow
+ * surfaces typos at commit time instead of writing to an unintended
+ * location.
+ *
+ * @example
+ *   var snap = b.apiSnapshot.capture(require("@blamejs/core"));
+ *   var written = b.apiSnapshot.write(snap, "./api-snapshot.json");
+ *   // → "./api-snapshot.json"
+ */
 function write(snapshot, filePath) {
   if (!snapshot || typeof snapshot !== "object") {
     throw new ApiSnapshotError("api-snapshot/bad-snapshot",
@@ -155,6 +203,28 @@ function write(snapshot, filePath) {
   return filePath;
 }
 
+/**
+ * @primitive b.apiSnapshot.read
+ * @signature b.apiSnapshot.read(filePath)
+ * @since     0.1.91
+ * @status    stable
+ * @related   b.apiSnapshot.write, b.apiSnapshot.compare
+ *
+ * Load a snapshot from disk and validate its envelope. Throws
+ * `ApiSnapshotError` with a specific code on each failure mode —
+ * `api-snapshot/missing` (no file), `api-snapshot/read-failed`
+ * (I/O error), `api-snapshot/bad-json` (parse failure), or
+ * `api-snapshot/bad-version` (format-version mismatch — the
+ * baseline was written by a different snapshot major) — so the
+ * release workflow can surface a precise reason instead of a
+ * generic "snapshot broken" message.
+ *
+ * @example
+ *   var loaded = b.apiSnapshot.read("./api-snapshot.json");
+ *   var current = b.apiSnapshot.capture(require("@blamejs/core"));
+ *   var diff = b.apiSnapshot.compare(loaded, current);
+ *   // → { breaking: [], additive: [], typeChanged: [] }
+ */
 function read(filePath) {
   if (typeof filePath !== "string" || filePath.length === 0) {
     throw new ApiSnapshotError("api-snapshot/bad-path",
@@ -277,6 +347,31 @@ function _walkCompare(oldNode, newNode, prefix, breaking, additive, typeChanged)
   // cycle / deep — terminal, nothing more to compare
 }
 
+/**
+ * @primitive b.apiSnapshot.compare
+ * @signature b.apiSnapshot.compare(oldSnapshot, newSnapshot)
+ * @since     0.1.91
+ * @status    stable
+ * @related   b.apiSnapshot.formatDiff, b.apiSnapshot.capture
+ *
+ * Diff two snapshots and return
+ * `{ breaking, additive, typeChanged }`. `breaking` carries every
+ * member that was removed, retyped, lost arity, swapped its
+ * constructor name, or changed primitive `valueType`; the release
+ * workflow exits non-zero when this list is non-empty. `additive`
+ * lists new members (informational — operator should rerun
+ * `capture` and commit the refreshed baseline). `typeChanged` is a
+ * subset of `breaking` surfaced separately for easier triage.
+ *
+ * @example
+ *   var loaded = b.apiSnapshot.read("./api-snapshot.json");
+ *   var current = b.apiSnapshot.capture(require("@blamejs/core"));
+ *   var diff = b.apiSnapshot.compare(loaded, current);
+ *   if (diff.breaking.length > 0) {
+ *     console.error(b.apiSnapshot.formatDiff(diff));
+ *     process.exit(1);
+ *   }
+ */
 function compare(oldSnapshot, newSnapshot) {
   if (!oldSnapshot || !oldSnapshot.exports) {
     throw new ApiSnapshotError("api-snapshot/bad-snapshot",
@@ -298,6 +393,28 @@ function compare(oldSnapshot, newSnapshot) {
   return { breaking: breaking, additive: additive, typeChanged: typeChanged };
 }
 
+/**
+ * @primitive b.apiSnapshot.formatDiff
+ * @signature b.apiSnapshot.formatDiff(diff)
+ * @since     0.1.91
+ * @status    stable
+ * @related   b.apiSnapshot.compare
+ *
+ * Render a diff result from `compare` into a human-readable
+ * multi-line string suitable for `console.error` in a CI script.
+ * Breaking entries are flagged with `-`, additive entries with `+`,
+ * and the `was` / `is` types are JSON-quoted so the operator can
+ * paste the line verbatim into the migration notes.
+ *
+ * @example
+ *   var diff = {
+ *     breaking: [{ path: "uuid.v3", kind: "removed", was: "function" }],
+ *     additive: [{ path: "uuid.v8", type: "function" }],
+ *     typeChanged: [],
+ *   };
+ *   var rendered = b.apiSnapshot.formatDiff(diff);
+ *   // → "[api-snapshot] BREAKING (1):\n  - uuid.v3 (removed) was=\"function\"\n..."
+ */
 function formatDiff(diff) {
   if (!diff || typeof diff !== "object") {
     throw new ApiSnapshotError("api-snapshot/bad-diff",