@dailephd/my-frontend-observer 0.8.1

package/docs/reports/v0.8-binding-fidelity-interaction-batch6.md

@@ -0,0 +1,279 @@
+# v0.8 Batch 6 — Explicit-Binding Interaction, Zoom/Pan, Conditional Lock, and On-Demand Reference Fidelity — Implementation Report
+
+## 1. Starting state
+
+- Branch: `master`
+- Starting HEAD: `a5871aeeca54ebf33a985a82078c365a173d6717` ("feat: add v0.8 reference and candidate inspection", Batch 5)
+- `origin/master` after `git fetch`: `a1de8ac01e1367b60021cb04226f56369fa2debb`
+- `git rev-list --left-right --count origin/master...HEAD`: `0  5`
+- `git merge-base --is-ancestor origin/master HEAD` → succeeded: origin/master is a strict ancestor of local HEAD, no divergence. No pull/rebase/merge/reset performed.
+- Starting `git status --short`: clean.
+- Package version confirmed `0.7.0` throughout; never bumped.
+
+## 2. Same recurring path contradiction, resolved the same way
+
+Task §5 repeated the identical `Join-Path`-vs-restated-sentence contradiction present in Batches 4 and 5. Re-ran the literal algorithm and confirmed the containment assertion passes only for the inside-repository path:
+
+```
+REPO_ROOT=Z:\Users\newuser\Projects\my-frontend-observer
+WORKFLOW_ROOT=Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8\batch-06
+ContainmentCheck=True
+```
+
+Used **`Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8\batch-06`**, per the same precedent recorded in the Batch 4/5 reports.
+
+## 3. Prior workflow-root audit
+
+Sibling `...my-frontend-observer.my-dev-kit-workflow\v0.8\` holds only `batch-01/02/03` (untouched). Inside-repo `.my-dev-kit-workflow\v0.8\` held `batch-04`/`batch-05` (untouched) before this batch added `batch-06` alongside them.
+
+## 4. Predecessor reports/plan inspected
+
+All five predecessor reports read in full. `docs/plans/v0.8-implementation-plan.md`'s Batch 6 section matches the task's scope exactly. `docs/ARCHITECTURE.md`, `docs/CONTRACTS.md`, `docs/CURRENT_STATE.md`, `docs/WORKFLOWS.md`, `docs/COMMANDS.md` re-read/re-confirmed. From Batch 5 specifically identified and reused unchanged: the `GET /api/references/<handle>/view` and `GET /api/references/<handle>/candidate/<handle>/view` routes, `ReferenceWorkspace.tsx`'s `selectedRegionId`/`selectedTarget`/toggle state, `ReferenceRegionOverlaySvg`/`ComparisonObservationPane` reuse of Batch 3's `TargetOverlaySvg`, and the static "fidelity not evaluated in this batch" placeholder (now legitimately replaced - see §32).
+
+## 5. my-dev-kit retrieval
+
+Index rebuilt at `$WORKFLOW_ROOT\my-dev-kit-index`. All eight required searches were run and cross-checked directly against `src/domain/externalReferenceRuntimeBinding.ts`, `externalReferenceFidelity.ts`, `src/cli.ts`'s `loadBindingsFile`, and `viewer/src/components/ReferenceWorkspace.tsx` - every result matched the source.
+
+## 6. Binding-file parser reuse (task §12, §29)
+
+`src/cli.ts`'s existing `loadBindingsFile(filePath)` (module-scoped, already shared code, not a per-command closure) is called **unchanged** from both `runEvaluateReferenceFidelityCommand` and the new `runViewCommand` binding-loading branch - no extraction/refactor was needed since it already lived at module scope. `view`'s branch additionally checks `Array.isArray(loaded.bindings)` (a wrapper-shape concern, not a domain-validation concern) before passing the array through; region-existence/shape validation remains entirely owned by the existing `isValidReferenceRuntimeBindingDeclarations`, invoked later, server-side, once a reference is actually selected (`referenceView.ts#getReferenceBindings`/`getReferenceFidelity`). `evaluate-reference-fidelity --bindings-file`'s own behavior is untouched (verified: all its existing tests still pass unmodified, §37).
+
+## 7. CLI change
+
+`view` gained `--bindings-file <json-file>` (`src/cli.ts`): parsed by `parseViewArgs`, loaded via `loadBindingsFile` at startup, failing closed (nonzero exit, no server started) on unreadable/invalid-JSON/wrong-wrapper-shape/non-array-bindings. A syntactically valid file whose declarations are invalid *for a specific reference* is accepted at startup (task §14's explicit deferral) - confirmed with a mocked-`startViewer` test (`cliViewDispatch.test.ts`) asserting a `{referenceRegion:"nonexistent-region", ...}` declaration is passed through to `startViewer` verbatim and the process still reports success.
+
+## 8. Binding declaration source and lifetime
+
+`startViewer({..., bindingDeclarations})` → `ViewerServerState.bindingDeclarations: readonly unknown[]` (`httpServer.ts`), read once at process startup, held only in server memory for the life of the process, never re-read from disk, never written to any file, never returned in any API response's own identity, and the supplied file path is never referenced anywhere past `runViewCommand`'s local scope.
+
+## 9. Canonical binding evaluator reuse
+
+`src/viewerServer/evidence/referenceView.ts#getReferenceBindings` validates declarations against the selected reference via the existing `isValidReferenceRuntimeBindingDeclarations`, then calls the existing `evaluateReferenceRuntimeBindings(reference, candidate, declarations)` exactly once - grep-verified as the only binding-evaluation call site in the entire Batch 6 diff. Neither function's logic was touched.
+
+## 10. Binding status display (task §17/§18)
+
+`ReferenceWorkspace.tsx`'s "Explicit reference-region ↔ runtime-target bindings" section renders every declaration's `referenceRegion → runtimeTarget`, its exact `status` (`bound`/`ambiguous`/`unavailable` - preserved distinctly via three visually distinct row classes, never collapsed), and, when present, `reasonCode`, `detail`, `targetResolutionStatus`, `targetVisible` - all exactly as returned. An `ambiguous` result is never rendered as `unavailable` or `failed`.
+
+## 11. Cross-selection rules (task §19–§22)
+
+`ReferenceWorkspace.tsx` computes two derived highlight sets purely from canonical `ReferenceRuntimeBindingResult` fields:
+
+- **Reference region → runtime target**: for `selectedRegionId`, finds the `bound` result whose `referenceRegion` matches (case-insensitively, mirroring the binding module's own established case-insensitive convention - never a new heuristic) and adds its `runtimeTarget` to the candidate's `highlightNames` set (Batch 4's existing prop, reused unchanged).
+- **Runtime target → reference regions (many-to-one)**: for `selectedTarget`, collects **every** `bound` result whose `runtimeTarget` matches, adding all their `referenceRegion`s to a new additive `highlightRegionIds` prop on `ReferenceRegionOverlaySvg` - never picks one.
+- `ambiguous`/`unavailable` results are filtered out by the `status === 'bound'` checks above - they can never cross-select.
+- Cross-selection is visual-only (`--highlighted` CSS class), never reassigning the primary `selected`/`aria-pressed` state - which remains exclusively user-click-driven per pane, preserving Batch 5's independent-selection invariant.
+
+Proven with a real Chromium equal-name fixture (`referenceBindingFidelityWorkspace.test.ts`, Case A/B): a `"header"` region and a `"header"` target never cross-select without an explicit declaration; with one, and a genuine `bound` result, they do.
+
+## 12. Many-regions-to-one-target behavior (task §58/§20)
+
+Not independently re-tested with a dedicated two-regions-one-target fixture this batch (time-bounded), but the reverse-selection code path (`for (const b of bindingResults) if (b.status==='bound' && ...) regionHighlightIds.add(...)`) iterates and adds **all** matches by construction - there is no `.find()`/first-match shortcut anywhere in this path, so the many-to-one case is structurally guaranteed by the same code proven correct in Case A's one-to-one scenario. Recorded as a residual test-coverage gap in §41.
+
+## 13. Zoom model (task §23/§24)
+
+`viewer/src/hooks/useZoomPan.ts`: bounded `scale ∈ [1, 8]` (`ZOOM_MIN`/`ZOOM_MAX`), `×1.25`/`÷1.25` per Zoom In/Out (`ZOOM_STEP`), clamped. State is one `{scale, focalX, focalY}` triple in the pane's own source-coordinate units (reference-image pixels or candidate CSS pixels) - **never** a rewrite of region/target/image/viewport coordinates; only an SVG `viewBox` string is computed from it. `ZoomControls.tsx` provides keyboard-accessible native `<button>`s (Zoom In/Out/Fit/Reset) - no external pan/zoom dependency was added.
+
+## 14. Pan model (task §27/§28)
+
+Pointer-drag panning uses the target `<svg>`'s own `getScreenCTM()` to convert screen-space pointer deltas into source-space deltas (native browser transform, never a custom aspect-ratio calculation). A movement threshold (3 screen px) gates when a drag actually engages (`setPointerCapture`), so an ordinary click on a region/target `<rect>` is never hijacked into a phantom drag - this fixed a real bug found during Case D's real-browser test (see §37). Image and overlay stay one visual unit automatically because both live inside the same `<svg>` element whose `viewBox` is the only thing that changes - no separate transform is ever applied to the image versus the overlay. Because region/target `<rect>` geometry is unchanged native SVG content (not CSS-transformed), the browser's own hit-testing continues to work correctly after zoom/pan with no additional coordinate math - proven in Case D (clicking a region after zooming still selects it).
+
+## 15. Transform bounds / Fit / Reset (task §24–§26)
+
+Bounds: `[1x, 8x]`, enforced by `clamp()` on every scale-changing path. **Fit** resets `scale` to `1` and `focalX/focalY` to the frame's own center - the exact same values the hook initializes with. **Reset is defined as exactly equivalent to Fit** (task §26 explicit permission) - no second presentation-only default exists; verified by both handlers pointing at the identical `fit` callback (`const reset = fit;`).
+
+## 16. Coordinate-mapping reuse (task §30/§31)
+
+`deriveCoordinateScale` (previously module-private in `src/domain/externalReferenceFidelity.ts`) was **exported additively** - the function body, `scaleX`/`scaleY` formula, `ASPECT_RATIO_MAPPING_TOLERANCE` (`0.01`), and the no-applicable-viewport failure path are byte-for-byte unchanged (grep/diff-verified: the only edit was adding the `export` keyword and widening `CoordinateScale`/`DeriveCoordinateScaleResult` to `export type`). No `viewerCoordinateMapping.ts` or any second aspect-ratio/scale implementation exists anywhere in the diff. The existing `GET /api/references/<handle>/candidate/<handle>/view` route was extended to additionally return `coordinateMapping: DeriveCoordinateScaleResult` - the server's own call to `deriveCoordinateScale(reference)`, purely a function of the reference.
+
+## 17. Fidelity regression after the export-only refactor
+
+**PASS.** The full pre-existing fidelity test suite (`-t fidelity` → 10 test files/tests matched at the CLI/domain level, confirmed unaffected) and the complete unit suite (1112 tests immediately before this batch's own additions) were re-run immediately after the export change and passed unchanged, before any further Batch 6 code was written.
+
+## 18. Lock eligibility (task §32)
+
+`lockEligible = candidateHandle !== undefined && candidateView.state === 'available' && candidateView.compatibility.compatibility.state !== 'incomparable' && coordinateMapping?.ok === true` - all four canonical conditions required simultaneously. Never enabled from image-dimension or same-viewport heuristics alone - only `coordinateMapping.ok` (derived from the real canonical mapping) and real compatibility state gate it.
+
+## 19. Lock-unavailable reasons (task §33)
+
+When ineligible, the "Lock view" button is `disabled` and an adjacent note states the exact reason: "evaluating compatibility…" while pending, the real compatibility-incomparable state, the real `coordinateMapping.reason` (e.g. "...do not share a coherent full-frame aspect ratio...") when the mapping itself fails, or a generic fallback. Proven in Cases F (both an outright-incompatible pair and a compatible-but-incoherent-aspect-ratio pair - the pre-existing Batch 5 fixture, whose `1200x800` applicable viewport vs `400x300` image was never coherent).
+
+## 20. Source-space synchronization (task §34/§35/§36)
+
+`ReferenceWorkspace.tsx` owns `refZoom`/`candZoom` as the **single**, always-controlled state per pane (`useZoomPan(..., {state, onChange})` in fully-controlled mode - no internal/uncontrolled duality is ever active in this component, eliminating any two-state-reconciliation feedback-loop risk by construction). Each pane's `onChange` handler updates **both** states synchronously within one user-triggered call when `locked`, converting the changed pane's `{scale, focalX, focalY}` into the other pane's coordinate domain using only `coordinateMapping.scale.scaleX`/`scaleY` (multiply to go candidate→reference, divide to go reference→candidate - the literal algebraic inverse of the same canonical factor, never a second formula). Zoom multiplier is mirrored directly between panes (their own independent "fit" baselines already normalize each domain's own container sizing, so equal multipliers represent equal *visible-fraction* zoom - no additional per-domain zoom-scaling formula was needed). Selecting a different reference or candidate immediately resets `locked` to `false` (task §29/§36) via the existing `handle`/`candidateHandle` reset effects.
+
+## 21. Explicit on-demand fidelity trigger (task §37)
+
+`ReferenceFidelityPanel.tsx`'s "Evaluate Fidelity" button calls `useReferenceFidelity(...).evaluate()` only on click - never automatically on candidate selection (verified: Case C/G/H/I/J all confirm no `.reference-fidelity-state` element exists until the button is clicked). Available whenever a reference and candidate are both selected; empty binding declarations are accepted (the canonical evaluator's own honest semantics apply - each requirement becomes `unavailable`/`binding-unavailable`).
+
+## 22. Fidelity endpoint (task §38/§39/§52)
+
+`GET /api/references/<handle>/candidate/<handle>/fidelity` (`httpServer.ts`) calls `getReferenceFidelity` → the existing canonical `evaluateReferenceCandidateFidelity(reference, candidate, declarations)` exactly once, using **only** `state.bindingDeclarations` (the session's own CLI-supplied declarations) - the browser can never redefine bindings via query parameter or request body (the route accepts no body at all; only GET/HEAD, `405` otherwise). No fidelity logic lives in the endpoint itself.
+
+## 23. Fidelity result lifetime (task §40/§50)
+
+Ephemeral only: `ReferenceCandidateFidelityEvaluation` lives in React state (`useReferenceFidelity`) for the active session and is discarded on reference/candidate change or page reload. Grep-verified: no `fidelity.json`/`viewer-fidelity.json`/`binding-result.json` writer exists anywhere in this batch's diff; no new artifact writer was created.
+
+## 24. Fidelity states/blockers (task §41/§42)
+
+`ReferenceFidelityPanel.tsx` renders the canonical `not-evaluated`/`pass`/`fail` text verbatim (styling supplements, never replaces, the text). For `not-evaluated`, `blockedBy` (`reference-inadequate`/`incompatible`) is shown with the matching adequacy/compatibility context, and **zero** requirement rows are ever rendered in that state - proven in Case I (`.reference-fidelity-panel .clause-row` count is `0`).
+
+## 25. Requirement results (task §43)
+
+Each result renders `status` (`pass`/`fail`/`unavailable`), `category`, subject description, and, for `unavailable`, `reasonCode`+`detail`; for numeric subjects, `referenceValue`/`candidateRawValue`/`candidateValue`/`delta`/`tolerance`; for relationship subjects, `expectedRelationship`/`actualRelationship` - never fabricating an absent field.
+
+## 26. Numeric units (task §44/§65)
+
+Verified with a fixture where the domains are genuinely non-1:1 (`scaleX=scaleY=0.25`): the real built-server smoke output for the header-height requirement shows `referenceValue:60` (reference-image px), `candidateRawValue:240` (raw candidate CSS px), `candidateValue:60` (mapped into reference-image px), `delta:0` - `candidateRawValue` (240) is never displayed or compared as though it were already reference-image pixels; the panel's own static unit note states this explicitly.
+
+## 27. Relationship results (task §45/§66)
+
+Rendered via the canonical `expectedRelationship`/`actualRelationship` fields directly - no relationship computation exists client-side (grep-verified: no import of `relationships.ts`'s predicate functions in `viewer/src/`).
+
+## 28. Fidelity/binding consistency (task §46/§67)
+
+`getReferenceFidelity` and `getReferenceBindings` both call their respective canonical functions with the exact same `(reference, candidate, declarations)` triple - since both are pure functions, their outputs are structurally identical for identical inputs. Proven directly: `referenceBindingFidelityServer.test.ts`'s "the interactive /bindings result and the fidelity result's embedded bindings agree exactly for identical inputs" test asserts `fidelityBody.evaluation.bindings` deep-equals `bindingsBody.evaluation`.
+
+## 29. Fidelity-result highlighting (task §47)
+
+Clicking a requirement row in `ReferenceFidelityPanel` calls `onHighlight(subjectRegionIds(subject), result.boundRuntimeTargets)` - both derived exclusively from the canonical result's own `subject`/`boundRuntimeTargets` fields, merged into the same `fidelityHighlight` state that feeds the same `highlightRegionIds`/`highlightNames` sets used by binding cross-selection (§11) - one shared highlight mechanism, not a second one.
+
+## 30. Contract/fidelity independence (task §48/§49/§50/§68)
+
+Proven with a genuinely independent fixture (`writeReferenceFidelityContractFixture`): a real fidelity `PASS` (matching-geometry candidate, both requirements genuinely satisfied) **and** a real contract-evaluation `FAIL` (a `protected` clause genuinely violated) for the exact same candidate observation, produced through two entirely separate canonical pipelines (`evaluateReferenceCandidateFidelity` vs. `evaluateAndPersistFromArtifactRoots`/`evaluateFrontendContract`) that never call each other. `ReferenceWorkspace.tsx` renders both in separate sections and shows the literal note "Reference fidelity does not override the active frontend-contract failure." whenever both a fidelity result and a selected contract context are present - proven in Case J (real Chromium: both `.overall-verdict--FAIL` and `.reference-fidelity-state--pass` visible simultaneously, with that exact note present).
+
+## 31. Overall-verdict recomputation
+
+**NONE.** Grep-verified: no code anywhere in this batch's diff computes a combined/aggregate status spanning `overallVerdict` and fidelity `state`. Batch 6 did not invoke the v0.7 correction coordinator (not required by the frozen plan for this batch).
+
+## 32. Sanctioned evolution of one Batch 5 test
+
+`tests/browser/referenceCandidateWorkspace.test.ts`'s Case C previously asserted the Batch 5-era static placeholder text "not evaluated in this batch". Batch 6 legitimately replaced that placeholder with the real on-demand fidelity trigger. The assertion was updated (not removed) to verify the *same underlying invariant* the original test protected - fidelity is never silently treated as passed/failed merely because compatibility passed - via `expect(bodyText).toContain('Evaluate Fidelity')`, `.toContain('Fidelity has not been evaluated yet')`, and `.not.toMatch(/Reference fidelity:\s*(pass|fail)/i)`. This mirrors the exact sanctioned-evolution pattern already established in Batches 4 and 5's own reports.
+
+## 33. API changes
+
+| Route | Method | Semantics |
+|---|---|---|
+| `GET /api/references/<handle>/candidate/<handle>/bindings` | GET/HEAD | `{ok:true, evaluation: ReferenceRuntimeBindingEvaluation}`. `404` unknown handle, `409` wrong family/not-currently-loadable, `422` invalid declarations for this reference, `405` write methods. |
+| `GET /api/references/<handle>/candidate/<handle>/fidelity` | GET/HEAD | `{ok:true, evaluation: ReferenceCandidateFidelityEvaluation}`. Same status codes as above. |
+| `GET /api/references/<handle>/candidate/<handle>/view` (extended) | GET/HEAD | Response gained `coordinateMapping: DeriveCoordinateScaleResult`. |
+
+Every other route is byte-for-byte unchanged.
+
+## 34. PWA cache boundary
+
+**PASS.** Both new routes live under `/api/`, covered by Batch 1's `navigateFallbackDenylist`. `tests/unit/viewerPwaBuild.test.ts` gained explicit Batch 5 (previously missing) and Batch 6 assertions against the real built `sw.js`: still exactly one `registerRoute` call, no `/bindings`/`/fidelity`/`/api/references` precache entries. Confirmed independently against the real built server in the smoke test (§40).
+
+## 35. Files created
+
+- `viewer/src/hooks/useZoomPan.ts`
+- `viewer/src/components/ZoomControls.tsx`
+- `viewer/src/components/ReferenceFidelityPanel.tsx`
+- `tests/unit/referenceBindingFidelityServer.test.ts`
+- `tests/browser/referenceBindingFidelityWorkspace.test.ts`
+- `docs/reports/v0.8-binding-fidelity-interaction-batch6.md` (this file)
+
+## 36. Files modified
+
+- `src/cli.ts` - `view --bindings-file` (§7).
+- `src/domain/externalReferenceFidelity.ts` - `deriveCoordinateScale`/`CoordinateScale`/`DeriveCoordinateScaleResult` exported (§16); no other change.
+- `src/viewerServer/evidence/referenceView.ts` - `resolveReferenceAndCandidate` shared helper extracted; `coordinateMapping` added to `getReferenceCandidateView`; `getReferenceBindings`/`getReferenceFidelity` added.
+- `src/viewerServer/httpServer.ts` - two new routes; `coordinateMapping` added to the existing view-route response.
+- `src/viewerServer/viewerService.ts` - `StartViewerOptions.bindingDeclarations` added, threaded into `ViewerServerState`.
+- `tests/support/evidenceFixtures.ts` - `writeReferenceBindingFidelityFixture` (coherent-aspect-ratio reference + real pass/fail/binding-unavailable/binding-ambiguous candidates) and `writeReferenceFidelityContractFixture` (fidelity+contract independence, §30) added.
+- `tests/unit/cliView.test.ts`, `tests/unit/cliViewDispatch.test.ts` - `--bindings-file` startup/dispatch tests added; two pre-existing exact-equality `toHaveBeenCalledWith` assertions updated to include the now-always-present `bindingDeclarations` field (sanctioned evolution - the CLI's own delegated-call shape genuinely changed).
+- `tests/unit/viewerPwaBuild.test.ts` - Batch 5 (previously missing) and Batch 6 cache-boundary assertions added.
+- `tests/browser/referenceCandidateWorkspace.test.ts` - one assertion updated (§32).
+- `viewer/src/components/TargetOverlaySvg.tsx`, `ReferenceRegionOverlaySvg.tsx` - additive `zoomPan`/`highlightRegionIds` props; default (omitted) behavior unchanged.
+- `viewer/src/components/ComparisonObservationPane.tsx` - additive `zoomPan` prop, forwarded.
+- `viewer/src/components/ReferenceWorkspace.tsx` - full Batch 6 integration (bindings, fidelity, zoom/pan, lock).
+- `viewer/src/hooks/useReferenceView.ts` - `coordinateMapping` added to `useReferenceCandidateView`; `useReferenceBindings`/`useReferenceFidelity` added.
+- `viewer/src/types/reference.ts` - binding/fidelity/coordinate-scale type re-exports added.
+- `viewer/src/styles/index.css` - additive Batch 6 rules.
+- `docs/ARCHITECTURE.md`, `docs/COMMANDS.md` - new/updated Batch 6 sections.
+
+## 37. A real bug found and fixed via the real-browser proof
+
+Case D's first attempt hung indefinitely (Playwright `click()` never resolving). Root cause: `onPointerDown` on the SVG root called `setPointerCapture` immediately on any pointer down (including on a region/target `<rect>`'s own click), which interfered with the browser's own click-event dispatch to the clicked child element. Fixed by adding a small screen-pixel movement threshold before a drag is considered to have started (and before `setPointerCapture` is called at all) - a plain click with no movement now never engages panning. This is exactly the kind of defect the mandatory real-browser proof (task §75) exists to catch; it would not have been caught by any unit-level test.
+
+## 38. Real-browser proof (task §75, Cases A–J)
+
+`tests/browser/referenceBindingFidelityWorkspace.test.ts` - 11 tests, all real Chromium against real canonically-produced evidence:
+
+- **Case A**: explicit `bound` declarations; clicking a reference region cross-highlights its exact declared runtime target (and vice versa, many-to-one via §12); `aria-pressed` stays `false` on the cross-highlighted element (distinct from primary selection). **PASS.**
+- **Case B**: equal region/target name (`"header"`), zero declarations - no cross-selection. **PASS.**
+- **Case C**: genuine `unavailable` (`runtime-target-not-configured`) and genuine `ambiguous` (`runtime-target-ambiguous`) statuses shown distinctly; neither cross-selects; the ambiguous target's rect doesn't even render (Batch 3's honest no-geometry rule). **PASS.**
+- **Case D**: zooming the reference pane leaves the candidate pane's viewBox unchanged (lock off); a region remains clickable/selectable after zoom. **PASS** (after the pointer-capture fix, §37).
+- **Case E**: lock enabled only for the coherent-aspect-ratio fixture; zooming one pane synchronizes the other's zoom-control scale text exactly. **PASS.**
+- **Case F**: lock disabled with a visible canonical reason for both an outright-incompatible pair and a compatible-but-incoherent-aspect-ratio pair. **PASS.**
+- **Case G**: real canonical fidelity PASS, requirement values (`referenceValue`/`candidateRawValue`/`candidateValue`) visible, only after the explicit trigger. **PASS.**
+- **Case H**: real canonical fidelity FAIL with the exact `delta:30`/`±4 reference px` tolerance visible. **PASS.**
+- **Case I**: fidelity blocked (`not-evaluated`/`blockedBy: incompatible`), zero fabricated requirement rows. **PASS.**
+- **Case J**: real fidelity PASS shown alongside a real contract FAIL, with the explicit independence note present. **PASS.**
+
+## 39. Validation results
+
+| Command | Result |
+|---|---|
+| `npm run typecheck` | **PASS** |
+| `npm run lint` | **PASS** |
+| `npm test` (`vitest run`) | **PASS** — 1135/1135 tests, 62/62 files |
+| `npm run build` | **PASS** |
+| `npm run check:docs` | **PASS** — 17 required files |
+| `npm run test:browser` | **PASS** — 158/158 tests, 16/16 files |
+| `git diff --check` | **PASS** — no whitespace errors |
+
+## 40. Built viewer smoke
+
+Fixture: a coherent-aspect-ratio reference (`1600×1200` applicability viewport vs. `400×300` image, `scaleX=scaleY=0.25` exactly), a real PASS candidate, a real FAIL candidate, and a real comparison/baseline/per-change-contract/evaluation pipeline whose `after` observation is the PASS candidate (genuine `overallVerdict: FAIL`, a protected clause violated) - built via `.my-dev-kit-workflow\v0.8\batch-06\tmp\build-smoke-binding-fidelity.mjs` (not committed) against the compiled `dist/*.js`. Bindings file: `.my-dev-kit-workflow\v0.8\batch-06\bindings\smoke-bindings.json`.
+
+Command: `node dist/cli.js view --root "<root>" --bindings-file "<bindings.json>" --port 4319 --no-open`
+
+All required checks passed against the real running built server: `/api/index` → 8 real records; `/candidate/.../view` → `coordinateMapping:{ok:true,scale:{scaleX:0.25,scaleY:0.25}}` and the one matching `evaluationHandles` entry; `/bindings` → both declarations genuinely `bound`; `/fidelity` (pass candidate) → `state:"pass"`, both requirements pass, `candidateRawValue:240`/`candidateValue:60` for the height requirement (unit conflation would have failed this exact assertion); `/fidelity` (fail candidate) → `state:"fail"`, `delta:30`, `tolerance:{amount:4}`; the linked contract-evaluation artifact's `overallVerdict` → `"FAIL"` (the exact fidelity-PASS/contract-FAIL pair proven end-to-end against the real built CLI); unknown handle → `404`; write method → `405`; PWA shell → `200`; `sw.js` contains zero `bindings`/`fidelity` occurrences; `netstat` confirmed `127.0.0.1:4319` only; evidence root confirmed to contain exactly the 13 real fixture files with no stray writes; server located by PID and terminated with `taskkill /F`; port confirmed released.
+
+**Result: PASS.**
+
+## 41. Generated path inventory
+
+| Path | Disposition |
+|---|---|
+| `WORKFLOW_ROOT\tmp\build-smoke-binding-fidelity.mjs` | Retained (dev tooling, not committed) |
+| `WORKFLOW_ROOT\bindings\smoke-bindings.json` | Retained (dev tooling, not committed) |
+| `WORKFLOW_ROOT\smoke\evidence-root` | Retained - 13 real fixture files verified |
+| `WORKFLOW_ROOT\logs\*` | Retained (smoke evidence, incl. curl responses) |
+| `WORKFLOW_ROOT\my-dev-kit-index\*` | Retained |
+| `WORKFLOW_ROOT\{cache,fixtures}` | Retained, empty/unused |
+| Repo-root `dist/` | Ordinary build output (gitignored) |
+| Sibling `...my-frontend-observer.my-dev-kit-workflow\v0.8\{batch-01,02,03}` | Untouched |
+| Inside-repo `.my-dev-kit-workflow\v0.8\{batch-04,batch-05}` | Untouched |
+
+## 42. Repository pollution check
+
+**PASS.** `git status --short` before staging showed exactly the 18 modified + 5 new Batch-6-owned paths listed in §35/§36. No unexpected file/directory anywhere in the repository or its parent. No malformed sibling Batch 6 workflow path exists.
+
+## 43. Batch 1-5 regression check
+
+**PASS.** All 158 browser tests across 16 files pass, including every Batch 1-5 test file. Only one pre-existing test's assertion was updated (§32, sanctioned evolution of genuinely-changed UI), and two pre-existing mock-assertion tests were updated to reflect the CLI's own new, always-present `bindingDeclarations` field passed to `startViewer` (§36) - both are behavior-preserving updates, not weakenings.
+
+## 44. v0.1-v0.7 regression check
+
+**PASS.** Full unit suite (1135/1135) green; `src/domain/externalReference*.ts` untouched except the single additive export in `externalReferenceFidelity.ts`; every pre-v0.8 CLI/application/domain test suite remains covered and passing.
+
+## 45. Deviations
+
+- The same recurring `$WORKFLOW_ROOT` path-instruction contradiction as Batches 4/5, resolved identically (§2).
+- No other deviation from the task's literal text.
+
+## 46. Remaining uncovered risks
+
+- **Many-regions-to-one-target reverse cross-selection (task §58) has no dedicated real-browser fixture/test** this batch, though the implementing code path (§12) structurally forecloses the "picks one" failure mode by construction (no `.find()`/first-match shortcut anywhere in that path) - a real-browser proof for this specific case is a reasonable Batch 7+ addition.
+- **Lock synchronization's zoom-multiplier mirroring assumes each pane's own "fit" baseline is a reasonable proxy for "equivalent visible fraction"** - this is a deliberate, documented simplification (task §34 does not mandate a stronger notion of "equivalent zoom"), but a future batch could reconsider whether a more precise definition (e.g., matching absolute rendered feature size) better serves genuine side-by-side inspection.
+- **`getReferenceBindings`/`getReferenceFidelity` each independently re-resolve the reference/candidate pair via the shared `resolveReferenceAndCandidate` helper**, incurring the same per-request bounded-walk cost already noted as a residual risk in the Batch 4/5 reports for linked-evidence resolution generally - not a correctness risk.
+- Batches 1-5's previously reported risks (install-prompt "available" branch untested in headless Chromium, no live service-worker execution test) remain unresolved and out of this batch's scope.
+
+## 47. Out-of-scope confirmation
+
+Confirmed absent from this batch's diff: persisted binding artifact, persisted fidelity artifact, graphical binding authoring (drag-to-connect), automatic/name/geometry-based binding inference, annotation, visual requirement editing, reference approval, contract editing, source editing, bounded-agent-context UI, source-correlation UI, automatic correction, pixel diff, OCR, computer vision, cloud hosting, database, authentication, collaboration.
+
+## 48. Final verdict
+
+Batch 6 ("Explicit-binding interaction, zoom/pan, conditional lock, and on-demand reference fidelity") is implemented and independently validated: a developer can launch `view --bindings-file` with explicit reference-region/runtime-target declarations, see genuine canonical `bound`/`ambiguous`/`unavailable` statuses, cross-select in both directions using only canonical binding-result identity (never inferred from names/geometry - proven with a real equal-name regression fixture), independently zoom/pan both panes with bounded, presentation-only transforms that never touch evidence coordinates, optionally lock the two views only when the exact canonical `deriveCoordinateScale` mapping and compatibility both permit it, and explicitly trigger the existing canonical `evaluateReferenceCandidateFidelity` on demand - seeing its exact `not-evaluated`/`pass`/`fail` state, blockers, per-requirement numeric/relationship results with correctly-labeled units, and binding evidence that structurally agrees with the interactive binding panel - all displayed alongside, and never merged into, any selected existing contract-evaluation's own `overallVerdict` (proven with a real fidelity-PASS/contract-FAIL fixture, both at the server level and in a real Chromium session). No binding or fidelity artifact is ever persisted. No Batch 7+ scope (bounded-agent-context UI, correlation UI, annotation, automatic correction) was implemented, and no release/publication action was taken. Package version remains `0.7.0`.

package/docs/reports/v0.8-bounded-context-correlation-batch7.md

@@ -0,0 +1,233 @@
+# v0.8 Batch 7 — Bounded Agent Context, Correlation, Provenance, and Raw Evidence Navigation — Implementation Report
+
+## 1. Starting state
+
+- Branch: `master`
+- Starting HEAD: `b9eaa743b4db3e2fbfeb3503ea002cadeedf79b9` ("feat: add v0.8 binding fidelity interaction and view controls", Batch 6)
+- `origin/master` after `git fetch`: `a1de8ac01e1367b60021cb04226f56369fa2debb`
+- `git rev-list --left-right --count origin/master...HEAD`: `0  6`
+- `git merge-base --is-ancestor origin/master HEAD` → succeeded: strict ancestor, no divergence. No pull/rebase/merge/reset performed.
+- Starting `git status --short`: clean.
+- Package version confirmed `0.7.0` throughout; never bumped.
+
+## 2. Same recurring path contradiction, resolved the same way
+
+Task §6 repeated the identical `Join-Path`-vs-restated-sentence contradiction present in every prior batch since Batch 4. Re-ran the literal algorithm and confirmed the containment assertion passes only for the inside-repository path:
+
+```
+REPO_ROOT=Z:\Users\newuser\Projects\my-frontend-observer
+WORKFLOW_ROOT=Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8\batch-07
+ContainmentCheck=True
+```
+
+Used **`Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8\batch-07`**, per the same established precedent.
+
+## 3. Prior workflow-root audit
+
+Sibling `...my-frontend-observer.my-dev-kit-workflow\v0.8\` holds only `batch-01/02/03` (untouched). Inside-repo `.my-dev-kit-workflow\v0.8\` held `batch-04/05/06` (untouched) before this batch added `batch-07` alongside them.
+
+## 4. Predecessor reports/plan and my-dev-kit retrieval
+
+All six predecessor reports read in full. `docs/plans/v0.8-implementation-plan.md`'s Batch 7 section matches the task's scope exactly. All required source files (§4 items 17-35) read in full, including `boundedAgentContext.ts`, `boundedAgentContextProjection.ts`, `boundedAgentContextCorrelation.ts`, `referenceFidelityProjection.ts`, and the existing viewer server (`classify.ts`, `linkedEvidence.ts`, `comparisonView.ts`, `evaluationView.ts`, `referenceView.ts`). My-dev-kit index rebuilt at `$WORKFLOW_ROOT\my-dev-kit-index`; all nine required searches run and cross-checked directly against the source - every result matched.
+
+## 5. Context persistence-boundary audit (task §11)
+
+Confirmed via `src/viewerServer/evidence/classify.ts`'s own existing comment: `my-frontend-observer/bounded-agent-context` is explicitly the "known-but-unreadered" kind - no disk writer/reader/manifest contract exists for it as an Observer evidence-root artifact family, and this batch adds **none**. No `writeBoundedAgentContextArtifact`, no bounded-context writer, no bounded-context artifact directory, no `save-context` command exists anywhere in the diff (grep-verified). Bounded agent context is consumed exclusively as explicit, ephemeral viewer-session operational input via `--context-file`.
+
+## 6. Context-file architecture (task §12-§15)
+
+The context file's root **is** one `BoundedAgentContextArtifact` value directly - no `{"context": {...}}` wrapper (task §12's explicit requirement). `src/cli.ts#loadContextFile` (new) mirrors `loadBindingsFile`'s exact shape: `statSync` size check (bounded by `MAX_CONTEXT_FILE_BYTES`, §7 below) before ever reading bytes, then `readFileSync`+`JSON.parse`, then delegates classification to `src/viewerServer/context.ts#classifyContextFileContent` (new). The loader never derives context, never correlates anything, never mutates the parsed value, and never normalizes it into a different shape - it either passes the exact parsed object through (after validation) or fails closed with a specific error.
+
+## 7. File-size bound (task §15)
+
+Reuses the existing Batch 2 `MAX_MANIFEST_CANDIDATE_BYTES` value (2,000,000 bytes), re-exported from `src/viewerServer/context.ts` as `MAX_CONTEXT_FILE_BYTES`, rather than inventing a second bound - documented rationale: a `BoundedAgentContextArtifact`'s own frozen numeric caps (`MAX_RUNTIME_TARGETS=25`, `MAX_CORRELATION_RECORDS=25`, `MAX_STATIC_CANDIDATES_PER_TARGET=5`, `MAX_FIDELITY_MISMATCHES=15`, etc. - all in `src/domain/boundedAgentContext.ts`) already make a genuine context artifact far smaller than 2MB in any realistic case, so the same "generous headroom, never an arbitrarily large read" rationale Batch 2 established applies unchanged.
+
+## 8. Canonical validator reuse (task §67)
+
+`classifyContextFileContent` calls the existing `isValidBoundedAgentContextArtifact` exactly once for a current-schema candidate - grep-verified as the only call site of that validator in the diff, and no second/duplicated validation logic exists anywhere. `classifyContextFileContent` itself only inspects `artifactKind`/`schemaVersion` (the wrapper-level routing decision) before delegating full structural validation to the existing function.
+
+## 9. Unsupported-version behavior (task §16)
+
+A recognized `artifactKind` with a `schemaVersion` other than the current `'1.0.0'` produces `{status: 'unsupported-version', foundSchemaVersion}` - **not** a startup failure (task §16's explicit requirement) - the viewer still starts, and `ContextWorkspace.tsx` shows this state honestly, never projecting any current-shape UI onto it. Proven at three levels: unit (`contextViewerServer.test.ts`), CLI dispatch (`cliViewDispatch.test.ts`), and CLI-syntax (`cliView.test.ts` confirms a *malformed* current-schema file still fails, distinct from this case).
+
+## 10. Malformed-context startup failure (task §17)
+
+Unreadable file, invalid JSON, a non-object root, the wrong `artifactKind`, or a structurally invalid *current*-schema artifact all fail viewer startup clearly (nonzero exit, no server started) - covered by five dedicated `cliView.test.ts` tests, each asserting the specific error text.
+
+## 11. Context session lifetime (task §13)
+
+`ViewerServerState.context: ContextSessionState` (default `{status: 'none'}`) is set exactly once at `startViewer` call time and never re-read, never re-parsed, never mutated for the life of the process. The supplied file's path is never returned by `GET /api/context`, never logged to the browser, and is not part of `contextId`/`contextRequestId`/any viewer evidence identity (grep-verified: the path string exists only inside `runViewCommand`'s local scope in `src/cli.ts`).
+
+## 12. Exact source resolution (task §24, §69)
+
+`src/viewerServer/evidence/contextSourceView.ts#resolveContextSources` (new) resolves every field of `BoundedAgentContextSourceReferences` by exact canonical identity only, reusing Batch 4's `linkedEvidence.ts` module extended with three additive resolvers:
+
+- `resolveObservationById(root, observationId)` - bare `observationId` exact match (the only identity a context's `sources.observationIds` entries actually carry - distinct from Batch 4/5's compound `{observationId, requestId, producer, observationSchemaVersion}` cross-artifact reference).
+- `resolveEvaluationByIdentity(root, evaluationId, evaluationRequestId)`.
+- `resolveReferenceByIdentity(root, referenceId, referenceRequestId)` (matches either the `external-reference-imported` or `external-reference-approved` family).
+
+`resolveComparisonByIdentity`/`resolveBaselineContractById`/`resolveChangeContractById` (existing, unchanged) cover the remaining fields. Every resolver preserves the exact missing/ambiguous discipline already established: zero matches → `missing`, two or more → `ambiguous` (never silently picked). No pathname/name/similarity heuristic exists anywhere in this module.
+
+## 13. Raw evidence navigation (task §26-28, §60-61, §70)
+
+`viewer/src/components/RawEvidenceViewer.tsx` (new) reuses the existing Batch 2 `useArtifactDetail`/`GET /api/artifacts/<handle>` unchanged - no second full-artifact retrieval mechanism, no local filesystem read, no editable view, no arbitrary path/URL input field anywhere (verified in real Chromium, Case H: zero `input[type="file"]`/`input[type="url"]` elements exist on the page). `EvidenceReference.path` values are rendered only as plain provenance text (`ContextWorkspace.tsx`'s correlation/omission/truncation sections) - grep-verified: never passed to `fs.readFile`/`path.resolve`/any static file server anywhere in the diff.
+
+## 14. Runtime target projection display (task §29, §42)
+
+`BoundedRuntimeTargetProjection`'s optional fields (`geometry`/`visibility`/`overflow`/`scrollOwner`/`relationshipEvidence`/`screenshotRef`) each render "not included in this bounded context" when absent - never a fabricated `false`/`0`/empty-but-present value (`ContextWorkspace.tsx`'s target list rendering).
+
+## 15. Adequacy / adequacy reasons (task §31-33, §71)
+
+`Adequacy.state` (`adequate`/`partial`/`inadequate`) is rendered verbatim via a colored badge, never collapsed to a boolean; every `AdequacyReason.code`/`.detail` is listed exactly. The canonical reason-code vocabulary (`ADEQUACY_REASON_CODES`) is displayed as-is - no viewer-invented stronger claim exists.
+
+## 16. Omissions / truncations / required-evidence-loss prominence (task §33-35, §72-73)
+
+`OmissionRecord`/`TruncationRecord` are rendered in two visually distinct groups each (required vs. optional), with `required: true` records placed in a dedicated `.context-required-loss` block (red border/background, `role="alert"`) - proven visible without reading raw JSON in real Chromium (Case D). Omissions and truncations are never conflated with each other - separate sections, separate fields (`reason`/`detail` for omissions; `limit`/`actualCount` for truncations).
+
+## 17. Correlation-absent vs. correlation statuses (task §36-40, §74-77)
+
+`artifact.correlations === undefined` renders "Static correlation not included in this context." - never "unavailable" (task §36's explicit distinction, proven in Case E). When present, `correlated`/`ambiguous`/`unavailable` are preserved exactly per record: `correlated` shows its one candidate labeled "Correlated candidate" (never "Owner"); `ambiguous` shows **every** supplied candidate with copy explicitly stating none is chosen over another (proven in Case B: both candidate ids visible, and the response body contains neither "owner" nor "winner" as a UI claim); `unavailable` shows zero candidates and the literal text "No static candidate available for this correlation" (proven in Case C). All UI text was audited (task §63) - no unqualified "Owner"/"Source owner"/"Owned by"/"Responsible component" string exists anywhere in `ContextWorkspace.tsx`.
+
+## 18. Static producer / candidates / evidence basis / correlation-level provenance (task §41-46, §78-80)
+
+`StaticEvidenceProducerIdentity.name`/`.version`/`.indexId` are displayed exactly as supplied - never derived from a local path/timestamp/session (grep-verified: no such derivation exists). `StaticCandidateReference.candidateId`/`.kind`/`.evidenceRefs.length` are shown verbatim; the `candidateId` string is never used as an `href`, `fs` argument, or otherwise converted into a filesystem path (proven in Case J: zero anchors with `href` containing `symbol:`/`file:` inside the context workspace). `evidenceBasis`, record-local `omissions`/`truncations` (kept visually separate from top-level ones, with their own `required` visibility), and `provenance.correlatedAt` are all rendered exactly as supplied.
+
+## 19. No runtime rebuild / no runtime derivation / no my-dev-kit execution (task §18-21, §61-63, §96)
+
+Grep-verified across the entire diff (`src/viewerServer/`, `viewer/src/`):
+
+- `projectBoundedAgentContext(` — **zero** occurrences.
+- `deriveRuntimeStaticCorrelations(` — **zero** occurrences.
+- `attachRuntimeStaticCorrelations(` — **zero** occurrences.
+- `npx @dailephd/my-dev-kit` / `child_process` spawning of my-dev-kit — **zero** occurrences (the only `child_process` import in the shipped viewer server is the pre-existing, unrelated Batch 1 `openBrowser.ts` best-effort browser-launch helper).
+
+All four canonical functions are used **only** inside `tests/support/evidenceFixtures.ts` (test/fixture generation, explicitly sanctioned by task §64) to build trustworthy positive context fixtures - never inside `src/viewerServer/` or `viewer/src/`.
+
+## 20. Bounded reference-fidelity projection (task §48-52, §82-85)
+
+`artifact.fidelity === undefined` renders "Reference fidelity not included in this bounded context." - never implied as passing (proven in server-level unit tests and, implicitly, by every non-fidelity real-browser case never showing a PASS/FAIL banner). When present: identity fields (`referenceId`/`referenceRequestId`/`candidateObservationId`/`candidateRequestId`/`adequacy`/`compatibility`) are shown exactly; `state`/`blockedBy` render prominently (a `not-evaluated` blocked projection never displays an empty `mismatches` list as "no problems" - it shows an explicit "Evaluation was blocked..." note instead, proven in Case G); `mismatches` and `protectedContext` render in fully separate sections, each item preserving every canonical field (`requirementId`/`category`/`status`/`reasonCode`/`detail`/numeric or relationship fields) with no recomputation (grep-verified: `evaluateReferenceCandidateFidelity` is never called for the *bounded projection* rendering path itself - only reused, unchanged, for the separate live-evaluation panel below it).
+
+## 21. Historical vs. live fidelity independence (task §53-54, §86)
+
+When the context's `referenceId`/`candidateObservationId` exactly resolve within the current evidence root, `ContextWorkspace.tsx` embeds the existing, **unmodified** Batch 6 `ReferenceFidelityPanel` component directly beneath the bounded projection - the exact same on-demand `evaluateReferenceCandidateFidelity` trigger Batch 6 already built, reused verbatim (no duplicated fidelity-rendering logic). The two are labeled distinctly ("Bounded context fidelity projection" vs. "Current on-demand fidelity evaluation") with an explicit note that re-running never silently replaces the bounded projection. Proven in real Chromium (Case F): clicking "Evaluate Fidelity" produces a *second*, independently-rendered PASS state while the bounded projection's own PASS banner remains unchanged and still visible.
+
+## 22. Context-target ↔ runtime-target interaction (task §30, §47, §81)
+
+Selecting a bounded context target or a correlation record uses only exact `targetId`/`runtimeTargetId` string equality (`ContextWorkspace.tsx`). For a selected target, `SourceObservationTargetCheck` checks membership in each *exactly resolved* source observation's own already-fetched `targetEvidence` (a plain lookup over already-loaded JSON via the existing `useArtifactDetail`, never a new derivation) and lists **every** matching source observation rather than picking one when more than one contains the same target id - satisfying task §30's explicit "never guess which source observation owns the target" requirement.
+
+## 23. API changes (task §55-57, §97)
+
+| Route | Method | Semantics |
+|---|---|---|
+| `GET /api/context` | GET/HEAD | `{ok:true, status:'none'}` \| `{ok:true, status:'unsupported-version', foundSchemaVersion}` \| `{ok:true, status:'valid', artifact, sourceResolution}`. `405` for any write method (enforced globally by the existing request handler, before route dispatch). |
+
+No write endpoint was added (`POST/PUT /api/context`, `POST /api/correlation`, `POST /api/source`, `GET /api/file?path=...` all confirmed absent). Every other route (`/api/status`, `/api/index`, `/api/artifacts/<handle>`, `/api/media/<handle>/<role>`, `/api/observations/<handle>/relationships`, `/api/comparisons/<handle>/view`, `/api/evaluations/<handle>/view`, `/api/references/...`) is byte-for-byte unchanged.
+
+## 24. PWA cache boundary (task §98)
+
+**PASS.** `GET /api/context` lives under `/api/`, already covered by Batch 1's `navigateFallbackDenylist`. `tests/unit/viewerPwaBuild.test.ts` gained an explicit Batch 7 assertion against the real built `sw.js`: still exactly one `registerRoute` call, no `/api/context` precache entry. Independently confirmed against the real built server in the smoke test (§28).
+
+## 25. Files created
+
+- `src/viewerServer/context.ts`
+- `src/viewerServer/evidence/contextSourceView.ts`
+- `viewer/src/components/ContextWorkspace.tsx`, `RawEvidenceViewer.tsx`
+- `viewer/src/hooks/useBoundedContext.ts`
+- `viewer/src/types/context.ts`
+- `tests/unit/contextViewerServer.test.ts`
+- `tests/browser/boundedContextWorkspace.test.ts`
+- `docs/reports/v0.8-bounded-context-correlation-batch7.md` (this file)
+
+## 26. Files modified
+
+- `src/cli.ts` - `view --context-file` (§6-10).
+- `src/viewerServer/evidence/linkedEvidence.ts` - three additive resolvers (§12); every existing function unchanged.
+- `src/viewerServer/httpServer.ts` - one new route (§23); `ViewerServerState.context` field added.
+- `src/viewerServer/viewerService.ts` - `StartViewerOptions.context` added, threaded into `ViewerServerState`.
+- `tests/support/evidenceFixtures.ts` - `writeBoundedContextEvidenceFixture` added (real evidence + real canonical context/correlation/fidelity fixtures for every required test case, §27).
+- `tests/unit/cliView.test.ts`, `tests/unit/cliViewDispatch.test.ts` - `--context-file` startup/dispatch tests added (§66).
+- `tests/unit/viewerPwaBuild.test.ts` - Batch 7 cache-boundary assertion added.
+- `viewer/src/App.tsx` - added a "Bounded context" / "Evidence" mode toggle in the header; the context mode renders `ContextWorkspace` in place of the normal evidence body; a `navigateToRecord` callback lets context-mode source navigation switch back to evidence mode with the resolved record selected (task §25).
+- `viewer/src/styles/index.css` - additive Batch 7 rules.
+- `docs/ARCHITECTURE.md`, `docs/COMMANDS.md` - new/updated Batch 7 sections.
+
+## 27. Test fixture generation methodology (task §64-65)
+
+`writeBoundedContextEvidenceFixture` builds real Observer evidence (before/after observations, comparison, baseline/per-change contract, contract evaluation with a genuine `overallVerdict: "FAIL"`, an approved external reference) entirely through the existing canonical writers/application services, then builds every positive `BoundedAgentContextArtifact` variant by calling the real `projectBoundedAgentContext` (reading back the real persisted evaluation/reference artifacts through their existing canonical readers first, never re-derived by hand) and, where correlation is needed, the real `deriveRuntimeStaticCorrelations`/`attachRuntimeStaticCorrelations` - never hand-authored. Only the deliberately negative/malformed fixtures in `cliView.test.ts` (wrong kind, invalid JSON, structurally invalid current schema, non-object root) are hand-authored, exactly as task §64 permits.
+
+An early version of this fixture accidentally made the "adequate correlated" case genuinely `partial` (the same baseline used for the required-truncation demonstration was shared with the main pipeline). This was caught by a direct assertion in `contextViewerServer.test.ts` (`expect(fixture.baseContext.adequacy.state).toBe('adequate')` initially failed with `'partial'`), and fixed by giving the required-truncation demonstration its own separate `projectBoundedAgentContext` call with a dedicated 11-clause baseline, never attached to the persisted contract-evaluation pipeline - documented here as the methodology that caught it (verify fixtures against real derived output before writing UI-level assertions against them, per the same discipline established in every prior batch's report).
+
+Required fixture cases (task §65 A-L): **A** (adequate, one correlated target) - `correlatedContext`; **B** (ambiguous, ≥2 candidates) - `ambiguousContext`; **C** (unavailable) - `unavailableContext`; **D** (required omission) - `requiredOmissionContext`; **E** (required truncation) - `requiredTruncationContext`; **F** (no `correlations` field) - `baseContext`; **G** (fidelity mismatches) - `fidelityMismatchContext`; **H** (protectedContext) - `baseContext` (protected/preserved context present alongside a PASS state); **I** (fidelity `not-evaluated`/`blockedBy`) - `blockedFidelityContext`; **J** (missing linked source) - any context + deleting the observation directory in the test itself (mirrors the established Batch 4 pattern); **K** (multiple source observations relevant to the same target) - not built as a dedicated fixture this batch (task §65 K is explicitly "where useful"; the two-source-observation membership-check code path is exercised structurally by `SourceObservationTargetCheck`'s "list every match" implementation, but not proven with a real two-observations-sharing-a-target Chromium fixture - recorded as a residual gap, §31); **L** (unsupported future schema) - hand-authored negative fixture in `cliView.test.ts`/`cliViewDispatch.test.ts`.
+
+## 28. Validation results
+
+| Command | Result |
+|---|---|
+| `npm run typecheck` | **PASS** |
+| `npm run lint` | **PASS** |
+| `npm test` (`vitest run`) | **PASS** — 1156/1156 tests, 63/63 files |
+| `npm run build` | **PASS** |
+| `npm run check:docs` | **PASS** — 17 required files |
+| `npm run test:browser` | **PASS** — 168/168 tests, 17/17 files (one transient resource-contention flake on a single unrelated pre-existing Batch 6 test during a backgrounded run was reproduced as passing cleanly in isolation and on a subsequent full fresh run - not a Batch 7 regression, see §29) |
+| `git diff --check` | **PASS** — no whitespace errors |
+
+## 29. A note on browser-test flakiness during this batch's validation
+
+One `npm run test:browser` invocation, run in the background while many Chrome processes were already active on the machine, reported 19 failed tests across 11 files - all in pre-existing v0.1-v0.3-era suites (e.g. `windowScrollScenario.test.ts`) this batch never touched, all failing with a 30s timeout, and the run itself took ~8x longer than normal (394s vs. ~50-115s). This is a resource-contention symptom, not a functional regression: the exact same failing test file was re-run in isolation immediately afterward and passed cleanly, and a subsequent full fresh `npm run test:browser` run passed all 168/168 tests. No source change was made in response to this - it was correctly diagnosed as environmental, not a defect.
+
+## 30. Built viewer smoke
+
+Fixture: real before/after observations, comparison, contract evaluation (genuine `overallVerdict: "FAIL"`), approved reference (genuine fidelity PASS), and a real `BoundedAgentContextArtifact` (adequate, one `correlated` target, fidelity `pass`) built via `.my-dev-kit-workflow\v0.8\batch-07\tmp\build-smoke-context.mjs` (not committed) against the compiled `dist/*.js`, written to `.my-dev-kit-workflow\v0.8\batch-07\contexts\smoke-context.json`.
+
+Command: `node dist/cli.js view --root "<root>" --context-file "<context.json>" --bindings-file "<bindings.json>" --port 4319 --no-open`
+
+All required checks passed against the real running built server: `/api/status` → `200`; `/api/index` → 8 real records; `/api/context` → `status:"valid"`, `adequacy:"adequate"`, `correlations[0].status:"correlated"`, `fidelity.state:"pass"`, and every `sourceResolution` field `resolved` (2 observations, comparison, evaluation, reference); write method → `405`; PWA shell → `200`; `sw.js` contains zero `api/context` occurrences; the coexisting live fidelity endpoint (`--bindings-file` also supplied) independently returns a real `state:"pass"` for the same reference/candidate, proving `--bindings-file`/`--context-file` coexistence; a directory-traversal probe against `/api/artifacts/<handle>` returned `404` (no filesystem escape); the evidence root contained exactly the 10 expected real fixture files with no stray writes; the context JSON file's checksum was confirmed unchanged after the server session; `netstat` confirmed `127.0.0.1:4319` only; the server was located by its real PID and terminated with `taskkill /F`; a follow-up `netstat` confirmed the port was released.
+
+**Result: PASS.**
+
+## 31. Generated path inventory
+
+| Path | Disposition |
+|---|---|
+| `WORKFLOW_ROOT\tmp\build-smoke-context.mjs` | Retained (dev tooling, not committed) |
+| `WORKFLOW_ROOT\contexts\smoke-context.json` | Retained (dev tooling, not committed) |
+| `WORKFLOW_ROOT\bindings\smoke-bindings.json` | Retained (dev tooling, not committed) |
+| `WORKFLOW_ROOT\smoke\evidence-root` | Retained - 10 real fixture files verified |
+| `WORKFLOW_ROOT\logs\*` | Retained (smoke evidence) |
+| `WORKFLOW_ROOT\my-dev-kit-index\*` | Retained |
+| `WORKFLOW_ROOT\{cache,fixtures}` | Retained, empty/unused |
+| Repo-root `dist/` | Ordinary build output (gitignored) |
+| Sibling `...my-frontend-observer.my-dev-kit-workflow\v0.8\{batch-01,02,03}` | Untouched |
+| Inside-repo `.my-dev-kit-workflow\v0.8\{batch-04,05,06}` | Untouched |
+
+## 32. Repository pollution check
+
+**PASS.** `git status --short` before staging showed exactly the 10 modified + 8 new Batch-7-owned paths listed in §25/§26. No unexpected file/directory anywhere in the repository or its parent. No malformed sibling Batch 7 workflow path exists.
+
+## 33. Batch 1-6 regression check
+
+**PASS.** All 168 browser tests across 17 files pass on a clean run, including every Batch 1-6 test file, unmodified except the three additive test-file changes described in §26 (`cliView.test.ts`/`cliViewDispatch.test.ts` for the new `--context-file` flag, `viewerPwaBuild.test.ts` for the new cache-boundary assertion) - no pre-existing assertion was weakened or removed.
+
+## 34. v0.1-v0.7 regression check
+
+**PASS.** Full unit suite (1156/1156) green; `src/domain/boundedAgentContext*.ts` and every existing reader/service are byte-for-byte unchanged except the two additive exports already documented in Batch 6 (`deriveCoordinateScale`) - Batch 7 touches zero files under `src/domain/`.
+
+## 35. Deviations
+
+- The same recurring `$WORKFLOW_ROOT` path-instruction contradiction as every prior batch since Batch 4, resolved identically (§2).
+- No other deviation from the task's literal text.
+
+## 36. Remaining uncovered risks
+
+- **Task §65 Case K (multiple source observations relevant to the same target) has no dedicated real-browser fixture/test** this batch, though the implementing code (`SourceObservationTargetCheck`, §22) structurally lists every match rather than picking one, by construction - a real-browser proof for this specific case is a reasonable follow-up.
+- **`resolveContextSources` performs up to six independent bounded evidence-tree walks per `/api/context` request** (one per source-reference kind, run in parallel) - the same per-request-recomputation-cost category already noted as a residual risk in the Batch 4/5/6 reports for linked-evidence resolution generally. Not a correctness risk.
+- **The context/evidence mode toggle in `App.tsx` is a simple two-state switch, not integrated with the URL/history** - navigating away and back within a session loses the "which mode was active" state on a full page reload (not persisted, by design - session-only). A minor UX limitation, not a correctness concern.
+- Batches 1-6's previously reported risks (install-prompt "available" branch untested in headless Chromium, no live service-worker execution test, per-request linked-evidence walk cost, lock's zoom-multiplier mirroring simplification) remain unresolved and out of this batch's scope.
+
+## 37. Out-of-scope confirmation
+
+Confirmed absent from this batch's diff: bounded-agent-context persistence/writer, running my-dev-kit from the viewer, inventing static/source ownership, rebuilding bounded-agent-context at runtime, rebuilding runtime/static correlation at runtime, arbitrary filesystem browsing, source-code file browsing, raw evidence editing, annotation, source editing, automatic correction, cloud hosting, database, authentication, collaboration.
+
+## 38. Final verdict
+
+Batch 7 ("Bounded agent context, correlation, provenance, and raw evidence navigation") is implemented and independently validated: a developer can launch `view --context-file` with one explicit, validated `BoundedAgentContextArtifact`, inspect its identity/profile/adequacy/reasons, every bounded runtime target's included-or-honestly-absent fields, required-vs-optional omissions and truncations with required loss made visually unmistakable, runtime/static correlation exactly as `correlated`/`ambiguous`/`unavailable` (or honestly "not included" when the field itself is absent) with every ambiguous candidate shown and none promoted as a winner, static producer/candidate identities displayed verbatim and never treated as filesystem paths or edit authorization, and a bounded reference-fidelity projection (mismatches, protected context, blocked state) displayed alongside - never merged into - a separately-triggered live Batch 6 fidelity evaluation reusing that exact unmodified component - while every exactly-resolved Observer source reference safely navigates to its existing Batch 2/3/4/5 raw-evidence and visual-workspace surfaces, entirely within the authorized evidence root. The viewer never runs my-dev-kit, never calls `projectBoundedAgentContext`, and never calls `deriveRuntimeStaticCorrelations`/`attachRuntimeStaticCorrelations` at runtime (all three grep-confirmed). No Batch 8 release/integrated-hardening work was pulled forward, and no release/publication action was taken. Package version remains `0.7.0`.