@ngockhoale/ukit 3.0.8 → 3.0.10

package/src/core/memory/writeClassification.js

@@ -0,0 +1,161 @@
+// writeClassification — deterministic classification of incoming writes
+// (SPEC §5 FR-020..FR-022). Pure, no I/O: same candidate + existing set
+// always yields the same {action, targetId?, reason}. Wired into
+// mutateMemory op:'add' as the default classifyAdd so duplicates,
+// enrichments, supersessions, and conflicts resolve predictably; conflicts
+// and user-edited records land in a bounded REVIEW queue, never
+// auto-authoritative.
+//
+// Normalization matches store.js normalizePatternText: lowercase +
+// whitespace-collapse + trim.
+
+import { MAX_EVIDENCE } from './records.js';
+
+export const REVIEW_QUEUE_MAX = 64;
+
+const USER_WRITERS = new Set(['user', 'cli']);
+const NEGATION_PREFIXES = ['not ', 'never '];
+
+function normalizeText(text) {
+  return String(text ?? '').toLowerCase().replace(/\s+/g, ' ').trim();
+}
+
+function candidateProjectId(candidate) {
+  return candidate?.project_id ?? candidate?.projectId ?? null;
+}
+
+function candidateCreatedBy(candidate) {
+  return candidate?.created_by ?? candidate?.createdBy ?? null;
+}
+
+function candidateEvidence(candidate) {
+  return Array.isArray(candidate?.evidence) ? candidate.evidence : [];
+}
+
+function evidenceKey(entry) {
+  return `${entry?.kind ?? ''}:${entry?.locator ?? ''}`;
+}
+
+function hasDelta(candidate, match) {
+  const existingKeys = new Set((match.evidence ?? []).map(evidenceKey));
+  if (candidateEvidence(candidate).some((e) => !existingKeys.has(evidenceKey(e)))) {
+    return true;
+  }
+  const provenance = candidate?.provenance;
+  if (provenance != null && provenance !== match.provenance) return true;
+  const confidence = candidate?.confidence;
+  if (typeof confidence === 'number' && confidence !== match.confidence) return true;
+  return false;
+}
+
+function isUserEdited(record) {
+  return USER_WRITERS.has(record?.created_by) || record?.meta?.userEdited === true;
+}
+
+function stripNegation(text) {
+  for (const prefix of NEGATION_PREFIXES) {
+    if (text.startsWith(prefix)) return text.slice(prefix.length);
+  }
+  return text;
+}
+
+function isNegationFlip(a, b) {
+  if (a === b) return false;
+  return stripNegation(a) === b || stripNegation(b) === a;
+}
+
+function sameKey(candidate, record) {
+  return normalizeText(candidate?.text) === normalizeText(record?.text)
+    && (candidate?.scope ?? 'repo') === record?.scope
+    && candidateProjectId(candidate) === (record?.project_id ?? null);
+}
+
+/**
+ * classifyWrite(candidate, existing, {now} = {}) →
+ *   {action:'ADD'|'ENRICH'|'SUPERSEDE'|'NOOP'|'REVIEW', targetId?, reason}
+ * `existing` is the record list inside the locked write. Pure + deterministic.
+ */
+export function classifyWrite(candidate, existing = [], { now } = {}) {
+  const records = Array.isArray(existing) ? existing : [];
+  const active = records.filter((r) => r?.status === 'active');
+  const candidateId = candidate?.id ?? candidate?.recordId ?? null;
+
+  // (c) explicit supersession — validated before key matching so a malformed
+  // supersedes list can never silently fall through to ADD/ENRICH.
+  const supersedes = Array.isArray(candidate?.supersedes) ? candidate.supersedes : [];
+  if (supersedes.length > 0) {
+    const targets = [];
+    for (const id of supersedes) {
+      const target = records.find((r) => r.id === id);
+      if (!target || target.id === candidateId || target.superseded_by != null
+          || target.status === 'archived') {
+        return { action: 'REVIEW', reason: 'supersede-invalid' };
+      }
+      targets.push(target);
+    }
+    // (f) user-edited targets are never silently superseded.
+    const writer = candidateCreatedBy(candidate);
+    if (targets.some((t) => isUserEdited(t) && t.created_by !== writer)) {
+      return { action: 'REVIEW', reason: 'user-edit-conflict' };
+    }
+    return { action: 'SUPERSEDE', targetId: targets[0].id, targetIds: targets.map((t) => t.id) };
+  }
+
+  const keyMatch = active.find((r) => sameKey(candidate, r));
+  if (keyMatch) {
+    // (f) same-key writes against a user/cli-authored record from a different
+    // writer go to REVIEW — user edits are never silently enriched away.
+    const writer = candidateCreatedBy(candidate);
+    if (isUserEdited(keyMatch) && writer != null && keyMatch.created_by !== writer) {
+      return { action: 'REVIEW', targetId: keyMatch.id, reason: 'user-edit-conflict' };
+    }
+    // (a) identical key, no new evidence/provenance/confidence → NOOP.
+    if (!hasDelta(candidate, keyMatch)) {
+      return { action: 'NOOP', targetId: keyMatch.id };
+    }
+    // (b) same key with new evidence/provenance/confidence → ENRICH.
+    return { action: 'ENRICH', targetId: keyMatch.id };
+  }
+
+  const candidateText = normalizeText(candidate?.text);
+  const sameText = active.filter((r) => normalizeText(r?.text) === candidateText);
+
+  // (d) same normalized text under a different scope/project_id → ambiguous.
+  if (sameText.length > 0) {
+    return { action: 'REVIEW', reason: 'scope-ambiguous' };
+  }
+
+  // (e) contradiction heuristic — same meta.signature/meta.subject with a
+  // different value/text, or a negation-only text delta.
+  const signature = candidate?.meta?.signature ?? candidate?.signature;
+  const subject = candidate?.meta?.subject ?? candidate?.subject;
+  for (const record of active) {
+    const sameHandle = (signature != null && record?.meta?.signature === signature)
+      || (subject != null && record?.meta?.subject === subject);
+    if (sameHandle && normalizeText(record.text) !== candidateText) {
+      return { action: 'REVIEW', reason: 'contradiction' };
+    }
+    if (isNegationFlip(candidateText, normalizeText(record?.text))) {
+      return { action: 'REVIEW', reason: 'contradiction' };
+    }
+  }
+
+  return { action: 'ADD' };
+}
+
+/**
+ * mergeEvidence(existing, incoming) → evidence[] — union by kind:locator,
+ * bounded at MAX_EVIDENCE (existing entries keep precedence).
+ */
+export function mergeEvidence(existing = [], incoming = []) {
+  const merged = [...(Array.isArray(existing) ? existing : [])];
+  const seen = new Set(merged.map(evidenceKey));
+  for (const entry of Array.isArray(incoming) ? incoming : []) {
+    const key = evidenceKey(entry);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    merged.push(entry);
+    if (merged.length >= MAX_EVIDENCE) break;
+  }
+  return merged.slice(0, MAX_EVIDENCE);
+}

package/src/core/memory/writeGuard.js

@@ -0,0 +1,129 @@
+/**
+ * writeGuard.js (C58 TASK-002 — SPEC §5 FR-004/005/006, §14)
+ *
+ * Redact/reject engine shared by every memory write entry point.
+ * - guardWritePayload: reject-mode for interactive/single writes.
+ * - redactWritePayload: redact-mode for bulk lanes (migration/export) so a
+ *   secret-bearing record is sanitized instead of silently dropped.
+ *
+ * Deep-scans payload.text, every string leaf of payload.meta, and
+ * payload.evidence[*].locator / .fingerprint. Leak-safety contract: return
+ * values carry labels only — never a matched value, excerpt, or hash.
+ * Never throws; non-string/non-object input is a clean passthrough.
+ */
+
+import {
+  scanText,
+  redactText,
+  isSensitiveDataGateEnabled,
+  loadSensitiveAllowlist,
+} from '../sensitiveValueScanner.js';
+import { resolveMemoryStage } from './memoryFlags.js';
+function* stringLeaves(value) {
+  if (typeof value === 'string') {
+    yield value;
+  } else if (Array.isArray(value)) {
+    for (const item of value) yield* stringLeaves(item);
+  } else if (value && typeof value === 'object') {
+    for (const key of Object.keys(value)) yield* stringLeaves(value[key]);
+  }
+}
+
+function* payloadStrings(payload) {
+  if (typeof payload.text === 'string') yield payload.text;
+  if (payload.meta && typeof payload.meta === 'object') {
+    yield* stringLeaves(payload.meta);
+  }
+  if (Array.isArray(payload.evidence)) {
+    for (const ev of payload.evidence) {
+      if (!ev || typeof ev !== 'object') continue;
+      if (typeof ev.locator === 'string') yield ev.locator;
+      if (typeof ev.fingerprint === 'string') yield ev.fingerprint;
+    }
+  }
+}
+
+function scanOptions(config) {
+  return {
+    allowlistHashes: loadSensitiveAllowlist(config),
+    gateEnabled: isSensitiveDataGateEnabled(config),
+  };
+}
+
+/**
+ * Reject-mode gate: returns {ok:true} when the payload carries no
+ * high-confidence secret values, else {ok:false, reason:'secret-detected',
+ * labels}. Gate off or non-object input → {ok:true}.
+ */
+export function guardWritePayload(payload, { config, projectId } = {}) {
+  try {
+    if (!payload || typeof payload !== 'object') return { ok: true };
+    // M06 rollout flag (SPEC §5 FR-003): writer stage 'off' denies the write
+    // at the guard too — defense-in-depth behind mutateMemory's own consult.
+    // Only consulted when a memoryV2 block exists; absent config (user lane,
+    // legacy callers) keeps the guard purely a secret gate.
+    if (config?.memoryV2 && typeof config.memoryV2 === 'object'
+      && resolveMemoryStage(config, 'writer', { projectId }) === 'off') {
+      return { ok: false, reason: 'writer-disabled' };
+    }
+    const opts = scanOptions(config);
+    const labels = new Set();
+    for (const text of payloadStrings(payload)) {
+      const res = scanText(text, opts);
+      for (const label of res.labels) labels.add(label);
+    }
+    if (labels.size === 0) return { ok: true };
+    return { ok: false, reason: 'secret-detected', labels: [...labels] };
+  } catch {
+    return { ok: true };
+  }
+}
+
+/**
+ * Redact-mode gate: returns a new payload with every matched secret span
+ * replaced by `[REDACTED:<label>]`. Input is never mutated. Gate off or
+ * non-object input → `{payload, redacted:false, labels:[]}` passthrough.
+ */
+export function redactWritePayload(payload, { config } = {}) {
+  try {
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+      return { payload, redacted: false, labels: [] };
+    }
+    const opts = scanOptions(config);
+    if (opts.gateEnabled === false) return { payload, redacted: false, labels: [] };
+
+    const labels = new Set();
+    let redacted = false;
+    const redactValue = (value) => {
+      if (typeof value === 'string') {
+        const res = redactText(value, opts);
+        for (const label of res.labels) labels.add(label);
+        if (res.redacted) redacted = true;
+        return res.text;
+      }
+      if (Array.isArray(value)) return value.map(redactValue);
+      if (value && typeof value === 'object') {
+        const out = {};
+        for (const key of Object.keys(value)) out[key] = redactValue(value[key]);
+        return out;
+      }
+      return value;
+    };
+
+    const next = { ...payload };
+    if (typeof payload.text === 'string') next.text = redactValue(payload.text);
+    if (payload.meta && typeof payload.meta === 'object') next.meta = redactValue(payload.meta);
+    if (Array.isArray(payload.evidence)) {
+      next.evidence = payload.evidence.map((ev) => {
+        if (!ev || typeof ev !== 'object') return ev;
+        const out = { ...ev };
+        if (typeof ev.locator === 'string') out.locator = redactValue(ev.locator);
+        if (typeof ev.fingerprint === 'string') out.fingerprint = redactValue(ev.fingerprint);
+        return out;
+      });
+    }
+    return { payload: next, redacted, labels: [...labels] };
+  } catch {
+    return { payload, redacted: false, labels: [] };
+  }
+}

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

@@ -0,0 +1,90 @@
+// hookTelemetryAdapter.js (TASK-001, SPEC §2 G2-FR02/FR05, DF-FR08) — the
+// minimal observer seam over existing hook latency telemetry. Rows are
+// produced today by `template_project/.claude/ukit/runtime/hook-telemetry.mjs`
+// (`buildTimingRow`, TELEMETRY_VERSION 1) and by `hook-chain-runner.mjs`.
+// This adapter is a PURE, read-only transform: it never reads files, never
+// mutates the owner event, and never wires hooks itself — callers pass one
+// row through and receive a sanitized SemanticRecord (or null) to feed
+// `recorder.emit()` inside the hook deadline.
+//
+//   adaptHookTelemetryEvent(event, ctx?) → SemanticRecord | null
+//
+// Only allowlisted metadata crosses the seam: hook identity (event, hook
+// path, tool name), outcome, and measured timings. tool_use_id, session ids,
+// payload bodies, and any field outside the support allowlist never reach a
+// record.
+//
+// DF-FR08: hook rows carry no host usage, so `payload.resource` is always
+// `{ value: null, source: 'UNKNOWN' }` — unknown is never 0, never invented.
+// An unmeasurable elapsed window (`elapsedMs: null`) stays `duration_ms:
+// null` and marks `telemetry_complete: false`; the optional stage split maps
+// to `queue_ms` only when the owner actually measured it.
+
+import {
+  isPlainObject,
+  asString,
+  asIsoTime,
+  createAdapterContext,
+  emitRecord,
+} from './common.js';
+
+const TELEMETRY_ROW_VERSION = 1;
+
+// Owner outcome vocabulary that means the hook run did not complete
+// successfully. Everything else (ok, allow, pass, skip, ...) is a completed
+// invocation — the raw outcome string still travels in payload.outcome.
+const FAILED_OUTCOMES = new Set([
+  'error',
+  'fail',
+  'failed',
+  'timeout',
+  'deny',
+  'denied',
+  'block',
+  'blocked',
+  'crash',
+  'killed',
+]);
+
+function finiteMs(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+}
+
+export function adaptHookTelemetryEvent(event, ctx) {
+  if (!isPlainObject(event)) return null;
+  // Version gate: rows from a newer owner format are unallowlisted input —
+  // adapting them would guess at field meanings, so they never persist.
+  if (event.v !== TELEMETRY_ROW_VERSION) return null;
+
+  const hook = asString(event.hook);
+  const hookEvent = asString(event.hookEvent ?? event.event);
+  const toolName = asString(event.toolName ?? event.tool);
+  // A row that names nothing observable (no hook, event, or tool) carries no
+  // safe provenance — drop it rather than emit an anonymous record.
+  if (!hook && !hookEvent && !toolName) return null;
+
+  const durationMs = finiteMs(event.elapsedMs);
+  const stageMs = finiteMs(event.stageMs);
+  const outcome = asString(event.outcome) ?? 'ok';
+
+  const context = ctx && typeof ctx === 'object' && typeof ctx.now === 'function'
+    ? ctx
+    : createAdapterContext({ writerId: 'adapter-hook-telemetry' });
+
+  const payload = {
+    operation: hookEvent,
+    name: hook,
+    tool_name: toolName,
+    outcome,
+    duration_ms: durationMs,
+    resource: { value: null, source: 'UNKNOWN' },
+    telemetry_complete: durationMs !== null,
+  };
+  if (stageMs !== null) payload.queue_ms = stageMs;
+
+  return emitRecord(context, {
+    semantic_name: FAILED_OUTCOMES.has(outcome.toLowerCase()) ? 'tool.failed' : 'tool.completed',
+    wall_time_utc: asIsoTime(event.ts),
+    payload,
+  });
+}

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

@@ -0,0 +1,148 @@
+/**
+ * cohorts.js (C73 TASK-001, SPEC §2 G3-FR04/G3-FR05, §4) — cohort projection.
+ *
+ *   cohortize(summaries) → Map<key, cohort>
+ *
+ * Groups TraceSummary rows into honest cohorts. Cohort key components:
+ *   operation      — operation family of the trace's first root span
+ *   model_version  — summary.metric_version
+ *   token_source   — sorted unique resource sources ('+'-joined when mixed)
+ *   telemetry      — 'complete' | 'incomplete'
+ *   task_type      — summary.task_type (appended last: key format stays
+ *                    additive for existing consumers)
+ *
+ * Any missing or unattributable field maps to the literal key `UNKNOWN` —
+ * never dropped, never coerced to 0. A trace with no resource values lands
+ * in a `token_source=UNKNOWN` cohort that still carries its own denominator
+ * (records + traces) so unknown usage is visible, not silently 0.
+ *
+ * Each cohort carries:
+ *   { key, operation, model_version, token_source, telemetry, task_type,
+ *     count,
+ *     denominators: { records, traces },
+ *     aggregates:  { resource_total, resource_numeric, resource_unknown,
+ *                    critical_path_max, dropped_count, retries },
+ *     coverage:    { spans, open_spans, orphan_spans, duplicate_ends } }
+ *
+ * Pure function: no IO, no clock, no randomness. Iteration order of the
+ * returned Map is sorted cohort keys — deterministic regardless of input
+ * order (summaries are sorted by trace_id before grouping).
+ */
+
+const UNKNOWN = 'UNKNOWN';
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function num(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+
+/** Operation family: the first root span wins; unattributable → UNKNOWN. */
+function operationOf(summary) {
+  const spans = Array.isArray(summary.spans) ? summary.spans : [];
+  if (spans.length === 0) return UNKNOWN;
+  const ids = new Set(spans.map((s) => s && s.span_id));
+  const root = spans.find(
+    (s) => !s || typeof s.parent_span_id !== 'string' || !ids.has(s.parent_span_id),
+  );
+  const family = (root || spans[0]) && (root || spans[0]).family;
+  return typeof family === 'string' && family.length > 0 ? family : UNKNOWN;
+}
+
+/** Token source: sorted unique resource.sources keys; none → UNKNOWN. */
+function tokenSourceOf(summary) {
+  const sources = isPlainObject(summary.resource) && isPlainObject(summary.resource.sources)
+    ? Object.keys(summary.resource.sources).filter((k) => summary.resource.sources[k] > 0).sort()
+    : [];
+  return sources.length > 0 ? sources.join('+') : UNKNOWN;
+}
+
+function modelVersionOf(summary) {
+  return typeof summary.metric_version === 'string' && summary.metric_version.length > 0
+    ? summary.metric_version
+    : UNKNOWN;
+}
+function taskTypeOf(summary) {
+  return typeof summary.task_type === 'string' && summary.task_type.length > 0
+    ? summary.task_type
+    : UNKNOWN;
+}
+
+export function cohortize(summaries) {
+  const input = Array.isArray(summaries) ? summaries.filter(isPlainObject) : [];
+  const ordered = input
+    .slice()
+    .sort((a, b) => String(a.trace_id).localeCompare(String(b.trace_id)));
+
+  const byKey = new Map();
+  for (const summary of ordered) {
+    const operation = operationOf(summary);
+    const model_version = modelVersionOf(summary);
+    const token_source = tokenSourceOf(summary);
+    const telemetry = summary.telemetry_complete === true ? 'complete' : 'incomplete';
+    const task_type = taskTypeOf(summary);
+    const key = `operation=${operation}|model_version=${model_version}|token_source=${token_source}|telemetry=${telemetry}|task_type=${task_type}`;
+
+    let cohort = byKey.get(key);
+    if (!cohort) {
+      cohort = {
+        key,
+        operation,
+        model_version,
+        token_source,
+        telemetry,
+        task_type,
+        count: 0,
+        denominators: { records: 0, traces: 0 },
+        aggregates: {
+          resource_total: null,
+          resource_numeric: 0,
+          resource_unknown: 0,
+          critical_path_max: null,
+          dropped_count: 0,
+          retries: 0,
+        },
+        coverage: { spans: 0, open_spans: 0, orphan_spans: 0, duplicate_ends: 0 },
+      };
+      byKey.set(key, cohort);
+    }
+
+    const cov = isPlainObject(summary.coverage) ? summary.coverage : {};
+    const res = isPlainObject(summary.resource) ? summary.resource : {};
+    const retries = isPlainObject(summary.retries) ? summary.retries : {};
+    const drops = isPlainObject(summary.drops) ? summary.drops : {};
+
+    cohort.count += 1;
+    cohort.denominators.records += num(cov.records);
+    cohort.denominators.traces += 1;
+
+    if (typeof res.total_value === 'number' && Number.isFinite(res.total_value)) {
+      cohort.aggregates.resource_total = (cohort.aggregates.resource_total || 0) + res.total_value;
+    }
+    cohort.aggregates.resource_numeric += num(res.numeric_count);
+    cohort.aggregates.resource_unknown += num(res.unknown_count);
+    if (typeof summary.critical_path_ms === 'number' && Number.isFinite(summary.critical_path_ms)) {
+      if (
+        cohort.aggregates.critical_path_max === null ||
+        summary.critical_path_ms > cohort.aggregates.critical_path_max
+      ) {
+        cohort.aggregates.critical_path_max = summary.critical_path_ms;
+      }
+    }
+    cohort.aggregates.dropped_count += num(drops.dropped_count);
+    cohort.aggregates.retries += num(retries.retries);
+
+    cohort.coverage.spans += num(cov.spans);
+    cohort.coverage.open_spans += num(cov.open_spans);
+    cohort.coverage.orphan_spans += num(cov.orphan_spans);
+    cohort.coverage.duplicate_ends += num(cov.duplicate_ends);
+  }
+
+  // Deterministic iteration: sorted cohort keys only.
+  const sorted = new Map(
+    [...byKey.entries()].sort((a, b) => a[0].localeCompare(b[0])),
+  );
+  return sorted;
+}

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

@@ -0,0 +1,163 @@
+/**
+ * storeDigest.js (C73 TASK-001, SPEC §2 G3-FR02/G3-FR03, §4) — store-level
+ * deterministic digest over a rebuildIndex result.
+ *
+ *   renderStoreDigest(rebuildResult, opts?) → string
+ *   digestStoreHash(rebuildResult)          → sha256 hex
+ *
+ * The store digest is the W3 byte-identity artifact: one bounded markdown
+ * document over the whole rebuild result — a store header (records read,
+ * traces, coverage gaps, ok flag), one compact fingerprint line per trace,
+ * and a cohort table where every aggregate carries numerator/denominator
+ * and coverage. Unknowns render as `unknown`, never `0`.
+ *
+ *   digestStoreHash canonicalizes the rebuild result (stable key order,
+ *   trace order sorted by trace_id) and hashes it — two rebuilds over the
+ *   same retained facts MUST produce the same hex string.
+ *
+ * Contract:
+ *   - Hard cap: output never exceeds STORE_DIGEST_MAX_BYTES (default 16KB;
+ *     opts.maxBytes overrides). Overflow is truncated deterministically
+ *     with an explicit marker — never silent.
+ *   - Deterministic: no clock, no randomness; sorted trace order and
+ *     sorted cohort keys only.
+ *   - Pure/read-only: no fs, no writes.
+ */
+
+import crypto from 'node:crypto';
+
+import { cohortize } from './cohorts.js';
+
+export const STORE_DIGEST_MAX_BYTES = 16 * 1024;
+
+const MAX_TRACE_ROWS = 256;
+const MAX_COHORT_ROWS = 64;
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function fmtNum(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? String(value) : 'unknown';
+}
+
+/** Stable stringify: object keys sorted at every depth, arrays in order. */
+function stableStringify(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+  }
+  const keys = Object.keys(value).sort();
+  const parts = keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`);
+  return `{${parts.join(',')}}`;
+}
+
+function canonicalResult(rebuildResult) {
+  const r = isPlainObject(rebuildResult) ? rebuildResult : {};
+  const summaries = (Array.isArray(r.summaries) ? r.summaries : [])
+    .slice()
+    .sort((a, b) => String(a && a.trace_id).localeCompare(String(b && b.trace_id)));
+  return { summaries, coverage: isPlainObject(r.coverage) ? r.coverage : {}, ok: r.ok === true };
+}
+
+/**
+ * sha256 over the canonical serialization of { summaries, coverage, ok }.
+ * Trace order is normalized by trace_id and object key order is stable, so
+ * byte-identity of the hash is byte-identity of the rebuild, not of the
+ * in-memory shape.
+ */
+export function digestStoreHash(rebuildResult) {
+  const canonical = stableStringify(canonicalResult(rebuildResult));
+  return crypto.createHash('sha256').update(canonical, 'utf8').digest('hex');
+}
+
+function traceLine(summary) {
+  const s = isPlainObject(summary) ? summary : {};
+  const cov = isPlainObject(s.coverage) ? s.coverage : {};
+  const res = isPlainObject(s.resource) ? s.resource : {};
+  const drops = isPlainObject(s.drops) ? s.drops : {};
+  return (
+    `- ${s.trace_id || 'unknown'}` +
+    ` | spans=${fmtNum(cov.spans)}` +
+    ` | critical_path_ms=${fmtNum(s.critical_path_ms)}` +
+    ` | resource_total=${fmtNum(res.total_value)} (numeric=${fmtNum(res.numeric_count)}, unknown=${fmtNum(res.unknown_count)})` +
+    ` | drops=${fmtNum(drops.dropped_count)}` +
+    ` | telemetry=${s.telemetry_complete === true ? 'complete' : 'incomplete'}`
+  );
+}
+
+function cohortRow(cohort) {
+  return (
+    `| ${cohort.operation} | ${cohort.model_version} | ${cohort.token_source}` +
+    ` | ${cohort.telemetry} | ${cohort.denominators.traces}` +
+    ` | ${cohort.denominators.records}` +
+    ` | ${fmtNum(cohort.aggregates.resource_total)}` +
+    ` | ${cohort.aggregates.resource_numeric}/${cohort.aggregates.resource_unknown}` +
+    ` | ${fmtNum(cohort.aggregates.critical_path_max)}` +
+    ` | ${cohort.aggregates.dropped_count}` +
+    ` | ${cohort.coverage.open_spans} |`
+  );
+}
+
+export function renderStoreDigest(rebuildResult, opts = {}) {
+  const r = canonicalResult(rebuildResult);
+  const cov = r.coverage;
+  const maxBytes = Number.isInteger(opts.maxBytes) && opts.maxBytes > 0
+    ? opts.maxBytes
+    : STORE_DIGEST_MAX_BYTES;
+
+  const head = [
+    '# store digest',
+    `ok: ${r.ok ? 'true' : 'false'}`,
+    `records_read: ${fmtNum(cov.records_read)}`,
+    `traces: ${fmtNum(cov.traces)}`,
+    `untraced_records: ${fmtNum(cov.untraced_records)}`,
+    '',
+    '## coverage gaps',
+    `corrupt_lines: ${fmtNum(cov.corrupt_lines)}`,
+    `partial_tail_bytes: ${fmtNum(cov.partial_tail_bytes)}`,
+    `quarantined: ${fmtNum(cov.quarantined_segments)}`,
+    `expired_segments: ${fmtNum(cov.expired_segments)}`,
+    `cursor_missed: ${cov.cursor_missed === true ? 'true' : 'false'}`,
+    `degraded: ${Array.isArray(cov.degraded) ? cov.degraded.length : 0}`,
+    '',
+  ];
+
+  const summaries = r.summaries;
+  const shown = summaries.slice(0, MAX_TRACE_ROWS);
+  const traceLines = ['## traces', `summaries: ${summaries.length} total, ${shown.length} shown`];
+  for (const summary of shown) traceLines.push(traceLine(summary));
+  if (summaries.length > shown.length) {
+    traceLines.push(`- … truncated: ${summaries.length - shown.length} trace(s) omitted (digest cap)`);
+  }
+  traceLines.push('');
+
+  const cohorts = [...cohortize(summaries).values()];
+  const shownCohorts = cohorts.slice(0, MAX_COHORT_ROWS);
+  const cohortLines = [
+    '## cohorts',
+    `cohorts: ${cohorts.length} total`,
+    '| operation | model_version | token_source | telemetry | traces | records | resource_total | resource(numeric/unknown) | critical_path_max | dropped | open_spans |',
+  ];
+  for (const cohort of shownCohorts) cohortLines.push(cohortRow(cohort));
+  if (cohorts.length > shownCohorts.length) {
+    cohortLines.push(`- … truncated: ${cohorts.length - shownCohorts.length} cohort(s) omitted (digest cap)`);
+  }
+
+  let out = [...head, ...traceLines, ...cohortLines].join('\n');
+
+  // Hard cap: deterministic tail truncation with an explicit marker.
+  if (Buffer.byteLength(out, 'utf8') > maxBytes) {
+    const marker = '\n[truncated: store digest exceeded byte cap]\n';
+    const budget = maxBytes - 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;
+}