@noego/telemetry 0.0.1

package/dist/trace-adapter/index.js

@@ -0,0 +1,1007 @@
+/* @noego/telemetry */
+
+// src/adapters/trace/trace_telemetry_adapter.ts
+var TraceTelemetryAdapter = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  attachTraceManager(manager) {
+    return manager.registerSink((event) => {
+      this.admitTraceEvent(event);
+    });
+  }
+  admitTraceEvent(input) {
+    const parsed = this.parseTraceEvent(input);
+    if (!parsed.ok) {
+      return this.client.admit(this.invalidAdmission("trace.invalid", parsed.error));
+    }
+    return this.client.admit({
+      source: parsed.value.source,
+      processKind: parsed.value.process,
+      level: this.numericLevel(parsed.value.level),
+      label: parsed.value.label,
+      occurredAtMs: parsed.value.occurredAtMs,
+      monotonicNs: null,
+      conversationId: parsed.value.conversationId,
+      correlationId: parsed.value.correlationId,
+      metadata: parsed.value.metadata
+    });
+  }
+  admitWoodEvent(input) {
+    const parsed = this.parseWoodEvent(input);
+    if (!parsed.ok) {
+      return this.client.admit(this.invalidAdmission("wood.invalid", parsed.error));
+    }
+    return this.client.admit({
+      source: parsed.value.source,
+      processKind: parsed.value.process,
+      level: parsed.value.level,
+      label: parsed.value.label,
+      occurredAtMs: parsed.value.occurredAtMs,
+      monotonicNs: null,
+      conversationId: parsed.value.conversationId,
+      correlationId: parsed.value.correlationId,
+      metadata: parsed.value.metadata
+    });
+  }
+  admitScoped(input) {
+    const correlation = this.correlationFromMetadata(input.metadata);
+    return this.client.admit({
+      source: input.source,
+      processKind: input.processKind,
+      level: input.level,
+      label: input.label,
+      occurredAtMs: input.occurredAtMs,
+      monotonicNs: null,
+      conversationId: correlation.conversationId,
+      correlationId: correlation.correlationId,
+      metadata: input.metadata
+    });
+  }
+  parseTraceEvent(input) {
+    if (!this.isRecord(input)) {
+      return { ok: false, error: "Trace event must be an object" };
+    }
+    const timestamp = input.timestamp;
+    const source = input.source;
+    const label = input.event;
+    const level = input.level;
+    if (typeof timestamp !== "number" || !Number.isFinite(timestamp)) {
+      return { ok: false, error: "Trace event timestamp is invalid" };
+    }
+    if (typeof source !== "string" || typeof label !== "string" || typeof level !== "number") {
+      return { ok: false, error: "Trace event identity is invalid" };
+    }
+    const metadata = this.mergeMessage(input.context, input.message);
+    const correlation = this.correlationFromMetadata(metadata);
+    return {
+      ok: true,
+      value: {
+        source,
+        process: typeof input.process === "string" ? input.process : "unknown",
+        level,
+        label,
+        occurredAtMs: timestamp,
+        conversationId: correlation.conversationId,
+        correlationId: correlation.correlationId,
+        metadata
+      }
+    };
+  }
+  parseWoodEvent(input) {
+    if (!this.isRecord(input)) {
+      return { ok: false, error: "Wood trace event must be an object" };
+    }
+    const source = input.source;
+    const label = input.type;
+    const level = input.level;
+    const timestamp = input.timestamp;
+    if (typeof source !== "string" || typeof label !== "string" || typeof level !== "string") {
+      return { ok: false, error: "Wood trace event identity is invalid" };
+    }
+    const occurredAtMs = typeof timestamp === "string" ? Date.parse(timestamp) : Number.NaN;
+    if (!Number.isFinite(occurredAtMs)) {
+      return { ok: false, error: "Wood trace event timestamp is invalid" };
+    }
+    const metadata = this.copyRecord(input.payload);
+    if (typeof input.message === "string") {
+      metadata.message = input.message;
+    }
+    if (typeof input.traceSeq === "number") {
+      metadata.woodTraceSeq = input.traceSeq;
+    }
+    const topConversation = this.scalarConversationId(input.conversationId);
+    const correlation = this.correlationFromMetadata(metadata);
+    return {
+      ok: true,
+      value: {
+        source,
+        process: typeof input.process === "string" ? input.process : "unknown",
+        level,
+        label,
+        occurredAtMs,
+        conversationId: topConversation ?? correlation.conversationId,
+        correlationId: correlation.correlationId,
+        metadata
+      }
+    };
+  }
+  correlationFromMetadata(input) {
+    if (!this.isRecord(input)) {
+      return { conversationId: null, correlationId: null };
+    }
+    const conversationId = this.scalarConversationId(input.conversationId) ?? this.scalarConversationId(input.threadId);
+    const correlationId = typeof input.correlationId === "string" ? input.correlationId : null;
+    return { conversationId, correlationId };
+  }
+  scalarConversationId(value) {
+    return typeof value === "string" || typeof value === "number" ? value : null;
+  }
+  mergeMessage(context, message) {
+    const metadata = this.copyRecord(context);
+    if (typeof message === "string") {
+      metadata.message = message;
+    }
+    return metadata;
+  }
+  copyRecord(input) {
+    if (!this.isRecord(input)) {
+      return {};
+    }
+    let keys;
+    try {
+      keys = Object.keys(input);
+    } catch {
+      return { __telemetryAdapter: "[property-enumeration-failed]" };
+    }
+    const output = {};
+    for (const key of keys) {
+      try {
+        output[key] = Reflect.get(input, key);
+      } catch {
+        output[key] = "[property-read-failed]";
+      }
+    }
+    return output;
+  }
+  numericLevel(level) {
+    switch (level) {
+      case 0:
+        return "debug";
+      case 1:
+        return "info";
+      case 2:
+        return "warn";
+      case 3:
+        return "error";
+      default:
+        return "debug";
+    }
+  }
+  invalidAdmission(label, error) {
+    return {
+      source: "telemetry-adapter",
+      processKind: "unknown",
+      level: "warn",
+      label,
+      occurredAtMs: Date.now(),
+      monotonicNs: null,
+      conversationId: null,
+      correlationId: null,
+      metadata: { error }
+    };
+  }
+  isRecord(value) {
+    try {
+      return typeof value === "object" && value !== null && !Array.isArray(value);
+    } catch {
+      return false;
+    }
+  }
+};
+
+// src/core/helper/canonical_json.ts
+var UTF8_ENCODER = new TextEncoder();
+function compareCanonicalKeys(left, right) {
+  if (left === right) return 0;
+  if (/^[\x00-\x7f]*$/.test(left) && /^[\x00-\x7f]*$/.test(right)) {
+    return left < right ? -1 : 1;
+  }
+  const leftBytes = UTF8_ENCODER.encode(left);
+  const rightBytes = UTF8_ENCODER.encode(right);
+  const length = Math.min(leftBytes.length, rightBytes.length);
+  for (let index = 0; index < length; index += 1) {
+    const difference = (leftBytes[index] ?? 0) - (rightBytes[index] ?? 0);
+    if (difference !== 0) return difference;
+  }
+  return leftBytes.length - rightBytes.length;
+}
+function canonicalJson(value) {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return JSON.stringify(value);
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new Error("Canonical telemetry JSON cannot encode a non-finite number");
+    }
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    const items = value.map((item) => canonicalJson(item));
+    return `[${items.join(",")}]`;
+  }
+  if (typeof value !== "object") {
+    throw new Error(`Canonical telemetry JSON cannot encode ${typeof value}`);
+  }
+  const entries = Object.entries(value).sort(([left], [right]) => compareCanonicalKeys(left, right));
+  const properties = entries.map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`);
+  return `{${properties.join(",")}}`;
+}
+function telemetryUtf8Length(value) {
+  return new TextEncoder().encode(value).byteLength;
+}
+function telemetryChecksum(value) {
+  const bytes = new TextEncoder().encode(canonicalJson(value));
+  let hash = 0xcbf29ce484222325n;
+  const prime = 0x100000001b3n;
+  for (const byte of bytes) {
+    hash ^= BigInt(byte);
+    hash = BigInt.asUintN(64, hash * prime);
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+
+// src/core/bounded_metadata_snapshotter.ts
+var SENTINEL_CIRCULAR = "[telemetry:circular]";
+var SENTINEL_TRUNCATED = "[telemetry:truncated]";
+var BoundedMetadataSnapshotter = class {
+  constructor(limits) {
+    this.limits = limits;
+    this.validateLimits();
+  }
+  limits;
+  snapshot(input) {
+    const state = {
+      bytes: 0,
+      properties: 0,
+      truncatedValues: 0,
+      redactedValues: 0,
+      serializationFailures: 0,
+      seen: /* @__PURE__ */ new WeakSet()
+    };
+    let normalized;
+    try {
+      normalized = this.normalize(input, "$", 0, state);
+    } catch {
+      state.serializationFailures += 1;
+      normalized = { __telemetry: "[telemetry:snapshot-failed]" };
+    }
+    const root = this.ensureObject(normalized);
+    const canonical = canonicalJson(root);
+    const metadata = telemetryUtf8Length(canonical) <= this.limits.maxBytes ? root : Object.freeze({ __telemetry: SENTINEL_TRUNCATED });
+    if (metadata !== root) {
+      state.truncatedValues += 1;
+    }
+    const stats = Object.freeze({
+      estimatedBytes: Math.min(telemetryUtf8Length(canonical), this.limits.maxBytes),
+      truncatedValues: state.truncatedValues,
+      redactedValues: state.redactedValues,
+      serializationFailures: state.serializationFailures
+    });
+    return Object.freeze({ metadata, stats });
+  }
+  normalize(input, path, depth, state) {
+    const replacement = this.redactionFor(path);
+    if (replacement !== null) {
+      state.redactedValues += 1;
+      return replacement;
+    }
+    if (depth > this.limits.maxDepth || state.bytes >= this.limits.maxBytes) {
+      state.truncatedValues += 1;
+      return SENTINEL_TRUNCATED;
+    }
+    if (input === null || typeof input === "boolean") {
+      return input;
+    }
+    if (typeof input === "string") {
+      return this.normalizeString(input, state);
+    }
+    if (typeof input === "number") {
+      return Number.isFinite(input) ? input : `[telemetry:number:${String(input)}]`;
+    }
+    if (typeof input === "bigint") {
+      return `[telemetry:bigint:${input.toString()}]`;
+    }
+    if (typeof input === "undefined") {
+      return "[telemetry:undefined]";
+    }
+    if (typeof input === "symbol") {
+      return `[telemetry:symbol:${input.description ?? ""}]`;
+    }
+    if (typeof input === "function") {
+      return "[telemetry:function]";
+    }
+    if (input instanceof Error) {
+      return this.normalizeError(input, path, depth, state);
+    }
+    if (typeof input !== "object") {
+      return `[telemetry:unsupported:${typeof input}]`;
+    }
+    if (state.seen.has(input)) {
+      return SENTINEL_CIRCULAR;
+    }
+    state.seen.add(input);
+    try {
+      return Array.isArray(input) ? this.normalizeArray(input, path, depth, state) : this.normalizeObject(input, path, depth, state);
+    } finally {
+      state.seen.delete(input);
+    }
+  }
+  normalizeString(input, state) {
+    const stringLimit = Math.min(this.limits.maxStringLength, Math.max(0, this.limits.maxBytes - state.bytes));
+    const truncated = input.length > stringLimit;
+    const normalized = truncated ? input.slice(0, stringLimit) : input;
+    state.bytes += telemetryUtf8Length(normalized);
+    if (truncated) {
+      state.truncatedValues += 1;
+    }
+    return normalized;
+  }
+  normalizeArray(input, path, depth, state) {
+    const length = Math.min(input.length, this.limits.maxArrayLength);
+    const values = [];
+    for (let index = 0; index < length; index += 1) {
+      let item;
+      try {
+        item = input[index];
+      } catch {
+        state.serializationFailures += 1;
+        item = "[telemetry:property-read-failed]";
+      }
+      values.push(this.normalize(item, `${path}[${index}]`, depth + 1, state));
+    }
+    if (input.length > length) {
+      values.push(SENTINEL_TRUNCATED);
+      state.truncatedValues += 1;
+    }
+    return Object.freeze(values);
+  }
+  normalizeObject(input, path, depth, state) {
+    let keys;
+    try {
+      keys = Object.keys(input).sort((left, right) => left.localeCompare(right));
+    } catch {
+      state.serializationFailures += 1;
+      return Object.freeze({ __telemetry: "[telemetry:keys-failed]" });
+    }
+    const output = {};
+    for (const key of keys) {
+      if (state.properties >= this.limits.maxProperties) {
+        output.__telemetry = SENTINEL_TRUNCATED;
+        state.truncatedValues += 1;
+        break;
+      }
+      state.properties += 1;
+      state.bytes += telemetryUtf8Length(key);
+      const childPath = path === "$" ? key : `${path}.${key}`;
+      const redaction = this.redactionFor(childPath);
+      if (redaction !== null) {
+        output[key] = redaction;
+        state.redactedValues += 1;
+        continue;
+      }
+      let property;
+      try {
+        property = Reflect.get(input, key);
+      } catch {
+        state.serializationFailures += 1;
+        property = "[telemetry:property-read-failed]";
+      }
+      output[key] = this.normalize(property, childPath, depth + 1, state);
+    }
+    return Object.freeze(output);
+  }
+  normalizeError(error, path, depth, state) {
+    const name = this.readErrorField(error, "name", state);
+    const message = this.readErrorField(error, "message", state);
+    const stack = this.readErrorField(error, "stack", state).slice(0, this.limits.maxErrorStackLength);
+    return Object.freeze({
+      name: this.normalize(name, `${path}.name`, depth + 1, state),
+      message: this.normalize(message, `${path}.message`, depth + 1, state),
+      stack: this.normalize(stack, `${path}.stack`, depth + 1, state)
+    });
+  }
+  readErrorField(error, field, state) {
+    try {
+      return typeof error[field] === "string" ? error[field] : "";
+    } catch {
+      state.serializationFailures += 1;
+      return "[telemetry:error-field-read-failed]";
+    }
+  }
+  ensureObject(value) {
+    return this.isJsonObject(value) ? value : Object.freeze({ value });
+  }
+  isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+  }
+  redactionFor(path) {
+    const matchingRule = this.limits.redactions.find((rule) => rule.path === path);
+    return matchingRule?.replacement ?? null;
+  }
+  validateLimits() {
+    const limits = [
+      this.limits.maxBytes,
+      this.limits.maxDepth,
+      this.limits.maxProperties,
+      this.limits.maxArrayLength,
+      this.limits.maxStringLength,
+      this.limits.maxErrorStackLength
+    ];
+    const hasInvalidLimit = limits.some((limit) => !Number.isInteger(limit) || limit <= 0);
+    if (hasInvalidLimit) {
+      throw new Error("Metadata snapshot limits must be positive integers");
+    }
+  }
+};
+
+// src/core/helper/client_defaults.ts
+var DEFAULT_TELEMETRY_ADMISSION_POLICY = Object.freeze({
+  maxQueuedEvents: 2e3,
+  maxQueuedBytes: 2e6,
+  maxBatchEvents: 128,
+  maxBatchBytes: 256e3,
+  maxInFlightBatches: 1,
+  retryLimit: 3,
+  retryBaseDelayMs: 25,
+  sampleRates: Object.freeze({
+    low: 1,
+    normal: 1,
+    high: 1
+  })
+});
+var DEFAULT_METADATA_SNAPSHOT_LIMITS = Object.freeze({
+  maxBytes: 32768,
+  maxDepth: 8,
+  maxProperties: 256,
+  maxArrayLength: 128,
+  maxStringLength: 4096,
+  maxErrorStackLength: 8192,
+  redactions: Object.freeze([])
+});
+var DEFAULT_TELEMETRY_BATCH_VALIDATION_LIMITS = Object.freeze({
+  maxBatchEvents: 1024,
+  maxBatchBytes: 1e6,
+  maxEventBytes: 256e3,
+  maxMetadataBytes: 131072,
+  maxMetadataDepth: 16,
+  maxMetadataProperties: 1024,
+  maxMetadataArrayLength: 1024,
+  maxMetadataStringBytes: 65536,
+  maxDropCounters: 15,
+  maxIdentityBytes: 1024
+});
+
+// src/core/telemetry_batch_contract.ts
+var BATCH_KEYS = Object.freeze([
+  "schemaVersion",
+  "producerId",
+  "sequenceStart",
+  "sequenceEnd",
+  "idempotencyKey",
+  "checksum",
+  "envelopes",
+  "dropCounters"
+]);
+var ENVELOPE_KEYS = Object.freeze([
+  "schemaVersion",
+  "eventId",
+  "producerId",
+  "sequence",
+  "occurredAtMs",
+  "monotonicNs",
+  "source",
+  "processKind",
+  "level",
+  "label",
+  "conversationId",
+  "correlationId",
+  "metadata"
+]);
+var DROP_COUNTER_KEYS = Object.freeze(["reason", "priority", "count"]);
+var DROP_REASONS = /* @__PURE__ */ new Set(["capacity", "sampled", "stopped", "invalid", "transport"]);
+var DROP_PRIORITIES = /* @__PURE__ */ new Set(["low", "normal", "high"]);
+var TelemetryBatchContract = class _TelemetryBatchContract {
+  static schemaVersion = 1;
+  static checksumAlgorithm = "fnv1a64-canonical-json-v1";
+  limits;
+  constructor(limits = {}) {
+    this.limits = Object.freeze({
+      ...DEFAULT_TELEMETRY_BATCH_VALIDATION_LIMITS,
+      ...limits
+    });
+    this.validateLimits();
+  }
+  create(envelopes, dropCounters) {
+    try {
+      return this.createChecked(envelopes, dropCounters);
+    } catch {
+      return { ok: false, error: "Telemetry batch creation failed safe validation" };
+    }
+  }
+  validate(batch) {
+    try {
+      return this.validateChecked(batch);
+    } catch {
+      return { ok: false, error: "Telemetry batch validation failed safely" };
+    }
+  }
+  createChecked(envelopes, dropCounters) {
+    const payloadError = this.validatePayload(envelopes, dropCounters);
+    if (payloadError !== null) {
+      return { ok: false, error: payloadError };
+    }
+    const payloadBytesError = this.payloadBytesError(envelopes, dropCounters);
+    if (payloadBytesError !== null) {
+      return { ok: false, error: payloadBytesError };
+    }
+    const first = envelopes[0];
+    const last = envelopes[envelopes.length - 1];
+    if (!first || !last) {
+      return { ok: false, error: "A telemetry batch must contain a first and last envelope" };
+    }
+    const producerId = first.producerId;
+    const sequenceStart = first.sequence;
+    const sequenceEnd = last.sequence;
+    const checksumPayload = this.checksumPayload(
+      producerId,
+      sequenceStart,
+      sequenceEnd,
+      envelopes,
+      dropCounters
+    );
+    const checksum = telemetryChecksum(checksumPayload);
+    const idempotencyKey = `tb1:${producerId}:${sequenceStart}-${sequenceEnd}:${checksum}`;
+    const batch = Object.freeze({
+      schemaVersion: _TelemetryBatchContract.schemaVersion,
+      producerId,
+      sequenceStart,
+      sequenceEnd,
+      idempotencyKey,
+      checksum,
+      envelopes: Object.freeze([...envelopes]),
+      dropCounters: Object.freeze([...dropCounters])
+    });
+    const framingError = this.validateFraming(batch);
+    if (framingError !== null) {
+      return { ok: false, error: framingError };
+    }
+    const byteError = this.serializedByteError(batch, this.limits.maxBatchBytes, "batch");
+    return byteError === null ? { ok: true, value: this.detachBatch(batch) } : { ok: false, error: byteError };
+  }
+  validateChecked(batch) {
+    if (!this.isRecord(batch)) {
+      return { ok: false, error: "Telemetry batch must be a plain object" };
+    }
+    const schemaVersion = batch.schemaVersion;
+    if (!Number.isSafeInteger(schemaVersion)) {
+      return { ok: false, error: "Telemetry batch schema version must be a safe integer" };
+    }
+    if (schemaVersion !== _TelemetryBatchContract.schemaVersion) {
+      return { ok: false, error: `Unsupported telemetry schema version ${String(schemaVersion)}` };
+    }
+    if (!this.hasExactKeys(batch, BATCH_KEYS)) {
+      return { ok: false, error: "Telemetry batch fields do not match the schema" };
+    }
+    const framingError = this.validateFraming(batch);
+    if (framingError !== null) {
+      return { ok: false, error: framingError };
+    }
+    const recreated = this.create(
+      batch.envelopes,
+      batch.dropCounters
+    );
+    if (!recreated.ok) {
+      return recreated;
+    }
+    const identityError = this.compareFraming(batch, recreated.value);
+    return identityError === null ? { ok: true, value: recreated.value } : { ok: false, error: identityError };
+  }
+  validatePayload(envelopes, dropCounters) {
+    if (!Array.isArray(envelopes) || envelopes.length === 0) {
+      return "A telemetry batch must contain at least one envelope";
+    }
+    if (envelopes.length > this.limits.maxBatchEvents) {
+      return `Telemetry batch exceeds ${this.limits.maxBatchEvents} envelopes`;
+    }
+    const envelopeError = this.validateEnvelopes(envelopes);
+    return envelopeError ?? this.validateDropCounters(dropCounters);
+  }
+  validateEnvelopes(envelopes) {
+    let previousSequence = -1;
+    let producerId = null;
+    for (const envelope of envelopes) {
+      const envelopeError = this.validateEnvelope(envelope, producerId, previousSequence);
+      if (envelopeError !== null) {
+        return envelopeError;
+      }
+      const typedEnvelope = envelope;
+      producerId = typedEnvelope.producerId;
+      previousSequence = typedEnvelope.sequence;
+    }
+    return null;
+  }
+  validateEnvelope(envelope, expectedProducerId, previousSequence) {
+    if (!this.isRecord(envelope) || !this.hasExactKeys(envelope, ENVELOPE_KEYS)) {
+      return "Telemetry envelope fields do not match the schema";
+    }
+    const identityError = this.validateEnvelopeIdentity(envelope, expectedProducerId, previousSequence);
+    if (identityError !== null) {
+      return identityError;
+    }
+    const valueError = this.validateEnvelopeValues(envelope);
+    if (valueError !== null) {
+      return valueError;
+    }
+    const metadataError = this.validateMetadata(envelope.metadata);
+    return metadataError ?? this.serializedByteError(envelope, this.limits.maxEventBytes, "event");
+  }
+  validateEnvelopeIdentity(envelope, expectedProducerId, previousSequence) {
+    if (envelope.schemaVersion !== _TelemetryBatchContract.schemaVersion) {
+      return "Telemetry envelope schema version does not match its batch";
+    }
+    if (!this.isIdentity(envelope.producerId)) {
+      return "Telemetry envelope producer identity is invalid";
+    }
+    if (!this.isSequence(envelope.sequence) || envelope.sequence <= previousSequence) {
+      return "Telemetry envelope sequences must be nonnegative safe integers in increasing order";
+    }
+    if (expectedProducerId !== null && envelope.producerId !== expectedProducerId) {
+      return "A telemetry batch cannot mix producer identities";
+    }
+    const eventId = `${envelope.producerId}:${envelope.sequence}`;
+    if (envelope.eventId !== eventId || telemetryUtf8Length(eventId) > this.limits.maxIdentityBytes) {
+      return "Telemetry envelope event identity is invalid";
+    }
+    return null;
+  }
+  validateEnvelopeValues(envelope) {
+    if (!Number.isSafeInteger(envelope.occurredAtMs) || Number(envelope.occurredAtMs) < 0) {
+      return "Telemetry envelope occurredAtMs must be a nonnegative safe integer";
+    }
+    if (!this.isMonotonicTimestamp(envelope.monotonicNs)) {
+      return "Telemetry envelope monotonicNs is invalid";
+    }
+    if (!this.isIdentity(envelope.source) || !this.isIdentity(envelope.processKind)) {
+      return "Telemetry envelope source and process kind are invalid";
+    }
+    if (!this.isIdentity(envelope.level)) {
+      return "Telemetry envelope level is invalid";
+    }
+    if (!this.isLabel(envelope.label)) {
+      return "Telemetry envelope label is invalid";
+    }
+    if (!this.isConversationId(envelope.conversationId)) {
+      return "Telemetry envelope conversation identity is invalid";
+    }
+    if (!this.isOptionalBoundedString(envelope.correlationId)) {
+      return "Telemetry envelope correlation identity is invalid";
+    }
+    return null;
+  }
+  validateMetadata(metadata) {
+    if (!this.isRecord(metadata)) {
+      return "Telemetry envelope metadata must be a plain JSON object";
+    }
+    const state = { properties: 0, bytes: 0, active: /* @__PURE__ */ new WeakSet() };
+    const jsonError = this.validateJsonValue(metadata, 0, state);
+    return jsonError ?? this.serializedByteError(metadata, this.limits.maxMetadataBytes, "metadata");
+  }
+  validateJsonValue(value, depth, state) {
+    if (value === null || typeof value === "boolean") {
+      state.bytes += value === null ? 4 : 5;
+      return null;
+    }
+    if (typeof value === "number") {
+      if (!Number.isFinite(value)) {
+        return "Telemetry metadata contains a non-finite number";
+      }
+      state.bytes += String(value).length;
+      return this.metadataBudgetError(state);
+    }
+    if (typeof value === "string") {
+      if (!this.isWithinUtf8Limit(value, this.limits.maxMetadataStringBytes)) {
+        return "Telemetry metadata string exceeds the receiver limit";
+      }
+      state.bytes += telemetryUtf8Length(value);
+      return this.metadataBudgetError(state);
+    }
+    if (typeof value !== "object") {
+      return "Telemetry metadata contains a non-JSON value";
+    }
+    if (depth > this.limits.maxMetadataDepth) {
+      return "Telemetry metadata exceeds the receiver depth limit";
+    }
+    return Array.isArray(value) ? this.validateJsonArray(value, depth, state) : this.validateJsonObject(value, depth, state);
+  }
+  validateJsonArray(value, depth, state) {
+    if (value.length > this.limits.maxMetadataArrayLength) {
+      return "Telemetry metadata array exceeds the receiver length limit";
+    }
+    const keys = Object.keys(value);
+    if (keys.length !== value.length || Object.getOwnPropertySymbols(value).length > 0) {
+      return "Telemetry metadata arrays must be dense JSON arrays";
+    }
+    return this.validateJsonChildren(value, value, depth, state);
+  }
+  validateJsonObject(value, depth, state) {
+    if (!this.isRecord(value)) {
+      return "Telemetry metadata contains a non-plain object";
+    }
+    const keys = Object.keys(value);
+    if (Object.getOwnPropertySymbols(value).length > 0) {
+      return "Telemetry metadata objects cannot contain symbol keys";
+    }
+    state.properties += keys.length;
+    if (state.properties > this.limits.maxMetadataProperties) {
+      return "Telemetry metadata exceeds the receiver property limit";
+    }
+    if (keys.some((key) => !this.isWithinUtf8Limit(key, this.limits.maxMetadataStringBytes))) {
+      return "Telemetry metadata property name exceeds the receiver string limit";
+    }
+    for (const key of keys) {
+      state.bytes += telemetryUtf8Length(key);
+    }
+    const budgetError = this.metadataBudgetError(state);
+    if (budgetError !== null) {
+      return budgetError;
+    }
+    return this.validateJsonChildren(value, keys.map((key) => Reflect.get(value, key)), depth, state);
+  }
+  validateJsonChildren(owner, values, depth, state) {
+    if (state.active.has(owner)) {
+      return "Telemetry metadata cannot contain a cycle";
+    }
+    state.active.add(owner);
+    try {
+      for (const value of values) {
+        const error = this.validateJsonValue(value, depth + 1, state);
+        if (error !== null) {
+          return error;
+        }
+      }
+      return null;
+    } finally {
+      state.active.delete(owner);
+    }
+  }
+  validateDropCounters(dropCounters) {
+    if (!Array.isArray(dropCounters) || dropCounters.length > this.limits.maxDropCounters) {
+      return "Telemetry drop counters exceed the fixed receiver limit";
+    }
+    const identities = /* @__PURE__ */ new Set();
+    let total = 0;
+    for (const counter of dropCounters) {
+      const error = this.validateDropCounter(counter, identities, total);
+      if (error !== null) {
+        return error;
+      }
+      total += counter.count;
+    }
+    return null;
+  }
+  validateDropCounter(counter, identities, currentTotal) {
+    if (!this.isRecord(counter) || !this.hasExactKeys(counter, DROP_COUNTER_KEYS)) {
+      return "Telemetry drop counter fields do not match the schema";
+    }
+    if (!DROP_REASONS.has(String(counter.reason)) || !DROP_PRIORITIES.has(String(counter.priority))) {
+      return "Telemetry drop counter identity is invalid";
+    }
+    if (!Number.isSafeInteger(counter.count) || Number(counter.count) <= 0) {
+      return "Telemetry drop counter count must be a positive safe integer";
+    }
+    if (currentTotal > Number.MAX_SAFE_INTEGER - Number(counter.count)) {
+      return "Telemetry drop counter total exceeds the safe integer range";
+    }
+    const identity = `${counter.reason}:${counter.priority}`;
+    if (identities.has(identity)) {
+      return "Telemetry drop counter identities must be unique within a batch";
+    }
+    identities.add(identity);
+    return null;
+  }
+  validateFraming(batch) {
+    if (!this.isIdentity(batch.producerId)) {
+      return "Telemetry batch producer identity is invalid";
+    }
+    if (!this.isSequence(batch.sequenceStart) || !this.isSequence(batch.sequenceEnd)) {
+      return "Telemetry batch sequence range must use nonnegative safe integers";
+    }
+    if (Number(batch.sequenceEnd) < Number(batch.sequenceStart)) {
+      return "Telemetry batch sequence range is reversed";
+    }
+    if (typeof batch.checksum !== "string" || !/^[a-f0-9]{16}$/.test(batch.checksum)) {
+      return "Telemetry batch checksum is invalid";
+    }
+    if (typeof batch.idempotencyKey !== "string" || !this.isWithinUtf8Limit(batch.idempotencyKey, this.limits.maxIdentityBytes)) {
+      return "Telemetry batch idempotency identity is invalid";
+    }
+    return null;
+  }
+  compareFraming(batch, recreated) {
+    const matches = recreated.checksum === batch.checksum && recreated.idempotencyKey === batch.idempotencyKey && recreated.sequenceStart === batch.sequenceStart && recreated.sequenceEnd === batch.sequenceEnd && recreated.producerId === batch.producerId;
+    return matches ? null : "Telemetry batch framing or checksum is invalid";
+  }
+  checksumPayload(producerId, sequenceStart, sequenceEnd, envelopes, dropCounters) {
+    return {
+      schemaVersion: _TelemetryBatchContract.schemaVersion,
+      producerId,
+      sequenceStart,
+      sequenceEnd,
+      envelopes,
+      dropCounters
+    };
+  }
+  serializedByteError(value, maximum, kind) {
+    const bytes = telemetryUtf8Length(canonicalJson(value));
+    return bytes <= maximum ? null : `Telemetry ${kind} exceeds ${maximum} bytes`;
+  }
+  payloadBytesError(envelopes, dropCounters) {
+    let bytes = 0;
+    for (const envelope of envelopes) {
+      bytes += telemetryUtf8Length(canonicalJson(envelope));
+      if (bytes > this.limits.maxBatchBytes) {
+        return `Telemetry batch exceeds ${this.limits.maxBatchBytes} bytes`;
+      }
+    }
+    bytes += telemetryUtf8Length(canonicalJson(dropCounters));
+    return bytes > this.limits.maxBatchBytes ? `Telemetry batch exceeds ${this.limits.maxBatchBytes} bytes` : null;
+  }
+  metadataBudgetError(state) {
+    return state.bytes > this.limits.maxMetadataBytes ? `Telemetry metadata exceeds ${this.limits.maxMetadataBytes} bytes` : null;
+  }
+  detachBatch(batch) {
+    const detached = JSON.parse(canonicalJson(batch));
+    return this.deepFreeze(detached);
+  }
+  deepFreeze(value) {
+    if (typeof value !== "object" || value === null || Object.isFrozen(value)) {
+      return value;
+    }
+    for (const child of Object.values(value)) {
+      this.deepFreeze(child);
+    }
+    return Object.freeze(value);
+  }
+  isRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === null || prototype.constructor?.name === "Object";
+  }
+  hasExactKeys(value, expected) {
+    const keys = Object.keys(value);
+    return Object.getOwnPropertySymbols(value).length === 0 && keys.length === expected.length && expected.every((key) => Object.prototype.hasOwnProperty.call(value, key));
+  }
+  isSequence(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 0;
+  }
+  isIdentity(value) {
+    return typeof value === "string" && value.length <= this.limits.maxIdentityBytes && value.trim().length > 0 && this.isWithinUtf8Limit(value, this.limits.maxIdentityBytes) && !/[\u0000-\u001f\u007f]/.test(value);
+  }
+  isLabel(value) {
+    return typeof value === "string" && value.length <= Math.min(256, this.limits.maxIdentityBytes) && /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/.test(value) && this.isWithinUtf8Limit(value, Math.min(256, this.limits.maxIdentityBytes));
+  }
+  isMonotonicTimestamp(value) {
+    return value === null || typeof value === "string" && value.length <= this.limits.maxIdentityBytes && /^\d+$/.test(value) && this.isWithinUtf8Limit(value, this.limits.maxIdentityBytes);
+  }
+  isConversationId(value) {
+    return value === null || typeof value === "number" && Number.isSafeInteger(value) || typeof value === "string" && this.isWithinUtf8Limit(value, this.limits.maxIdentityBytes) && !/[\u0000-\u001f\u007f]/.test(value);
+  }
+  isOptionalBoundedString(value) {
+    return value === null || typeof value === "string" && this.isWithinUtf8Limit(value, this.limits.maxIdentityBytes) && !/[\u0000-\u001f\u007f]/.test(value);
+  }
+  isWithinUtf8Limit(value, maximum) {
+    return value.length <= maximum && telemetryUtf8Length(value) <= maximum;
+  }
+  validateLimits() {
+    const values = Object.values(this.limits);
+    if (values.some((value) => !Number.isSafeInteger(value) || value <= 0)) {
+      throw new Error("Telemetry batch validation limits must be positive safe integers");
+    }
+    if (this.limits.maxMetadataBytes > this.limits.maxEventBytes || this.limits.maxEventBytes > this.limits.maxBatchBytes) {
+      throw new Error("Telemetry receiver byte limits must satisfy metadata <= event <= batch");
+    }
+  }
+};
+
+// src/adapters/trace/wood_telemetry_batch_adapter.ts
+var WoodTelemetryBatchAdapter = class {
+  constructor(metadataLimits, producerIdPrefix = "wood-renderer:") {
+    this.producerIdPrefix = producerIdPrefix;
+    this.snapshotter = new BoundedMetadataSnapshotter(metadataLimits);
+  }
+  producerIdPrefix;
+  batchContract = new TelemetryBatchContract();
+  snapshotter;
+  create(batch, context = {}) {
+    try {
+      const identityError = this.validateBatchIdentity(batch);
+      if (identityError !== null) {
+        return { ok: false, error: identityError };
+      }
+      const producerId = `${this.producerIdPrefix}${batch.producerId}`;
+      const envelopes = batch.events.map((event) => {
+        return this.createEnvelope(producerId, batch, event, context);
+      });
+      return this.batchContract.create(envelopes, []);
+    } catch (cause) {
+      return { ok: false, error: this.errorMessage(cause) };
+    }
+  }
+  createEnvelope(producerId, batch, event, context) {
+    const sequence = event.traceSeq - 1;
+    const occurredAtMs = Date.parse(event.timestamp);
+    if (!Number.isSafeInteger(sequence) || sequence < 0 || !Number.isFinite(occurredAtMs)) {
+      throw new Error("Wood trace event timing is invalid");
+    }
+    if (!event.source.trim() || !event.type.trim() || !event.level.trim() || !event.process.trim()) {
+      throw new Error("Wood trace event identity is invalid");
+    }
+    const payload = this.snapshotter.snapshot(event.payload ?? {}).metadata;
+    const metadata = this.snapshotter.snapshot({
+      ...payload,
+      ...typeof event.message === "string" ? { message: event.message } : {},
+      woodTraceSeq: event.traceSeq,
+      __telemetryWoodBatchId: batch.batchId,
+      woodRendererProducerId: batch.producerId,
+      woodRendererSequenceStart: batch.sequenceStart,
+      woodRendererSequenceEnd: batch.sequenceEnd,
+      ...context
+    }).metadata;
+    const metadataConversationId = this.scalarConversationId(metadata.conversationId) ?? this.scalarConversationId(metadata.threadId);
+    const conversationId = this.scalarConversationId(event.conversationId) ?? metadataConversationId;
+    const correlationId = typeof metadata.correlationId === "string" ? metadata.correlationId : null;
+    return Object.freeze({
+      schemaVersion: 1,
+      eventId: `${producerId}:${sequence}`,
+      producerId,
+      sequence,
+      occurredAtMs,
+      monotonicNs: null,
+      source: event.source,
+      processKind: event.process,
+      level: event.level,
+      label: event.type,
+      conversationId,
+      correlationId,
+      metadata
+    });
+  }
+  validateBatchIdentity(batch) {
+    if (!batch.producerId.trim() || !batch.batchId.trim() || batch.events.length === 0) {
+      return "Wood trace batch identity is invalid";
+    }
+    const first = batch.events[0];
+    const last = batch.events[batch.events.length - 1];
+    const rangeMatches = first?.traceSeq === batch.sequenceStart + 1 && last?.traceSeq === batch.sequenceEnd + 1;
+    const sequencesIncrease = batch.events.every((event, index) => {
+      const previous = batch.events[index - 1];
+      return previous === void 0 || event.traceSeq > previous.traceSeq;
+    });
+    return rangeMatches && sequencesIncrease ? null : "Wood trace batch sequence range is invalid";
+  }
+  scalarConversationId(value) {
+    return typeof value === "string" || typeof value === "number" ? value : null;
+  }
+  errorMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+  }
+};
+export {
+  TraceTelemetryAdapter,
+  WoodTelemetryBatchAdapter
+};
+//# sourceMappingURL=index.js.map