@visual-z/xeno 0.2.1 → 0.3.0

package/src/core/project.ts

@@ -30,6 +30,10 @@ import type { LogEvent, AssistantBlock } from "./events.ts";
 import { assertNever } from "./exhaustive.ts";
 import type { ImageContent } from "./images.ts";
 import { type Handoff, emitHandoff } from "./handoff.ts";
+import { diagnosticContent } from "./tool-contract.ts";
+
+/** O.8: persist the interpretation used to replay a frozen request. */
+export const PROJECTION_VERSION = 1;
 
 export type ContentBlock =
   | ImageContent
@@ -61,15 +65,18 @@ export interface FrozenPrefix {
 }
 
 export interface ProjectInput {
+  /** Diagnostic only; trace never enters provider messages. */
+  trace?: boolean;
   frozen: FrozenPrefix;
   /** Previous segment's handoff, or null for segment 0. */
   handoff: Handoff | null;
   events: readonly LogEvent[];
-  /** Log location given to the model so it can grep for anything the handoff omits. */
-  logHint?: { manifestPath: string; segmentPath: string };
+  /** Source locations and versioned recovery guidance; workspace search does not index the log. */
+  logHint?: { manifestPath: string; segmentPath: string; scopedGuidance?: true };
 }
 
 export interface ProjectResult {
+  provenance?: { version: number; messages: string[][]; omitted: string[] };
   system: string;
   tools: readonly unknown[];
   messages: Message[];
@@ -110,9 +117,11 @@ export interface ProjectViolation {
  * two things". It is a following message rather than a mutation of the user
  * turn so appending the event only appends to the projection (P7).
  */
-type ReplayEvent = Extract<LogEvent, { t: "user" | "user_bash" | "guidance" | "interrupt" | "assistant" | "tool_result" | "rewind" | "snapshot" | "extension" }>;
+type ReplayEvent = Extract<LogEvent, { t: "acceptance_contract" | "acceptance_decision" | "user" | "user_bash" | "guidance" | "interrupt" | "assistant" | "tool_result" | "rewind" | "snapshot" | "extension" }>;
 
 function replayable(e: LogEvent): e is ReplayEvent {
+  if (e.t === "tool_result" && (e.parent_call_id !== undefined || e.origin === "extension")) return false;
+  if (e.t === "acceptance_contract" || e.t === "acceptance_decision") return true;
   if (e.t === "extension") return e.inContext;
   if (e.t === "user_bash") return !e.excludeFromContext;
   if (e.t === "rewind") return e.mode !== "both";
@@ -198,7 +207,7 @@ export function renderRewindMessage(e: Extract<LogEvent, { t: "rewind" }>): Mess
  */
 export function renderHandoffMessage(
   handoff: Handoff,
-  logHint?: { manifestPath: string; segmentPath: string },
+  logHint?: { manifestPath: string; segmentPath: string; scopedGuidance?: true },
 ): Message {
   const yaml = emitHandoff(handoff);
 
@@ -221,8 +230,10 @@ export function renderHandoffMessage(
       "detail this state does not carry, read it rather than guessing:",
       `  - segment index: ${logHint.manifestPath}`,
       `  - previous segment: ${logHint.segmentPath}`,
-      "Each line is one JSON event. Search it with history; read a line range with read,",
-      "or filter with bash and jq. The grep tool skips the log directory.",
+      ...(logHint.scopedGuidance !== true ? [
+        "Each line is one JSON event. Search it with history; read a line range with read,",
+        "or filter with bash and jq. The grep tool skips the log directory.",
+      ] : ["Each line is one JSON event. Recover originals using the declared tools' contracts; if evidence is inaccessible, state the gap instead of guessing."]),
     );
   }
 
@@ -251,9 +262,11 @@ export function renderHandoffMessage(
 export function projectContext(input: ProjectInput): ProjectResult {
   const violations: ProjectViolation[] = [];
   const messages: Message[] = [];
+  const sources: string[][] = [];
+  const append = (message: Message, ids: string[]) => { messages.push(message); sources.push(ids); };
 
   if (input.handoff) {
-    messages.push(renderHandoffMessage(input.handoff, input.logHint));
+    append(renderHandoffMessage(input.handoff, input.logHint), [`handoff:${input.handoff.predecessor?.node ?? "root"}`]);
   }
 
   const events = input.events.filter(replayable);
@@ -262,10 +275,12 @@ export function projectContext(input: ProjectInput): ProjectResult {
   // a SINGLE user message. Splitting them across messages teaches the model to stop
   // issuing parallel calls, which is a silent, permanent capability regression.
   let pending: ContentBlock[] = [];
+  let pendingSources: string[] = [];
   const flushPending = () => {
     if (pending.length > 0) {
-      messages.push({ role: "user", content: pending });
+      append({ role: "user", content: pending }, pendingSources);
       pending = [];
+      pendingSources = [];
     }
   };
 
@@ -273,29 +288,38 @@ export function projectContext(input: ProjectInput): ProjectResult {
   let awaiting = new Set<string>();
 
   for (const e of events) {
+    if (e.t === "acceptance_contract" || e.t === "acceptance_decision") {
+      flushPending();
+      if (awaiting.size) violations.push({ code: "UNPAIRED_TOOL_USE", detail: `acceptance event ${e.id} follows unanswered tools` });
+      append({ role: "user", content: [{ type: "text", text: e.t === "acceptance_contract"
+        ? `Declared acceptance contract (execution success alone does not satisfy it): ${JSON.stringify(e.contract)}`
+        : `User accepted criterion ${e.criterion} of contract ${e.contract_id} for request ${e.request}.` +
+          (e.target_binding ? ` Bound to runtime instance ${e.target_binding}, observation ${e.target_observation}. Later runtime changes invalidate this acceptance.` : "") }] }, [e.id]);
+      continue;
+    }
     if (e.t === "extension") {
       flushPending();
       if (awaiting.size) violations.push({ code: "UNPAIRED_TOOL_USE", detail: `custom message ${e.id} follows unanswered tool_use ${[...awaiting].join(", ")}` });
-      messages.push({ role: "user", content: [{ type: "text", text: e.content }] });
+      append({ role: "user", content: [{ type: "text", text: e.content }] }, [e.id]);
       continue;
     }
     if (e.t === "user_bash") {
       flushPending();
-      messages.push({ role: "user", content: [{ type: "text", text: `User ran: ${e.command}\n${e.content}` }] });
+      append({ role: "user", content: [{ type: "text", text: `User ran: ${e.command}\n${e.content}` }] }, [e.id]);
       continue;
     }
     if (e.t === "snapshot") {
       flushPending();
-      messages.push({ role: "user", content: [{ type: "text",
+      append({ role: "user", content: [{ type: "text",
         text: `Workspace observation: changes outside declared file edits: ${e.undeclared.join(", ")}. ${REREAD_INSTRUCTION}`,
-      }] });
+      }] }, [e.id]);
       continue;
     }
     if (e.t === "rewind") {
       // Flushed first for the same reason a user turn is: it opens a user
       // message, and a pending tool_result batch has to close before it.
       flushPending();
-      messages.push(renderRewindMessage(e));
+      append(renderRewindMessage(e), [e.id]);
       continue;
     }
     if (e.t === "user" || e.t === "guidance") {
@@ -307,8 +331,8 @@ export function projectContext(input: ProjectInput): ProjectResult {
         });
         awaiting = new Set();
       }
-      messages.push({ role: "user", content: [...(e.text || e.t === "guidance" || !e.images?.length ? [{ type: "text" as const, text: e.text }] : []),
-        ...(e.t === "user" ? (e.images ?? []).map(image => ({ type: "image" as const, image })) : [])] });
+      append({ role: "user", content: [...(e.text || e.t === "guidance" || !e.images?.length ? [{ type: "text" as const, text: e.text }] : []),
+        ...(e.t === "user" ? (e.images ?? []).map(image => ({ type: "image" as const, image })) : [])] }, [e.id]);
       continue;
     }
     if (e.t === "interrupt") {
@@ -316,7 +340,7 @@ export function projectContext(input: ProjectInput): ProjectResult {
       // look-ahead mutation of that turn would rewrite it once a later
       // event (tool_use, another user) was already projected after it.
       flushPending();
-      messages.push({ role: "user", content: [{ type: "text", text: INTERRUPT_NOTE }] });
+      append({ role: "user", content: [{ type: "text", text: INTERRUPT_NOTE }] }, [e.id]);
       continue;
     }
 
@@ -328,7 +352,7 @@ export function projectContext(input: ProjectInput): ProjectResult {
           detail: `assistant turn ${e.id} follows unanswered tool_use ${[...awaiting].join(", ")}`,
         });
       }
-      messages.push({ role: "assistant", content: e.blocks.map(toContentBlock) });
+      append({ role: "assistant", content: e.blocks.map(toContentBlock) }, [e.id]);
       awaiting = new Set(
         e.blocks.filter((b) => b.type === "tool_use").map((b) => (b as { call_id: string }).call_id),
       );
@@ -344,10 +368,11 @@ export function projectContext(input: ProjectInput): ProjectResult {
       continue;
     }
     awaiting.delete(e.call_id);
+    pendingSources.push(e.id);
     pending.push({
       type: "tool_result",
       tool_use_id: e.call_id,
-      content: e.content,
+      content: diagnosticContent(e.content, e.diagnostic) + (e.warnings?.length ? "\nObserver warnings (operation result retained): " + JSON.stringify(e.warnings) : ""),
       ...(e.ok ? {} : { is_error: true }),
     });
     // Images follow the paired text result, so APIs without image tool outputs receive a user image.
@@ -368,6 +393,8 @@ export function projectContext(input: ProjectInput): ProjectResult {
   }
 
   return {
+    ...(input.trace ? { provenance: { version: PROJECTION_VERSION, messages: sources,
+      omitted: input.events.filter(e => !sources.some(ids => ids.includes(e.id))).map(e => e.id) } } : {}),
     system: input.frozen.system,
     tools: input.frozen.tools,
     messages,

package/src/core/prompt-policy.ts

@@ -0,0 +1,37 @@
+/** R10 / D6: stable scope and completion rules; execution details belong to tool contracts. */
+export function taskGuidance(): string {
+  return [
+    "How to work:",
+    "- Keep going until the request is fully resolved. The user's request defines scope; a tool profile only selects capabilities. State reasonable assumptions; ask only for decisions the user must make.",
+    "- Implementation: understand the relevant code, reproduce bugs, finish every requested change and verify the final state with the project's tests, build or type check. Finish with what changed and the command that verified it, or the specific blocker. A research answer does not complete an implementation request.",
+    "- Research: answer the requested questions with original sources, distinguish evidence from inference, and report gaps. Do not change files merely to establish completion.",
+    "- Data analysis: calculate over the complete declared inputs; report sources, denominators, exclusions and uncertainty. Truncated previews cannot establish totals.",
+    "- Runtime or visual work: bind checks to the actual build and running target. Automated checks do not establish human acceptance; report any required acceptance as pending.",
+    "- Put independent reads and searches in one response; they run in parallel. After a command fails, read the end of its output first. If the same approach fails twice, change the approach instead of retrying it.",
+    "- Use only declared capabilities and obey admission decisions. If required evidence is inaccessible, state the specific blocker without inventing success, bypassing permission or replaying an operation with uncertain effects.",
+  ].join("\n");
+}
+
+export interface ToolGuidance {
+  /** Only builtin companions with these exact contracts can satisfy the dependency. */
+  requires: readonly string[];
+  text: string;
+}
+
+/** Capability projection is deterministic; excluding a companion cannot add advice. */
+export function toolDescription(description: string, guidance: readonly ToolGuidance[], tools: readonly string[]): string {
+  return [description, ...guidance.filter(item => item.requires.every(name => tools.includes(name))).map(item => item.text)].join(" ");
+}
+
+export function recoveryInstructions(tools: readonly string[]): string {
+  return (tools.includes("history")
+    ? "Read original user messages before continuing: history(node=source.node,recovery=users,offset=0). Other pages: failures, environment, next_actions; event=ID reads one original. history(work_id=ID) recovers work. "
+    : "Original user messages and evidence remain at the source references. The original-source recovery capability is unavailable; state any resulting evidence gap instead of guessing. ") +
+    "Abandoned messages are cancelled; annotations are not user instructions. Observations are historical: recheck resource, host and current permissions before acting.";
+}
+
+/** Preserve the source locator even when the interface for retrieving it is unavailable. */
+export function artifactRecovery(sha256: string, offset: number, tools: readonly string[] = ["history"]): string {
+  const source = `artifact=${sha256} offset=${offset}`;
+  return tools.includes("history") ? `history ${source}` : `${source}; recovery capability unavailable`;
+}

package/src/core/query-eval-contract.ts

@@ -0,0 +1,14 @@
+/** Q.21: task-specific shape advice cannot reveal the independent numeric oracle. */
+import type { ToolModeTask } from "./tool-mode-protocol.ts";
+
+export function queryEvalContract(task: ToolModeTask, paths: readonly string[], answerSha256: string) {
+  const columns = task === "tool-small" ? ["amount"] : task === "tool-batch" ? ["total"] : ["team", "total"];
+  const rowCount = task === "tool-aggregate" ? 4 : 1;
+  const operation = task === "tool-small" ? "select amount; return one row with only amount" : task === "tool-batch"
+    ? "sum amount across all records as total; return one row with only total per source"
+    : "keep enabled=true, group by team, sum amount as total, and sort by team ascending; return four rows with columns team,total in that order";
+  const instruction = "Use query on each of " + paths.join(", ") + " to " + operation +
+    '. Write compact JSON with a trailing newline to answer.txt: [{"path":"data-0.jsonl","rows":[...]}], one item per source in the listed order. ' +
+    "Preserve all fixture inputs and run bun run gate.";
+  return { instruction, columns, rowCount, paths: [...paths], answerSha256 };
+}

package/src/core/read-observation.ts

@@ -0,0 +1,82 @@
+/** R2 / D8: source bytes, an unclipped observation, and the visible projection have distinct identities. */
+import type { ArtifactRef } from "./events.ts";
+import { artifactRecovery } from "./prompt-policy.ts";
+import { headTailSelection, isObservationArtifact as ref, isBytePreview, type BytePreview } from "./observation-view.ts";
+
+export interface ObservationReceipt {
+  version: 1;
+  source: { host: string; workspace: string; resource: string; sha256: string; raw: ArtifactRef };
+  artifact: ArtifactRef;
+  /** R4: content-addressed version premise, separate from this formatted observation. */
+  descriptor?: ArtifactRef;
+  selection: { start: number; end: number; total_lines: number };
+  preview: BytePreview;
+}
+
+const encoder = new TextEncoder();
+const size = (text: string) => encoder.encode(text).length;
+/** Existing assumed preview cap; archival removes data loss without changing the display policy. */
+const READ_MAX_LINE_CHARS = 2000;
+
+export function readObservationText(header: string, lines: readonly string[], start: number): string {
+  return header + lines.map((line, i) => `${start + i}\t${line}`).join("\n");
+}
+
+/** Map two successive cuts (per line and total bytes) back to the same immutable observation. */
+export function previewReadObservation(header: string, lines: readonly string[], start: number, artifact: string,
+  maxBytes: number, maxLineChars = READ_MAX_LINE_CHARS, tools?: readonly string[]): { text: string; preview: ObservationReceipt["preview"]; semantic: string } {
+  const spans: { view: number; source: number; bytes: number }[] = [];
+  let text = "", source = 0, view = 0;
+  const mapped = (value: string, offset: number) => {
+    const bytes = size(value);
+    if (bytes) spans.push({ view, source: offset, bytes });
+    text += value; view += bytes;
+  };
+  const synthetic = (value: string) => { text += value; view += size(value); };
+  mapped(header, 0); source += size(header);
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]!, prefix = `${start + i}\t`;
+    let end = Math.min(line.length, maxLineChars);
+    // JavaScript string indices are UTF-16; a character can occupy a surrogate pair.
+    if (end > 0 && end < line.length && /[\uD800-\uDBFF]/.test(line[end - 1]!)) end--;
+    const kept = prefix + line.slice(0, end);
+    mapped(kept, source);
+    if (end < line.length) synthetic(` [line truncated: ${line.length} chars; ${artifactRecovery(artifact, source + size(kept), tools)}]`);
+    source += size(prefix + line);
+    if (i < lines.length - 1) { mapped("\n", source); source++; }
+  }
+  const bytes = encoder.encode(text);
+  const selected = headTailSelection(bytes, bytes, bytes.length, maxBytes,
+    omitted => `\n[truncated ${omitted} preview bytes; ${artifactRecovery(artifact, 0, tools)}]\n`);
+  const visible: [number, number][] = [];
+  for (const [lo, hi] of selected.visible) for (const span of spans) {
+    const begin = Math.max(lo, span.view), end = Math.min(hi, span.view + span.bytes);
+    if (end <= begin) continue;
+    const a = span.source + begin - span.view, b = span.source + end - span.view;
+    const last = visible.at(-1);
+    if (last?.[1] === a) last[1] = b;
+    else visible.push([a, b]);
+  }
+  let next = 0;
+  for (const [lo, hi] of visible) { if (lo !== next) break; next = hi; }
+  const full = encoder.encode(readObservationText(header, lines, start));
+  const semantic = visible.map(([lo, hi]) => new TextDecoder().decode(full.subarray(Math.max(lo, size(header)), Math.max(hi, size(header))))).join("");
+  return { text: selected.text, semantic, preview: { unit: "utf8_bytes", complete: next === source,
+    visible, next_offset: next === source ? null : next } };
+}
+
+const record = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
+const natural = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+const digest = (value: unknown): value is string => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+
+/** Optional on old logs, strict when present. A cursor cannot certify bytes outside its artifact. */
+export function isObservationReceipt(value: unknown): value is ObservationReceipt {
+  if (!record(value) || value["version"] !== 1 || !ref(value["artifact"])) return false;
+  if (value["descriptor"] !== undefined && !ref(value["descriptor"])) return false;
+  const source = value["source"], selection = value["selection"], preview = value["preview"];
+  if (!record(source) || !["host", "workspace", "resource"].every(key => typeof source[key] === "string" && source[key] !== "") ||
+    !digest(source["sha256"]) || !ref(source["raw"]) || source["sha256"] !== source["raw"].sha256) return false;
+  if (!record(selection) || !natural(selection["start"]) || selection["start"] < 1 || !natural(selection["end"]) ||
+    !natural(selection["total_lines"]) || selection["end"] < selection["start"] || selection["end"] > selection["total_lines"]) return false;
+  return isBytePreview(preview, value["artifact"].bytes);
+}

package/src/core/recovery-corpus.ts

@@ -0,0 +1,17 @@
+/** R12c: curated mechanisms, never copied private transcript contents or population estimates. */
+export const RECOVERY_SOURCE_REPORT = { path: "docs/research/local-agent-tool-audit-2026-10-06.md",
+  sha256: "a4c83ec9e5c52ea6500434673f0e90c171e55aa247d293dc3f09c893ec604832" } as const;
+export const RECOVERY_CASES = [
+  {id:"recovery-missing-path",family:"parameters",partition:"development",source:"E2",basis:"observed",scenario:"An edit omits its required file identity."},
+  {id:"recovery-stale-version",family:"version",partition:"development",source:"section-2.2-replacement-mismatch",basis:"derived-scenario",scenario:"An obsolete file digest must not authorize an edit over newer content; the source mismatch alone did not establish a stale-version cause."},
+  {id:"recovery-long-output",family:"output",partition:"development",source:"X2",basis:"observed",scenario:"A clipped long line hides the needed value; recover immutable original bytes."},
+  {id:"recovery-api-mismatch",family:"environment",partition:"holdout",source:"E4",basis:"portable-analogue",scenario:"An older local API rejects a named option; inspect its actual contract before retrying."},
+  {id:"recovery-closed-process",family:"lifecycle",partition:"development",source:"E5",basis:"derived-scenario",scenario:"A finished process cannot accept more input; the original unknown ID did not establish why ownership was lost."},
+  {id:"recovery-unchanged-retry",family:"recovery",partition:"development",source:"E3",basis:"derived-scenario",scenario:"Changing replacement wording does not repair an unchanged missing anchor; this extends the source's identical retry mechanism."},
+  {id:"recovery-runtime-acceptance",family:"acceptance",partition:"holdout",source:"E6",basis:"scenario-from-user-question",scenario:"A build is not a running current instance or author acceptance; bind the preview to its build."},
+  {id:"recovery-eof",family:"parameters",partition:"holdout",source:"section-2.2-read-range",basis:"observed",scenario:"A line request exceeds the real file boundary; recover from the reported range."},
+] as const;
+export type RecoveryTask = typeof RECOVERY_CASES[number]["id"];
+export const RECOVERY_TASKS = RECOVERY_CASES.map(item=>item.id);
+export const recoveryCase = (task:string) => RECOVERY_CASES.find(item=>item.id===task);
+export type RecoveryPartition = "all" | "development" | "holdout";

package/src/core/recovery-evaluation.ts

@@ -0,0 +1,60 @@
+/** R12c: metrics are projections of original calls, not generated tool-result prose. */
+import type {LogEvent} from "./events.ts";
+import {advanceRecovery,emptyRecoveryState} from "./failure-recovery.ts";
+import {resolveEvidence} from "./evidence.ts";
+
+export interface RecoveryMetrics {
+  toolCalls:number; recordedInvocations:number; outerCalls:number; nestedCalls:number; unresolvedCalls:number; toolFailures:number;
+  firstToolSuccess:boolean|null; firstPassTaskSuccess:boolean|null; finalTaskSuccess:boolean|null;
+  recoveryCalls:number; unchangedFailureRetries:number; classifiedFailures:number; unclassifiedFailures:number;
+  originalEvidenceRetrievals:number; unsupportedClaims:number;
+}
+export function deriveRecoveryMetrics(nodes:readonly {node:number;events:readonly LogEvent[]}[],verifiedRetrievals:ReadonlySet<string>,
+  finalTaskSuccess:boolean|null,identify:(path:string)=>string):RecoveryMetrics{
+  type Call={name:string;ordinal:number;recorded:boolean;nested:boolean;ok:boolean|null};
+  const calls=new Map<string,Call>();let ordinal=0,firstFailure=Infinity,repeated=0,classified=0,unclassified=0,retrieved=0,unsupported=0;
+  let state=emptyRecoveryState();
+  for(const part of nodes)for(const [index,event] of part.events.entries()){
+    ordinal++;
+    if(event.t==="assistant")for(const block of event.blocks)if(block.type==="tool_use"){
+      const key=`${part.node}:${block.call_id}`;
+      if(calls.has(key))throw Error("duplicate recovery call identity");
+      calls.set(key,{name:block.name,ordinal,recorded:false,nested:false,ok:null});
+    }
+    if(event.t==="tool_invocation"){
+      const key=`${part.node}:${event.call_id}`,prior=calls.get(key);
+      if(prior?.recorded)throw Error("duplicate recovery invocation");
+      calls.set(key,{name:event.name,ordinal:prior?.ordinal??ordinal,recorded:true,nested:event.parent_call_id!==undefined,ok:prior?.ok??null});
+    }
+    if(event.t==="tool_result"){
+      const key=`${event.invocation_ref?.node??part.node}:${event.call_id}`,call=calls.get(key);
+      if(!call||call.ok!==null)throw Error("unpaired recovery result");
+      call.ok=event.ok;
+      if(!event.ok){firstFailure=Math.min(firstFailure,ordinal);if(event.diagnostic)classified++;else unclassified++;}
+      if(call.name==="history"&&event.ok&&verifiedRetrievals.has(`${part.node}:${event.id}`))retrieved++;
+    }
+    if(event.t==="claim"&&!resolveEvidence(part.events.slice(0,index),event.evidence).ok)unsupported++;
+    state=advanceRecovery(state,[event],identify);
+    if(event.t==="tool_result"&&!event.ok&&[...state.failures.values()].some(run=>run.count>1&&run.sources.at(-1)===event.id))repeated++;
+  }
+  const rows=[...calls.values()],failed=rows.filter(call=>call.ok===false).length,unresolved=rows.filter(call=>call.ok===null).length;
+  // An invocation record proves the attempt was logged, not that schema or
+  // permission checks admitted its effect. Rejected requests have receipts too.
+  return {toolCalls:rows.length,recordedInvocations:rows.filter(call=>call.recorded).length,outerCalls:rows.filter(call=>!call.nested).length,
+    nestedCalls:rows.filter(call=>call.nested).length,unresolvedCalls:unresolved,toolFailures:failed,firstToolSuccess:rows[0]?.ok??null,
+    firstPassTaskSuccess:finalTaskSuccess===null?null:finalTaskSuccess&&failed===0&&unresolved===0,
+    finalTaskSuccess,recoveryCalls:rows.filter(call=>call.ordinal>firstFailure).length,unchangedFailureRetries:repeated,
+    classifiedFailures:classified,unclassifiedFailures:unclassified,originalEvidenceRetrievals:retrieved,unsupportedClaims:unsupported};
+}
+export function isRecoveryMetrics(value:unknown):value is RecoveryMetrics{
+  if(!value||typeof value!=="object")return false;
+  const v=value as Record<string,unknown>;
+  const numbers=["toolCalls","recordedInvocations","outerCalls","nestedCalls","unresolvedCalls","toolFailures","recoveryCalls","unchangedFailureRetries","classifiedFailures","unclassifiedFailures","originalEvidenceRetrievals","unsupportedClaims"];
+  if(numbers.some(key=>!Number.isSafeInteger(v[key])||Number(v[key])<0))return false;
+  if(["firstToolSuccess","firstPassTaskSuccess","finalTaskSuccess"].some(key=>v[key]!==null&&typeof v[key]!=="boolean"))return false;
+  const n=(key:string)=>Number(v[key]);
+  return n("outerCalls")+n("nestedCalls")===n("toolCalls")&&n("recordedInvocations")<=n("toolCalls")
+    &&n("unresolvedCalls")+n("toolFailures")<=n("toolCalls")&&n("classifiedFailures")+n("unclassifiedFailures")===n("toolFailures")
+    &&n("recoveryCalls")<=n("toolCalls")&&n("unchangedFailureRetries")<=n("toolFailures")&&n("originalEvidenceRetrievals")<=n("toolCalls")-n("toolFailures")-n("unresolvedCalls")
+    &&(v["firstPassTaskSuccess"]!==true||v["finalTaskSuccess"]===true&&n("toolFailures")===0&&n("unresolvedCalls")===0);
+}

package/src/core/recovery-sources.ts

@@ -0,0 +1,74 @@
+/** R9 / D8: navigation into original ancestry, never a semantic summary or permission grant. */
+import type { LogEvent } from "./events.ts";
+import { historyEntries, type HistoryEntry } from "./history-query.ts";
+import { isEnvironmentReceipt } from "./environment.ts";
+import { resourceKey } from "./evidence-links.ts";
+import type { ToolDiagnostic } from "./tool-contract.ts";
+
+export const RECOVERY_SECTIONS = ["users", "failures", "environment", "next_actions"] as const;
+export type RecoverySection = typeof RECOVERY_SECTIONS[number];
+export const RECOVERY_KINDS = { users: "user", failures: "failure", environment: "environment", next_actions: "next_action" } as const;
+export type RecoveryNodes = readonly { node: number; events: readonly LogEvent[] }[];
+export type RecoveryReference = {
+  node: number; event: string; kind: "user" | "failure" | "environment" | "next_action";
+  /** This is the recorded role, not proof of current authorization or human authorship. */
+  provenance: "user_message" | "observation" | "model_annotation";
+  abandoned?: true; tool?: string; work?: string;
+  resources?: readonly string[];
+  /** A failed request can name a resource without having observed it. */
+  requested_resource?: string;
+  diagnostic?: Pick<ToolDiagnostic, "code" | "execution" | "effects">;
+  host?: string; workspace?: string; cwd?: string; program?: string;
+};
+export type RecoverySources = Record<RecoverySection, RecoveryReference[]>;
+export type RecoveryRanges = Record<RecoverySection, { total: number; omitted: number }>;
+
+/** Newest first within each role; no keywords decide which user sentence is a constraint. */
+export function recoverySources(nodes: RecoveryNodes, entries: readonly HistoryEntry[] = historyEntries(nodes)): RecoverySources {
+  const abandoned = new Set(nodes.flatMap(part => part.events.flatMap(event => event.t === "interrupt" ? [event.user_id] : [])));
+  const result: RecoverySources = { users: [], failures: [], environment: [], next_actions: [] };
+  for (const entry of entries.toReversed()) {
+    const source = { node: entry.node, event: entry.event };
+    if (entry.kind === "user") result.users.push({ ...source, kind: "user", provenance: "user_message",
+      ...(abandoned.has(entry.event) ? { abandoned: true } : {}) });
+    if (entry.kind === "next_action") result.next_actions.push({ ...source, kind: "next_action", provenance: "model_annotation",
+      ...(entry.work_ids?.[0] ? { work: entry.work_ids[0] } : {}) });
+    if (entry.kind !== "tool_result") continue;
+    if (entry.ok === false) {
+      const input = entry.input !== null && typeof entry.input === "object" ? entry.input as Record<string, unknown> : {};
+      const requested = typeof input["path"] === "string" ? input["path"] : typeof input["cwd"] === "string" ? input["cwd"] : undefined;
+      const diagnostic = entry.diagnostic;
+      result.failures.push({ ...source, kind: "failure", provenance: "observation", ...(entry.tool ? { tool: entry.tool } : {}),
+        ...(entry.resources?.length ? { resources: entry.resources } : {}),
+        ...(requested ? { requested_resource: resourceKey(requested) } : {}),
+        ...(diagnostic ? { diagnostic: { code: diagnostic.code,
+          ...(diagnostic.execution ? { execution: diagnostic.execution } : {}), ...(diagnostic.effects ? { effects: diagnostic.effects } : {}) } } : {}) });
+    }
+    if (entry.tool === "environment") {
+      const receipt = entry.data;
+      // Only a validated actual receipt contributes identity. Text that looks
+      // like a host or a successful probe does not become a machine fact (D11).
+      const identity = isEnvironmentReceipt(receipt) && entry.effect?.kind === "command" && entry.effect.exit === receipt.evidence.exit
+        ? { host: receipt.source.host, workspace: receipt.source.workspace, cwd: receipt.source.cwd, program: receipt.query.program } : {};
+      result.environment.push({ ...source, kind: "environment", provenance: "observation", ...identity });
+    }
+  }
+  return result;
+}
+
+/** Source labels are stable even when the runtime attaches a fresh validity view. */
+export function recoveryPage(sources: RecoverySources, entries: readonly HistoryEntry[], section: RecoverySection, offset: number, limit: number): {
+  total: number; offset: number; next: number | null; items: { source: RecoveryReference; original: HistoryEntry }[];
+} {
+  if (!Number.isSafeInteger(offset) || offset < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > 100) {
+    throw new RangeError("recovery offset must be nonnegative and limit must be 1..100");
+  }
+  const indexed = new Map(entries.map(entry => [entry.event, entry]));
+  const references = sources[section], end = Math.min(references.length, offset + limit);
+  return { total: references.length, offset, next: end < references.length ? end : null,
+    items: references.slice(offset, end).map(source => {
+      const original = indexed.get(source.event);
+      if (!original || original.node !== source.node) throw new Error("recovery source is absent from the selected ancestry");
+      return { source, original };
+    }) };
+}

package/src/core/runtime-target.ts

@@ -0,0 +1,94 @@
+/** R8: declarations select a target; only an owned runtime observation supplies its identity. */
+import { parseCommandArtifactPlan, validArtifactPath, type CommandArtifactPlan } from "./command-artifacts.ts";
+import type { ArtifactRef } from "./events.ts";
+import { isObservationArtifact } from "./observation-view.ts";
+import type { ProcessSource } from "./process-receipt.ts";
+
+export type RuntimeTarget = { id: string; build: string; artifacts: CommandArtifactPlan; entry: string;
+  interpreter?: string; args?: string[]; workdir?: string; port?: number };
+export type TargetBuild = { node: number; event: string; manifest: ArtifactRef };
+export type RuntimeInstance = { id: string; session: number; pid: number; source: ProcessSource;
+  entry: { path: string; sha256: string }; program: { path: string; sha256: string; device: string; inode: string } };
+export type RuntimeTargetReceipt = {
+  kind: "runtime_target"; version: 1; target: string; request: string; contract_event: string;
+  state: "ready" | "not_ready" | "stale" | "unknown"; reason: string; observed_at: string;
+  source: ProcessSource; build?: TargetBuild; instance?: RuntimeInstance; port?: number;
+  checks: { build: boolean; inputs: boolean; artifacts: boolean; process: boolean; image: boolean; port: boolean | null };
+  manifest?: ArtifactRef;
+};
+export type TargetAcceptance = { id: string; build: string; status: "not_run" | RuntimeTargetReceipt["state"];
+  observation?: string; binding?: string; session?: number; pid?: number; entry?: string; port?: number; build_event?: string; reason?: string };
+
+const record = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
+const id = (value: unknown): value is string => typeof value === "string" && /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,79}$/.test(value);
+const text = (value: unknown): value is string => typeof value === "string" && value.length > 0;
+const digest = (value: unknown): value is string => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+const natural = (value: unknown): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+const source = (value: unknown): value is ProcessSource => record(value) && ["host", "workspace", "cwd", "runtime"].every(key => text(value[key]));
+
+export function parseRuntimeTarget(value: unknown): RuntimeTarget {
+  if (!record(value) || Object.keys(value).some(key => !["id", "build", "artifacts", "entry", "interpreter", "args", "workdir", "port"].includes(key)) ||
+    !id(value["id"]) || !id(value["build"]) || !validArtifactPath(value["entry"])) throw Error("invalid runtime target declaration");
+  const artifacts = parseCommandArtifactPlan(value["artifacts"]);
+  if (!artifacts.paths.includes(value["entry"])) throw Error("target entry must be an observed build artifact");
+  const interpreter = value["interpreter"], args = value["args"], workdir = value["workdir"], port = value["port"];
+  if (interpreter !== undefined && (typeof interpreter !== "string" || !interpreter.startsWith("/") || /[\x00-\x1f\x7f]/.test(interpreter) || interpreter.length > 4096)) throw Error("target interpreter needs an explicit absolute path");
+  // Assumed argv budget prevents declarations from becoming an unbounded prompt or exec payload.
+  if (args !== undefined && (!Array.isArray(args) || args.length > 64 || !args.every(arg => typeof arg === "string" && !arg.includes("\0")) || JSON.stringify(args).length > 8192)) throw Error("target args must be a bounded literal string array");
+  if (workdir !== undefined && workdir !== "." && !validArtifactPath(workdir)) throw Error("target workdir must stay inside the workspace");
+  if (port !== undefined && (!natural(port) || port < 1 || port > 65535)) throw Error("target port must be 1..65535 on IPv4 loopback");
+  return { id: value["id"], build: value["build"], entry: value["entry"], artifacts,
+    ...(interpreter !== undefined ? { interpreter: interpreter as string } : {}), ...(args !== undefined ? { args: [...args as string[]] } : {}),
+    ...(workdir !== undefined ? { workdir: workdir as string } : {}), ...(port !== undefined ? { port: port as number } : {}) };
+}
+
+export function targetIsReady(receipt: Pick<RuntimeTargetReceipt, "build" | "instance" | "checks">): boolean {
+  return receipt.build !== undefined && receipt.instance !== undefined && receipt.checks.build && receipt.checks.inputs && receipt.checks.artifacts &&
+    receipt.checks.process && receipt.checks.image && receipt.checks.port !== false;
+}
+export function isRuntimeTargetReceipt(value: unknown): value is RuntimeTargetReceipt {
+  if (!record(value) || value["kind"] !== "runtime_target" || value["version"] !== 1 || !id(value["target"]) || !text(value["request"]) ||
+    !text(value["contract_event"]) || !text(value["observed_at"]) || !text(value["reason"]) || !source(value["source"]) ||
+    !["ready", "not_ready", "stale", "unknown"].includes(String(value["state"]))) return false;
+  const build = value["build"], instance = value["instance"], checks = value["checks"], port = value["port"];
+  if (build !== undefined && (!record(build) || !natural(build["node"]) || !text(build["event"]) || !isObservationArtifact(build["manifest"]))) return false;
+  if (instance !== undefined && (!record(instance) || !text(instance["id"]) || !natural(instance["session"]) || instance["session"] < 1 ||
+    !natural(instance["pid"]) || instance["pid"] < 1 || !source(instance["source"]) ||
+    !["host", "workspace", "cwd", "runtime"].every(key => (instance["source"] as Record<string, string>)[key] === (value["source"] as Record<string, string>)[key]) ||
+    !record(instance["entry"]) || !text(instance["entry"]["path"]) || !digest(instance["entry"]["sha256"]) ||
+    !record(instance["program"]) || !text(instance["program"]["path"]) || !digest(instance["program"]["sha256"]) ||
+    !text(instance["program"]["device"]) || !text(instance["program"]["inode"]))) return false;
+  if (!record(checks) || !["build", "inputs", "artifacts", "process", "image"].every(key => typeof checks[key] === "boolean") ||
+    !(checks["port"] === null || typeof checks["port"] === "boolean") ||
+    (port === undefined ? checks["port"] !== null : !natural(port) || port < 1 || port > 65535 || checks["port"] === null)) return false;
+  if (value["manifest"] !== undefined && !isObservationArtifact(value["manifest"])) return false;
+  return value["state"] !== "ready" || targetIsReady(value as RuntimeTargetReceipt) && isObservationArtifact(value["manifest"]);
+}
+
+/** lsof -F0 is a field protocol; matching a process name or display substring proves nothing. */
+export function lsofFiles(output: string, pid: number): Record<string, string>[] {
+  let process = -1, file: Record<string, string> | undefined;
+  const files: Record<string, string>[] = [];
+  for (const chunk of output.split("\0")) {
+    const field = chunk.replace(/^\n/, "");
+    if (!field) continue;
+    const key = field[0]!, value = field.slice(1);
+    if (key === "p") { process = Number(value); file = undefined; }
+    else if (key === "f") { file = { f: value }; if (process === pid) files.push(file); }
+    else if (file && process === pid) {
+      if (key === "T") { const split = value.indexOf("="); if (split > 0) file[`T${value.slice(0, split)}`] = value.slice(split + 1); }
+      else file[key] = value;
+    }
+  }
+  return files;
+}
+export function lsofOwnsImage(output: string, pid: number, device: string, inode: string): boolean {
+  return lsofFiles(output, pid).some(file => {
+    if (file["f"] !== "txt" || file["i"] !== inode || !/^0x[0-9a-f]+$/i.test(file["D"] ?? "")) return false;
+    try { return BigInt(file["D"]!) === BigInt(device); } catch { return false; }
+  });
+}
+export function lsofOwnsPort(output: string, pid: number, port: number): boolean {
+  return lsofFiles(output, pid).some(file => file["t"] === "IPv4" && file["P"] === "TCP" && file["TST"] === "LISTEN" &&
+    ["*", "127.0.0.1"].some(host => file["n"] === `${host}:${port}`));
+}