@dailephd/my-frontend-observer 0.10.0 → 0.10.1

package/docs/reports/v0.8-evidence-index-readers-batch2.md

@@ -1,247 +1,247 @@
-# v0.8 Batch 2 — Evidence Indexing, Canonical Readers, and Lazy Data Boundary — Implementation Report
-
-## 1. Starting state
-
-- Starting branch: `master`
-- Starting HEAD: `3fb9df9db9335bb1efbd1cd90c00dfb0dc3cd41d` ("feat: add v0.8 viewer runtime and PWA foundation")
-- `origin/master` HEAD after `git fetch`: `a1de8ac01e1367b60021cb04226f56369fa2debb`
-- `git rev-list --left-right --count origin/master...HEAD`: `0  1` — local is exactly one commit (Batch 1) ahead of origin, no divergence. Per task §4, no pull/reset/merge was performed.
-- Starting `git status --short`: clean.
-- Package version confirmed `0.7.0` throughout; never bumped.
-
-## 2. Batch 1 report inspected
-
-Read the complete local `docs/reports/v0.8-viewer-runtime-pwa-batch1.md` (not just its console summary). Confirmed and reused without modification:
-
-- host `127.0.0.1`, fixed default port `4319` (`src/viewerServer/port.ts`);
-- server owner module `src/viewerServer/httpServer.ts` (`createViewerServer`/`handleRequest`) and application seam `src/viewerServer/viewerService.ts` (`startViewer`);
-- `/api/status` as the sole Batch 1 route, with an existing `pathname.startsWith('/api/')` fallback that Batch 2 routes were inserted before;
-- CLI dispatch ownership (`src/cli.ts` `runViewCommand`/`parseViewArgs`) - unchanged this batch;
-- PWA cache boundary: `viewer/vite.config.ts`'s `workbox.navigateFallbackDenylist: [/^\/api\//]`, which - being a prefix match on `/api/` - already covers every new Batch 2 route without modification;
-- generated-path convention (`WORKFLOW_ROOT` sibling directory, `npm_config_cache`/`VITE_CACHE_DIR` redirection);
-- Batch 1's own unresolved risks (install-prompt "available" branch untested in headless Chromium; no live service-worker execution test) - unrelated to Batch 2, not re-litigated.
-
-No contradiction between the report and the task's Batch 1 summary was found.
-
-## 3. Frozen planning authority inspected
-
-Read (or re-confirmed already-cached knowledge of, where noted) in order:
-
-1. `docs/DOCUMENTATION_PRESERVATION_POLICY.md` (previously read, unchanged)
-2. `docs/PROJECT_MILESTONES.md` (Milestone 8, previously read in full)
-3. `docs/ROADMAP.md` (v0.8 section, previously read)
-4. `docs/plans/v0.8-implementation-plan.md` Batch 2 section (`### Batch 2 — Evidence indexing, canonical readers, and lazy data boundary`) plus cross-batch invariants (§7)
-5. `docs/reports/v0.8-viewer-runtime-pwa-batch1.md` (§2 above)
-6. `docs/ARCHITECTURE.md` (relevant sections, then edited)
-7. `docs/CONTRACTS.md` (fully, in two paginated reads - artifact-kind/schema-version constants, directory/manifest-filename conventions, and the v0.7 external-reference media-ownership contract)
-8. `docs/COMMANDS.md` (`view` section, then edited)
-9. `docs/WORKFLOWS.md` (bounded-agent-context and external-reference workflow sections)
-10. `package.json`, `src/viewerServer/httpServer.ts`, `src/viewerServer/viewerService.ts`, `src/viewerServer/port.ts`
-11. `src/artifacts/artifactReader.ts`, `comparisonArtifactReader.ts`, `externalReferenceArtifactReader.ts`, `frontendContractArtifactReader.ts`, `frontendContractEvaluationArtifactReader.ts`, `types.ts`
-12. `src/artifacts/externalReferenceArtifactWriter.ts` (directory/media-ownership shape)
-13. `src/domain/schema.ts`, `comparison.ts`, `frontendContracts.ts`, `frontendContractEvaluationArtifact.ts`, `externalReference.ts`, `boundedAgentContext.ts`, `evidence.ts`, `completion.ts`
-14. `tests/unit/cliFrontendContracts.test.ts` (fixture-construction pattern reused for Batch 2 test fixtures), `tests/unit/diagnostics.test.ts`, `tests/unit/externalReferenceImageFixtures.ts`
-
-Confirmed the frozen plan is unchanged and Batch 2's title/scope match the task exactly.
-
-## 4. my-dev-kit retrieval
-
-Unlike Batch 1, this step was **run**, not skipped. Index built successfully:
-
-```
-npx @dailephd/my-dev-kit@latest index --root . --src src --src tests --src viewer \
-  --out "<WORKFLOW_ROOT>\my-dev-kit-index" --call-graph --json
-```
-
-Result: `status: "complete"`, 73 files indexed. Ran all five required searches (reader ownership, artifact-write ownership, bounded-agent-context persistence, screenshot/media ownership, viewer server routes, and artifact-kind/schema-version constants). Every result matched direct source inspection exactly - in particular, the `BoundedAgentContextArtifact` search returned only `src/domain/boundedAgentContext.ts` and application-service files, **no** `boundedAgentContextArtifactReader.ts`/`Writer.ts` - corroborating (not merely asserting) that no disk reader/writer exists for that family. No `lookup`/`source`/`slice` follow-up was needed since search results were unambiguous. `MY_DEV_KIT_INDEX` = `Z:\Users\newuser\Projects\my-frontend-observer.my-dev-kit-workflow\v0.8\batch-02\my-dev-kit-index`.
-
-## 5. Evidence-family inventory
-
-| Family | Kind constant | Schema | Persisted? | Writer | Reader (existing) | Discriminant | Media owned/referenced |
-|---|---|---|---|---|---|---|---|
-| Observation | `my-frontend-observer/observation` | `1.2.0` | Yes | `artifactWriter.ts` | `artifactReader.ts#readObservationArtifact` | - | owns `screenshot.png` (via `screenshot: EvidenceField<{path}>`) |
-| Comparison | `my-frontend-observer/comparison` | `1.0.0` | Yes | `comparisonArtifactWriter.ts` | `comparisonArtifactReader.ts#readComparisonArtifact` | - | none (references `before`/`after` observation ids only) |
-| Persistent baseline contract | `my-frontend-observer/frontend-contract` | `1.0.0` | Yes | `frontendContractArtifactWriter.ts#writePersistentBaselineContract` | `frontendContractArtifactReader.ts#readPersistentBaselineContract` | `contractClass: 'baseline'` | none |
-| Per-change contract | `my-frontend-observer/frontend-contract` | `1.0.0` | Yes | `...#writePerChangeContract` | `...#readPerChangeContract` | `contractClass: 'change'` | none |
-| Contract evaluation | `my-frontend-observer/frontend-contract-evaluation` | `1.0.0` | Yes | `frontendContractEvaluationArtifactWriter.ts` | `frontendContractEvaluationArtifactReader.ts` | - | none |
-| External reference (imported) | `my-frontend-observer/external-reference` | `1.0.0` | Yes | `externalReferenceArtifactWriter.ts` | `externalReferenceArtifactReader.ts#readExternalReferenceArtifact` | `lifecycle.state: 'imported'` | owns `image.<ext>` (bare filename) |
-| External reference (approved) | `my-frontend-observer/external-reference` | `1.0.0` | Yes | same | same | `lifecycle.state: 'approved'` | references, never copies, the imported artifact's image via `sourceReference.{referenceId, image}` |
-| Bounded agent context | `my-frontend-observer/bounded-agent-context` | `1.0.0` | **No** | none | none | - | n/a |
-
-Every family (all filename `manifest.json`, one artifact directory per instance) belongs in Batch 2 discovery **except** bounded-agent-context, which - per `docs/CONTRACTS.md` "v0.6 bounded agent context and correlation contract" ("there is no disk artifact writer/reader... it is a pure programmatic contract and derivation layer") and confirmed by my-dev-kit search (§4) - has no persisted filesystem representation to discover. Per task §8/§21, no persistence was invented for it; a manifest declaring that kind is classified `unrecognized-kind` (test: `evidenceDiscovery.test.ts` "a bounded-agent-context-kind manifest is treated as unrecognized").
-
-## 6. Existing readers reused (no new readers were needed)
-
-All five persisted families already had a canonical reader before this batch (`readObservationArtifact`, `readComparisonArtifact`, `readPersistentBaselineContract`, `readPerChangeContract`, `readFrontendContractEvaluationArtifact`, `readExternalReferenceArtifact`) - confirmed by direct inspection (§3) and my-dev-kit search (§4). **No new reader was added.** `src/viewerServer/evidence/classify.ts` calls these six functions unchanged; it never re-implements JSON parsing or structural validation.
-
-## 7. Canonical validators reused
-
-Every classification decision for a "supported" or "invalid-structure" result comes from the family's own existing validator, invoked transitively by its reader (`isValidObservationArtifact`, `isValidComparisonArtifact`, `isValidPersistentBaselineContract`, `isValidPerChangeContract`, `isValidFrontendContractEvaluationArtifact`, `isValidExternalReferenceArtifact`). No second/parallel validator was introduced anywhere in `src/viewerServer/evidence/`. For the shared `frontend-contract` kind, `classify.ts` tries `readPersistentBaselineContract` then `readPerChangeContract` in sequence - the **existing validators**, not classifier-owned logic, decide which (if either) a candidate actually is.
-
-## 8. Index bounds selected (and rationale)
-
-Defined in `src/viewerServer/evidence/limits.ts`, chosen after inspecting that every current writer produces a shallow `<outputLocation>/<id>/manifest.json` shape (§5) rather than a deep tree:
-
-- `MAX_DISCOVERY_DEPTH = 6` (typical real shape needs depth 2; generous slack for a nested `--output`, still bounded);
-- `MAX_DIRECTORIES_VISITED = 2000`;
-- `MAX_MANIFEST_CANDIDATES = 1000` (candidate `manifest.json` files classified);
-- `MAX_INDEX_RECORDS = 500` (metadata records returned in one `/api/index` response);
-- `MAX_MANIFEST_CANDIDATE_BYTES = 2,000,000` - a candidate exceeding this is never read into memory; classified `unreadable` instead. Real manifests are small (identity/geometry/config JSON only; screenshots/images are always separate sibling files - §5), so this is generous headroom, not a tight fit.
-
-`discoverManifests` opens **only** files literally named `manifest.json` - no other filename is ever read or classified, regardless of content (even valid JSON), satisfying "do not treat every `manifest.json` as valid Observer evidence... do not treat arbitrary JSON files as viewer artifacts" without needing a broader allow/deny list.
-
-## 9. Symlink/junction policy
-
-`discovery.ts#walk` checks `dirent.isSymbolicLink()` on every entry (file or directory) via `readdir(dir, {withFileTypes:true})` and skips it entirely - never followed, never opened. Verified with a real symlinked directory pointing outside the evidence root (`evidenceDiscovery.test.ts` "never follows a directory symlink out of the evidence root"; the test degrades gracefully rather than failing if symlink creation requires elevated privileges in a given Windows configuration - confirmed working in this environment). Since symlinks are never followed, no separate `realpath`-based re-containment check was needed for the walk itself; `resolveContainedDir`/`resolveContainedFile` (§13) provide that containment guarantee independently for handle-driven (not walk-driven) access.
-
-## 10. Viewer handle design
-
-A handle is `<family-slug>:<percent-encoded root-relative directory path>` (`evidence/handles.ts`) - e.g. `observation:observations%2Fsmoke-obs-before`. It is "server-issued" only in the sense that it is exactly what discovery/classification already produced; it grants no filesystem access by itself. **Every** route that accepts a handle (`/api/artifacts/<handle>`, `/api/media/<handle>/<role>`) independently decodes it, re-resolves it against the evidence root via `resolveContainedDir` (re-checking containment), and re-classifies that one candidate through the same canonical-reader dispatch the index uses - it never trusts a cached record or a client-supplied path string. A handle whose backing directory no longer exists, or whose re-classified family no longer matches what the handle claims, fails closed as "unknown handle" (404), never served as stale.
-
-## 11. API routes and semantics
-
-| Route | Method | Semantics |
-|---|---|---|
-| `GET /api/status` | GET/HEAD | Unchanged from Batch 1. |
-| `GET /api/index` | GET/HEAD | Bounded, metadata-only, deterministic (rebuilt fresh every call - no persistent cache). |
-| `GET /api/artifacts/<handle>` | GET/HEAD | Known handle only; one canonical-reader read; on demand; no schema upgrade; no mutation. `200` supported / `404` unknown handle / `409` handle resolves but is not currently loadable (unsupported-version, invalid-structure, malformed-json, unreadable - carries the same honest `metadata` the index would show). |
-| `GET /api/media/<handle>/<role>` | GET/HEAD | Known handle + known role only; root/artifact-contained; on demand; streamed. `200` / `404` for any failure (unknown handle, unknown/inapplicable role, missing file). |
-
-All four reject every write method (`POST`/`PUT`/`PATCH`/`DELETE`) with `405 Method Not Allowed` (enforced once, ahead of all routing, in `handleRequest` - unchanged Batch 1 mechanism now covers the new routes too; verified in `viewerEvidenceServer.test.ts`).
-
-## 12. Viewer adapter architecture
-
-`src/viewerServer/evidence/projection.ts`:
-
-- `EvidenceMetadataRecord` - the `/api/index` shape: `handle`, `family`, `supportState`, `relativeDir`, and (only when meaningful for that family/state) `logicalId`, `schemaVersion`, `foundSchemaVersion`, `producerVersion`, `completion`, `lifecycleState`, `contractClass`, `overallVerdict`, `comparability`, `media` (availability summary only, never bytes), `relatedIds`, `message`. Verified to exclude full-payload fields (`targetEvidence`, `pageEvidence`, `requestConfig`) via a direct serialization assertion.
-- `EvidenceArtifactDetail` - the `/api/artifacts/<handle>` shape: the already-validated domain object wrapped with `handle`/`family`. Selects/wraps existing canonical fields only; derives nothing new, recomputes nothing, persists nothing (no `viewer.json`/viewer-manifest/cache artifact of any kind exists anywhere in this batch).
-
-Both are ephemeral: constructed fresh per request, held only in memory for the duration of that request/response.
-
-## 13. Absolute-path exposure policy
-
-Metadata records expose only a root-relative `relativeDir` (POSIX-normalized), never an absolute filesystem path. `/api/status`'s pre-existing `root` field (Batch 1, unchanged) remains the only place an absolute path is echoed back, and only as an opaque display string the server itself supplied - never accepted as input from the browser.
-
-## 14. Media ownership/resolution behavior
-
-`src/viewerServer/evidence/mediaResolver.ts` recognizes exactly three roles: `screenshot` (observation only), `image` (imported external reference only), `source-image` (approved external reference only) - any other role, or a role requested against a family it doesn't apply to, is rejected (`404`). Every resolved path goes through `resolveContainedFile`, which additionally rejects any filename containing a path separator outright (every real media reference is contractually a bare filename - `docs/CONTRACTS.md` "v0.7 Prompt 1" `ExternalReferenceImageReference.path`).
-
-## 15. Approved external-reference source-image behavior
-
-Confirmed via `docs/CONTRACTS.md`/`externalReference.ts` (§3/§5) and proven by a real fixture (`writeExternalReferencePairFixture`, using the actual `importExternalReference`/`approveExternalReference` application services): an approved artifact's directory contains **only** `manifest.json` - no image file. `source-image` resolution reads the approved artifact's `sourceReference.referenceId`, then calls `evidence/index.ts#findImportedReferenceDir` - a bounded search (reusing the same discovery+classify pipeline, capped at `MAX_INDEX_RECORDS`) for the **imported** artifact whose own `referenceId` matches - and only then resolves `sourceReference.image.path` against *that* artifact's real directory. Never assumes co-location. Two tests prove this exactly: "resolves an approved reference's source-image through the owning imported artifact, never assuming co-location" (success case, real cross-artifact resolution) and "an approved reference whose owning imported artifact is absent from the root reports missing media honestly" (the imported artifact deliberately left out of the root - `404`, not a crash or a fabricated image). The full built-CLI smoke test (§20) additionally proves this against the real compiled server.
-
-## 16. Unsupported-version behavior
-
-`classify.ts` compares the candidate's `schemaVersion` against the current canonical constant (`SCHEMA_VERSION`, `COMPARISON_SCHEMA_VERSION`, `CONTRACT_SCHEMA_VERSION`, `EVALUATION_SCHEMA_VERSION`, `EXTERNAL_REFERENCE_SCHEMA_VERSION`) **before** attempting a canonical read, so an unsupported version never even reaches (and is never silently accepted by) the reader/validator pair pinned to the current schema. `/api/index` reports `supportState: 'unsupported-version'` plus both the found and supported version strings; `/api/artifacts/<handle>` refuses to load it (`409`, carrying that same honest metadata) - never coerced into a fabricated current-shape domain object. Proven with a real fixture (`writeUnsupportedVersionManifest`: a genuine `my-frontend-observer/observation` kind at schema `99.0.0`) at the unit level and in the real-Chromium/CLI smoke.
-
-## 17. Malformed/unavailable/missing behavior
-
-Six independent, honestly distinguished states (`ViewerSupportState` in `classify.ts`): `supported`, `unsupported-version`, `invalid-structure` (kind+version match but the canonical validator itself rejects it), `unrecognized-kind` (no known `artifactKind`, including the bounded-agent-context case), `malformed-json` (not valid JSON at all), `unreadable` (stat/read failure or over the size bound). None is ever silently dropped or reinterpreted as `supported`; one malformed/unrelated candidate never erases valid neighboring evidence (`evidenceDiscovery.test.ts`: 6 real pipeline artifacts + 1 malformed all appear in one index response). Missing media is reported per-role (`available: false` with an honest `reason`) rather than as a whole-artifact failure - a genuinely deleted `screenshot.png` still yields a `supported` observation record whose `media` summary honestly says `unavailable`.
-
-## 18. PWA cache verification
-
-No `vite.config.ts`/service-worker configuration change was needed: every new route lives under `/api/`, already covered by Batch 1's `navigateFallbackDenylist: [/^\/api\//]`. Extended `tests/unit/viewerPwaBuild.test.ts` with an explicit Batch 2 assertion against the **real built** `sw.js`: still exactly one `registerRoute` call after the server-side additions, and the precache manifest contains no `/api/index`, `/api/artifacts`, or `/api/media` entry.
-
-## 19. Batch 2 UI changes
-
-`viewer/src/hooks/useEvidenceIndex.ts` (fetches `/api/index`), `useArtifactDetail.ts` (fetches `/api/artifacts/<handle>` only when a handle is selected - never eagerly), `components/EvidenceList.tsx` (bounded list, one item per record, honest support-state label per item), `components/ArtifactPreview.tsx` (loading/loaded/error/unsupported states; a bounded raw-JSON preview of the loaded artifact - explicitly *not* a real visualization). `App.tsx` wires these into the existing Batch 1 shell regions (nav = list, workspace = preview, details aside = selected record's own already-fetched metadata fields - no additional request). No screenshot rendering, SVG overlay, or comparison/contract/reference visualization exists anywhere in `viewer/src/` (verified by a real-Chromium test asserting zero `<img>`/`<svg>` elements after loading a real observation).
-
-## 20. Files created
-
-- `src/viewerServer/evidence/limits.ts`, `discovery.ts`, `classify.ts`, `handles.ts`, `pathSafety.ts`, `projection.ts`, `index.ts`, `mediaResolver.ts`
-- `tests/support/evidenceFixtures.ts` (shared real-evidence fixture builders, reusing the existing writer/application-service functions - mirrors `tests/unit/cliFrontendContracts.test.ts`'s established construction pattern)
-- `tests/unit/evidenceDiscovery.test.ts`, `viewerEvidenceServer.test.ts`
-- `tests/browser/viewerEvidenceShell.test.ts`
-- `viewer/src/hooks/useEvidenceIndex.ts`, `useArtifactDetail.ts`
-- `viewer/src/components/EvidenceList.tsx`, `ArtifactPreview.tsx`
-- `docs/reports/v0.8-evidence-index-readers-batch2.md` (this file)
-
-## 21. Files modified
-
-- `src/viewerServer/httpServer.ts` - added `/api/index`, `/api/artifacts/<handle>`, `/api/media/<handle>/<role>` routing plus shared `writeJsonBody`/`writeJsonError`/`streamFile`/`decodeURIComponentSafe` helpers; existing `/api/status` and static-asset serving unchanged.
-- `viewer/src/App.tsx` - wires the new hooks/components into the existing shell regions.
-- `viewer/src/styles/index.css` - additive rules for the evidence list/preview/details UI.
-- `tests/browser/viewerShell.test.ts` - one pre-existing Batch 1 assertion (`toContain('Evidence navigation will appear here')`, a *static placeholder* string) legitimately no longer holds now that the nav region is live; updated to assert the new, honest "no recognized evidence" message for an empty root - the same kind of sanctioned evolution as Batch 1's own `TST-401` update.
-- `tests/unit/viewerPwaBuild.test.ts` - added the explicit Batch 2 cache-boundary assertion (§18).
-- `docs/ARCHITECTURE.md` - new "v0.8 Batch 2" section.
-- `docs/COMMANDS.md` - `view` section updated to describe the new routes/behavior.
-
-## 22. A production bug found and fixed by real-CLI smoke testing
-
-`src/viewerServer/evidence/pathSafety.ts#resolveContainedDir` originally compared a `path.resolve()`-normalized candidate path against the **un-normalized** `root` string. Every unit test's `root` came from `path.join(tmpdir(), ...)`, which Node already normalizes to the platform separator, masking the bug entirely - all 19 initial `viewerEvidenceServer.test.ts` tests passed. The real built-CLI smoke test (§23), run with `--root` supplied using forward slashes (as a user typing a path in a shell commonly would, even on Windows), reproduced it immediately: every artifact/media request returned `404 unknown handle` even for evidence that genuinely existed. Root-caused via direct `node -e` reproduction against the compiled `dist` output, fixed by resolving `root` itself before the prefix comparison, and covered by a new dedicated regression test (`viewerEvidenceServer.test.ts` "root path normalization" describe block) that deliberately constructs a forward-slash root and asserts a real handle still resolves. This is exactly the kind of defect the task's mandated built-CLI smoke step (§34) exists to catch, and it did.
-
-## 23. Validation results
-
-| Command | Result |
-|---|---|
-| `npm run typecheck` | **PASS** (zero errors, both `tsconfig.json` and `viewer/tsconfig.json`) |
-| `npm run lint` | **PASS** (zero errors/warnings) |
-| `npm test` | **PASS** - 1071/1071 tests, 56/56 files |
-| `npm run build` | **PASS** - unchanged Node/library output plus `dist/viewerServer/evidence/**` and the rebuilt `dist/viewer/**` PWA |
-| `npm run check:docs` | **PASS** - "Documentation check passed (17 required files)." |
-| `npm run test:browser` | **PASS** - 132/132 tests, 12/12 files (real Chromium; run in full, not skipped, per task §33's instruction since this batch directly changes the browser-facing data boundary) |
-| `git diff --check` | **PASS** - no whitespace errors (only expected LF→CRLF line-ending notices) |
-
-## 24. Built viewer Batch 2 smoke (§34)
-
-Fixture: a real evidence root built via a one-off script (not committed; lives under `WORKFLOW_ROOT\tmp`) that calls the actual compiled `dist/artifacts/*Writer.js` and `dist/application/*Service.js` modules directly - the same real writers/services the CLI itself uses - to produce two real observations, a real comparison, a real baseline contract, a real per-change contract, a real evaluation, a real imported external reference (with a real image file), and a real approved external reference, plus a malformed-JSON candidate, an unsupported-future-schema-version candidate, and one unrelated `README.txt`, all under `WORKFLOW_ROOT\smoke\evidence-root`.
-
-Command: `node dist/cli.js view --root "<WORKFLOW_ROOT>\smoke\evidence-root" --port 4319 --no-open`
-
-All required checks (§34), against the real running built server:
-
-- `/api/status` → `200`, correct root echoed.
-- `/api/index` → `200`, all 9 real evidence records present with correct `family`/`supportState`, plus the malformed and unsupported-version candidates shown honestly; response body contains no full-artifact fields (`targetEvidence` etc.) and no `README` reference.
-- Selected supported artifact (`observation:observations%2Fsmoke-obs-before`) loaded on demand via `/api/artifacts/<handle>` → `200` with its full payload.
-- Selected media loaded on demand: observation `screenshot` → `200 image/png`; imported reference `image` → `200 image/png`; **approved reference `source-image` → `200 image/png`, resolved through the separate imported artifact's directory** (§15/§22).
-- Unsupported-version and malformed candidates both correctly refused at `/api/artifacts/<handle>` → `409` (not fabricated as loaded).
-- Unrelated `README.txt` never appears in `/api/index` and is not directly servable (`GET /README.txt` → `404`).
-- Path-traversal attempt (`/api/artifacts/observation:..%2F..%2Fetc`) → `404`.
-- Absolute-path-shaped handle attempt → `404`.
-- PWA still loads: `/` → `200`, `/manifest.webmanifest` → `200`, `/sw.js` → `200`.
-- `netstat` confirmed the listener bound to `127.0.0.1:4319` only (never `0.0.0.0`).
-- Server located by its real PID via `netstat` and terminated with `taskkill /F`; a follow-up `netstat` confirmed the port was released and no server process remained.
-- A post-run directory listing of the smoke evidence root shows exactly the fixture's own files - no stray `.tmp-*` write-in-progress directories, no modified/deleted files.
-
-**Result: PASS.** Logs retained under `WORKFLOW_ROOT\logs\` (`smoke-server.log`, `smoke-server-2.log` [post-fix rerun], `index-response.json`, `index-response-2.json`, `smoke-checks-final.log`).
-
-## 25. Existing command regression check
-
-`observe`, `compare`, `approve-baseline`, `save-change-contract`, `evaluate-contract`, `import-reference`, `approve-reference`, `evaluate-reference-fidelity`, Batch 1 `view` startup, PWA shell, fixed host/port behavior, and the PWA cache boundary all remain covered by their existing, unmodified test suites (all 1071 unit + 132 browser tests pass - §23). Canonical v0.1-v0.7 semantics were not touched anywhere in this batch's diff; `src/domain/`, `src/artifacts/*Writer.ts`, and every existing reader are byte-for-byte unchanged.
-
-## 26. Generated path inventory
-
-| Path | Disposition |
-|---|---|
-| `WORKFLOW_ROOT\cache\npm` | Retained (npm cache from the my-dev-kit-index `npx` invocation; harmless, reusable) |
-| `WORKFLOW_ROOT\tmp\vite-cache`, `WORKFLOW_ROOT\tmp\build-smoke-evidence.mjs` | Retained (build cache dir was empty again, same as Batch 1 - Vite build mode doesn't populate it; the smoke-fixture script is dev/readiness tooling only, not committed) |
-| `WORKFLOW_ROOT\logs\*` | Retained (smoke evidence - §24) |
-| `WORKFLOW_ROOT\smoke\evidence-root` | Retained (real evidence fixture tree built for the smoke test - §24) |
-| `WORKFLOW_ROOT\my-dev-kit-index\*` | Retained (successful index + cache-metadata from §4) |
-| `WORKFLOW_ROOT\{fixtures,candidate,pack}` | Retained, empty/unused this batch (no `npm pack`/candidate-install step was needed since no packaging-boundary change occurred beyond the existing `dist` allowlist) |
-| Repo-root `dist/` | Ordinary build output (gitignored); rebuilt cleanly by `scripts/clean.mjs` on every `npm run build` |
-| Pre-existing repo-root `.my-dev-kit*`/`baselines`/`comparisons`/`contracts`/`evaluations`/`observations` | Pre-existing, empty, untouched (same finding as the Batch 1 report) |
-
-`Z:\Users\newuser\Projects\my-frontend-observer.my-dev-kit-workflow\v0.8\batch-01` was never targeted by any command in this session (verified) - preserved exactly as Batch 1 left it.
-
-## 27. Repository pollution check
-
-`git status --short` before staging showed only the seven modified + eight new Batch-2-owned paths listed in §20/§21 (plus their containing directories). No unexpected file or directory appeared anywhere in the repository as a result of this batch's work.
-
-## 28. Skipped work / deviations
-
-- None. Every task step (my-dev-kit retrieval, all six required test categories, the full validation chain including `test:browser`, and the built-CLI smoke) was executed, not skipped or substituted.
-
-## 29. Remaining uncovered risks
-
-- **`findImportedReferenceDir` re-walks the evidence tree per `source-image` request** rather than reusing a cached index (by design - no persistent cache exists, per task §30). For an evidence root at the bound edge (near `MAX_MANIFEST_CANDIDATES`), an approved-reference-heavy workload would re-pay that walk cost on every source-image request. Not a correctness risk; a potential future performance consideration only if real usage ever approaches the bound (task §30 explicitly says to report rather than pre-optimize).
-- **The bounded-agent-context "unrecognized-kind" classification is asserted only at the unit level**, not against a real persisted fixture (none exists to build, by design - §5). The behavior is exercised with a hand-written manifest declaring that kind, which is the most realistic proof achievable without inventing persistence for a family that has none.
-- Batch 1's previously reported risks (install-prompt "available" branch, live service-worker execution) remain unresolved and out of this batch's scope.
-
-## 30. Out-of-scope confirmation
-
-Confirmed absent from this batch's diff: target SVG overlays, screenshot geometry rendering, runtime target inspection UI, relationship/scroll visualization, before/after visual comparison, contract/change-scope visualization, external-reference/candidate side-by-side visual inspection, region/target overlays, explicit-binding cross-selection, zoom/pan, synchronized lock, on-demand fidelity computation, bounded-agent-context visual inspection, correlation UI, arbitrary filesystem navigation, annotation, region/requirement authoring, source editing, automatic binding/target discovery, pixel-diff scoring, computer vision, cloud hosting, database, authentication, collaboration. `ArtifactPreview.tsx`'s raw-JSON preview is explicitly not a visualization (no image, no SVG, no geometry rendering - proven by the zero-`<img>`/zero-`<svg>` browser assertion, §19).
-
-## 31. Final verdict
-
-Batch 2 ("Evidence indexing, canonical readers, and lazy data boundary") is implemented and independently validated: a built candidate's viewer can enumerate real recognized evidence from bounded metadata, load one selected artifact on demand through its existing canonical validation boundary, load its owned/referenced media safely (including the cross-artifact approved-reference case), and visibly distinguish malformed/unsupported/missing evidence rather than silently dropping it - proven at the unit, real-Chromium, and real-built-CLI-smoke levels, with one genuine cross-platform path-handling defect found and fixed along the way. No Batch 3+ visualization, no v0.9 annotation, and no release/publication action was taken. Package version remains `0.7.0`.
+# v0.8 Batch 2 — Evidence Indexing, Canonical Readers, and Lazy Data Boundary — Implementation Report
+
+## 1. Starting state
+
+- Starting branch: `master`
+- Starting HEAD: `3fb9df9db9335bb1efbd1cd90c00dfb0dc3cd41d` ("feat: add v0.8 viewer runtime and PWA foundation")
+- `origin/master` HEAD after `git fetch`: `a1de8ac01e1367b60021cb04226f56369fa2debb`
+- `git rev-list --left-right --count origin/master...HEAD`: `0  1` — local is exactly one commit (Batch 1) ahead of origin, no divergence. Per task §4, no pull/reset/merge was performed.
+- Starting `git status --short`: clean.
+- Package version confirmed `0.7.0` throughout; never bumped.
+
+## 2. Batch 1 report inspected
+
+Read the complete local `docs/reports/v0.8-viewer-runtime-pwa-batch1.md` (not just its console summary). Confirmed and reused without modification:
+
+- host `127.0.0.1`, fixed default port `4319` (`src/viewerServer/port.ts`);
+- server owner module `src/viewerServer/httpServer.ts` (`createViewerServer`/`handleRequest`) and application seam `src/viewerServer/viewerService.ts` (`startViewer`);
+- `/api/status` as the sole Batch 1 route, with an existing `pathname.startsWith('/api/')` fallback that Batch 2 routes were inserted before;
+- CLI dispatch ownership (`src/cli.ts` `runViewCommand`/`parseViewArgs`) - unchanged this batch;
+- PWA cache boundary: `viewer/vite.config.ts`'s `workbox.navigateFallbackDenylist: [/^\/api\//]`, which - being a prefix match on `/api/` - already covers every new Batch 2 route without modification;
+- generated-path convention (`WORKFLOW_ROOT` sibling directory, `npm_config_cache`/`VITE_CACHE_DIR` redirection);
+- Batch 1's own unresolved risks (install-prompt "available" branch untested in headless Chromium; no live service-worker execution test) - unrelated to Batch 2, not re-litigated.
+
+No contradiction between the report and the task's Batch 1 summary was found.
+
+## 3. Frozen planning authority inspected
+
+Read (or re-confirmed already-cached knowledge of, where noted) in order:
+
+1. `docs/DOCUMENTATION_PRESERVATION_POLICY.md` (previously read, unchanged)
+2. `docs/PROJECT_MILESTONES.md` (Milestone 8, previously read in full)
+3. `docs/ROADMAP.md` (v0.8 section, previously read)
+4. `docs/plans/v0.8-implementation-plan.md` Batch 2 section (`### Batch 2 — Evidence indexing, canonical readers, and lazy data boundary`) plus cross-batch invariants (§7)
+5. `docs/reports/v0.8-viewer-runtime-pwa-batch1.md` (§2 above)
+6. `docs/ARCHITECTURE.md` (relevant sections, then edited)
+7. `docs/CONTRACTS.md` (fully, in two paginated reads - artifact-kind/schema-version constants, directory/manifest-filename conventions, and the v0.7 external-reference media-ownership contract)
+8. `docs/COMMANDS.md` (`view` section, then edited)
+9. `docs/WORKFLOWS.md` (bounded-agent-context and external-reference workflow sections)
+10. `package.json`, `src/viewerServer/httpServer.ts`, `src/viewerServer/viewerService.ts`, `src/viewerServer/port.ts`
+11. `src/artifacts/artifactReader.ts`, `comparisonArtifactReader.ts`, `externalReferenceArtifactReader.ts`, `frontendContractArtifactReader.ts`, `frontendContractEvaluationArtifactReader.ts`, `types.ts`
+12. `src/artifacts/externalReferenceArtifactWriter.ts` (directory/media-ownership shape)
+13. `src/domain/schema.ts`, `comparison.ts`, `frontendContracts.ts`, `frontendContractEvaluationArtifact.ts`, `externalReference.ts`, `boundedAgentContext.ts`, `evidence.ts`, `completion.ts`
+14. `tests/unit/cliFrontendContracts.test.ts` (fixture-construction pattern reused for Batch 2 test fixtures), `tests/unit/diagnostics.test.ts`, `tests/unit/externalReferenceImageFixtures.ts`
+
+Confirmed the frozen plan is unchanged and Batch 2's title/scope match the task exactly.
+
+## 4. my-dev-kit retrieval
+
+Unlike Batch 1, this step was **run**, not skipped. Index built successfully:
+
+```
+npx @dailephd/my-dev-kit@latest index --root . --src src --src tests --src viewer \
+  --out "<WORKFLOW_ROOT>\my-dev-kit-index" --call-graph --json
+```
+
+Result: `status: "complete"`, 73 files indexed. Ran all five required searches (reader ownership, artifact-write ownership, bounded-agent-context persistence, screenshot/media ownership, viewer server routes, and artifact-kind/schema-version constants). Every result matched direct source inspection exactly - in particular, the `BoundedAgentContextArtifact` search returned only `src/domain/boundedAgentContext.ts` and application-service files, **no** `boundedAgentContextArtifactReader.ts`/`Writer.ts` - corroborating (not merely asserting) that no disk reader/writer exists for that family. No `lookup`/`source`/`slice` follow-up was needed since search results were unambiguous. `MY_DEV_KIT_INDEX` = `Z:\Users\newuser\Projects\my-frontend-observer.my-dev-kit-workflow\v0.8\batch-02\my-dev-kit-index`.
+
+## 5. Evidence-family inventory
+
+| Family | Kind constant | Schema | Persisted? | Writer | Reader (existing) | Discriminant | Media owned/referenced |
+|---|---|---|---|---|---|---|---|
+| Observation | `my-frontend-observer/observation` | `1.2.0` | Yes | `artifactWriter.ts` | `artifactReader.ts#readObservationArtifact` | - | owns `screenshot.png` (via `screenshot: EvidenceField<{path}>`) |
+| Comparison | `my-frontend-observer/comparison` | `1.0.0` | Yes | `comparisonArtifactWriter.ts` | `comparisonArtifactReader.ts#readComparisonArtifact` | - | none (references `before`/`after` observation ids only) |
+| Persistent baseline contract | `my-frontend-observer/frontend-contract` | `1.0.0` | Yes | `frontendContractArtifactWriter.ts#writePersistentBaselineContract` | `frontendContractArtifactReader.ts#readPersistentBaselineContract` | `contractClass: 'baseline'` | none |
+| Per-change contract | `my-frontend-observer/frontend-contract` | `1.0.0` | Yes | `...#writePerChangeContract` | `...#readPerChangeContract` | `contractClass: 'change'` | none |
+| Contract evaluation | `my-frontend-observer/frontend-contract-evaluation` | `1.0.0` | Yes | `frontendContractEvaluationArtifactWriter.ts` | `frontendContractEvaluationArtifactReader.ts` | - | none |
+| External reference (imported) | `my-frontend-observer/external-reference` | `1.0.0` | Yes | `externalReferenceArtifactWriter.ts` | `externalReferenceArtifactReader.ts#readExternalReferenceArtifact` | `lifecycle.state: 'imported'` | owns `image.<ext>` (bare filename) |
+| External reference (approved) | `my-frontend-observer/external-reference` | `1.0.0` | Yes | same | same | `lifecycle.state: 'approved'` | references, never copies, the imported artifact's image via `sourceReference.{referenceId, image}` |
+| Bounded agent context | `my-frontend-observer/bounded-agent-context` | `1.0.0` | **No** | none | none | - | n/a |
+
+Every family (all filename `manifest.json`, one artifact directory per instance) belongs in Batch 2 discovery **except** bounded-agent-context, which - per `docs/CONTRACTS.md` "v0.6 bounded agent context and correlation contract" ("there is no disk artifact writer/reader... it is a pure programmatic contract and derivation layer") and confirmed by my-dev-kit search (§4) - has no persisted filesystem representation to discover. Per task §8/§21, no persistence was invented for it; a manifest declaring that kind is classified `unrecognized-kind` (test: `evidenceDiscovery.test.ts` "a bounded-agent-context-kind manifest is treated as unrecognized").
+
+## 6. Existing readers reused (no new readers were needed)
+
+All five persisted families already had a canonical reader before this batch (`readObservationArtifact`, `readComparisonArtifact`, `readPersistentBaselineContract`, `readPerChangeContract`, `readFrontendContractEvaluationArtifact`, `readExternalReferenceArtifact`) - confirmed by direct inspection (§3) and my-dev-kit search (§4). **No new reader was added.** `src/viewerServer/evidence/classify.ts` calls these six functions unchanged; it never re-implements JSON parsing or structural validation.
+
+## 7. Canonical validators reused
+
+Every classification decision for a "supported" or "invalid-structure" result comes from the family's own existing validator, invoked transitively by its reader (`isValidObservationArtifact`, `isValidComparisonArtifact`, `isValidPersistentBaselineContract`, `isValidPerChangeContract`, `isValidFrontendContractEvaluationArtifact`, `isValidExternalReferenceArtifact`). No second/parallel validator was introduced anywhere in `src/viewerServer/evidence/`. For the shared `frontend-contract` kind, `classify.ts` tries `readPersistentBaselineContract` then `readPerChangeContract` in sequence - the **existing validators**, not classifier-owned logic, decide which (if either) a candidate actually is.
+
+## 8. Index bounds selected (and rationale)
+
+Defined in `src/viewerServer/evidence/limits.ts`, chosen after inspecting that every current writer produces a shallow `<outputLocation>/<id>/manifest.json` shape (§5) rather than a deep tree:
+
+- `MAX_DISCOVERY_DEPTH = 6` (typical real shape needs depth 2; generous slack for a nested `--output`, still bounded);
+- `MAX_DIRECTORIES_VISITED = 2000`;
+- `MAX_MANIFEST_CANDIDATES = 1000` (candidate `manifest.json` files classified);
+- `MAX_INDEX_RECORDS = 500` (metadata records returned in one `/api/index` response);
+- `MAX_MANIFEST_CANDIDATE_BYTES = 2,000,000` - a candidate exceeding this is never read into memory; classified `unreadable` instead. Real manifests are small (identity/geometry/config JSON only; screenshots/images are always separate sibling files - §5), so this is generous headroom, not a tight fit.
+
+`discoverManifests` opens **only** files literally named `manifest.json` - no other filename is ever read or classified, regardless of content (even valid JSON), satisfying "do not treat every `manifest.json` as valid Observer evidence... do not treat arbitrary JSON files as viewer artifacts" without needing a broader allow/deny list.
+
+## 9. Symlink/junction policy
+
+`discovery.ts#walk` checks `dirent.isSymbolicLink()` on every entry (file or directory) via `readdir(dir, {withFileTypes:true})` and skips it entirely - never followed, never opened. Verified with a real symlinked directory pointing outside the evidence root (`evidenceDiscovery.test.ts` "never follows a directory symlink out of the evidence root"; the test degrades gracefully rather than failing if symlink creation requires elevated privileges in a given Windows configuration - confirmed working in this environment). Since symlinks are never followed, no separate `realpath`-based re-containment check was needed for the walk itself; `resolveContainedDir`/`resolveContainedFile` (§13) provide that containment guarantee independently for handle-driven (not walk-driven) access.
+
+## 10. Viewer handle design
+
+A handle is `<family-slug>:<percent-encoded root-relative directory path>` (`evidence/handles.ts`) - e.g. `observation:observations%2Fsmoke-obs-before`. It is "server-issued" only in the sense that it is exactly what discovery/classification already produced; it grants no filesystem access by itself. **Every** route that accepts a handle (`/api/artifacts/<handle>`, `/api/media/<handle>/<role>`) independently decodes it, re-resolves it against the evidence root via `resolveContainedDir` (re-checking containment), and re-classifies that one candidate through the same canonical-reader dispatch the index uses - it never trusts a cached record or a client-supplied path string. A handle whose backing directory no longer exists, or whose re-classified family no longer matches what the handle claims, fails closed as "unknown handle" (404), never served as stale.
+
+## 11. API routes and semantics
+
+| Route | Method | Semantics |
+|---|---|---|
+| `GET /api/status` | GET/HEAD | Unchanged from Batch 1. |
+| `GET /api/index` | GET/HEAD | Bounded, metadata-only, deterministic (rebuilt fresh every call - no persistent cache). |
+| `GET /api/artifacts/<handle>` | GET/HEAD | Known handle only; one canonical-reader read; on demand; no schema upgrade; no mutation. `200` supported / `404` unknown handle / `409` handle resolves but is not currently loadable (unsupported-version, invalid-structure, malformed-json, unreadable - carries the same honest `metadata` the index would show). |
+| `GET /api/media/<handle>/<role>` | GET/HEAD | Known handle + known role only; root/artifact-contained; on demand; streamed. `200` / `404` for any failure (unknown handle, unknown/inapplicable role, missing file). |
+
+All four reject every write method (`POST`/`PUT`/`PATCH`/`DELETE`) with `405 Method Not Allowed` (enforced once, ahead of all routing, in `handleRequest` - unchanged Batch 1 mechanism now covers the new routes too; verified in `viewerEvidenceServer.test.ts`).
+
+## 12. Viewer adapter architecture
+
+`src/viewerServer/evidence/projection.ts`:
+
+- `EvidenceMetadataRecord` - the `/api/index` shape: `handle`, `family`, `supportState`, `relativeDir`, and (only when meaningful for that family/state) `logicalId`, `schemaVersion`, `foundSchemaVersion`, `producerVersion`, `completion`, `lifecycleState`, `contractClass`, `overallVerdict`, `comparability`, `media` (availability summary only, never bytes), `relatedIds`, `message`. Verified to exclude full-payload fields (`targetEvidence`, `pageEvidence`, `requestConfig`) via a direct serialization assertion.
+- `EvidenceArtifactDetail` - the `/api/artifacts/<handle>` shape: the already-validated domain object wrapped with `handle`/`family`. Selects/wraps existing canonical fields only; derives nothing new, recomputes nothing, persists nothing (no `viewer.json`/viewer-manifest/cache artifact of any kind exists anywhere in this batch).
+
+Both are ephemeral: constructed fresh per request, held only in memory for the duration of that request/response.
+
+## 13. Absolute-path exposure policy
+
+Metadata records expose only a root-relative `relativeDir` (POSIX-normalized), never an absolute filesystem path. `/api/status`'s pre-existing `root` field (Batch 1, unchanged) remains the only place an absolute path is echoed back, and only as an opaque display string the server itself supplied - never accepted as input from the browser.
+
+## 14. Media ownership/resolution behavior
+
+`src/viewerServer/evidence/mediaResolver.ts` recognizes exactly three roles: `screenshot` (observation only), `image` (imported external reference only), `source-image` (approved external reference only) - any other role, or a role requested against a family it doesn't apply to, is rejected (`404`). Every resolved path goes through `resolveContainedFile`, which additionally rejects any filename containing a path separator outright (every real media reference is contractually a bare filename - `docs/CONTRACTS.md` "v0.7 Prompt 1" `ExternalReferenceImageReference.path`).
+
+## 15. Approved external-reference source-image behavior
+
+Confirmed via `docs/CONTRACTS.md`/`externalReference.ts` (§3/§5) and proven by a real fixture (`writeExternalReferencePairFixture`, using the actual `importExternalReference`/`approveExternalReference` application services): an approved artifact's directory contains **only** `manifest.json` - no image file. `source-image` resolution reads the approved artifact's `sourceReference.referenceId`, then calls `evidence/index.ts#findImportedReferenceDir` - a bounded search (reusing the same discovery+classify pipeline, capped at `MAX_INDEX_RECORDS`) for the **imported** artifact whose own `referenceId` matches - and only then resolves `sourceReference.image.path` against *that* artifact's real directory. Never assumes co-location. Two tests prove this exactly: "resolves an approved reference's source-image through the owning imported artifact, never assuming co-location" (success case, real cross-artifact resolution) and "an approved reference whose owning imported artifact is absent from the root reports missing media honestly" (the imported artifact deliberately left out of the root - `404`, not a crash or a fabricated image). The full built-CLI smoke test (§20) additionally proves this against the real compiled server.
+
+## 16. Unsupported-version behavior
+
+`classify.ts` compares the candidate's `schemaVersion` against the current canonical constant (`SCHEMA_VERSION`, `COMPARISON_SCHEMA_VERSION`, `CONTRACT_SCHEMA_VERSION`, `EVALUATION_SCHEMA_VERSION`, `EXTERNAL_REFERENCE_SCHEMA_VERSION`) **before** attempting a canonical read, so an unsupported version never even reaches (and is never silently accepted by) the reader/validator pair pinned to the current schema. `/api/index` reports `supportState: 'unsupported-version'` plus both the found and supported version strings; `/api/artifacts/<handle>` refuses to load it (`409`, carrying that same honest metadata) - never coerced into a fabricated current-shape domain object. Proven with a real fixture (`writeUnsupportedVersionManifest`: a genuine `my-frontend-observer/observation` kind at schema `99.0.0`) at the unit level and in the real-Chromium/CLI smoke.
+
+## 17. Malformed/unavailable/missing behavior
+
+Six independent, honestly distinguished states (`ViewerSupportState` in `classify.ts`): `supported`, `unsupported-version`, `invalid-structure` (kind+version match but the canonical validator itself rejects it), `unrecognized-kind` (no known `artifactKind`, including the bounded-agent-context case), `malformed-json` (not valid JSON at all), `unreadable` (stat/read failure or over the size bound). None is ever silently dropped or reinterpreted as `supported`; one malformed/unrelated candidate never erases valid neighboring evidence (`evidenceDiscovery.test.ts`: 6 real pipeline artifacts + 1 malformed all appear in one index response). Missing media is reported per-role (`available: false` with an honest `reason`) rather than as a whole-artifact failure - a genuinely deleted `screenshot.png` still yields a `supported` observation record whose `media` summary honestly says `unavailable`.
+
+## 18. PWA cache verification
+
+No `vite.config.ts`/service-worker configuration change was needed: every new route lives under `/api/`, already covered by Batch 1's `navigateFallbackDenylist: [/^\/api\//]`. Extended `tests/unit/viewerPwaBuild.test.ts` with an explicit Batch 2 assertion against the **real built** `sw.js`: still exactly one `registerRoute` call after the server-side additions, and the precache manifest contains no `/api/index`, `/api/artifacts`, or `/api/media` entry.
+
+## 19. Batch 2 UI changes
+
+`viewer/src/hooks/useEvidenceIndex.ts` (fetches `/api/index`), `useArtifactDetail.ts` (fetches `/api/artifacts/<handle>` only when a handle is selected - never eagerly), `components/EvidenceList.tsx` (bounded list, one item per record, honest support-state label per item), `components/ArtifactPreview.tsx` (loading/loaded/error/unsupported states; a bounded raw-JSON preview of the loaded artifact - explicitly *not* a real visualization). `App.tsx` wires these into the existing Batch 1 shell regions (nav = list, workspace = preview, details aside = selected record's own already-fetched metadata fields - no additional request). No screenshot rendering, SVG overlay, or comparison/contract/reference visualization exists anywhere in `viewer/src/` (verified by a real-Chromium test asserting zero `<img>`/`<svg>` elements after loading a real observation).
+
+## 20. Files created
+
+- `src/viewerServer/evidence/limits.ts`, `discovery.ts`, `classify.ts`, `handles.ts`, `pathSafety.ts`, `projection.ts`, `index.ts`, `mediaResolver.ts`
+- `tests/support/evidenceFixtures.ts` (shared real-evidence fixture builders, reusing the existing writer/application-service functions - mirrors `tests/unit/cliFrontendContracts.test.ts`'s established construction pattern)
+- `tests/unit/evidenceDiscovery.test.ts`, `viewerEvidenceServer.test.ts`
+- `tests/browser/viewerEvidenceShell.test.ts`
+- `viewer/src/hooks/useEvidenceIndex.ts`, `useArtifactDetail.ts`
+- `viewer/src/components/EvidenceList.tsx`, `ArtifactPreview.tsx`
+- `docs/reports/v0.8-evidence-index-readers-batch2.md` (this file)
+
+## 21. Files modified
+
+- `src/viewerServer/httpServer.ts` - added `/api/index`, `/api/artifacts/<handle>`, `/api/media/<handle>/<role>` routing plus shared `writeJsonBody`/`writeJsonError`/`streamFile`/`decodeURIComponentSafe` helpers; existing `/api/status` and static-asset serving unchanged.
+- `viewer/src/App.tsx` - wires the new hooks/components into the existing shell regions.
+- `viewer/src/styles/index.css` - additive rules for the evidence list/preview/details UI.
+- `tests/browser/viewerShell.test.ts` - one pre-existing Batch 1 assertion (`toContain('Evidence navigation will appear here')`, a *static placeholder* string) legitimately no longer holds now that the nav region is live; updated to assert the new, honest "no recognized evidence" message for an empty root - the same kind of sanctioned evolution as Batch 1's own `TST-401` update.
+- `tests/unit/viewerPwaBuild.test.ts` - added the explicit Batch 2 cache-boundary assertion (§18).
+- `docs/ARCHITECTURE.md` - new "v0.8 Batch 2" section.
+- `docs/COMMANDS.md` - `view` section updated to describe the new routes/behavior.
+
+## 22. A production bug found and fixed by real-CLI smoke testing
+
+`src/viewerServer/evidence/pathSafety.ts#resolveContainedDir` originally compared a `path.resolve()`-normalized candidate path against the **un-normalized** `root` string. Every unit test's `root` came from `path.join(tmpdir(), ...)`, which Node already normalizes to the platform separator, masking the bug entirely - all 19 initial `viewerEvidenceServer.test.ts` tests passed. The real built-CLI smoke test (§23), run with `--root` supplied using forward slashes (as a user typing a path in a shell commonly would, even on Windows), reproduced it immediately: every artifact/media request returned `404 unknown handle` even for evidence that genuinely existed. Root-caused via direct `node -e` reproduction against the compiled `dist` output, fixed by resolving `root` itself before the prefix comparison, and covered by a new dedicated regression test (`viewerEvidenceServer.test.ts` "root path normalization" describe block) that deliberately constructs a forward-slash root and asserts a real handle still resolves. This is exactly the kind of defect the task's mandated built-CLI smoke step (§34) exists to catch, and it did.
+
+## 23. Validation results
+
+| Command | Result |
+|---|---|
+| `npm run typecheck` | **PASS** (zero errors, both `tsconfig.json` and `viewer/tsconfig.json`) |
+| `npm run lint` | **PASS** (zero errors/warnings) |
+| `npm test` | **PASS** - 1071/1071 tests, 56/56 files |
+| `npm run build` | **PASS** - unchanged Node/library output plus `dist/viewerServer/evidence/**` and the rebuilt `dist/viewer/**` PWA |
+| `npm run check:docs` | **PASS** - "Documentation check passed (17 required files)." |
+| `npm run test:browser` | **PASS** - 132/132 tests, 12/12 files (real Chromium; run in full, not skipped, per task §33's instruction since this batch directly changes the browser-facing data boundary) |
+| `git diff --check` | **PASS** - no whitespace errors (only expected LF→CRLF line-ending notices) |
+
+## 24. Built viewer Batch 2 smoke (§34)
+
+Fixture: a real evidence root built via a one-off script (not committed; lives under `WORKFLOW_ROOT\tmp`) that calls the actual compiled `dist/artifacts/*Writer.js` and `dist/application/*Service.js` modules directly - the same real writers/services the CLI itself uses - to produce two real observations, a real comparison, a real baseline contract, a real per-change contract, a real evaluation, a real imported external reference (with a real image file), and a real approved external reference, plus a malformed-JSON candidate, an unsupported-future-schema-version candidate, and one unrelated `README.txt`, all under `WORKFLOW_ROOT\smoke\evidence-root`.
+
+Command: `node dist/cli.js view --root "<WORKFLOW_ROOT>\smoke\evidence-root" --port 4319 --no-open`
+
+All required checks (§34), against the real running built server:
+
+- `/api/status` → `200`, correct root echoed.
+- `/api/index` → `200`, all 9 real evidence records present with correct `family`/`supportState`, plus the malformed and unsupported-version candidates shown honestly; response body contains no full-artifact fields (`targetEvidence` etc.) and no `README` reference.
+- Selected supported artifact (`observation:observations%2Fsmoke-obs-before`) loaded on demand via `/api/artifacts/<handle>` → `200` with its full payload.
+- Selected media loaded on demand: observation `screenshot` → `200 image/png`; imported reference `image` → `200 image/png`; **approved reference `source-image` → `200 image/png`, resolved through the separate imported artifact's directory** (§15/§22).
+- Unsupported-version and malformed candidates both correctly refused at `/api/artifacts/<handle>` → `409` (not fabricated as loaded).
+- Unrelated `README.txt` never appears in `/api/index` and is not directly servable (`GET /README.txt` → `404`).
+- Path-traversal attempt (`/api/artifacts/observation:..%2F..%2Fetc`) → `404`.
+- Absolute-path-shaped handle attempt → `404`.
+- PWA still loads: `/` → `200`, `/manifest.webmanifest` → `200`, `/sw.js` → `200`.
+- `netstat` confirmed the listener bound to `127.0.0.1:4319` only (never `0.0.0.0`).
+- Server located by its real PID via `netstat` and terminated with `taskkill /F`; a follow-up `netstat` confirmed the port was released and no server process remained.
+- A post-run directory listing of the smoke evidence root shows exactly the fixture's own files - no stray `.tmp-*` write-in-progress directories, no modified/deleted files.
+
+**Result: PASS.** Logs retained under `WORKFLOW_ROOT\logs\` (`smoke-server.log`, `smoke-server-2.log` [post-fix rerun], `index-response.json`, `index-response-2.json`, `smoke-checks-final.log`).
+
+## 25. Existing command regression check
+
+`observe`, `compare`, `approve-baseline`, `save-change-contract`, `evaluate-contract`, `import-reference`, `approve-reference`, `evaluate-reference-fidelity`, Batch 1 `view` startup, PWA shell, fixed host/port behavior, and the PWA cache boundary all remain covered by their existing, unmodified test suites (all 1071 unit + 132 browser tests pass - §23). Canonical v0.1-v0.7 semantics were not touched anywhere in this batch's diff; `src/domain/`, `src/artifacts/*Writer.ts`, and every existing reader are byte-for-byte unchanged.
+
+## 26. Generated path inventory
+
+| Path | Disposition |
+|---|---|
+| `WORKFLOW_ROOT\cache\npm` | Retained (npm cache from the my-dev-kit-index `npx` invocation; harmless, reusable) |
+| `WORKFLOW_ROOT\tmp\vite-cache`, `WORKFLOW_ROOT\tmp\build-smoke-evidence.mjs` | Retained (build cache dir was empty again, same as Batch 1 - Vite build mode doesn't populate it; the smoke-fixture script is dev/readiness tooling only, not committed) |
+| `WORKFLOW_ROOT\logs\*` | Retained (smoke evidence - §24) |
+| `WORKFLOW_ROOT\smoke\evidence-root` | Retained (real evidence fixture tree built for the smoke test - §24) |
+| `WORKFLOW_ROOT\my-dev-kit-index\*` | Retained (successful index + cache-metadata from §4) |
+| `WORKFLOW_ROOT\{fixtures,candidate,pack}` | Retained, empty/unused this batch (no `npm pack`/candidate-install step was needed since no packaging-boundary change occurred beyond the existing `dist` allowlist) |
+| Repo-root `dist/` | Ordinary build output (gitignored); rebuilt cleanly by `scripts/clean.mjs` on every `npm run build` |
+| Pre-existing repo-root `.my-dev-kit*`/`baselines`/`comparisons`/`contracts`/`evaluations`/`observations` | Pre-existing, empty, untouched (same finding as the Batch 1 report) |
+
+`Z:\Users\newuser\Projects\my-frontend-observer.my-dev-kit-workflow\v0.8\batch-01` was never targeted by any command in this session (verified) - preserved exactly as Batch 1 left it.
+
+## 27. Repository pollution check
+
+`git status --short` before staging showed only the seven modified + eight new Batch-2-owned paths listed in §20/§21 (plus their containing directories). No unexpected file or directory appeared anywhere in the repository as a result of this batch's work.
+
+## 28. Skipped work / deviations
+
+- None. Every task step (my-dev-kit retrieval, all six required test categories, the full validation chain including `test:browser`, and the built-CLI smoke) was executed, not skipped or substituted.
+
+## 29. Remaining uncovered risks
+
+- **`findImportedReferenceDir` re-walks the evidence tree per `source-image` request** rather than reusing a cached index (by design - no persistent cache exists, per task §30). For an evidence root at the bound edge (near `MAX_MANIFEST_CANDIDATES`), an approved-reference-heavy workload would re-pay that walk cost on every source-image request. Not a correctness risk; a potential future performance consideration only if real usage ever approaches the bound (task §30 explicitly says to report rather than pre-optimize).
+- **The bounded-agent-context "unrecognized-kind" classification is asserted only at the unit level**, not against a real persisted fixture (none exists to build, by design - §5). The behavior is exercised with a hand-written manifest declaring that kind, which is the most realistic proof achievable without inventing persistence for a family that has none.
+- Batch 1's previously reported risks (install-prompt "available" branch, live service-worker execution) remain unresolved and out of this batch's scope.
+
+## 30. Out-of-scope confirmation
+
+Confirmed absent from this batch's diff: target SVG overlays, screenshot geometry rendering, runtime target inspection UI, relationship/scroll visualization, before/after visual comparison, contract/change-scope visualization, external-reference/candidate side-by-side visual inspection, region/target overlays, explicit-binding cross-selection, zoom/pan, synchronized lock, on-demand fidelity computation, bounded-agent-context visual inspection, correlation UI, arbitrary filesystem navigation, annotation, region/requirement authoring, source editing, automatic binding/target discovery, pixel-diff scoring, computer vision, cloud hosting, database, authentication, collaboration. `ArtifactPreview.tsx`'s raw-JSON preview is explicitly not a visualization (no image, no SVG, no geometry rendering - proven by the zero-`<img>`/zero-`<svg>` browser assertion, §19).
+
+## 31. Final verdict
+
+Batch 2 ("Evidence indexing, canonical readers, and lazy data boundary") is implemented and independently validated: a built candidate's viewer can enumerate real recognized evidence from bounded metadata, load one selected artifact on demand through its existing canonical validation boundary, load its owned/referenced media safely (including the cross-artifact approved-reference case), and visibly distinguish malformed/unsupported/missing evidence rather than silently dropping it - proven at the unit, real-Chromium, and real-built-CLI-smoke levels, with one genuine cross-platform path-handling defect found and fixed along the way. No Batch 3+ visualization, no v0.9 annotation, and no release/publication action was taken. Package version remains `0.7.0`.