@blamejs/core 0.15.12 → 0.15.14

package/lib/object-store/sigv4-bucket-ops.js

@@ -50,6 +50,7 @@
  * BUCKET_ALREADY_OWNED, BUCKET_NOT_EMPTY, etc.).
  */
 var nodeCrypto = require("node:crypto");
+var safeBuffer = require("../safe-buffer");
 var C = require("../constants");
 var requestHelpers = require("../request-helpers");
 var sigv4 = require("./sigv4");
@@ -403,7 +404,7 @@ function _validateObjectKey(key) {
   if (typeof key !== "string" || key.length === 0) {
     throw _err("INVALID_KEY", "object key must be a non-empty string", true);
   }
-  if (key.length > C.BYTES.kib(1)) {
+  if (safeBuffer.byteLengthOf(key) > C.BYTES.kib(1)) {
     throw _err("INVALID_KEY", "object key exceeds 1024 bytes (S3 limit)", true);
   }
 }

package/lib/object-store/sigv4.js

@@ -25,11 +25,9 @@
  */
 var nodeCrypto = require("node:crypto");
 var { URL } = require("node:url");
-var { Readable } = require("node:stream");
 var safeXml = require("../parsers/safe-xml");
 var sharedRequest = require("./http-request");
 var C = require("../constants");
-var numericBounds = require("../numeric-bounds");
 var requestHelpers = require("../request-helpers");
 var { ObjectStoreError } = require("../framework-error");
 var safeUrl = require("../safe-url");
@@ -66,12 +64,6 @@ function _arrayify(value) {
 var SERVICE = "s3";
 var ALGORITHM = "AWS4-HMAC-SHA256";
 
-// Presigned-URL expiry bounds. The SigV4 spec caps query-string-signed
-// URLs at 7 days; below 1 second is effectively unsignable.
-var PRESIGN_DEFAULT_EXPIRES_SECONDS = C.TIME.minutes(15) / C.TIME.seconds(1); // 15 minutes
-var PRESIGN_MAX_EXPIRES_SECONDS     = C.TIME.days(7)     / C.TIME.seconds(1); // 7 days (SigV4 hard cap)
-var PRESIGN_MIN_EXPIRES_SECONDS     = 1;
-
 var _err = ObjectStoreError.factory;
 
 // ---- SigV4 primitives ----
@@ -640,7 +632,7 @@ function create(config) {
   }
 
   function getStream(key, opts) {
-    return Readable.from(get(key, opts));
+    return sharedRequest.promiseToStream(get(key, opts));
   }
 
   // getResponse(key, opts?) — full-fidelity GET. Returns
@@ -658,35 +650,16 @@ function create(config) {
     // param is in the SigV4 canonical request.
     if (opts.versionId) url.searchParams.set("versionId", opts.versionId);
     var headers = _makeSigned("GET", url, sha256Hex(Buffer.alloc(0)));
-    if (opts.range) {
-      headers["Range"] = "bytes=" + opts.range.start + "-" + opts.range.end;
-    }
-    if (opts.ifNoneMatch)      headers["If-None-Match"]      = opts.ifNoneMatch;
-    if (opts.ifMatch)          headers["If-Match"]           = opts.ifMatch;
-    if (opts.ifModifiedSince)  headers["If-Modified-Since"]  = opts.ifModifiedSince;
-    if (opts.ifUnmodifiedSince) headers["If-Unmodified-Since"] = opts.ifUnmodifiedSince;
+    sharedRequest.applyConditionalGetHeaders(headers, opts, "Range");
     var localReqOpts = Object.assign({}, reqOpts, { _resolveOnRedirect: false });
     return _request("GET", url, headers, null, localReqOpts).then(function (res) {
-      return {
-        statusCode:   res.statusCode,
-        body:         res.body,
-        etag:         res.headers && res.headers.etag,
-        lastModified: res.headers && res.headers["last-modified"]
-                      ? Date.parse(res.headers["last-modified"]) : null,
-        contentRange: res.headers && res.headers["content-range"] || null,
-        size:         res.headers && res.headers["content-length"]
-                      ? parseInt(res.headers["content-length"], 10) : null,
-        contentType:  res.headers && res.headers["content-type"] || null,
-      };
+      return sharedRequest.mapGetResponse(res);
     }, function (err) {
       // 304 surfaces as a "non-2xx error" via httpClient; propagate it
       // as a structured 304 result instead so operator routes get
       // the conditional-GET short-circuit they expect.
       if (err && err.statusCode === requestHelpers.HTTP_STATUS.NOT_MODIFIED) {
-        return {
-          statusCode: requestHelpers.HTTP_STATUS.NOT_MODIFIED,
-          body: null, etag: null, lastModified: null,
-        };
+        return sharedRequest.notModifiedGetResult();
       }
       throw err;
     });
@@ -698,11 +671,7 @@ function create(config) {
     if (opts.versionId) url.searchParams.set("versionId", opts.versionId);
     var headers = _makeSigned("HEAD", url, sha256Hex(Buffer.alloc(0)));
     return _request("HEAD", url, headers, null, reqOpts).then(function (res) {
-      return {
-        size:         res.headers["content-length"] ? parseInt(res.headers["content-length"], 10) : null,
-        etag:         res.headers.etag,
-        lastModified: res.headers["last-modified"] ? Date.parse(res.headers["last-modified"]) : null,
-      };
+      return sharedRequest.mapHeadResponse(res);
     }, function (e) {
       // A missing key surfaces as the framework NOT_FOUND code — the same
       // contract local.js head() exposes and that deleteKey already maps 404
@@ -758,21 +727,8 @@ function create(config) {
 
   function _presign(method, opts) {
     opts = opts || {};
-    if (!opts.key || typeof opts.key !== "string") {
-      throw _err("INVALID_KEY", "presigned URL: key is required", true);
-    }
-    if (opts.key.indexOf("\0") !== -1) {
-      throw _err("INVALID_KEY", "null byte in key", true);
-    }
-    var expiresIn = opts.expiresIn != null ? opts.expiresIn : PRESIGN_DEFAULT_EXPIRES_SECONDS;
-    if (typeof expiresIn !== "number" ||
-        expiresIn < PRESIGN_MIN_EXPIRES_SECONDS ||
-        expiresIn > PRESIGN_MAX_EXPIRES_SECONDS) {
-      throw _err("INVALID_EXPIRES",
-        "presigned URL: expiresIn must be a number of seconds between " +
-        PRESIGN_MIN_EXPIRES_SECONDS + " and " + PRESIGN_MAX_EXPIRES_SECONDS +
-        " (7 days, SigV4 hard cap)", true);
-    }
+    sharedRequest.requirePresignKey(opts, "presigned URL");
+    var expiresIn = sharedRequest.resolvePresignExpires(opts, "presigned URL", "SigV4");
 
     // Validate opts.responseHeaders shape — operators pass camelCase
     // keys; refuse unknown keys at config-time so a typo surfaces at
@@ -876,34 +832,9 @@ function create(config) {
   // Reference: AWS S3 "Browser-Based Uploads Using POST".
   function presignedUploadPolicy(opts) {
     opts = opts || {};
-    if (!opts.key || typeof opts.key !== "string") {
-      throw _err("INVALID_KEY", "presignedUploadPolicy: key is required", true);
-    }
-    if (opts.key.indexOf("\0") !== -1) {
-      throw _err("INVALID_KEY", "null byte in key", true);
-    }
-    if (typeof opts.maxBytes !== "number" || !Number.isFinite(opts.maxBytes) ||
-        opts.maxBytes <= 0) {
-      throw _err("INVALID_MAX_BYTES",
-        "presignedUploadPolicy: maxBytes (positive number of bytes) is required — " +
-        "POST-form policy enforces body size via the content-length-range condition; " +
-        "use presignedUploadUrl if size enforcement is not needed", true);
-    }
-    if (opts.minBytes !== undefined && !numericBounds.isNonNegativeFiniteInt(opts.minBytes)) {
-      throw _err("INVALID_MIN_BYTES",
-        "presignedUploadPolicy: minBytes must be a non-negative finite integer; got " +
-        numericBounds.shape(opts.minBytes), true);
-    }
-    var minBytes = opts.minBytes !== undefined ? opts.minBytes : 0;
-    var expiresIn = opts.expiresIn != null ? opts.expiresIn : PRESIGN_DEFAULT_EXPIRES_SECONDS;
-    if (typeof expiresIn !== "number" ||
-        expiresIn < PRESIGN_MIN_EXPIRES_SECONDS ||
-        expiresIn > PRESIGN_MAX_EXPIRES_SECONDS) {
-      throw _err("INVALID_EXPIRES",
-        "presignedUploadPolicy: expiresIn must be a number of seconds between " +
-        PRESIGN_MIN_EXPIRES_SECONDS + " and " + PRESIGN_MAX_EXPIRES_SECONDS +
-        " (7 days, SigV4 hard cap)", true);
-    }
+    sharedRequest.requirePresignKey(opts, "presignedUploadPolicy");
+    var minBytes = sharedRequest.resolvePresignUploadMinBytes(opts);
+    var expiresIn = sharedRequest.resolvePresignExpires(opts, "presignedUploadPolicy", "SigV4");
 
     var date = opts.date || new Date();
     var amzDate = _formatAmzDate(date);

package/lib/observability-otlp-exporter.js

@@ -37,6 +37,7 @@ var safeBuffer = require("./safe-buffer");
 var validateOpts = require("./validate-opts");
 var safeUrl = require("./safe-url");
 var pb = require("./protobuf-encoder");
+var boundedMap = require("./bounded-map");
 var { defineClass } = require("./framework-error");
 
 var OtlpExporterError = defineClass("OtlpExporterError", { alwaysPermanent: true });
@@ -132,12 +133,27 @@ function _valueToOtlp(v) {
   return { stringValue: String(v) };
 }
 
+// Run a single wire STRING (span name / status message) through the telemetry
+// redactor. These reach the collector exactly like attribute values, so a
+// connection string / token / PII in an error message (the tracer's canonical
+// `setStatus("error", e.message)`) must be scrubbed too (CWE-532). Routes
+// through redactAttrs (the same chokepoint attributes use); fails toward an
+// empty string on a redactor throw, matching redactAttrs' drop-on-error.
+function _redactWireString(key, value) {
+  if (typeof value !== "string" || value.length === 0) return value || "";
+  try {
+    var holder = {};
+    holder[key] = value;
+    return observability().redactAttrs(holder)[key];
+  } catch (_e) { return ""; }
+}
+
 function _spanToOtlp(span) {
   return {
     traceId:           span.traceId,
     spanId:            span.spanId,
     parentSpanId:      span.parentSpanId || "",
-    name:              span.name,
+    name:              _redactWireString("otel.span.name", span.name),
     kind:              KIND_TO_OTLP[span.kind] || KIND_TO_OTLP.internal,
     startTimeUnixNano: span.startTimeUnixNano,
     endTimeUnixNano:   span.endTimeUnixNano || span.startTimeUnixNano,
@@ -154,7 +170,7 @@ function _spanToOtlp(span) {
     droppedEventsCount: span.droppedEventsCount || 0,
     status: {
       code:    STATUS_CODE_TO_OTLP[span.status && span.status.code] || 0,
-      message: (span.status && span.status.message) || "",
+      message: _redactWireString("exception.message", (span.status && span.status.message) || ""),
     },
   };
 }
@@ -167,15 +183,13 @@ function _bundleSpans(spans) {
   for (var i = 0; i < spans.length; i++) {
     var s = spans[i];
     var resKey = JSON.stringify(s.resource || {});
-    var bucket = byResource.get(resKey);
-    if (!bucket) {
-      bucket = {
+    var bucket = boundedMap.getOrInsert(byResource, resKey, function () {
+      return {
         resource: s.resource || {},
         scope:    s.scope || { name: "blamejs", version: null },
         spans:    [],
       };
-      byResource.set(resKey, bucket);
-    }
+    });
     bucket.spans.push(s);
   }
   var resourceSpans = [];
@@ -337,7 +351,7 @@ function _attrsToProto(attrs) {
 function _spanToProto(span) {
   // Status code: 0=Unset, 1=Ok, 2=Error. Status field 1 is reserved.
   var statusBody = Buffer.concat([
-    pb.string(2, (span.status && span.status.message) || ""),
+    pb.string(2, _redactWireString("exception.message", (span.status && span.status.message) || "")),
     pb.uint32(3, STATUS_CODE_TO_OTLP[span.status && span.status.code] || 0),
   ]);
   var eventsRepeated = pb.repeatedMessage(11, span.events || [], function (e) {
@@ -353,7 +367,7 @@ function _spanToProto(span) {
     pb.bytes(2,   _hexToBytes(span.spanId)),
     pb.string(3,  ""),                                                          // trace_state (not yet propagated by the framework)
     pb.bytes(4,   _hexToBytes(span.parentSpanId || "")),
-    pb.string(5,  span.name || ""),
+    pb.string(5,  _redactWireString("otel.span.name", span.name || "")),
     pb.uint32(6,  KIND_TEXT_TO_ENUM[span.kind] != null ? KIND_TEXT_TO_ENUM[span.kind] : KIND_TEXT_TO_ENUM.internal),
     pb.fixed64(7, span.startTimeUnixNano || 0),
     pb.fixed64(8, span.endTimeUnixNano || span.startTimeUnixNano || 0),         // proto field number 8, not bytes
@@ -380,15 +394,13 @@ function _bundleSpansToProto(spansArray) {
   for (var i = 0; i < spansArray.length; i += 1) {
     var s = spansArray[i];
     var resKey = JSON.stringify(s.resource || {});
-    var bucket = byResource.get(resKey);
-    if (!bucket) {
-      bucket = {
+    var bucket = boundedMap.getOrInsert(byResource, resKey, function () {
+      return {
         resource: s.resource || {},
         scope:    s.scope || { name: "blamejs", version: null },
         spans:    [],
       };
-      byResource.set(resKey, bucket);
-    }
+    });
     bucket.spans.push(s);
   }
   var resourceSpansPieces = [];
@@ -493,21 +505,8 @@ function create(opts) {
   var inFlight = false;
   var stopping = false;
 
-  var auditOn = opts.audit !== false;
-  function _emitMetric(verb, n, labels) {
-    try { observability().safeEvent("otlp.exporter." + verb, n || 1, labels || {}); }
-    catch (_e) { /* drop-silent */ }
-  }
-  function _emitAudit(action, outcome, metadata) {
-    if (!auditOn) return;
-    try {
-      audit().safeEmit({
-        action:   "system.observability.otlp_exporter." + action,
-        outcome:  outcome,
-        metadata: metadata || {},
-      });
-    } catch (_e) { /* drop-silent — audit is best-effort, never crashes the exporter */ }
-  }
+  var _emitMetric = observability().namespaced("otlp.exporter");
+  var _emitAudit = audit().namespaced("system.observability.otlp_exporter", opts.audit);
 
   function queue_(span) {
     if (stopping) { droppedExportFailed += 1; return; }
@@ -664,6 +663,7 @@ module.exports = {
   OtlpExporterError:       OtlpExporterError,
   // Exported for tests
   _spanToOtlp:             _spanToOtlp,
+  _spanToProto:            _spanToProto,
   _bundleSpans:            _bundleSpans,
   _attrToOtlp:             _attrToOtlp,
   _BASE64URL_RE_REF:       safeBuffer.BASE64URL_RE,                                // not used; reserved for OTLP/protobuf shape upgrade

package/lib/observability.js

@@ -343,6 +343,98 @@ function safeEvent(name, value, labels) {
   catch (_e) { /* hot-path observability sink — drops silent on internal throws */ }
 }
 
+/**
+ * @primitive b.observability.safeEmit
+ * @signature b.observability.safeEmit(sink, name, value, labels)
+ * @since     0.15.13
+ * @related   b.observability.safeEvent, b.observability.event
+ *
+ * The sink-aware sibling of `safeEvent`: emit a metric event to an
+ * explicitly-configured observability `sink` (a per-instance
+ * observability object) when one is supplied, otherwise fall back to
+ * the global registry — each path wrapped in a try/catch so a
+ * misconfigured counter never crashes the request that triggered it.
+ * Replaces the `_emitObs` + `_safeGlobalObs` helper pair that the auth
+ * brute-force modules (bot-challenge / lockout / session-device-binding)
+ * each duplicated to route a configured observability instance with a
+ * global fallback.
+ *
+ * @example
+ *   b.observability.safeEmit(opts.observability, "auth.lockout.hit", 1,
+ *     { namespace: ns });
+ */
+function safeEmit(sink, name, value, labels) {
+  if (sink) {
+    try { sink.event(name, value, labels); }
+    catch (_e) { /* per-instance observability sink — drops silent */ }
+    return;
+  }
+  safeEvent(name, value, labels);
+}
+
+/**
+ * @primitive b.observability.makeCounterEmitter
+ * @signature b.observability.makeCounterEmitter(sink)
+ * @since      0.15.13
+ * @status     stable
+ * @related    b.observability.safeEmit, b.observability.namespaced
+ *
+ * Bind a per-instance counter emitter. Returns `(name, labels)` that
+ * increments metric `name` by 1 (with `labels`) on the supplied
+ * observability `sink`, drop-silent on a sink throw and falling back to
+ * the global tap when `sink` is null. The shorthand every primitive that
+ * accepts an `observability` instance wrapped in a private
+ * `_emitObs(name, labels)` closure around
+ * `safeEmit(obsInst, name, 1, labels)` — build it once with the instance
+ * and call the returned emitter.
+ *
+ * @example
+ *   var b = require("blamejs");
+ *   var emit = b.observability.makeCounterEmitter(myObsInstance);
+ *   emit("auth.lockout.tripped", { actor: "alice" });
+ */
+function makeCounterEmitter(sink) {
+  return function (name, labels) {
+    safeEmit(sink, name, 1, labels);
+  };
+}
+
+/**
+ * @primitive b.observability.namespaced
+ * @signature b.observability.namespaced(prefix, gateFlag?)
+ * @since     0.15.13
+ * @status    stable
+ * @related   b.observability.safeEvent, b.observability.event, b.audit.namespaced
+ *
+ * Build a drop-silent metric emitter bound to one name prefix — the shape every
+ * primitive hand-rolled as a private `_emitMetric(verb, n, labels)` closure
+ * (`try { observability().safeEvent("ns." + verb, n || 1, labels || {}); }
+ * catch {}`). The returned function prefixes `verb` with `prefix + "."`,
+ * defaults the value to `1` and labels to `{}`, and routes through `safeEvent`
+ * so a misconfigured counter / label name cannot crash the caller. The metric
+ * sibling of `b.audit.namespaced`. Metrics emit unconditionally by default;
+ * pass `gateFlag === false` to disable a primitive's own metrics in lockstep
+ * with its audit (the few primitives that gate both behind one `opts.audit`).
+ *
+ * @example
+ *   var emitMetric = b.observability.namespaced("network.byte_quota");
+ *   emitMetric("exceeded", 1, { key: k });
+ *   // → safeEvent("network.byte_quota.exceeded", 1, { key: k })
+ *   emitMetric("reset");
+ *   // → safeEvent("network.byte_quota.reset", 1, {})
+ */
+function namespaced(prefix, gateFlag) {
+  var on = gateFlag !== false;
+  return function (verb, n, labels) {
+    if (!on) return;
+    // module.exports.safeEvent (late-bound) so a test that stubs
+    // b.observability.safeEvent still observes the emit — the closures this
+    // replaces all called `observability().safeEvent(...)`.
+    try { module.exports.safeEvent(prefix + "." + verb, n || 1, labels || {}); }
+    catch (_e) { /* drop-silent — observability sink */ }
+  };
+}
+
 // timed — convenience wrapper that measures wall-clock duration of a
 // sync or async operation and emits a counter event with
 // duration_ms in the labels. Returns the wrapped function's return
@@ -870,6 +962,9 @@ module.exports = {
   tap:           tap,
   event:         event,
   safeEvent:     safeEvent,
+  safeEmit:      safeEmit,
+  makeCounterEmitter: makeCounterEmitter,
+  namespaced:    namespaced,
   timed:         timed,
   setTap:        setTap,
   setRedactor:   setRedactor,

package/lib/openapi-paths-builder.js

@@ -25,6 +25,7 @@
 
 var validateOpts = require("./validate-opts");
 var schemaWalk   = require("./openapi-schema-walk");
+var pick         = require("./pick");
 var { defineClass } = require("./framework-error");
 var OpenApiError = defineClass("OpenApiError", { alwaysPermanent: true });
 
@@ -44,7 +45,10 @@ function _extractPathParams(pathTemplate) {
 }
 
 function PathsBuilder() {
-  this._paths = {};
+  // null-proto so a urlPattern keyed into _paths (operator-supplied API path)
+  // can never reach Object.prototype — a "__proto__" / "constructor" path lands
+  // as an own property, not a prototype mutation (prototype-polluting-assignment).
+  this._paths = Object.create(null);
 }
 
 // _buildOperation — normalise a single Operation Object from operator
@@ -133,7 +137,7 @@ PathsBuilder.prototype.add = function (method, urlPattern, opts) {
     }
   }
 
-  if (!this._paths[urlPattern]) this._paths[urlPattern] = {};
+  if (!this._paths[urlPattern]) this._paths[urlPattern] = Object.create(null);
   if (this._paths[urlPattern][method.toLowerCase()]) {
     throw new OpenApiError("openapi/duplicate-operation",
       "paths.add: duplicate operation " + method.toUpperCase() + " " + urlPattern);
@@ -279,7 +283,7 @@ WebhooksBuilder.prototype.add = function (name, method, opts) {
   opts = opts || {};
   validateOpts.requireNonEmptyString(name, "webhook.add: name",
     OpenApiError, "openapi/bad-webhook");
-  if (name === "__proto__" || name === "constructor" || name === "prototype") {
+  if (pick.isPoisonedKey(name)) {
     throw new OpenApiError("openapi/bad-webhook",
       "webhook.add: name must not be a reserved object key (" + JSON.stringify(name) + ")");
   }

package/lib/otel-export.js

@@ -40,6 +40,7 @@
  * hand-rolled wire format with no compelling benefit at this scope.
  */
 var C = require("./constants");
+var boundedMap = require("./bounded-map");
 var canonicalJson = require("./canonical-json");
 var httpClient = require("./http-client");
 var observability = require("./observability");
@@ -144,11 +145,9 @@ function create(opts) {
     if (typeof name !== "string" || name.length === 0) return;
     var v = typeof value === "number" && isFinite(value) ? value : 1;
     var key = _bucketKey(name, attrs);
-    var b = counters.get(key);
-    if (!b) {
-      b = { name: name, attrs: attrs || {}, value: 0, startUnixNano: startUnixNano };
-      counters.set(key, b);
-    }
+    var b = boundedMap.getOrInsert(counters, key, function () {
+      return { name: name, attrs: attrs || {}, value: 0, startUnixNano: startUnixNano };
+    });
     b.value += v;
   }
 
@@ -157,11 +156,9 @@ function create(opts) {
     if (typeof name !== "string" || name.length === 0) return;
     if (typeof value !== "number" || !isFinite(value)) return;
     var key = _bucketKey(name, attrs);
-    var b = observations.get(key);
-    if (!b) {
-      b = { name: name, attrs: attrs || {}, sum: 0, count: 0, min: value, max: value, startUnixNano: startUnixNano };
-      observations.set(key, b);
-    }
+    var b = boundedMap.getOrInsert(observations, key, function () {
+      return { name: name, attrs: attrs || {}, sum: 0, count: 0, min: value, max: value, startUnixNano: startUnixNano };
+    });
     b.sum   += value;
     b.count += 1;
     if (value < b.min) b.min = value;

package/lib/outbox.js

@@ -208,29 +208,47 @@ function create(opts) {
     "envelope", "connectorName", "connectorVersion", "dbName",
   ], "outbox.create");
 
-  if (!opts.externalDb || typeof opts.externalDb.transaction !== "function") {
-    throw new OutboxError("outbox/bad-externaldb",
-      "outbox.create: externalDb must be the b.externalDb namespace (with transaction/query)");
-  }
-  validateOpts.requireNonEmptyString(opts.table,
-    "outbox.create: table", OutboxError, "outbox/bad-table");
-  // Validate the table identifier at create-time so a bad name throws at
-  // boot, not at first query. b.sql re-quotes the name by construction on
-  // every emitted statement (the builder owns identifier quoting now).
-  _validateTableName(opts.table);
-
-  if (typeof opts.publisher !== "function") {
-    throw new OutboxError("outbox/bad-publisher",
-      "outbox.create: publisher must be an async function (event) → void");
-  }
-  validateOpts.optionalPositiveFinite(opts.pollIntervalMs,
-    "outbox.create: pollIntervalMs", OutboxError, "outbox/bad-opts");
-  validateOpts.optionalPositiveFinite(opts.batchSize,
-    "outbox.create: batchSize", OutboxError, "outbox/bad-opts");
-  validateOpts.optionalPositiveFinite(opts.maxAttempts,
-    "outbox.create: maxAttempts", OutboxError, "outbox/bad-opts");
-  validateOpts.optionalPositiveFinite(opts.claimReclaimMs,
-    "outbox.create: claimReclaimMs", OutboxError, "outbox/bad-opts");
+  validateOpts.shape(opts, {
+    externalDb: function (v) {
+      if (!v || typeof v.transaction !== "function") {
+        throw new OutboxError("outbox/bad-externaldb",
+          "outbox.create: externalDb must be the b.externalDb namespace (with transaction/query)");
+      }
+    },
+    table: function (v) {
+      validateOpts.requireNonEmptyString(v,
+        "outbox.create: table", OutboxError, "outbox/bad-table");
+      // Validate the table identifier at create-time so a bad name throws
+      // at boot, not at first query. b.sql re-quotes the name by
+      // construction on every emitted statement (the builder owns
+      // identifier quoting now).
+      _validateTableName(v);
+    },
+    publisher: function (v) {
+      if (typeof v !== "function") {
+        throw new OutboxError("outbox/bad-publisher",
+          "outbox.create: publisher must be an async function (event) → void");
+      }
+    },
+    pollIntervalMs: "optional-positive-finite",
+    batchSize:      "optional-positive-finite",
+    maxAttempts:    "optional-positive-finite",
+    claimReclaimMs: "optional-positive-finite",
+    retryBackoff: {
+      optional: true,
+      shape: {
+        initialMs: "optional-positive-finite",
+        maxMs:     "optional-positive-finite",
+        factor:    "optional-positive-finite",
+      },
+    },
+    audit:            "optional-boolean",
+    name:             "optional-string",
+    envelope:         "optional-string",
+    connectorName:    "optional-string",
+    connectorVersion: "optional-string",
+    dbName:           "optional-string",
+  }, "outbox.create", OutboxError, "outbox/bad-opts");
 
   var pollIntervalMs = opts.pollIntervalMs || DEFAULT_POLL_MS;
   var batchSize      = opts.batchSize      || DEFAULT_BATCH_SIZE;
@@ -268,20 +286,8 @@ function create(opts) {
     return Math.floor(ms);
   }
 
-  function _emitMetric(verb, n) {
-    try { observability().safeEvent("outbox." + verb, n || 1, {}); }
-    catch (_e) { /* drop-silent */ }
-  }
-  function _emitAudit(action, outcome, metadata) {
-    if (!auditOn) return;
-    try {
-      audit().safeEmit({
-        action:   action,
-        outcome:  outcome,
-        metadata: metadata || {},
-      });
-    } catch (_e) { /* drop-silent */ }
-  }
+  var _emitMetric = observability().namespaced("outbox");
+  var _emitAudit = audit().namespaced(null, { audit: auditOn });
 
   async function enqueue(event, txn) {
     if (!txn || typeof txn.query !== "function") {
@@ -369,11 +375,18 @@ function create(opts) {
       { name: "last_error",      type: "TEXT" },
       { name: "status",          type: "VARCHAR(16)",  notNull: true, default: "pending" },
     ], { dialect: dialect }), dialect);
-    // Partial index on the pending pool (the publisher's claim path scans
-    // status='pending' ORDER BY next_attempt_at). The 'pending' literal is
-    // a builder-emitted static predicate, opted in via allowLiterals.
+    // Index for the publisher's claim path (scans status='pending' ORDER BY
+    // next_attempt_at). sqlite/postgres support a partial index (WHERE on
+    // CREATE INDEX) on next_attempt_at; MySQL does NOT — a WHERE there is a
+    // syntax error that made declareSchema() throw on MySQL — so fall back to a
+    // composite (status, next_attempt_at) index, which serves the same
+    // equality+range scan. The 'pending' literal is a builder-emitted static
+    // predicate, opted in via allowLiterals.
+    var idxCols = dialect === "mysql" ? ["status", "next_attempt_at"] : ["next_attempt_at"];
+    var idxOpts = { dialect: dialect };
+    if (dialect !== "mysql") idxOpts.where = "status = 'pending'";
     var idx = sql.toExternalSql(sql.createIndex(opts.table + "_pending_idx", opts.table,
-      ["next_attempt_at"], { dialect: dialect, where: "status = 'pending'" }), dialect);
+      idxCols, idxOpts), dialect);
     await target.query(ddl.sql, ddl.params);
     await target.query(idx.sql, idx.params);
     // Back-compat: an outbox table created before the claimed_at column

package/lib/pagination.js

@@ -50,6 +50,7 @@ var nodeCrypto = require("node:crypto");
 var C = require("./constants");
 var canonicalJson = require("./canonical-json");
 var bCrypto = require("./crypto");
+var validateOpts = require("./validate-opts");
 var numericBounds = require("./numeric-bounds");
 var safeJson = require("./safe-json");
 var safeSql = require("./safe-sql");
@@ -85,11 +86,12 @@ function _toBuf(secret) {
 
 function _b64urlEncode(buf) { return bCrypto.toBase64Url(buf); }
 
-function _b64urlDecode(s) {
-  if (typeof s !== "string") throw new PaginationError("pagination/bad-cursor", "cursor must be a string");
-  try { return bCrypto.fromBase64Url(s); }
-  catch (_e) { throw new PaginationError("pagination/bad-cursor", "cursor is not valid base64url"); }
-}
+var _b64urlDecode = bCrypto.makeBase64UrlDecoder({
+  errorClass:  PaginationError,
+  code:        "pagination/bad-cursor",
+  typeMessage: "cursor must be a string",
+  badMessage:  "cursor is not valid base64url",
+});
 
 function _tag(secretBuf, stateJson) {
   var h = nodeCrypto.createHash("sha3-512");
@@ -345,11 +347,8 @@ function _buildKeysetWhere(orderEntries, cursorVals, forward) {
  *   });
  */
 async function cursor(query, opts) {
-  if (!query || typeof query.where !== "function" || typeof query.orderBy !== "function" ||
-      typeof query.limit !== "function" || typeof query.all !== "function") {
-    throw new PaginationError("pagination/bad-query",
-      "cursor: first arg must be a db Query (must support where, orderBy, limit, all)");
-  }
+  validateOpts.requireMethods(query, ["where", "orderBy", "limit", "all"],
+    "cursor: first arg (db Query)", PaginationError, "pagination/bad-query");
   opts = opts || {};
   if (opts.secret == null) {
     throw new PaginationError("pagination/no-secret",
@@ -484,11 +483,8 @@ async function cursor(query, opts) {
  *   page.hasMore;      // → true when page < totalPages
  */
 async function offset(query, opts) {
-  if (!query || typeof query.limit !== "function" || typeof query.offset !== "function" ||
-      typeof query.all !== "function" || typeof query.count !== "function") {
-    throw new PaginationError("pagination/bad-query",
-      "offset: first arg must be a db Query (must support limit, offset, all, count)");
-  }
+  validateOpts.requireMethods(query, ["limit", "offset", "all", "count"],
+    "offset: first arg (db Query)", PaginationError, "pagination/bad-query");
   opts = opts || {};
   var perPage = _resolveLimit({ limit: opts.perPage, max: opts.max, default: opts.default });
   var page = parseInt(opts.page, 10);