@dailephd/my-frontend-observer 0.10.0 → 0.10.1

package/docs/reports/v0.8-comparison-contract-inspection-batch4.md

@@ -1,279 +1,279 @@
-# v0.8 Batch 4 — Before/After Comparison and Contract/Change-Scope Inspection — Implementation Report
-
-## 1. Starting state
-
-- Branch: `master`
-- Starting HEAD: `05d504a2c3b2419502faf48ff5661abb02b0e10d` ("feat: add v0.8 observation inspection and SVG overlays")
-- `origin/master` after `git fetch`: `a1de8ac01e1367b60021cb04226f56369fa2debb`
-- `git rev-list --left-right --count origin/master...HEAD`: `0  3` — local is exactly Batches 1-3 ahead of origin, no divergence.
-- Starting `git status --short`: clean.
-- Package version confirmed `0.7.0` throughout; never bumped.
-
-## 2. A resolved contradiction in the task's path instructions (task §5)
-
-The task gave an explicit `Join-Path`-based algorithm (`$WORKFLOW_BASE = Join-Path $REPO_ROOT ".my-dev-kit-workflow"`; `$WORKFLOW_ROOT = Join-Path $WORKFLOW_BASE "v0.8\batch-04"`) together with five verifiable assertions, then separately restated a "Required Batch 4 root" as the old Batches-1-3 sibling path (`...\my-frontend-observer.my-dev-kit-workflow\v0.8\batch-04`). These two are inconsistent: the sibling path **fails assertion 1** (`$WORKFLOW_ROOT` must begin with `$REPO_ROOT\`), since it is a sibling directory name, not a path under the repository root.
-
-Verified programmatically in PowerShell:
-
-```
-REPO_ROOT=Z:\Users\newuser\Projects\my-frontend-observer
-WORKFLOW_BASE=Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow
-WORKFLOW_ROOT=Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8\batch-04
-Assertion1 (starts with REPO_ROOT\): True
-Assertion2 (WORKFLOW_BASE parent = REPO_ROOT): True
-Assertion3 (WORKFLOW_ROOT parent = REPO_ROOT\.my-dev-kit-workflow\v0.8): True
-Assertion4 (not sibling path): True
-Assertion5 (not on C:): True
-```
-
-All five assertions pass for the `Join-Path`-derived (inside-repository) path and would fail for the restated sibling path. A decisive tiebreaker was also found in the repository's own `.gitignore` (`.my-dev-kit-workflow/`, present since before this batch) - a pattern that only makes sense for a directory *inside* the repository, since a sibling directory outside the repo is never a `git` ignore-pattern candidate in the first place. Per the task's own instruction ("Do not manually repair the string by guessing"), the literal, executable `Join-Path` algorithm was followed exactly rather than the inconsistent restated path, and this resolution is recorded here rather than silently picked.
-
-**Resolved `WORKFLOW_ROOT` for Batch 4:** `Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8\batch-04` (inside the repository, gitignored).
-
-## 3. Prior generated-path audit (task §6)
-
-- **Sibling location** `Z:\Users\newuser\Projects\my-frontend-observer.my-dev-kit-workflow\v0.8\` exists and contains exactly `batch-01`, `batch-02`, `batch-03` (Batches 1-3's own generated state, per their reports) - confirmed present, **not modified, not migrated, not reused** by this batch.
-- **Inside-repository location** `Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\` also pre-existed, but held only unrelated pre-v0.8 tooling state (`npm-cache`, `pw-browsers`, `readiness` - no `v0.8` subdirectory at all before this batch). Batch 4 added a new `v0.8\batch-04` subtree there without touching those pre-existing siblings.
-- No third, differently-malformed sibling path was found anywhere under `Z:\Users\newuser\Projects\`.
-
-## 4. Predecessor reports inspected
-
-All three read in full (not console summaries) - previously written in this same session, so their exact content was already held in full working memory and was re-confirmed against this batch's actual needs:
-
-- **Batch 1**: host `127.0.0.1`/port `4319`, `src/viewerServer/{httpServer,viewerService}.ts`, PWA `navigateFallbackDenylist: [/^\/api\//]`.
-- **Batch 2**: `evidence/{discovery,classify,handles,pathSafety,index,projection,mediaResolver}.ts` exact module boundaries; `EvidenceMetadataRecord`/`EvidenceArtifactDetail` shapes; `GET /api/index`/`/api/artifacts/<handle>`/`/api/media/<handle>/<role>` exact status-code semantics (404 unknown handle, 409 not-currently-loadable, 405 write methods); the `<family-slug>:<percent-encoded-relativeDir>` handle format; `resolveContainedDir`'s known forward-slash-root bugfix (reused unchanged, not re-litigated).
-- **Batch 3**: `observationView.ts#getObservationRelationships` and `GET /api/observations/<handle>/relationships`; `ObservationWorkspace`/`TargetOverlaySvg`/`ObservationInspector`/`EvidenceFieldView`/`useArtifactDetail`/`targetOrder.ts` component/hook boundaries; the coordinate-mapping decision (`requestConfig.viewport` as the canonical SVG `viewBox` source, geometry never rewritten); the `data-target-name` attribute already present on rendered `<rect>`/`<g>` elements.
-
-Batch 4 extends these mechanisms exactly - no second observation viewer, no second evidence index, no second media-loading path was created.
-
-## 5. Frozen planning authority inspected
-
-`docs/DOCUMENTATION_PRESERVATION_POLICY.md`, `docs/PROJECT_MILESTONES.md` (Milestone 8), `docs/ROADMAP.md` (v0.8), `docs/plans/v0.8-implementation-plan.md` (Batch 4 section + cross-batch invariants) - all previously read in full during Batches 1-3, re-confirmed unchanged. `docs/ARCHITECTURE.md`, `docs/CONTRACTS.md` (previously read in full), `docs/WORKFLOWS.md`, `docs/COMMANDS.md` (then edited). New this batch, read in full: `src/domain/comparison.ts`, `src/domain/frontendContracts.ts`, `src/domain/frontendContractEvaluationArtifact.ts`; targeted reads of `src/domain/frontendContractEvaluation.ts` (`UnexpectedChangeResult`, `FrontendContractEvaluationInput/Result`) and the three readers (`comparisonArtifactReader.ts`, `frontendContractArtifactReader.ts`, `frontendContractEvaluationArtifactReader.ts` - function names confirmed, bodies already known from having authored `classify.ts` in Batch 2).
-
-Confirmed Batch 4's title/scope in `docs/plans/v0.8-implementation-plan.md` match the task exactly; no material difference found.
-
-## 6. my-dev-kit retrieval
-
-Index built successfully at `$WORKFLOW_ROOT\my-dev-kit-index`. All seven required searches were run (comparison artifact ownership, comparison engine ownership, frontend contract shapes, contract evaluation ownership, viewer linked-evidence/index APIs, Batch 3 observation viewer, existing protected/preserved-regression tests). Every result matched direct source inspection - `src/domain/comparison.ts`, `comparisonEngine.ts`, `frontendContracts.ts`, `frontendContractEvaluation.ts`, `frontendContractEvaluationArtifact.ts`, the three readers, and the application services were all surfaced consistently.
-
-## 7. Comparison contract audit (task §10)
-
-Recorded from `src/domain/comparison.ts` (full read):
-
-- `comparisonId` (fresh per execution), `comparisonRequestId` (deterministic, `compare(A,B) !== compare(B,A)`).
-- `before`/`after`: **ordered**, distinct fields (`ComparisonSourceObservationReference` = `{observationId, requestId, producer:{name,version}, observationSchemaVersion, screenshot:{path}}`) - never swappable, confirmed by the type's own doc comment ("Comparison is ordered... never a swappable pair").
-- `config: ComparisonConfig`, `comparability: ComparabilityResult` (`state` + `reasons[]`, each reason carrying `code`/`severity`/`message`), `configurationChanges: TargetConfigurationChange[]` (`added`/`removed`/`locator-changed`), `relationshipsBefore`/`relationshipsAfter: LayoutRelationshipGraph` (the pre-persisted graphs, not re-derivable data), `differences: ComparisonDifference[]`, `relationshipChanges: RelationshipChangeRecord[]`, `expectedDependencyEvidence: ExpectedDependencyEvidence[]`, `diagnostics: Diagnostic[]`, `limits: {truncated, omittedFields, omittedTargetPairs}`.
-- Source references carry logical identity (`observationId`/`requestId`/`producer`/`observationSchemaVersion`) - never a persisted filesystem path. Confirmed: no path field anywhere in `ComparisonSourceObservationReference`.
-
-## 8. Source-observation resolution rule (task §11)
-
-**Exact match on all four available identity fields simultaneously**: `observationId`, `requestId`, `producer.version` (`producer.name` is already a fixed constant, `PRODUCER_NAME`, so only `.version` varies), and `observationSchemaVersion` - implemented in `src/viewerServer/evidence/linkedEvidence.ts#resolveObservationByReference`. Zero matches → `{status: 'missing'}`. Two or more exact matches → `{status: 'ambiguous', count}` - **never silently picks one** (proven with a real duplicated-manifest fixture in `tests/unit/linkedEvidenceServer.test.ts`). No folder-name/screenshot-filename/URL/target-set/geometry-based matching exists anywhere in this module. The resolution walks the bounded evidence tree once per lookup (mirroring Batch 2's `findImportedReferenceDir` pattern exactly, applied consistently here for comparisons/baseline-contracts/change-contracts too).
-
-## 9. Evaluation linked-artifact resolution rule
-
-`FrontendContractEvaluationArtifact` references are resolved by exact identity, each independently:
-
-- **Comparison**: exact `comparisonId` **and** `comparisonRequestId` (`resolveComparisonByIdentity`).
-- **Baseline contract**: exact `baselineId` (`resolveBaselineContractById`).
-- **Per-change contract**: exact `contractId` (`resolveChangeContractById`).
-- **Before/after observations**: the same exact-reference rule as §8 (`resolveObservationByReference`), applied to `evaluation.before`/`evaluation.after`.
-
-All five resolutions run in parallel (`Promise.all`) inside `src/viewerServer/evidence/evaluationView.ts#getEvaluationView`, each independently reporting `resolved`/`missing`/`ambiguous` - one missing/ambiguous linked artifact never blocks resolution of the others (proven in `tests/unit/linkedEvidenceServer.test.ts`: a missing baseline and a missing comparison are each tested independently while the rest of the evaluation view still resolves correctly).
-
-## 10. Comparison-view architecture
-
-`src/viewerServer/evidence/comparisonView.ts#getComparisonView(root, handle)`: same handle-decode → contained-dir-resolve → re-stat → re-classify discipline as `observationView.ts`/`mediaResolver.ts` (Batches 2-3). Requires `family === 'comparison'` and `supportState === 'supported'` (else `404`/`409`), then resolves `artifact.before`/`artifact.after` via §8's rule. Route: `GET /api/comparisons/<handle>/view` → `{ok:true, before: LinkStatus, after: LinkStatus}`. The comparison's own full payload is **not** duplicated in this response - the browser fetches it separately through the existing, unchanged `GET /api/artifacts/<handle>` (Batch 2), and the resolved before/after `handle`s are fed straight into that same existing route for the source observations. This keeps the new route minimal/ephemeral and avoids inventing a second artifact-detail contract.
-
-## 11. Before/after reuse of Batch 3 components (task §35)
-
-`viewer/src/components/ComparisonObservationPane.tsx` is built **entirely** from Batch 3's existing lower-level primitives: `useArtifactDetail` (unchanged), `orderedTargets` (unchanged), `TargetOverlaySvg` (one small additive change, below). No second screenshot-loading, coordinate-transform, or geometry-rendering implementation exists anywhere in Batch 4. The comparison's own persisted `relationshipsBefore`/`relationshipsAfter` are passed directly into `TargetOverlaySvg`'s existing `relationships: LayoutRelationshipGraph | undefined` prop - **`deriveLayoutRelationships` is never called to replace them** (grep-verified: no import of `deriveLayoutRelationships` exists in any Batch-4 file except the pre-existing Batch 3 `observationView.ts`, which Batch 4 does not modify).
-
-`TargetOverlaySvg.tsx` gained one additive, optional prop: `highlightNames?: ReadonlySet<string> | undefined`, rendering an extra `--highlighted` CSS class on any rectangle whose name is in the set, alongside (never replacing) the existing single-select `selected`/`aria-pressed` interaction. This lets a relationship-subject difference or a two-target contract primitive (e.g. `targets-do-not-overlap`) emphasize both named targets without changing Batch 3's existing single-select contract or its passing tests (`npm run test:browser` re-run in full, §21 below - all pre-existing Batch 3 tests pass unmodified).
-
-## 12. Confirmation: `compareObservations` was **not** called for viewer reconstruction
-
-Grep-verified across every Batch 4 file (`src/viewerServer/evidence/{linkedEvidence,comparisonView,evaluationView}.ts`, every `viewer/src/**` file touched this batch): zero imports of `compareObservations` or `comparisonEngine.js`. The persisted `ComparisonArtifact` (`differences`, `relationshipsBefore`/`After`, `comparability`, `configurationChanges`, `expectedDependencyEvidence`, `diagnostics`, `limits`) is read unchanged via the existing Batch 2 `GET /api/artifacts/<handle>` and rendered as-is in `ComparisonWorkspace.tsx`.
-
-## 13. Differences displayed (task §15)
-
-All 13 canonical `DifferenceKind` values are rendered generically (kind/subject/before/after/delta, exactly as persisted, `JSON.stringify`'d for `before`/`after`/`delta` since their shape is difference-kind-dependent per the domain type's own design): `appeared`, `disappeared`, `moved`, `resized`, `visibility-changed`, `clipping-changed`, `containment-changed`, `horizontal-overflow-changed`, `vertical-overflow-changed`, `page-size-changed`, `scroll-owner-changed`, `relative-position-changed`, `relationship-changed`. No new PASS/FAIL severity is assigned anywhere - `ComparisonWorkspace.tsx`'s difference list is presentation-only.
-
-## 14. Difference target highlighting (task §16)
-
-`subjectTargetNames(subject: ComparisonDifferenceSubject)`: `type: 'target'` → `[subject.target]`; `type: 'relationship'` → `[subjectTarget, relatedTarget].filter(defined)`; `type: 'page'` → `[]` (no target ever fabricated for a page-level subject). Clicking a difference calls `highlightSubject`, which sets the first name as the single interactive `selected` target and any remaining name(s) as `highlightNames`. Because `TargetOverlaySvg` only ever renders a rectangle for a target with real geometry in *that specific* observation, an `appeared` target (absent in `before`) simply has no rectangle in the Before pane, and a `disappeared` target (absent in `after`) has none in the After pane - **never fabricated**, proven with a real Chromium test (`comparisonEvaluationWorkspace.test.ts`, "appeared/disappeared target behavior") that asserts a rectangle count of exactly `0` on the absent side and `1` on the present side, for both targets.
-
-## 15. Comparability presentation (task §18)
-
-`.comparability-banner--{comparable|comparable-with-warnings|incomparable}` renders `artifact.comparability.state` and every reason with its own severity class (`blocking`/`warning`/`unassessed`) and message unchanged. An `incomparable` result gets `role="alert"` and a red-bordered banner - visually unmistakable, proven with a real Chromium test against a genuinely `incomparable` fixture (two observations with different `requestConfig.viewport` producing a real `viewport-mismatch` blocking reason from `compareObservations` itself, never asserted/faked).
-
-## 16. Target configuration changes (task §19)
-
-Rendered as their own `Configuration changes` section (`kind` + `target`), entirely separate from the `Differences` section that shows `appeared`/`disappeared` - the two lists never merge or share a component.
-
-## 17. Expected dependency evidence (task §20)
-
-Rendered under the heading "Expected dependency evidence (explicit, non-causal)"; each entry shows `cause.target.property direction → effect.target.property direction: outcome`, where `outcome` is exactly one of `consistent`/`not-observed`/`contradictory-to-declaration`/`unavailable` - never rephrased as a pass/fail or causal claim.
-
-## 18. Comparison diagnostics and limits (task §21)
-
-`artifact.limits.truncated === true` renders a visible, non-suppressible banner listing `omittedFields`/`omittedTargetPairs`; `artifact.diagnostics` (when non-empty) render as their own section. Neither is hidden behind a successful-looking default state.
-
-## 19. Contract/evaluation architecture
-
-`src/viewerServer/evidence/evaluationView.ts#getEvaluationView(root, handle)` mirrors `comparisonView.ts` exactly, resolving all five linked references (§9) in parallel. Route: `GET /api/evaluations/<handle>/view` → `{ok:true, comparison, baseline, change, before, after}` (each a `LinkStatus`). `viewer/src/components/EvaluationWorkspace.tsx` fetches the evaluation's own already-loaded artifact (from `ArtifactPreview`'s existing `useArtifactDetail`) plus this view route, then calls `useArtifactDetail` four more times (baseline/change/comparison handles, plus reusing `ComparisonObservationPane` for before/after) - all through the same existing Batch 2 on-demand-loading contract, never a new artifact-fetching mechanism.
-
-## 20. Confirmation: `evaluateFrontendContract` was **not** called for viewer reconstruction
-
-Grep-verified: zero imports of `evaluateFrontendContract` or `frontendContractEvaluation.js`'s evaluator export anywhere in Batch 4's `src/viewerServer/` or `viewer/src/` code (only `UnexpectedChangeResult`, a pure type, is imported for typing). `overallVerdict`, `clauseResults`, `activeBaselineClauseIds`, `supersededBaselineClauseIds`, and `unexpectedChanges` are the persisted artifact's own fields, read unchanged via `GET /api/artifacts/<handle>` and rendered as-is.
-
-## 21. Baseline clauses / change-scope / clause results / active-superseded / unexpected changes / overall verdict
-
-- **Clause joining by exact `clauseId` only** (`viewer/src/components/ClauseResultRow.tsx`, `EvaluationWorkspace.tsx`): a `Map<clauseId, {source, clause}>` is built from the loaded baseline's `clauses` and the loaded change contract's `clauses`; each `clauseResults` entry is looked up by its own `clauseId` - never by target/primitive-shape/category/position/text similarity. An id present in neither loaded contract renders as an honest "unresolved clause definition" (never a fabricated category/primitive) - a distinct "Unresolved clause definitions" section exists specifically for this case.
-- **Baseline clauses** are shown in their own section, distinctly from per-change categories, each tagged `active` or `superseded` **exclusively from the evaluation artifact's own `activeBaselineClauseIds`/`supersededBaselineClauseIds`** - never recomputed from clause-id overlap or any other inference.
-- **Per-change clauses** are grouped into four sections in the frozen category order (`requested`, `expected-dependent`, `protected`, `preserved`); `expected-dependent` clauses additionally show their `required`/`permitted` mode without merging the two modes' meaning.
-- **Clause result status** (`pass`/`fail`/`unavailable`/`conflict`) is preserved exactly via `statusLabel()` - `unavailable` always shows its `reason`, `conflict` always shows its `reason` and `conflictingClauseIds`; neither is ever collapsed to a boolean or converted to `fail`.
-- **Unexpected changes** render in their own section, `classification: 'unexpected'` preserved verbatim, with target highlighting from the same `subjectTargetNames`-style extraction as ordinary differences (since `UnexpectedChangeResult.subject` reuses `ComparisonDifferenceSubject` unchanged - confirmed in `frontendContractEvaluation.ts`).
-- **Overall verdict**: `artifact.overallVerdict` renders directly in a large `.overall-verdict--PASS`/`.overall-verdict--FAIL` banner - the UI performs no verdict computation of its own anywhere in this batch's code (grep-verified: no `every(...status==='pass')`-style logic exists in `EvaluationWorkspace.tsx`).
-
-## 22. Target cross-highlighting from contract primitives (task §34)
-
-`viewer/src/contract/clauseTargets.ts#primitiveTargetNames` is an exhaustive `switch` over every `ContractPrimitiveKind`: single-target primitives (`target-visible`, `target-not-clipped`, `target-width-within-bound`, `target-does-not-own-scroll`, `target-begins-below-initial-viewport`, `property-unchanged-within-tolerance`, `property-increases`, `property-decreases`) return `[target]`; two-target primitives (`targets-do-not-overlap`, `target-wider-than`, `target-follows-vertically`) return `[targetA, targetB]`; `target-fits-inside` returns `[target, container]`; `relationship-unchanged` returns `[subjectTarget, relatedTarget].filter(defined)`; the two page-level primitives (`document-width-fits-viewport`, `scroll-owner-is-document`) return `[]` - clicking their clause row is disabled (`names.length === 0` → `disabled`) rather than highlighting an invented target.
-
-## 23. All-pass proof (task §33/§44 Case A)
-
-**Fixture**: `tests/support/evidenceFixtures.ts#writeAllPassPipelineFixture` - the deliberate all-pass counterpart to the existing `writeFullPipelineFixture`, differing only in the *actual rendered geometry/style* fed to the real `compareObservations`/`evaluateFrontendContract` workflow (via `evaluateAndPersistFromArtifactRoots`): `rightAd` genuinely unchanged (protected clause genuinely satisfied) and `navigation` genuinely never clipped (`scrollWidth === clientWidth`, preserved clause genuinely satisfied). Verified directly against the real evaluator's output before use (§30 below) - `overallVerdict: "PASS"`, all four clauses `pass`. `overallVerdict` is never hand-edited.
-
-**Real-browser proof**: `tests/browser/comparisonEvaluationWorkspace.test.ts`, "Case A" describe block - selects the evaluation, confirms `.overall-verdict--PASS`, confirms both before/after screenshots load through the real `/api/media/observation:...` endpoint, confirms `requested-nav`/`protected-rightad`/`preserved-nav-unclipped` are each `.clause-row--pass`, and confirms clicking the `requested-nav` clause row highlights the exact `navigation` target (`aria-pressed="true"` on its real SVG rectangle).
-
-## 24. Safety-failure proof (task §32/§44 Case B)
-
-**Fixture**: the existing `writeFullPipelineFixture` (reused unchanged, not a new fixture) - already produces, through the real canonical evaluator, `overallVerdict: "FAIL"` with `requested-nav: pass`, `protected-rightad: fail`, `preserved-nav-unclipped: fail` (confirmed by direct inspection before use, §30). This is exactly the required safety case: **a requested/local change passes while a protected clause and a preserved clause both fail, and the overall verdict is FAIL** - never hand-constructed.
-
-**Real-browser proof**: `tests/browser/comparisonEvaluationWorkspace.test.ts`, "Case B" describe block - selects the evaluation, confirms `.overall-verdict--FAIL`, confirms `requested-nav` is `.clause-row--pass` while `protected-rightad` and `preserved-nav-unclipped` are both `.clause-row--fail`, confirms before/after visual context remains fully available (both screenshots render) despite the overall failure, and confirms clicking the failing `protected-rightad` clause highlights the exact `rightAd` target.
-
-## 25. API changes
-
-| Route | Method | Semantics |
-|---|---|---|
-| `GET /api/comparisons/<handle>/view` | GET/HEAD | `{ok:true, before: LinkStatus, after: LinkStatus}`. `404` unknown handle, `409` not-a-comparison/not-currently-loadable, `405` any write method. |
-| `GET /api/evaluations/<handle>/view` | GET/HEAD | `{ok:true, comparison, baseline, change, before, after}` (each a `LinkStatus`). `404`/`409`/`405` as above. |
-
-`/api/status`, `/api/index`, `/api/artifacts/<handle>`, `/api/media/<handle>/<role>`, `/api/observations/<handle>/relationships` are byte-for-byte unchanged.
-
-## 26. PWA cache boundary
-
-**PASS.** Both new routes live under `/api/`, already covered by Batch 1's `navigateFallbackDenylist: [/^\/api\//]` - no service-worker configuration change was needed. `tests/unit/viewerPwaBuild.test.ts` gained one explicit assertion against the real built `sw.js`: still exactly one `registerRoute` call, and the precache manifest contains neither `/api/comparisons` nor `/api/evaluations`.
-
-## 27. Files created
-
-- `src/viewerServer/evidence/linkedEvidence.ts`, `comparisonView.ts`, `evaluationView.ts`
-- `viewer/src/components/ComparisonObservationPane.tsx`, `ComparisonWorkspace.tsx`, `EvaluationWorkspace.tsx`, `ClauseResultRow.tsx`
-- `viewer/src/contract/clauseTargets.ts`
-- `viewer/src/hooks/useLinkedEvidence.ts`
-- `viewer/src/types/comparison.ts`, `contracts.ts`
-- `tests/unit/linkedEvidenceServer.test.ts`
-- `tests/browser/comparisonEvaluationWorkspace.test.ts`
-- `docs/reports/v0.8-comparison-contract-inspection-batch4.md` (this file)
-
-## 28. Files modified
-
-- `src/viewerServer/httpServer.ts` - added the two new routes (§25); `/api/status`, `/api/index`, `/api/artifacts/<handle>`, `/api/media/<handle>/<role>`, `/api/observations/<handle>/relationships`, and static-asset serving unchanged.
-- `viewer/src/components/TargetOverlaySvg.tsx` - one additive, optional `highlightNames` prop (§11); existing `selected`/`onSelect`/`toggles` behavior unchanged.
-- `viewer/src/components/ArtifactPreview.tsx` - branches to `ComparisonWorkspace`/`EvaluationWorkspace` for their families; every other family's raw-JSON preview unchanged.
-- `viewer/src/styles/index.css` - additive rules for the new workspaces.
-- `tests/support/evidenceFixtures.ts` - added `writeAllPassPipelineFixture`, `writeBaselineSupersessionFixture`, `writeAppearedDisappearedComparisonFixture`, `writeIncomparableComparisonFixture` (all built through the real canonical `compareObservations`/`evaluateFrontendContract` workflow, never hand-edited results); `buildObservation` gained optional `pageEvidence`/`viewport` parameters (already added in Batch 3, unchanged here).
-- `tests/browser/viewerEvidenceShell.test.ts` - two pre-existing Batch 2 tests that selected a `comparison` record to exercise the *generic* raw-JSON-preview/no-visualization path now legitimately conflict with Batch 4's real comparison workspace; both were repointed to `baseline-contract` (which still exercises exactly the generic path/invariant they were written to protect) - the same kind of sanctioned evolution as Batch 1→2's placeholder-text update, Batch 2's `TST-401`, and Batch 3's analogous `viewerEvidenceShell.test.ts` update.
-- `tests/unit/viewerPwaBuild.test.ts` - added the explicit Batch 4 cache-boundary assertion (§26).
-- `docs/ARCHITECTURE.md`, `docs/COMMANDS.md` - new/updated Batch 4 sections (condensed versions of §7-§22 above).
-
-## 29. Tests added/modified and behavior protected
-
-| Test file | Level | Protects |
-|---|---|---|
-| `linkedEvidenceServer.test.ts` (15 tests) | unit/integration (real HTTP) | Exact before/after resolution; honest `missing` when a source observation is removed; honest `ambiguous` with a real duplicated-identity fixture (count=2); 409 for a non-comparison/non-evaluation handle; 404 unknown handle; 405 write methods; exact resolution of all five evaluation links; missing baseline reported honestly; missing comparison reported honestly; the all-pass fixture is a genuine `PASS` with every clause `pass`; the full-pipeline fixture is a genuine `FAIL` with the exact required requested-pass/protected-fail/preserved-fail signature; the baseline-supersession fixture reports real active/superseded ids and a real unexpected change. |
-| `comparisonEvaluationWorkspace.test.ts` (4 tests, real Chromium) | browser | Case A (all-pass) full proof (§23); Case B (safety failure) full proof (§24); appeared/disappeared honest rectangle presence/absence; incomparable state visibly unmistakable with its real blocking reason. |
-| `viewerEvidenceShell.test.ts` (2 updated) | browser | Generic Batch 2 on-demand-load/no-visualization invariants still hold for families without a Batch 3/4 workspace. |
-| `viewerPwaBuild.test.ts` (+1) | build/integration | New routes covered by the existing `/api/` denylist, no new runtime-caching rule. |
-
-## 30. A methodology note: fixtures verified against the real evaluator before use
-
-Before writing any assertion against `writeAllPassPipelineFixture`, `writeFullPipelineFixture` (reused), or `writeBaselineSupersessionFixture`, each was run once through the real `readFrontendContractEvaluationArtifact` reader in an isolated scratch test and its actual `overallVerdict`/`clauseResults`/`activeBaselineClauseIds`/`supersededBaselineClauseIds` were inspected directly (not assumed) - this is how the exact safety-case signature (`requested-nav: pass`, `protected-rightad: fail`, `preserved-nav-unclipped: fail`, `overallVerdict: "FAIL"`) in the pre-existing `writeFullPipelineFixture` was *discovered*, not designed - it already existed from Batch 2/3's fixture reuse and turned out to exactly match Batch 4's required safety case. The scratch inspection tests were deleted before finalizing (never committed); this report documents the methodology rather than leaving throwaway files behind.
-
-## 31. 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** — 1101/1101 tests, 60/60 files |
-| `npm run build` | **PASS** — unchanged Node/library output plus `dist/viewerServer/evidence/{comparisonView,evaluationView,linkedEvidence}.js` and the rebuilt `dist/viewer/**` PWA |
-| `npm run check:docs` | **PASS** — "Documentation check passed (17 required files)." |
-| `npm run test:browser` | **PASS** — 141/141 tests, 14/14 files (real Chromium; run in full per task §46) |
-| `git diff --check` | **PASS** — no whitespace errors (only expected LF→CRLF notices) |
-
-## 32. Built viewer smoke (task §47)
-
-Fixture: one real before/after observation pair, a real comparison, a real baseline contract, a real per-change contract (the "milestone signature" clause set), and a real evaluation - all built via a one-off script (not committed, `$WORKFLOW_ROOT\tmp`) calling the actual compiled `dist/artifacts/*.js`/`dist/application/frontendContractEvaluationService.js` modules directly, 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 passed against the real running built server:
-
-- `/api/status` → `200`; `/api/index` → all 6 real records (`observation` x2, `comparison`, `baseline-contract`, `change-contract`, `contract-evaluation`), all `supported`.
-- `/api/comparisons/<handle>/view` → `200`, both `before`/`after` `resolved` to the exact real observation handles.
-- `/api/evaluations/<handle>/view` → `200`, all five links (`comparison`/`baseline`/`change`/`before`/`after`) `resolved`.
-- `/api/artifacts/<evaluation-handle>` → `overallVerdict: "FAIL"`, `clauseResults`: `requested-nav: pass`, `expected-workspace: pass`, `protected-rightad: fail`, `preserved-nav-unclipped: fail` - the exact required safety signature, produced by the real canonical workflow, not edited.
-- Both before/after screenshots → `200 image/png`.
-- Unknown comparison/evaluation handles → `404`; write method (`POST`) → `405`.
-- PWA still loads (`/`, `/sw.js` both `200`); `sw.js` contains no `api/comparisons`/`api/evaluations` reference.
-- `netstat` confirmed `127.0.0.1:4319` only, never `0.0.0.0`.
-- Server located by its real PID and terminated with `taskkill /F`; a follow-up `netstat` confirmed the port was released.
-- A post-shutdown listing of the smoke evidence root shows exactly the 8 fixture files the script wrote - no stray writes, no modification.
-
-**Result: PASS.** Logs retained under `$WORKFLOW_ROOT\logs\` (`smoke-server.log`, `index-response.json`, `eval-detail.json`, `smoke-checks-1.log`, `smoke-checks-2.log`).
-
-## 33. Generated path inventory
-
-| Path | Disposition |
-|---|---|
-| `WORKFLOW_ROOT\cache\npm` | Retained (npm cache from the my-dev-kit-index `npx` invocation) |
-| `WORKFLOW_ROOT\tmp\vite-cache`, `WORKFLOW_ROOT\tmp\build-smoke-comparison.mjs` | Retained (build cache empty again, same finding as every prior batch; the smoke-fixture script is dev/readiness tooling only, not committed) |
-| `WORKFLOW_ROOT\logs\*` | Retained (smoke evidence, §32) |
-| `WORKFLOW_ROOT\smoke\evidence-root` | Retained (real evidence fixture tree built for the smoke test) |
-| `WORKFLOW_ROOT\my-dev-kit-index\*` | Retained (successful index + cache-metadata) |
-| `WORKFLOW_ROOT\fixtures` | Retained, empty/unused (no committed deterministic repository fixture was needed - all Batch 4 fixtures are built programmatically via `tests/support/evidenceFixtures.ts`, matching the existing repository convention) |
-| 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 every prior batch) |
-| Sibling `...my-frontend-observer.my-dev-kit-workflow\v0.8\{batch-01,batch-02,batch-03}` | Untouched (verified, §3) |
-
-## 34. Repository pollution check
-
-**PASS.** `git status --short` before staging showed only the 9 modified + 13 new Batch-4-owned paths listed in §27/§28. No unexpected file or directory appeared anywhere in the repository. No malformed sibling Batch 4 workflow path exists anywhere under `Z:\Users\newuser\Projects\` (verified directly, §3).
-
-## 35. Batch 1/2/3 regression check
-
-**PASS.** All Batch 1 tests (`view` CLI, `127.0.0.1`/port `4319`, PWA shell/installability, cache boundary, server cleanup), Batch 2 tests (evidence indexing, unsupported-version handling, safe handles, on-demand artifact/media loading, filesystem containment), and Batch 3 tests (observation SVG workspace, coordinate mapping, relationship reuse, unresolved-target honesty) pass unmodified except the two `viewerEvidenceShell.test.ts` updates described in §28, which preserve the exact invariants they originally protected while accounting for Batch 4's legitimate new comparison-family behavior.
-
-## 36. v0.1-v0.7 regression check
-
-**PASS.** Every pre-v0.8 unit and browser test suite (`observe`, `compare`, `approve-baseline`, `save-change-contract`, `evaluate-contract`, `import-reference`, `approve-reference`, `evaluate-reference-fidelity`) remains covered and passing - none was touched by this batch's diff. `src/domain/`, `src/artifacts/*Writer.ts`, and every existing reader/engine (`compareObservations`, `evaluateFrontendContract`, `deriveLayoutRelationships`) are byte-for-byte unchanged.
-
-## 37. Deviations
-
-- The task's §5 "Required Batch 4 root" restatement conflicted with its own `Join-Path` algorithm and verification assertions; resolved per §2 above by following the literal, executable, self-verifying algorithm. This is the only deviation from the task's literal text, and it was necessary to satisfy the task's own stated assertions rather than an arbitrary choice.
-- No other deviations. Every other task step (predecessor-report inspection, my-dev-kit retrieval, the coordinate/contract audits, all required test categories, the full validation chain including `test:browser`, and the built-CLI smoke) was executed as specified.
-
-## 38. Remaining uncovered risks
-
-- **`highlightNames` only distinguishes "the primary selected target" from "secondary highlighted targets" visually (different CSS classes), not through `aria-pressed`** (which remains true only for the single `selected` target, matching Batch 3's existing accessibility contract). A screen-reader user selecting a relationship-subject difference will not hear the second (related) target announced as selected, only visually distinguished. Not a regression (Batch 3 never had multi-target selection at all), but a genuine accessibility gap for the new multi-target case specifically.
-- **`resolveObservationByReference`/`resolveComparisonByIdentity`/etc. each independently re-walk the bounded evidence tree** (same pattern as Batch 2's `findImportedReferenceDir`, carried forward deliberately for consistency rather than introducing a new caching layer). An evaluation view triggers five such walks in parallel; for an evidence root near the `MAX_MANIFEST_CANDIDATES` bound, this is more filesystem work per evaluation-view request than a single shared index pass would need. Not a correctness risk; the same category of "report rather than pre-optimize" risk Batch 2 already recorded.
-- **`ComparisonWorkspace`/`EvaluationWorkspace` do not yet offer a synchronized zoom/pan or a locked view between before/after panes** - explicitly out of scope for this batch (task §42), planned for a later batch.
-- Batches 1-3'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.
-
-## 39. Out-of-scope confirmation
-
-Confirmed absent from this batch's diff: external-reference image display, reference regions, reference/candidate side-by-side mode, reference applicability UI, reference fidelity UI, reference/runtime binding, explicit-binding cross-selection, image zoom/pan, synchronized view lock, bounded-agent-context UI, runtime/static correlation UI, annotation, contract editing, baseline approval, contract approval, reference approval, source editing, automatic binding, automatic visual analysis, pixel difference, cloud hosting, database, authentication, collaboration.
-
-## 40. Final verdict
-
-Batch 4 ("Before/after comparison and contract/change-scope inspection") is implemented and independently validated: a developer can select an existing `ComparisonArtifact`, see its exact persisted before/after observations resolved by canonical identity and displayed side by side through the reused Batch 3 screenshot/SVG machinery, inspect every canonical difference/relationship-change/comparability/dependency-evidence category exactly as persisted, select an existing `FrontendContractEvaluationArtifact`, see its exact linked baseline/per-change contracts/comparison/observations resolved by canonical identity, inspect every clause result (baseline active/superseded, requested/expected-dependent/protected/preserved, unexpected) joined by exact `clauseId`, and see the authoritative overall `PASS`/`FAIL` verdict rendered unmistakably - including the required safety case where a requested change passes while a protected and a preserved clause both fail, proven against a real canonically-evaluated fixture in real Chromium. `compareObservations` and `evaluateFrontendContract` were never invoked for viewer reconstruction anywhere in this batch. No Batch 5+ visualization, no v0.9 annotation, and no release/publication action was taken. Package version remains `0.7.0`.
+# v0.8 Batch 4 — Before/After Comparison and Contract/Change-Scope Inspection — Implementation Report
+
+## 1. Starting state
+
+- Branch: `master`
+- Starting HEAD: `05d504a2c3b2419502faf48ff5661abb02b0e10d` ("feat: add v0.8 observation inspection and SVG overlays")
+- `origin/master` after `git fetch`: `a1de8ac01e1367b60021cb04226f56369fa2debb`
+- `git rev-list --left-right --count origin/master...HEAD`: `0  3` — local is exactly Batches 1-3 ahead of origin, no divergence.
+- Starting `git status --short`: clean.
+- Package version confirmed `0.7.0` throughout; never bumped.
+
+## 2. A resolved contradiction in the task's path instructions (task §5)
+
+The task gave an explicit `Join-Path`-based algorithm (`$WORKFLOW_BASE = Join-Path $REPO_ROOT ".my-dev-kit-workflow"`; `$WORKFLOW_ROOT = Join-Path $WORKFLOW_BASE "v0.8\batch-04"`) together with five verifiable assertions, then separately restated a "Required Batch 4 root" as the old Batches-1-3 sibling path (`...\my-frontend-observer.my-dev-kit-workflow\v0.8\batch-04`). These two are inconsistent: the sibling path **fails assertion 1** (`$WORKFLOW_ROOT` must begin with `$REPO_ROOT\`), since it is a sibling directory name, not a path under the repository root.
+
+Verified programmatically in PowerShell:
+
+```
+REPO_ROOT=Z:\Users\newuser\Projects\my-frontend-observer
+WORKFLOW_BASE=Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow
+WORKFLOW_ROOT=Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8\batch-04
+Assertion1 (starts with REPO_ROOT\): True
+Assertion2 (WORKFLOW_BASE parent = REPO_ROOT): True
+Assertion3 (WORKFLOW_ROOT parent = REPO_ROOT\.my-dev-kit-workflow\v0.8): True
+Assertion4 (not sibling path): True
+Assertion5 (not on C:): True
+```
+
+All five assertions pass for the `Join-Path`-derived (inside-repository) path and would fail for the restated sibling path. A decisive tiebreaker was also found in the repository's own `.gitignore` (`.my-dev-kit-workflow/`, present since before this batch) - a pattern that only makes sense for a directory *inside* the repository, since a sibling directory outside the repo is never a `git` ignore-pattern candidate in the first place. Per the task's own instruction ("Do not manually repair the string by guessing"), the literal, executable `Join-Path` algorithm was followed exactly rather than the inconsistent restated path, and this resolution is recorded here rather than silently picked.
+
+**Resolved `WORKFLOW_ROOT` for Batch 4:** `Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\v0.8\batch-04` (inside the repository, gitignored).
+
+## 3. Prior generated-path audit (task §6)
+
+- **Sibling location** `Z:\Users\newuser\Projects\my-frontend-observer.my-dev-kit-workflow\v0.8\` exists and contains exactly `batch-01`, `batch-02`, `batch-03` (Batches 1-3's own generated state, per their reports) - confirmed present, **not modified, not migrated, not reused** by this batch.
+- **Inside-repository location** `Z:\Users\newuser\Projects\my-frontend-observer\.my-dev-kit-workflow\` also pre-existed, but held only unrelated pre-v0.8 tooling state (`npm-cache`, `pw-browsers`, `readiness` - no `v0.8` subdirectory at all before this batch). Batch 4 added a new `v0.8\batch-04` subtree there without touching those pre-existing siblings.
+- No third, differently-malformed sibling path was found anywhere under `Z:\Users\newuser\Projects\`.
+
+## 4. Predecessor reports inspected
+
+All three read in full (not console summaries) - previously written in this same session, so their exact content was already held in full working memory and was re-confirmed against this batch's actual needs:
+
+- **Batch 1**: host `127.0.0.1`/port `4319`, `src/viewerServer/{httpServer,viewerService}.ts`, PWA `navigateFallbackDenylist: [/^\/api\//]`.
+- **Batch 2**: `evidence/{discovery,classify,handles,pathSafety,index,projection,mediaResolver}.ts` exact module boundaries; `EvidenceMetadataRecord`/`EvidenceArtifactDetail` shapes; `GET /api/index`/`/api/artifacts/<handle>`/`/api/media/<handle>/<role>` exact status-code semantics (404 unknown handle, 409 not-currently-loadable, 405 write methods); the `<family-slug>:<percent-encoded-relativeDir>` handle format; `resolveContainedDir`'s known forward-slash-root bugfix (reused unchanged, not re-litigated).
+- **Batch 3**: `observationView.ts#getObservationRelationships` and `GET /api/observations/<handle>/relationships`; `ObservationWorkspace`/`TargetOverlaySvg`/`ObservationInspector`/`EvidenceFieldView`/`useArtifactDetail`/`targetOrder.ts` component/hook boundaries; the coordinate-mapping decision (`requestConfig.viewport` as the canonical SVG `viewBox` source, geometry never rewritten); the `data-target-name` attribute already present on rendered `<rect>`/`<g>` elements.
+
+Batch 4 extends these mechanisms exactly - no second observation viewer, no second evidence index, no second media-loading path was created.
+
+## 5. Frozen planning authority inspected
+
+`docs/DOCUMENTATION_PRESERVATION_POLICY.md`, `docs/PROJECT_MILESTONES.md` (Milestone 8), `docs/ROADMAP.md` (v0.8), `docs/plans/v0.8-implementation-plan.md` (Batch 4 section + cross-batch invariants) - all previously read in full during Batches 1-3, re-confirmed unchanged. `docs/ARCHITECTURE.md`, `docs/CONTRACTS.md` (previously read in full), `docs/WORKFLOWS.md`, `docs/COMMANDS.md` (then edited). New this batch, read in full: `src/domain/comparison.ts`, `src/domain/frontendContracts.ts`, `src/domain/frontendContractEvaluationArtifact.ts`; targeted reads of `src/domain/frontendContractEvaluation.ts` (`UnexpectedChangeResult`, `FrontendContractEvaluationInput/Result`) and the three readers (`comparisonArtifactReader.ts`, `frontendContractArtifactReader.ts`, `frontendContractEvaluationArtifactReader.ts` - function names confirmed, bodies already known from having authored `classify.ts` in Batch 2).
+
+Confirmed Batch 4's title/scope in `docs/plans/v0.8-implementation-plan.md` match the task exactly; no material difference found.
+
+## 6. my-dev-kit retrieval
+
+Index built successfully at `$WORKFLOW_ROOT\my-dev-kit-index`. All seven required searches were run (comparison artifact ownership, comparison engine ownership, frontend contract shapes, contract evaluation ownership, viewer linked-evidence/index APIs, Batch 3 observation viewer, existing protected/preserved-regression tests). Every result matched direct source inspection - `src/domain/comparison.ts`, `comparisonEngine.ts`, `frontendContracts.ts`, `frontendContractEvaluation.ts`, `frontendContractEvaluationArtifact.ts`, the three readers, and the application services were all surfaced consistently.
+
+## 7. Comparison contract audit (task §10)
+
+Recorded from `src/domain/comparison.ts` (full read):
+
+- `comparisonId` (fresh per execution), `comparisonRequestId` (deterministic, `compare(A,B) !== compare(B,A)`).
+- `before`/`after`: **ordered**, distinct fields (`ComparisonSourceObservationReference` = `{observationId, requestId, producer:{name,version}, observationSchemaVersion, screenshot:{path}}`) - never swappable, confirmed by the type's own doc comment ("Comparison is ordered... never a swappable pair").
+- `config: ComparisonConfig`, `comparability: ComparabilityResult` (`state` + `reasons[]`, each reason carrying `code`/`severity`/`message`), `configurationChanges: TargetConfigurationChange[]` (`added`/`removed`/`locator-changed`), `relationshipsBefore`/`relationshipsAfter: LayoutRelationshipGraph` (the pre-persisted graphs, not re-derivable data), `differences: ComparisonDifference[]`, `relationshipChanges: RelationshipChangeRecord[]`, `expectedDependencyEvidence: ExpectedDependencyEvidence[]`, `diagnostics: Diagnostic[]`, `limits: {truncated, omittedFields, omittedTargetPairs}`.
+- Source references carry logical identity (`observationId`/`requestId`/`producer`/`observationSchemaVersion`) - never a persisted filesystem path. Confirmed: no path field anywhere in `ComparisonSourceObservationReference`.
+
+## 8. Source-observation resolution rule (task §11)
+
+**Exact match on all four available identity fields simultaneously**: `observationId`, `requestId`, `producer.version` (`producer.name` is already a fixed constant, `PRODUCER_NAME`, so only `.version` varies), and `observationSchemaVersion` - implemented in `src/viewerServer/evidence/linkedEvidence.ts#resolveObservationByReference`. Zero matches → `{status: 'missing'}`. Two or more exact matches → `{status: 'ambiguous', count}` - **never silently picks one** (proven with a real duplicated-manifest fixture in `tests/unit/linkedEvidenceServer.test.ts`). No folder-name/screenshot-filename/URL/target-set/geometry-based matching exists anywhere in this module. The resolution walks the bounded evidence tree once per lookup (mirroring Batch 2's `findImportedReferenceDir` pattern exactly, applied consistently here for comparisons/baseline-contracts/change-contracts too).
+
+## 9. Evaluation linked-artifact resolution rule
+
+`FrontendContractEvaluationArtifact` references are resolved by exact identity, each independently:
+
+- **Comparison**: exact `comparisonId` **and** `comparisonRequestId` (`resolveComparisonByIdentity`).
+- **Baseline contract**: exact `baselineId` (`resolveBaselineContractById`).
+- **Per-change contract**: exact `contractId` (`resolveChangeContractById`).
+- **Before/after observations**: the same exact-reference rule as §8 (`resolveObservationByReference`), applied to `evaluation.before`/`evaluation.after`.
+
+All five resolutions run in parallel (`Promise.all`) inside `src/viewerServer/evidence/evaluationView.ts#getEvaluationView`, each independently reporting `resolved`/`missing`/`ambiguous` - one missing/ambiguous linked artifact never blocks resolution of the others (proven in `tests/unit/linkedEvidenceServer.test.ts`: a missing baseline and a missing comparison are each tested independently while the rest of the evaluation view still resolves correctly).
+
+## 10. Comparison-view architecture
+
+`src/viewerServer/evidence/comparisonView.ts#getComparisonView(root, handle)`: same handle-decode → contained-dir-resolve → re-stat → re-classify discipline as `observationView.ts`/`mediaResolver.ts` (Batches 2-3). Requires `family === 'comparison'` and `supportState === 'supported'` (else `404`/`409`), then resolves `artifact.before`/`artifact.after` via §8's rule. Route: `GET /api/comparisons/<handle>/view` → `{ok:true, before: LinkStatus, after: LinkStatus}`. The comparison's own full payload is **not** duplicated in this response - the browser fetches it separately through the existing, unchanged `GET /api/artifacts/<handle>` (Batch 2), and the resolved before/after `handle`s are fed straight into that same existing route for the source observations. This keeps the new route minimal/ephemeral and avoids inventing a second artifact-detail contract.
+
+## 11. Before/after reuse of Batch 3 components (task §35)
+
+`viewer/src/components/ComparisonObservationPane.tsx` is built **entirely** from Batch 3's existing lower-level primitives: `useArtifactDetail` (unchanged), `orderedTargets` (unchanged), `TargetOverlaySvg` (one small additive change, below). No second screenshot-loading, coordinate-transform, or geometry-rendering implementation exists anywhere in Batch 4. The comparison's own persisted `relationshipsBefore`/`relationshipsAfter` are passed directly into `TargetOverlaySvg`'s existing `relationships: LayoutRelationshipGraph | undefined` prop - **`deriveLayoutRelationships` is never called to replace them** (grep-verified: no import of `deriveLayoutRelationships` exists in any Batch-4 file except the pre-existing Batch 3 `observationView.ts`, which Batch 4 does not modify).
+
+`TargetOverlaySvg.tsx` gained one additive, optional prop: `highlightNames?: ReadonlySet<string> | undefined`, rendering an extra `--highlighted` CSS class on any rectangle whose name is in the set, alongside (never replacing) the existing single-select `selected`/`aria-pressed` interaction. This lets a relationship-subject difference or a two-target contract primitive (e.g. `targets-do-not-overlap`) emphasize both named targets without changing Batch 3's existing single-select contract or its passing tests (`npm run test:browser` re-run in full, §21 below - all pre-existing Batch 3 tests pass unmodified).
+
+## 12. Confirmation: `compareObservations` was **not** called for viewer reconstruction
+
+Grep-verified across every Batch 4 file (`src/viewerServer/evidence/{linkedEvidence,comparisonView,evaluationView}.ts`, every `viewer/src/**` file touched this batch): zero imports of `compareObservations` or `comparisonEngine.js`. The persisted `ComparisonArtifact` (`differences`, `relationshipsBefore`/`After`, `comparability`, `configurationChanges`, `expectedDependencyEvidence`, `diagnostics`, `limits`) is read unchanged via the existing Batch 2 `GET /api/artifacts/<handle>` and rendered as-is in `ComparisonWorkspace.tsx`.
+
+## 13. Differences displayed (task §15)
+
+All 13 canonical `DifferenceKind` values are rendered generically (kind/subject/before/after/delta, exactly as persisted, `JSON.stringify`'d for `before`/`after`/`delta` since their shape is difference-kind-dependent per the domain type's own design): `appeared`, `disappeared`, `moved`, `resized`, `visibility-changed`, `clipping-changed`, `containment-changed`, `horizontal-overflow-changed`, `vertical-overflow-changed`, `page-size-changed`, `scroll-owner-changed`, `relative-position-changed`, `relationship-changed`. No new PASS/FAIL severity is assigned anywhere - `ComparisonWorkspace.tsx`'s difference list is presentation-only.
+
+## 14. Difference target highlighting (task §16)
+
+`subjectTargetNames(subject: ComparisonDifferenceSubject)`: `type: 'target'` → `[subject.target]`; `type: 'relationship'` → `[subjectTarget, relatedTarget].filter(defined)`; `type: 'page'` → `[]` (no target ever fabricated for a page-level subject). Clicking a difference calls `highlightSubject`, which sets the first name as the single interactive `selected` target and any remaining name(s) as `highlightNames`. Because `TargetOverlaySvg` only ever renders a rectangle for a target with real geometry in *that specific* observation, an `appeared` target (absent in `before`) simply has no rectangle in the Before pane, and a `disappeared` target (absent in `after`) has none in the After pane - **never fabricated**, proven with a real Chromium test (`comparisonEvaluationWorkspace.test.ts`, "appeared/disappeared target behavior") that asserts a rectangle count of exactly `0` on the absent side and `1` on the present side, for both targets.
+
+## 15. Comparability presentation (task §18)
+
+`.comparability-banner--{comparable|comparable-with-warnings|incomparable}` renders `artifact.comparability.state` and every reason with its own severity class (`blocking`/`warning`/`unassessed`) and message unchanged. An `incomparable` result gets `role="alert"` and a red-bordered banner - visually unmistakable, proven with a real Chromium test against a genuinely `incomparable` fixture (two observations with different `requestConfig.viewport` producing a real `viewport-mismatch` blocking reason from `compareObservations` itself, never asserted/faked).
+
+## 16. Target configuration changes (task §19)
+
+Rendered as their own `Configuration changes` section (`kind` + `target`), entirely separate from the `Differences` section that shows `appeared`/`disappeared` - the two lists never merge or share a component.
+
+## 17. Expected dependency evidence (task §20)
+
+Rendered under the heading "Expected dependency evidence (explicit, non-causal)"; each entry shows `cause.target.property direction → effect.target.property direction: outcome`, where `outcome` is exactly one of `consistent`/`not-observed`/`contradictory-to-declaration`/`unavailable` - never rephrased as a pass/fail or causal claim.
+
+## 18. Comparison diagnostics and limits (task §21)
+
+`artifact.limits.truncated === true` renders a visible, non-suppressible banner listing `omittedFields`/`omittedTargetPairs`; `artifact.diagnostics` (when non-empty) render as their own section. Neither is hidden behind a successful-looking default state.
+
+## 19. Contract/evaluation architecture
+
+`src/viewerServer/evidence/evaluationView.ts#getEvaluationView(root, handle)` mirrors `comparisonView.ts` exactly, resolving all five linked references (§9) in parallel. Route: `GET /api/evaluations/<handle>/view` → `{ok:true, comparison, baseline, change, before, after}` (each a `LinkStatus`). `viewer/src/components/EvaluationWorkspace.tsx` fetches the evaluation's own already-loaded artifact (from `ArtifactPreview`'s existing `useArtifactDetail`) plus this view route, then calls `useArtifactDetail` four more times (baseline/change/comparison handles, plus reusing `ComparisonObservationPane` for before/after) - all through the same existing Batch 2 on-demand-loading contract, never a new artifact-fetching mechanism.
+
+## 20. Confirmation: `evaluateFrontendContract` was **not** called for viewer reconstruction
+
+Grep-verified: zero imports of `evaluateFrontendContract` or `frontendContractEvaluation.js`'s evaluator export anywhere in Batch 4's `src/viewerServer/` or `viewer/src/` code (only `UnexpectedChangeResult`, a pure type, is imported for typing). `overallVerdict`, `clauseResults`, `activeBaselineClauseIds`, `supersededBaselineClauseIds`, and `unexpectedChanges` are the persisted artifact's own fields, read unchanged via `GET /api/artifacts/<handle>` and rendered as-is.
+
+## 21. Baseline clauses / change-scope / clause results / active-superseded / unexpected changes / overall verdict
+
+- **Clause joining by exact `clauseId` only** (`viewer/src/components/ClauseResultRow.tsx`, `EvaluationWorkspace.tsx`): a `Map<clauseId, {source, clause}>` is built from the loaded baseline's `clauses` and the loaded change contract's `clauses`; each `clauseResults` entry is looked up by its own `clauseId` - never by target/primitive-shape/category/position/text similarity. An id present in neither loaded contract renders as an honest "unresolved clause definition" (never a fabricated category/primitive) - a distinct "Unresolved clause definitions" section exists specifically for this case.
+- **Baseline clauses** are shown in their own section, distinctly from per-change categories, each tagged `active` or `superseded` **exclusively from the evaluation artifact's own `activeBaselineClauseIds`/`supersededBaselineClauseIds`** - never recomputed from clause-id overlap or any other inference.
+- **Per-change clauses** are grouped into four sections in the frozen category order (`requested`, `expected-dependent`, `protected`, `preserved`); `expected-dependent` clauses additionally show their `required`/`permitted` mode without merging the two modes' meaning.
+- **Clause result status** (`pass`/`fail`/`unavailable`/`conflict`) is preserved exactly via `statusLabel()` - `unavailable` always shows its `reason`, `conflict` always shows its `reason` and `conflictingClauseIds`; neither is ever collapsed to a boolean or converted to `fail`.
+- **Unexpected changes** render in their own section, `classification: 'unexpected'` preserved verbatim, with target highlighting from the same `subjectTargetNames`-style extraction as ordinary differences (since `UnexpectedChangeResult.subject` reuses `ComparisonDifferenceSubject` unchanged - confirmed in `frontendContractEvaluation.ts`).
+- **Overall verdict**: `artifact.overallVerdict` renders directly in a large `.overall-verdict--PASS`/`.overall-verdict--FAIL` banner - the UI performs no verdict computation of its own anywhere in this batch's code (grep-verified: no `every(...status==='pass')`-style logic exists in `EvaluationWorkspace.tsx`).
+
+## 22. Target cross-highlighting from contract primitives (task §34)
+
+`viewer/src/contract/clauseTargets.ts#primitiveTargetNames` is an exhaustive `switch` over every `ContractPrimitiveKind`: single-target primitives (`target-visible`, `target-not-clipped`, `target-width-within-bound`, `target-does-not-own-scroll`, `target-begins-below-initial-viewport`, `property-unchanged-within-tolerance`, `property-increases`, `property-decreases`) return `[target]`; two-target primitives (`targets-do-not-overlap`, `target-wider-than`, `target-follows-vertically`) return `[targetA, targetB]`; `target-fits-inside` returns `[target, container]`; `relationship-unchanged` returns `[subjectTarget, relatedTarget].filter(defined)`; the two page-level primitives (`document-width-fits-viewport`, `scroll-owner-is-document`) return `[]` - clicking their clause row is disabled (`names.length === 0` → `disabled`) rather than highlighting an invented target.
+
+## 23. All-pass proof (task §33/§44 Case A)
+
+**Fixture**: `tests/support/evidenceFixtures.ts#writeAllPassPipelineFixture` - the deliberate all-pass counterpart to the existing `writeFullPipelineFixture`, differing only in the *actual rendered geometry/style* fed to the real `compareObservations`/`evaluateFrontendContract` workflow (via `evaluateAndPersistFromArtifactRoots`): `rightAd` genuinely unchanged (protected clause genuinely satisfied) and `navigation` genuinely never clipped (`scrollWidth === clientWidth`, preserved clause genuinely satisfied). Verified directly against the real evaluator's output before use (§30 below) - `overallVerdict: "PASS"`, all four clauses `pass`. `overallVerdict` is never hand-edited.
+
+**Real-browser proof**: `tests/browser/comparisonEvaluationWorkspace.test.ts`, "Case A" describe block - selects the evaluation, confirms `.overall-verdict--PASS`, confirms both before/after screenshots load through the real `/api/media/observation:...` endpoint, confirms `requested-nav`/`protected-rightad`/`preserved-nav-unclipped` are each `.clause-row--pass`, and confirms clicking the `requested-nav` clause row highlights the exact `navigation` target (`aria-pressed="true"` on its real SVG rectangle).
+
+## 24. Safety-failure proof (task §32/§44 Case B)
+
+**Fixture**: the existing `writeFullPipelineFixture` (reused unchanged, not a new fixture) - already produces, through the real canonical evaluator, `overallVerdict: "FAIL"` with `requested-nav: pass`, `protected-rightad: fail`, `preserved-nav-unclipped: fail` (confirmed by direct inspection before use, §30). This is exactly the required safety case: **a requested/local change passes while a protected clause and a preserved clause both fail, and the overall verdict is FAIL** - never hand-constructed.
+
+**Real-browser proof**: `tests/browser/comparisonEvaluationWorkspace.test.ts`, "Case B" describe block - selects the evaluation, confirms `.overall-verdict--FAIL`, confirms `requested-nav` is `.clause-row--pass` while `protected-rightad` and `preserved-nav-unclipped` are both `.clause-row--fail`, confirms before/after visual context remains fully available (both screenshots render) despite the overall failure, and confirms clicking the failing `protected-rightad` clause highlights the exact `rightAd` target.
+
+## 25. API changes
+
+| Route | Method | Semantics |
+|---|---|---|
+| `GET /api/comparisons/<handle>/view` | GET/HEAD | `{ok:true, before: LinkStatus, after: LinkStatus}`. `404` unknown handle, `409` not-a-comparison/not-currently-loadable, `405` any write method. |
+| `GET /api/evaluations/<handle>/view` | GET/HEAD | `{ok:true, comparison, baseline, change, before, after}` (each a `LinkStatus`). `404`/`409`/`405` as above. |
+
+`/api/status`, `/api/index`, `/api/artifacts/<handle>`, `/api/media/<handle>/<role>`, `/api/observations/<handle>/relationships` are byte-for-byte unchanged.
+
+## 26. PWA cache boundary
+
+**PASS.** Both new routes live under `/api/`, already covered by Batch 1's `navigateFallbackDenylist: [/^\/api\//]` - no service-worker configuration change was needed. `tests/unit/viewerPwaBuild.test.ts` gained one explicit assertion against the real built `sw.js`: still exactly one `registerRoute` call, and the precache manifest contains neither `/api/comparisons` nor `/api/evaluations`.
+
+## 27. Files created
+
+- `src/viewerServer/evidence/linkedEvidence.ts`, `comparisonView.ts`, `evaluationView.ts`
+- `viewer/src/components/ComparisonObservationPane.tsx`, `ComparisonWorkspace.tsx`, `EvaluationWorkspace.tsx`, `ClauseResultRow.tsx`
+- `viewer/src/contract/clauseTargets.ts`
+- `viewer/src/hooks/useLinkedEvidence.ts`
+- `viewer/src/types/comparison.ts`, `contracts.ts`
+- `tests/unit/linkedEvidenceServer.test.ts`
+- `tests/browser/comparisonEvaluationWorkspace.test.ts`
+- `docs/reports/v0.8-comparison-contract-inspection-batch4.md` (this file)
+
+## 28. Files modified
+
+- `src/viewerServer/httpServer.ts` - added the two new routes (§25); `/api/status`, `/api/index`, `/api/artifacts/<handle>`, `/api/media/<handle>/<role>`, `/api/observations/<handle>/relationships`, and static-asset serving unchanged.
+- `viewer/src/components/TargetOverlaySvg.tsx` - one additive, optional `highlightNames` prop (§11); existing `selected`/`onSelect`/`toggles` behavior unchanged.
+- `viewer/src/components/ArtifactPreview.tsx` - branches to `ComparisonWorkspace`/`EvaluationWorkspace` for their families; every other family's raw-JSON preview unchanged.
+- `viewer/src/styles/index.css` - additive rules for the new workspaces.
+- `tests/support/evidenceFixtures.ts` - added `writeAllPassPipelineFixture`, `writeBaselineSupersessionFixture`, `writeAppearedDisappearedComparisonFixture`, `writeIncomparableComparisonFixture` (all built through the real canonical `compareObservations`/`evaluateFrontendContract` workflow, never hand-edited results); `buildObservation` gained optional `pageEvidence`/`viewport` parameters (already added in Batch 3, unchanged here).
+- `tests/browser/viewerEvidenceShell.test.ts` - two pre-existing Batch 2 tests that selected a `comparison` record to exercise the *generic* raw-JSON-preview/no-visualization path now legitimately conflict with Batch 4's real comparison workspace; both were repointed to `baseline-contract` (which still exercises exactly the generic path/invariant they were written to protect) - the same kind of sanctioned evolution as Batch 1→2's placeholder-text update, Batch 2's `TST-401`, and Batch 3's analogous `viewerEvidenceShell.test.ts` update.
+- `tests/unit/viewerPwaBuild.test.ts` - added the explicit Batch 4 cache-boundary assertion (§26).
+- `docs/ARCHITECTURE.md`, `docs/COMMANDS.md` - new/updated Batch 4 sections (condensed versions of §7-§22 above).
+
+## 29. Tests added/modified and behavior protected
+
+| Test file | Level | Protects |
+|---|---|---|
+| `linkedEvidenceServer.test.ts` (15 tests) | unit/integration (real HTTP) | Exact before/after resolution; honest `missing` when a source observation is removed; honest `ambiguous` with a real duplicated-identity fixture (count=2); 409 for a non-comparison/non-evaluation handle; 404 unknown handle; 405 write methods; exact resolution of all five evaluation links; missing baseline reported honestly; missing comparison reported honestly; the all-pass fixture is a genuine `PASS` with every clause `pass`; the full-pipeline fixture is a genuine `FAIL` with the exact required requested-pass/protected-fail/preserved-fail signature; the baseline-supersession fixture reports real active/superseded ids and a real unexpected change. |
+| `comparisonEvaluationWorkspace.test.ts` (4 tests, real Chromium) | browser | Case A (all-pass) full proof (§23); Case B (safety failure) full proof (§24); appeared/disappeared honest rectangle presence/absence; incomparable state visibly unmistakable with its real blocking reason. |
+| `viewerEvidenceShell.test.ts` (2 updated) | browser | Generic Batch 2 on-demand-load/no-visualization invariants still hold for families without a Batch 3/4 workspace. |
+| `viewerPwaBuild.test.ts` (+1) | build/integration | New routes covered by the existing `/api/` denylist, no new runtime-caching rule. |
+
+## 30. A methodology note: fixtures verified against the real evaluator before use
+
+Before writing any assertion against `writeAllPassPipelineFixture`, `writeFullPipelineFixture` (reused), or `writeBaselineSupersessionFixture`, each was run once through the real `readFrontendContractEvaluationArtifact` reader in an isolated scratch test and its actual `overallVerdict`/`clauseResults`/`activeBaselineClauseIds`/`supersededBaselineClauseIds` were inspected directly (not assumed) - this is how the exact safety-case signature (`requested-nav: pass`, `protected-rightad: fail`, `preserved-nav-unclipped: fail`, `overallVerdict: "FAIL"`) in the pre-existing `writeFullPipelineFixture` was *discovered*, not designed - it already existed from Batch 2/3's fixture reuse and turned out to exactly match Batch 4's required safety case. The scratch inspection tests were deleted before finalizing (never committed); this report documents the methodology rather than leaving throwaway files behind.
+
+## 31. 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** — 1101/1101 tests, 60/60 files |
+| `npm run build` | **PASS** — unchanged Node/library output plus `dist/viewerServer/evidence/{comparisonView,evaluationView,linkedEvidence}.js` and the rebuilt `dist/viewer/**` PWA |
+| `npm run check:docs` | **PASS** — "Documentation check passed (17 required files)." |
+| `npm run test:browser` | **PASS** — 141/141 tests, 14/14 files (real Chromium; run in full per task §46) |
+| `git diff --check` | **PASS** — no whitespace errors (only expected LF→CRLF notices) |
+
+## 32. Built viewer smoke (task §47)
+
+Fixture: one real before/after observation pair, a real comparison, a real baseline contract, a real per-change contract (the "milestone signature" clause set), and a real evaluation - all built via a one-off script (not committed, `$WORKFLOW_ROOT\tmp`) calling the actual compiled `dist/artifacts/*.js`/`dist/application/frontendContractEvaluationService.js` modules directly, 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 passed against the real running built server:
+
+- `/api/status` → `200`; `/api/index` → all 6 real records (`observation` x2, `comparison`, `baseline-contract`, `change-contract`, `contract-evaluation`), all `supported`.
+- `/api/comparisons/<handle>/view` → `200`, both `before`/`after` `resolved` to the exact real observation handles.
+- `/api/evaluations/<handle>/view` → `200`, all five links (`comparison`/`baseline`/`change`/`before`/`after`) `resolved`.
+- `/api/artifacts/<evaluation-handle>` → `overallVerdict: "FAIL"`, `clauseResults`: `requested-nav: pass`, `expected-workspace: pass`, `protected-rightad: fail`, `preserved-nav-unclipped: fail` - the exact required safety signature, produced by the real canonical workflow, not edited.
+- Both before/after screenshots → `200 image/png`.
+- Unknown comparison/evaluation handles → `404`; write method (`POST`) → `405`.
+- PWA still loads (`/`, `/sw.js` both `200`); `sw.js` contains no `api/comparisons`/`api/evaluations` reference.
+- `netstat` confirmed `127.0.0.1:4319` only, never `0.0.0.0`.
+- Server located by its real PID and terminated with `taskkill /F`; a follow-up `netstat` confirmed the port was released.
+- A post-shutdown listing of the smoke evidence root shows exactly the 8 fixture files the script wrote - no stray writes, no modification.
+
+**Result: PASS.** Logs retained under `$WORKFLOW_ROOT\logs\` (`smoke-server.log`, `index-response.json`, `eval-detail.json`, `smoke-checks-1.log`, `smoke-checks-2.log`).
+
+## 33. Generated path inventory
+
+| Path | Disposition |
+|---|---|
+| `WORKFLOW_ROOT\cache\npm` | Retained (npm cache from the my-dev-kit-index `npx` invocation) |
+| `WORKFLOW_ROOT\tmp\vite-cache`, `WORKFLOW_ROOT\tmp\build-smoke-comparison.mjs` | Retained (build cache empty again, same finding as every prior batch; the smoke-fixture script is dev/readiness tooling only, not committed) |
+| `WORKFLOW_ROOT\logs\*` | Retained (smoke evidence, §32) |
+| `WORKFLOW_ROOT\smoke\evidence-root` | Retained (real evidence fixture tree built for the smoke test) |
+| `WORKFLOW_ROOT\my-dev-kit-index\*` | Retained (successful index + cache-metadata) |
+| `WORKFLOW_ROOT\fixtures` | Retained, empty/unused (no committed deterministic repository fixture was needed - all Batch 4 fixtures are built programmatically via `tests/support/evidenceFixtures.ts`, matching the existing repository convention) |
+| 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 every prior batch) |
+| Sibling `...my-frontend-observer.my-dev-kit-workflow\v0.8\{batch-01,batch-02,batch-03}` | Untouched (verified, §3) |
+
+## 34. Repository pollution check
+
+**PASS.** `git status --short` before staging showed only the 9 modified + 13 new Batch-4-owned paths listed in §27/§28. No unexpected file or directory appeared anywhere in the repository. No malformed sibling Batch 4 workflow path exists anywhere under `Z:\Users\newuser\Projects\` (verified directly, §3).
+
+## 35. Batch 1/2/3 regression check
+
+**PASS.** All Batch 1 tests (`view` CLI, `127.0.0.1`/port `4319`, PWA shell/installability, cache boundary, server cleanup), Batch 2 tests (evidence indexing, unsupported-version handling, safe handles, on-demand artifact/media loading, filesystem containment), and Batch 3 tests (observation SVG workspace, coordinate mapping, relationship reuse, unresolved-target honesty) pass unmodified except the two `viewerEvidenceShell.test.ts` updates described in §28, which preserve the exact invariants they originally protected while accounting for Batch 4's legitimate new comparison-family behavior.
+
+## 36. v0.1-v0.7 regression check
+
+**PASS.** Every pre-v0.8 unit and browser test suite (`observe`, `compare`, `approve-baseline`, `save-change-contract`, `evaluate-contract`, `import-reference`, `approve-reference`, `evaluate-reference-fidelity`) remains covered and passing - none was touched by this batch's diff. `src/domain/`, `src/artifacts/*Writer.ts`, and every existing reader/engine (`compareObservations`, `evaluateFrontendContract`, `deriveLayoutRelationships`) are byte-for-byte unchanged.
+
+## 37. Deviations
+
+- The task's §5 "Required Batch 4 root" restatement conflicted with its own `Join-Path` algorithm and verification assertions; resolved per §2 above by following the literal, executable, self-verifying algorithm. This is the only deviation from the task's literal text, and it was necessary to satisfy the task's own stated assertions rather than an arbitrary choice.
+- No other deviations. Every other task step (predecessor-report inspection, my-dev-kit retrieval, the coordinate/contract audits, all required test categories, the full validation chain including `test:browser`, and the built-CLI smoke) was executed as specified.
+
+## 38. Remaining uncovered risks
+
+- **`highlightNames` only distinguishes "the primary selected target" from "secondary highlighted targets" visually (different CSS classes), not through `aria-pressed`** (which remains true only for the single `selected` target, matching Batch 3's existing accessibility contract). A screen-reader user selecting a relationship-subject difference will not hear the second (related) target announced as selected, only visually distinguished. Not a regression (Batch 3 never had multi-target selection at all), but a genuine accessibility gap for the new multi-target case specifically.
+- **`resolveObservationByReference`/`resolveComparisonByIdentity`/etc. each independently re-walk the bounded evidence tree** (same pattern as Batch 2's `findImportedReferenceDir`, carried forward deliberately for consistency rather than introducing a new caching layer). An evaluation view triggers five such walks in parallel; for an evidence root near the `MAX_MANIFEST_CANDIDATES` bound, this is more filesystem work per evaluation-view request than a single shared index pass would need. Not a correctness risk; the same category of "report rather than pre-optimize" risk Batch 2 already recorded.
+- **`ComparisonWorkspace`/`EvaluationWorkspace` do not yet offer a synchronized zoom/pan or a locked view between before/after panes** - explicitly out of scope for this batch (task §42), planned for a later batch.
+- Batches 1-3'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.
+
+## 39. Out-of-scope confirmation
+
+Confirmed absent from this batch's diff: external-reference image display, reference regions, reference/candidate side-by-side mode, reference applicability UI, reference fidelity UI, reference/runtime binding, explicit-binding cross-selection, image zoom/pan, synchronized view lock, bounded-agent-context UI, runtime/static correlation UI, annotation, contract editing, baseline approval, contract approval, reference approval, source editing, automatic binding, automatic visual analysis, pixel difference, cloud hosting, database, authentication, collaboration.
+
+## 40. Final verdict
+
+Batch 4 ("Before/after comparison and contract/change-scope inspection") is implemented and independently validated: a developer can select an existing `ComparisonArtifact`, see its exact persisted before/after observations resolved by canonical identity and displayed side by side through the reused Batch 3 screenshot/SVG machinery, inspect every canonical difference/relationship-change/comparability/dependency-evidence category exactly as persisted, select an existing `FrontendContractEvaluationArtifact`, see its exact linked baseline/per-change contracts/comparison/observations resolved by canonical identity, inspect every clause result (baseline active/superseded, requested/expected-dependent/protected/preserved, unexpected) joined by exact `clauseId`, and see the authoritative overall `PASS`/`FAIL` verdict rendered unmistakably - including the required safety case where a requested change passes while a protected and a preserved clause both fail, proven against a real canonically-evaluated fixture in real Chromium. `compareObservations` and `evaluateFrontendContract` were never invoked for viewer reconstruction anywhere in this batch. No Batch 5+ visualization, no v0.9 annotation, and no release/publication action was taken. Package version remains `0.7.0`.