@noego/telemetry 0.0.1

package/dist/core/index.js

@@ -0,0 +1,2318 @@
+/* @noego/telemetry */
+
+// 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/metric_definition_contract.ts
+var MetricDefinitionContract = class {
+  normalize(definition) {
+    const parsedSelector = this.parseSelector(definition.selector);
+    if (!parsedSelector.ok) {
+      return parsedSelector;
+    }
+    const bracketGroupBy = parsedSelector.value.groupBy;
+    const configuredGroupBy = definition.groupBy;
+    const bothSpecifyDifferentGrouping = bracketGroupBy.length > 0 && configuredGroupBy.length > 0 && bracketGroupBy.join(".") !== configuredGroupBy.join(".");
+    if (bothSpecifyDifferentGrouping) {
+      return { ok: false, error: `Metric ${definition.name} has conflicting selector and groupBy declarations` };
+    }
+    const groupBy = configuredGroupBy.length > 0 ? configuredGroupBy : bracketGroupBy;
+    const basicError = this.validateBasic(definition, parsedSelector.value.selector, groupBy);
+    if (basicError !== null) {
+      return { ok: false, error: basicError };
+    }
+    if (parsedSelector.value.wildcardUngrouped && definition.measurements.some((measurement) => measurement.kind !== "count")) {
+      return {
+        ok: false,
+        error: `Metric ${definition.name} uses [*] and may only declare count`
+      };
+    }
+    return {
+      ok: true,
+      value: Object.freeze({
+        ...definition,
+        selector: parsedSelector.value.selector,
+        groupBy: Object.freeze([...groupBy]),
+        resolutionsMs: Object.freeze([...definition.resolutionsMs].sort((left, right) => left - right)),
+        measurements: Object.freeze([...definition.measurements]),
+        targetIds: Object.freeze([...definition.targetIds]),
+        cardinality: Object.freeze({ ...definition.cardinality })
+      })
+    };
+  }
+  matches(selector, label) {
+    const selectorSegments = selector.split(".");
+    const labelSegments = label.split(".");
+    return this.matchSegments(selectorSegments, labelSegments, 0, 0);
+  }
+  parseSelector(selector) {
+    if (selector.startsWith("[")) {
+      return { ok: false, error: "A metric selector cannot omit its event label or glob" };
+    }
+    const bracketStart = selector.lastIndexOf("[");
+    if (bracketStart < 0) {
+      return { ok: true, value: { selector, groupBy: [], wildcardUngrouped: false } };
+    }
+    if (!selector.endsWith("]")) {
+      return { ok: false, error: `Invalid metric selector ${selector}` };
+    }
+    const eventSelector = selector.slice(0, bracketStart);
+    const bracket = selector.slice(bracketStart + 1, -1).trim();
+    if (!eventSelector || !bracket) {
+      return { ok: false, error: `Invalid metric selector ${selector}` };
+    }
+    return {
+      ok: true,
+      value: {
+        selector: eventSelector,
+        groupBy: bracket === "*" ? [] : [bracket],
+        wildcardUngrouped: bracket === "*"
+      }
+    };
+  }
+  validateBasic(definition, selector, groupBy) {
+    if (!/^[A-Za-z0-9_*][A-Za-z0-9_.:*\-]*$/.test(selector)) {
+      return `Metric ${definition.name} has an invalid selector`;
+    }
+    if (!/^[A-Za-z][A-Za-z0-9_]*$/.test(definition.name)) {
+      return `Metric name ${definition.name} is invalid`;
+    }
+    if (!Number.isInteger(definition.version) || definition.version <= 0) {
+      return `Metric ${definition.name} must have a positive integer version`;
+    }
+    if (definition.measurements.length === 0) {
+      return `Metric ${definition.name} must declare at least one measurement`;
+    }
+    const invalidResolution = definition.resolutionsMs.some(
+      (resolution) => !Number.isInteger(resolution) || resolution <= 0
+    );
+    const duplicateResolution = new Set(definition.resolutionsMs).size !== definition.resolutionsMs.length;
+    if (invalidResolution || duplicateResolution || definition.resolutionsMs.length === 0) {
+      return `Metric ${definition.name} has invalid or duplicate resolutions`;
+    }
+    const missingCardinality = groupBy.find((field) => definition.cardinality[field] === void 0);
+    if (missingCardinality) {
+      return `Metric ${definition.name} is missing cardinality policy for ${missingCardinality}`;
+    }
+    const invalidCardinality = Object.values(definition.cardinality).some(
+      (rule) => !Number.isInteger(rule.maxValuesPerBucket) || rule.maxValuesPerBucket <= 0
+    );
+    if (invalidCardinality) {
+      return `Metric ${definition.name} has an invalid cardinality limit`;
+    }
+    return null;
+  }
+  matchSegments(selector, label, selectorIndex, labelIndex) {
+    if (selectorIndex === selector.length) {
+      return labelIndex === label.length;
+    }
+    const segment = selector[selectorIndex];
+    if (segment === "**") {
+      if (selectorIndex === selector.length - 1) {
+        return true;
+      }
+      for (let next = labelIndex; next <= label.length; next += 1) {
+        if (this.matchSegments(selector, label, selectorIndex + 1, next)) {
+          return true;
+        }
+      }
+      return false;
+    }
+    if (labelIndex >= label.length) {
+      return false;
+    }
+    const segmentMatches = segment === "*" || segment === label[labelIndex];
+    return segmentMatches && this.matchSegments(selector, label, selectorIndex + 1, labelIndex + 1);
+  }
+};
+
+// src/core/metric_extractor.ts
+var MetricExtractor = class {
+  constructor(definitions) {
+    this.definitions = definitions;
+  }
+  definitions;
+  contract = new MetricDefinitionContract();
+  extract(envelopes) {
+    const samples = [];
+    const failures = [];
+    for (const envelope of envelopes) {
+      for (const definition of this.definitions) {
+        if (!this.contract.matches(definition.selector, envelope.label)) {
+          continue;
+        }
+        const extracted = this.extractDefinition(definition, envelope);
+        if (extracted.ok) {
+          samples.push(extracted.sample);
+        } else if (definition.missingField === "record-failure") {
+          failures.push({
+            metricName: definition.name,
+            definitionVersion: definition.version,
+            producerId: envelope.producerId,
+            sequence: envelope.sequence,
+            reason: extracted.reason
+          });
+        }
+      }
+    }
+    return Object.freeze({
+      samples: Object.freeze(samples),
+      failures: Object.freeze(failures)
+    });
+  }
+  extractDefinition(definition, envelope) {
+    const dimensions = {};
+    for (const field of definition.groupBy) {
+      const dimension = this.readField(envelope, field);
+      if (!this.isDimensionValue(dimension)) {
+        return { ok: false, reason: `Missing or invalid dimension ${field}` };
+      }
+      dimensions[field] = dimension;
+    }
+    const values = { __count: 1 };
+    for (const measurement of definition.measurements) {
+      if (measurement.kind === "count") {
+        continue;
+      }
+      const measured = this.readField(envelope, measurement.field);
+      if (typeof measured !== "number" || !Number.isFinite(measured)) {
+        return { ok: false, reason: `Missing or non-numeric measurement ${measurement.field}` };
+      }
+      values[measurement.field] = measured;
+    }
+    const frozenDimensions = Object.freeze(dimensions);
+    return {
+      ok: true,
+      sample: Object.freeze({
+        metricName: definition.name,
+        definitionVersion: definition.version,
+        occurredAtMs: envelope.occurredAtMs,
+        producerId: envelope.producerId,
+        sequence: envelope.sequence,
+        dimensions: frozenDimensions,
+        dimensionKey: canonicalJson(frozenDimensions),
+        values: Object.freeze(values),
+        targetIds: definition.targetIds
+      })
+    };
+  }
+  readField(envelope, path) {
+    const topLevel = this.readTopLevel(envelope, path);
+    if (topLevel !== void 0) {
+      return topLevel;
+    }
+    const segments = path.split(".");
+    let current = envelope.metadata;
+    for (const segment of segments) {
+      if (!this.isJsonObject(current)) {
+        return void 0;
+      }
+      const nextValue = current[segment];
+      if (nextValue === void 0) {
+        return void 0;
+      }
+      current = nextValue;
+    }
+    return current;
+  }
+  readTopLevel(envelope, path) {
+    switch (path) {
+      case "conversationId":
+        return envelope.conversationId;
+      case "correlationId":
+        return envelope.correlationId;
+      case "source":
+        return envelope.source;
+      case "processKind":
+        return envelope.processKind;
+      case "level":
+        return envelope.level;
+      case "label":
+        return envelope.label;
+      case "producerId":
+        return envelope.producerId;
+      default:
+        return void 0;
+    }
+  }
+  isDimensionValue(value) {
+    return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+  }
+  isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+  }
+};
+
+// src/core/telemetry_acknowledgement_contract.ts
+var MAX_TARGET_STATES = 1024;
+var MAX_TARGET_ID_BYTES = 256;
+var MAX_REASON_BYTES = 512;
+var TelemetryAcknowledgementContract = class {
+  exceptionReason(cause) {
+    try {
+      const value = cause instanceof Error ? cause.message : cause;
+      return this.truncateReason(String(value));
+    } catch {
+      return "Unknown telemetry transport failure";
+    }
+  }
+  validateAndDetach(batch, value) {
+    try {
+      const initialError = this.acknowledgementError(batch, value);
+      if (initialError !== null) {
+        return { ok: false, error: initialError };
+      }
+      const detached = JSON.parse(canonicalJson(value));
+      const detachedError = this.acknowledgementError(batch, detached);
+      if (detachedError !== null) {
+        return { ok: false, error: detachedError };
+      }
+      return { ok: true, value: this.freezeAcknowledgement(detached) };
+    } catch {
+      return { ok: false, error: "acknowledgement could not be inspected" };
+    }
+  }
+  acknowledgementError(batch, value) {
+    if (!this.isRecord(value) || value.idempotencyKey !== batch.idempotencyKey) {
+      return "acknowledgement identity is missing or mismatched";
+    }
+    const targetsError = this.targetStatesError(value.targetStates);
+    if (targetsError !== null) {
+      return targetsError;
+    }
+    switch (value.kind) {
+      case "committed":
+        return this.committedAcknowledgementError(batch, value);
+      case "retryable":
+        return this.retryableAcknowledgementError(value);
+      case "rejected":
+        return this.rejectedAcknowledgementError(value);
+      case "conflict":
+        return this.conflictAcknowledgementError(value);
+      default:
+        return "acknowledgement kind is invalid";
+    }
+  }
+  committedAcknowledgementError(batch, value) {
+    const valid = this.hasExactKeys(value, [
+      "kind",
+      "idempotencyKey",
+      "committedAtMs",
+      "acceptedEvents",
+      "duplicate",
+      "targetStates"
+    ]) && Number.isSafeInteger(value.committedAtMs) && Number(value.committedAtMs) >= 0 && value.acceptedEvents === batch.envelopes.length && typeof value.duplicate === "boolean";
+    return valid ? null : "committed acknowledgement fields are invalid";
+  }
+  retryableAcknowledgementError(value) {
+    const valid = this.hasExactKeys(value, [
+      "kind",
+      "idempotencyKey",
+      "reason",
+      "retryAfterMs",
+      "targetStates"
+    ]) && this.isBoundedReason(value.reason) && Number.isFinite(value.retryAfterMs) && Number(value.retryAfterMs) >= 0 && Number(value.retryAfterMs) <= Number.MAX_SAFE_INTEGER;
+    return valid ? null : "retryable acknowledgement fields are invalid";
+  }
+  rejectedAcknowledgementError(value) {
+    const codes = ["invalid-batch", "unsupported-version", "no-required-terminal", "closed"];
+    const valid = this.hasExactKeys(value, [
+      "kind",
+      "idempotencyKey",
+      "code",
+      "reason",
+      "targetStates"
+    ]) && codes.includes(String(value.code)) && this.isBoundedReason(value.reason);
+    return valid ? null : "rejected acknowledgement fields are invalid";
+  }
+  conflictAcknowledgementError(value) {
+    const valid = this.hasExactKeys(value, ["kind", "idempotencyKey", "reason", "targetStates"]) && this.isBoundedReason(value.reason);
+    return valid ? null : "conflict acknowledgement fields are invalid";
+  }
+  targetStatesError(value) {
+    if (!Array.isArray(value) || value.length > MAX_TARGET_STATES || !this.hasExactArrayIndexes(value)) {
+      return "acknowledgement target states are invalid";
+    }
+    const targetIds = /* @__PURE__ */ new Set();
+    for (const target of value) {
+      if (!this.isValidTargetState(target) || targetIds.has(target.targetId)) {
+        return "acknowledgement target states are invalid";
+      }
+      targetIds.add(target.targetId);
+    }
+    return null;
+  }
+  isValidTargetState(value) {
+    if (!this.isRecord(value) || !this.hasExactKeys(value, ["targetId", "delivery", "state", "attempts", "reason"])) {
+      return false;
+    }
+    const deliveries = ["required", "best-effort"];
+    const states = ["pending", "committed", "failed", "abandoned"];
+    return typeof value.targetId === "string" && value.targetId.length > 0 && telemetryUtf8Length(value.targetId) <= MAX_TARGET_ID_BYTES && deliveries.includes(String(value.delivery)) && states.includes(String(value.state)) && Number.isSafeInteger(value.attempts) && Number(value.attempts) >= 0 && (value.reason === null || this.isBoundedReason(value.reason));
+  }
+  freezeAcknowledgement(value) {
+    const targetStates = value.targetStates.map((target) => Object.freeze({ ...target }));
+    return Object.freeze({ ...value, targetStates: Object.freeze(targetStates) });
+  }
+  isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+  }
+  hasExactKeys(value, expected) {
+    const keys = Reflect.ownKeys(value);
+    return keys.length === expected.length && keys.every((key) => typeof key === "string" && expected.includes(key));
+  }
+  hasExactArrayIndexes(value) {
+    const keys = Reflect.ownKeys(value);
+    if (keys.length !== value.length + 1 || !keys.includes("length")) {
+      return false;
+    }
+    return value.every((_item, index) => keys.includes(String(index)));
+  }
+  isBoundedReason(value) {
+    return typeof value === "string" && telemetryUtf8Length(value) <= MAX_REASON_BYTES;
+  }
+  truncateReason(value) {
+    const encoded = new TextEncoder().encode(value);
+    if (encoded.length <= MAX_REASON_BYTES) {
+      return value;
+    }
+    const decoder = new TextDecoder("utf-8", { fatal: true });
+    for (let length = MAX_REASON_BYTES; length > 0; length -= 1) {
+      try {
+        return decoder.decode(encoded.subarray(0, length));
+      } catch {
+      }
+    }
+    return "";
+  }
+};
+
+// 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/core/helper/telemetry_deadline_guard.ts
+var MAX_TIMER_DELAY_MS = 2147483647;
+var TelemetryDeadlineGuard = class {
+  async settle(operation, deadlineMs, now) {
+    const observed = operation.then(
+      (value) => ({ kind: "completed", value }),
+      (error) => ({ kind: "failed", error })
+    );
+    const remainingMs = deadlineMs - now();
+    if (!Number.isFinite(remainingMs) || remainingMs <= 0) {
+      return { kind: "deadline-exhausted" };
+    }
+    let timer = null;
+    const outcome = await Promise.race([
+      observed,
+      new Promise((resolve) => {
+        timer = setTimeout(
+          () => resolve({ kind: "deadline-exhausted" }),
+          Math.min(remainingMs, MAX_TIMER_DELAY_MS)
+        );
+      })
+    ]);
+    if (timer !== null) {
+      clearTimeout(timer);
+    }
+    return outcome;
+  }
+};
+
+// src/core/telemetry_batch_router.ts
+var TelemetryBatchRouter = class {
+  constructor(options) {
+    this.options = options;
+    this.transportId = options.routerId;
+    this.validateRoutes();
+    this.capabilities = Object.freeze({
+      maxBatchBytes: Math.min(...options.routes.map((route) => route.transport.capabilities.maxBatchBytes)),
+      acknowledgement: options.volatile ? "receipt" : "durable",
+      ordering: options.routes.every((route) => route.transport.capabilities.ordering === "producer") ? "producer" : "none",
+      boundedCapacity: Math.min(...options.routes.map((route) => route.transport.capabilities.boundedCapacity))
+    });
+  }
+  options;
+  transportId;
+  capabilities;
+  acknowledgementContract = new TelemetryAcknowledgementContract();
+  deadlineGuard = new TelemetryDeadlineGuard();
+  committed = /* @__PURE__ */ new Map();
+  async send(batch) {
+    const matchingRoutes = this.options.routes.filter((route) => route.matches(batch));
+    const hasRequiredRoute = matchingRoutes.some((route) => route.delivery === "required");
+    if (!hasRequiredRoute && !this.options.volatile) {
+      return {
+        kind: "rejected",
+        idempotencyKey: batch.idempotencyKey,
+        code: "no-required-terminal",
+        reason: "No required durable route matched this batch",
+        targetStates: this.unmatchedStates(batch, matchingRoutes)
+      };
+    }
+    const committedRoutes = this.committed.get(batch.idempotencyKey) ?? /* @__PURE__ */ new Set();
+    const routeResults = await this.sendMatchingRoutes(batch, matchingRoutes, committedRoutes);
+    this.remember(batch.idempotencyKey, committedRoutes);
+    return this.aggregateAcknowledgement(batch, matchingRoutes, routeResults);
+  }
+  async flush(deadlineMs) {
+    await this.runLifecycleUntilDeadline(
+      deadlineMs,
+      (transport) => transport.flush(deadlineMs)
+    );
+  }
+  async close(deadlineMs) {
+    await this.runLifecycleUntilDeadline(
+      deadlineMs,
+      (transport) => transport.close(deadlineMs)
+    );
+  }
+  async runLifecycleUntilDeadline(deadlineMs, run) {
+    const operations = this.options.routes.map((route) => {
+      return Promise.resolve().then(() => run(route.transport));
+    });
+    const outcome = await this.deadlineGuard.settle(
+      Promise.all(operations),
+      deadlineMs,
+      this.options.now
+    );
+    if (outcome.kind === "failed") {
+      throw outcome.error;
+    }
+  }
+  async sendMatchingRoutes(batch, routes, committedRoutes) {
+    return Promise.all(routes.map(async (route) => {
+      if (committedRoutes.has(route.routeId)) {
+        return { route, acknowledgement: this.alreadyCommitted(batch), attempts: 0 };
+      }
+      const acknowledgement = await this.sendSafely(route.transport, batch);
+      if (acknowledgement.kind === "committed") {
+        committedRoutes.add(route.routeId);
+      }
+      return { route, acknowledgement, attempts: 1 };
+    }));
+  }
+  aggregateAcknowledgement(batch, matchingRoutes, routeResults) {
+    const targetStates = this.deliveryStates(batch, routeResults, matchingRoutes);
+    const requiredResults = routeResults.filter(({ route }) => route.delivery === "required");
+    const conflict = requiredResults.find(({ acknowledgement }) => acknowledgement.kind === "conflict");
+    const conflictAcknowledgement = conflict?.acknowledgement;
+    if (conflictAcknowledgement?.kind === "conflict") {
+      return {
+        kind: "conflict",
+        idempotencyKey: batch.idempotencyKey,
+        reason: conflictAcknowledgement.reason,
+        targetStates
+      };
+    }
+    const rejected = requiredResults.find(({ acknowledgement }) => acknowledgement.kind === "rejected");
+    const rejectedAcknowledgement = rejected?.acknowledgement;
+    if (rejectedAcknowledgement?.kind === "rejected") {
+      return {
+        kind: "rejected",
+        idempotencyKey: batch.idempotencyKey,
+        code: rejectedAcknowledgement.code,
+        reason: rejectedAcknowledgement.reason,
+        targetStates
+      };
+    }
+    const retryable = requiredResults.find(({ acknowledgement }) => acknowledgement.kind === "retryable");
+    const retryableAcknowledgement = retryable?.acknowledgement;
+    if (retryableAcknowledgement?.kind === "retryable") {
+      return {
+        kind: "retryable",
+        idempotencyKey: batch.idempotencyKey,
+        reason: retryableAcknowledgement.reason,
+        retryAfterMs: retryableAcknowledgement.retryAfterMs,
+        targetStates
+      };
+    }
+    return {
+      kind: "committed",
+      idempotencyKey: batch.idempotencyKey,
+      committedAtMs: this.options.now(),
+      acceptedEvents: batch.envelopes.length,
+      duplicate: routeResults.length > 0 && routeResults.every(({ attempts }) => attempts === 0),
+      targetStates
+    };
+  }
+  deliveryStates(batch, routeResults, matchingRoutes) {
+    return [
+      ...routeResults.map(({ route, acknowledgement, attempts }) => this.deliveryState(
+        route.routeId,
+        route.delivery,
+        acknowledgement,
+        attempts
+      )),
+      ...this.unmatchedStates(batch, matchingRoutes)
+    ];
+  }
+  async sendSafely(transport, batch) {
+    try {
+      const received = await transport.send(batch);
+      const validated = this.acknowledgementContract.validateAndDetach(batch, received);
+      return validated.ok ? validated.value : this.invalidAcknowledgement(batch, validated.error);
+    } catch (cause) {
+      return {
+        kind: "retryable",
+        idempotencyKey: batch.idempotencyKey,
+        reason: this.acknowledgementContract.exceptionReason(cause),
+        retryAfterMs: 25,
+        targetStates: []
+      };
+    }
+  }
+  invalidAcknowledgement(batch, error) {
+    return {
+      kind: "retryable",
+      idempotencyKey: batch.idempotencyKey,
+      reason: `Invalid telemetry acknowledgement: ${error}`,
+      retryAfterMs: 25,
+      targetStates: []
+    };
+  }
+  alreadyCommitted(batch) {
+    return {
+      kind: "committed",
+      idempotencyKey: batch.idempotencyKey,
+      committedAtMs: this.options.now(),
+      acceptedEvents: batch.envelopes.length,
+      duplicate: true,
+      targetStates: []
+    };
+  }
+  deliveryState(routeId, delivery, acknowledgement, attempts) {
+    if (acknowledgement.kind === "committed") {
+      return { targetId: routeId, delivery, state: "committed", attempts, reason: null };
+    }
+    return {
+      targetId: routeId,
+      delivery,
+      state: "failed",
+      attempts,
+      reason: acknowledgement.reason
+    };
+  }
+  unmatchedStates(_batch, matchingRoutes) {
+    const matchingIds = new Set(matchingRoutes.map((route) => route.routeId));
+    return this.options.routes.filter((route) => !matchingIds.has(route.routeId)).map((route) => ({
+      targetId: route.routeId,
+      delivery: route.delivery,
+      state: "abandoned",
+      attempts: 0,
+      reason: "route-not-matched"
+    }));
+  }
+  validateRoutes() {
+    if (!this.options.routerId.trim() || this.options.routes.length === 0) {
+      throw new Error("A telemetry batch router requires an id and at least one route");
+    }
+    if (this.options.maxRememberedBatches !== void 0 && (!Number.isSafeInteger(this.options.maxRememberedBatches) || this.options.maxRememberedBatches <= 0)) {
+      throw new Error("Telemetry batch router memory must be a positive safe integer");
+    }
+    const routeIds = this.options.routes.map((route) => route.routeId);
+    if (new Set(routeIds).size !== routeIds.length) {
+      throw new Error("Telemetry batch route ids must be unique");
+    }
+    const requiredRoutes = this.options.routes.filter((route) => route.delivery === "required");
+    const hasNonDurableRequiredRoute = requiredRoutes.some(
+      (route) => route.transport.capabilities.acknowledgement !== "durable"
+    );
+    if (!this.options.volatile && (requiredRoutes.length === 0 || hasNonDurableRequiredRoute)) {
+      throw new Error("A non-volatile router requires at least one durable required route");
+    }
+  }
+  remember(idempotencyKey, routes) {
+    this.committed.set(idempotencyKey, routes);
+    const maximum = this.options.maxRememberedBatches ?? 1024;
+    while (this.committed.size > maximum) {
+      const oldest = this.committed.keys().next().value;
+      if (typeof oldest !== "string") {
+        return;
+      }
+      this.committed.delete(oldest);
+    }
+  }
+};
+
+// src/core/telemetry_client.ts
+var TelemetryClient = class {
+  constructor(options) {
+    this.options = options;
+    this.validateOptions();
+    this.snapshotter = new BoundedMetadataSnapshotter(options.metadata);
+  }
+  options;
+  snapshotter;
+  batchContract = new TelemetryBatchContract();
+  queue = [];
+  dropCounts = /* @__PURE__ */ new Map();
+  state = "accepting";
+  nextSequence = 0;
+  queuedBytes = 0;
+  inFlightBatches = 0;
+  drainScheduled = false;
+  activeDrain = null;
+  lastAcknowledgement = null;
+  trace(level, label, metadata = {}) {
+    return this.emit(level, label, metadata);
+  }
+  debug(label, metadata = {}) {
+    return this.emit("debug", label, metadata);
+  }
+  info(label, metadata = {}) {
+    return this.emit("info", label, metadata);
+  }
+  warn(label, metadata = {}) {
+    return this.emit("warn", label, metadata);
+  }
+  error(label, metadata = {}) {
+    return this.emit("error", label, metadata);
+  }
+  fatal(label, metadata = {}) {
+    return this.emit("fatal", label, metadata);
+  }
+  emit(level, label, metadata) {
+    return this.admit({
+      source: this.options.source,
+      processKind: this.options.processKind,
+      level,
+      label,
+      occurredAtMs: this.options.now(),
+      monotonicNs: this.options.monotonicNowNs(),
+      conversationId: null,
+      correlationId: null,
+      metadata
+    });
+  }
+  admit(input) {
+    const sequence = this.nextSequence;
+    this.nextSequence += 1;
+    if (this.state !== "accepting") {
+      this.incrementDrop("stopped", this.priorityFor(input.level));
+      return { kind: "dropped", producerId: this.options.producerId, sequence, reason: "client-stopped" };
+    }
+    const hasInvalidIdentity = !this.isValidLabel(input.label) || !input.source.trim() || !input.processKind.trim() || !Number.isFinite(input.occurredAtMs);
+    if (hasInvalidIdentity) {
+      this.incrementDrop("invalid", this.priorityFor(input.level));
+      return { kind: "dropped", producerId: this.options.producerId, sequence, reason: "invalid-label" };
+    }
+    const priority = this.priorityFor(input.level);
+    if (!this.isSampled(priority)) {
+      this.incrementDrop("sampled", priority);
+      return { kind: "dropped", producerId: this.options.producerId, sequence, reason: "sampled" };
+    }
+    const snapshot = this.snapshotter.snapshot(input.metadata);
+    const extractedCorrelation = this.resolveCorrelation(snapshot.metadata);
+    const correlation = {
+      conversationId: input.conversationId ?? extractedCorrelation.conversationId,
+      correlationId: input.correlationId ?? extractedCorrelation.correlationId
+    };
+    const envelope = this.createEnvelope(sequence, input, snapshot.metadata, correlation);
+    const bytes = telemetryUtf8Length(canonicalJson(envelope));
+    const single = this.batchContract.create([envelope], []);
+    if (!single.ok) {
+      this.incrementDrop("invalid", priority);
+      return { kind: "dropped", producerId: this.options.producerId, sequence, reason: "invalid-envelope" };
+    }
+    const framedBytes = telemetryUtf8Length(canonicalJson(single.value));
+    const queueWouldOverflow = this.queue.length >= this.options.admission.maxQueuedEvents || this.queuedBytes + bytes > this.options.admission.maxQueuedBytes || framedBytes > this.options.admission.maxBatchBytes;
+    if (queueWouldOverflow) {
+      this.incrementDrop("capacity", priority);
+      return { kind: "dropped", producerId: this.options.producerId, sequence, reason: "capacity" };
+    }
+    this.queue.push(Object.freeze({ envelope, bytes }));
+    this.queuedBytes += bytes;
+    this.scheduleDrain();
+    return {
+      kind: "admitted",
+      producerId: this.options.producerId,
+      sequence,
+      eventId: envelope.eventId
+    };
+  }
+  status() {
+    return Object.freeze({
+      state: this.state,
+      producerId: this.options.producerId,
+      nextSequence: this.nextSequence,
+      queuedEvents: this.queue.length,
+      queuedBytes: this.queuedBytes,
+      inFlightBatches: this.inFlightBatches,
+      dropCounters: this.dropCounterSnapshot(),
+      lastAcknowledgement: this.lastAcknowledgement
+    });
+  }
+  async flush(deadlineMs) {
+    this.scheduleDrain();
+    while ((this.queue.length > 0 || this.activeDrain !== null) && this.options.now() < deadlineMs) {
+      const currentDrain = this.activeDrain;
+      if (currentDrain) {
+        await Promise.race([currentDrain, this.options.delay(1)]);
+      } else {
+        await this.options.delay(1);
+      }
+    }
+    await this.settleExternalShutdown(
+      () => this.options.transport.flush(deadlineMs),
+      deadlineMs
+    );
+  }
+  async stop(deadlineMs) {
+    if (this.state === "stopped") {
+      return;
+    }
+    this.state = "draining";
+    await this.flush(deadlineMs);
+    const abandoned = this.queue.splice(0, this.queue.length);
+    if (abandoned.length > 0) {
+      this.incrementDropBy("transport", "normal", abandoned.length);
+      this.queuedBytes = 0;
+    }
+    await this.settleExternalShutdown(
+      () => this.options.transport.close(deadlineMs),
+      deadlineMs
+    );
+    this.state = "stopped";
+  }
+  createEnvelope(sequence, input, metadata, correlation) {
+    return Object.freeze({
+      schemaVersion: TelemetryBatchContract.schemaVersion,
+      eventId: `${this.options.producerId}:${sequence}`,
+      producerId: this.options.producerId,
+      sequence,
+      occurredAtMs: input.occurredAtMs,
+      monotonicNs: input.monotonicNs,
+      source: input.source,
+      processKind: input.processKind,
+      level: input.level.trim().toLowerCase() || "info",
+      label: input.label,
+      conversationId: correlation.conversationId,
+      correlationId: correlation.correlationId,
+      metadata
+    });
+  }
+  resolveCorrelation(metadata) {
+    const conversationValue = metadata.conversationId ?? metadata.threadId ?? null;
+    const conversationId = typeof conversationValue === "string" || typeof conversationValue === "number" ? conversationValue : null;
+    const correlationValue = metadata.correlationId;
+    const correlationId = typeof correlationValue === "string" ? correlationValue : null;
+    return { conversationId, correlationId };
+  }
+  scheduleDrain() {
+    if (this.drainScheduled || this.activeDrain !== null || this.queue.length === 0) {
+      return;
+    }
+    this.drainScheduled = true;
+    try {
+      this.options.schedule(() => {
+        this.drainScheduled = false;
+        const drain = this.drainLoop();
+        this.activeDrain = drain;
+        const settle = () => {
+          this.activeDrain = null;
+          if (this.queue.length > 0) {
+            this.scheduleDrain();
+          }
+        };
+        void drain.then(settle, settle);
+      });
+    } catch {
+      this.drainScheduled = false;
+    }
+  }
+  async drainLoop() {
+    while (this.queue.length > 0) {
+      const dropSnapshot = this.dropCounterSnapshot();
+      const prepared = this.prepareBatch(dropSnapshot);
+      if (prepared === null) {
+        continue;
+      }
+      this.inFlightBatches += 1;
+      try {
+        const acknowledgement = await this.deliverWithRetry(prepared.batch);
+        this.lastAcknowledgement = acknowledgement;
+        if (acknowledgement.kind === "committed") {
+          this.subtractDropSnapshot(prepared.dropCounters);
+        } else {
+          this.incrementDropBy("transport", "normal", prepared.eventCount);
+        }
+      } finally {
+        this.inFlightBatches -= 1;
+      }
+    }
+  }
+  prepareBatch(dropCounters) {
+    const entries = this.peekBatchEntries();
+    const withCounters = this.findFittingBatch(entries, dropCounters);
+    const prepared = withCounters ?? this.findFittingBatch(entries, []);
+    if (prepared === null) {
+      const invalid = this.queue.shift();
+      if (invalid !== void 0) {
+        this.queuedBytes -= invalid.bytes;
+        this.incrementDrop("invalid", this.priorityFor(invalid.envelope.level));
+      }
+      return null;
+    }
+    for (let index = 0; index < prepared.eventCount; index += 1) {
+      const removed = this.queue.shift();
+      if (removed !== void 0) {
+        this.queuedBytes -= removed.bytes;
+      }
+    }
+    return prepared;
+  }
+  peekBatchEntries() {
+    const entries = [];
+    let batchBytes = 0;
+    while (entries.length < this.options.admission.maxBatchEvents) {
+      const next = this.queue[entries.length];
+      if (!next) {
+        break;
+      }
+      const exceedsBatchBytes = entries.length > 0 && batchBytes + next.bytes > this.options.admission.maxBatchBytes;
+      if (exceedsBatchBytes) {
+        break;
+      }
+      batchBytes += next.bytes;
+      entries.push(next);
+    }
+    return entries;
+  }
+  findFittingBatch(entries, dropCounters) {
+    for (let eventCount = entries.length; eventCount > 0; eventCount -= 1) {
+      const created = this.batchContract.create(
+        entries.slice(0, eventCount).map((entry) => entry.envelope),
+        dropCounters
+      );
+      if (created.ok && telemetryUtf8Length(canonicalJson(created.value)) <= this.options.admission.maxBatchBytes) {
+        return Object.freeze({ batch: created.value, dropCounters, eventCount });
+      }
+    }
+    return null;
+  }
+  async deliverWithRetry(batch) {
+    let attempt = 0;
+    while (attempt <= this.options.admission.retryLimit) {
+      let acknowledgement;
+      try {
+        const received = await this.options.transport.send(batch);
+        acknowledgement = this.normalizeAcknowledgement(batch, received, attempt);
+      } catch (cause) {
+        acknowledgement = {
+          kind: "retryable",
+          idempotencyKey: batch.idempotencyKey,
+          reason: this.errorMessage(cause),
+          retryAfterMs: this.retryDelay(attempt),
+          targetStates: []
+        };
+      }
+      if (acknowledgement.kind !== "retryable" || attempt === this.options.admission.retryLimit) {
+        return acknowledgement;
+      }
+      const requestedDelay = Math.max(acknowledgement.retryAfterMs, this.retryDelay(attempt));
+      await this.options.delay(requestedDelay);
+      attempt += 1;
+    }
+    return {
+      kind: "retryable",
+      idempotencyKey: batch.idempotencyKey,
+      reason: "retry-limit-exhausted",
+      retryAfterMs: 0,
+      targetStates: []
+    };
+  }
+  retryDelay(attempt) {
+    return Math.min(
+      Number.MAX_SAFE_INTEGER,
+      this.options.admission.retryBaseDelayMs * 2 ** attempt
+    );
+  }
+  normalizeAcknowledgement(batch, value, attempt) {
+    try {
+      const error = this.acknowledgementError(batch, value);
+      return error === null ? this.detachAcknowledgement(value) : this.invalidAcknowledgement(batch, error, attempt);
+    } catch {
+      return this.invalidAcknowledgement(batch, "acknowledgement could not be inspected", attempt);
+    }
+  }
+  acknowledgementError(batch, value) {
+    if (!this.isRecord(value) || value.idempotencyKey !== batch.idempotencyKey) {
+      return "acknowledgement identity is missing or mismatched";
+    }
+    const targetsError = this.targetStatesError(value.targetStates);
+    if (targetsError !== null) {
+      return targetsError;
+    }
+    switch (value.kind) {
+      case "committed":
+        return this.committedAcknowledgementError(batch, value);
+      case "retryable":
+        return this.retryableAcknowledgementError(value);
+      case "rejected":
+        return this.rejectedAcknowledgementError(value);
+      case "conflict":
+        return this.conflictAcknowledgementError(value);
+      default:
+        return "acknowledgement kind is invalid";
+    }
+  }
+  committedAcknowledgementError(batch, value) {
+    const valid = this.hasExactKeys(value, [
+      "kind",
+      "idempotencyKey",
+      "committedAtMs",
+      "acceptedEvents",
+      "duplicate",
+      "targetStates"
+    ]) && Number.isSafeInteger(value.committedAtMs) && Number(value.committedAtMs) >= 0 && value.acceptedEvents === batch.envelopes.length && typeof value.duplicate === "boolean";
+    return valid ? null : "committed acknowledgement fields are invalid";
+  }
+  retryableAcknowledgementError(value) {
+    const valid = this.hasExactKeys(value, [
+      "kind",
+      "idempotencyKey",
+      "reason",
+      "retryAfterMs",
+      "targetStates"
+    ]) && this.isBoundedReason(value.reason) && Number.isFinite(value.retryAfterMs) && Number(value.retryAfterMs) >= 0 && Number(value.retryAfterMs) <= Number.MAX_SAFE_INTEGER;
+    return valid ? null : "retryable acknowledgement fields are invalid";
+  }
+  rejectedAcknowledgementError(value) {
+    const codes = ["invalid-batch", "unsupported-version", "no-required-terminal", "closed"];
+    const valid = this.hasExactKeys(value, [
+      "kind",
+      "idempotencyKey",
+      "code",
+      "reason",
+      "targetStates"
+    ]) && codes.includes(String(value.code)) && this.isBoundedReason(value.reason);
+    return valid ? null : "rejected acknowledgement fields are invalid";
+  }
+  conflictAcknowledgementError(value) {
+    const valid = this.hasExactKeys(value, ["kind", "idempotencyKey", "reason", "targetStates"]) && this.isBoundedReason(value.reason);
+    return valid ? null : "conflict acknowledgement fields are invalid";
+  }
+  targetStatesError(value) {
+    if (!Array.isArray(value) || value.length > 1024) {
+      return "acknowledgement target states are invalid";
+    }
+    const targetIds = /* @__PURE__ */ new Set();
+    for (const target of value) {
+      if (!this.isValidTargetState(target) || targetIds.has(target.targetId)) {
+        return "acknowledgement target states are invalid";
+      }
+      targetIds.add(target.targetId);
+    }
+    return null;
+  }
+  isValidTargetState(value) {
+    if (!this.isRecord(value) || !this.hasExactKeys(value, ["targetId", "delivery", "state", "attempts", "reason"])) {
+      return false;
+    }
+    const deliveries = ["required", "best-effort"];
+    const states = ["pending", "committed", "failed", "abandoned"];
+    return typeof value.targetId === "string" && value.targetId.length > 0 && telemetryUtf8Length(value.targetId) <= 256 && deliveries.includes(String(value.delivery)) && states.includes(String(value.state)) && Number.isSafeInteger(value.attempts) && Number(value.attempts) >= 0 && (value.reason === null || this.isBoundedReason(value.reason));
+  }
+  invalidAcknowledgement(batch, error, attempt) {
+    return {
+      kind: "retryable",
+      idempotencyKey: batch.idempotencyKey,
+      reason: `Invalid telemetry acknowledgement: ${error}`,
+      retryAfterMs: this.retryDelay(attempt),
+      targetStates: []
+    };
+  }
+  detachAcknowledgement(value) {
+    const detached = JSON.parse(canonicalJson(value));
+    const targetStates = Object.freeze(detached.targetStates.map((target) => Object.freeze({ ...target })));
+    return Object.freeze({ ...detached, targetStates });
+  }
+  isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+  }
+  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));
+  }
+  isBoundedReason(value) {
+    return typeof value === "string" && telemetryUtf8Length(value) <= 512;
+  }
+  dropCounterSnapshot() {
+    const counters = [...this.dropCounts.entries()].filter(([, count]) => count > 0).sort(([left], [right]) => left.localeCompare(right)).map(([key, count]) => {
+      const [reason, priority] = key.split(":");
+      return Object.freeze({
+        reason,
+        priority,
+        count
+      });
+    });
+    return Object.freeze(counters);
+  }
+  subtractDropSnapshot(snapshot) {
+    for (const counter of snapshot) {
+      const key = `${counter.reason}:${counter.priority}`;
+      const current = this.dropCounts.get(key) ?? 0;
+      this.dropCounts.set(key, Math.max(0, current - counter.count));
+    }
+  }
+  incrementDrop(reason, priority) {
+    this.incrementDropBy(reason, priority, 1);
+  }
+  incrementDropBy(reason, priority, count) {
+    const key = `${reason}:${priority}`;
+    const current = this.dropCounts.get(key) ?? 0;
+    this.dropCounts.set(key, Math.min(Number.MAX_SAFE_INTEGER, current + count));
+  }
+  priorityFor(level) {
+    const normalized = level.trim().toLowerCase();
+    if (normalized === "error" || normalized === "fatal") {
+      return "high";
+    }
+    if (normalized === "trace" || normalized === "debug") {
+      return "low";
+    }
+    return "normal";
+  }
+  isSampled(priority) {
+    const sampleRate = this.options.admission.sampleRates[priority];
+    return sampleRate >= 1 || this.options.random() < sampleRate;
+  }
+  isValidLabel(label) {
+    return /^[A-Za-z0-9][A-Za-z0-9_.:-]*$/.test(label) && label.length <= 256;
+  }
+  errorMessage(cause) {
+    if (cause instanceof Error) {
+      return cause.message.slice(0, 512);
+    }
+    return String(cause).slice(0, 512);
+  }
+  async settleExternalShutdown(work, deadlineMs) {
+    const operation = Promise.resolve().then(work);
+    const remainingMs = deadlineMs - this.options.now();
+    if (!Number.isFinite(remainingMs) || remainingMs <= 0) {
+      void operation.catch(() => void 0);
+      return;
+    }
+    await new Promise((resolve, reject) => {
+      let settled = false;
+      const finish = (failed, error) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        if (failed) {
+          reject(error);
+        } else {
+          resolve();
+        }
+      };
+      const timer = setTimeout(
+        () => finish(false),
+        Math.min(remainingMs, 2147483647)
+      );
+      void operation.then(
+        () => finish(false),
+        (error) => finish(true, error)
+      );
+    });
+  }
+  validateOptions() {
+    this.validateIdentityOptions();
+    this.validateOrderedDeliveryOptions();
+    this.validateCapacityOptions();
+    this.validateBatchEventOptions();
+    this.validateBatchByteOptions();
+    this.validateMetadataOptions();
+    this.validateRetryOptions();
+    this.validateSampleRateOptions();
+  }
+  validateIdentityOptions() {
+    if (!this.options.source.trim() || !this.options.processKind.trim() || !this.options.producerId.trim()) {
+      throw new Error("Telemetry client source, process kind, and producer id are required");
+    }
+  }
+  validateOrderedDeliveryOptions() {
+    if (this.options.admission.maxInFlightBatches !== 1) {
+      throw new Error("Ordered telemetry clients currently require maxInFlightBatches to equal 1");
+    }
+  }
+  validateCapacityOptions() {
+    const capacities = [
+      this.options.admission.maxQueuedEvents,
+      this.options.admission.maxQueuedBytes,
+      this.options.admission.maxBatchEvents,
+      this.options.admission.maxBatchBytes,
+      this.options.admission.maxInFlightBatches,
+      this.options.transport.capabilities.maxBatchBytes,
+      this.options.transport.capabilities.boundedCapacity
+    ];
+    if (capacities.some((capacity) => !Number.isSafeInteger(capacity) || capacity <= 0)) {
+      throw new Error("Telemetry client and transport capacities must be positive safe integers");
+    }
+  }
+  validateBatchEventOptions() {
+    if (this.options.admission.maxBatchEvents > this.options.admission.maxQueuedEvents || this.options.admission.maxBatchEvents > this.batchContract.limits.maxBatchEvents) {
+      throw new Error("Telemetry maxBatchEvents must not exceed queue or receiver capacity");
+    }
+  }
+  validateBatchByteOptions() {
+    if (this.options.admission.maxBatchBytes > this.options.admission.maxQueuedBytes || this.options.admission.maxBatchBytes > this.options.transport.capabilities.maxBatchBytes || this.options.admission.maxBatchBytes > this.batchContract.limits.maxBatchBytes) {
+      throw new Error("Telemetry maxBatchBytes must not exceed queue, transport, or receiver capacity");
+    }
+  }
+  validateMetadataOptions() {
+    if (this.options.metadata.maxBytes > this.options.admission.maxBatchBytes) {
+      throw new Error("Telemetry metadata bytes must not exceed maxBatchBytes");
+    }
+  }
+  validateRetryOptions() {
+    if (!Number.isSafeInteger(this.options.admission.retryLimit) || this.options.admission.retryLimit < 0 || !Number.isFinite(this.options.admission.retryBaseDelayMs) || this.options.admission.retryBaseDelayMs < 0) {
+      throw new Error("Telemetry retry limit and delay must be nonnegative finite values");
+    }
+  }
+  validateSampleRateOptions() {
+    const rates = Object.values(this.options.admission.sampleRates);
+    if (rates.some((rate) => !Number.isFinite(rate) || rate < 0 || rate > 1)) {
+      throw new Error("Telemetry sample rates must be between zero and one");
+    }
+  }
+};
+
+// src/core/telemetry_storage_router.ts
+var START_ROLLBACK_TIMEOUT_MS = 5e3;
+var TelemetryStorageRouter = class {
+  constructor(options) {
+    this.options = options;
+    this.targetId = options.routerId;
+    this.validateOptions();
+    this.capabilities = Object.freeze({
+      rawPersistence: options.targets.every((target) => target.transport.capabilities.rawPersistence),
+      metricSamples: options.targets.every((target) => target.transport.capabilities.metricSamples),
+      rollups: options.targets.some((target) => target.transport.capabilities.rollups),
+      queries: options.targets.some((target) => target.transport.capabilities.queries),
+      retention: options.targets.some((target) => target.transport.capabilities.retention),
+      maintenance: options.targets.some((target) => target.transport.capabilities.maintenance)
+    });
+  }
+  options;
+  targetId;
+  capabilities;
+  acknowledgementContract = new TelemetryAcknowledgementContract();
+  deadlineGuard = new TelemetryDeadlineGuard();
+  committed = /* @__PURE__ */ new Map();
+  definitionTargets = /* @__PURE__ */ new Map();
+  state = "created";
+  detail = null;
+  async start(definitions) {
+    if (this.state !== "created" && this.state !== "stopped") {
+      return { ok: false, error: `Cannot start telemetry storage router from state ${this.state}` };
+    }
+    this.state = "starting";
+    this.detail = null;
+    this.definitionTargets.clear();
+    for (const definition of definitions) {
+      this.definitionTargets.set(
+        `${definition.name}:${definition.version}`,
+        Object.freeze([...definition.targetIds])
+      );
+    }
+    const attemptedTargets = [];
+    const bestEffortFailures = [];
+    for (const target of this.options.targets) {
+      attemptedTargets.push(target);
+      const targetDefinitions = definitions.filter((definition) => {
+        return definition.targetIds.length === 0 || definition.targetIds.includes(target.targetId);
+      });
+      const started = await this.startTarget(target, targetDefinitions);
+      if (started.ok) {
+        continue;
+      }
+      const failure = `${target.targetId}: ${started.error}`;
+      if (target.delivery === "required") {
+        await this.rollbackAttemptedTargets(attemptedTargets, failure);
+        return { ok: false, error: failure };
+      }
+      bestEffortFailures.push(failure);
+    }
+    this.state = "ready";
+    this.detail = bestEffortFailures.length > 0 ? `Best-effort target startup failures: ${bestEffortFailures.join("; ")}` : null;
+    return { ok: true, value: void 0 };
+  }
+  async persist(request) {
+    const matchingTargets = this.options.targets.filter((target) => target.matches(request.batch));
+    const hasRequiredTarget = matchingTargets.some((target) => target.delivery === "required");
+    if (!hasRequiredTarget && !this.options.volatile) {
+      return {
+        kind: "rejected",
+        idempotencyKey: request.batch.idempotencyKey,
+        code: "no-required-terminal",
+        reason: "No required storage target matched this batch",
+        targetStates: this.unmatchedStates(matchingTargets)
+      };
+    }
+    const committedTargets = this.committed.get(request.batch.idempotencyKey) ?? /* @__PURE__ */ new Set();
+    const targetResults = await this.persistMatchingTargets(request, matchingTargets, committedTargets);
+    this.remember(request.batch.idempotencyKey, committedTargets);
+    return this.aggregateAcknowledgement(request, matchingTargets, targetResults);
+  }
+  async timeline(query) {
+    const target = this.resolveQueryTarget(query.targetId);
+    if (!target.ok) {
+      return target;
+    }
+    return target.value.transport.timeline(Object.freeze({ ...query, targetId: target.value.targetId }));
+  }
+  async metrics(query) {
+    const target = this.resolveQueryTarget(query.targetId);
+    if (!target.ok) {
+      return target;
+    }
+    return target.value.transport.metrics(Object.freeze({ ...query, targetId: target.value.targetId }));
+  }
+  async materializeRollups(nowMs, maxWorkMs) {
+    return this.runMaintenance("rollup", (target) => target.materializeRollups(nowMs, maxWorkMs));
+  }
+  async enforceRetention(nowMs, shouldContinue) {
+    return this.runMaintenance("retention", (target) => target.enforceRetention(nowMs, shouldContinue));
+  }
+  async checkpoint() {
+    return this.runMaintenance("checkpoint", (target) => target.checkpoint());
+  }
+  async reclaim(maxPages) {
+    return this.runMaintenance("reclaim", (target) => target.reclaim(maxPages));
+  }
+  async compact(deadlineMs) {
+    return this.runMaintenance("compaction", (target) => target.compact(deadlineMs));
+  }
+  status() {
+    const states = this.options.targets.map((target) => target.transport.status());
+    const requiredIds = new Set(this.options.targets.filter((target) => target.delivery === "required").map((target) => target.targetId));
+    const failedRequired = states.find((state) => {
+      return requiredIds.has(state.targetId) && state.state === "failed";
+    });
+    return {
+      targetId: this.targetId,
+      state: failedRequired ? "failed" : this.state,
+      detail: this.state === "failed" ? this.detail : failedRequired?.detail ?? this.detail,
+      writerLeaseHeld: states.some((state) => state.writerLeaseHeld)
+    };
+  }
+  async stop(deadlineMs) {
+    const operations = this.options.targets.map((target) => {
+      return Promise.resolve().then(() => target.transport.stop(deadlineMs));
+    });
+    const outcome = await this.deadlineGuard.settle(
+      Promise.allSettled(operations),
+      deadlineMs,
+      this.options.now
+    );
+    if (outcome.kind === "deadline-exhausted") {
+      this.state = "failed";
+      this.detail = "Telemetry storage router stop deadline exceeded";
+      return;
+    }
+    if (outcome.kind === "failed") {
+      this.state = "failed";
+      this.detail = `Telemetry storage router stop failed: ${this.errorMessage(outcome.error)}`;
+      throw outcome.error;
+    }
+    const failed = outcome.value.find((result) => result.status === "rejected");
+    if (failed) {
+      this.state = "failed";
+      this.detail = `Telemetry storage router stop failed: ${this.errorMessage(failed.reason)}`;
+      throw failed.reason;
+    }
+    this.state = "stopped";
+    this.detail = null;
+  }
+  targetStatuses() {
+    return this.options.targets.map((target) => target.transport.status());
+  }
+  async startTarget(target, definitions) {
+    try {
+      return await target.transport.start(definitions);
+    } catch (cause) {
+      return { ok: false, error: this.errorMessage(cause) };
+    }
+  }
+  async rollbackAttemptedTargets(attemptedTargets, primaryFailure) {
+    const deadlineMs = this.options.now() + START_ROLLBACK_TIMEOUT_MS;
+    const rollbackTargets = [...attemptedTargets].reverse();
+    const settled = /* @__PURE__ */ new Map();
+    const operations = rollbackTargets.map(async (target) => {
+      const result = await this.stopRollbackTarget(target, deadlineMs);
+      settled.set(target.targetId, result);
+    });
+    const outcome = await this.deadlineGuard.settle(
+      Promise.all(operations),
+      deadlineMs,
+      this.options.now
+    );
+    const timedOut = outcome.kind === "deadline-exhausted";
+    const cleanupFailures = rollbackTargets.flatMap((target) => {
+      const result = settled.get(target.targetId);
+      if (result === void 0) {
+        return timedOut ? [`${target.targetId}: rollback deadline exceeded`] : [];
+      }
+      return result.error === null ? [] : [`${target.targetId}: ${result.error}`];
+    });
+    this.state = "failed";
+    this.detail = cleanupFailures.length > 0 ? `${primaryFailure}; rollback cleanup failures: ${cleanupFailures.join("; ")}` : primaryFailure;
+  }
+  async stopRollbackTarget(target, deadlineMs) {
+    try {
+      await target.transport.stop(deadlineMs);
+      return { targetId: target.targetId, error: null };
+    } catch (cause) {
+      return { targetId: target.targetId, error: this.errorMessage(cause) };
+    }
+  }
+  async persistMatchingTargets(request, targets, committedTargets) {
+    return Promise.all(targets.map(async (target) => {
+      if (committedTargets.has(target.targetId)) {
+        return { target, acknowledgement: this.alreadyCommitted(request), attempts: 0 };
+      }
+      const targetRequest = this.requestForTarget(request, target.targetId);
+      const acknowledgement = await this.persistSafely(target, targetRequest);
+      if (acknowledgement.kind === "committed") {
+        committedTargets.add(target.targetId);
+      }
+      return { target, acknowledgement, attempts: 1 };
+    }));
+  }
+  aggregateAcknowledgement(request, matchingTargets, targetResults) {
+    const targetStates = this.deliveryStates(targetResults, matchingTargets);
+    const requiredResults = targetResults.filter(({ target }) => target.delivery === "required");
+    const conflict = requiredResults.find(({ acknowledgement }) => acknowledgement.kind === "conflict");
+    const conflictAcknowledgement = conflict?.acknowledgement;
+    if (conflictAcknowledgement?.kind === "conflict") {
+      return {
+        kind: "conflict",
+        idempotencyKey: request.batch.idempotencyKey,
+        reason: conflictAcknowledgement.reason,
+        targetStates
+      };
+    }
+    const rejected = requiredResults.find(({ acknowledgement }) => acknowledgement.kind === "rejected");
+    const rejectedAcknowledgement = rejected?.acknowledgement;
+    if (rejectedAcknowledgement?.kind === "rejected") {
+      return {
+        kind: "rejected",
+        idempotencyKey: request.batch.idempotencyKey,
+        code: rejectedAcknowledgement.code,
+        reason: rejectedAcknowledgement.reason,
+        targetStates
+      };
+    }
+    const retryable = requiredResults.find(({ acknowledgement }) => acknowledgement.kind === "retryable");
+    const retryableAcknowledgement = retryable?.acknowledgement;
+    if (retryableAcknowledgement?.kind === "retryable") {
+      return {
+        kind: "retryable",
+        idempotencyKey: request.batch.idempotencyKey,
+        reason: retryableAcknowledgement.reason,
+        retryAfterMs: retryableAcknowledgement.retryAfterMs,
+        targetStates
+      };
+    }
+    return {
+      kind: "committed",
+      idempotencyKey: request.batch.idempotencyKey,
+      committedAtMs: this.options.now(),
+      acceptedEvents: request.batch.envelopes.length,
+      duplicate: targetResults.length > 0 && targetResults.every(({ attempts }) => attempts === 0),
+      targetStates
+    };
+  }
+  deliveryStates(targetResults, matchingTargets) {
+    return [
+      ...targetResults.map(({ target, acknowledgement, attempts }) => this.deliveryState(
+        target,
+        acknowledgement,
+        attempts
+      )),
+      ...this.unmatchedStates(matchingTargets)
+    ];
+  }
+  requestForTarget(request, targetId) {
+    const samples = request.samples.filter((sample) => {
+      return sample.targetIds.length === 0 || sample.targetIds.includes(targetId);
+    });
+    const extractionFailures = request.extractionFailures.filter((failure) => {
+      const targetIds = this.definitionTargets.get(`${failure.metricName}:${failure.definitionVersion}`);
+      return targetIds === void 0 || targetIds.length === 0 || targetIds.includes(targetId);
+    });
+    return Object.freeze({
+      batch: request.batch,
+      samples: Object.freeze(samples),
+      extractionFailures: Object.freeze(extractionFailures)
+    });
+  }
+  async persistSafely(target, request) {
+    try {
+      const received = await target.transport.persist(request);
+      const validated = this.acknowledgementContract.validateAndDetach(request.batch, received);
+      return validated.ok ? validated.value : this.invalidAcknowledgement(request, validated.error);
+    } catch (cause) {
+      return {
+        kind: "retryable",
+        idempotencyKey: request.batch.idempotencyKey,
+        reason: this.acknowledgementContract.exceptionReason(cause),
+        retryAfterMs: 50,
+        targetStates: []
+      };
+    }
+  }
+  invalidAcknowledgement(request, error) {
+    return {
+      kind: "retryable",
+      idempotencyKey: request.batch.idempotencyKey,
+      reason: `Invalid telemetry acknowledgement: ${error}`,
+      retryAfterMs: 50,
+      targetStates: []
+    };
+  }
+  alreadyCommitted(request) {
+    return {
+      kind: "committed",
+      idempotencyKey: request.batch.idempotencyKey,
+      committedAtMs: this.options.now(),
+      acceptedEvents: request.batch.envelopes.length,
+      duplicate: true,
+      targetStates: []
+    };
+  }
+  deliveryState(target, acknowledgement, attempts) {
+    return acknowledgement.kind === "committed" ? {
+      targetId: target.targetId,
+      delivery: target.delivery,
+      state: "committed",
+      attempts,
+      reason: null
+    } : {
+      targetId: target.targetId,
+      delivery: target.delivery,
+      state: "failed",
+      attempts,
+      reason: acknowledgement.reason
+    };
+  }
+  unmatchedStates(matchingTargets) {
+    const matchingIds = new Set(matchingTargets.map((target) => target.targetId));
+    return this.options.targets.filter((target) => !matchingIds.has(target.targetId)).map((target) => ({
+      targetId: target.targetId,
+      delivery: target.delivery,
+      state: "abandoned",
+      attempts: 0,
+      reason: "route-not-matched"
+    }));
+  }
+  resolveQueryTarget(requestedTargetId) {
+    const queryable = this.options.targets.filter((target2) => target2.transport.capabilities.queries);
+    if (queryable.length === 0) {
+      return {
+        ok: false,
+        error: { kind: "unsupported", message: "No configured telemetry target supports queries" }
+      };
+    }
+    const resolvedId = requestedTargetId ?? this.options.defaultTargetId ?? (queryable.length === 1 ? queryable[0]?.targetId ?? null : null);
+    if (resolvedId === null) {
+      return {
+        ok: false,
+        error: { kind: "ambiguous-target", message: "Multiple queryable targets exist and no default was configured" }
+      };
+    }
+    const target = queryable.find((candidate) => candidate.targetId === resolvedId);
+    if (!target) {
+      return { ok: false, error: { kind: "unknown-target", message: `Unknown query target ${resolvedId}` } };
+    }
+    return { ok: true, value: target };
+  }
+  async runMaintenance(stage, run) {
+    let affectedRows = 0;
+    let affectedPages = 0;
+    let elapsedMs = 0;
+    for (const target of this.options.targets) {
+      if (!target.transport.capabilities.maintenance) {
+        continue;
+      }
+      const completed = await run(target.transport);
+      if (!completed.ok && target.delivery === "required") {
+        return { ok: false, error: `${target.targetId}: ${completed.error}` };
+      }
+      if (completed.ok) {
+        affectedRows += completed.value.affectedRows;
+        affectedPages += completed.value.affectedPages;
+        elapsedMs += completed.value.elapsedMs;
+      }
+    }
+    return {
+      ok: true,
+      value: { stage, affectedRows, affectedPages, elapsedMs, detail: null }
+    };
+  }
+  validateOptions() {
+    if (!this.options.routerId.trim() || this.options.targets.length === 0) {
+      throw new Error("A telemetry storage router requires an id and at least one target");
+    }
+    if (this.options.maxRememberedBatches !== void 0 && (!Number.isSafeInteger(this.options.maxRememberedBatches) || this.options.maxRememberedBatches <= 0)) {
+      throw new Error("Telemetry storage router memory must be a positive safe integer");
+    }
+    const targetIds = this.options.targets.map((target) => target.targetId);
+    if (new Set(targetIds).size !== targetIds.length) {
+      throw new Error("Telemetry storage target ids must be unique");
+    }
+    const requiredTargets = this.options.targets.filter((target) => target.delivery === "required");
+    if (!this.options.volatile && requiredTargets.length === 0) {
+      throw new Error("A non-volatile storage router requires a required target");
+    }
+    const defaultExists = this.options.defaultTargetId === null || targetIds.includes(this.options.defaultTargetId);
+    if (!defaultExists) {
+      throw new Error(`Unknown default telemetry target ${this.options.defaultTargetId}`);
+    }
+    const defaultTarget = this.options.targets.find((target) => target.targetId === this.options.defaultTargetId);
+    if (defaultTarget && !defaultTarget.transport.capabilities.queries) {
+      throw new Error(`Default telemetry target ${defaultTarget.targetId} does not support queries`);
+    }
+  }
+  remember(idempotencyKey, targets) {
+    this.committed.set(idempotencyKey, targets);
+    const maximum = this.options.maxRememberedBatches ?? 1024;
+    while (this.committed.size > maximum) {
+      const oldest = this.committed.keys().next().value;
+      if (typeof oldest !== "string") {
+        return;
+      }
+      this.committed.delete(oldest);
+    }
+  }
+  errorMessage(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+  }
+};
+export {
+  BoundedMetadataSnapshotter,
+  DEFAULT_METADATA_SNAPSHOT_LIMITS,
+  DEFAULT_TELEMETRY_ADMISSION_POLICY,
+  DEFAULT_TELEMETRY_BATCH_VALIDATION_LIMITS,
+  MetricDefinitionContract,
+  MetricExtractor,
+  TelemetryAcknowledgementContract,
+  TelemetryBatchContract,
+  TelemetryBatchRouter,
+  TelemetryClient,
+  TelemetryStorageRouter
+};
+//# sourceMappingURL=index.js.map