@citeark/agent 0.3.20

package/src/verification/claim-evaluator.mjs

@@ -0,0 +1,242 @@
+import {
+  verificationPolicyTargets,
+} from "../contracts/execution-contract.mjs";
+import { sha256Value, writeJson } from "../util.mjs";
+import { SCIENTIFIC_ASSESSMENT_RUBRIC_VERSION } from "./ai-assessor.mjs";
+
+export async function evaluateClaim({
+  contract,
+  policy,
+  metrics,
+  outputs,
+  integrity,
+  result,
+  claim,
+  scientificAssessor,
+  runnerAudit,
+  evidenceContext,
+  assessmentPath,
+  assessedAt,
+}) {
+  const executionStatus = result?.execution?.status ?? integrity.states?.experimentStatus ?? "unknown";
+  const reconstructionFidelity = contract.reconstructionFidelity ?? "faithful";
+  const strictlyComparable = new Set(["exact", "faithful"]).has(reconstructionFidelity);
+  const parsedMeasurements = Array.isArray(metrics.measurements) ? metrics.measurements : [];
+  const deterministicAssessments = verificationPolicyTargets(policy).map((target) => {
+    const parsed = parsedMeasurements.find((item) => item.measurementId === target.measurementId);
+    const assessment = evaluateMeasurement({
+      target,
+      metrics: parsed,
+      integrity,
+      result,
+      executionStatus,
+    });
+    if (strictlyComparable || assessment.verificationStatus === "inconclusive") return assessment;
+    return {
+      ...assessment,
+      verdict: "inconclusive",
+      verificationStatus: "inconclusive",
+      reason: `The observed value is recorded as directional evidence, but ${reconstructionFidelity} reconstruction fidelity cannot establish a strict Match against the paper`,
+      comparison: {
+        ...assessment.comparison,
+        directionalStatus: assessment.verificationStatus,
+      },
+    };
+  });
+  let measurementAssessments = deterministicAssessments;
+  let verificationStatus = measurementAssessments.length > 0
+    && measurementAssessments.every((item) => item.verificationStatus === "reproduced")
+    ? "reproduced"
+    : measurementAssessments.some((item) => item.verificationStatus === "not_reproduced")
+      ? "not_reproduced"
+      : "inconclusive";
+  let verdict = verificationStatus === "reproduced"
+    ? "supports"
+    : verificationStatus === "not_reproduced"
+      ? "contradicts"
+      : "inconclusive";
+  let reason = verificationStatus === "reproduced"
+    ? "Every protocol-bound measurement is within its pre-declared tolerance"
+    : verificationStatus === "not_reproduced"
+      ? "At least one protocol-bound measurement is outside its pre-declared tolerance"
+      : measurementAssessments
+          .filter((item) => item.verificationStatus === "inconclusive")
+          .map((item) => item.reason)
+          .filter((value, index, values) => values.indexOf(value) === index)
+          .join("; ") || "At least one protocol-bound measurement lacks sufficient trustworthy evidence";
+  let assessor = { kind: "service", name: "citeark-verification-engine", version: "0.1.0" };
+  let confidence = null;
+  let protocolComparability = strictlyComparable ? "exact" : "material_difference";
+  let assessmentLimitations = [];
+  let assessorFailure = null;
+  let assessmentUsage = null;
+  let executionEvidence = null;
+  let evidenceReads = [];
+
+  const completeTrustworthyEvidence = integrity.status === "passed"
+    && measurementAssessments.length > 0
+    && (contract.executionPlan
+      ? measurementAssessments.some((item) => item.comparison?.observedValue != null)
+      : measurementAssessments.every((item) => item.comparison?.observedValue !== null))
+    && new Set(contract.executionPlan ? ["succeeded", "completed", "partial"] : ["succeeded", "completed"]).has(executionStatus);
+  if (typeof scientificAssessor === "function" && completeTrustworthyEvidence) {
+    const modelResult = await scientificAssessor({
+      claim,
+      contract,
+      comparisons: contract.executionPlan
+        ? measurementAssessments.filter((item) => item.comparison?.observedValue != null)
+        : measurementAssessments,
+      result,
+      integrity,
+      runnerAudit,
+      evidenceContext,
+    });
+    if (modelResult?.status === "completed") {
+      const byMeasurementId = new Map(modelResult.assessment.measurementAssessments.map((item) => [item.measurementId, item]));
+      measurementAssessments = measurementAssessments.map((item) => ({
+        ...(byMeasurementId.get(item.measurementId) ?? item),
+        comparison: item.comparison,
+      }));
+      verificationStatus = modelResult.assessment.verificationStatus;
+      verdict = modelResult.assessment.conclusion;
+      reason = modelResult.assessment.reason;
+      confidence = modelResult.assessment.confidence;
+      protocolComparability = modelResult.assessment.protocolComparability;
+      assessmentLimitations = modelResult.assessment.limitations;
+      assessor = modelResult.assessor;
+      assessmentUsage = modelResult.usage;
+      evidenceReads = modelResult.evidenceReads ?? [];
+      executionEvidence = modelResult.assessment.executionEvidence ?? null;
+    } else {
+      verificationStatus = "inconclusive";
+      verdict = "inconclusive";
+      reason = "The independent AI scientific assessor is unavailable. Numeric evidence is preserved, and CiteArk does not fall back to a fixed-threshold verdict.";
+      measurementAssessments = measurementAssessments.map((item) => ({
+        ...item,
+        verdict: "inconclusive",
+        verificationStatus: "inconclusive",
+        reason,
+      }));
+      assessorFailure = modelResult?.error ?? { message: "unknown assessor failure" };
+      assessor = { kind: "model", name: "unavailable", rubricVersion: SCIENTIFIC_ASSESSMENT_RUBRIC_VERSION };
+      assessmentLimitations = [reason];
+      protocolComparability = "unknown";
+    }
+  }
+  const advisoryProvenance = integrity.checks?.some((item) =>
+    item.evidentiaryRole === "advisory-only; assessor must trace actual computation");
+  if (((contract.executionPlan || advisoryProvenance) && typeof scientificAssessor !== "function")
+    || (contract.executionPlan && measurementAssessments.some((item) => item.comparison?.observedValue == null))) {
+    verificationStatus = "inconclusive";
+    verdict = "inconclusive";
+    reason = typeof scientificAssessor !== "function"
+      ? "Scientific execution provenance requires independent assessment; numeric proximity and advisory command matches are insufficient."
+      : [reason, "Some original claim measurements remain without evidence; available measurements are assessed individually."].filter(Boolean).join(" ");
+    if (typeof scientificAssessor !== "function") {
+      measurementAssessments = measurementAssessments.map((item) => ({ ...item,
+        verdict: "inconclusive", verificationStatus: "inconclusive", reason }));
+    }
+  }
+  const body = {
+    schemaVersion: "1.0",
+    kind: "citeark.claim-assessment",
+    contractDigest: contract.contractDigest,
+    ...(contract.executionPlan ? { executionPlanDigest: contract.executionPlan.digest } : {}),
+    policyDigest: policy.policyDigest,
+    claimVersionId: contract.research.claimVersionId,
+    experimentVersionId: contract.research.experimentVersionId,
+    reproductionLevel: contract.reproductionLevel,
+    reconstructionFidelity,
+    verdict,
+    verificationStatus,
+    reason,
+    ...(confidence ? { confidence } : {}),
+    protocolComparability,
+    ...(executionEvidence ? { executionEvidence } : {}),
+    limitations: assessmentLimitations,
+    evidenceReads,
+    ...(assessorFailure ? { assessorFailure } : {}),
+    ...(assessmentUsage ? { usage: assessmentUsage } : {}),
+    measurementAssessments,
+    outputAssessments: (outputs?.outputs ?? []).map((output, index) => {
+      const label = `${index + 1}:${output.id}`;
+      const captured = [
+        `output_present:${label}`,
+        `output_digest:${label}`,
+      ].every((name) => integrity.checks?.some((check) => check.name === name && check.status === "passed"));
+      return {
+        outputId: output.id,
+        kind: output.kind,
+        role: output.role,
+        status: captured ? "captured" : "invalid",
+        reason: captured
+          ? "The output is preserved with a runner-verified content identity"
+          : "The output file or its declared content identity did not pass integrity verification",
+        digest: output.digest,
+        byteSize: output.byteSize,
+        mediaType: output.mediaType,
+      };
+    }),
+    integrityStatus: integrity.status,
+    assessedAt: assessedAt ?? integrity.checkedAt ?? new Date().toISOString(),
+    assessor,
+  };
+  const assessment = { ...body, assessmentDigest: `sha256:${sha256Value(body)}` };
+  if (assessmentPath) await writeJson(assessmentPath, assessment);
+  return assessment;
+}
+
+function evaluateMeasurement({ target, metrics, integrity, result, executionStatus }) {
+  let verificationStatus = "inconclusive";
+  let verdict = "inconclusive";
+  let reason = "Execution integrity checks did not pass, so this measurement cannot be evaluated";
+  let absoluteDifference = null;
+  const observedValue = typeof metrics?.primary?.value === "number" && Number.isFinite(metrics.primary.value)
+    ? metrics.primary.value
+    : null;
+  if (integrity.status === "passed" && observedValue === null) {
+    const evidenceReason = metrics?.availability?.reason ?? "The execution produced no independently parseable metric";
+    reason = result?.execution?.failure
+      ? `${failureReason(result.execution.failure, executionStatus, evidenceReason)} ${evidenceReason}`
+      : evidenceReason;
+  } else if (integrity.status === "passed") {
+    absoluteDifference = Number(Math.abs(observedValue - target.reportedValue).toPrecision(12));
+    if (target.toleranceSource?.kind === "unconfigured") {
+      reason = "The independently parsed observation is preserved, but no metric-specific tolerance was pre-declared; the measurement remains inconclusive";
+    } else {
+      const reproduced = absoluteDifference <= target.tolerance;
+      verificationStatus = reproduced ? "reproduced" : "not_reproduced";
+      verdict = reproduced ? "supports" : "contradicts";
+      reason = reproduced
+        ? "The independently parsed observed result is within the pre-declared tolerance"
+        : "The independently parsed observed result is outside the pre-declared tolerance";
+    }
+  }
+  return {
+    measurementId: target.measurementId,
+    verdict,
+    verificationStatus,
+    reason,
+    comparison: {
+      metric: target.metric,
+      unit: target.unit,
+      reportedValue: target.reportedValue,
+      observedValue,
+      tolerance: target.tolerance,
+      ...(target.toleranceSource ? { toleranceSource: target.toleranceSource } : {}),
+      ...(target.evidenceBasis ? { evidenceBasis: target.evidenceBasis } : {}),
+      ...(target.extractionUncertainty !== undefined
+        ? { extractionUncertainty: target.extractionUncertainty }
+        : {}),
+      absoluteDifference,
+    },
+  };
+}
+
+function failureReason(failure, executionStatus, fallback) {
+  if (!failure || typeof failure !== "object") {
+    return fallback ?? `The execution ended with status ${executionStatus} before a trustworthy comparison metric was available`;
+  }
+  const retryability = failure.retryable ? "potentially retryable" : "not retryable without changing the available inputs or conditions";
+  return `The execution was ${executionStatus} during ${failure.stage ?? "an unknown stage"} because of ${failure.category ?? "an unclassified failure"}: ${failure.reason ?? fallback ?? "no further detail was recorded"}. This outcome is ${retryability}`;
+}

package/src/verification/evidence-context.mjs

@@ -0,0 +1,165 @@
+import path from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { createHash } from "node:crypto";
+import { lstat, readFile, realpath, readdir } from "node:fs/promises";
+import { redactString } from "../cap/redaction.mjs";
+import { safeRelativePath, sha256Value } from "../util.mjs";
+
+const execute = promisify(execFile);
+const MAX_FILE_BYTES = 64 * 1024 * 1024; // Memory safety per retained text file; never a prompt limit.
+
+
+/** Host-selected, bounded source material for independent assessment. Selection
+ * and hashes establish which bytes were read, never scientific correctness.
+ * No arbitrary file reads or commands supplied by the execution Agent are run.
+ */
+export async function buildAssessmentEvidenceContext({ runDirectory, contract, claim, runnerAudit, paperDigest }) {
+  const root = await realpath(runDirectory);
+  const files = [];
+  const omissions = [];
+
+  const task = await readJson("input/task.json");
+  const after = await readJson("execution/workspace-after.json");
+  const entries = new Map((after?.entries ?? []).map((entry) => [entry.path, entry]));
+
+  const addText = async (relative, role, expectedDigest) => {
+    if (files.some((item) => item.path === relative)) return;
+
+    try {
+      const { bytes } = await readSafe(relative, MAX_FILE_BYTES);
+      if (bytes.includes(0)) throw new Error("binary_file");
+      const digest = sha256Bytes(bytes);
+      if (expectedDigest && normalizeDigest(expectedDigest) !== digest) throw new Error("workspace_snapshot_digest_mismatch");
+      const text = redactString(bytes.toString("utf8"));
+      const selected = { text, truncated: false, originalCharacters: text.length };
+      files.push({ role, path: relative, digest, byteSize: bytes.length,
+        provenance: expectedDigest ? "matches_runner_workspace_snapshot" : "retained_run_file",
+        redacted: text !== bytes.toString("utf8"), ...selected });
+
+      return true;
+    } catch (error) { omissions.push({ path: relative, reason: error.code === "ENOENT" ? "not_retained" : error.message }); return false; }
+  };
+
+  // Paper excerpts are selected by the actual source locators, not by result
+  // proximity. Missing or ambiguous locators remain visible to the assessor.
+  const paper = task?.paper?.path;
+  if (typeof paper === "string" && paper.startsWith("/job/input/paper/") && path.basename(paper) !== ".") {
+    const relative = `input/paper/${path.basename(paper)}`;
+    try {
+      const { bytes, filename } = await readSafe(relative, 64 * 1024 * 1024);
+      const digest = sha256Bytes(bytes);
+      if (paperDigest && normalizeDigest(paperDigest) !== digest) throw new Error("paper_snapshot_digest_mismatch");
+      const text = path.extname(filename).toLowerCase() === ".pdf"
+        ? (await execute("pdftotext", ["-layout", filename, "-"], { timeout: 20_000, maxBuffer: MAX_FILE_BYTES })).stdout
+        : bytes.toString("utf8");
+      const locators = sourceLocators(contract, claim);
+      const excerpts = selectSourceExcerpts(text, locators, 18_000);
+      files.push({ role: "paper_source", path: relative, digest, byteSize: bytes.length,
+        provenance: paperDigest ? "matches_fixed_paper_digest" : "staged_paper_snapshot",
+        requestedLocators: locators, excerpts, text: redactString(text), truncated: false, completeDocument: true });
+
+      if (!excerpts.length) omissions.push({ path: relative, reason: "no_source_locator_resolved" });
+    } catch (error) { omissions.push({ path: relative, reason: error.code === "ENOENT" ? "not_retained" : error.message }); }
+  } else omissions.push({ role: "paper_source", reason: "staged_paper_unavailable" });
+
+  const rawPaths = [...new Set((contract.measurements ?? []).map((item) => item.parser?.evidencePath).filter(safeRelativePath))];
+  for (const relative of rawPaths) await addText(`output/${relative}`, "parser_input", null);
+  // Keep the raw histories available for paged independent reads, not only the aggregate.
+  async function visitOutput(directory) {
+    for (const entry of await readdir(path.join(root, directory), { withFileTypes: true }).catch(() => [])) {
+      const relative = `${directory}/${entry.name}`;
+      // Delivery is derived after scientific assessment. Feeding it back into
+      // evidence would invalidate the same run's checkpoint on every replay.
+      if (['output/handoff-review.json', 'output/reproduction-code.json', 'output/REPRODUCE.md'].includes(relative)) continue;
+      if (entry.isDirectory()) await visitOutput(relative);
+      else if (entry.isFile() && /\.(json|jsonl|ndjson|csv|tsv|txt|log)$/.test(relative)
+        && !/(?:credentials|secrets?|auth\.json|\.env)/i.test(relative)) await addText(relative, "raw_evidence");
+    }
+  }
+  await visitOutput("output");
+
+  // Read helpers/configuration actually named in captured commands, followed
+  // by changed source files. Only bytes matching the captured final snapshot
+  // are included; a patch is provided separately to disclose modifications.
+  const commandPaths = (runnerAudit?.commandRecords ?? []).flatMap((record) =>
+    [...(record.command?.text ?? "").matchAll(/\/job\/workspace\/repository\/([A-Za-z0-9_./-]+)/g)].map((match) => match[1]));
+  const changes = await readJson("execution/workspace-changes.json");
+  const changedPaths = [...(changes?.added ?? []), ...(changes?.modified ?? [])].map((item) => item.path);
+  const implementationPaths = (contract.protocol?.benchmark?.implementations ?? []).map((item) => item.provenance);
+  const candidates = [...new Set([...commandPaths, ...implementationPaths, ...changedPaths, ...entries.keys()])].filter((relative) =>
+    safeRelativePath(relative) && /\.(?:py|sh|mjs|js|ts|cu|c|cpp|h|json|toml|ya?ml|ipynb|r|R|rs|jl|java|cfg|ini|md|txt)$/.test(relative)
+    && !/(?:^|\/)(?:\.env[^/]*|[^/]*(?:credentials|signing-key|private-key)[^/]*|secrets?[^/]*|auth\.json|id_rsa)$/.test(relative));
+  for (const relative of candidates) {
+    const entry = entries.get(relative);
+    if (!entry?.sha256 || entry.type !== "file") { omissions.push({ path: relative, reason: "no_runner_snapshot_binding" }); continue; }
+    const localPath = `workspace/repository/${relative}`;
+    const included = await addText(localPath, "implementation", entry.sha256);
+    // Remote publication retains added files in the checkpoint, while the
+    // coordinator checkout can still contain the original source snapshot.
+    if (!included && await addText(`execution/workspace-checkpoint/untracked/${relative}`, "implementation", entry.sha256)) {
+      const index = omissions.findIndex((item) => item.path === localPath && item.reason === "not_retained");
+      if (index >= 0) omissions.splice(index, 1);
+    }
+  }
+
+  if (changedPaths.length) await addText("execution/repository.patch", "implementation_changes", null);
+  const body = { schemaVersion: "1.1", kind: "citeark.assessment-evidence-context",
+    trust: "Untrusted scientific content selected by the host; hashes bind bytes, not truth. Missing and truncated material cannot be assumed verified.",
+    files, omissions };
+  return { ...body, digest: `sha256:${sha256Value(body)}` };
+
+  async function readSafe(relative, maximumBytes) {
+    if (!safeRelativePath(relative)) throw new Error("unsafe_path");
+    const filename = path.join(root, relative);
+    const stat = await lstat(filename);
+    if (!stat.isFile() || !(await realpath(filename)).startsWith(`${root}${path.sep}`)) throw new Error("not_a_regular_run_file");
+    if (stat.size > maximumBytes) throw new Error("file_size_budget");
+    return { bytes: await readFile(filename), filename };
+  }
+  async function readJson(relative) {
+    try { return JSON.parse((await readSafe(relative, MAX_FILE_BYTES)).bytes.toString("utf8")); }
+    catch { return null; }
+  }
+}
+
+function normalizeDigest(value) { return value.startsWith("sha256:") ? value : `sha256:${value}`; }
+function sha256Bytes(bytes) { return `sha256:${createHash("sha256").update(bytes).digest("hex")}`; }
+
+function sourceLocators(contract, claim) {
+  const sources = [claim?.sourceLocator, ...(claim?.reportedMeasurements ?? []).map((item) => item.sourceLocator),
+    ...(contract.executionPlan?.plan?.sources ?? [])];
+  return [...new Set(sources.map((source) => typeof source === "string" ? source : source?.locator).filter((value) => typeof value === "string" && value.trim()))];
+}
+
+export function selectSourceExcerpts(text, locators, maximumChars = 18_000) {
+  const pages = text.split("\f");
+  const selected = new Map();
+  for (const locator of locators) {
+    for (const match of locator.matchAll(/\b(?:page|p\.)\s*(\d+)\b/gi)) {
+      const index = Number(match[1]) - 1;
+      if (pages[index] !== undefined && !selected.has(index)) selected.set(index, { locator, offset: 0 });
+    }
+    const terms = [...locator.matchAll(/\b(?:table|figure|section|appendix)\s+[A-Z0-9]+(?:\.\d+)*/gi)].map((match) => match[0]);
+    for (const term of terms) {
+      const escaped = term.replace(/[.*+?^${}()|[\]\\]/g, "\\$&").replace(/\s+/g, "\\s+");
+      const pattern = new RegExp(`${escaped}\\b`, "i");
+      for (let index = 0; index < pages.length; index++) {
+        const match = pattern.exec(pages[index]);
+        if (match && !selected.has(index)) selected.set(index, { locator, offset: Math.max(0, match.index - 600) });
+      }
+    }
+  }
+  const excerpts = [];
+  let remaining = maximumChars;
+  for (const [index, selection] of selected) {
+    if (remaining <= 0 || excerpts.length >= 6) break;
+    const content = redactString(pages[index]);
+    const limit = Math.min(5_000, remaining);
+    const end = Math.min(content.length, selection.offset + limit);
+    excerpts.push({ page: index + 1, locator: selection.locator, startCharacter: selection.offset,
+      text: content.slice(selection.offset, end), truncated: selection.offset > 0 || end < content.length });
+    remaining -= end - selection.offset;
+  }
+  return excerpts;
+}

package/src/verification/evidence-reader.mjs

@@ -0,0 +1,95 @@
+import { sha256Value } from "../util.mjs";
+
+// These are per-response page sizes. Every retained character remains addressable.
+const PAGE = 12_000;
+const tool = (name, description, properties, required) => ({ type: "function", function: {
+  name, description, parameters: { type: "object", properties, required, additionalProperties: false },
+} });
+export function createAssessmentEvidenceReader({ evidenceContext, runnerAudit }) {
+  const documents = new Map();
+  for (const file of evidenceContext?.files ?? []) {
+    const text = file.text ?? file.excerpts?.map(e => `[page ${e.page}]\n${e.text}`).join("\n");
+    if (typeof text === "string") documents.set(file.path, { ...file, text });
+  }
+  for (const record of runnerAudit?.commandRecords ?? []) {
+    for (const field of ["command", "stdout", "stderr"]) {
+      if (typeof record[field]?.text === "string") documents.set(`audit/${record.recordId}/${field}`, {
+        path: `audit/${record.recordId}/${field}`, role: "execution_audit", recordId: record.recordId,
+        text: record[field].text, digest: `sha256:${sha256Value(record[field].text)}`,
+        status: record.status, exitCode: record.exitCode, truncated: Boolean(record[field].truncated),
+      });
+    }
+  }
+  const descriptor = ({ text, excerpts, ...file }) => ({ ...file, characters: text.length });
+  const index = [...documents.values()].map(descriptor);
+  const reads = [];
+  const definitions = [
+    tool("list_evidence", "List retained paper, full implementation, raw data and execution logs. Pagination limits one response, not the accessible corpus.", {
+      offset: { type: "integer", minimum: 0 }, prefix: { type: "string" },
+    }, ["offset", "prefix"]),
+    tool("read_evidence", "Read exact retained characters. Follow nextOffset until the relevant implementation is complete. Legacy truncation is explicitly marked and cannot be recovered by this tool.", {
+      path: { type: "string" }, offset: { type: "integer", minimum: 0 },
+    }, ["path", "offset"]),
+    tool("search_evidence", "Literal search in all retained documents; page results with offset. A hit is not verification; read the surrounding implementation.", {
+      query: { type: "string", minLength: 1 }, prefix: { type: "string" }, offset: { type: "integer", minimum: 0 },
+    }, ["query", "prefix", "offset"]),
+    tool("read_evidence_json", "Read a JSON pointer from a retained JSON file, including exact scalars, keys or slices of arrays. No execution of scientific code.", {
+      path: { type: "string" }, pointer: { type: "string" }, offset: { type: "integer", minimum: 0 },
+    }, ["path", "pointer", "offset"]),
+  ];
+  function execute(name, args) {
+    let result;
+    try {
+      const offset = args.offset;
+      if (!Number.isSafeInteger(offset) || offset < 0) throw Error("offset must be a nonnegative integer");
+      if (name === "list_evidence") {
+        const selected = index.filter(d => d.path.startsWith(args.prefix));
+        result = { files: selected.slice(offset, offset + 40), total: selected.length,
+          nextOffset: offset + 40 < selected.length ? offset + 40 : null };
+      } else if (name === "read_evidence") {
+        const d = documents.get(args.path); if (!d) throw Error("Path is not in retained evidence index");
+        result = { ...descriptor(d), offset, text: d.text.slice(offset, offset + PAGE),
+          nextOffset: offset + PAGE < d.text.length ? offset + PAGE : null };
+      } else if (name === "search_evidence") {
+        if (typeof args.query !== "string" || !args.query) throw Error("Nonempty literal query required");
+        const hits = [];
+        let total = 0;
+        for (const d of documents.values()) {
+          if (!d.path.startsWith(args.prefix)) continue;
+          let at = 0;
+          while ((at = d.text.indexOf(args.query, at)) !== -1) {
+            if (total >= offset && hits.length < 20) hits.push({ path: d.path, offset: at, preview: d.text.slice(Math.max(0, at - 100), at + 200) });
+            total++;
+            at += args.query.length;
+          }
+        }
+        result = { hits, total,
+          nextOffset: offset + 20 < total ? offset + 20 : null };
+      } else if (name === "read_evidence_json") {
+        const d = documents.get(args.path); if (!d) throw Error("Path is not in retained evidence index");
+        if (d.truncated) throw Error("Legacy file is truncated; not a complete JSON source");
+        let value = JSON.parse(d.text);
+        if (args.pointer !== "") {
+          if (!args.pointer.startsWith("/")) throw Error("Expected JSON pointer");
+          for (const part of args.pointer.slice(1).split("/")) {
+            const key = part.replace(/~1/g, "/").replace(/~0/g, "~");
+            if (value === null || typeof value !== "object" || !Object.hasOwn(value, key)) throw Error("Pointer absent");
+            value = value[key];
+          }
+        }
+        if (Array.isArray(value)) result = { length: value.length, values: value.slice(offset, offset + 20), nextOffset: offset + 20 < value.length ? offset + 20 : null };
+        else if (value && typeof value === "object") {
+          const keys = Object.keys(value); result = { keys: keys.slice(offset, offset + 100), total: keys.length, nextOffset: offset + 100 < keys.length ? offset + 100 : null };
+        } else result = { value };
+        if (JSON.stringify(result).length > PAGE) result = { error: "Selected values exceed a response page; read a narrower JSON pointer or use character pages" };
+      } else throw Error("Unknown evidence tool");
+    } catch (error) { result = { error: error.message }; }
+    reads.push({ name, args, responseDigest: `sha256:${sha256Value(result)}` });
+    return result;
+  }
+  return { definitions, execute, reads, index,
+    orientation: { digest: evidenceContext?.digest, available: documents.size > 0,
+      files: index.slice(0, 40), totalFiles: index.length, nextOffset: index.length > 40 ? 40 : null,
+      omissions: evidenceContext?.omissions ?? [],
+      instruction: "Use evidence tools to inspect complete source, called implementation and raw observations. An initial index is not evidence inspection. Read core update/evaluator code, including helpers and original source, before claiming comparability. Material omitted by the platform is not missing author material. Never infer correctness from labels, hashes or scalar proximity." } };
+}