@piagent/platform 1.5.5 → 1.6.0

package/packages/piagent-core/extensions/acceptance-test-binding-evidence.js

@@ -0,0 +1,60 @@
+import { assertionsProveErrorMapping } from "./acceptance-error-classes.js";
+import { executableRejectionAssertions } from "./acceptance-executable-evidence.js";
+
+export function callableAssertionMode(bodies, name) {
+  const callable = bodies.get(name);
+  return callable ? (callable.asynchronous ? "rejects" : "throws") : undefined;
+}
+
+/** Keep executable rejection assertions bound to the file that imported them. */
+export function boundRejectionTestEvidence(input) {
+  const codeByPath = new Map(input.testCodeEntries.map((entry) => [entry.path, entry.code]));
+  const cache = new Map();
+  const assertionsForBinding = (binding) => {
+    const key = `${binding.testPath}\u0000${binding.testName}`;
+    if (cache.has(key)) return cache.get(key);
+    const code = codeByPath.get(binding.testPath);
+    const assertions = typeof code === "string" ? executableRejectionAssertions(code, new Set([binding.testName]))
+      .filter((assertion) => assertion.targets.includes(binding.testName)) : [];
+    cache.set(key, assertions);
+    return assertions;
+  };
+  const requestedError = (assertion) => input.requestedErrors.length === 0
+    || input.requestedErrors.some((name) => assertion.errorClasses.includes(name));
+  const bindingGroups = input.bindings.map((binding) => {
+    const allAssertions = (binding.testBindings ?? []).flatMap(assertionsForBinding);
+    return { binding, allAssertions, assertions: allAssertions.filter(requestedError) };
+  });
+  const testCodes = input.testCodeEntries.length > 0
+    ? input.testCodeEntries.map((entry) => entry.code) : [input.fallbackTestCode];
+  const structuralGroups = input.structuralTargets.map((target) => {
+    const allAssertions = testCodes.flatMap((code) => executableRejectionAssertions(
+      code, new Set([`*.${target}`])
+    ).filter((assertion) => assertion.targets.includes(`*.${target}`)));
+    return { target, allAssertions, assertions: allAssertions.filter(requestedError) };
+  });
+  const groups = [...bindingGroups, ...structuralGroups];
+  const assertions = groups.flatMap((group) => group.assertions);
+  const assertionModesMatch = (items, targets, expectedMode) => {
+    const relevant = items.filter((item) => item.targets.some((target) => targets.includes(target)));
+    return Boolean(expectedMode) && relevant.length > 0 && relevant.every((item) => item.mode === expectedMode);
+  };
+  const mappingOk = input.requestedErrors.length <= 1 || Boolean(input.requestedErrorMapping
+    && groups.length > 0
+    && bindingGroups.every(({ binding, allAssertions }) => assertionsProveErrorMapping(
+      allAssertions, binding.testNames, input.requestedErrorMapping
+    ))
+    && structuralGroups.every(({ target, allAssertions }) => assertionsProveErrorMapping(
+      allAssertions, [`*.${target}`], input.requestedErrorMapping
+    )));
+  const targetOk = assertions.length > 0
+    && bindingGroups.every(({ binding, assertions: items }) => binding.testNames.length > 0 && items.length > 0)
+    && structuralGroups.every(({ assertions: items }) => items.length > 0);
+  const modeOk = bindingGroups.every(({ binding, assertions: items }) => assertionModesMatch(
+    items, binding.testNames, callableAssertionMode(input.bodyMaps.get(binding.sourcePath) ?? new Map(), binding.sourceName)
+  )) && structuralGroups.every(({ target, assertions: items }) => {
+    const matches = [...input.bodyMaps.values()].filter((bodies) => bodies.has(target));
+    return assertionModesMatch(items, [`*.${target}`], matches.length === 1 ? callableAssertionMode(matches[0], target) : undefined);
+  });
+  return { assertions, mappingOk, modeOk, targetOk };
+}

package/packages/piagent-core/extensions/context-efficiency-metrics.js

@@ -0,0 +1,302 @@
+function ratio(numerator, denominator) {
+  return denominator > 0 ? numerator / denominator : 0;
+}
+
+function normalizeRelative(value) {
+  return String(value ?? "").replaceAll("\\", "/").replace(/^\.\/+/, "").replace(/\/+/g, "/");
+}
+
+function taskBindings(events) {
+  return new Map(events
+    .filter((event) => event.event === "turn_task_bound" && typeof event.sessionId === "string" && typeof event.turnId === "string" && typeof event.taskRunId === "string")
+    .map((event) => [`${event.sessionId}\0${event.turnId}`, event.taskRunId]));
+}
+
+function evidenceCoverage(comparable, observed) {
+  return ratio(comparable, observed);
+}
+
+const MAX_CONTEXT_METRIC_AGGREGATE = 1_000_000_000;
+
+function boundedContextMetricInteger(value, { positive = false } = {}) {
+  return Number.isSafeInteger(value)
+    && value >= (positive ? 1 : 0)
+    && value <= MAX_CONTEXT_METRIC_AGGREGATE;
+}
+
+export function editRecoveryContextMetrics(events) {
+  const sessionStarts = new Map();
+  for (const [index, event] of events.entries()) {
+    if (event.event !== "session_start" || typeof event.sessionId !== "string" || !event.sessionId) continue;
+    const existing = sessionStarts.get(event.sessionId) ?? { firstIndex: index, valid: true };
+    existing.valid &&= event.editRecoveryContextTelemetryVersion === 1;
+    sessionStarts.set(event.sessionId, existing);
+  }
+  const receipts = new Map(), results = new Map();
+  let invalidReceipts = 0, invalidResults = 0;
+  let recoveryFailures = 0, comparableRecoveryFailures = 0, suppressedRecoveryFailures = 0;
+  const recoveryKey = (event) => typeof event.sessionId === "string" && event.sessionId
+    && typeof event.toolCallId === "string" && event.toolCallId && event.toolCallId.length <= 200
+    ? `${event.sessionId}\0${event.toolCallId}` : "";
+  const recoveryPath = (value) => {
+    const normalized = normalizeRelative(value);
+    if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../")
+      || normalized.startsWith("/") || /^[A-Za-z]:\//.test(normalized)) return "";
+    return normalized;
+  };
+  for (const [index, event] of events.entries()) {
+    if (event.event === "edit_recovery_context") {
+      const key = recoveryKey(event), targetPath = recoveryPath(event.targetPath);
+      const valid = key && targetPath && /^[a-f0-9]{64}$/.test(String(event.contentHash ?? ""))
+        && boundedContextMetricInteger(event.originalChars)
+        && boundedContextMetricInteger(event.injectedChars, { positive: true })
+        && event.injectedChars > event.originalChars
+        && boundedContextMetricInteger(event.injectedEstimatedTokens, { positive: true })
+        && event.sensitiveContentRedacted === false;
+      if (!valid) {
+        invalidReceipts += 1;
+        continue;
+      }
+      const values = receipts.get(key) ?? [];
+      values.push({ ...event, index, targetPath });
+      receipts.set(key, values);
+      continue;
+    }
+    if (event.event !== "tool_result") continue;
+    const recoveryFailure = ["edit-anchor-not-unique", "edit-anchor-stale"].includes(event.reasonCode);
+    if (!recoveryFailure) {
+      if (event.editRecoveryContext !== undefined) invalidResults += 1;
+      continue;
+    }
+    recoveryFailures += 1;
+    const key = recoveryKey(event), targetPath = recoveryPath(event.targetPath);
+    const valid = key && targetPath && String(event.toolName ?? "").toLowerCase() === "edit"
+      && event.isError === true && typeof event.editRecoveryContext === "boolean"
+      && (event.editRecoveryContext === true
+        ? boundedContextMetricInteger(event.editRecoveryInjectedChars, { positive: true })
+          && boundedContextMetricInteger(event.editRecoveryEstimatedTokens, { positive: true })
+        : event.editRecoveryInjectedChars === undefined && event.editRecoveryEstimatedTokens === undefined);
+    if (!valid) {
+      continue;
+    }
+    const capability = sessionStarts.get(event.sessionId);
+    if (capability?.valid === true && capability.firstIndex < index) {
+      comparableRecoveryFailures += 1;
+      if (event.editRecoveryContext === false) suppressedRecoveryFailures += 1;
+    }
+    if (event.editRecoveryContext === false) continue;
+    const values = results.get(key) ?? [];
+    values.push({ ...event, index, targetPath });
+    results.set(key, values);
+  }
+  const recoveryKeys = new Set([...receipts.keys(), ...results.keys()]);
+  let recoveryEvents = invalidReceipts + invalidResults;
+  let comparableEvents = 0;
+  let injectedChars = 0;
+  let injectedEstimatedTokens = 0;
+  for (const key of recoveryKeys) {
+    const receiptGroup = receipts.get(key) ?? [], resultGroup = results.get(key) ?? [];
+    recoveryEvents += Math.max(receiptGroup.length, resultGroup.length);
+    if (receiptGroup.length !== 1 || resultGroup.length !== 1) continue;
+    const receipt = receiptGroup[0], result = resultGroup[0];
+    const capability = sessionStarts.get(receipt.sessionId);
+    if (capability?.valid !== true || capability.firstIndex >= receipt.index
+      || receipt.index >= result.index || receipt.targetPath !== result.targetPath
+      || String(receipt.taskRunId ?? "") !== String(result.taskRunId ?? "")
+      || receipt.injectedChars !== result.editRecoveryInjectedChars
+      || receipt.injectedEstimatedTokens !== result.editRecoveryEstimatedTokens
+      || injectedChars + receipt.injectedChars > MAX_CONTEXT_METRIC_AGGREGATE
+      || injectedEstimatedTokens + receipt.injectedEstimatedTokens > MAX_CONTEXT_METRIC_AGGREGATE) continue;
+    comparableEvents += 1;
+    injectedChars += receipt.injectedChars;
+    injectedEstimatedTokens += receipt.injectedEstimatedTokens;
+  }
+  return {
+    editRecoveryContextEvents: recoveryEvents,
+    comparableEditRecoveryContextEvents: comparableEvents,
+    uncomparableEditRecoveryContextEvents: recoveryEvents - comparableEvents,
+    editRecoveryContextEvidenceCoverage: evidenceCoverage(comparableEvents, recoveryEvents),
+    editRecoveryContextCount: comparableEvents,
+    editRecoveryInjectedChars: injectedChars,
+    editRecoveryEstimatedTokens: injectedEstimatedTokens,
+    editRecoveryFailures: recoveryFailures,
+    comparableEditRecoveryFailures: comparableRecoveryFailures,
+    uncomparableEditRecoveryFailures: recoveryFailures - comparableRecoveryFailures,
+    editRecoveryFailureEvidenceCoverage: evidenceCoverage(comparableRecoveryFailures, recoveryFailures),
+    editRecoverySuppressedFailures: suppressedRecoveryFailures
+  };
+}
+
+export function contextMetricPartition(event, taskByTurn = new Map()) {
+  const sessionId = typeof event.sessionId === "string" ? event.sessionId : "";
+  const turnId = typeof event.turnId === "string" ? event.turnId : "";
+  const taskRunId = typeof event.taskRunId === "string" ? event.taskRunId : taskByTurn.get(`${sessionId}\0${turnId}`) ?? "";
+  if (!sessionId || !taskRunId) return "";
+  return [sessionId, taskRunId, event.model ?? "unknown", event.thinkingLevel ?? "unknown"].join("\0");
+}
+
+export function prefixEfficiencyMetrics(events) {
+  const taskByTurn = taskBindings(events), partitions = new Map();
+  const prefixPrompts = events.filter((event) => event.event === "agent_prompt").length;
+  for (const event of events) {
+    if (event.event !== "agent_prompt" || typeof event.prefixSurfaceHash !== "string") continue;
+    const partition = contextMetricPartition(event, taskByTurn);
+    if (!partition) continue;
+    const values = partitions.get(partition) ?? [];
+    values.push(event.prefixSurfaceHash);
+    partitions.set(partition, values);
+  }
+  let prompts = 0, transitions = 0, changes = 0;
+  const rates = [], turnsPerEpoch = [];
+  for (const hashes of partitions.values()) {
+    const partitionTransitions = Math.max(0, hashes.length - 1);
+    let partitionChanges = 0;
+    for (let index = 1; index < hashes.length; index += 1) if (hashes[index] !== hashes[index - 1]) partitionChanges += 1;
+    prompts += hashes.length; transitions += partitionTransitions; changes += partitionChanges;
+    if (partitionTransitions > 0) rates.push(ratio(partitionChanges, partitionTransitions));
+    turnsPerEpoch.push(ratio(hashes.length, 1 + partitionChanges));
+  }
+  return {
+    prefixPrompts,
+    comparablePrefixPrompts: prompts,
+    prefixEvidenceCoverage: evidenceCoverage(prompts, prefixPrompts),
+    prefixTransitions: transitions,
+    prefixChanges: changes,
+    prefixChangeRate: ratio(changes, transitions),
+    macroPrefixChangeRate: ratio(rates.reduce((sum, value) => sum + value, 0), rates.length),
+    averageTurnsPerPrefixEpoch: ratio(prompts, partitions.size + changes),
+    macroTurnsPerPrefixEpoch: ratio(turnsPerEpoch.reduce((sum, value) => sum + value, 0), turnsPerEpoch.length)
+  };
+}
+
+const READ_TOOLS = new Set(["read", "grep", "find", "ls"]);
+const MUTATION_TOOLS = new Set(["write", "edit", "apply_patch", "patch"]);
+
+function normalizedPaths(value) {
+  return [...new Set((Array.isArray(value) ? value : [])
+    .map(normalizeRelative)
+    .filter(Boolean))];
+}
+
+function successfulMutationPaths(event) {
+  if (event.event !== "tool_result") return null;
+  const explicit = [event.changedPaths, event.mutationPaths, event.targetPaths]
+    .find((value) => Array.isArray(value));
+  if (explicit) {
+    const paths = normalizedPaths(explicit);
+    if (paths.length > 0) return paths;
+  }
+  if (event.isError === true) return null;
+  if (!MUTATION_TOOLS.has(String(event.toolName ?? "").toLowerCase())) return null;
+  const target = normalizeRelative(event.targetPath);
+  return target ? [target] : [];
+}
+
+function pathAffected(readPath, mutationPaths) {
+  if (!readPath || mutationPaths.length === 0) return true;
+  return mutationPaths.some((mutationPath) => readPath === mutationPath
+    || readPath === "."
+    || mutationPath.startsWith(`${readPath}/`)
+    || readPath.startsWith(`${mutationPath}/`));
+}
+
+export function readEfficiencyMetrics(events) {
+  const taskByTurn = taskBindings(events), seenByPartition = new Map(), partitionTotals = new Map();
+  let readCalls = 0, comparableReadCalls = 0, duplicateReads = 0;
+  for (const event of events) {
+    const mutationPaths = successfulMutationPaths(event);
+    if (mutationPaths) {
+      const mutationPartition = contextMetricPartition(event, taskByTurn);
+      if (!mutationPartition) continue;
+      const [sessionId, taskRunId] = mutationPartition.split("\0");
+      const taskPrefix = `${sessionId}\0${taskRunId}\0`;
+      for (const [partition, seen] of seenByPartition) {
+        if (!partition.startsWith(taskPrefix)) continue;
+        for (const [key, readPath] of seen) {
+          if (pathAffected(readPath, mutationPaths)) seen.delete(key);
+        }
+      }
+      continue;
+    }
+    if (event.event !== "tool_call" || !READ_TOOLS.has(event.toolName)) continue;
+    readCalls += 1;
+    const partition = contextMetricPartition(event, taskByTurn);
+    const inputHash = typeof event.inputHash === "string" ? event.inputHash : "";
+    if (!partition || !inputHash) continue;
+    comparableReadCalls += 1;
+    const seen = seenByPartition.get(partition) ?? new Map();
+    const totals = partitionTotals.get(partition) ?? { calls: 0, duplicates: 0 };
+    totals.calls += 1;
+    // targetHash deliberately does not participate here. Two reads of one path
+    // with different ranges or queries are different calls; only the exact
+    // canonical input may be classified as a repeated read.
+    const key = `${event.toolName}\0${inputHash}`;
+    if (seen.has(key)) {
+      duplicateReads += 1;
+      totals.duplicates += 1;
+    } else {
+      seen.set(key, normalizeRelative(event.targetPath));
+    }
+    seenByPartition.set(partition, seen);
+    partitionTotals.set(partition, totals);
+  }
+  const macroRates = [...partitionTotals.values()].map((item) => ratio(item.duplicates, item.calls));
+  return {
+    readCalls,
+    comparableReadCalls,
+    uncomparableReadCalls: Math.max(0, readCalls - comparableReadCalls),
+    readEvidenceCoverage: evidenceCoverage(comparableReadCalls, readCalls),
+    duplicateReads,
+    duplicateReadRate: ratio(duplicateReads, comparableReadCalls),
+    macroDuplicateReadRate: ratio(macroRates.reduce((sum, value) => sum + value, 0), macroRates.length)
+  };
+}
+
+function injectionEquivalenceKey(item) {
+  if (!item || typeof item !== "object" || typeof item.path !== "string" || typeof item.payloadHash !== "string"
+    || typeof item.fileContentHash !== "string" || typeof item.representation !== "string") return "";
+  return JSON.stringify([normalizeRelative(item.path), item.fileContentHash, item.payloadHash, item.representation,
+    Array.isArray(item.ranges) ? item.ranges : [], Number.isInteger(item.generation) ? item.generation : 0]);
+}
+
+export function injectionEfficiencyMetrics(events) {
+  const taskByTurn = taskBindings(events), seen = new Map(), partitionTotals = new Map();
+  let receipts = 0, comparableReceipts = 0, occurrences = 0, comparable = 0, duplicates = 0, tokens = 0, comparableTokens = 0, duplicateTokens = 0;
+  for (const event of events) {
+    if (event.event !== "context_pack_injected") continue;
+    receipts += 1;
+    const partition = contextMetricPartition(event, taskByTurn);
+    if (!Array.isArray(event.selectedItems)) continue;
+    if (partition) comparableReceipts += 1;
+    const partitionSeen = seen.get(partition) ?? new Set(), totals = partitionTotals.get(partition) ?? { occurrences: 0, duplicates: 0 };
+    for (const item of event.selectedItems) {
+      const estimatedTokens = Math.max(0, Number(item?.estimatedTokens ?? 0));
+      occurrences += 1; tokens += estimatedTokens;
+      const key = injectionEquivalenceKey(item);
+      if (!partition || !key || event.rehydration === true || event.source === "compaction-rehydrate") continue;
+      comparable += 1; comparableTokens += estimatedTokens; totals.occurrences += 1;
+      if (partitionSeen.has(key)) {
+        duplicates += 1; duplicateTokens += estimatedTokens; totals.duplicates += 1;
+      } else partitionSeen.add(key);
+    }
+    seen.set(partition, partitionSeen); partitionTotals.set(partition, totals);
+  }
+  const macroRates = [...partitionTotals.values()].filter((item) => item.occurrences > 0).map((item) => ratio(item.duplicates, item.occurrences));
+  return {
+    injectionReceipts: receipts,
+    comparableInjectionReceipts: comparableReceipts,
+    injectionReceiptCoverage: evidenceCoverage(comparableReceipts, receipts),
+    injectedPathOccurrences: occurrences,
+    comparableInjectionItems: comparable,
+    injectionItemCoverage: evidenceCoverage(comparable, occurrences),
+    duplicateInjections: duplicates,
+    duplicateInjectionRate: ratio(duplicates, comparable),
+    duplicateInjectionOccurrenceRate: ratio(duplicates, occurrences),
+    macroDuplicateInjectionRate: ratio(macroRates.reduce((sum, value) => sum + value, 0), macroRates.length),
+    injectedPathTokens: tokens,
+    comparableInjectionTokens: comparableTokens,
+    duplicateInjectionTokens: duplicateTokens,
+    duplicateInjectionTokenRate: ratio(duplicateTokens, comparableTokens),
+    duplicateInjectionObservedTokenRate: ratio(duplicateTokens, tokens)
+  };
+}

package/packages/piagent-core/extensions/context-efficiency-report.js

@@ -0,0 +1,167 @@
+import fs from "node:fs";
+
+import {
+  editRecoveryContextMetrics,
+  injectionEfficiencyMetrics,
+  prefixEfficiencyMetrics,
+  readEfficiencyMetrics
+} from "./context-efficiency-metrics.js";
+import { ensurePrivateStateDirectory, resolveLocalStatePath } from "./local-state-path.js";
+
+function ratio(numerator, denominator) {
+  return denominator > 0 ? numerator / denominator : 0;
+}
+function evidenceStatus(observed, comparable) {
+  if (observed === 0) return "not-observed";
+  if (comparable === 0) return "unavailable";
+  return comparable === observed ? "complete" : "partial";
+}
+export function writeContextEfficiencyReport(cwd, events, dependencies) {
+  const prompts = events.filter((event) => event.event === "agent_prompt"), toolCalls = events.filter((event) => event.event === "tool_call"), toolResults = events.filter((event) => event.event === "tool_result"), packs = events.filter((event) => event.event === "context_pack");
+  const offeredPacks = events.filter((event) => event.event === "context_pack_offered"), injectedPacks = events.filter((event) => event.event === "context_pack_injected");
+  const compactions = events.filter((event) => event.event === "session_compact");
+  const readMetrics = readEfficiencyMetrics(events);
+  const comparableToolResults = toolResults.filter((event) => Number.isFinite(event.outputChars)
+    && event.outputChars >= 0 && typeof event.repeated === "boolean");
+  const toolResultEvidenceCoverage = ratio(comparableToolResults.length, toolResults.length);
+  const outputChars = comparableToolResults.reduce((sum, event) => sum + event.outputChars, 0);
+  const duplicateOutputChars = comparableToolResults.reduce((sum, event) => sum + (event.repeated ? event.outputChars : 0), 0);
+  const activeToolPrompts = prompts.filter((event) => Number.isFinite(Number(event.activeTools)));
+  const schemaPrompts = prompts.filter((event) => Number.isFinite(Number(event.systemPromptTokens)) && Number.isFinite(Number(event.toolSchemaTokens)));
+  const averageActiveTools = activeToolPrompts.length > 0
+    ? activeToolPrompts.reduce((sum, event) => sum + Number(event.activeTools), 0) / activeToolPrompts.length
+    : 0;
+  const averageSystemPromptTokens = schemaPrompts.length > 0
+    ? schemaPrompts.reduce((sum, event) => sum + Number(event.systemPromptTokens), 0) / schemaPrompts.length
+    : 0;
+  const averageToolSchemaTokens = schemaPrompts.length > 0
+    ? schemaPrompts.reduce((sum, event) => sum + Number(event.toolSchemaTokens), 0) / schemaPrompts.length
+    : 0;
+  const comparableConfidencePacks = packs.filter((event) => ["none", "low", "medium", "high"].includes(event.confidence));
+  const contextPackEvidenceCoverage = ratio(comparableConfidencePacks.length, packs.length);
+  const lowConfidencePacks = comparableConfidencePacks.filter((event) => ["none", "low"].includes(event.confidence)).length;
+  const feedback = dependencies.retrievalFeedback();
+  const prefixMetrics = prefixEfficiencyMetrics(events), injectionMetrics = injectionEfficiencyMetrics(events);
+  const editRecoveryMetrics = editRecoveryContextMetrics(events);
+  const duplicateOutputRate = ratio(duplicateOutputChars, outputChars);
+  const schemaToSystemRatio = ratio(averageToolSchemaTokens, averageSystemPromptTokens);
+  const schemaPrefixShare = ratio(averageToolSchemaTokens, averageSystemPromptTokens + averageToolSchemaTokens);
+  const lowConfidenceRate = ratio(lowConfidencePacks, comparableConfidencePacks.length);
+  const activeToolPenalty = Math.max(0, Math.min(1, (averageActiveTools - 12) / 24));
+  const wasteScore = Math.round(100 * (
+    readMetrics.duplicateReadRate * 0.3
+    + duplicateOutputRate * 0.25
+    + Math.min(1, schemaPrefixShare * 3) * 0.2
+    + lowConfidenceRate * 0.15
+    + activeToolPenalty * 0.1
+  ));
+  const scoreEvidenceCoverage = (
+    readMetrics.readEvidenceCoverage * 0.3
+    + toolResultEvidenceCoverage * 0.25
+    + ratio(schemaPrompts.length, prompts.length) * 0.2
+    + contextPackEvidenceCoverage * 0.15
+    + ratio(activeToolPrompts.length, prompts.length) * 0.1
+  );
+  const scoreEvidenceComplete = scoreEvidenceCoverage >= 1 - 1e-12;
+  const scoreEvidenceStatus = scoreEvidenceComplete ? "complete" : scoreEvidenceCoverage === 0 ? "unavailable" : "partial";
+  const recommendations = [];
+  if (readMetrics.comparableReadCalls > 0 && readMetrics.duplicateReadRate > 0.2) recommendations.push("Repeated reads are high within comparable task/session partitions; reuse the current working set before searching again.");
+  if (duplicateOutputRate > 0.15) recommendations.push("Repeated tool output is high; prefer delta results and narrower verification.");
+  if (schemaPrefixShare > 0.15 || averageActiveTools > 20) recommendations.push("Tool surface is large; activate only the workflow groups needed for the next turn.");
+  if (lowConfidenceRate > 0.4) recommendations.push("Retrieval confidence is low; rebuild the index or run one bounded finder pass.");
+  if (feedback.selected >= 4 && feedback.utilizationRate < 0.45) recommendations.push("Few injected paths receive successful mutation evidence; reduce pack breadth or improve task-specific ranking signals.");
+  if (feedback.selected >= 4 && feedback.fallbackRereadRate > 0.35) recommendations.push("Injected paths are frequently read again; improve snapshot completeness instead of treating fallback reads as positive retrieval feedback.");
+  if (readMetrics.readCalls > 0 && readMetrics.readEvidenceCoverage < 1) recommendations.push("Read telemetry coverage is incomplete; duplicate-read rates exclude calls without task/session/input identity.");
+  if (toolResults.length > 0 && toolResultEvidenceCoverage < 1) recommendations.push("Tool-result telemetry coverage is incomplete; duplicate-output rates exclude results without finite output size and an explicit repeated classification.");
+  if (packs.length > 0 && contextPackEvidenceCoverage < 1) recommendations.push("Context-pack telemetry coverage is incomplete; low-confidence rates exclude packs without a recognized confidence value.");
+  if (injectionMetrics.injectionReceipts > 0 && injectionMetrics.injectionReceiptCoverage < 1) recommendations.push("Injection receipt coverage is incomplete; zero duplicate injection waste is not established for unattributed receipts.");
+  if (injectionMetrics.injectedPathOccurrences > 0 && injectionMetrics.injectionItemCoverage < 1) recommendations.push("Injection item coverage is incomplete; duplicate injection rates exclude selected paths without canonical content and payload receipts.");
+  if (editRecoveryMetrics.editRecoveryContextEvents > 0 && editRecoveryMetrics.editRecoveryContextEvidenceCoverage < 1) recommendations.push("Edit-recovery telemetry coverage is incomplete; recovery context totals exclude malformed or unbounded recovery receipts.");
+  if (editRecoveryMetrics.editRecoveryFailures > 0 && editRecoveryMetrics.editRecoveryFailureEvidenceCoverage < 1) recommendations.push("Edit-recovery failure classification coverage is incomplete; a missing recovery context cannot be interpreted as a policy decision.");
+  if (!scoreEvidenceComplete) recommendations.push("Context-waste score is unavailable because one or more weighted telemetry lanes have incomplete evidence; do not interpret missing observations as zero waste.");
+  if (recommendations.length === 0) recommendations.push("No dominant context waste signal was detected in the sampled events.");
+  const report = {
+    schemaVersion: 3,
+    source: "piagent",
+    generatedAt: dependencies.nowIso(),
+    sample: {
+      events: events.length,
+      prompts: prompts.length,
+      toolCalls: toolCalls.length,
+      toolResults: toolResults.length,
+      contextPacks: packs.length,
+      contextPacksOffered: offeredPacks.length, contextPacksInjected: injectedPacks.length,
+      compactions: compactions.length,
+      editRecoveryContexts: editRecoveryMetrics.editRecoveryContextEvents,
+      editRecoveryFailures: editRecoveryMetrics.editRecoveryFailures
+    },
+    metrics: {
+      averageActiveTools: Number(averageActiveTools.toFixed(2)),
+      averageSystemPromptTokens: Math.round(averageSystemPromptTokens),
+      averageToolSchemaTokens: Math.round(averageToolSchemaTokens),
+      toolSchemaShare: Number(schemaPrefixShare.toFixed(4)),
+      toolSchemaPrefixShare: Number(schemaPrefixShare.toFixed(4)),
+      toolSchemaToSystemRatio: Number(schemaToSystemRatio.toFixed(4)),
+      ...Object.fromEntries(Object.entries(readMetrics).map(([key, value]) => [key, Number(value.toFixed(4))])),
+      outputChars,
+      duplicateOutputChars,
+      duplicateOutputRate: Number(duplicateOutputRate.toFixed(4)),
+      comparableToolResults: comparableToolResults.length,
+      uncomparableToolResults: Math.max(0, toolResults.length - comparableToolResults.length),
+      toolResultEvidenceCoverage: Number(toolResultEvidenceCoverage.toFixed(4)),
+      lowConfidencePacks,
+      lowConfidenceRate: Number(lowConfidenceRate.toFixed(4)),
+      comparableConfidencePacks: comparableConfidencePacks.length,
+      uncomparableConfidencePacks: Math.max(0, packs.length - comparableConfidencePacks.length),
+      contextPackEvidenceCoverage: Number(contextPackEvidenceCoverage.toFixed(4)),
+      contextSelections: feedback.selected,
+      contextSelectionsUsed: feedback.used,
+      contextSelectionsMutationCredited: feedback.used,
+      contextSelectionsUnused: feedback.unused,
+      contextUtilizationRate: Number(feedback.utilizationRate.toFixed(4)),
+      contextFallbackRereads: feedback.fallbackRereads,
+      contextFallbackRereadRate: Number(feedback.fallbackRereadRate.toFixed(4)),
+      ...Object.fromEntries(Object.entries({ ...prefixMetrics, ...injectionMetrics }).map(([key, value]) => [key, Number(value.toFixed(4))])),
+      ...Object.fromEntries(Object.entries(editRecoveryMetrics).map(([key, value]) => [key, Number(value.toFixed(4))])),
+      contextWasteScore: scoreEvidenceComplete ? wasteScore : null,
+      contextWasteScoreEstimate: wasteScore,
+      contextWasteScoreEvidenceCoverage: Number(scoreEvidenceCoverage.toFixed(4))
+    },
+    coverage: {
+      reads: { status: evidenceStatus(readMetrics.readCalls, readMetrics.comparableReadCalls), observed: readMetrics.readCalls, comparable: readMetrics.comparableReadCalls, rate: Number(readMetrics.readEvidenceCoverage.toFixed(4)) },
+      toolResults: { status: evidenceStatus(toolResults.length, comparableToolResults.length), observed: toolResults.length, comparable: comparableToolResults.length, rate: Number(toolResultEvidenceCoverage.toFixed(4)) },
+      contextPacks: { status: evidenceStatus(packs.length, comparableConfidencePacks.length), observed: packs.length, comparable: comparableConfidencePacks.length, rate: Number(contextPackEvidenceCoverage.toFixed(4)) },
+      prefixPrompts: { status: evidenceStatus(prefixMetrics.prefixPrompts, prefixMetrics.comparablePrefixPrompts), observed: prefixMetrics.prefixPrompts, comparable: prefixMetrics.comparablePrefixPrompts, rate: Number(prefixMetrics.prefixEvidenceCoverage.toFixed(4)) },
+      injectionReceipts: { status: evidenceStatus(injectionMetrics.injectionReceipts, injectionMetrics.comparableInjectionReceipts), observed: injectionMetrics.injectionReceipts, comparable: injectionMetrics.comparableInjectionReceipts, rate: Number(injectionMetrics.injectionReceiptCoverage.toFixed(4)) },
+      injectionItems: { status: evidenceStatus(injectionMetrics.injectedPathOccurrences, injectionMetrics.comparableInjectionItems), observed: injectionMetrics.injectedPathOccurrences, comparable: injectionMetrics.comparableInjectionItems, rate: Number(injectionMetrics.injectionItemCoverage.toFixed(4)) },
+      editRecoveryContexts: { status: evidenceStatus(editRecoveryMetrics.editRecoveryContextEvents, editRecoveryMetrics.comparableEditRecoveryContextEvents), observed: editRecoveryMetrics.editRecoveryContextEvents, comparable: editRecoveryMetrics.comparableEditRecoveryContextEvents, rate: Number(editRecoveryMetrics.editRecoveryContextEvidenceCoverage.toFixed(4)) },
+      editRecoveryFailures: { status: evidenceStatus(editRecoveryMetrics.editRecoveryFailures, editRecoveryMetrics.comparableEditRecoveryFailures), observed: editRecoveryMetrics.editRecoveryFailures, comparable: editRecoveryMetrics.comparableEditRecoveryFailures, rate: Number(editRecoveryMetrics.editRecoveryFailureEvidenceCoverage.toFixed(4)) },
+      retrievalSelections: { status: evidenceStatus(feedback.observedSelected, feedback.selected), observed: feedback.observedSelected, comparable: feedback.selected, rate: Number(ratio(feedback.selected, feedback.observedSelected).toFixed(4)) },
+      wasteScore: { status: scoreEvidenceStatus, rate: Number(scoreEvidenceCoverage.toFixed(4)) }
+    },
+    methodology: {
+      scoreRange: "0-100; lower is better; contextWasteScore is null unless all weighted telemetry lanes are complete, while contextWasteScoreEstimate remains explicitly diagnostic",
+      weights: {
+        duplicateReads: 0.3,
+        duplicateOutput: 0.25,
+        toolSchemaPrefixShare: 0.2,
+        lowConfidenceRetrieval: 0.15,
+        activeToolExcess: 0.1
+      },
+      retrievalFeedback: "Positive-only reranking consumes host-confirmed context_pack_injected events and credits a path only after a successful direct mutation result (or explicit changed-path evidence) in the same session/task/model/thinking partition. Fallback reads are reported separately and never increase ranking.",
+      readMetrics: "Duplicate reads require the same tool and exact inputHash within one session, task, model, and thinking-level partition. targetHash is not used as a substitute. Calls lacking comparable identity remain visible in coverage and are excluded from the rate.",
+      outputMetrics: "Duplicate-output rates use only tool results with a finite non-negative outputChars value and an explicit boolean repeated classification. Coverage exposes every excluded result instead of treating missing evidence as zero output or non-duplicate output.",
+      confidenceMetrics: "Low-confidence rates use only context-pack events with a recognized none/low/medium/high confidence value. Coverage exposes missing or unknown confidence instead of counting it as a non-low result.",
+      prefixMetrics: "Canonical provider tool schemas are compared only within session, task, model, and thinking-level partitions. First-turn task attribution uses turn_task_bound. Coverage distinguishes missing prefix evidence from a stable prefix.", injectionMetrics: "Duplicates require the same path, file hash, payload hash, representation, ranges, and generation within one task/session partition. Unconfirmed and post-compaction rehydration events are excluded from duplicate attribution; coverage exposes excluded receipts/items.",
+      editRecoveryMetrics: "Recovery count, characters, and estimated tokens require one versioned session capability marker plus an exact standalone edit_recovery_context receipt/tool_result pair. Original tool-result outputChars stays separate, so the failed tool output and the returned current-file snapshot are never added together.",
+      schemaMetrics: "toolSchemaPrefixShare is tool schema tokens divided by system-plus-tool-schema tokens. toolSchemaToSystemRatio preserves the former tool/system diagnostic explicitly; toolSchemaShare is a compatibility alias for the corrected prefix share.",
+      note: "This is an operational signal, not a quality verdict. Compare it with task acceptance and verification results."
+    },
+    recommendations
+  };
+  const paths = dependencies.contextEnginePaths();
+  ensurePrivateStateDirectory(cwd, paths.root, "Context report directory");
+  const reportPath = resolveLocalStatePath(cwd, paths.report, { label: "Context efficiency report" });
+  fs.writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`, { mode: 0o600 });
+  return report;
+}