@duckmind/dm-linux-x64 0.66.0 → 0.66.2

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

@@ -1,847 +0,0 @@
-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);
-}