@visual-z/xeno 0.2.1 → 0.4.0

package/src/core/environment.ts

@@ -1,3 +1,6 @@
+import type { ArtifactRef, LogEvent } from "./events.ts";
+import { isObservationArtifact } from "./observation-view.ts";
+
 /**
  * Facts about the machine, fixed at session start.
  *
@@ -27,3 +30,145 @@ export function environmentSection(env: SessionEnvironment): string {
     `- Git repository: ${env.git ? "yes" : "no"}`,
   ].join("\n");
 }
+
+/** R6: these are operational assumptions, not measured freshness guarantees. */
+export const ENVIRONMENT_TTL_MS = 5 * 60_000;
+export const ENVIRONMENT_TIMEOUT_MS = 5_000;
+export const ENVIRONMENT_OUTPUT_BYTES = 256 * 1024;
+export const ENVIRONMENT_PARSE_BYTES = 64 * 1024;
+/** Version reports are metadata; verbose command output remains in the original artifact. */
+export const ENVIRONMENT_VERSION_BYTES = 4096;
+export type EnvironmentProbe = "version" | "python";
+export type EnvironmentSource = { host: string; workspace: string; cwd: string; runtime: string; inherited_sha256: string };
+export type PythonCapability = { executable: string; prefix: string; base_prefix: string; version: string;
+  implementation: string; isolated: true; features: { tarfile_extractall_filter: boolean } };
+export type EnvironmentReceipt = {
+  kind: "environment"; version: 1;
+  query: { program: string; probe: EnvironmentProbe };
+  source: EnvironmentSource;
+  observed_at: number; expires_at: number;
+  state: "observed" | "missing" | "opaque" | "failed" | "unknown";
+  shell: { executable: string; version: string; cwd: string; path_sha256: string } | null;
+  resolution: { kind: string; executable: string | null } | null;
+  reported_version: string | null;
+  python?: PythonCapability;
+  evidence: { output: ArtifactRef; exit: number; complete: boolean };
+  reason?: string;
+};
+
+const quote = (text: string) => "'" + text.replaceAll("'", "'\\''") + "'";
+const marker = "\0XENO_ENVIRONMENT_V1\0";
+const PYTHON_CAPABILITY_PROBE = [
+  "import inspect,json,platform,sys,tarfile",
+  "print(json.dumps({'executable':sys.executable,'prefix':sys.prefix,'base_prefix':sys.base_prefix,'version':platform.python_version(),'implementation':platform.python_implementation(),'isolated':bool(sys.flags.isolated),'features':{'tarfile_extractall_filter':'filter' in inspect.signature(tarfile.TarFile.extractall).parameters}},sort_keys=True))",
+].join(";");
+
+/** Program names are data, including paths with quotes/newlines; no caller code is evaluated. */
+export function environmentProbeCommand(program: unknown, probe: unknown = "version"): string {
+  if (typeof program !== "string" || !program || program.includes("\0") || new TextEncoder().encode(program).length > 4096) throw new Error("program must be a nonempty name or path up to 4096 bytes without NUL");
+  if (probe !== "version" && probe !== "python") throw new Error("probe must be version or python");
+  return [
+    "builtin set +e", `xeno_probe_program=${quote(program)}`,
+    'xeno_probe_kind=$(builtin type -t -- "$xeno_probe_program" 2>/dev/null)',
+    'xeno_probe_path=""',
+    'if [ "$xeno_probe_kind" = file ]; then xeno_probe_path=$(builtin type -P -- "$xeno_probe_program" 2>/dev/null); fi',
+    // A single frame precedes the program output, which remains untrusted data.
+    `builtin printf '\\0XENO_ENVIRONMENT_V1\\0%s\\0%s\\0%s\\0%s\\0%s\\0%s\\0%s\\0%s\\0' "$xeno_probe_program" ${quote(probe)} "$xeno_probe_kind" "$xeno_probe_path" "$BASH" "$BASH_VERSION" "$PWD" "$PATH"`,
+    'if [ -z "$xeno_probe_kind" ]; then builtin exit 127; fi',
+    'if [ "$xeno_probe_kind" != file ] || [ -z "$xeno_probe_path" ]; then builtin exit 125; fi',
+    // Replace the discovery shell: the managed group leader and exit belong
+    // to the probed program, not an extra shell waiting for its child (R1).
+    probe === "python" ? `builtin exec -- "$xeno_probe_path" -I -c ${quote(PYTHON_CAPABILITY_PROBE)}` : 'builtin exec -- "$xeno_probe_path" --version',
+  ].join("\n");
+}
+
+export interface EnvironmentFrame { program: string; probe: EnvironmentProbe; kind: string; executable: string | null;
+  shell: string; shell_version: string; cwd: string; path: string; output: string }
+export function parseEnvironmentFrame(text: string, program: string, probe: EnvironmentProbe): EnvironmentFrame | null {
+  const start = text.indexOf(marker);
+  if (start < 0) return null;
+  const fields: string[] = [];
+  let at = start + marker.length;
+  for (let i = 0; i < 8; i++) {
+    const end = text.indexOf("\0", at);
+    if (end < 0) return null;
+    fields.push(text.slice(at, end)); at = end + 1;
+  }
+  if (fields[0] !== program || fields[1] !== probe || !["", "file", "function", "alias", "builtin", "keyword"].includes(fields[2]!) ||
+    !fields[4] || !fields[5] || !fields[6] || (fields[2] === "file" && !fields[3])) return null;
+  return { program, probe, kind: fields[2]!, executable: fields[3] || null, shell: fields[4]!, shell_version: fields[5]!, cwd: fields[6]!, path: fields[7]!, output: text.slice(at) };
+}
+
+const object = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
+const digest = (value: unknown): value is string => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+const strings = (value: Record<string, unknown>, keys: readonly string[]) => keys.every(key => typeof value[key] === "string" && value[key] !== "");
+export function isPythonCapability(value: unknown): value is PythonCapability {
+  return object(value) && strings(value, ["executable", "prefix", "base_prefix", "version", "implementation"]) && value["isolated"] === true &&
+    object(value["features"]) && typeof value["features"]["tarfile_extractall_filter"] === "boolean";
+}
+
+/** D11: neither a version-looking line nor an interrupted exit zero proves a capability. */
+export function environmentCapability(frame: EnvironmentFrame | null, exit: number, capture: {
+  complete: boolean; stopped?: "cancelled" | "timeout"; limited?: "output" | "parse";
+}): Pick<EnvironmentReceipt, "state" | "reported_version" | "python" | "reason"> {
+  const unknown = (reason: string) => ({ state: "unknown" as const, reported_version: null, reason });
+  if (capture.limited) return unknown(`probe exceeded its ${capture.limited} budget; inspect the original output`);
+  if (capture.stopped) return unknown(`probe ${capture.stopped}; inspect partial effects before continuing`);
+  if (!capture.complete || !frame) return unknown("probe output is incomplete or its environment frame is invalid");
+  if (frame.kind === "" && exit === 127) return { state: "missing", reported_version: null, reason: "program was not found in the command environment" };
+  if (frame.kind !== "file") return { state: "opaque", reported_version: null, reason: "shell resolution is not an executable file; specify its exact path" };
+  if (exit !== 0) return { state: "failed", reported_version: null, reason: "program exited unsuccessfully; a version-like line is not capability evidence" };
+  const output = frame.output.trim();
+  if (!output || new TextEncoder().encode(output).length > ENVIRONMENT_VERSION_BYTES) return unknown("version report is empty or exceeds the metadata budget");
+  if (frame.probe === "version") return { state: "observed", reported_version: output };
+  try {
+    const value: unknown = JSON.parse(output);
+    if (isPythonCapability(value)) return { state: "observed", reported_version: value.version, python: value };
+  } catch { /* The complete untrusted report remains available in the artifact. */ }
+  return unknown("Python did not return a valid isolated capability report");
+}
+export function isEnvironmentReceipt(value: unknown): value is EnvironmentReceipt {
+  if (!object(value) || value["kind"] !== "environment" || value["version"] !== 1 || !object(value["query"]) ||
+    !strings(value["query"], ["program"]) || !["version", "python"].includes(String(value["query"]["probe"]))) return false;
+  const source = value["source"], evidence = value["evidence"], shell = value["shell"], resolution = value["resolution"];
+  if (!object(source) || !strings(source, ["host", "workspace", "cwd", "runtime"]) || !digest(source["inherited_sha256"]) ||
+    !object(evidence) || !isObservationArtifact(evidence["output"]) || !Number.isInteger(evidence["exit"]) || typeof evidence["complete"] !== "boolean") return false;
+  const observed = value["observed_at"], expires = value["expires_at"];
+  if (typeof observed !== "number" || !Number.isSafeInteger(observed) || observed < 0 || expires !== observed + ENVIRONMENT_TTL_MS ||
+    !["observed", "missing", "opaque", "failed", "unknown"].includes(String(value["state"])) ||
+    !(value["reported_version"] === null || typeof value["reported_version"] === "string") ||
+    !(value["reason"] === undefined || typeof value["reason"] === "string")) return false;
+  if (shell !== null && (!object(shell) || !strings(shell, ["executable", "version", "cwd"]) || !digest(shell["path_sha256"]))) return false;
+  if (resolution !== null && (!object(resolution) || typeof resolution["kind"] !== "string" ||
+    !(resolution["executable"] === null || typeof resolution["executable"] === "string"))) return false;
+  if (value["python"] !== undefined && !isPythonCapability(value["python"])) return false;
+  if (value["state"] === "observed" && (evidence["exit"] !== 0 || !evidence["complete"] || !object(shell) || !object(resolution) ||
+    resolution["kind"] !== "file" || !resolution["executable"] || !value["reported_version"] ||
+    value["query"]["probe"] === "python" && value["python"] === undefined)) return false;
+  return true;
+}
+
+export type EnvironmentValidity = { state: "recorded" | "expired" | "scope_changed" | "invalidated" | "unconfirmed";
+  reason: string; event?: string };
+/** Recomputed on consumption: recent observations are never guarantees about a future invocation. */
+export function environmentValidity(receipt: EnvironmentReceipt, source: EnvironmentSource, now: number, after: readonly LogEvent[]): EnvironmentValidity {
+  for (const event of after) {
+    if (event.t === "user_bash" || event.t === "snapshot" &&
+      (Object.keys(event.added).length > 0 || Object.keys(event.changed).length > 0 || event.removed.length > 0)) {
+      return { state: "invalidated", reason: "later command or workspace change requires environment revalidation", event: event.id };
+    }
+    if (event.t !== "tool_result") continue;
+    if (isEnvironmentReceipt(event.data) && event.data.query.program === receipt.query.program && event.data.query.probe === receipt.query.probe) {
+      return { state: "invalidated", reason: "a later probe supersedes this observation, including a failed probe", event: event.id };
+    }
+    if (event.effect?.kind === "edit" || event.effect?.kind === "command" || event.diagnostic?.code === "environment_missing" ||
+      event.diagnostic?.effects === "possible" && event.diagnostic.execution !== "not_started") {
+      return { state: "invalidated", reason: "later execution or mutation requires environment revalidation", event: event.id };
+    }
+  }
+  const keys: readonly (keyof EnvironmentSource)[] = ["host", "workspace", "cwd", "runtime", "inherited_sha256"];
+  if (keys.some(key => source[key] !== receipt.source[key])) return { state: "scope_changed", reason: "host, workspace, directory, runtime, or inherited environment changed" };
+  if (!Number.isFinite(now) || now < receipt.observed_at || now >= receipt.expires_at) return { state: "expired", reason: "observation time is outside its validity interval" };
+  if (receipt.state !== "observed") return { state: "unconfirmed", reason: "the probe did not establish this capability" };
+  return { state: "recorded", reason: "recent observation only; login startup files or external changes may require another probe" };
+}

package/src/core/evaluation-coverage.ts

@@ -0,0 +1,74 @@
+/** R12c: missing final rows cannot erase attempted work or measured charges. */
+import type { EvalJob, EvalResult } from "./experiment.ts";
+import { recoveryCase } from "./recovery-corpus.ts";
+import { TOOL_MODE_FACTORS, isToolModeTask, isToolModeMetrics } from "./tool-mode-protocol.ts";
+
+export interface BillingRecord {
+  kind: "reserved" | "settled"; request: number; inputSha256: string;
+  reservation: number; charge: number; measured: number | null; ledgerCharged: number;
+}
+export function requestAccounting(records: readonly BillingRecord[], before: number) {
+  const nonnegative = (n: unknown): n is number => typeof n === "number" && Number.isFinite(n) && n >= 0;
+  if (!nonnegative(before)) throw Error("invalid trial ledger start");
+  let charged = before, pending: BillingRecord | undefined, requests = 0, known = 0, unknown = 0;
+  for (const row of records) {
+    if (![row.reservation, row.charge, row.ledgerCharged].every(nonnegative) || row.measured !== null && !nonnegative(row.measured) ||
+        !Number.isSafeInteger(row.request) || row.request < 1 || !/^[a-f0-9]{64}$/.test(row.inputSha256)) throw Error("invalid billing record");
+    if (row.kind === "reserved") {
+      if (pending || row.request !== ++requests || row.measured !== null || row.charge !== row.reservation) throw Error("invalid reservation order");
+      pending = row; charged += row.reservation;
+    } else if (row.kind === "settled") {
+      if (!pending || row.request !== pending.request || row.inputSha256 !== pending.inputSha256 || row.reservation !== pending.reservation ||
+          row.charge !== (row.measured ?? row.reservation)) throw Error("invalid settlement identity");
+      charged += row.charge - pending.reservation;
+      if (row.measured === null) unknown += row.reservation; else known += row.measured;
+      pending = undefined;
+    } else throw Error("invalid billing record kind");
+    if (row.ledgerCharged !== charged) throw Error("billing ledger sequence changed");
+  }
+  return { requests, charged, knownCostSubtotal: known, unsettledRequests: pending ? 1 : 0,
+    unsettledReservation: pending?.reservation ?? 0, unknownSettlementReserve: unknown,
+    fullyMeasured: !pending && records.filter(row => row.kind === "settled").every(row => row.measured !== null) };
+}
+export type RequestAccounting = ReturnType<typeof requestAccounting>;
+export type TrialCoverage = { id: string; accounting: RequestAccounting; tail: "complete" | "truncated";
+  result?: EvalResult; interruption: "deadline" | "caller" | null; partialMetrics?: EvalResult["recovery"] };
+
+export function summarizeRecoveryCoverage(jobs: readonly EvalJob[], trials: readonly TrialCoverage[], mechanical: boolean) {
+  const ids = new Set(jobs.map(job => job.id)), byId = new Map(trials.map(trial => [trial.id, trial]));
+  if (ids.size !== jobs.length || byId.size !== trials.length || trials.some(trial => !ids.has(trial.id) || trial.result && trial.result.id !== trial.id)) throw Error("invalid recovery coverage identities");
+  const group = (selected: readonly EvalJob[]) => {
+    const rows = selected.flatMap(job => byId.has(job.id) ? [byId.get(job.id)!] : []), finalized = rows.filter(row => row.result);
+    const passed = finalized.filter(row => row.result!.scenarioPassed).length;
+    const unknown = rows.filter(row => !row.result || row.tail !== "complete" || !row.accounting.fullyMeasured).length;
+    const known = rows.reduce((n, row) => n + row.accounting.knownCostSubtotal, 0);
+    const cost = !mechanical && rows.length === selected.length && unknown === 0 ? known : null;
+    const metrics = rows.flatMap(row => row.result?.recovery ?? row.partialMetrics ?? []);
+    const modes = finalized.flatMap(row => row.result?.toolMode ?? []);
+    if (modes.some(mode => !isToolModeMetrics(mode))) throw Error("invalid tool mode measurements");
+    const toolMode = selected.some(job => isToolModeTask(job.task)) ? { observed: modes.length, missing: selected.length - modes.length,
+      queryCalls: modes.reduce((n, mode) => n + mode.queryCalls, 0),
+      primitiveCalls: modes.reduce((n, mode) => n + mode.primitiveCalls, 0), sourcesComplete: modes.filter(mode => mode.sourceComplete).length,
+      meanElapsedMs: modes.length === selected.length && modes.length > 0 ? modes.reduce((n, mode) => n + mode.elapsedMs, 0) / modes.length : null } : undefined;
+    return { ...(toolMode ? { toolMode } : {}), planned: selected.length, attempted: rows.length, finalized: finalized.length, incomplete: rows.length - finalized.length,
+      unattempted: selected.length - rows.length, failed: finalized.length - passed, passed, plannedPassFraction: selected.length ? passed / selected.length : null,
+      cancelled: rows.filter(row => row.interruption === "caller").length, timedOut: rows.filter(row => row.interruption === "deadline").length,
+      requests: rows.reduce((n, row) => n + row.accounting.requests, 0), truncatedRequestLogs: rows.filter(row => row.tail === "truncated").length,
+      knownCostSubtotal: mechanical ? null : known, costUsd: cost,
+      unsettledRequests: rows.reduce((n, row) => n + row.accounting.unsettledRequests, 0),
+      unsettledReservationUsd: mechanical ? null : rows.reduce((n, row) => n + row.accounting.unsettledReservation, 0),
+      unknownSettlementReserveUsd: mechanical ? null : rows.reduce((n, row) => n + row.accounting.unknownSettlementReserve, 0),
+      unknownCostTrials: mechanical ? rows.length : unknown, costPerScenarioSuccess: cost !== null && passed > 0 ? cost / passed : null,
+      unverifiedEndings: finalized.filter(row => row.result!.unverifiedEnding).length,
+      recovery: { observed: metrics.length, missing: selected.length - metrics.length,
+        firstToolSuccess: metrics.filter(row => row.firstToolSuccess === true).length,
+        firstToolUnknown: metrics.filter(row => row.firstToolSuccess === null).length,
+        firstPassTaskSuccess: metrics.filter(row => row.firstPassTaskSuccess === true).length,
+        ...Object.fromEntries((["toolCalls", "outerCalls", "nestedCalls", "unresolvedCalls", "toolFailures", "classifiedFailures", "unclassifiedFailures", "recoveryCalls", "unchangedFailureRetries", "originalEvidenceRetrievals", "unsupportedClaims"] as const)
+          .map(key => [key, metrics.reduce((n, row) => n + row[key], 0)])) } };
+  };
+  const toolModes = jobs.some(job => isToolModeTask(job.task));
+  return { ...group(jobs), arms: (toolModes ? TOOL_MODE_FACTORS : ["profile", "workingSet", "strictVerification"]).flatMap(factor => ["control", "treatment"].map(arm =>
+    ({ factor, arm, ...group(jobs.filter(job => job.factor === factor && job.arm === arm)) }))),
+    partitions: toolModes ? [] : ["development", "holdout"].map(partition => ({ partition, ...group(jobs.filter(job => recoveryCase(job.task)?.partition === partition)) })) };
+}

package/src/core/event-validation.ts

@@ -3,6 +3,14 @@ import type { LogEvent, NodeRef } from "./events.ts";
 import { isExecutionOutcome } from "./outcome.ts";
 import { isJsonValue, isToolDiagnostic } from "./tool-contract.ts";
 import { validImageRef } from "./images.ts";
+import { parseAcceptanceContract } from "./acceptance.ts";
+import { validFileChanges } from "./checkpoints.ts";
+import { isObservationReceipt } from "./read-observation.ts";
+import { isSearchReceipt } from "./search-observation.ts";
+import { isProcessReceipt } from "./process-receipt.ts";
+import { isObservationArtifact } from "./observation-view.ts";
+import { isCommandArtifactReceipt } from "./command-artifacts.ts";
+import { isRuntimeTargetReceipt } from "./runtime-target.ts";
 
 export function isRecord(value: unknown): value is Record<string, unknown> {
   return value !== null && typeof value === "object" && !Array.isArray(value);
@@ -11,6 +19,7 @@ const strings = (value: unknown): boolean => Array.isArray(value) && value.every
 const stringMap = (value: unknown): boolean => isRecord(value) && Object.values(value).every((v) => typeof v === "string");
 const optionalString = (value: unknown): boolean => value === undefined || typeof value === "string";
 const natural = (value: unknown): boolean => Number.isSafeInteger(value) && Number(value) >= 0;
+const eventRef = (value: unknown): boolean => isRecord(value) && natural(value["node"]) && typeof value["event"] === "string" && value["event"] !== "";
 export function validNodeRef(value: unknown): value is NodeRef {
   return isRecord(value) && Number.isSafeInteger(value["node"]) && Number(value["node"]) >= 0 &&
     typeof value["log_ref"] === "string" && typeof value["sha256"] === "string" &&
@@ -27,8 +36,39 @@ export function isLogEvent(value: unknown): value is LogEvent {
   const images = value["images"];
   if (images !== undefined && (!Array.isArray(images) || !images.every(validImageRef))) return false;
   switch (value["t"]) {
+    case "tool_invocation": return has("call_id", "name") && value["call_id"] !== "" && value["name"] !== "" &&
+      (value["origin"] === undefined || value["origin"] === "extension") &&
+      isObservationArtifact(value["input_ref"]) && (value["schema_ref"] === null || isObservationArtifact(value["schema_ref"])) &&
+      (value["input"] === undefined || isJsonValue(value["input"])) && optionalString(value["parent_call_id"]) &&
+      (value["parent_ref"] === undefined ? value["parent_call_id"] === undefined : eventRef(value["parent_ref"]) && value["parent_call_id"] !== undefined) &&
+      value["parent_call_id"] !== "" && value["parent_call_id"] !== value["call_id"];
+    case "checkpoint": return has("operation") && ["edit", "git", "restore"].includes(String(value["source"])) &&
+      ["prepared", "applied", "unavailable"].includes(String(value["phase"])) && validFileChanges(value["changes"]) &&
+      optionalString(value["tree"]) && optionalString(value["reason"]);
+    case "workspace_observation": return value["scope"] === "source-v1" && typeof value["changed"] === "boolean" && optionalString(value["reason"]) &&
+      (value["fingerprint"] === undefined || typeof value["fingerprint"] === "string" && /^[a-f0-9]{64}$/.test(value["fingerprint"]));
+    case "process_exit": {
+      const output = value["output"];
+      const receipt = value["receipt"];
+      if (receipt !== undefined && (!isProcessReceipt(receipt) || receipt.replayed || receipt.running !== false ||
+        receipt.session_id !== value["session"] || receipt.exit !== value["exit"] || !isRecord(output) ||
+        receipt.artifacts !== undefined && receipt.artifacts.command !== value["command"] ||
+        receipt.output === undefined || receipt.output.sha256 !== output["sha256"] || receipt.output.bytes !== output["bytes"])) return false;
+      return has("command") && natural(value["session"]) && Number(value["session"]) > 0 && Number.isInteger(value["exit"]) &&
+        value["reason"] === "disposed" && isRecord(output) && typeof output["path"] === "string" &&
+        typeof output["sha256"] === "string" && /^[a-f0-9]{64}$/.test(output["sha256"]) && natural(output["bytes"]);
+    }
+    case "skill_loaded": return has("name", "path", "sha256", "artifact") &&
+      ["sha256", "artifact"].every(key => /^[a-f0-9]{64}$/.test(String(value[key]))) &&
+      ["inline", "fork", "read"].includes(String(value["mode"])) && ["user", "model"].includes(String(value["origin"]));
+    case "acceptance_contract": {
+      try { parseAcceptanceContract(value["contract"]); return has("request"); } catch { return false; }
+    }
+    case "acceptance_decision": return has("request", "contract_id", "criterion") && value["actor"] === "user" &&
+      (value["target_binding"] === undefined ? value["target_observation"] === undefined : has("target_binding", "target_observation"));
+    case "target_observation": return isRuntimeTargetReceipt(value["observation"]);
     case "extension": return has("customType", "content") && typeof value["display"] === "boolean" && typeof value["inContext"] === "boolean" && (value["data"] === undefined || isJsonValue(value["data"]));
-    case "user": return has("text");
+    case "user": return has("text") && (value["request"] === undefined || typeof value["request"] === "string" && value["request"] !== "");
     case "outcome": return has("reason") && isExecutionOutcome(value["outcome"]);
     case "user_bash": {
       const ref = value["content_ref"];
@@ -40,7 +80,7 @@ export function isLogEvent(value: unknown): value is LogEvent {
         isRecord(ref) && typeof ref["sha256"] === "string" &&
         typeof ref["path"] === "string" && natural(ref["bytes"]);
     }
-    case "guidance": return has("text") && ["continuation", "repetition", "budget", "boundary", "stall", "output_recovery", "completion_review", "churn", "deadline"].includes(String(value["reason"])) && strings(value["sources"]);
+    case "guidance": return has("text") && ["continuation", "repetition", "budget", "boundary", "stall", "output_recovery", "completion_review", "churn", "deadline", "runtime_acceptance"].includes(String(value["reason"])) && strings(value["sources"]);
     case "interrupt": return has("user_id");
     case "assistant": return (value["stop_reason"] === null || optionalString(value["stop_reason"])) &&
       (value["replay_key"] === undefined || typeof value["replay_key"] === "string" && /^[a-f0-9]{64}$/.test(value["replay_key"])) &&
@@ -51,8 +91,34 @@ export function isLogEvent(value: unknown): value is LogEvent {
       return b["type"] === "tool_use" && typeof b["call_id"] === "string" && typeof b["name"] === "string" && "input" in b;
     });
     case "tool_result": {
+      if (!optionalString(value["parent_call_id"]) || value["parent_call_id"] === "" || value["parent_call_id"] === value["call_id"]) return false;
+      if (value["origin"] !== undefined && value["origin"] !== "extension") return false;
+      if (value["invocation_ref"] !== undefined && !eventRef(value["invocation_ref"])) return false;
+      const observation = value["observation"];
+      if (observation !== undefined && (!isObservationReceipt(observation) ||
+        !isRecord(value["content_ref"]) || value["content_ref"]["sha256"] !== observation.artifact.sha256 ||
+        value["content_ref"]["bytes"] !== observation.artifact.bytes || value["content_sha256"] !== observation.artifact.sha256)) return false;
       if (value["data"] !== undefined && !isJsonValue(value["data"])) return false;
+      if (value["data_ref"] !== undefined && (!isObservationArtifact(value["data_ref"]) || value["data"] !== undefined)) return false;
+      if (isRecord(value["data"]) && value["data"]["kind"] === "process") {
+        const process = value["data"];
+        if (!isProcessReceipt(process)) return false;
+        if (process.output && (!isRecord(value["content_ref"]) || value["content_ref"]["sha256"] !== process.output.sha256 ||
+          value["content_ref"]["bytes"] !== process.output.bytes || value["content_sha256"] !== process.output.sha256)) return false;
+        if (process.replayed && value["effect"] !== undefined) return false;
+        if (value["effect"] !== undefined && (!isRecord(value["effect"]) || value["effect"]["kind"] !== "command" ||
+          process.running !== false || value["effect"]["exit"] !== process.exit ||
+          JSON.stringify(value["effect"]["artifacts"]) !== JSON.stringify(process.artifacts))) return false;
+      }
+      if (isObservationReceipt(observation) && observation.descriptor !== undefined &&
+        (!isRecord(value["data"]) || value["data"]["read_handle"] !== observation.descriptor.sha256)) return false;
+      if (isRecord(value["data"]) && value["data"]["kind"] === "search") {
+        const search = value["data"];
+        if (!isSearchReceipt(search) || !isRecord(value["content_ref"]) || value["content_ref"]["sha256"] !== search.artifact.sha256 ||
+          value["content_ref"]["bytes"] !== search.artifact.bytes || value["content_sha256"] !== search.artifact.sha256) return false;
+      }
       if (value["diagnostic"] !== undefined && !isToolDiagnostic(value["diagnostic"])) return false;
+      if (value["warnings"] !== undefined && (!Array.isArray(value["warnings"]) || !value["warnings"].every(isToolDiagnostic))) return false;
       if (!has("call_id", "content") || typeof value["ok"] !== "boolean") return false;
       if (!optionalString(value["content_sha256"])) return false;
       if (!optionalString(value["observation_sha256"])) return false;
@@ -63,14 +129,19 @@ export function isLogEvent(value: unknown): value is LogEvent {
       if (effect === undefined) return true;
       if (!isRecord(effect)) return false;
       if (effect["kind"] === "command") return typeof effect["cmd"] === "string" && Number.isInteger(effect["exit"]) &&
-        optionalString(effect["gate"]) && optionalString(effect["workspace_sha256"]);
+        optionalString(effect["gate"]) && optionalString(effect["workspace_sha256"]) &&
+        (effect["artifacts"] === undefined || isCommandArtifactReceipt(effect["artifacts"]) &&
+          effect["artifacts"].exit === effect["exit"] && effect["artifacts"].command === effect["cmd"]) &&
+        (effect["workspace_scope"] === undefined || effect["workspace_scope"] === "source-v1") &&
+        (effect["workspace_observed"] === undefined || typeof effect["workspace_observed"] === "boolean");
       if (effect["kind"] === "read") return typeof effect["path"] === "string" && typeof effect["sha256"] === "string" &&
         (effect["ranges"] === undefined || (Array.isArray(effect["ranges"]) && effect["ranges"].every((r: unknown) =>
           Array.isArray(r) && r.length === 2 && r.every((n) => Number.isSafeInteger(n)) && r[0] >= 1 && r[1] >= r[0])));
       return effect["kind"] === "edit" && typeof effect["path"] === "string" && typeof effect["sha256_after"] === "string" &&
         (effect["sha256_before"] === null || typeof effect["sha256_before"] === "string");
     }
-    case "cut": return has("handoff_ref") && ["trigger", "hard_limit", "model_checkpoint"].includes(String(value["reason"])) &&
+    case "cut": return has("handoff_ref") && (value["working_set_version"] === undefined || value["working_set_version"] === 1 || value["working_set_version"] === 2) && ["trigger", "hard_limit", "model_checkpoint"].includes(String(value["reason"])) &&
+      (value["guidance_tools"] === undefined || Array.isArray(value["guidance_tools"]) && value["guidance_tools"].every(item => typeof item === "string")) &&
       optionalString(value["retained_from"]) && optionalString(value["next_context_ref"]) &&
       (value["next_node"] === undefined || natural(value["next_node"])) && optionalString(value["next_model"]) &&
       (value["handoff_tokens"] === undefined || (typeof value["handoff_tokens"] === "number" && Number.isFinite(value["handoff_tokens"]) && value["handoff_tokens"] > 0)) &&
@@ -83,7 +154,9 @@ export function isLogEvent(value: unknown): value is LogEvent {
     case "pitfall": return has("tried", "failed_because");
     case "blocked": return has("what", "reason");
     case "question": return has("text");
-    case "next_action": return has("what", "next_action");
+    case "next_action": return has("what", "next_action") && (value["depends_on"] === undefined || strings(value["depends_on"]));
+    case "work_dependencies": return has("work_id", "what") && strings(value["depends_on"]);
+    case "work_owner": return has("work_id", "what", "owner") && ["claim", "release"].includes(String(value["operation"]));
     case "evidence_link": return has("work", "what", "source") && optionalString(value["resource"]) && optionalString(value["version"]) &&
       optionalString(value["supersedes"]) && (value["observed_version"] === null || optionalString(value["observed_version"]));
     case "work_status": return has("work_id", "what") && ["unblock", "reopen", "cancel"].includes(String(value["operation"])) &&
@@ -93,6 +166,7 @@ export function isLogEvent(value: unknown): value is LogEvent {
       strings(value["undeclared"]) && strings(value["declared_but_unchanged"]) && optionalString(value["workspace_sha256"]) &&
       (value["phase"] === undefined || value["phase"] === "turn" || value["phase"] === "idle");
     case "rewind": return ["both", "files", "context"].includes(String(value["mode"])) && validNodeRef(value["from"]) &&
+      (value["files_from"] === undefined || validNodeRef(value["files_from"])) &&
       has("prompt") && strings(value["restored"]) && strings(value["removed"]) && strings(value["unrecoverable"]) && strings(value["divergence"]);
     case "spawn": {
       const input = value["input"];
@@ -103,10 +177,11 @@ export function isLogEvent(value: unknown): value is LogEvent {
         if (!(workspace["kind"] === "shared_readonly" || (workspace["kind"] === "git_tree" &&
             typeof workspace["head"] === "string" && typeof workspace["tree"] === "string"))) return false;
       }
-      return validNodeRef(value["branch"]) && has("purpose") && (value["workspace"] === undefined ||
+      return (value["background"] === undefined || value["background"] === true) && validNodeRef(value["branch"]) && has("purpose") && (value["workspace"] === undefined ||
       (isRecord(value["workspace"]) && typeof value["workspace"]["path"] === "string" && typeof value["workspace"]["branch"] === "string"));
     }
     case "joined": return validNodeRef(value["branch"]) && has("handoff_ref", "summary") && optionalString(value["model"]) &&
+      (value["receipt_ref"] === undefined || typeof value["receipt_ref"] === "string" && /^[a-f0-9]{64}$/.test(value["receipt_ref"])) &&
       (value["tip"] === undefined || validNodeRef(value["tip"]));
     case "adopt": return validNodeRef(value["branch"]) && (value["next_node"] === undefined || natural(value["next_node"])) &&
       (value["applied"] === undefined || value["applied"] === true);

package/src/core/events.ts

@@ -21,6 +21,11 @@
 import type { ExecutionOutcome } from "./outcome.ts";
 import type { ImageRef } from "./images.ts";
 import type { JsonValue, ToolDiagnostic } from "./tool-contract.ts";
+import type { AcceptanceContract } from "./acceptance.ts";
+import type { CheckpointEvent, WorkspaceObservationEvent } from "./checkpoints.ts";
+import type { ObservationReceipt } from "./read-observation.ts";
+import type { CommandArtifactReceipt } from "./command-artifacts.ts";
+import type { RuntimeTargetReceipt } from "./runtime-target.ts";
 
 export type EventId = string;
 export type Sha256 = string;
@@ -68,7 +73,7 @@ export type NodeRef = {
 export type Effect =
   | { kind: "read"; path: string; sha256: Sha256; ranges?: readonly LineRange[] }
   | { kind: "edit"; path: string; sha256_before: Sha256 | null; sha256_after: Sha256 }
-  | { kind: "command"; cmd: string; exit: number; gate?: string; workspace_sha256?: Sha256 };
+  | { kind: "command"; cmd: string; exit: number; gate?: string; workspace_sha256?: Sha256; workspace_observed?: boolean; workspace_scope?: "source-v1"; artifacts?: CommandArtifactReceipt };
 
 // ---------------------------------------------------------------------------
 // Harness-derived events
@@ -79,6 +84,8 @@ export interface UserEvent {
   id: EventId;
   at: IsoTime;
   text: string;
+  /** Q23: in-flight steering belongs to this original user event; legacy events open a request. */
+  request?: EventId;
   images?: readonly ImageRef[];
 }
 
@@ -109,7 +116,7 @@ export interface GuidanceEvent {
   t: "guidance";
   id: EventId;
   at: IsoTime;
-  reason: "continuation" | "repetition" | "budget" | "boundary" | "stall" | "output_recovery" | "completion_review" | "churn" | "deadline";
+  reason: "continuation" | "repetition" | "budget" | "boundary" | "stall" | "output_recovery" | "completion_review" | "churn" | "deadline" | "runtime_acceptance";
   text: string;
   sources: readonly EventId[];
 }
@@ -167,6 +174,11 @@ export interface ToolResultEvent {
   id: EventId;
   at: IsoTime;
   call_id: string;
+  /** Trusted host execution has no provider tool_use and is excluded from provider replay. */
+  origin?: "extension";
+  /** Pi A: nested observations remain evidence without creating provider-visible tool pairs. */
+  parent_call_id?: string;
+  invocation_ref?: { node: number; event: EventId };
   ok: boolean;
   /** What the model sees. Large payloads belong on disk, referenced by effect. */
   content: string;
@@ -175,17 +187,36 @@ export interface ToolResultEvent {
   content_sha256?: Sha256;
   /** O.3: semantic observation digest excludes presentation metadata. */
   observation_sha256?: Sha256;
+  /** R2: exact preview coverage and immutable source identity; old logs omit this receipt. */
+  observation?: ObservationReceipt;
   content_ref?: ArtifactRef;
   effect?: Effect;
   /** O.1: actual termination, independent of effect/verification; legacy logs omit it. */
   outcome?: ExecutionOutcome;
   /** O.3: machine-readable observations and recovery hints, not additional proof. */
   data?: JsonValue;
+  /** Pi A: large structured results stay recoverable without bloating each JSONL event. */
+  data_ref?: ArtifactRef;
   diagnostic?: ToolDiagnostic;
+  /** Post-operation observer failures cannot erase the operation's factual result. */
+  warnings?: readonly ToolDiagnostic[];
 }
 
 export type ArtifactRef = { sha256: Sha256; path: string; bytes: number };
 
+/** Pi A: an invocation is durable before its admitted action may start. */
+export interface ToolInvocationEvent {
+  t: "tool_invocation"; id: EventId; at: IsoTime;
+  call_id: string; name: string; parent_call_id?: string;
+  origin?: "extension";
+  parent_ref?: { node: number; event: EventId };
+  /** Original request and the exact declarative contract are independently recoverable. */
+  input_ref: ArtifactRef;
+  schema_ref: ArtifactRef | null;
+  /** Bounded actual arguments; absent for a direct unchanged request or an oversized refusal. */
+  input?: JsonValue;
+}
+
 /** Terminates the segment it appears in. Carries refs only -- see rule 1 above. */
 export interface CutEvent {
   t: "cut";
@@ -205,6 +236,10 @@ export interface CutEvent {
   next_context_ref?: Sha256;
   /** V2 carried-state budget, fixed in the log for identical replay. */
   handoff_tokens?: number;
+  /** O.10: absent preserves the original D20 carried projection. */
+  working_set_version?: 1 | 2;
+  /** R10: declared builtin advice capabilities at this cut, not an authorization grant. Absent replays old text. */
+  guidance_tools?: readonly string[];
   /** N.8: first retained event on the effective ancestry; no copied transcript. */
   retained_from?: EventId;
 }
@@ -242,6 +277,7 @@ export interface DecisionEvent {
   chose: string;
   because: string;
   rejected?: readonly string[];
+  work_id?: string;
   /** Set when an adopt moved this event from another node. */
   carried_from?: CarriedFrom;
 }
@@ -252,6 +288,7 @@ export interface PitfallEvent {
   at: IsoTime;
   tried: string;
   failed_because: string;
+  work_id?: string;
   /** Set when an adopt moved this event from another node. */
   carried_from?: CarriedFrom;
 }
@@ -340,6 +377,8 @@ export interface RewindEvent {
   id: EventId;
   at: IsoTime;
   mode: RewindMode;
+  /** P.3: context navigation keeps the file history at this separate cursor. */
+  files_from?: NodeRef;
   /** Where things were moved back to. */
   from: NodeRef;
   /** The prompt that opened the exchange moved back to, for a human reader. */
@@ -368,6 +407,8 @@ export interface SpawnEvent {
   branch: NodeRef;
   /** What the branch is for, in one line. */
   purpose: string;
+  /** O.14: execution mode is durable; it never proves a live handle exists. */
+  background?: true;
   /** The isolated checkout belongs to this branch, including after restart. */
   workspace?: { path: string; branch: string };
   /** O.4: a task input envelope references the original request, never copies history. */
@@ -393,6 +434,8 @@ export interface JoinedEvent {
   branch: NodeRef;
   handoff_ref: string;
   summary: string;
+  /** O.9: artifact contains a deterministic evidence index, never raw history. */
+  receipt_ref?: Sha256;
   /** A branch can cut before joining; its last node need not be its root. */
   tip?: NodeRef;
   model?: string;
@@ -445,6 +488,7 @@ export interface NextActionEvent {
   what: string;
   work_id?: string;
   next_action: string;
+  depends_on?: readonly string[];
   /** Set when an adopt moved this event from another node. */
   carried_from?: CarriedFrom;
 }
@@ -462,6 +506,15 @@ export interface WorkStatusEvent {
   carried_from?: CarriedFrom;
 }
 
+export interface WorkDependenciesEvent {
+  t: "work_dependencies"; id: EventId; at: IsoTime; work_id: string; what: string;
+  depends_on: readonly string[]; carried_from?: CarriedFrom;
+}
+export interface WorkOwnerEvent {
+  t: "work_owner"; id: EventId; at: IsoTime; work_id: string; what: string;
+  operation: "claim" | "release"; owner: string; carried_from?: CarriedFrom;
+}
+
 /** O.6: a model associates an original observation with work; the runtime resolves its source. */
 export interface EvidenceLinkEvent {
   t: "evidence_link"; id: EventId; at: IsoTime;
@@ -479,7 +532,38 @@ export interface ExtensionEvent {
   data?: import("./tool-contract.ts").JsonValue;
 }
 
+export interface AcceptanceContractEvent {
+  t: "acceptance_contract"; id: EventId; at: IsoTime; request: EventId;
+  contract: AcceptanceContract;
+}
+export interface AcceptanceDecisionEvent {
+  t: "acceptance_decision"; id: EventId; at: IsoTime; request: EventId;
+  contract_id: string; criterion: string; actor: "user";
+  target_binding?: string; target_observation?: EventId;
+}
+export interface TargetObservationEvent {
+  t: "target_observation"; id: EventId; at: IsoTime; observation: RuntimeTargetReceipt;
+}
+
+export interface SkillLoadedEvent {
+  t: "skill_loaded"; id: EventId; at: IsoTime; name: string; path: string;
+  sha256: Sha256; artifact: Sha256; mode: "inline" | "fork" | "read"; origin: "user" | "model";
+}
+
+/** O.14: owner cleanup is an actual process observation, not a model claim. */
+export interface ProcessExitEvent {
+  t: "process_exit"; id: EventId; at: IsoTime; session: number;
+  command: string; exit: number; output: ArtifactRef; reason: "disposed";
+  receipt?: import("./process-receipt.ts").ProcessReceipt;
+}
+
 export type LogEvent =
+  | ToolInvocationEvent
+  | ProcessExitEvent
+  | SkillLoadedEvent
+  | AcceptanceContractEvent
+  | AcceptanceDecisionEvent
+  | TargetObservationEvent
   | ExtensionEvent
   | UserEvent
   | UserBashEvent
@@ -491,6 +575,8 @@ export type LogEvent =
   | EvidenceLinkEvent
   | CutEvent
   | SnapshotEvent
+  | CheckpointEvent
+  | WorkspaceObservationEvent
   | RewindEvent
   | SpawnEvent
   | JoinedEvent
@@ -502,12 +588,21 @@ export type LogEvent =
   | BlockedEvent
   | QuestionEvent
   | NextActionEvent
-  | WorkStatusEvent;
+  | WorkStatusEvent
+  | WorkDependenciesEvent
+  | WorkOwnerEvent;
+// Work coordination is intent, never a substitute for command proof.
 
 export const HARNESS_EVENTS = [
+  "checkpoint", "workspace_observation",
+  "target_observation",
+  "process_exit",
+  "skill_loaded",
+  "acceptance_contract", "acceptance_decision",
   "user", "user_bash", "outcome", "guidance", "interrupt", "assistant", "tool_result", "cut", "snapshot", "rewind", "extension",
 ] as const;
 export const MODEL_EVENTS = [
+  "work_dependencies", "work_owner",
   "claim", "decision", "pitfall", "blocked", "question", "next_action", "work_status", "evidence_link",
   "spawn", "joined", "adopt", "discard",
 ] as const;
@@ -519,6 +614,7 @@ export const MODEL_EVENTS = [
  * ancestry or are parent actions the branch should not inherit.
  */
 export const CARRYABLE_EVENTS = [
+  "work_dependencies", "work_owner",
   "claim", "decision", "pitfall", "blocked", "question", "next_action", "work_status", "evidence_link",
 ] as const;