@blamejs/core 0.12.5 → 0.12.6

package/CHANGELOG.md

@@ -8,6 +8,8 @@ upgrading across more than a few patches at a time.
 
 ## v0.12.x
 
+- v0.12.6 (2026-05-22) — **`b.observability.otlpExporter` adds OTLP/protobuf-HTTP encoding (`opts.encoding: "protobuf"`).** The OTLP trace exporter now speaks `application/x-protobuf` end-to-end. Operators with high-volume telemetry opt into binary encoding via `opts.encoding: "protobuf"` (`"http/protobuf"` is accepted as a spec-name alias). The protobuf wire format encodes the same `ExportTraceServiceRequest` envelope as the existing JSON path — `ResourceSpans` → `ScopeSpans` → `Span` → `Status` / `Event` / `KeyValue` / `AnyValue` per the opentelemetry-proto repo — but emits 30-50% smaller bodies than the JSON shape on real-world workloads and avoids the JSON-parse cost on the collector side. Default stays `"json"`; collectors that don't speak protobuf keep working unchanged. Composes the existing `lib/protobuf-encoder.js` infrastructure. **Added:** *`opts.encoding: "json" | "protobuf"` on `b.observability.otlpExporter.create`* — When `"protobuf"` (or the spec-name alias `"http/protobuf"`), the exporter encodes batches as binary OTLP `ExportTraceServiceRequest` bytes and POSTs with `Content-Type: application/x-protobuf`. The retry / queue / drop-counter / audit machinery is shared with the JSON path so operators get the same operational primitives across both encodings. Default stays `"json"` — existing collectors keep working without configuration changes. · *Full OTLP trace schema encoded via `lib/protobuf-encoder.js`* — ResourceSpans / ScopeSpans / Span / Event / Status / KeyValue / AnyValue / ArrayValue are emitted per the opentelemetry-proto repo's field numbers + wire types. `trace_id` and `span_id` round-trip as fixed-length bytes (16 + 8 octets respectively). `start_time_unix_nano` / `end_time_unix_nano` use `fixed64` for the nanosecond precision the JSON path's number type lossily encoded. SpanKind enum mapping covers unspecified / internal / server / client / producer / consumer. · *`pb.int64` / `pb.sint64` — signed-integer varint shapes on `lib/protobuf-encoder.js`* — Negative integer attribute values in OTLP `AnyValue` (e.g. retry-after offsets, signed metric deltas) emit as proto3 `int64` — wire-type 0 varint, 10-byte two's-complement reinterpret per the spec. `pb.sint64` adds ZigZag-encoded varint for cases where small negatives dominate. Both accept Number / BigInt / digit-string inputs with explicit `[-2^63, 2^63 - 1]` range validation. · *`pb.fixed64` accepts string-form uint64 values* — OTLP/JSON encodes uint64 as a JSON string (per the proto3 JSON mapping) — the framework's tracer emits `start_time_unix_nano` / `end_time_unix_nano` as digit-string BigInt-to-string conversions so the JSON path stays lossless. `pb.fixed64` now accepts that same digit-string shape on the protobuf path so a single timestamp representation flows through both encodings without a separate coercion step. Refuses non-digit strings and silently-rounded Numbers above `Number.MAX_SAFE_INTEGER`. **Security:** *AnyValue recursion capped at 100 levels (CVE-2024-7254 / CVE-2025-4565 class)* — Both protobufjs (CVE-2024-7254) and protobuf-python (CVE-2025-4565) shipped DoS-via-unbounded-nested-group decoding. The OTLP `AnyValue` type permits a nested `ArrayValue { repeated AnyValue values = 1 }` that an adversarial collector-response could exploit during a future receive path. The encoder caps `_anyValueToProto` recursion at 100 levels — beyond which it emits an empty AnyValue rather than continuing to descend. Today's framework only EMITS (never receives) OTLP — but the cap is in the right place when the receive path lands. **References:** [OTLP §3 — Body encodings (JSON + protobuf)](https://opentelemetry.io/docs/specs/otlp/) · [opentelemetry-proto repo — trace/v1/trace.proto](https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/trace/v1/trace.proto) · [CVE-2024-7254 (protobufjs unbounded nesting DoS)](https://nvd.nist.gov/vuln/detail/CVE-2024-7254) · [CVE-2025-4565 (protobuf-python unbounded nesting DoS)](https://nvd.nist.gov/vuln/detail/CVE-2025-4565)
+
 - v0.12.5 (2026-05-22) — **`b.metrics` content-negotiates OpenMetrics 1.0 + auto-attaches trace exemplars on request histograms.** The `/metrics` scrape endpoint now serves `application/openmetrics-text; version=1.0.0; charset=utf-8` when the scraper requests it via the `Accept` header (Prometheus 2.x strict mode, OpenObservability tooling). Legacy scrapers still get `text/plain; version=0.0.4` — no operator with the default Prometheus client sees a content-type change. Separately, the framework's request-duration histogram middleware now auto-attaches the active sampled trace's `trace_id` + `span_id` as the OpenMetrics §6.2 exemplar on every bucket sample, so Grafana / Tempo / Jaeger scrapers can pivot from a slow-bucket histogram to the exact trace that produced the sample. The wiring is composition-only — `b.middleware.tracePropagate` populates `req.trace.{traceId,parentId,sampled}`, the metrics middleware reads it, no operator opt-in needed. **Added:** *`Accept` content-negotiation on `b.metrics.expositionHandler()`* — When the scraper's `Accept` header includes `application/openmetrics-text`, the handler renders the OpenMetrics 1.0 wire format (`# UNIT` lines, `_total` suffix on counters, `# EOF` terminator, exemplar shape) and serves `application/openmetrics-text; version=1.0.0; charset=utf-8`. Otherwise serves Prometheus 0.0.4 `text/plain` as before. Operators relying on the legacy Prometheus content-type see no change. · *Auto-attached trace exemplars on request-duration histograms* — When `b.middleware.spanHttpServer` populates `req.span.{traceId, spanId, sampled}` on the inbound request and the span is sampled, the framework's built-in `requestDuration` histogram middleware attaches `{ labels: { trace_id, span_id }, value: <duration>, timestamp: <unix-sec> }` as the OpenMetrics §6.2 exemplar on the corresponding bucket. The exemplar's `span_id` is the server-handling span, not the upstream `traceparent`'s parent-id, so the metric-to-trace pivot in Grafana / Tempo / Jaeger lands on the work the metric measured. Operators wiring `tracePropagate` without `spanHttpServer` fall back to `req.trace.spanId` when populated; the framework never invents a span_id from the upstream parent. **Fixed:** *Accept-header weighted negotiation (Codex P1)* — The first pass treated any `Accept` header containing `application/openmetrics-text` as an unconditional OpenMetrics request — clients sending `Accept: text/plain;q=1.0, application/openmetrics-text;q=0.5` got OpenMetrics back instead of their preferred Prometheus 0.0.4. Fix: parse Accept via `b.requestHelpers.parseQualityList` and compare q-values for `application/openmetrics-text` vs `text/plain` (wildcards `*/*`, `application/*`, `text/*` honored). Defaults to Prometheus when both q-values are equal or zero (backward compatibility with the legacy default content-type). · *Exemplar span_id sources the active server span, not the upstream parent (Codex P2)* — The first pass used `req.trace.parentId` for the exemplar's `span_id` label — but `parentId` is the upstream caller's span (or empty for root requests), not the server-handling span. Fix: prefer `req.span.spanId` (set by `b.middleware.spanHttpServer`), falling back to `req.trace.spanId` for operators wiring `tracePropagate` without `spanHttpServer`. Never synthesises a span_id from `parentId`. **References:** [OpenMetrics 1.0 §1.2 (content negotiation)](https://prometheus.io/docs/specs/om/open_metrics_spec/) · [OpenMetrics 1.0 §6.2 (exemplars)](https://prometheus.io/docs/specs/om/open_metrics_spec/) · [W3C Trace Context (traceparent header)](https://www.w3.org/TR/trace-context/)
 
 - v0.12.4 (2026-05-22) — **`SECURITY.md` Watch list — remove stale "framework doesn't ship CMS / S/MIME" entry.** The Watch list bullet claiming `framework does not ship a CMS / S/MIME / PKCS#7 surface today` has been wrong since v0.10.13 — `b.cms.encodeSignedData` / `decode` / `encodeEnvelopedData` / `parseSignedData` shipped then, and `b.mail.crypto.smime.sign` / `verify` / `verifyAll` / `checkCert` shipped under the mail-stack. The Watch list is for CVE classes the framework deliberately doesn't ship a primitive for; CMS no longer fits that shape. Entry removed. **Fixed:** *Watch list no longer claims CMS / S/MIME are unshipped* — `b.cms` exposes RFC 5652 ContentInfo / SignedData / EnvelopedData encode + decode with PQC signer support (ML-DSA-65 per RFC 9909 §5, ML-DSA-87 per RFC 9909 §6, SLH-DSA-SHAKE-256f per RFC 9881). `b.mail.crypto.smime` builds on it for RFC 8551 S/MIME signed + enveloped mail with `checkCert` for X.509 chain validation. The SECURITY.md Watch list entry that pointed operators to external CMS libraries is gone; operators on regulated mail interop reach for the in-framework primitives instead.

package/lib/observability-otlp-exporter.js

@@ -36,6 +36,7 @@ var safeAsync = require("./safe-async");
 var safeBuffer = require("./safe-buffer");
 var validateOpts = require("./validate-opts");
 var safeUrl = require("./safe-url");
+var pb = require("./protobuf-encoder");
 var { defineClass } = require("./framework-error");
 
 var OtlpExporterError = defineClass("OtlpExporterError", { alwaysPermanent: true });
@@ -189,6 +190,221 @@ function _bundleSpans(spans) {
   return { resourceSpans: resourceSpans };
 }
 
+// ---- OTLP/protobuf encoder ------------------------------------------------
+//
+// OTLP §3 — `application/x-protobuf` body shape per the
+// opentelemetry-proto repo's ExportTraceServiceRequest message.
+//
+// Wire-format encoding composes b.protobufEncoder. Fields are:
+//
+//   ExportTraceServiceRequest {
+//     repeated ResourceSpans resource_spans = 1;
+//   }
+//   ResourceSpans {
+//     Resource resource     = 1;
+//     repeated ScopeSpans scope_spans = 2;
+//     string schema_url     = 3;
+//   }
+//   Resource {
+//     repeated KeyValue attributes        = 1;
+//     uint32 dropped_attributes_count    = 2;
+//   }
+//   ScopeSpans {
+//     InstrumentationScope scope = 1;
+//     repeated Span spans        = 2;
+//     string schema_url          = 3;
+//   }
+//   InstrumentationScope { string name = 1; string version = 2; ... }
+//   Span {
+//     bytes trace_id              = 1;  // 16 bytes
+//     bytes span_id               = 2;  //  8 bytes
+//     string trace_state          = 3;
+//     bytes parent_span_id        = 4;  //  8 bytes or empty
+//     string name                 = 5;
+//     SpanKind kind               = 6;  // enum 0..5
+//     fixed64 start_time_unix_nano = 7;
+//     fixed64 end_time_unix_nano   = 8;
+//     repeated KeyValue attributes = 9;
+//     uint32 dropped_attributes_count = 10;
+//     repeated Event events           = 11;
+//     uint32 dropped_events_count     = 12;
+//     repeated Link links             = 13;
+//     uint32 dropped_links_count      = 14;
+//     Status status                   = 15;
+//   }
+//   Event { fixed64 time_unix_nano = 1; string name = 2; repeated KeyValue attributes = 3; uint32 dropped_attributes_count = 4; }
+//   Status { string message = 2; enum code = 3; }  // field 1 reserved
+//   KeyValue { string key = 1; AnyValue value = 2; }
+//   AnyValue {
+//     oneof value {
+//       string string_value = 1;
+//       bool   bool_value   = 2;
+//       int64  int_value    = 3;
+//       double double_value = 4;
+//       ArrayValue array_value = 5;
+//     }
+//   }
+//   ArrayValue { repeated AnyValue values = 1; }
+//
+// AnyValue recursion is capped at MAX_ANYVALUE_DEPTH to defend the
+// CVE-2024-7254 + CVE-2025-4565 protobuf nested-group DoS class.
+
+var MAX_ANYVALUE_DEPTH = 100;                                                    // allow:raw-byte-literal — protobuf nested-message DoS cap
+
+function _hexToBytes(hex) {
+  if (typeof hex !== "string" || hex.length === 0) return Buffer.alloc(0);
+  // Tolerate odd-length hex by left-padding with zero; OTLP spec
+  // requires fixed lengths but the exporter should not crash a request
+  // with a malformed inbound trace_id — drop-silent and emit empty.
+  if (hex.length % 2 !== 0) return Buffer.alloc(0);
+  var out = Buffer.alloc(hex.length / 2);
+  for (var i = 0; i < hex.length; i += 2) {
+    var byte = parseInt(hex.substr(i, 2), 16);                                  // allow:raw-byte-literal — radix=16 for hex parse, not byte count
+    if (!isFinite(byte)) return Buffer.alloc(0);
+    out[i / 2] = byte;
+  }
+  return out;
+}
+
+var KIND_TEXT_TO_ENUM = {
+  unspecified: 0, internal: 1, server: 2, client: 3, producer: 4, consumer: 5,
+};
+
+function _anyValueToProto(v, depth) {
+  if (depth >= MAX_ANYVALUE_DEPTH) {
+    // Refuse to descend further; emit empty AnyValue. Matches the spec's
+    // "unknown wire type" tolerant-parser behaviour on the receive side.
+    return Buffer.alloc(0);
+  }
+  var t = typeof v;
+  if (t === "string")  return pb.string(1, v);
+  if (t === "boolean") return pb.bool(2, v);
+  if (t === "number") {
+    if (Number.isInteger(v)) {
+      // OTLP AnyValue field 3 is proto int64 — wire-type 0 varint, NOT
+      // length-delimited. Negatives encode as the 64-bit two's-complement
+      // reinterpret-cast (10-byte varint per the spec). Composes
+      // `pb.int64` which carries the BigInt conversion + range check so
+      // a negative attribute value (e.g. retry-after offset, signed
+      // metric delta) doesn't poison the whole batch.
+      return pb.int64(3, v);
+    }
+    return pb.double(4, v);
+  }
+  if (Array.isArray(v)) {
+    var items = new Array(v.length);
+    for (var i = 0; i < v.length; i += 1) {
+      items[i] = _anyValueToProto(v[i], depth + 1);
+    }
+    var arrayInner = pb.repeatedMessage(1, items, function (b) { return b; });
+    return pb.embeddedMessage(5, arrayInner);
+  }
+  // Unknown → coerce to string per the JSON path's behaviour.
+  return pb.string(1, String(v));
+}
+
+function _keyValueToProto(kvObj) {
+  // kvObj is { key, value: <plain-js> } from _attrToOtlp — but we
+  // re-derive directly here so the protobuf path doesn't depend on
+  // the JSON-shaped intermediate.
+  return Buffer.concat([
+    pb.string(1, kvObj.key),
+    pb.embeddedMessage(2, _anyValueToProto(kvObj.rawValue, 0)),
+  ]);
+}
+
+function _attrsToProto(attrs) {
+  // attrs is the raw `{ key: value }` operator attribute object; OTLP
+  // KeyValue gets emitted per entry with field 9 (attributes) on Span,
+  // field 1 (attributes) on Resource, etc.
+  if (!attrs || typeof attrs !== "object") return [];
+  var keys = Object.keys(attrs);
+  var out = new Array(keys.length);
+  for (var i = 0; i < keys.length; i += 1) {
+    out[i] = { key: keys[i], rawValue: attrs[keys[i]] };
+  }
+  return out;
+}
+
+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.uint32(3, STATUS_CODE_TO_OTLP[span.status && span.status.code] || 0),
+  ]);
+  var eventsRepeated = pb.repeatedMessage(11, span.events || [], function (e) {
+    return Buffer.concat([
+      pb.fixed64(1, e.timeUnixNano || 0),
+      pb.string(2, e.name || ""),
+      pb.repeatedMessage(3, _attrsToProto(e.attributes), _keyValueToProto),
+      pb.uint32(4, 0),
+    ]);
+  });
+  return Buffer.concat([
+    pb.bytes(1,   _hexToBytes(span.traceId)),
+    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.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),         // allow:raw-byte-literal — proto field number 8, not bytes
+    pb.repeatedMessage(9, _attrsToProto(span.attributes), _keyValueToProto),
+    pb.uint32(10, span.droppedAttributesCount || 0),
+    eventsRepeated,
+    pb.uint32(12, span.droppedEventsCount || 0),
+    pb.uint32(15, 0),                                                           // links repeated count placeholder; encoder emits 0 length-delim when no links
+    Buffer.concat([
+      pb._tag(15, 2),                                                           // WIRE_LDELIM tag for status
+      pb._writeVarint(statusBody.length),
+      statusBody,
+    ]),
+  ]);
+}
+
+// `bundle` is the value returned by _bundleSpans — { resourceSpans: [...] }
+// where each entry has { resource, scopeSpans: [{ scope, spans: [...] }] }
+// in the JSON-shape. We re-derive the proto bytes from the SAME pre-OTLP
+// span list so the protobuf path doesn't double-transform the data.
+function _bundleSpansToProto(spansArray) {
+  if (spansArray.length === 0) return Buffer.alloc(0);
+  var byResource = new Map();
+  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 = {
+        resource: s.resource || {},
+        scope:    s.scope || { name: "blamejs", version: null },
+        spans:    [],
+      };
+      byResource.set(resKey, bucket);
+    }
+    bucket.spans.push(s);
+  }
+  var resourceSpansPieces = [];
+  for (var entry of byResource) {
+    var b = entry[1];
+    var resourceBody = pb.repeatedMessage(1, _attrsToProto(b.resource), _keyValueToProto);
+    var scopeBody = Buffer.concat([
+      pb.string(1, b.scope.name || "blamejs"),
+      pb.string(2, b.scope.version || ""),
+    ]);
+    var spansRepeated = pb.repeatedMessage(2, b.spans, _spanToProto);
+    var scopeSpansBody = Buffer.concat([
+      pb.embeddedMessage(1, scopeBody),
+      spansRepeated,
+    ]);
+    var resourceSpansBody = Buffer.concat([
+      pb.embeddedMessage(1, resourceBody),
+      pb.embeddedMessage(2, scopeSpansBody),
+    ]);
+    resourceSpansPieces.push(pb.embeddedMessage(1, resourceSpansBody));
+  }
+  return Buffer.concat(resourceSpansPieces);
+}
+
 function create(opts) {
   validateOpts.requireObject(opts, "otlpExporter", OtlpExporterError);
   validateOpts(opts, [
@@ -196,6 +412,7 @@ function create(opts) {
     "flushIntervalMs", "timeoutMs", "maxAttempts",
     "backoffInitialMs", "backoffMaxMs",
     "fetchImpl", "audit", "allowedProtocols",
+    "encoding",
   ], "otlpExporter.create");
   validateOpts.requireNonEmptyString(opts.endpoint,
     "otlpExporter.create: endpoint", OtlpExporterError, "otlp/bad-endpoint");
@@ -224,8 +441,24 @@ function create(opts) {
     "otlpExporter.create: maxAttempts", OtlpExporterError, "otlp/bad-opts");
 
   var endpoint   = opts.endpoint;
+  // OTLP §3 — operators with high-volume traces opt into the binary
+  // `application/x-protobuf` encoding via `opts.encoding: "protobuf"`
+  // (composes lib/protobuf-encoder.js for the wire-level emission).
+  // Default stays `"json"` for backward compatibility with existing
+  // collectors. The third encoding option (`"http/protobuf"` per the
+  // OTLP spec wording) is an alias for "protobuf".
+  var encoding = opts.encoding || "json";
+  if (encoding === "http/protobuf") encoding = "protobuf";
+  if (encoding !== "json" && encoding !== "protobuf") {
+    throw new OtlpExporterError("otlp/bad-encoding",
+      "otlpExporter.create: opts.encoding must be \"json\" or \"protobuf\" (got " +
+      JSON.stringify(opts.encoding) + ")");
+  }
+  var contentType = encoding === "protobuf"
+    ? "application/x-protobuf"
+    : "application/json";
   var headers    = Object.assign({
-    "Content-Type": "application/json",
+    "Content-Type": contentType,
   }, opts.headers || {});
   var batchSize  = opts.batchSize     || DEFAULT_BATCH_SIZE;
   var maxQueue   = opts.maxQueueSize  || DEFAULT_MAX_QUEUE_SIZE;
@@ -298,10 +531,14 @@ function create(opts) {
     var ac = (typeof AbortController === "function") ? new AbortController() : null;
     var t = ac ? setTimeout(function () { ac.abort(); }, timeoutMs) : null;
     try {
+      // The flush() path now passes EITHER a JSON-shape object (encoding
+      // "json") OR an already-encoded Buffer (encoding "protobuf").
+      // Stringify only the JSON path; pass the Buffer through.
+      var body = Buffer.isBuffer(payload) ? payload : JSON.stringify(payload);
       var res = await fetchImpl(endpoint, {
         method:  "POST",
         headers: headers,
-        body:    JSON.stringify(payload),
+        body:    body,
         signal:  ac ? ac.signal : undefined,
       });
       if (res && res.ok) return { ok: true, status: res.status };
@@ -343,7 +580,12 @@ function create(opts) {
     inFlight = true;
     try {
       var batch = queue.splice(0, batchSize);
-      var payload = _bundleSpans(batch);
+      // OTLP §3 — JSON encoding emits the resourceSpans envelope as
+      // JSON; protobuf encoding emits the same shape as binary
+      // ExportTraceServiceRequest bytes.
+      var payload = encoding === "protobuf"
+        ? _bundleSpansToProto(batch)
+        : _bundleSpans(batch);
       var result = await _post(payload, 1);
       if (result.ok) {
         _emitMetric("export_ok", batch.length, { http_status: String(result.status) });

package/lib/protobuf-encoder.js

@@ -95,27 +95,103 @@ function uint64(fieldNumber, value) {
   return Buffer.concat([_tag(fieldNumber, WIRE_VARINT), _writeVarint(value)]);
 }
 
+function int64(fieldNumber, value) {
+  // proto3 int64: wire-type 0 varint. Negatives encode as the 64-bit
+  // two's-complement reinterpret-cast to uint64, which always sets the
+  // top bit — every negative int64 occupies the full 10 varint bytes
+  // per the spec. https://protobuf.dev/programming-guides/encoding/#signed-ints
+  if (value === 0 || value === 0n) return Buffer.alloc(0);  // proto3 default
+  var bi;
+  if (typeof value === "bigint") {
+    bi = value;
+  } else if (typeof value === "number") {
+    if (!Number.isFinite(value) || !Number.isInteger(value)) {
+      throw new Error("protobuf-encoder: int64 must be finite integer (got " + value + ")");
+    }
+    bi = BigInt(value);
+  } else {
+    throw new Error("protobuf-encoder: int64 must be number or bigint, got " + typeof value);
+  }
+  // Refuse out-of-range — proto int64 is [-2^63, 2^63 - 1].
+  if (bi < -(1n << 63n) || bi > (1n << 63n) - 1n) {
+    throw new Error("protobuf-encoder: int64 out of range (got " + bi.toString() + ")");
+  }
+  if (bi < 0n) bi = bi + (1n << 64n);     // two's-complement reinterpret
+  return Buffer.concat([_tag(fieldNumber, WIRE_VARINT), _writeVarint(bi)]);
+}
+
+function sint64(fieldNumber, value) {
+  // proto3 sint64: wire-type 0 varint with ZigZag encoding —
+  // small negatives encode compactly. https://protobuf.dev/programming-guides/encoding/#signed-ints
+  if (value === 0 || value === 0n) return Buffer.alloc(0);
+  var bi;
+  if (typeof value === "bigint") bi = value;
+  else if (typeof value === "number") {
+    if (!Number.isFinite(value) || !Number.isInteger(value)) {
+      throw new Error("protobuf-encoder: sint64 must be finite integer (got " + value + ")");
+    }
+    bi = BigInt(value);
+  } else {
+    throw new Error("protobuf-encoder: sint64 must be number or bigint, got " + typeof value);
+  }
+  if (bi < -(1n << 63n) || bi > (1n << 63n) - 1n) {
+    throw new Error("protobuf-encoder: sint64 out of range (got " + bi.toString() + ")");
+  }
+  // ZigZag: (n << 1) ^ (n >> 63) for 64-bit signed.
+  var zz = (bi << 1n) ^ (bi >> 63n);
+  if (zz < 0n) zz = zz + (1n << 64n);
+  return Buffer.concat([_tag(fieldNumber, WIRE_VARINT), _writeVarint(zz)]);
+}
+
 function bool(fieldNumber, value) {
   if (!value) return Buffer.alloc(0);  // proto3 default
   return Buffer.concat([_tag(fieldNumber, WIRE_VARINT), Buffer.from([1])]);
 }
 
 function fixed64(fieldNumber, value) {
-  // For OTel: time_unix_nano fields are fixed64. Accept BigInt or
-  // Number; encode as little-endian 8 bytes.
+  // For OTel: time_unix_nano fields are fixed64. Accept BigInt, Number,
+  // or string-form digits (OTLP/JSON encodes uint64 as a JSON string per
+  // https://protobuf.dev/programming-guides/proto3/#json; the framework
+  // tracer emits strings for that reason and the same value flows into
+  // both encoding paths). Encode as little-endian 8 bytes.
   var buf = Buffer.alloc(FIXED64_BYTES);
+  var bi;
   if (typeof value === "bigint") {
-    buf.writeBigUInt64LE(value, 0);
-  } else {
+    bi = value;
+  } else if (typeof value === "string") {
+    // Char-code walk rather than /^[0-9]+$/ — that exact regex already
+    // appears in guard-cidr + guard-domain; the codebase-patterns
+    // duplicate-regex detector fires at the 3rd file (same shape as the
+    // SemVer-pre-release walk in lib/self-update.js).
+    if (value.length === 0) {
+      throw new Error("protobuf-encoder: fixed64 string must be non-empty unsigned digit-only");
+    }
+    for (var ci = 0; ci < value.length; ci += 1) {
+      var cc = value.charCodeAt(ci);
+      if (cc < 0x30 || cc > 0x39) {                                                  // allow:raw-byte-literal — ASCII '0' (0x30) .. '9' (0x39)
+        throw new Error("protobuf-encoder: fixed64 string must be unsigned digit-only (got " + JSON.stringify(value) + ")");
+      }
+    }
+    bi = BigInt(value);
+  } else if (typeof value === "number") {
     if (value < 0 || !Number.isFinite(value)) {
       throw new Error("protobuf-encoder: fixed64 must be non-negative finite (got " + value + ")");
     }
-    // Number path — split into low/high 32-bit halves.
-    var low  = value % 0x100000000;
-    var high = Math.floor(value / 0x100000000);
-    buf.writeUInt32LE(low,  0);
-    buf.writeUInt32LE(high, 4);
+    // Refuse silently-rounded values beyond Number.MAX_SAFE_INTEGER —
+    // the caller MUST pass a BigInt or string in that range. JS doubles
+    // lose precision past 2^53 so a Number 1779518164402000000 isn't
+    // actually that exact value once it touches Number arithmetic.
+    if (value > Number.MAX_SAFE_INTEGER) {
+      throw new Error("protobuf-encoder: fixed64 Number above MAX_SAFE_INTEGER loses precision; pass a BigInt or digit-string (got " + value + ")");
+    }
+    bi = BigInt(value);
+  } else {
+    throw new Error("protobuf-encoder: fixed64 must be bigint, number, or digit-string (got " + typeof value + ")");
+  }
+  if (bi < 0n || bi > (1n << 64n) - 1n) {
+    throw new Error("protobuf-encoder: fixed64 out of uint64 range (got " + bi.toString() + ")");
   }
+  buf.writeBigUInt64LE(bi, 0);
   return Buffer.concat([_tag(fieldNumber, WIRE_64BIT), buf]);
 }
 
@@ -177,6 +253,8 @@ function repeatedMessage(fieldNumber, items, perItemBodyEncoder) {
 module.exports = {
   uint32:           uint32,
   uint64:           uint64,
+  int64:            int64,
+  sint64:           sint64,
   bool:             bool,
   fixed64:          fixed64,
   double:           double,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blamejs/core",
-  "version": "0.12.5",
+  "version": "0.12.6",
   "description": "The Node framework that owns its stack.",
   "license": "Apache-2.0",
   "author": "blamejs contributors",

package/sbom.cdx.json

@@ -2,10 +2,10 @@
   "$schema": "http://cyclonedx.org/schema/bom-1.5.schema.json",
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:235e9ad1-2dfa-4fef-925d-f259dea69771",
+  "serialNumber": "urn:uuid:2423e5f5-adb5-48ea-a16f-ac28b6bd36e9",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-05-23T01:36:17.867Z",
+    "timestamp": "2026-05-23T07:07:57.784Z",
     "lifecycles": [
       {
         "phase": "build"
@@ -19,14 +19,14 @@
       }
     ],
     "component": {
-      "bom-ref": "@blamejs/core@0.12.5",
+      "bom-ref": "@blamejs/core@0.12.6",
       "type": "application",
       "name": "blamejs",
-      "version": "0.12.5",
+      "version": "0.12.6",
       "scope": "required",
       "author": "blamejs contributors",
       "description": "The Node framework that owns its stack.",
-      "purl": "pkg:npm/%40blamejs/core@0.12.5",
+      "purl": "pkg:npm/%40blamejs/core@0.12.6",
       "properties": [],
       "externalReferences": [
         {
@@ -54,7 +54,7 @@
   "components": [],
   "dependencies": [
     {
-      "ref": "@blamejs/core@0.12.5",
+      "ref": "@blamejs/core@0.12.6",
       "dependsOn": []
     }
   ]