@duckmind/dm-linux-x64 0.65.5 → 0.65.6

package/extensions/dm-lens/dist/clients/cache-observability.js

@@ -0,0 +1,847 @@
+import { createHash } from "node:crypto";
+import { BoundedFifoMap, BoundedLruCache } from "./bounded-cache.js";
+import { lazyEnvNumber } from "./env-utils.js";
+import { logLatency } from "./latency-logger.js";
+import { compareOrdinal } from "./string-utils.js";
+const PROCESS_TURN_SCOPE = "process-global-runtime";
+const SECONDARY_TURN_SCOPE = "unavailable-concurrent-secondary";
+const MAX_HASHED_MESSAGES = 64;
+const MAX_HASHED_CONTENT_CHARS = 2048;
+const MAX_REPORTED_MESSAGES = 1e4;
+const MAX_INJECTED_CHARS = 16384;
+const MAX_INJECTED_BYTES = 65536;
+let contextObservationCounter = 0;
+const CHARS_PER_ESTIMATED_TOKEN = 4;
+export const DEFAULT_PROVIDER_CACHE_TTL_MS = 60000;
+const _providerCacheTtl = lazyEnvNumber("DM_LENS_PROVIDER_CACHE_TTL_MS", DEFAULT_PROVIDER_CACHE_TTL_MS);
+const getProviderCacheTtlMs = _providerCacheTtl.get;
+export const _resetProviderCacheTtlForTests = _providerCacheTtl._resetForTests;
+const LOW_CACHE_READ_RATIO = 0.5;
+const PARTIAL_EVICTION_INPUT_FACTOR = 4;
+const PARTIAL_EVICTION_MIN_FRESH_TOKENS = 512;
+const MAX_ATTRIBUTION_CHARS = 262144;
+const MAX_ATTRIBUTION_BYTES = 1048576;
+function emptyCacheMissCauses() {
+  return {
+    "ttl-expired": 0,
+    "prefix-broke": 0,
+    "partial-eviction": 0,
+    "model-provider-changed": 0,
+    unknown: 0
+  };
+}
+function emptyUnknownEvidenceReasons() {
+  return {
+    "no-prior-sample": 0,
+    "cache-read-unavailable": 0,
+    "malformed-provider-usage": 0,
+    "request-correlation-unavailable": 0,
+    "request-evidence-incomplete": 0,
+    "sequence-hash-truncated": 0,
+    "model-provider-unavailable": 0,
+    "provider-reported-zero-stable-prefix": 0,
+    "provider-reported-low-read-stable-prefix": 0,
+    "no-local-explanation": 0
+  };
+}
+function newCacheUsageSummary() {
+  return {
+    usageRecords: 0,
+    cacheHits: 0,
+    missObservations: 0,
+    cacheMissCauses: emptyCacheMissCauses(),
+    unknownEvidenceReasons: emptyUnknownEvidenceReasons()
+  };
+}
+export const MAX_TRACKED_SESSIONS = 32;
+const attributionBySession = new BoundedLruCache(MAX_TRACKED_SESSIONS);
+function newAttributionState() {
+  return {
+    prefixBrokeSinceLastUsage: false,
+    prefixStableSinceLastUsage: false,
+    sequenceHashTruncatedSinceLastUsage: false,
+    requestEvidenceIncompleteSinceLastUsage: false,
+    injectedCharsSinceLastUsage: 0,
+    newTranscriptCharsSinceLastUsage: 0,
+    attributionCharsCapped: false,
+    injectedBytes: emptyInjectedBytes(),
+    injectedFindingsRepeated: 0,
+    findingIdentities: new Set,
+    findingIdentityCapRecorded: false,
+    turnEndAdvisoryBytes: 0,
+    toolResultBytes: 0,
+    toolResultsTruncated: 0,
+    summary: newCacheUsageSummary()
+  };
+}
+const MAX_FINDING_IDENTITIES = 2000;
+function emptyInjectedBytes() {
+  return {
+    sessionGuidance: 0,
+    turnFindings: 0,
+    testFindings: 0,
+    agentNudge: 0,
+    turnEndAdvisory: 0,
+    other: 0
+  };
+}
+function sourceKey(source) {
+  return {
+    "session-guidance": "sessionGuidance",
+    "turn-findings": "turnFindings",
+    "test-findings": "testFindings",
+    "agent-nudge": "agentNudge"
+  }[source];
+}
+function findingIdentities(text) {
+  const out = [];
+  for (const line of text.split(/\r?\n/)) {
+    const location = line.match(/(?:^|\s)([^\s:]+):(\d+)(?::\d+)?/);
+    if (!location)
+      continue;
+    const rule = line.match(/(?:rule|code)\s*[:=]\s*([\w./-]+)/i)?.[1] ?? line.match(/\(([\w./-]+)\)\s*$/)?.[1] ?? line.match(/:\d+(?::\d+)?\s+([\w./-]+)/)?.[1];
+    if (rule)
+      out.push(`${location[1]}:${location[2]}:${rule}`);
+  }
+  return out;
+}
+function attributionFor(key) {
+  const existing = attributionBySession.get(key);
+  const state = existing ?? newAttributionState();
+  attributionBySession.set(key, state);
+  return state;
+}
+function recordContextAttribution(key, existingMessages, injectedSize) {
+  const state = attributionFor(key);
+  const baseline = Math.min(state.lastObservedMessageCount ?? existingMessages.length, existingMessages.length);
+  const grown = measureTranscriptGrowth(existingMessages.slice(baseline));
+  state.injectedCharsSinceLastUsage = Math.min(MAX_ATTRIBUTION_CHARS, state.injectedCharsSinceLastUsage + injectedSize.chars);
+  state.newTranscriptCharsSinceLastUsage = Math.min(MAX_ATTRIBUTION_CHARS, state.newTranscriptCharsSinceLastUsage + grown.chars);
+  if (injectedSize.capped || grown.capped || state.injectedCharsSinceLastUsage >= MAX_ATTRIBUTION_CHARS || state.newTranscriptCharsSinceLastUsage >= MAX_ATTRIBUTION_CHARS) {
+    state.attributionCharsCapped = true;
+  }
+  state.lastObservedMessageCount = existingMessages.length;
+  state.lastContextAtMs = Date.now();
+}
+function resolveInterTurnGap(state, nowMs) {
+  if (state.lastUsageAtMs === undefined) {
+    return { gapMs: null, basis: "no-prior-turn" };
+  }
+  if (state.lastContextAtMs !== undefined) {
+    return {
+      gapMs: Math.max(0, state.lastContextAtMs - state.lastUsageAtMs),
+      basis: "request-time"
+    };
+  }
+  return {
+    gapMs: Math.max(0, nowMs - state.lastUsageAtMs),
+    basis: "message-end-fallback"
+  };
+}
+function estimateTokens(chars) {
+  return Math.ceil(chars / CHARS_PER_ESTIMATED_TOKEN);
+}
+function readableTokenCount(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+function readNumericEvidence(record, key) {
+  let raw;
+  try {
+    raw = record[key];
+  } catch {
+    return { status: "malformed" };
+  }
+  if (raw === undefined)
+    return { status: "absent" };
+  const value = readableTokenCount(raw);
+  return value === undefined ? { status: "malformed" } : { status: "available", value };
+}
+const MAX_LOGGED_IDENTITY_CHARS = 200;
+function identityEvidence(value) {
+  if (typeof value !== "string")
+    return { status: "unavailable" };
+  const normalized = value.trim();
+  if (!normalized)
+    return { status: "unavailable" };
+  const truncated = normalized.length > MAX_LOGGED_IDENTITY_CHARS;
+  return {
+    display: normalized.slice(0, MAX_LOGGED_IDENTITY_CHARS),
+    hash: createHash("sha256").update(normalized).digest("hex"),
+    status: truncated ? "truncated" : "complete"
+  };
+}
+function classifyCacheMiss(args) {
+  const cacheRead = readableTokenCount(args.cacheRead);
+  if (cacheRead === undefined)
+    return null;
+  const priorCacheRead = readableTokenCount(args.priorCacheRead);
+  if (priorCacheRead === undefined) {
+    return null;
+  }
+  let kind;
+  if (cacheRead === 0) {
+    kind = "zero-read";
+  } else if (priorCacheRead > 0 && cacheRead < priorCacheRead * LOW_CACHE_READ_RATIO) {
+    kind = "low-read";
+  } else {
+    return null;
+  }
+  if (!args.stableSessionIdentity) {
+    return {
+      kind,
+      cause: "unknown",
+      unknownReason: "request-correlation-unavailable"
+    };
+  }
+  if (args.prefixBroke)
+    return { kind, cause: "prefix-broke" };
+  if (args.modelProviderChanged) {
+    return { kind, cause: "model-provider-changed" };
+  }
+  if (args.gapBasis !== "request-time") {
+    return {
+      kind,
+      cause: "unknown",
+      unknownReason: "request-correlation-unavailable"
+    };
+  }
+  if (args.requestEvidenceIncomplete) {
+    return {
+      kind,
+      cause: "unknown",
+      unknownReason: "request-evidence-incomplete"
+    };
+  }
+  if (args.sequenceHashTruncated) {
+    return {
+      kind,
+      cause: "unknown",
+      unknownReason: "sequence-hash-truncated"
+    };
+  }
+  if (args.providerUsageMalformed) {
+    return {
+      kind,
+      cause: "unknown",
+      unknownReason: "malformed-provider-usage"
+    };
+  }
+  if (!args.modelProviderEvidenceAvailable) {
+    return {
+      kind,
+      cause: "unknown",
+      unknownReason: "model-provider-unavailable"
+    };
+  }
+  if (args.interTurnGapMs !== null && args.interTurnGapMs >= args.ttlMs) {
+    return { kind, cause: "ttl-expired" };
+  }
+  if (kind === "low-read" && !args.attributionCharsCapped && args.input > Math.max(PARTIAL_EVICTION_MIN_FRESH_TOKENS, args.estimatedNewTokens * PARTIAL_EVICTION_INPUT_FACTOR)) {
+    return { kind, cause: "partial-eviction" };
+  }
+  if (args.prefixStable) {
+    return {
+      kind,
+      cause: "unknown",
+      unknownReason: kind === "zero-read" ? "provider-reported-zero-stable-prefix" : "provider-reported-low-read-stable-prefix"
+    };
+  }
+  return {
+    kind,
+    cause: "unknown",
+    unknownReason: "no-local-explanation"
+  };
+}
+function recordCacheUsageSummary(args) {
+  const summary = args.state.summary;
+  summary.usageRecords += 1;
+  let unknownReasonRecorded = false;
+  if (args.unknownReason === "malformed-provider-usage") {
+    summary.unknownEvidenceReasons["malformed-provider-usage"] += 1;
+    unknownReasonRecorded = true;
+  }
+  if (args.cacheRead === undefined) {
+    if (!unknownReasonRecorded) {
+      summary.unknownEvidenceReasons["cache-read-unavailable"] += 1;
+    }
+    return;
+  }
+  if (args.priorCacheRead === undefined) {
+    if (args.cacheRead === 0) {
+      summary.missObservations += 1;
+      if (!unknownReasonRecorded) {
+        summary.unknownEvidenceReasons["no-prior-sample"] += 1;
+      }
+    } else {
+      summary.cacheHits += 1;
+    }
+    return;
+  }
+  if (!args.verdict) {
+    summary.cacheHits += 1;
+    return;
+  }
+  summary.missObservations += 1;
+  summary.cacheMissCauses[args.verdict.cause] += 1;
+  if (args.verdict.cause === "unknown" && args.unknownReason && !unknownReasonRecorded) {
+    summary.unknownEvidenceReasons[args.unknownReason] += 1;
+  }
+}
+function boundedHashScalar(value, state) {
+  if (value === null)
+    return "null";
+  if (value === undefined)
+    return "undefined";
+  if (typeof value === "string") {
+    const truncated = value.length > MAX_HASHED_CONTENT_CHARS;
+    if (truncated)
+      state.contentTruncated = true;
+    const suffix = truncated ? ":content-truncated" : "";
+    return `string:${value.length}:${value.slice(0, MAX_HASHED_CONTENT_CHARS)}${suffix}`;
+  }
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return `${typeof value}:${String(value)}`;
+  }
+  return typeof value;
+}
+function boundedHashArray(value, depth, seen, state) {
+  if (value.length > 12)
+    state.contentTruncated = true;
+  const items = value.slice(0, 12).map((item) => boundedHashValue(item, depth + 1, seen, state));
+  return `array:${value.length}:[${items.join(",")}]`;
+}
+function boundedHashObject(value, depth, seen, state) {
+  const keys = Object.keys(value).sort((left, right) => compareOrdinal(left, right));
+  if (keys.length > 24)
+    state.contentTruncated = true;
+  const fields = keys.slice(0, 24).map((key) => `${key}:${boundedHashValue(value[key], depth + 1, seen, state)}`);
+  return `object:${keys.length}:{${fields.join(",")}}`;
+}
+function boundedHashValue(value, depth = 0, seen = new Set, state) {
+  const hashState = state ?? { contentTruncated: false, incomplete: false };
+  if (value === null || typeof value !== "object") {
+    return boundedHashScalar(value, hashState);
+  }
+  if (depth >= 3) {
+    hashState.contentTruncated = true;
+    return "[depth-limit]";
+  }
+  if (seen.has(value)) {
+    hashState.incomplete = true;
+    return "[cycle]";
+  }
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      return boundedHashArray(value, depth, seen, hashState);
+    }
+    return boundedHashObject(value, depth, seen, hashState);
+  } catch {
+    hashState.incomplete = true;
+    return "[unreadable]";
+  } finally {
+    seen.delete(value);
+  }
+}
+function hashMessageSequence(messages) {
+  const hash = createHash("sha256");
+  const state = {
+    contentTruncated: false,
+    incomplete: false
+  };
+  let messageCount;
+  try {
+    messageCount = messages.length;
+    if (!Number.isSafeInteger(messageCount) || messageCount < 0) {
+      throw new Error("invalid message count");
+    }
+  } catch {
+    state.incomplete = true;
+    hash.update("message-count:[unreadable];");
+    return {
+      hash: hash.digest("hex"),
+      truncated: false,
+      contentTruncated: false,
+      incomplete: true
+    };
+  }
+  hash.update(`message-count:${messageCount};`);
+  const sampled = Math.min(messageCount, MAX_HASHED_MESSAGES);
+  for (let i = 0;i < sampled; i++) {
+    const seen = new Set;
+    let role;
+    let content;
+    try {
+      const message = messages[i];
+      role = message?.role;
+      content = message?.content;
+    } catch {
+      state.incomplete = true;
+      role = "[unreadable]";
+      content = "[unreadable]";
+    }
+    hash.update(`${i}|role:${boundedHashValue(role, 0, seen, state)}|content:${boundedHashValue(content, 0, seen, state)};`);
+  }
+  const truncated = messageCount > sampled;
+  if (truncated)
+    hash.update(`truncated-after:${sampled};`);
+  return {
+    hash: hash.digest("hex"),
+    truncated,
+    contentTruncated: state.contentTruncated,
+    incomplete: state.incomplete
+  };
+}
+const INJECTED_LIMITS = {
+  maxChars: MAX_INJECTED_CHARS,
+  maxBytes: MAX_INJECTED_BYTES
+};
+const TRANSCRIPT_LIMITS = {
+  maxChars: MAX_ATTRIBUTION_CHARS,
+  maxBytes: MAX_ATTRIBUTION_BYTES
+};
+function messageTextSize(content, limits) {
+  if (typeof content === "string") {
+    const chars = Math.min(content.length, limits.maxChars);
+    return {
+      chars,
+      bytes: Math.min(Buffer.byteLength(content.slice(0, chars), "utf8"), limits.maxBytes)
+    };
+  }
+  const bounded = boundedHashValue(content, 0, new Set, {
+    contentTruncated: false,
+    incomplete: false
+  });
+  return {
+    chars: Math.min(bounded.length, limits.maxChars),
+    bytes: Math.min(Buffer.byteLength(bounded.slice(0, limits.maxChars), "utf8"), limits.maxBytes)
+  };
+}
+function measureMessages(messages, limits) {
+  let chars = 0;
+  let bytes = 0;
+  const measuredCount = Math.min(messages.length, MAX_REPORTED_MESSAGES);
+  for (let i = 0;i < measuredCount; i++) {
+    const message = messages[i];
+    const size = messageTextSize(message?.content, limits);
+    chars = Math.min(limits.maxChars, chars + size.chars);
+    bytes = Math.min(limits.maxBytes, bytes + size.bytes);
+    if (chars === limits.maxChars || bytes === limits.maxBytes)
+      break;
+  }
+  return {
+    chars,
+    bytes,
+    capped: chars >= limits.maxChars || bytes >= limits.maxBytes
+  };
+}
+function measureInjectedMessages(messages) {
+  return measureMessages(messages, INJECTED_LIMITS);
+}
+function measureTranscriptGrowth(messages) {
+  return measureMessages(messages, TRANSCRIPT_LIMITS);
+}
+function sessionKey(sessionId) {
+  return sessionId?.trim() ? sessionId.trim() : NO_SESSION_KEY;
+}
+function attributionKey(sessionId, sessionRole) {
+  const key = sessionKey(sessionId);
+  if (key !== NO_SESSION_KEY)
+    return key;
+  return `${sessionRole ?? "unknown"}:${key}`;
+}
+export function observeCacheContext(args) {
+  try {
+    const existingMessages = args.existingMessages ?? [];
+    const resultMessages = args.resultMessages ?? existingMessages;
+    const injectionSlices = (args.injectionSlices ?? []).filter((slice) => slice.messages.length > 0);
+    const injectedMessages = injectionSlices.flatMap((slice) => slice.messages);
+    const placement = args.placement ?? "none";
+    const beforeSequence = hashMessageSequence(existingMessages);
+    const afterSequence = hashMessageSequence(resultMessages);
+    const sizes = measureInjectedMessages(injectedMessages);
+    const sourceBreakdown = injectionSlices.map((slice) => {
+      const sliceSize = measureInjectedMessages(slice.messages);
+      return {
+        source: slice.source,
+        messageCount: Math.min(slice.messages.length, MAX_REPORTED_MESSAGES),
+        chars: sliceSize.chars,
+        bytes: sliceSize.bytes,
+        estimatedTokens: estimateTokens(sliceSize.chars),
+        countsCapped: sliceSize.capped
+      };
+    });
+    const state = attributionFor(attributionKey(args.sessionId, args.sessionRole));
+    for (const slice of injectionSlices) {
+      const key = sourceKey(slice.source);
+      const bytes = measureInjectedMessages(slice.messages).bytes;
+      state.injectedBytes[key] += bytes;
+      for (const message of slice.messages) {
+        for (const identity of findingIdentities(typeof message.content === "string" ? message.content : "")) {
+          if (state.findingIdentities.has(identity)) {
+            state.injectedFindingsRepeated += 1;
+            continue;
+          }
+          if (state.findingIdentities.size >= MAX_FINDING_IDENTITIES) {
+            if (!state.findingIdentityCapRecorded) {
+              state.findingIdentityCapRecorded = true;
+              logLatency({
+                type: "phase",
+                filePath: "<dm-lens>",
+                phase: "injected_finding_identity_cap",
+                durationMs: 0,
+                metadata: { cap: MAX_FINDING_IDENTITIES }
+              });
+            }
+            continue;
+          }
+          state.findingIdentities.add(identity);
+        }
+      }
+    }
+    const messageCountCapped = existingMessages.length > MAX_REPORTED_MESSAGES || resultMessages.length > MAX_REPORTED_MESSAGES;
+    recordContextAttribution(attributionKey(args.sessionId, args.sessionRole), existingMessages, sizes);
+    state.sequenceHashTruncatedSinceLastUsage ||= beforeSequence.truncated || beforeSequence.contentTruncated || afterSequence.truncated || afterSequence.contentTruncated;
+    state.requestEvidenceIncompleteSinceLastUsage ||= beforeSequence.incomplete || afterSequence.incomplete;
+    logLatency({
+      type: "phase",
+      filePath: "<dm-lens>",
+      phase: "cache_context",
+      durationMs: 0,
+      metadata: {
+        version: 1,
+        observedStage: "dm-lens-context-handler",
+        observationId: `ctx-${(++contextObservationCounter).toString(36)}`,
+        sessionId: sessionKey(args.sessionId),
+        sessionRole: args.sessionRole,
+        ...args.sessionRole === "concurrent-secondary" ? { turnScope: SECONDARY_TURN_SCOPE } : { turnIndex: args.turnIndex, turnScope: PROCESS_TURN_SCOPE },
+        injectionEnabled: args.injectionEnabled,
+        injectionSources: sourceBreakdown.map((entry) => entry.source),
+        injectionSourceBreakdown: sourceBreakdown,
+        injectionOccurred: injectedMessages.length > 0,
+        injectedMessageCount: Math.min(injectedMessages.length, MAX_REPORTED_MESSAGES),
+        injectedMessageCountCapped: injectedMessages.length > MAX_REPORTED_MESSAGES,
+        injectedChars: sizes.chars,
+        injectedBytes: sizes.bytes,
+        injectedBytesBySource: Object.fromEntries(sourceBreakdown.map((entry) => [
+          sourceKey(entry.source),
+          entry.bytes
+        ])),
+        injectedEstimatedTokens: estimateTokens(sizes.chars),
+        injectedTokenBasis: "chars-per-token-4-estimate-not-provider-measured",
+        injectedCountsCapped: sizes.capped,
+        existingMessageCount: Math.min(existingMessages.length, MAX_REPORTED_MESSAGES),
+        resultMessageCount: Math.min(resultMessages.length, MAX_REPORTED_MESSAGES),
+        messageCountCapped,
+        placement,
+        beforeSequenceHash: beforeSequence.hash,
+        afterSequenceHash: afterSequence.hash,
+        sequenceHashTruncated: beforeSequence.truncated || afterSequence.truncated || beforeSequence.contentTruncated || afterSequence.contentTruncated,
+        sequenceMessageCountTruncated: beforeSequence.truncated || afterSequence.truncated,
+        sequenceContentHashTruncated: beforeSequence.contentTruncated || afterSequence.contentTruncated,
+        sequenceHashIncomplete: beforeSequence.incomplete || afterSequence.incomplete
+      }
+    });
+  } catch (err) {
+    try {
+      const state = attributionFor(attributionKey(args.sessionId, args.sessionRole));
+      state.lastContextAtMs = Date.now();
+      state.requestEvidenceIncompleteSinceLastUsage = true;
+    } catch {}
+    args.dbg?.(`cache-context: failed to log context observation: ${err}`);
+  }
+}
+export function logCacheUsage(message, dbg, context) {
+  try {
+    if (!message || typeof message !== "object")
+      return;
+    const msg = message;
+    if (msg.role !== "assistant")
+      return;
+    const usage = msg.usage;
+    if (!usage || typeof usage !== "object")
+      return;
+    const usageRecord = usage;
+    const stateKey = attributionKey(context?.sessionId, context?.sessionRole);
+    const state = attributionFor(stateKey);
+    const nowMs = Date.now();
+    const gap = resolveInterTurnGap(state, nowMs);
+    const interTurnGapMs = gap.gapMs;
+    const ttlMs = getProviderCacheTtlMs();
+    const inputEvidence = readNumericEvidence(usageRecord, "input");
+    const outputEvidence = readNumericEvidence(usageRecord, "output");
+    const cacheReadEvidence = readNumericEvidence(usageRecord, "cacheRead");
+    const cacheWriteEvidence = readNumericEvidence(usageRecord, "cacheWrite");
+    let costEvidence;
+    try {
+      const cost = usageRecord.cost;
+      costEvidence = cost === undefined ? { status: "absent" } : cost && typeof cost === "object" ? readNumericEvidence(cost, "total") : { status: "malformed" };
+    } catch {
+      costEvidence = { status: "malformed" };
+    }
+    const usageEvidenceFields = [
+      ["input", inputEvidence],
+      ["output", outputEvidence],
+      ["cacheRead", cacheReadEvidence],
+      ["cacheWrite", cacheWriteEvidence],
+      ["cost.total", costEvidence]
+    ];
+    const malformedProviderUsageFields = usageEvidenceFields.filter(([, evidence]) => evidence.status === "malformed").map(([field]) => field);
+    const providerUsageMalformed = malformedProviderUsageFields.length > 0;
+    const cacheRead = cacheReadEvidence.value;
+    const priorCacheReadValue = readableTokenCount(state.lastCacheRead);
+    const messageRecord = msg;
+    const safeMessageField = (key) => {
+      try {
+        return identityEvidence(messageRecord[key]);
+      } catch {
+        return { status: "unavailable" };
+      }
+    };
+    const currentProvider = safeMessageField("provider");
+    const responseModel = safeMessageField("responseModel");
+    const currentModel = responseModel.hash !== undefined ? responseModel : safeMessageField("model");
+    const modelProviderEvidenceAvailable = Boolean(currentProvider.hash && currentModel.hash && state.lastProviderIdentityHash && state.lastModelIdentityHash);
+    const modelProviderChanged = Boolean(modelProviderEvidenceAvailable && (currentProvider.hash !== state.lastProviderIdentityHash || currentModel.hash !== state.lastModelIdentityHash));
+    const estimatedNewTokens = estimateTokens(state.injectedCharsSinceLastUsage + state.newTranscriptCharsSinceLastUsage);
+    const verdict = classifyCacheMiss({
+      cacheRead,
+      input: inputEvidence.value ?? 0,
+      priorCacheRead: priorCacheReadValue,
+      interTurnGapMs,
+      gapBasis: gap.basis,
+      ttlMs,
+      prefixBroke: state.prefixBrokeSinceLastUsage,
+      prefixStable: state.prefixStableSinceLastUsage,
+      sequenceHashTruncated: state.sequenceHashTruncatedSinceLastUsage,
+      requestEvidenceIncomplete: state.requestEvidenceIncompleteSinceLastUsage,
+      stableSessionIdentity: sessionKey(context?.sessionId) !== NO_SESSION_KEY,
+      modelProviderChanged,
+      modelProviderEvidenceAvailable,
+      providerUsageMalformed,
+      estimatedNewTokens,
+      attributionCharsCapped: state.attributionCharsCapped
+    });
+    const unknownReason = providerUsageMalformed ? "malformed-provider-usage" : cacheRead === undefined ? "cache-read-unavailable" : priorCacheReadValue === undefined && cacheRead === 0 ? "no-prior-sample" : verdict?.unknownReason;
+    recordCacheUsageSummary({
+      state,
+      cacheRead,
+      priorCacheRead: priorCacheReadValue,
+      verdict,
+      unknownReason
+    });
+    const priorCacheRead = priorCacheReadValue ?? null;
+    const injectedCharsSinceLastTurn = state.injectedCharsSinceLastUsage;
+    const newTranscriptCharsSinceLastTurn = state.newTranscriptCharsSinceLastUsage;
+    const attributionCharsCapped = state.attributionCharsCapped;
+    const injectedBytes = {
+      ...state.injectedBytes,
+      turnEndAdvisory: state.turnEndAdvisoryBytes + state.injectedBytes.turnEndAdvisory
+    };
+    const injectedFindingsRepeated = state.injectedFindingsRepeated;
+    const toolResultBytes = state.toolResultBytes;
+    const toolResultsTruncated = state.toolResultsTruncated;
+    state.lastUsageAtMs = nowMs;
+    state.lastCacheRead = cacheRead;
+    state.lastProviderIdentityHash = currentProvider.hash;
+    state.lastModelIdentityHash = currentModel.hash;
+    state.prefixBrokeSinceLastUsage = false;
+    state.prefixStableSinceLastUsage = false;
+    state.sequenceHashTruncatedSinceLastUsage = false;
+    state.requestEvidenceIncompleteSinceLastUsage = false;
+    state.injectedCharsSinceLastUsage = 0;
+    state.newTranscriptCharsSinceLastUsage = 0;
+    state.attributionCharsCapped = false;
+    state.injectedBytes = emptyInjectedBytes();
+    state.injectedFindingsRepeated = 0;
+    state.turnEndAdvisoryBytes = 0;
+    state.toolResultBytes = 0;
+    state.toolResultsTruncated = 0;
+    state.lastContextAtMs = undefined;
+    logLatency({
+      type: "phase",
+      filePath: "<dm-lens>",
+      phase: "cache_usage",
+      durationMs: 0,
+      metadata: {
+        provider: currentProvider.display,
+        model: currentModel.display,
+        providerIdentityHash: currentProvider.hash,
+        modelIdentityHash: currentModel.hash,
+        providerIdentityStatus: currentProvider.status,
+        modelIdentityStatus: currentModel.status,
+        providerIdentityTruncated: currentProvider.status === "truncated",
+        modelIdentityTruncated: currentModel.status === "truncated",
+        cacheRead: cacheReadEvidence.value ?? null,
+        cacheWrite: cacheWriteEvidence.value ?? null,
+        input: inputEvidence.value ?? null,
+        output: outputEvidence.value ?? null,
+        cost: costEvidence.value ?? null,
+        providerUsageMalformedFields: malformedProviderUsageFields,
+        interTurnGapMs,
+        gapBasis: gap.basis,
+        cacheMissCause: verdict?.cause ?? null,
+        cacheMissKind: verdict?.kind ?? null,
+        cacheMissUnknownReason: unknownReason ?? null,
+        modelProviderChanged,
+        cacheTtlThresholdMs: ttlMs,
+        priorCacheRead,
+        injectedCharsSinceLastTurn,
+        newTranscriptCharsSinceLastTurn,
+        attributionCharsCapped,
+        injectedBytes,
+        injectedFindingsRepeated,
+        toolResultBytes,
+        toolResultsTruncated,
+        ...context ? {
+          sessionId: sessionKey(context.sessionId),
+          ...context.sessionRole === "concurrent-secondary" ? { turnScope: SECONDARY_TURN_SCOPE } : {
+            turnIndex: context.turnIndex,
+            turnScope: PROCESS_TURN_SCOPE
+          },
+          contextCorrelation: context.sessionId ? "session-only-no-request-id" : "no-stable-session-id"
+        } : {}
+      }
+    });
+  } catch (err) {
+    dbg?.(`cache-usage: failed to log message_end usage: ${err}`);
+  }
+}
+function hashFirstMessage(first) {
+  const serialized = JSON.stringify({
+    role: first.role,
+    content: first.content
+  });
+  return createHash("sha256").update(serialized).digest("hex");
+}
+const prefixHashBySession = new BoundedFifoMap(MAX_TRACKED_SESSIONS);
+const NO_SESSION_KEY = "<no-session>";
+function recordSessionHash(key, hash) {
+  prefixHashBySession.delete(key);
+  prefixHashBySession.set(key, hash);
+}
+export function observeCachePrefix(messages, turnIndex, sessionId, sessionRole, dbg) {
+  try {
+    if (!messages || messages.length === 0)
+      return "empty";
+    const first = messages[0];
+    if (!first || typeof first !== "object")
+      return "empty";
+    const key = attributionKey(sessionId, sessionRole);
+    const reportedSessionId = sessionKey(sessionId);
+    const currentHash = hashFirstMessage(first);
+    const previousHash = prefixHashBySession.get(key);
+    const state = attributionFor(key);
+    if (previousHash === undefined) {
+      recordSessionHash(key, currentHash);
+      state.prefixStableSinceLastUsage = true;
+      logLatency({
+        type: "phase",
+        filePath: "<dm-lens>",
+        phase: "cache_prefix_break",
+        durationMs: 0,
+        metadata: {
+          ...sessionRole === "concurrent-secondary" ? { turnScope: SECONDARY_TURN_SCOPE } : { turnIndex, turnScope: PROCESS_TURN_SCOPE },
+          previousHash: null,
+          currentHash,
+          baseline: true,
+          sessionId: reportedSessionId,
+          sessionRole
+        }
+      });
+      return "baseline";
+    }
+    if (currentHash !== previousHash) {
+      state.prefixBrokeSinceLastUsage = true;
+      state.prefixStableSinceLastUsage = false;
+      logLatency({
+        type: "phase",
+        filePath: "<dm-lens>",
+        phase: "cache_prefix_break",
+        durationMs: 0,
+        metadata: {
+          ...sessionRole === "concurrent-secondary" ? { turnScope: SECONDARY_TURN_SCOPE } : { turnIndex, turnScope: PROCESS_TURN_SCOPE },
+          previousHash,
+          currentHash,
+          sessionId: reportedSessionId,
+          sessionRole
+        }
+      });
+    }
+    if (currentHash === previousHash) {
+      state.prefixStableSinceLastUsage = true;
+    }
+    recordSessionHash(key, currentHash);
+    return currentHash === previousHash ? "unchanged" : "changed";
+  } catch (err) {
+    dbg?.(`cache-prefix: failed to observe messages[0]: ${err}`);
+    return "empty";
+  }
+}
+export function clearCachePrefixSession(sessionId, sessionRole) {
+  const key = attributionKey(sessionId, sessionRole);
+  prefixHashBySession.delete(key);
+  attributionBySession.delete(key);
+}
+export function recordTurnEndAdvisoryBytes(sessionId, bytes, sessionRole = "primary") {
+  const state = attributionFor(attributionKey(sessionId, sessionRole));
+  state.turnEndAdvisoryBytes = Math.min(MAX_INJECTED_BYTES, state.turnEndAdvisoryBytes + Math.max(0, bytes));
+}
+export function recordToolResultDelivery(args) {
+  const state = attributionFor(attributionKey(args.sessionId, args.sessionRole));
+  const bytes = Number.isFinite(args.bytes) ? Math.max(0, Math.floor(args.bytes)) : 0;
+  state.toolResultBytes = Math.min(MAX_ATTRIBUTION_BYTES, state.toolResultBytes + bytes);
+  if (args.truncated === true)
+    state.toolResultsTruncated += 1;
+}
+export function emitCacheUsageSummaryAtSessionEnd(sessionId, sessionRole) {
+  const key = attributionKey(sessionId, sessionRole);
+  const state = attributionBySession.get(key);
+  if (!state || state.summary.usageRecords === 0)
+    return;
+  logLatency({
+    type: "phase",
+    filePath: "<dm-lens>",
+    phase: "cache_usage_summary",
+    durationMs: 0,
+    metadata: {
+      version: 1,
+      sessionId: sessionKey(sessionId),
+      sessionRole,
+      usageRecords: state.summary.usageRecords,
+      cacheHits: state.summary.cacheHits,
+      missObservations: state.summary.missObservations,
+      cacheMissCauses: { ...state.summary.cacheMissCauses },
+      unknownEvidenceReasons: {
+        ...state.summary.unknownEvidenceReasons
+      }
+    }
+  });
+  attributionBySession.delete(key);
+}
+export function resetCachePrefixObservation() {
+  prefixHashBySession.clear();
+  attributionBySession.clear();
+}
+export function resetCacheFindingIdentitiesSession(sessionId, sessionRole) {
+  const state = attributionBySession.get(attributionKey(sessionId, sessionRole));
+  if (!state)
+    return;
+  state.findingIdentities.clear();
+  state.findingIdentityCapRecorded = false;
+}
+export function _attributionBySessionHasForTests(key) {
+  return attributionBySession.has(key);
+}
+export function _prefixHashBySessionHasForTests(key) {
+  return prefixHashBySession.has(key);
+}
+export function _touchAttributionForTests(key) {
+  attributionFor(key);
+}
+export function _recordSessionHashForTests(key, hash) {
+  recordSessionHash(key, hash);
+}
+export function _prefixHashBySessionGetForTests(key) {
+  return prefixHashBySession.get(key);
+}