# WO-05 — Artifact Fidelity and Explicit Materialization

**Status:** in progress  
**Primary modules:** `packages/execution/src/tools/file-read.ts`,
`packages/orchestrator/src/evidenceBranch.ts`, `evidenceLedger.ts`,
`artifactContract.ts`  
**Depends on:** WO-02, WO-03

## Problem

Mandatory curated branch-extract wrappers made the model distrust first-class
reads and fall back to shell. Automatic rehydration then injected partial or
duplicated material without explaining why it was present.

## Contract

`full_read` is canonical artifact evidence. `branch_extract` is a derived
artifact linked to source hash/range, requirement coverage, unresolved
requirements, extractor identity, and confidence. Materialization is an
explicit graph decision, never an opaque prompt wrapper.

## Todos

- [x] Persist full-read artifacts with hash, revision, range, fidelity, and
  availability state.
- [x] Make branch extraction optional (automatic only when the request budget
  cannot safely carry the full body) and callable by the model.
- [x] Require each extract to account for every requested requirement as
  satisfied with an anchor or unresolved with a bounded reason/recovery.
- [x] Never mark a partial or capped tool result `not_found`; record truncated
  provenance and deterministic narrowing advice.
- [ ] Retire the remaining legacy cache-rehydration presentation path after
  materialization telemetry has passed shadow/canary comparison.
- [x] On content-hash change, supersede old artifact evidence and allow the
  fresh read without stale-read penalties.

## Acceptance tests

- Twenty oversized files retain source hashes and explicit extract coverage;
  none can return a one-point “complete” extract with open requirements.
- An edit depending on a read gets the exact body or a visible request for it,
  never a deceptive wrapper.
- A capped 1 MB grep result is partial success with narrowing, not discovery
  failure.
- Hash-changing a file permits and records a justified reread.

## Live-harness safety gate

`live-branch-extract-harness.mjs` creates twenty individual oversized source
files and performs isolated extraction only. It requires
`HARNESS_APPROVED_GPU_UUID`; before its first generation it independently
checks `nvidia-smi`, the selected UUID, and the Ollama service's explicit
`CUDA_VISIBLE_DEVICES`. All visible service devices must be approved
A100-class accelerators. A missing, mismatched, or low-capability device is a
hard failure, never a fallback to CPU or another GPU.

The harness now has two explicit requirements per artifact—exact `baudRate`
and exact `channel`—and fails if either is unresolved, unanchored, or omitted
from the derived evidence. `HARNESS_REPORT_FILE` writes a structured,
non-source-bearing checkpoint after each artifact; a terminal report is
required for acceptance.

**Recorded acceptance:** 2026-07-13, `robit/ornith:35b` through Ollama on the
operator-approved A100 UUID completed 20/20 artifacts. Every artifact had two
satisfied anchored requirements and no unresolved requirement; the largest
isolated prompt was 6,080 characters while the parent received at most 1,611
characters of evidence. The local report is intentionally text-free.

## Definition of done

Tool tests plus an inference-driven extraction harness on approved A100-class
hardware demonstrate coverage and source-to-action fidelity.