@blamejs/core 0.8.43 → 0.8.49

package/lib/network.js

@@ -1,5 +1,36 @@
 "use strict";
+/**
+ * @module b.network
+ * @featured true
+ * @nav    Network
+ * @title  Network
+ *
+ * @intro
+ *   Framework network helpers — DNS-over-HTTPS dispatch, TLS
+ *   configuration, OCSP/CT validation, NTP/NTS-KE bootstrap.
+ *
+ *   `b.network` is the umbrella facade over the framework's outbound-
+ *   network surface: DNS (default DoH on, optional DoT, lookup cache
+ *   with TTL bound), TLS trust store (CA bundle / system trust /
+ *   ignored-cert opt-in), proxy resolution from `HTTP_PROXY` /
+ *   `HTTPS_PROXY` / `NO_PROXY`, NTP / NTS-KE drift checks, SMTP
+ *   policy (MTA-STS / DANE / TLS-RPT), heartbeat watchdog, byte
+ *   quota, SSRF allowlist, and socket-level defaults
+ *   (TCP_NODELAY / SO_KEEPALIVE).
+ *
+ *   `bootFromEnv` reads BLAMEJS_* environment variables once at
+ *   startup and applies the union to the live facade — operators
+ *   wire it from a process-supervisor's env without touching code.
+ *   `snapshot` returns a redacted view of the current configuration
+ *   for the operations dashboard. `applyToSocket` is the per-socket
+ *   tuning hook for primitives building their own server (`tls`,
+ *   `wsServer`, etc.).
+ *
+ * @card
+ *   Framework network helpers — DNS-over-HTTPS dispatch, TLS configuration, OCSP/CT validation, NTP/NTS-KE bootstrap.
+ */
 
+var byteQuota = require("./network-byte-quota");
 var ntpCheck = require("./ntp-check");
 var nts      = require("./network-nts");
 var dns      = require("./network-dns");
@@ -72,6 +103,28 @@ function _socketDefaults() {
   };
 }
 
+/**
+ * @primitive b.network.applyToSocket
+ * @signature b.network.applyToSocket(socket)
+ * @since     0.7.68
+ * @related   b.network.bootFromEnv, b.network.snapshot
+ *
+ * Apply the framework's socket defaults (`TCP_NODELAY`,
+ * `SO_KEEPALIVE` + initial-delay) to a freshly-created
+ * `net.Socket` / `tls.TLSSocket`. Best-effort: a socket that has
+ * already errored, lacks the setter methods, or rejects the call
+ * is left as-is. Returns the same socket. Used by primitives that
+ * build their own server (`b.tls`, `b.wsServer`, `b.smtp`) so
+ * every socket on the wire follows the same tuning.
+ *
+ * @example
+ *   var net = require("net");
+ *   var s   = new net.Socket();
+ *   var ret = b.network.applyToSocket(s);
+ *   ret === s;
+ *   // → true
+ *   s.destroy();
+ */
 function applyToSocket(socket) {
   if (!socket) return socket;
   try {
@@ -103,6 +156,34 @@ var ntpFacade = {
   nts:            nts,
 };
 
+/**
+ * @primitive b.network.bootFromEnv
+ * @signature b.network.bootFromEnv(opts)
+ * @since     0.7.68
+ * @related   b.network.snapshot, b.network.applyToSocket
+ *
+ * Read `BLAMEJS_*` environment variables once and apply the union to
+ * the live network facade. Recognised keys cover NTP servers /
+ * timeout / drift thresholds, DNS servers / result-order / family /
+ * lookup-timeout / cache-TTL / DoH URL or provider / DoT host+port,
+ * `HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`, extra-CA file or
+ * directory, `BLAMEJS_USE_SYSTEM_TRUST`, and the socket
+ * `TCP_NODELAY` / `SO_KEEPALIVE` defaults. Returns an `applied`
+ * report — exactly which keys took effect. Audits
+ * `network.boot.from_env` unless `opts.audit:false`.
+ *
+ * @opts
+ *   env:    object,    // default process.env — pass a fixture object in tests
+ *   audit:  boolean,   // default true — emit `network.boot.from_env`
+ *
+ * @example
+ *   var applied = b.network.bootFromEnv({
+ *     env:   { BLAMEJS_NTP_SERVERS: "time.cloudflare.com,time.google.com" },
+ *     audit: false,
+ *   });
+ *   applied.ntp.servers;
+ *   // → 2
+ */
 function bootFromEnv(opts) {
   opts = opts || {};
   validateOpts(opts, ["env", "audit"], "network.bootFromEnv");
@@ -181,6 +262,24 @@ function bootFromEnv(opts) {
   return applied;
 }
 
+/**
+ * @primitive b.network.snapshot
+ * @signature b.network.snapshot()
+ * @since     0.7.68
+ * @related   b.network.bootFromEnv
+ *
+ * Return a redacted snapshot of the network facade's current
+ * configuration: NTP servers + drift thresholds, DNS state (servers,
+ * result-order, family, DoH/DoT, cache TTL), proxy resolution, TLS
+ * trust-store size + system-trust flag, heartbeat statuses, and
+ * socket defaults. Cheap; safe to call from a `/healthz` or
+ * operations endpoint. No secrets are returned.
+ *
+ * @example
+ *   var snap = b.network.snapshot();
+ *   typeof snap.tls.caCount;
+ *   // → "number"
+ */
 function snapshot() {
   return {
     ntp: {
@@ -228,6 +327,10 @@ module.exports = {
     tlsRpt:    smtpPolicy.tlsRpt,
   },
   allowlist:  { create: ssrfGuard.createAllowlist },
+  byteQuota: {
+    create: byteQuota.create,
+    ByteQuotaError: byteQuota.ByteQuotaError,
+  },
   socket: {
     setDefaultNoDelay:   _setSocketNoDelay,
     setDefaultKeepAlive: _setSocketKeepAlive,

package/lib/notify.js

@@ -1,50 +1,43 @@
 "use strict";
 /**
- * b.notify — generic notification dispatcher.
+ * @module b.notify
+ * @nav    Communication
+ * @title  Notify
  *
- * Composes existing primitives — retry/backoff (b.retry), per-call
- * timeout (b.safeAsync.withTimeout), per-channel circuit breaker
- * (b.retry.CircuitBreaker), span+counter wrapping
- * (b.observability.tap), audit emission (b.audit.safeEmit),
- * 5 W's actor context (b.requestHelpers.extractActorContext), URL
- * validation (b.safeUrl.parse), HTTP I/O (b.httpClient.request), PII
- * redaction (b.redact.redact). Notify never re-implements any of these
- * — its job is to coordinate them around a transport abstraction.
+ * @intro
+ *   Pluggable notification dispatcher. One contract — `{ name, send }`
+ *   — adapts any transport (Slack incoming-webhook, Discord, Microsoft
+ *   Teams, PagerDuty, Twilio, FCM / APNs operator shim, plain
+ *   developer log) and the dispatcher coordinates retry / timeout /
+ *   circuit-breaker / observability / audit / PII redaction around it.
  *
- *   var notify = b.notify.create({
- *     channels: {
- *       slack: b.notify.transports.httpJson({ url: process.env.SLACK_HOOK }),
- *       sms:   operatorTwilioShim,
- *       log:   b.notify.transports.log(),
- *     },
- *     audit: b.audit,
- *   });
- *
- *   await notify.send({ channel: "slack", message: { text: "Hello" } });
+ *   Composition over reinvention: every cross-cutting concern routes
+ *   through an existing primitive — `b.retry.withRetry` for backoff +
+ *   classification, `b.safeAsync.withTimeout` for per-call timeouts,
+ *   `b.retry.CircuitBreaker` for per-channel breakers, `b.observability.
+ *   tap` for span+counter wrapping, `b.audit.safeEmit` for audit rows
+ *   (drop-silent on transport failure — observability sinks must not
+ *   crash send), `b.requestHelpers.extractActorContext` for the 5 W's,
+ *   `b.safeUrl.parse` + `b.httpClient.request` for HTTP I/O,
+ *   `b.redact.redact` for default PII scrubbing of message contents
+ *   before they hit the audit chain.
  *
- * Transport contract:
+ *   Built-in transports: `httpJson` (POST JSON / form to a URL — the
+ *   workhorse for Slack / Discord / generic incoming-webhook
+ *   integrations, with optional `b.webhook.signer` injection),
+ *   `log` (fire-and-forget developer logger via `b.log`),
+ *   `test` (captures sends to `.sent[]` for fixture inspection).
+ *   Operators bring their own SDK shims for Twilio / FCM / APNs /
+ *   Slack-API (the framework intentionally ships no vendor SDKs).
  *
- *   {
- *     name:    "slack",
- *     send:    async function (message, sendOpts) {
- *       // Returns { id?, status, attempts?, durationMs? }
- *       // Throws on permanent failure. For transient failures, throw
- *       // with err.statusCode in b.retry.RETRYABLE_HTTP_STATUS or
- *       // err.code in b.retry.RETRYABLE_NET_ERRORS — retry classifies
- *       // them automatically. Operators can also set err.transient =
- *       // true for shapes outside that classification.
- *     },
- *   }
+ *   Out of scope by design: template rendering (use `b.template`),
+ *   recipient preferences (operator concern), replacing `b.mail`
+ *   (SMTP / MIME stays its own primitive), replacing
+ *   `b.websocketChannels` (transient pub/sub vs retry-on-fail
+ *   delivery).
  *
- * What this primitive intentionally does NOT do (per scope):
- *   - Ship vendor SDKs (Twilio / FCM / APNs / Slack-API): operator brings
- *     transports; the framework provides the contract + httpJson +
- *     log + test built-ins.
- *   - Render templates / handle i18n: operator uses b.template + b.i18n.
- *   - Track recipient preferences: operator app concern.
- *   - Replace b.mail (SMTP/MIME stays its own primitive).
- *   - Replace b.websocketChannels (different abstraction —
- *     transient pub/sub, not retry-on-fail delivery).
+ * @card
+ *   Pluggable notification dispatcher.
  */
 
 var lazyRequire = require("./lazy-require");
@@ -162,9 +155,44 @@ function _validateCreateOpts(opts) {
 
 // ---- Built-in transports ----
 
-// httpJson — POST JSON to a URL via b.httpClient. Default `transient`
-// classifier defers to b.retry.isRetryable so HTTP/network classification
-// matches the rest of the framework.
+/**
+ * @primitive b.notify.transports.httpJson
+ * @signature b.notify.transports.httpJson(opts)
+ * @since     0.6.0
+ * @status    stable
+ * @related   b.notify.create, b.webhook.signer
+ *
+ * Built-in transport that POSTs the message as JSON (or
+ * `application/x-www-form-urlencoded`) to a URL via `b.httpClient.
+ * request`. Validates the URL at create time so bad URLs surface at
+ * boot, not at first send. Optional `signing` slot accepts any object
+ * with a `sign(body) → headers | { headers }` function — drop a
+ * `b.webhook.signer` straight in for HMAC / PQC signed deliveries.
+ * The default success classifier accepts HTTP 2xx; non-success
+ * statuses throw a plain `Error` with `statusCode` set so
+ * `b.retry.isRetryable` classifies the response (429 / 503 / network
+ * errors retry; permanent rejections don't).
+ *
+ * @opts
+ *   url:           string,                              // required
+ *   method:        "POST" | "PUT" | "PATCH",            // default "POST"
+ *   bodyFormat:    "json" | "form",                     // default "json"
+ *   headers:       { [k]: string },
+ *   signing:       { sign(body) => headers | { headers } },
+ *   successStatus: function (status) => boolean,
+ *   allowHttp:     boolean,                             // default false (HTTPS-only)
+ *   allowInternal: boolean,
+ *   httpClient:    object,                              // override b.httpClient
+ *   name:          string,                              // for audit + logs
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var slack = b.notify.transports.httpJson({
+ *     url:  "https://hooks.slack.com/services/T0/B0/X",
+ *     name: "slack",
+ *   });
+ *   // → { name: "slack", send: async function (message, sendOpts) { ... } }
+ */
 function httpJson(opts) {
   if (!opts || typeof opts !== "object") {
     throw _err("BAD_OPT", "notify.transports.httpJson: opts must be { url, ... }");
@@ -293,6 +321,49 @@ function testTransport() {
 
 // ---- Public create ----
 
+/**
+ * @primitive b.notify.create
+ * @signature b.notify.create(opts)
+ * @since     0.6.0
+ * @status    stable
+ * @compliance soc2, gdpr
+ * @related   b.notify.transports.httpJson
+ *
+ * Build a dispatcher bound to a set of named channels. Returns
+ * `{ send, sendBatch, queue, addChannel, channels, transport }`:
+ * `send` delivers one message through one channel with the full retry /
+ * timeout / breaker / span+counter / audit stack; `sendBatch` settles
+ * each input independently so one channel down doesn't fail the rest;
+ * `queue` enqueues onto a `b.queue` handle for out-of-band delivery;
+ * `addChannel` registers a new channel post-construction;
+ * `channels()` lists registered names; `transport(name)` exposes the
+ * raw transport handle for diagnostics. Each channel entry is either
+ * a transport object directly (`{ send, name? }`) or a config wrapper
+ * (`{ transport, retry?, breaker?, timeoutMs?, serialize? }`) so
+ * operators tune retry / breaker / timeout / serialize per channel.
+ *
+ * @opts
+ *   channels:         { [name]: transport | { transport, retry?, breaker?, timeoutMs?, serialize? } },
+ *   audit:            object,                          // b.audit handle
+ *   auditSuccess:     boolean,                         // default true
+ *   auditFailures:    boolean,                         // default true
+ *   redact:           function (message) => any,       // default b.redact.redact
+ *   defaultTimeoutMs: number,                          // default 30s, 0 disables
+ *   defaultRetry:     object,                          // b.retry.withRetry opts
+ *   defaultBreaker:   object,                          // b.retry.CircuitBreaker opts
+ *   queue:            { enqueue(name, payload), registerHandler? },
+ *   clock:            function () => number,           // ms
+ *
+ * @example
+ *   var b = require("@blamejs/core");
+ *   var notify = b.notify.create({
+ *     channels: {
+ *       slack: b.notify.transports.httpJson({ url: "https://hooks.slack.com/services/T0/B0/X" }),
+ *       log:   b.notify.transports.log(),
+ *     },
+ *   });
+ *   // → { send, sendBatch, queue, addChannel, channels, transport }
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, [

package/lib/ntp-check.js

@@ -1,29 +1,48 @@
 "use strict";
 /**
- * Minimal SNTP client for boot-time clock-drift verification.
+ * @module b.ntpCheck
+ * @nav    Production
+ * @title  NTP Check
  *
- * Why: the audit chain's monotonicCounter orders events deterministically
- * even if the wall clock jumps, but recordedAt is the human-readable
- * timestamp auditors will rely on. A clock that's silently off by hours
- * (container with no RTC sync, NTP daemon stopped) makes the audit trail
- * misleading.
+ * @intro
+ *   Boot-time clock-drift verification against an external NTP / NTS-KE
+ *   reference. The audit chain's `monotonicCounter` orders events
+ *   deterministically even when the wall clock jumps, but `recordedAt`
+ *   is the human-readable timestamp auditors rely on — a clock silently
+ *   off by hours (container with no RTC sync, NTP daemon stopped)
+ *   makes the audit trail misleading without ever surfacing as an
+ *   error.
  *
- * What this does:
- *   - Sends a single SNTPv4 query to a configured server (default
- *     pool.ntp.org) over UDP port 123.
- *   - Computes drift = (server's transmit timestamp) - (local clock).
- *   - Returns the drift in milliseconds.
+ *   What this does: sends a single SNTPv4 query over UDP/123 (RFC 5905)
+ *   to one or more configured servers, computes drift as
+ *   `serverTransmit - localMidpoint` (round-trip-corrected), returns
+ *   the drift in milliseconds. Falls through a server list in order;
+ *   the first success wins.
  *
- * What this does NOT do:
- *   - Continuous synchronization (use the OS NTP daemon for that).
- *   - Authenticated NTP (NTS, autokey).
- *   - Querying multiple servers and taking median (single-shot only).
+ *   What this does NOT do: continuous synchronization (the host OS's
+ *   NTP daemon does that), authenticated NTP / NTS / autokey (the
+ *   external reference is trust-on-first-query), or median-of-N
+ *   server reconciliation (single-shot only).
  *
- * The framework's policy in db.init():
- *   - drift |x| < 5min        → log info, continue
- *   - drift |x| in [5min,1hr) → log warning, continue
- *   - drift |x| >= 1hr        → log fatal, exit (BLAMEJS_NTP_STRICT=1) or warn
- *   - NTP unreachable         → log warning, continue (network may not allow UDP/123)
+ *   Policy thresholds at boot — wired into `b.db.init`:
+ *
+ *     drift |x| < warnMs (5 min default)        → info, continue
+ *     drift |x| in [warnMs, fatalMs)            → warning, continue
+ *     drift |x| >= fatalMs (1 hr default)       → refuse to boot
+ *                                                 (BLAMEJS_NTP_STRICT=1)
+ *     NTP unreachable                           → warning, continue
+ *                                                 (network may not allow
+ *                                                 UDP/123 outbound)
+ *
+ *   `b.ntpCheck.monitor` runs the same check on a recurring interval
+ *   after boot and emits `system.ntp.checked` /
+ *   `system.ntp.drift_warn` / `system.ntp.drift_fatal` /
+ *   `system.ntp.unreachable` audit events plus an `ntp.drift_ms`
+ *   observability gauge — so silent clock drift mid-flight surfaces
+ *   in the same evidence stream as boot drift.
+ *
+ * @card
+ *   Boot-time clock-drift verification against an external NTP / NTS-KE reference.
  */
 var dgram = require("dgram");
 var C = require("./constants");
@@ -50,6 +69,32 @@ var thresholds = {
   fatalMs: DEFAULT_DRIFT_FATAL_MS,
 };
 
+/**
+ * @primitive b.ntpCheck.setThresholds
+ * @signature b.ntpCheck.setThresholds(opts)
+ * @since     0.7.30
+ * @status    stable
+ * @related   b.ntpCheck.getThresholds, b.ntpCheck.bootCheck
+ *
+ * Override the warn / fatal drift thresholds applied by `bootCheck`
+ * and `monitor`. Validates that both values are non-negative finite
+ * numbers and that `warnMs <= fatalMs` (a fatal floor below the
+ * warning threshold would mean every warning is also fatal — likely
+ * a typo). Throws `TypeError` on bad shapes and `RangeError` on the
+ * ordering invariant.
+ *
+ * @opts
+ *   warnMs:  300000,    // ms; absolute drift at-or-above this logs warn
+ *   fatalMs: 3600000,   // ms; absolute drift at-or-above this refuses boot
+ *
+ * @example
+ *   b.ntpCheck.setThresholds({
+ *     warnMs:  60000,
+ *     fatalMs: 600000,
+ *   });
+ *   var t = b.ntpCheck.getThresholds();
+ *   // → { warnMs: 60000, fatalMs: 600000 }
+ */
 function setThresholds(opts) {
   opts = opts || {};
   if (opts.warnMs !== undefined) {
@@ -70,6 +115,21 @@ function setThresholds(opts) {
   }
 }
 
+/**
+ * @primitive b.ntpCheck.getThresholds
+ * @signature b.ntpCheck.getThresholds()
+ * @since     0.7.30
+ * @status    stable
+ * @related   b.ntpCheck.setThresholds
+ *
+ * Read the currently-effective warn / fatal drift thresholds. Returns
+ * a fresh object so mutating the result doesn't accidentally rewrite
+ * framework state.
+ *
+ * @example
+ *   var t = b.ntpCheck.getThresholds();
+ *   // → { warnMs: 300000, fatalMs: 3600000 }
+ */
 function getThresholds() {
   return { warnMs: thresholds.warnMs, fatalMs: thresholds.fatalMs };
 }
@@ -80,11 +140,29 @@ function _resetThresholdsForTest() {
 }
 
 /**
- * Query an NTP server once. Resolves with { driftMs, serverTimeMs } or
- * rejects with { code, message } where code is one of:
- *   'ntp/timeout'   — server didn't reply within timeoutMs
- *   'ntp/refused'   — DNS/connection error
- *   'ntp/bad-reply' — packet structure wrong
+ * @primitive b.ntpCheck.querySingle
+ * @signature b.ntpCheck.querySingle(server, opts)
+ * @since     0.0.7
+ * @status    stable
+ * @related   b.ntpCheck.checkDrift, b.ntpCheck.bootCheck
+ *
+ * Send one SNTPv4 query to a named server over UDP/123 and resolve
+ * with `{ driftMs, serverTimeMs, server }` (round-trip-corrected
+ * drift). Rejects with `{ code, message }` where `code` is one of
+ * `ntp/timeout` (no reply within `timeoutMs`), `ntp/refused`
+ * (DNS / connection error), `ntp/bad-reply` (packet too short), or
+ * `ntp/unsynchronized` (Stratum-16 peer with zero transmit
+ * timestamp). IPv4 / IPv6 socket family is selected from the host
+ * literal so an `fd00::...` server doesn't fail with EINVAL.
+ *
+ * @opts
+ *   port:      123,    // UDP port (almost always 123)
+ *   timeoutMs: 3000,   // single-query timeout
+ *
+ * @example
+ *   b.ntpCheck.querySingle("time.cloudflare.com", { timeoutMs: 2000 })
+ *     .then(function (r) { console.log("drift", r.driftMs, "ms"); })
+ *     .catch(function (e) { console.error("ntp", e.code, e.message); });
  */
 function querySingle(server, opts) {
   opts = opts || {};
@@ -165,8 +243,28 @@ function querySingle(server, opts) {
 }
 
 /**
- * Try each server in turn; return the first successful drift measurement.
- * Resolves null if all servers fail (caller decides whether that's fatal).
+ * @primitive b.ntpCheck.checkDrift
+ * @signature b.ntpCheck.checkDrift(opts)
+ * @since     0.0.7
+ * @status    stable
+ * @related   b.ntpCheck.querySingle, b.ntpCheck.bootCheck
+ *
+ * Walk a server list in order; resolve with the first successful
+ * drift measurement (`{ driftMs, serverTimeMs, server }`). When
+ * every server in the list fails, resolves with
+ * `{ driftMs: null, error }` so the caller — typically `bootCheck` —
+ * can decide whether unreachable NTP is fatal or a soft warning.
+ *
+ * @opts
+ *   servers:   ["time.cloudflare.com", "pool.ntp.org"],
+ *   port:      123,
+ *   timeoutMs: 3000,
+ *
+ * @example
+ *   var result = await b.ntpCheck.checkDrift({
+ *     servers: ["time.cloudflare.com", "pool.ntp.org"],
+ *   });
+ *   // → { driftMs: 12, serverTimeMs: 1714694400000, server: "time.cloudflare.com" }
  */
 async function checkDrift(opts) {
   opts = opts || {};
@@ -183,9 +281,37 @@ async function checkDrift(opts) {
 }
 
 /**
- * Boot-time check that integrates with the framework's logging policy.
- * Returns a result object with { ok, driftMs, severity, message }.
- * Caller (db.init) decides whether to exit.
+ * @primitive b.ntpCheck.bootCheck
+ * @signature b.ntpCheck.bootCheck(opts)
+ * @since     0.0.7
+ * @status    stable
+ * @related   b.ntpCheck.checkDrift, b.ntpCheck.monitor, b.ntpCheck.setThresholds
+ *
+ * Boot-time clock-drift check that integrates with the framework's
+ * logging policy. Resolves with
+ * `{ ok, severity, driftMs, server, message }` where `severity` is
+ * `info` / `warning` / `fatal`. The framework's `b.db.init` calls
+ * this and refuses to boot when `ok === false` and the operator has
+ * set `BLAMEJS_NTP_STRICT=1`. NTP unreachable returns
+ * `severity: "warning"` (network may not allow UDP/123 outbound) so
+ * the boot doesn't fail closed without operator intent.
+ *
+ * @opts
+ *   servers:      ["time.cloudflare.com", "pool.ntp.org"],
+ *   port:         123,
+ *   timeoutMs:    3000,
+ *   driftWarnMs:  300000,    // override registered warn threshold
+ *   driftFatalMs: 3600000,   // override registered fatal threshold
+ *
+ * @example
+ *   var result = await b.ntpCheck.bootCheck({
+ *     servers:      ["time.cloudflare.com"],
+ *     driftWarnMs:  60000,
+ *     driftFatalMs: 600000,
+ *   });
+ *   // → { ok: true, severity: "info", driftMs: 12,
+ *   //     server: "time.cloudflare.com",
+ *   //     message: "clock drift +12ms from time.cloudflare.com" }
  */
 async function bootCheck(opts) {
   opts = opts || {};
@@ -232,27 +358,42 @@ async function bootCheck(opts) {
   };
 }
 
-// Periodic drift monitor — runs checkDrift on a schedule and emits
-// audit + observability events on threshold crossings. Returns a
-// handle with `.stop()` for graceful shutdown.
-//
-//   var mon = b.ntpCheck.monitor({
-//     intervalMs:    C.TIME.minutes(15),
-//     servers:       ["time.cloudflare.com", "pool.ntp.org"],
-//     driftWarnMs:   C.TIME.seconds(2),
-//     driftFatalMs:  C.TIME.seconds(30),
-//     onDrift: function (result) { /* operator hook — drift > warn */ },
-//   });
-//   ...
-//   await mon.stop();
-//
-// Audit emissions:
-//   system.ntp.checked     — every check, success or fail
-//   system.ntp.drift_warn  — drift exceeds warn threshold
-//   system.ntp.drift_fatal — drift exceeds fatal threshold
-//   system.ntp.unreachable — every server in the list failed to respond
-//
-// Observability events: ntp.drift_ms (gauge) on every successful check.
+/**
+ * @primitive b.ntpCheck.monitor
+ * @signature b.ntpCheck.monitor(opts)
+ * @since     0.7.30
+ * @status    stable
+ * @related   b.ntpCheck.bootCheck, b.audit.safeEmit, b.observability.safeEvent
+ *
+ * Periodic drift monitor — runs `bootCheck` on a recurring interval
+ * and emits audit + observability events on threshold crossings.
+ * Returns a handle with `.stop()` for graceful shutdown. Audit
+ * emissions: `system.ntp.checked` on every tick,
+ * `system.ntp.drift_warn` and `system.ntp.drift_fatal` on threshold
+ * crossings, `system.ntp.unreachable` when every server in the list
+ * failed. Observability gauge `ntp.drift_ms` rides every successful
+ * check. The optional `onDrift` hook fires only when `severity`
+ * is `warning` or `fatal`, so operators can page on drift without
+ * inspecting every healthy tick.
+ *
+ * @opts
+ *   intervalMs:   900000,                            // tick cadence
+ *   servers:      ["time.cloudflare.com", "pool.ntp.org"],
+ *   driftWarnMs:  2000,
+ *   driftFatalMs: 30000,
+ *   audit:        true,                              // emit audit events
+ *   onDrift:      function (result) {},              // operator hook
+ *
+ * @example
+ *   var mon = b.ntpCheck.monitor({
+ *     intervalMs:   900000,
+ *     servers:      ["time.cloudflare.com", "pool.ntp.org"],
+ *     driftWarnMs:  2000,
+ *     driftFatalMs: 30000,
+ *     onDrift: function (r) { console.warn("ntp drift", r.driftMs); },
+ *   });
+ *   await mon.stop();
+ */
 function monitor(opts) {
   opts = opts || {};
   var intervalMs = opts.intervalMs || C.TIME.minutes(15);