@ngockhoale/ukit 3.0.6 → 3.0.8

package/src/core/observability/adapters/contextAdapter.js

@@ -0,0 +1,55 @@
+// contextAdapter.js (TASK-010, SPEC §5 DF-FR07/DF-FR08) — read-only
+// adapter over context-item provenance (retrieval lane / output history).
+// It records which items were selected, injected, and later referenced —
+// kind and opaque ref only, never item content.
+//
+//   adaptContextItems(items, options?) → records[]
+//
+// Each item becomes one `context.item.injected` fact. Provenance fields
+// stay distinct: `selected` (chosen by the lane), `injected` (entered the
+// episode), `referenced` (observed in the output). An injected-but-
+// unreferenced item is marked `usage_signal: 'potentially_unused'` with an
+// `evaluator_caveat` — a heuristic signal for the evaluator, never a
+// `wasted` verdict: the host may have consumed the item without leaving a
+// visible reference.
+
+import {
+  isPlainObject,
+  asString,
+  asIsoTime,
+  createAdapterContext,
+  emitRecord,
+} from './common.js';
+
+const UNUSED_CAVEAT =
+  'injected-not-referenced is a heuristic signal only; the host may have ' +
+  'consumed the item without a visible reference — requires evaluator confirmation';
+
+export function adaptContextItems(items, options = {}) {
+  if (!Array.isArray(items)) return [];
+  const ctx = createAdapterContext({ writerId: 'adapter-context', ...options });
+  const records = [];
+
+  for (const item of items) {
+    if (!isPlainObject(item)) continue;
+    const injected = item.injected === true;
+    const referenced = item.referenced === true;
+    const potentiallyUnused = injected && !referenced;
+    const record = emitRecord(ctx, {
+      semantic_name: 'context.item.injected',
+      wall_time_utc: asIsoTime(item.ts) ?? asIsoTime(item.injectedAt),
+      payload: {
+        kind: asString(item.kind) ?? asString(item.type),
+        item_ref: asString(item.ref) ?? asString(item.id),
+        selected: item.selected === true || injected,
+        injected,
+        referenced,
+        usage_signal: potentiallyUnused ? 'potentially_unused' : referenced ? 'referenced' : null,
+        evaluator_caveat: potentiallyUnused ? UNUSED_CAVEAT : null,
+      },
+    });
+    if (record) records.push(record);
+  }
+
+  return records;
+}

package/src/core/observability/adapters/decisionAdapter.js

@@ -0,0 +1,61 @@
+// decisionAdapter.js (TASK-010, SPEC §5 DF-FR07) — read-only adapter over
+// decision receipts produced by `src/decision/shadow.js`
+// (runShadowDecisions → receipt) and `src/decision/preflight.js`
+// (applyPreflight → receipt). Receipts are consumed as provenance inputs,
+// never re-executed and never treated as a second completion gate.
+//
+//   adaptDecisionReceipts(receipts, options?) → records[]
+//
+// Each receipt becomes one `decision.made` record (record_type 'decision',
+// origin.experiment required by the schema). `applied` is true ONLY when
+// the receipt carries host acknowledgement — `status: 'applied'` or
+// `acknowledged: true` (preflight.js: a suggestion is never applied
+// without acknowledgement). A shadow-stage or unacknowledged receipt
+// records `applied: false`: selected ≠ applied.
+
+import {
+  isPlainObject,
+  asString,
+  asStringArray,
+  asIsoTime,
+  createAdapterContext,
+  emitRecord,
+} from './common.js';
+
+export function adaptDecisionReceipts(receipts, options = {}) {
+  if (!Array.isArray(receipts)) return [];
+  const ctx = createAdapterContext({ writerId: 'adapter-decision', ...options });
+  const records = [];
+
+  for (const receipt of receipts) {
+    if (!isPlainObject(receipt)) continue;
+    const applied = receipt.status === 'applied' || receipt.acknowledged === true;
+    const record = emitRecord(ctx, {
+      record_type: 'decision',
+      semantic_name: 'decision.made',
+      wall_time_utc: asIsoTime(receipt.ts) ?? asIsoTime(receipt.createdAt),
+      origin: {
+        experiment: asString(receipt.experiment) ?? 'decision-plane',
+        stage: asString(receipt.stage),
+        checkpoint: asString(receipt.checkpoint),
+      },
+      payload: {
+        batch_id: asString(receipt.batchId),
+        stage: asString(receipt.stage),
+        outcome_class: asString(receipt.outcomeClass),
+        latency_class: asString(receipt.latencyClass),
+        fallback_code: asString(receipt.fallbackCode),
+        decision_keys: asStringArray(receipt.decisionKeys),
+        probability_bands: isPlainObject(receipt.probabilityBands) ? receipt.probabilityBands : {},
+        agreement: isPlainObject(receipt.agreement) ? receipt.agreement : null,
+        selected: true,
+        applied,
+        confirmation: asString(receipt.confirmation),
+        evidence_refs: asStringArray(receipt.evidenceRefs),
+      },
+    });
+    if (record) records.push(record);
+  }
+
+  return records;
+}

package/src/core/observability/adapters/routeAdapter.js

@@ -0,0 +1,135 @@
+// routeAdapter.js (TASK-010, SPEC §5 DF-FR07/DF-FR08) — read-only adapter
+// over the route-audit + exec-ledger join owned by
+// `src/diagnostics/routeOutcomes.js` (`collectRouteOutcomes(projectRoot,
+// { limitLedgers })`). This module never reads files itself and never
+// modifies the owner: callers pass the joined rows through and receive
+// sanitized semantic records back.
+//
+//   adaptRouteOutcomes(rows, options?) → records[]
+//
+// `rows` accepts either joined pairs `{ audit, ledger }` or flat owner
+// rows carrying the same field names. Only safe metadata crosses the
+// boundary: requestKey (opaque ref), taskType/executionMode, write and
+// verification outcome booleans, repeat/rescue codes, receipt refs, and
+// typed resource usage. Raw paths, transcripts, verdicts, blockers and
+// receipt content are never copied — the privacy gate is the boundary,
+// not field selection alone.
+//
+// DF-FR08: when a ledger row reports a model attempt, a `model.*` record
+// is emitted with typed resource usage — provider-reported counts keep
+// their source, estimates are marked ESTIMATED, and absent host data is
+// `{ value: null, source: 'UNKNOWN' }` with `telemetry_complete: false`.
+// Unknown is never 0 and never fabricated.
+
+import {
+  isPlainObject,
+  asString,
+  asStringArray,
+  asIsoTime,
+  createAdapterContext,
+  emitRecord,
+} from './common.js';
+
+const RESOURCE_SOURCES = new Set(['PROVIDER', 'LOCAL_TOKENIZER', 'ESTIMATED', 'UNKNOWN']);
+
+function normalizeRow(row) {
+  if (!isPlainObject(row)) return null;
+  const audit = isPlainObject(row.audit) ? row.audit : row;
+  const ledger = isPlainObject(row.ledger) ? row.ledger : row;
+  const requestKey = asString(audit.requestKey) ?? asString(ledger.requestKey);
+  if (!requestKey) return null;
+  return { audit, ledger, requestKey };
+}
+
+function executionSemantic(audit, ledger) {
+  if (audit.rescueMode != null) return 'execution.blocked';
+  if (ledger.writeAttempted === true && ledger.writeSucceeded !== true) return 'execution.failed';
+  if (ledger.verificationFailed === true) return 'execution.failed';
+  if (ledger.writeSucceeded === true) return 'execution.completed';
+  // Audit-only row: the route happened but no ledger evidence exists —
+  // report the start, never a fabricated outcome.
+  return 'execution.started';
+}
+
+function receiptRefs(ledger) {
+  if (!Array.isArray(ledger.receipts)) return [];
+  const refs = [];
+  for (const receipt of ledger.receipts.slice(0, 32)) {
+    const ref = asString(receipt?.receiptId) ?? asString(receipt?.id);
+    if (ref) refs.push(ref);
+  }
+  return refs;
+}
+
+function modelResource(model) {
+  const usage = isPlainObject(model.usage) ? model.usage : {};
+  const reported = usage.totalTokens ?? usage.tokens ?? model.totalTokens ?? model.tokens;
+  const estimated = usage.estimatedTokens ?? model.estimatedTokens;
+  let value = null;
+  let source = 'UNKNOWN';
+  if (typeof reported === 'number' && Number.isFinite(reported)) {
+    value = reported;
+    source = RESOURCE_SOURCES.has(usage.source) && usage.source !== 'UNKNOWN'
+      ? usage.source
+      : 'PROVIDER';
+  } else if (typeof estimated === 'number' && Number.isFinite(estimated)) {
+    value = estimated;
+    source = 'ESTIMATED';
+  }
+  return { value, source };
+}
+
+export function adaptRouteOutcomes(rows, options = {}) {
+  if (!Array.isArray(rows)) return [];
+  const ctx = createAdapterContext({ writerId: 'adapter-route', ...options });
+  const records = [];
+
+  for (const raw of rows) {
+    const row = normalizeRow(raw);
+    if (!row) continue;
+    const { audit, ledger, requestKey } = row;
+
+    const payload = {
+      request_key: requestKey,
+      task_type: asString(audit.taskType),
+      execution_mode: asString(audit.executionMode),
+      write_attempted: ledger.writeAttempted === true,
+      write_succeeded: ledger.writeSucceeded === true,
+      verification_attempted: ledger.verificationAttempted === true,
+      verification_succeeded: ledger.verificationSucceeded === true,
+      verification_failed: ledger.verificationFailed === true,
+      repeat_count: Number.isInteger(audit.repeatCount) ? audit.repeatCount : 0,
+      rescue_mode: asString(audit.rescueMode),
+      receipt_refs: receiptRefs(ledger),
+      telemetry_complete: isPlainObject(row.ledger),
+    };
+    const exec = emitRecord(ctx, {
+      semantic_name: executionSemantic(audit, ledger),
+      wall_time_utc: asIsoTime(audit.ts) ?? asIsoTime(ledger.updatedAt),
+      payload,
+    });
+    if (exec) records.push(exec);
+
+    const model = isPlainObject(ledger.model) ? ledger.model : null;
+    if (model) {
+      const resource = modelResource(model);
+      const failed = model.failed === true || asString(model.status) === 'failed';
+      const modelRecord = emitRecord(ctx, {
+        semantic_name: failed ? 'model.failed' : 'model.completed',
+        wall_time_utc: asIsoTime(audit.ts) ?? asIsoTime(ledger.updatedAt),
+        payload: {
+          request_key: requestKey,
+          duration_ms:
+            typeof model.durationMs === 'number' && Number.isFinite(model.durationMs)
+              ? model.durationMs
+              : null,
+          resource,
+          telemetry_complete: resource.source !== 'UNKNOWN',
+        },
+      });
+      if (modelRecord) records.push(modelRecord);
+    }
+  }
+
+  return records;
+}

package/src/core/observability/analytics/digest.js

@@ -0,0 +1,186 @@
+/**
+ * digest.js (TASK-008, SPEC §5 DF-FR09/DF-FR12, §8) — bounded AI-readable digest.
+ *
+ *   renderTraceDigest(summary, evidence): string
+ *
+ * Renders one TraceSummary (+ optional evidence records) as deterministic
+ * markdown for an AI reader. Section order mirrors the evaluator's reading
+ * sequence (SPEC §12): summary → anomalies → digest → evidence.
+ *
+ * Contract:
+ *   - Hard cap: output never exceeds DIGEST_MAX_BYTES (8KB). Overflow is
+ *     truncated deterministically with an explicit marker — never silent.
+ *   - Unknowns stay explicit: null metrics render as `unknown`, never 0.
+ *   - Drill-down: the evidence section names real record_ids so a reader
+ *     can jump from digest back to retained facts.
+ *   - Deterministic: no clock, no randomness, stable ordering — the same
+ *     summary always renders byte-identical output.
+ */
+
+export const DIGEST_MAX_BYTES = 8 * 1024;
+
+const MAX_SPAN_ROWS = 40;
+const MAX_EVIDENCE_REFS = 24;
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function fmtMs(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? `${value}ms` : 'unknown';
+}
+
+function fmtNum(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? String(value) : 'unknown';
+}
+
+function fmtRate(value) {
+  return typeof value === 'number' && Number.isFinite(value)
+    ? `${(value * 100).toFixed(1)}%`
+    : 'unknown';
+}
+
+function fmtPctile(stats) {
+  if (!isPlainObject(stats)) return 'p50=unknown p95=unknown p99=unknown';
+  return `n=${stats.count} p50=${fmtMs(stats.p50)} p95=${fmtMs(stats.p95)} p99=${fmtMs(stats.p99)}`;
+}
+
+function normalizeEvidence(evidence) {
+  if (Array.isArray(evidence)) return { records: evidence.filter(isPlainObject), coverage: null };
+  if (isPlainObject(evidence)) {
+    return {
+      records: Array.isArray(evidence.records) ? evidence.records.filter(isPlainObject) : [],
+      coverage: isPlainObject(evidence.coverage) ? evidence.coverage : null,
+    };
+  }
+  return { records: [], coverage: null };
+}
+
+/** Record IDs worth drilling into: drops, failures, redactions, high-importance. */
+function evidenceRefs(records) {
+  const refs = [];
+  for (const record of records) {
+    const name = record.semantic_name || '';
+    const anomalous =
+      name.startsWith('telemetry.') ||
+      name.endsWith('.failed') ||
+      name.endsWith('.blocked') ||
+      record.importance === 'high' ||
+      record.importance === 'critical';
+    if (anomalous && typeof record.record_id === 'string') {
+      refs.push(`${record.record_id} (${name})`);
+    }
+  }
+  return refs;
+}
+
+function anomalyLines(summary) {
+  const lines = [];
+  if (summary.telemetry_complete === false) {
+    lines.push('- telemetry incomplete: drops, gaps, or host-blind fields present');
+  }
+  if (summary.drops && summary.drops.dropped_count > 0) {
+    const reasons = Object.keys(summary.drops.by_reason || {}).sort();
+    lines.push(`- dropped records: ${summary.drops.dropped_count} (reasons: ${reasons.join(', ') || 'UNSPECIFIED'})`);
+  }
+  if (summary.drops && summary.drops.redacted > 0) {
+    lines.push(`- redacted records: ${summary.drops.redacted}`);
+  }
+  if (summary.retries && summary.retries.retries > 0) {
+    lines.push(`- retries: ${summary.retries.retries} (model attempts: ${summary.retries.model_attempts})`);
+  }
+  if (summary.retries && summary.retries.failed_spans > 0) {
+    lines.push(`- failed spans: ${summary.retries.failed_spans}`);
+  }
+  if (summary.resource && summary.resource.unknown_count > 0) {
+    lines.push(`- host-blind resource usage: ${summary.resource.unknown_count} record(s) UNKNOWN`);
+  }
+  if (summary.coverage) {
+    if (summary.coverage.open_spans > 0) lines.push(`- open spans (no end record): ${summary.coverage.open_spans}`);
+    if (summary.coverage.orphan_spans > 0) lines.push(`- orphan spans (missing parent): ${summary.coverage.orphan_spans}`);
+    if (summary.coverage.duplicate_ends > 0) lines.push(`- duplicate span ends: ${summary.coverage.duplicate_ends}`);
+  }
+  if (lines.length === 0) lines.push('- none');
+  return lines;
+}
+
+function spanRow(span) {
+  const parent = span.parent_span_id ? ` parent=${span.parent_span_id}` : '';
+  const attempt = typeof span.attempt_index === 'number' ? ` attempt=${span.attempt_index}` : '';
+  const op = span.operation ? ` op=${span.operation}` : '';
+  return `- ${span.span_id} ${span.family}.${span.status} dur=${fmtMs(span.duration_ms)}${attempt}${op}${parent}`;
+}
+
+export function renderTraceDigest(summary, evidence) {
+  const s = isPlainObject(summary) ? summary : {};
+  const { records, coverage } = normalizeEvidence(evidence);
+
+  const head = [
+    '# trace digest',
+    `metric_version: ${s.metric_version || 'unknown'}`,
+    `trace_id: ${s.trace_id || 'unknown'}`,
+    '',
+  ];
+
+  const summaryLines = [
+    '## summary',
+    `telemetry_complete: ${s.telemetry_complete === true ? 'true' : 'false'}`,
+    `critical_path_ms: ${fmtNum(s.critical_path_ms)}`,
+    `durations.overall: ${fmtPctile(s.durations && s.durations.overall)}`,
+    `durations.model: ${fmtPctile(s.durations && s.durations.model)}`,
+    `durations.tool: ${fmtPctile(s.durations && s.durations.tool)}`,
+    `retries: ${s.retries ? s.retries.retries : 'unknown'} (model_attempts=${s.retries ? s.retries.model_attempts : 'unknown'}, failed_spans=${s.retries ? s.retries.failed_spans : 'unknown'})`,
+    `drops: ${s.drops ? s.drops.dropped_count : 'unknown'} (events=${s.drops ? s.drops.events : 'unknown'})`,
+    `cache: hit_rate=${fmtRate(s.cache && s.cache.hit_rate)} (hits=${s.cache ? s.cache.hits : 'unknown'}, misses=${s.cache ? s.cache.misses : 'unknown'})`,
+    `resource: total_value=${fmtNum(s.resource && s.resource.total_value)} (numeric=${s.resource ? s.resource.numeric_count : 'unknown'}, unknown=${s.resource ? s.resource.unknown_count : 'unknown'})`,
+    `coverage: records=${s.coverage ? s.coverage.records : 'unknown'} spans=${s.coverage ? s.coverage.spans : 'unknown'}`,
+    '',
+  ];
+
+  const anomalySection = ['## anomalies', ...anomalyLines(s), ''];
+
+  const spans = Array.isArray(s.spans) ? s.spans : [];
+  const shownSpans = spans.slice(0, MAX_SPAN_ROWS);
+  const digestLines = ['## digest', `spans: ${spans.length} total, ${shownSpans.length} shown`];
+  for (const span of shownSpans) digestLines.push(spanRow(span));
+  if (spans.length > shownSpans.length) {
+    digestLines.push(`- … truncated: ${spans.length - shownSpans.length} span(s) omitted (digest cap)`);
+  }
+  digestLines.push('');
+
+  const refs = evidenceRefs(records);
+  const shownRefs = refs.slice(0, MAX_EVIDENCE_REFS);
+  const evidenceLines = ['## evidence'];
+  if (coverage) {
+    evidenceLines.push(
+      `store: records_read=${fmtNum(coverage.records_read)} traces=${fmtNum(coverage.traces)} corrupt_lines=${fmtNum(coverage.corrupt_lines)} partial_tail_bytes=${fmtNum(coverage.partial_tail_bytes)} quarantined=${fmtNum(coverage.quarantined_segments)}`,
+    );
+  }
+  evidenceLines.push(`records_available: ${records.length}`);
+  if (shownRefs.length > 0) {
+    evidenceLines.push('anomalous record refs:');
+    for (const ref of shownRefs) evidenceLines.push(`- ${ref}`);
+    if (refs.length > shownRefs.length) {
+      evidenceLines.push(`- … truncated: ${refs.length - shownRefs.length} ref(s) omitted (digest cap)`);
+    }
+  } else {
+    evidenceLines.push('anomalous record refs: none');
+  }
+
+  let out = [...head, ...summaryLines, ...anomalySection, ...digestLines, ...evidenceLines].join('\n');
+
+  // Hard cap: deterministic tail truncation with an explicit marker.
+  if (Buffer.byteLength(out, 'utf8') > DIGEST_MAX_BYTES) {
+    const marker = '\n[truncated: digest exceeded 8KB cap]\n';
+    const budget = DIGEST_MAX_BYTES - Buffer.byteLength(marker, 'utf8');
+    let lo = 0;
+    let hi = out.length;
+    while (lo < hi) {
+      const mid = (lo + hi + 1) >> 1;
+      if (Buffer.byteLength(out.slice(0, mid), 'utf8') <= budget) lo = mid;
+      else hi = mid - 1;
+    }
+    out = out.slice(0, lo) + marker;
+  }
+  return out;
+}

package/src/core/observability/analytics/fingerprints.js

@@ -0,0 +1,126 @@
+/**
+ * fingerprints.js (TASK-012, SPEC §5 DF-FR09 / §8) — structural fingerprints.
+ *
+ *   computeFingerprint(summary): { hash, kind, count, metric_version }
+ *
+ * Pure function over ONE TraceSummary. No IO, no clock, no randomness — the
+ * same summary always produces the same fingerprint, and two traces with the
+ * same STRUCTURE (same span families/operations/statuses/attempt pattern and
+ * the same signal counts) share a fingerprint even when every ID differs.
+ *
+ * What the hash covers — and what it deliberately excludes:
+ *   - IN: ordered span descriptors (family, operation, status, attempt_index,
+ *     parent link expressed as a positional index / 'root' / 'orphan') and
+ *     the signal counts (retries, failed spans, cache hits/misses, drop
+ *     events, telemetry completeness).
+ *   - OUT: record/span/trace IDs, timestamps, durations, resource values.
+ *     A fingerprint is a shape, not an identity — durations belong to the
+ *     opportunity layer, never to the grouping key.
+ *
+ * `kind` names the dominant failure/inefficiency pattern, precedence:
+ *   dropped > failure > retry > cache-miss > clean.
+ * `count` is the number of pattern occurrences inside the trace (retries,
+ * failed spans, dropped records, cache misses; 1 for a clean trace).
+ */
+
+import crypto from 'node:crypto';
+
+const FINGERPRINT_VERSION = 1;
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function num(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+/**
+ * Positional parent link: index of the parent inside the summary's own
+ * deterministic span order, 'root' when no parent is declared, 'orphan'
+ * when the declared parent is absent from the summary.
+ */
+function spanDescriptors(spans) {
+  const indexById = new Map();
+  spans.forEach((span, index) => {
+    if (typeof span.span_id === 'string') indexById.set(span.span_id, index);
+  });
+  return spans.map((span) => {
+    let parent = 'root';
+    if (typeof span.parent_span_id === 'string' && span.parent_span_id.length > 0) {
+      parent = indexById.has(span.parent_span_id) ? indexById.get(span.parent_span_id) : 'orphan';
+    }
+    // Model-span operation is the model/version axis — a COHORT key, not a
+    // pattern key. Normalizing it keeps mixed-model traces in one cluster so
+    // the opportunity layer can flag the confound instead of silently
+    // splitting (Simpson's-paradox guard, SPEC §12).
+    const operation =
+      span.family === 'model' ? '<model>' : typeof span.operation === 'string' ? span.operation : null;
+    return [
+      typeof span.family === 'string' ? span.family : 'unknown',
+      operation,
+      typeof span.status === 'string' ? span.status : 'unknown',
+      Number.isInteger(span.attempt_index) ? span.attempt_index : null,
+      parent,
+    ];
+  });
+}
+
+function signalsOf(summary) {
+  const retries = isPlainObject(summary.retries) ? summary.retries : {};
+  const cache = isPlainObject(summary.cache) ? summary.cache : {};
+  const drops = isPlainObject(summary.drops) ? summary.drops : {};
+  return {
+    retries: num(retries.retries),
+    failed_spans: num(retries.failed_spans),
+    cache_hits: num(cache.hits),
+    cache_misses: num(cache.misses),
+    drop_events: num(drops.events),
+    dropped_count: num(drops.dropped_count),
+    telemetry_complete: summary.telemetry_complete === true ? 1 : 0,
+  };
+}
+
+function kindOf(signals) {
+  if (signals.drop_events > 0) return 'dropped';
+  if (signals.failed_spans > 0) return 'failure';
+  if (signals.retries > 0) return 'retry';
+  if (signals.cache_misses > 0) return 'cache-miss';
+  return 'clean';
+}
+
+function countOf(kind, signals) {
+  switch (kind) {
+    case 'dropped':
+      return signals.dropped_count;
+    case 'failure':
+      return signals.failed_spans;
+    case 'retry':
+      return signals.retries;
+    case 'cache-miss':
+      return signals.cache_misses;
+    default:
+      return 1;
+  }
+}
+
+export function computeFingerprint(summary) {
+  if (!isPlainObject(summary) || !Array.isArray(summary.spans)) {
+    throw new TypeError('computeFingerprint: summary must be a TraceSummary object with a spans array');
+  }
+  const spans = summary.spans.filter(isPlainObject);
+  const signals = signalsOf(summary);
+  const kind = kindOf(signals);
+  const canonical = JSON.stringify({
+    v: FINGERPRINT_VERSION,
+    kind,
+    spans: spanDescriptors(spans),
+    signals,
+  });
+  return {
+    hash: crypto.createHash('sha256').update(canonical).digest('hex').slice(0, 16),
+    kind,
+    count: countOf(kind, signals),
+    metric_version: typeof summary.metric_version === 'string' ? summary.metric_version : 'unknown',
+  };
+}