@dailephd/my-frontend-observer 0.10.0 → 0.10.1

package/docs/ARCHITECTURE.md

@@ -1,1385 +1,1394 @@
-# Architecture
-
-## v0.10 visual workflow boundaries
-
-`VisualChangeWorkflowArtifact` (`1.0.0`) is the only new persisted v0.10
-family. It owns frozen scope, explicit activation/restoration, immutable
-attempt and review revisions, and optional references to governance results.
-The Viewer is the human workflow entry; `checkProject` remains the canonical
-evaluator. `VisualChangeAgentHandoff` (`1.0.0`) is a generated, non-persisted
-transfer contract. An external human or coding agent edits source. Optional
-orchestrator metadata is traceability only and Observer never imports or runs
-the orchestrator. Human acceptance is separate from baseline/reference
-governance and never rewrites prior workflow evidence.
-
-## v0.8.1 project workflow
-
-Versioned project configuration (`1.0.0` compatibility plus current `1.1.0`
-acceptance input), upward discovery, centralized managed paths, and the atomic
-alias catalog live under `src/projectWorkflow`. Aliases select exact canonical
-artifact directories; they never replace artifact identities.
-
-`src/application/projectCheckService.ts` composes the existing observation,
-comparison, contract-evaluation, reference-reader, explicit-binding,
-compatibility, and fidelity owners. `src/projectWorkflow/checkAcceptance.ts`
-owns contained acceptance-input resolution and shared file-wrapper parsing.
-`checkResult.ts` owns the bounded ephemeral projection, not a persisted check
-artifact or evaluation engine. Status precedence is `BLOCKED`, then `FAIL`,
-then `PASS` when all configured executable dimensions pass, then
-`REVIEW_REQUIRED` when comparison is the only evidence. Canonical observations,
-comparisons, and contract evaluations remain persisted; reference fidelity and
-the workflow result remain in memory/presentation.
-
-## Current package architecture
-
-The current repository is one published TypeScript ESM package
-(`@dailephd/my-frontend-observer@0.9.1`). The CLI remains
-`my-frontend-observer`; the npm scope does not rename the product or artifact
-identities.
-
-- `src/cli.ts` is the real, thin public CLI parsing/dispatch/presentation
-  boundary for the current command surface (`observe`, `compare`,
-  `approve-baseline`, `save-change-contract`, `evaluate-contract`,
-  `import-reference`, `approve-reference`, `evaluate-reference-fidelity`,
-  `view`, `init`, `capture`, `check`); argument parsing and output formatting
-  only, per command - domain semantics remain owned by application/domain
-  services rather than the CLI. v0.6 added no new CLI command; v0.7 added the
-  three external-reference commands; v0.8 added `view`; v0.8.1 added `init`,
-  `capture`, and `check` and made `view` project-aware while preserving its
-  standalone `--root` behavior.
-- `src/index.ts` is the library entry point re-exporting the observer-owned
-  contracts/functions from every layer below, including the v0.6 bounded-agent-
-  context projection and runtime/static correlation surface, and the v0.7
-  external-reference/region/requirement/applicability/compatibility/binding/
-  fidelity/correction-workflow surface (`prepareReferenceCorrection`/
-  `reviewReferenceCorrectionAttempt` remain programmatic-only, with no CLI
-  command).
-- `scripts/clean.mjs` safely removes only the project `dist/` directory.
-- `scripts/check-docs.mjs` validates the canonical documentation foundation,
-  roadmap version presence, and the no-batches rule.
-- TypeScript, ESLint, Vitest, and package configuration provide foundation
-  validation, now exercised by real product tests (`tests/unit/`,
-  `tests/browser/`).
-
-Batch 1 added the observation domain/schema and safety-policy layer
-(`src/domain/`, `src/request/`, `src/safety/`). Batch 2 added a real
-Playwright Chromium browser adapter (`src/browser/`), a minimal application
-seam invoking it (`src/application/`), and a deterministic browser
-fixture/test boundary (`tests/fixtures/`, `tests/browser/`, run via
-`npm run test:browser`). Batch 3 extended that single browser adapter with an
-internal page/target measurement module (`src/browser/evidenceCapture.ts`)
-that reads page and explicit-CSS-target evidence from the same live,
-already-ready page used for the screenshot - no second browser/page is ever
-opened, and Playwright objects still never leave `src/browser/`. Batch 4
-added the artifact ownership boundary itself: `src/artifacts/artifactWriter.ts`
-is the one canonical place that writes an observation to disk (temp
-directory, then one atomic rename into `<outputLocation>/<observationId>/`),
-and `src/application/observationPersistence.ts` assembles the frozen
-`ObservationArtifact` from a browser-capture result before handing it to the
-writer. The artifact layer has no Playwright dependency and is testable
-without launching Chromium. Batch 5 completed the boundary chain: `src/cli.ts`
-parses `observe` arguments (CLI-syntax errors only - e.g. malformed
-`WIDTHxHEIGHT`), constructs a raw request, and hands it to the existing
-Batch 1 `normalizeRequest`; on success it calls one new application-level use
-case, `observe()` in `src/application/observationPersistence.ts`, which runs
-the existing `runBrowserCapture` exactly once and, only on success, the
-existing artifact writer exactly once, then returns a small observer-owned
-`ApplicationObservationResult` (observation id, completion state, artifact
-path, target/diagnostic counts) for the CLI to print. The CLI never imports
-Playwright or the filesystem-write path directly. Batch 6 closed the
-remaining real-Chromium coverage gap (a genuine navigation failure, distinct
-from a readiness timeout or a pre-launch safety rejection) and validated the
-packed npm tarball end to end in a clean consumer environment, independent
-of the source checkout. At the end of the v0.1 implementation there was no
-controlled-scroll or comparison behavior.
-
-## Current v0.2 architecture (released/current architecture)
-
-v0.2 extends the same architecture rather than adding a parallel one.
-`src/request/request.ts` now owns a canonical `{name, locators}` target
-model (`TargetLocator`, six frozen kinds) in place of the old CSS-only
-shape; the legacy `{name, selector}` input still normalizes into it. The one
-existing browser-side target resolver/measurement module,
-`src/browser/evidenceCapture.ts`, was extended - not replaced - to resolve
-all six locator kinds against the live page through a single Playwright
-`Locator` per attempt, honor the frozen ordered-fallback/ambiguity/
-unavailable-no-fallback contract, and converge every kind on the same
-measurement path (`captureResolvedTargetRecord`); it additionally computes
-bounded semantic state, derived landmark identity, and configured-target-
-only DOM containment from the same already-resolved elements in the same
-capture pass - no second browser/page, no second resolution algorithm.
-`src/domain/schema.ts` extends `TargetEvidenceRecord`/`TargetResolution`
-additively for schema `1.1.0`, with matching structural validation in
-`isValidObservationArtifact`. `src/cli.ts` gained one CLI/input-boundary-
-only addition, `--targets-file`: it reads and validates only the JSON root
-wrapper (via the already-imported `node:fs`, never `node:fs/promises`) and
-hands the parsed `targets` value into the existing `RawObservationRequest`/
-`normalizeRequest()` path unchanged - there is no second application
-observation use case, and Playwright objects still never leave
-`src/browser/`. The artifact writer, application observation use case, and
-overall boundary chain (`CLI → normalizeRequest → observe() →
-runBrowserCapture → artifact writer`) are unchanged from v0.1.
-
-## Current v0.3 architecture (released/current architecture)
-
-v0.3 extends the same single-observation architecture again; it does not add
-a second browser lifecycle, target resolver, or artifact path.
-`src/request/request.ts` adds one optional `scrollScenario` field to
-`NormalizedObservationRequest` (`ScrollScenario { action }`, exactly
-`window-scroll-by` or `target-scroll-by`); `src/domain/schema.ts` adds the
-matching bounded runtime evidence types (`ScrollRuntimeSnapshot`,
-`ViewportRelationEvidence`, `OverflowEvidence`, `ScrollScenarioTransition`,
-`ScrollOwnerInterpretation`) and structural validation for schema `1.2.0`
-(additive over `1.1.0`). `src/domain/scrollEvidence.ts` holds the pure,
-browser-independent derivations (viewport relation, actual overflow,
-transitions, and `deriveScrollOwner`) so they are unit-testable without
-Chromium. `src/browser/scrollCapture.ts` holds the one browser-side scenario
-capture module: it reuses `evidenceCapture.ts#resolveConfiguredTargets` (now
-exported) to resolve configured targets exactly once, captures an initial
-`ScrollRuntimeSnapshot`, performs the one immediate scroll
-(`window.scrollBy`/`element.scrollBy`, both `behavior: 'instant'`), waits
-exactly two `requestAnimationFrame` cycles, and captures a final snapshot -
-all inside `chromiumAdapter.ts#captureViewportInternal`'s existing single
-navigate → ready → capture flow, strictly before the unchanged
-screenshot/`capturePageEvidence`/`captureTargetEvidence` calls, so every
-downstream capture (including a no-scenario request, which skips this block
-entirely) describes only the final state. `src/cli.ts` gained one CLI/input-
-boundary-only addition, `--scroll-scenario-file`: mirroring
-`--targets-file`, it reads and validates only the file readability/JSON-
-validity/non-array-object-root shape and hands the parsed value straight
-into `RawObservationRequest.scrollScenario` - every scenario/action rule
-(kind, deltas, target reference) stays owned by `normalizeRequest()`. There
-is still one canonical `observe()` application use case and one artifact
-writer; `scrollScenarioEvidence` is simply one more optional field on the
-same `ObservationArtifact`.
-
-## Current v0.4 architecture (released/current architecture)
-
-v0.4 adds one new downstream pipeline that consumes `ObservationArtifact`
-values rather than producing them - it never adds a second browser lifecycle,
-target resolver, or observation engine:
-
-```text
-ObservationArtifact before  ObservationArtifact after
-        \                          /
-         `--------.       .-------'
-                    \     /
-              artifact reader (src/artifacts/artifactReader.ts)
-                       ↓
-              comparability evaluation (src/domain/comparisonEngine.ts)
-                       ↓
-    canonical relationship derivation, called for each side independently
-              (src/domain/relationships.ts#deriveLayoutRelationships)
-                       ↓
-              canonical comparison derivation
-              (src/domain/comparisonEngine.ts#compareObservations)
-                       ↓
-                ComparisonArtifact
-                       ↓
-    atomic comparison writer (src/artifacts/comparisonArtifactWriter.ts)
-
-CLI `compare`
-        ↓
-application service only (src/application/comparisonService.ts)
-        ↓
-[reader → domain comparison → writer, as above]
-```
-
-`src/domain/relationships.ts` froze the layout-relationship contract and
-implements the one canonical pure derivation,
-`deriveLayoutRelationships(observation, options?)`: horizontal/vertical
-order, area overlap, relative width, geometric fit, vertical sequencing,
-page-width fit/exceeds, and a standalone `deriveTargetClipping(record)` -
-all computed only from an already-captured `ObservationArtifact`'s own
-`targetEvidence`/`pageEvidence`, never from a second browser query. DOM
-containment is read directly from the existing v0.2 `TargetContainment`
-evidence rather than re-derived, and stays a distinct concept from
-geometric fit.
-
-`src/domain/comparisonEngine.ts` implements the one canonical pure
-before/after engine, `compareObservations(before, after, config?)`:
-validates both source artifacts, evaluates comparability *before* any
-rendered difference is calculated, calls `deriveLayoutRelationships` once
-per side with the same tolerance, and derives target/page differences and
-relationship changes. `src/artifacts/comparisonArtifactWriter.ts` persists
-the result atomically (sibling temp directory, then one rename) as
-`<outputLocation>/<comparisonId>/manifest.json` only - no screenshot is
-copied; the manifest's `before`/`after` references point back to the
-source observations' own `screenshot.path`. `src/application/
-comparisonService.ts` is the one application-layer seam: `compareAndPersist`
-takes two in-memory `ObservationArtifact`s and does exactly one comparison
-plus exactly one persist; `compareAndPersistFromArtifactRoots` is a thin
-wrapper that additionally reads both sides from disk via the existing
-`src/artifacts/artifactReader.ts#readObservationArtifact` reader (itself
-just a `manifest.json` parse plus the same `isValidObservationArtifact`
-structural gate the writer uses).
-
-`src/cli.ts` gained one new top-level command, `compare`
-(`--before`/`--after`/`--output`/`--config-file`), implemented with the same
-thin-CLI-boundary discipline as `observe`: `parseCompareArgs` handles only
-argument shape/duplication, an optional `loadComparisonConfigFile` reads and
-validates only file readability/JSON-validity/non-array-object-root (exactly
-like `--targets-file`/`--scroll-scenario-file`), and the command body calls
-`compareAndPersistFromArtifactRoots` exactly once. **The CLI's comparison
-path never launches Chromium** - `src/cli.ts` imports nothing from
-`src/browser/` or `src/artifacts/` (it only reaches persistence and artifact
-reading indirectly, through the application-layer seam above), matching the
-same import-boundary discipline already enforced for `observe`.
-
-## Current v0.5 architecture (released/current architecture)
-
-v0.5 adds one new downstream layer that consumes `ComparisonArtifact` values
-(plus the source `ObservationArtifact` pair) rather than producing them - no
-new browser lifecycle, target resolver, or comparison engine is added:
-
-```text
-ObservationArtifact before + after
-              ↓
-existing v0.4 comparison/relationship pipeline (unchanged)
-              ↓
-        ComparisonArtifact
-              ↓                                PersistentBaselineContract
-              |                                          +
-              `------------------------→   PerChangeContract
-                                                          ↓
-                        canonical contract evaluation
-                        (src/domain/frontendContractEvaluation.ts#evaluateFrontendContract)
-                                                          ↓
-                        clause results + unexpected changes + overall PASS/FAIL
-```
-
-`src/domain/frontendContracts.ts` froze the contract/change-scope type,
-constant, and structural-validator vocabulary (Batch 1); `src/domain/
-frontendContractIdentity.ts` froze deterministic contract/baseline/clause
-identity in the same canonicalize+sha256(+opaque-nonce) style as `src/domain/
-comparisonIdentity.ts`. `src/domain/frontendContractEvaluation.ts#evaluateFrontendContract`
-(Batch 2) is the one canonical pure evaluation entry point: it validates its
-five inputs (before/after `ObservationArtifact`, `ComparisonArtifact`,
-`PersistentBaselineContract`, `PerChangeContract`) are structurally coherent
-and mutually consistent, calculates the active baseline clause set after
-explicit supersession, detects bounded structural conflicts, evaluates every
-active clause via the frozen 15-primitive vocabulary against the existing
-`ComparisonArtifact`/`ObservationArtifact` evidence (never re-deriving
-clipping/relationship/scroll-owner facts), classifies unaccounted-for
-`ComparisonArtifact.differences` entries as `unexpected`, and derives one
-overall `PASS`/`FAIL` verdict. It performs no I/O, launches no browser, and
-persists nothing - `src/domain/frontendContractEvaluation.ts` itself remains
-untouched by the persistence layer below (Batch 3).
-
-Batch 3 adds the persistence/application boundary around this frozen domain,
-without redefining it:
-
-```text
-        ComparisonArtifact (read via new src/artifacts/comparisonArtifactReader.ts)
-              +
-PersistentBaselineContract / PerChangeContract
-(read/written via src/artifacts/frontendContractArtifactReader.ts / ...Writer.ts)
-              ↓
-src/application/frontendContractEvaluationService.ts#evaluateAndPersist
-              ↓
-    evaluateFrontendContract()  [called exactly once, unmodified]
-              ↓
-src/domain/frontendContractEvaluationArtifact.ts
-    (minimal additive persisted envelope around the frozen result)
-              ↓
-src/artifacts/frontendContractEvaluationArtifactWriter.ts
-    (atomic write, exactly once on a structurally constructible result)
-```
-
-`evaluateAndPersistFromArtifactRoots` is the CLI-facing wrapper, reading
-before/after observations through the existing `readObservationArtifact` (no
-second observation reader), the comparison and both contract classes
-through the new readers, then delegating to `evaluateAndPersist` exactly
-once - mirroring `application/comparisonService.ts#compareAndPersistFromArtifactRoots`'s
-own thin-wrapper shape.
-
-Batch 4 exposes this through the same thin-CLI boundary already established
-by `observe`/`compare`:
-
-```text
-src/cli.ts (argument parsing, JSON-file-shape checks, help/output formatting,
-            exit-code selection only)
-        ↓
-src/application/frontendContractPersistenceService.ts#approveAndPersistBaseline
-src/application/frontendContractPersistenceService.ts#persistPerChangeContract
-src/application/frontendContractEvaluationService.ts#evaluateAndPersistFromArtifactRoots
-        ↓
-domain validators (isValidPersistentBaselineContract / isValidPerChangeContract)
-+ artifact readers/writers (Batch 3)
-+ evaluateFrontendContract() (Batch 2, unmodified)
-```
-
-Three new top-level commands - `approve-baseline`, `save-change-contract`,
-`evaluate-contract` - each parse only CLI-syntax concerns (duplicate/missing
-flags, JSON-file readability/parseability/object-root shape) and delegate to
-exactly one application-layer call; `src/cli.ts` imports no artifact writer/
-reader module and no browser code, matching the existing `observe`/`compare`
-import-boundary discipline exactly. `approveAndPersistBaseline` adds the one
-new coherence check Batch 3 did not need: verifying a baseline contract's
-frozen `sourceObservation` reference actually matches the supplied
-observation artifact before persisting - explicit approval only, never
-inferred from a `compare` or `evaluate-contract` result. `--enforce` on
-`evaluate-contract` is applied only after evaluation and persistence have
-already completed; it selects the process exit status for an already-final
-`FAIL` result and is never part of any identity or persisted field.
-
-## Current v0.6 architecture (released as `0.6.0`)
-
-v0.6 adds one new downstream, read-only layer that consumes existing v0.1-v0.5
-evidence (`ObservationArtifact`, `ComparisonArtifact`,
-`PersistentBaselineContract`/`PerChangeContract`, and evaluation results)
-plus caller-supplied bounded static candidate evidence - it adds no new
-browser lifecycle, target resolver, observation/comparison/contract engine,
-or persisted artifact family:
-
-```text
-ObservationArtifact(s) + ComparisonArtifact + contract/evaluation evidence
-              ↓
-src/domain/boundedAgentContextProjection.ts#projectBoundedAgentContext
-              ↓
-    BoundedRuntimeTargetProjection
-    (page/viewport identity, stable targets, geometry, runtime behavior,
-     relationships, before/after differences, contract results,
-     requested/expected-dependent/protected/preserved scope reused verbatim
-     from src/domain/frontendContracts.ts, diagnostics, artifact/screenshot
-     references, provenance, adequacy, omission, truncation)
-              ↓
-src/domain/boundedAgentContextCorrelation.ts
-    #deriveRuntimeStaticCorrelations / #attachRuntimeStaticCorrelations
-              ↓
-    RuntimeStaticCorrelation[] (correlated / ambiguous / unavailable,
-    competing candidates preserved verbatim - never collapsed to one owner)
-              ↓
-src/index.ts (public export/correlation boundary only)
-```
-
-`src/domain/boundedAgentContext.ts` freezes the bounded-projection and
-correlation type/constant vocabulary (`Adequacy`, `ADEQUACY_REASON_CODES`,
-`OmissionRecord`, `TruncationRecord`, `BOUNDED_AGENT_CONTEXT_ARTIFACT_KIND`,
-schema `1.0.0`). `src/domain/boundedAgentContextIdentity.ts` derives a
-deterministic logical identity distinct from a fresh per-execution instance
-identity, in the same canonicalize+hash style as
-`comparisonIdentity.ts`/`frontendContractIdentity.ts`.
-`boundedAgentContextProjection.ts` performs no browser I/O and re-derives
-nothing already owned upstream - it reads already-captured artifacts and
-reuses the existing v0.4 relationship/comparison evidence and v0.5
-change-scope clause types directly. `boundedAgentContextCorrelation.ts`
-accepts only plain, caller-supplied candidate static-evidence records; it has
-**no** dependency on `@dailephd/my-dev-kit`, since the audit that preceded
-implementation found no generic static-side retrieval capability actually
-missing (see `docs/ROADMAP.md` v0.6 "Dependency direction" - the "determine
-whether my-dev-kit requires a static-side change" step concluded no).
-Runtime target identity is carried through this module verbatim; the module
-never adds a `sourceOwner`/`causedBy`-shaped field, preserving the
-architectural rule that runtime identity never silently becomes source
-ownership.
-
-This layer is a programmatic export/correlation boundary only: `src/index.ts`
-re-exports its full type/function surface, but there is no new CLI command,
-no `src/artifacts/boundedAgentContext*` writer/reader, and no orchestrator or
-lab code in this repository - those remain separate sibling-repository
-responsibilities per the Milestone 6 ownership split in
-`docs/PROJECT_MILESTONES.md`.
-
-## v0.7-v0.10 reference-evidence architecture constraints
-
-The external visual-reference capability (v0.7) is released as package
-version `0.7.0` - see "v0.7 Prompt 1" through "v0.7 Prompt 8" below for the
-actual architecture, and `docs/CURRENT_STATE.md` for release state. It
-extends the existing v0.1-v0.6 evidence architecture rather than becoming a
-UI-only feature or a parallel visual-comparison stack. v0.8 (interactive
-viewer) is released as package version `0.8.0`. v0.9 (structured visual
-annotation) is released as package version `0.9.0` - see "v0.9 visual
-annotation architecture" below. v0.10 (full graphical human-LLM workflow) is
-implemented and documentation-reconciled but remains unreleased. The
-constraints below apply to both v0.9 and v0.10.
-
-The evidence domains remain distinct:
-
-```text
-runtime observation A ↔ runtime observation B
-→ existing before/after comparison
-
-approved baseline/per-change contract ↔ candidate runtime evidence
-→ existing canonical contract evaluation
-
-external visual reference ↔ candidate runtime evidence
-→ reference applicability + structured fidelity evaluation (v0.7,
-  released as `0.7.0` - see "v0.7 Prompt 4" and "v0.7 Prompt 6" below)
-```
-
-An external reference is not an `ObservationArtifact`, and a reference region
-is not a runtime target. The released v0.7 implementation preserves explicit
-identity and provenance for the reference image/version, reference regions,
-applicable viewport/theme/application state, authored requirements, tolerances,
-approval/supersession state, and reference-region/runtime-target bindings.
-Bindings are explicit and evaluate to `bound`, `ambiguous`, or `unavailable`;
-they never silently become source ownership.
-
-The non-UI reference model and structured reference-vs-candidate evaluation
-were established in v0.7 before v0.8. v0.8 may render side-by-side images,
-overlays, measurements, bindings, provenance, and fidelity results, but it must
-consume those existing engines and must not invent a second reference model or
-evaluation engine. v0.9 may author annotations against either runtime
-screenshots or external references, but both coordinate/identity domains remain
-explicit and feed the same canonical contract/change-scope semantics. v0.10
-combines both visual entry modes with the existing correction loop.
-
-Where a reference requirement is executable, it uses the existing v0.5
-requested/expected-dependent/protected/preserved semantics. Informational or
-unassessed reference evidence remains non-executable until explicitly selected.
-There is no reference-only PASS/FAIL taxonomy.
-
-The released reference evaluation reuses existing relationship/value
-conventions where they mean the same thing and adds distinct reference-owned
-units only where the image evidence requires them. v0.7 does not use pixel or
-image-region similarity as a success mechanism; a later bounded similarity
-feature may supplement structured evidence if separately designed, but it must
-not replace browser-authoritative runtime geometry, canonical contract
-evaluation, or explicit relationship evidence.
-
-Candidate rendering still uses the one existing Chromium observation engine.
-The observer remains non-mutating. `my-dev-kit` remains the static/source
-evidence owner, and the v0.6 correlation/bounded-context boundary remains the
-route for attaching relevant source evidence to reference-driven correction
-packets. Heavy reference image bytes are referenced rather than copied into
-every downstream context/evaluation record.
-
-Theme, application-state, viewport, and authenticated-state applicability are
-checked before reference fidelity is interpreted through the released v0.7
-compatibility path, which reuses v0.4 comparability conventions. If reference
-and candidate do not represent compatible intended states, the result is
-explicitly incompatible/incomparable rather than a fabricated visual difference
-set. v0.8, released as package version `0.8.0`, displays this result exactly
-as required rather than redefining the state model - see "v0.8 Batch 5"
-below.
-
-The constraints above were carried out by the actual v0.7 implementation
-described in "v0.7 Prompt 1" through "v0.7 Prompt 8" below: explicit
-identity/provenance, applicability/compatibility, region-to-target bindings,
-requested/expected-dependent/protected/preserved reuse, and the non-mutating
-Chromium/correlation boundaries all remain as constrained here. v0.8 (see
-"v0.8 Batch 1" through "v0.8 Batch 8" below) applied them unchanged, and so
-does the implemented v0.9 annotation layer. They continue to apply unchanged
-to the still-future v0.10 work.
-
-The exact public artifact names, schema versions, persistence layout, supported
-image formats, coordinate model, requirement/tolerance primitives, and fidelity
-behavior were frozen by the actual v0.7 implementation below, not by earlier
-planning language. Style/asset-similarity mechanisms remain future unless
-separately implemented.
-
-## v0.8 Batch 1 (Viewer runtime and PWA foundation) — implemented
-
-Batch 1 of the frozen `docs/plans/v0.8-implementation-plan.md` establishes
-only the viewer runtime/build shell — no evidence indexing, artifact reading,
-or evidence UI. It does not implement any of the v0.7-derived reference/
-fidelity/binding display constraints above; those remain future work for
-later v0.8 batches, which must consume this runtime boundary rather than
-redefine it.
-
-```text
-my-frontend-observer view [--root <evidence-root>]
-        |
-        v
-  thin CLI dispatch (src/cli.ts: parseViewArgs/runViewCommand)
-        |
-        v
-  viewer application seam (src/viewerServer/viewerService.ts: startViewer)
-        |
-        v
-  Node local server, loopback-only (src/viewerServer/httpServer.ts)
-        |
-        +---------------------+----------------------+
-        |                                             |
-        v                                             v
-  built viewer assets (dist/viewer)          GET /api/status
-  (React + TypeScript + Vite PWA)            (session/root identity only)
-```
-
-- **Node server boundary** (`src/viewerServer/`): binds only to `127.0.0.1`
-  on one fixed default port (`4319`, `src/viewerServer/port.ts`); serves only
-  the built viewer assets plus the one read-only status endpoint; resolves
-  every requested path against the built assets root and fails closed on any
-  path that would resolve outside it; accepts no write HTTP methods; performs
-  no artifact reading, browser observation, or mutation. `--root` is
-  validated operationally (exists, is a directory) and exposed only as an
-  opaque status string — it is never interpreted as Observer evidence in this
-  batch.
-- **Browser application** (`viewer/`): a React + TypeScript + Vite app, built
-  independently of `src/` via `viewer/tsconfig.json` and `viewer/vite.config.ts`,
-  output to `dist/viewer` inside the existing package `dist` allowlist (no
-  second npm package). Renders an honest foundation shell only — product
-  identity, live session status via `/api/status`, and placeholder
-  navigation/workspace/details regions — never fabricated evidence.
-- **PWA**: `vite-plugin-pwa` generates a web app manifest (`standalone`
-  display, stable `start_url`/`scope`, installability icons) and a service
-  worker that precaches only the built application shell. It declares no
-  `runtimeCaching` rules, so future evidence/media/API routes remain
-  network/server-backed rather than silently served as stale cached truth
-  when the local server is unavailable (enforced by
-  `tests/unit/viewerPwaBuild.test.ts`, which asserts on the actual built
-  `sw.js`, not a hand-written approximation). An install affordance appears
-  only when the browser actually fires `beforeinstallprompt`; its absence is
-  shown honestly, never as a disabled-looking fake control.
-- **CLI**: `view [--root <evidence-root>] [--port <n>] [--no-open]` remains a
-  thin dispatcher — it parses syntax, delegates once to `startViewer`, prints
-  the URL/root, and optionally best-effort opens the system browser (failure
-  there is never fatal to server startup). All v0.1-v0.7 commands are
-  unchanged.
-
-This batch introduces no second observer, relationship engine, comparison
-engine, contract engine, reference model, or bounded-context builder — there
-is nothing yet for the viewer to consume beyond its own runtime identity.
-
-## v0.8 Batch 2 (Evidence indexing, canonical readers, and lazy data boundary) — implemented
-
-Batch 2 adds the safe, read-only data boundary between existing on-disk
-Observer evidence and the Batch 1 viewer runtime, entirely under
-`src/viewerServer/evidence/`. It introduces no new persisted artifact family,
-no schema migration, and no second validator — every recognized candidate is
-decided exclusively by the existing canonical reader/validator for its
-family (`src/artifacts/*Reader.ts`).
-
-```text
-GET /api/index                     bounded discovery + classification -> metadata only
-GET /api/artifacts/<handle>        one canonical-reader read, on demand -> full projection
-GET /api/media/<handle>/<role>     one resolved, contained media file, streamed on demand
-```
-
-- **Discovery** (`evidence/discovery.ts`): a bounded, deterministic walk
-  beneath `--root` that opens only files literally named `manifest.json` (the
-  one filename every current persisted family uses) — no other file is ever
-  read or classified, so arbitrary files can never become evidence merely by
-  existing under the root. Directory entries that are symlinks/junctions are
-  never followed. Bounds (`evidence/limits.ts`): traversal depth 6,
-  directories visited 2000, candidate manifests 1000, index records 500,
-  manifest read size 2,000,000 bytes — chosen after inspecting that every
-  current writer produces a shallow `<outputLocation>/<id>/manifest.json`
-  shape (see `docs/CONTRACTS.md`), not a deep tree.
-- **Classification is not validation** (`evidence/classify.ts`): peeks only
-  `artifactKind`/`schemaVersion` (plus, where the shared kind is ambiguous,
-  tries each existing reader/validator in turn — e.g. baseline vs. per-change
-  contract) to decide *which* existing canonical reader to call; the reader's
-  own structural validator remains the sole authority. Six honest, mutually
-  exclusive states: `supported`, `unsupported-version`, `invalid-structure`,
-  `unrecognized-kind`, `malformed-json`, `unreadable` — never collapsed into
-  one boolean, and never conflated with an artifact's own `completion`
-  state (passed through separately, only for the families that carry one:
-  observation and external-reference). A manifest declaring the
-  `bounded-agent-context` kind is classified `unrecognized-kind`: v0.6/v0.7
-  never added a disk writer/reader for that family (confirmed via direct
-  source inspection and `@dailephd/my-dev-kit` search), so Batch 2 does not
-  invent persistence-shaped handling for it.
-- **Viewer handles** (`evidence/handles.ts`, `evidence/pathSafety.ts`): a
-  handle is a family-prefixed, percent-encoded, root-relative directory path
-  — never a raw filesystem path accepted from the browser. Every route that
-  accepts a handle re-decodes and re-resolves it against the evidence root,
-  re-checks containment, and re-classifies that one candidate before serving
-  anything; a handle whose backing directory or manifest no longer matches
-  what was indexed fails closed as unknown, never stale.
-- **Ephemeral projection** (`evidence/projection.ts`): `EvidenceMetadataRecord`
-  (bounded, `/api/index`-shaped: handle, family, support state, logical id,
-  schema version, completion where applicable, media availability summary,
-  a handful of related ids) and `EvidenceArtifactDetail` (the already-
-  validated domain object, wrapped with `handle`/`family` — no new evidence
-  schema, no recomputation, no persistence).
-- **Media resolution** (`evidence/mediaResolver.ts`): `screenshot` (observation),
-  `image` (imported external reference), and `source-image` (approved
-  external reference) are the only three recognized roles. An approved
-  reference's image is never assumed to live in the approved artifact's own
-  directory — its `sourceReference.referenceId` is looked up against the
-  current index to find the actual owning imported artifact
-  (`evidence/index.ts#findImportedReferenceDir`), exactly matching the v0.7
-  reference-ownership contract in `docs/CONTRACTS.md`. A genuinely missing
-  screenshot/image/source artifact is reported as 404, never fabricated.
-- **PWA cache boundary preserved, not re-verified from scratch**: every new
-  route lives under `/api/`, already covered by Batch 1's
-  `denylist:[/^\/api\//]` navigation-fallback rule — no new `runtimeCaching`
-  entry was needed or added (`tests/unit/viewerPwaBuild.test.ts` asserts this
-  against the real built `sw.js`).
-- **Minimal UI** (`viewer/src/hooks/useEvidenceIndex.ts`,
-  `useArtifactDetail.ts`, `components/EvidenceList.tsx`,
-  `ArtifactPreview.tsx`): a bounded evidence list (metadata-first) plus
-  on-demand full-artifact loading on selection, with every support state
-  shown honestly. No screenshot rendering, SVG overlay, or comparison/
-  contract/reference visualization exists yet — that begins in Batch 3.
-
-## v0.8 Batch 3 (Runtime observation inspection and SVG overlays) — implemented
-
-Batch 3 makes one already-supported `ObservationArtifact` (Batch 2's data
-boundary, unchanged) genuinely understandable: a real screenshot, SVG target
-overlays in the observation's own canonical coordinate domain, target
-selection/inspection, and canonical layout-relationship display. No second
-relationship engine, no client-side evidence derivation, no new persisted
-artifact.
-
-**Coordinate audit (the load-bearing decision for this batch)**: target
-geometry (`TargetGeometry.x/y/width/height`) is captured via
-`el.getBoundingClientRect()` (`src/browser/evidenceCapture.ts`) - CSS pixels,
-relative to the current viewport's top-left, at the same live page state the
-screenshot is taken from. The screenshot itself is `page.screenshot({type:
-'png'})` (`src/browser/chromiumAdapter.ts`), Playwright's default
-(non-fullPage) mode, against a browser context created with no
-`deviceScaleFactor` override (`browser.newContext({viewport})`) - so it
-defaults to `1`, meaning every observation this repository can currently
-produce has a screenshot whose raw PNG pixel dimensions equal
-`requestConfig.viewport.width × requestConfig.viewport.height` exactly (1
-CSS pixel = 1 PNG pixel). `requestConfig.viewport` (a required, strongly-typed
-field on every valid `ObservationArtifact`, distinct from the loosely-typed
-`pageEvidence` bag) is therefore the canonical, always-present source for the
-SVG display frame.
-
-**SVG coordinate model** (`viewer/src/components/TargetOverlaySvg.tsx`): the
-`<svg>` root's `viewBox` is `0 0 {requestConfig.viewport.width}
-{requestConfig.viewport.height}` - the exact frame `getBoundingClientRect()`
-already used. The screenshot loads into a `<image>` element filling that same
-viewBox (`preserveAspectRatio="none"`, since the two frames are already
-pixel-identical). Target `<rect>` elements use `geometry.x/y/width/height`
-completely unchanged - no rounding, no `devicePixelRatio` multiplication, no
-clamping; geometry lying partly outside the viewBox is drawn at its real
-coordinates and clipped only by the SVG root's default `overflow: hidden`
-(a display-only effect, verified never to touch the underlying evidence
-value - `tests/unit/observationCoordinateMapping.test.ts`). This is robust
-even if a future capture path used a different `deviceScaleFactor`: the
-`<image>`/viewBox scaling is presentation-only browser behavior, never a
-manual pixel calculation in this codebase. `devicePixelRatio` (captured as
-`pageEvidence.devicePixelRatio`) is shown as informational observation-level
-evidence only and is never consulted for any geometry calculation.
-
-**Server additions** (`src/viewerServer/evidence/observationView.ts`, one new
-route `GET /api/observations/<handle>/relationships`): the only new
-server-side computation this batch adds is one thin, defense-in-depth-wrapped
-call to the existing canonical, pure `deriveLayoutRelationships` (`src/domain/
-relationships.ts`) - never a second relationship predicate implementation.
-Mirrors the exact handle-decode → contained-dir-resolve → re-classify
-discipline `loadArtifactByHandle`/`resolveMedia` already established in
-Batch 2; a handle for a non-`observation` family or a non-`supported`
-candidate is rejected (`409`) before derivation is even attempted. The
-existing `GET /api/artifacts/<handle>` (full `ObservationArtifact`) and
-`GET /api/media/<handle>/screenshot` (Batch 2, unchanged) remain the only
-other data sources the observation workspace uses - no new artifact
-projection endpoint was needed, since the full validated domain object
-already contains everything the target/observation inspector displays.
-
-**Client-side presentation only** (`viewer/src/observation/targetOrder.ts`,
-`viewer/src/components/{ObservationWorkspace,TargetList,TargetOverlaySvg,
-ObservationInspector,EvidenceFieldView}.tsx`): React selects, orders
-(by the observation's own authored `requestConfig.targets` order, not
-incidental object-key order), and formats already-fetched canonical fields.
-It never resolves targets, computes relationships, or derives
-visibility/overflow/scroll-owner semantics - `deriveLayoutRelationships`
-runs exclusively on the server (above). An unresolved target (`not-found`/
-`ambiguous`/`unavailable`) is selectable from the target list and shown
-honestly in the inspector, but never receives a fabricated `<rect>` -
-`orderedTargets()`'s `hasGeometry` flag is `true` only when
-`geometry.state` is `'available'` or `'partial'`.
-
-**Selection**: viewer presentation state only (React `useState`, reset on
-observation change), never persisted, synchronized in both directions
-between the target list, the SVG `<rect>` (`role="button"`, keyboard-
-operable), and the inspector via the target's existing stable `name`.
-
-**Overlay toggles**: geometry, labels (disabled when geometry is off), and
-relationships - each independently toggleable and purely presentational
-(hiding/showing already-rendered elements), never altering the underlying
-evidence or the fetched artifact/graph.
-
-**PWA cache boundary preserved**: the new `/api/observations/*` route lives
-under the same `/api/` prefix Batch 1's `navigateFallbackDenylist` already
-denylists - no service-worker configuration change was needed
-(`tests/unit/viewerPwaBuild.test.ts` asserts this against the real built
-`sw.js`).
-
-## v0.8 Batch 4 (Before/after comparison and contract/change-scope inspection) — implemented
-
-Batch 4 exposes the existing v0.4 `ComparisonArtifact` and v0.5
-`FrontendContractEvaluationArtifact` through the viewer, entirely under
-`src/viewerServer/evidence/{linkedEvidence,comparisonView,evaluationView}.ts`
-and `viewer/src/components/{ComparisonWorkspace,EvaluationWorkspace,
-ComparisonObservationPane,ClauseResultRow}.tsx`. **`compareObservations` and
-`evaluateFrontendContract` are never called anywhere in this batch** - every
-displayed comparison/evaluation field is read unchanged from its persisted
-artifact via the existing Batch 2 `GET /api/artifacts/<handle>`.
-
-- **Exact linked-evidence resolution** (`evidence/linkedEvidence.ts`): given
-  a `ComparisonSourceObservationReference`/`FrontendContractObservationReference`,
-  a `comparisonId`+`comparisonRequestId` pair, or a `baselineId`/`contractId`,
-  resolves the matching indexed artifact by **exact identity only**
-  (`observationId`+`requestId`+`producer.version`+`observationSchemaVersion`
-  for observations; the id fields themselves for comparisons/contracts) -
-  never by folder name, screenshot filename, URL, target-set, or geometry
-  similarity. Zero matches → `missing`; two or more exact matches →
-  `ambiguous` (never silently picks one). Mirrors the exact bounded-walk
-  pattern Batch 2's `findImportedReferenceDir` already established.
-- **Two additive, read-only routes**: `GET /api/comparisons/<handle>/view`
-  (resolves the comparison's `before`/`after`) and
-  `GET /api/evaluations/<handle>/view` (resolves `comparison`, `baseline`,
-  `change`, `before`, `after`) - both under `/api/`, both GET/HEAD-only, both
-  returning only resolved-handle-or-missing-or-ambiguous status, never a
-  duplicated copy of the linked artifact's own payload (the browser fetches
-  that separately through the existing `GET /api/artifacts/<handle>`, reusing
-  Batch 2's on-demand-loading contract exactly).
-- **Before/after visual reuse, not reimplementation**: `ComparisonObservationPane.tsx`
-  is built entirely from Batch 3's existing lower-level primitives
-  (`useArtifactDetail`, `orderedTargets`, `TargetOverlaySvg`) - no second
-  screenshot-loading, coordinate-transform, or geometry-rendering code
-  exists. The comparison's own persisted `relationshipsBefore`/
-  `relationshipsAfter` are passed directly into `TargetOverlaySvg`'s existing
-  `relationships` prop - never recomputed via `deriveLayoutRelationships`.
-  `TargetOverlaySvg` gained one small additive, optional `highlightNames`
-  prop (alongside the existing single-select `selected`) so a
-  relationship-subject difference or a two-target contract primitive
-  (`targets-do-not-overlap`, `target-fits-inside`, etc.) can emphasize both
-  named targets at once without changing Batch 3's existing single-select
-  interaction contract.
-- **Difference/relationship-change/clause presentation is evidence display,
-  not re-derivation**: `ComparisonWorkspace.tsx` renders `differences`,
-  `relationshipChanges`, `configurationChanges` (kept visually distinct from
-  appeared/disappeared runtime differences), and `expectedDependencyEvidence`
-  exactly as persisted, labeling dependency outcomes as explicit non-causal
-  evidence. `comparability` (comparable/comparable-with-warnings/incomparable
-  plus blocking/warning/unassessed reasons) is shown honestly; an
-  `incomparable` result is visually unmistakable
-  (`.comparability-banner--incomparable`).
-- **Clause joining by exact `clauseId` only** (`EvaluationWorkspace.tsx`):
-  baseline clauses (from the linked `PersistentBaselineContract`) and
-  per-change clauses (from the linked `PerChangeContract`) are joined to the
-  evaluation's `clauseResults` by exact id - never by target/primitive-shape/
-  category/position. A `clauseId` absent from both loaded contracts is shown
-  as an honest "unresolved clause definition", never fabricated. Baseline
-  clause active/superseded status comes exclusively from the evaluation
-  artifact's own `activeBaselineClauseIds`/`supersededBaselineClauseIds` -
-  never recomputed from clause overlap. `pass`/`fail`/`unavailable`/
-  `conflict` are preserved exactly (never collapsed to a boolean);
-  `unavailable` shows its reason, `conflict` shows its reason and
-  `conflictingClauseIds`.
-- **Overall verdict is authoritative and unmistakable**: `overallVerdict`
-  (`PASS`/`FAIL`) is rendered directly from the artifact, in a large
-  `.overall-verdict--PASS`/`.overall-verdict--FAIL` banner - the UI never
-  computes it from visible rows. The required safety case (a `requested`
-  clause `pass` alongside a `protected`/`preserved` clause `fail` still
-  producing overall `FAIL`) and the all-pass case are both proven against
-  real, canonically-evaluated fixtures (`tests/support/evidenceFixtures.ts#writeFullPipelineFixture`/
-  `writeAllPassPipelineFixture`) in real Chromium
-  (`tests/browser/comparisonEvaluationWorkspace.test.ts`) - `overallVerdict`
-  is never hand-edited to construct either demonstration.
-- **Target/relationship cross-highlighting uses only explicit canonical
-  identity**: `primitiveTargetNames()` (`viewer/src/contract/clauseTargets.ts`)
-  extracts a contract primitive's named target field(s) (`target`, `targetA`/
-  `targetB`, `target`+`container`, `subjectTarget`/`relatedTarget`) by an
-  exhaustive switch over `ContractPrimitiveKind` - page-level primitives
-  (`document-width-fits-viewport`, `scroll-owner-is-document`) return no
-  names, so clicking them never fabricates a target highlight.
-- **PWA cache boundary preserved**: both new routes live under `/api/`,
-  already covered by Batch 1's `navigateFallbackDenylist`; verified against
-  the real built `sw.js`.
-
-## v0.8 Batch 5 (External reference and reference/candidate inspection) — implemented
-
-- **Reference indexing/media already existed (Batch 2), unchanged**: the
-  `external-reference-imported`/`external-reference-approved` families,
-  `GET /api/media/<handle>/image` (imported), and
-  `GET /api/media/<handle>/source-image` (approved, resolved through
-  `findImportedReferenceDir`'s exact `referenceId` walk) were already built
-  in Batch 2 and required no change here - Batch 5 only adds the visual
-  workspace consuming them.
-- **Two new additive, read-only routes**
-  (`src/viewerServer/evidence/referenceView.ts`):
-  `GET /api/references/<handle>/view` derives the selected reference's own
-  region-relationship graph (`deriveReferenceRegionRelationships`) and
-  requirement adequacy (`deriveReferenceRequirementAdequacy`) - both pure
-  functions over the artifact's own persisted `regions`/`requirements`,
-  never persisted, never a second derivation engine (mirrors Batch 3's
-  `getObservationRelationships` server-side-derivation pattern).
-  `GET /api/references/<handle>/candidate/<handle>/view` evaluates
-  reference/candidate compatibility through the existing canonical
-  `evaluateReferenceCandidateCompatibility` (never a second, viewer-owned
-  compatibility model) and separately lists every existing
-  `FrontendContractEvaluationArtifact` whose own persisted `after` reference
-  exactly identifies the candidate, for explicit, never-auto-selected
-  optional display.
-- **Reference-image SVG coordinate model is a genuinely distinct domain from
-  the candidate's runtime SVG** (`ReferenceRegionOverlaySvg.tsx`): `viewBox`
-  is the reference image's own pixel dimensions (never the candidate's CSS
-  viewport, never devicePixelRatio-multiplied); each region's canonical
-  `{x, y, width, height}` is rendered unchanged. Because this is a different
-  coordinate domain and data source from `TargetOverlaySvg` (runtime CSS
-  pixels, `TargetGeometry`), it is a separate, sibling component rather than
-  a parameterization of the existing one - reuse would have silently
-  conflated the two domains. The candidate side, in contrast, reuses Batch
-  3/4's exact `ComparisonObservationPane`/`TargetOverlaySvg` machinery
-  unchanged (a synthetic `{status:'resolved', handle}` `LinkStatus` is
-  constructed once a candidate is explicitly chosen).
-- **Reference region selection and runtime target selection are two
-  independent, never-synchronized selection domains**
-  (`ReferenceWorkspace.tsx`): selecting a reference region never selects or
-  highlights a runtime target, even when both happen to share the same
-  string name (proven with a real Chromium fixture deliberately naming both
-  `"header"` - `tests/browser/referenceCandidateWorkspace.test.ts`, Case E).
-  No binding connector/highlight-across-panes exists in this batch - that is
-  Batch 6's explicit-binding-interaction scope.
-- **Compatibility vs. reference adequacy vs. candidate fidelity are kept
-  strictly distinct, never conflated**: compatibility
-  (`comparable`/`comparable-with-warnings`/`incomparable` plus
-  blocking/warning/unassessed reasons) comes only from
-  `evaluateReferenceCandidateCompatibility`; reference-side requirement
-  adequacy (`adequate`/`partial`/`inadequate`) comes only from
-  `deriveReferenceRequirementAdequacy`; candidate fidelity is never computed
-  in this batch at all - the UI always shows an explicit "not evaluated in
-  this batch" note rather than ever implying a fidelity PASS from a
-  compatibility PASS or an adequate reference (task §32/§33 boundary,
-  `evaluateReferenceCandidateFidelity` is never imported/called anywhere in
-  Batch 5).
-- **Optional contract/evaluation context is opt-in, never inferred**
-  (`ReferenceWorkspace.tsx`): when the reference/candidate view lists more
-  than one exactly-matching evaluation artifact, the developer must
-  explicitly pick one from a `<select>` - the newest/first match is never
-  silently chosen, and with zero selected the candidate's contract status
-  reads "not selected/not available", never a fabricated PASS.
-- **Imported vs. approved image ownership preserved exactly as Batch 2 built
-  it**: an imported reference's image is fetched from its own directory; an
-  approved reference's image is fetched from its exact imported source via
-  `sourceReference.referenceId`, never assumed co-located, never
-  duplicated - proven with a real Chromium fixture asserting the two
-  `<image href>` values resolve to the `image`/`source-image` roles
-  respectively (Cases A/B).
-- **PWA cache boundary preserved**: both new routes live under `/api/`,
-  already covered by Batch 1's `navigateFallbackDenylist`; verified against
-  the real built `sw.js` (no new `registerRoute`, no `/api/references`
-  precache entry).
-
-## v0.8 Batch 6 (Explicit-binding interaction, zoom/pan, conditional lock, and on-demand reference fidelity) — implemented
-
-- **`view --bindings-file <json-file>`**: reuses the exact same operational
-  binding-file wrapper parser (`loadBindingsFile` in `src/cli.ts`) that
-  `evaluate-reference-fidelity --bindings-file` already used - one shared
-  parser, never a second divergent one. The file is read once at startup;
-  its declarations become `ViewerServerState.bindingDeclarations` (an opaque
-  `unknown[]` until validated against a specific reference); the file path
-  itself is never persisted, returned, or exposed to the browser. Reference-
-  specific declaration validity (region existence, shape) is deferred to the
-  moment a reference is actually selected server-side, via the existing
-  canonical `isValidReferenceRuntimeBindingDeclarations` - never checked at
-  startup without a reference.
-- **Two new additive, read-only routes**
-  (`src/viewerServer/evidence/referenceView.ts`):
-  `GET /api/references/<handle>/candidate/<handle>/bindings` validates the
-  session's declarations against the selected reference and calls the
-  existing canonical `evaluateReferenceRuntimeBindings` exactly once.
-  `GET /api/references/<handle>/candidate/<handle>/fidelity` is the explicit
-  on-demand fidelity trigger - calls the existing canonical
-  `evaluateReferenceCandidateFidelity` exactly once, using the exact same
-  session declarations, so its embedded `bindings` field and the `/bindings`
-  route's own result always structurally agree for identical inputs (same
-  pure function, same arguments). Neither route persists anything; both are
-  `GET` (idempotent, deterministic, ephemeral over already-selected explicit
-  input) - no mutation route was added.
-- **`deriveCoordinateScale` exported additively** from
-  `externalReferenceFidelity.ts` (previously module-private) - Batch 6's
-  view-lock eligibility reuses this exact function unchanged (same formula,
-  same `ASPECT_RATIO_MAPPING_TOLERANCE`, same no-applicable-viewport
-  failure) rather than a second aspect-ratio/scale implementation. The
-  existing `GET /api/references/<handle>/candidate/<handle>/view` route now
-  additionally returns `coordinateMapping: DeriveCoordinateScaleResult` -
-  purely a function of the reference, independent of the candidate.
-- **Explicit-binding cross-selection uses only canonical
-  `ReferenceRuntimeBindingResult.referenceRegion`/`.runtimeTarget` fields**
-  (`ReferenceWorkspace.tsx`): selecting a `bound` reference region
-  highlights (via `TargetOverlaySvg`'s existing Batch 4 `highlightNames`
-  prop - never the primary `selected`/`aria-pressed` target) its exact
-  declared runtime target; selecting a runtime target highlights every
-  region whose `bound` result names it (many-to-one, via a new additive
-  `highlightRegionIds` prop on `ReferenceRegionOverlaySvg`, matching
-  `TargetOverlaySvg`'s established highlight pattern). `ambiguous`/
-  `unavailable` results never cross-select. Proven with a real equal-name
-  ("header" region + "header" target) Chromium fixture: no cross-selection
-  without an explicit declaration, real cross-selection with one.
-- **Zoom/pan is a repository-owned, presentation-only hook**
-  (`viewer/src/hooks/useZoomPan.ts`): bounded `[1x, 8x]` scale, `×1.25`/
-  `÷1.25` step, expressed as one `{scale, focalX, focalY}` triple in the
-  pane's own source-coordinate frame (reference-image pixels or candidate
-  CSS pixels - never rewritten). Renders via an SVG `viewBox` override
-  (additive `viewBoxOverride`/`svgRef`/pointer-handler props on
-  `TargetOverlaySvg`/`ReferenceRegionOverlaySvg`, defaulting to Batch 3/5's
-  exact prior behavior when omitted) - image and overlay stay one
-  transformed unit automatically since both live inside the same `<svg>`
-  root, and native SVG hit-testing means selection keeps working correctly
-  under zoom/pan with no extra coordinate math. Panning uses the SVG
-  element's own `getScreenCTM()` to convert screen-space pointer deltas into
-  source-space deltas - reuses the browser's native transform rather than a
-  custom aspect-ratio-aware pixel calculation - and only engages (calling
-  `setPointerCapture`) once the pointer has moved past a small threshold, so
-  an ordinary click on a region/target rect is never hijacked into a
-  phantom drag. Fit and Reset are the same fitted-1x/centered default (task
-  §26 - no second presentation-only default was introduced).
-- **View lock reuses one single shared state, never two independently
-  synchronized states**: `ReferenceWorkspace.tsx` owns `refZoom`/`candZoom`
-  directly (always-controlled `useZoomPan` calls) and each pane's zoom/pan
-  action handler updates both states in one synchronous call when locked -
-  no reactive effect watches one pane's state to update the other, so no
-  feedback-loop risk exists. Lock is available only when a candidate is
-  selected, compatibility is not `incomparable`, and `coordinateMapping.ok`
-  is `true`; any change to that eligibility (including selecting a
-  different reference/candidate) immediately disables lock and shows an
-  actionable reason. Synchronization converts a candidate CSS-pixel focal
-  point/scale into reference-image-pixel space (and back) using only
-  `coordinateMapping.scale.scaleX`/`scaleY` - the exact same canonical
-  factor `deriveCoordinateScale` already produces, applied as a straight
-  multiply/divide (its own algebraic inverse), never a second mapping rule.
-- **Contract/fidelity independence is never collapsed into one status**:
-  the existing Batch 5 "Optional contract/evaluation context" section
-  (unchanged) and the new on-demand `ReferenceFidelityPanel` are two
-  separate sections rendering two separate canonical results
-  (`FrontendContractEvaluationArtifact.overallVerdict` and
-  `ReferenceCandidateFidelityEvaluation.state`) side by side; when both are
-  present, an explicit note states that fidelity does not override an
-  active contract failure. No new coordinator/aggregate verdict is computed
-  anywhere in this batch.
-- **PWA cache boundary preserved**: both new routes live under `/api/`,
-  already covered by Batch 1's `navigateFallbackDenylist`.
-
-## v0.8 Batch 7 (Bounded agent context, correlation, provenance, and raw evidence navigation) — implemented
-
-- **Bounded agent context remains programmatic-only**: no filesystem writer
-  was added for `BoundedAgentContextArtifact` (it is still not an
-  Observer-evidence-root artifact family - `src/viewerServer/evidence/classify.ts`'s
-  "known but unreadered kind" comment is unchanged). `view --context-file
-  <json-file>` reads exactly one already-serialized
-  `BoundedAgentContextArtifact` value directly (no wrapper object) as
-  explicit, session-only viewer input - read once at startup
-  (`src/cli.ts#loadContextFile`, mirroring `loadBindingsFile`'s exact
-  read/size-bound/parse shape), classified by
-  `src/viewerServer/context.ts#classifyContextFileContent` (reuses the
-  existing canonical `isValidBoundedAgentContextArtifact` - never a second
-  validator), and held only in `ViewerServerState.context` for the life of
-  the process. The file's size is bounded by the existing Batch 2
-  `MAX_MANIFEST_CANDIDATE_BYTES` (2,000,000 bytes) rather than a second
-  bound, since a context artifact's own frozen numeric caps already make it
-  far smaller in any realistic case.
-- **Three honest session states, never coerced into one another**: `'none'`
-  (no `--context-file`; every Batch 1-6 feature stays fully available),
-  `'unsupported-version'` (recognized `artifactKind`, a `schemaVersion`
-  other than the current one - the viewer still starts, showing this
-  state explicitly rather than either failing or misinterpreting the
-  fields), and `'valid'` (structurally validated current-schema context).
-  Every other problem (unreadable file, wrong `artifactKind`, a
-  structurally invalid *current*-schema artifact) fails viewer startup
-  clearly - an explicitly supplied file is never silently ignored.
-- **`GET /api/context`** (`httpServer.ts`) returns the session's exact
-  classified state; for `'valid'`, it additionally returns
-  `sourceResolution` - the result of resolving
-  `artifact.sources` against the current evidence root by **exact
-  canonical identity only**
-  (`src/viewerServer/evidence/contextSourceView.ts`, reusing/extending
-  Batch 4's `linkedEvidence.ts` resolver pattern with three additive
-  functions: `resolveObservationById` (bare `observationId`, the only
-  identity a context source reference actually carries),
-  `resolveEvaluationByIdentity`, and `resolveReferenceByIdentity`). Zero
-  matches → `missing`; two or more → `ambiguous` (never silently picks
-  one) - the same discipline every other Batch 4/5 resolver already
-  established.
-- **Raw structured evidence reuses the existing Batch 2 artifact-detail
-  route unchanged**: `RawEvidenceViewer.tsx` calls the existing
-  `useArtifactDetail`/`GET /api/artifacts/<handle>` for any exactly-resolved
-  source - no second full-artifact retrieval mechanism, no local filesystem
-  read, no arbitrary path accepted from the browser.
-  `EvidenceReference.path` values are always displayed as plain provenance
-  text, never passed to `fs.readFile`/`path.resolve`/a static file server.
-- **Bounded runtime targets, adequacy, omissions, truncations, and
-  correlation are rendered exactly as the validated artifact states them** -
-  never recomputed, never boolean-collapsed
-  (`ContextWorkspace.tsx`): `Adequacy.state`
-  (`adequate`/`partial`/`inadequate`) and reasons are shown verbatim;
-  absent bounded-target fields render "not included in this bounded
-  context", never a fabricated falsy/zero value; `required: true`
-  omissions/truncations render in a visually distinct
-  `.context-required-loss` block, separate from optional ones;
-  `correlations` absent renders "Static correlation not included in this
-  context" - never "unavailable" (that status is reserved for a real
-  per-target `RuntimeStaticCorrelationRecord` with zero candidates).
-  `correlated`/`ambiguous`/`unavailable` are preserved exactly; a
-  `correlated` record's one candidate is labeled "Correlated candidate", an
-  `ambiguous` record shows **every** supplied candidate with none visually
-  promoted, and `unavailable` fabricates zero candidates - matching the
-  frozen `CORRELATION_STATUSES` invariants
-  (`domain/boundedAgentContext.ts`) the validator itself already enforces.
-  All new UI text was audited against ownership/edit-authorization language
-  (no "owner"/"source owner"/"owned by") - correlation is presented as
-  evidence, never as edit authorization.
-- **Context-target ↔ runtime-target interaction never infers source
-  ownership**: selecting a bounded target or a correlation record uses only
-  exact `targetId`/`runtimeTargetId` string matching; for each *exactly
-  resolved* source observation, `SourceObservationTargetCheck` checks
-  membership in that observation's own already-fetched `targetEvidence`
-  (a plain lookup over already-loaded JSON, never a new derivation) and, if
-  more than one resolved source observation contains the same target id,
-  lists all of them rather than picking one.
-- **Bounded reference-fidelity projection is never recomputed, and is kept
-  visibly distinct from a live on-demand evaluation**: absent `fidelity`
-  renders "Reference fidelity not included in this bounded context" - never
-  implied as passing. When present, `mismatches` and `protectedContext` are
-  rendered in separate sections from the artifact's own fields exactly as
-  supplied; a `state: 'not-evaluated'` blocked projection always shows
-  `blockedBy` prominently and never renders an empty mismatch list as "no
-  problems". When the context's `referenceId`/`candidateObservationId`
-  exactly resolve within the current evidence root, `ContextWorkspace.tsx`
-  embeds the existing, unchanged Batch 6 `ReferenceFidelityPanel` (the same
-  on-demand `evaluateReferenceCandidateFidelity` trigger) directly beneath
-  the bounded projection, labeled "Bounded context fidelity projection"
-  above and "Current on-demand fidelity evaluation" below - two separate,
-  clearly labeled evidence instances, never silently merged or replaced.
-- **No runtime rebuild of context or correlation, and no my-dev-kit
-  execution from the shipped viewer**: grep-verified - `projectBoundedAgentContext(`,
-  `deriveRuntimeStaticCorrelations(`, and `attachRuntimeStaticCorrelations(`
-  appear nowhere under `src/viewerServer/` or `viewer/src/` (only in test/
-  fixture-generation code, per the frozen plan's explicit test-fixture
-  exception); no `child_process`/`npx @dailephd/my-dev-kit` invocation
-  exists in the viewer server or browser bundle.
-- **PWA cache boundary preserved**: `GET /api/context` lives under `/api/`,
-  already covered by Batch 1's `navigateFallbackDenylist`.
-
-## v0.8 Batch 8 (Integrated viewer acceptance, PWA hardening, and packaged proof) — implemented
-
-Batch 8 is the final v0.8 implementation batch. It is integration/hardening,
-not a new architecture layer: no new API route, no new CLI flag, and no new
-canonical-engine call site were added. See
-`docs/reports/v0.8-integrated-viewer-acceptance-batch8.md` for the full
-record.
-
-- **Closed three named real-browser coverage gaps**, each proved against the
-  actual built viewer through the actual loopback server, never a hand-edited
-  fixture verdict: many reference regions bound to one runtime target all
-  cross-highlight together (the pre-existing target→regions loop in
-  `ReferenceWorkspace.tsx` already iterated every matching binding - the gap
-  was in real-browser proof, not in the derivation); reference-fidelity
-  `fail` alongside a genuine frontend-contract `PASS` for the same candidate
-  display independently (the pre-existing independence note in
-  `ReferenceWorkspace.tsx` was already verdict-agnostic); a bounded context
-  whose sources include two observations sharing a stable target id lists
-  every matching source observation (the pre-existing
-  `SourceObservationTargetCheck` in `ContextWorkspace.tsx` already checked
-  membership per source independently, never picking one).
-- **One real accessibility defect found and fixed**: a cross-highlighted,
-  non-selected region/target `<rect>` (`TargetOverlaySvg.tsx`,
-  `ReferenceRegionOverlaySvg.tsx`) exposed no accessible state distinguishing
-  it from a plain unselected rect - `aria-pressed` correctly stayed `false`
-  (it is not the primary single-selection), but nothing else communicated
-  the highlight to assistive technology. Fixed by adding
-  `data-highlighted="true"` and an `aria-label` suffix
-  (`" (highlighted: related to current selection)"`) when highlighted and
-  not selected, leaving `aria-pressed` semantics untouched.
-- **First live-browser PWA proof suite** (`tests/browser/pwaHardening.test.ts`):
-  real service-worker registration and activation against the built shell;
-  the manifest fetched and confirmed `display: "standalone"`; zero Cache
-  Storage entries under any `/api/` pathname after normal use, confirming
-  the `navigateFallbackDenylist` boundary holds live, not just in the built
-  `sw.js` regex; and the hard server-down gate - after the server is closed
-  and the same page reloaded, the app shell still renders from the precache,
-  but the evidence-dependent surface shows the explicit
-  `.evidence-list__error` "Evidence index unavailable" state, with the
-  previously-visible evidence asserted absent. Install-control is proven
-  only via synthetic `beforeinstallprompt` dispatch (a genuine browser
-  install prompt was not observed under automation). Standalone-mode CDP
-  display-mode emulation was attempted but not observed to take effect -
-  recorded honestly, never overstated as actual OS-level installation proof.
-- **Packaged-candidate proof**: `npm pack` → clean consumer install (outside
-  the repository) → the actually-installed CLI executable (not repo
-  `dist/cli.js`) → the installed `view` server → real Chromium against the
-  packaged/installed server, not a source-checkout dev server. Read-only
-  evidence-hash proof (SHA-256 of every file in the exercised evidence root,
-  taken before and after the packaged-browser session) confirmed no
-  mutation and no new viewer-created artifact anywhere in the evidence root.
-- **Re-confirmed the no-second-engine invariant** across all eight batches by
-  re-running the exact `grep -rn` audit from earlier batches - unchanged
-  findings, no duplicate evidence engine exists.
-
-## v0.9 visual annotation architecture (released in 0.9.0)
-
-v0.9 is released as package version `0.9.0`. It adds one new
-evidence family and a narrow local authoring path to the existing viewer. It
-adds no new evaluator, no second contract or reference model, and no new
-PASS/FAIL semantics.
-
-**Evidence ownership**:
-
-- `src/domain/visualAnnotation.ts` owns `VisualAnnotationArtifact` (artifact
-  kind `my-frontend-observer/visual-annotation`, schema `1.0.0`): the source
-  union, structured marks, explicit associations, candidate/confirmed
-  interpretation, validation, and the pure overlay SVG renderer.
-- `src/domain/visualAnnotationIdentity.ts` owns deterministic request identity
-  and fresh instance identity.
-- `src/artifacts/visualAnnotationArtifactWriter.ts` and
-  `visualAnnotationArtifactReader.ts` own atomic persistence (temporary
-  `.tmp-<id>` directory, then rename) and canonical reading, including the
-  derived `annotation-overlay.svg` and its digest.
-- `src/application/visualAnnotationPersistenceService.ts` owns saving one
-  annotation or one superseding revision.
-
-**Coordinate domains**: runtime annotations use the observation's runtime CSS
-pixel space. Reference annotations use the reference image's own pixel space
-(for an approved reference, the owning imported image). The two domains are
-never mixed. Zoomed or panned drawing is mapped back through the SVG's own
-transform (`viewer/src/svg/sourceCoordinates.ts`).
-
-**Viewer discovery and media** (`src/viewerServer/evidence/`): the index
-classifies `visual-annotation` evidence and skips writer `.tmp-*`
-directories. `annotationView.ts` resolves an annotation's exact canonical
-source and reports `unavailable` instead of guessing a replacement. The media
-resolver serves the `annotation-overlay` role only after re-rendering the SVG
-from the artifact and verifying it, with a script-blocking sandbox policy.
-
-**Project-aware authoring security**: `src/viewerServer/authoringSecurity.ts`
-owns the in-memory 32-byte session capability and the Host, Origin, token,
-content-type, and content-encoding checks. `httpServer.ts` owns the shared
-bounded JSON gate and routes exactly three `POST` responsibilities.
-`view --root` never creates an authoring session, so the standalone
-arbitrary-root viewer stays read-only.
-
-1. `POST /api/annotations` (`src/viewerServer/annotationAuthoring.ts`) saves
-   a new annotation or a revision through the canonical persistence service,
-   with stale-parent conflict detection. This module also owns the single
-   per-session write queue used by all three routes.
-2. `POST /api/annotations/:handle/promote-contract`
-   (`src/viewerServer/annotationContractPromotion.ts`) calls
-   `src/application/visualAnnotationContractPromotionService.ts`. Selected
-   confirmed runtime intent becomes one canonical `PerChangeContract` through
-   the existing contract persistence service. Optional activation goes only
-   through `activateProjectChangeContract` in
-   `src/application/projectWorkflowService.ts`.
-3. `POST /api/annotations/:handle/materialize-reference`
-   (`src/viewerServer/annotationReferenceMaterialization.ts`) calls
-   `src/application/visualAnnotationReferenceMaterializationService.ts`.
-   Selected confirmed reference intent becomes a new imported
-   `ExternalReferenceArtifact` through the existing `importExternalReference`,
-   superseding the source. The image bytes come only from the safe media
-   resolver.
-
-Output locations come from `src/projectWorkflow/projectPaths.ts`
-(`annotations`, `contracts`, and `references` under
-`.frontend-observer/evidence`). The browser never supplies a path.
-
-**Viewer UI** (`viewer/src/`): `annotation/` holds pure presentation models
-(`annotationGeometry.ts`, `runtimeIntent.ts`, `referenceIntent.ts`,
-`confirmation.ts`). `components/AnnotationLayer.tsx`,
-`AnnotationToolbar.tsx`, `RuntimeAnnotationPanel.tsx`,
-`ReferenceAnnotationPanel.tsx`, `CandidateRegionPreviewLayer.tsx`, and
-`AnnotationPanelSections.tsx` render marks, tools, intent, promotion, and
-materialization. Hooks under `hooks/` hold draft, saved-list, session,
-pointer, promotion, and materialization state. The authoring token lives only
-in React memory.
-
-**Existing evaluators remain authoritative**: the canonical contract
-evaluator, reference relationship derivation, requirement adequacy, reference
-fidelity, and project `check` are unchanged. Annotation evidence feeds them
-only through promoted contracts and materialized references.
-
-## Retained v0.1 architecture constraints
-
-v0.1 planning preserved these approved boundaries without treating module
-names from the historical run as mandatory:
-
-```text
-thin command-line boundary
-        ↓
-reusable observation engine/application layer
-        ↓
-browser automation boundary
-        ↓
-observer-owned runtime evidence
-
-observer-owned domain/schema
-        ↓
-artifact ownership boundary
-
-deterministic fixture/test boundary
-        ↓
-browser-level validation
-```
-
-Use one browser engine implementation, keep browser logic out of presentation,
-avoid speculative plugin/multi-browser abstractions, and keep observed
-applications external. Versions before v0.6 did not add runtime coupling to
-sibling ecosystem projects. v0.6 adds only explicit bounded context and
-correlation/export contracts within this repository, preserving independent
-ownership; orchestrator-consumption and lab-compatibility work are separate
-sibling-repository deliverables, not part of this repository's architecture.
-
-The text/config-driven coding-agent workflow and the non-UI external-reference
-evidence foundation are operational as of v0.7. The viewer and annotation
-layers must consume the same canonical observation, relationship, comparison,
-contract, change-scope, reference, correlation, and context boundaries rather
-than creating parallel engines. The concrete implementation plan and module
-layout for each future version must be designed only after that version's
-planning workflow inspects the current repositories.
-
-v0.7 Prompt 1 implements only the bottom of that external-reference stack: a
-new, standalone `ExternalReferenceArtifact` evidence root
-(`src/domain/externalReference.ts`, `externalReferenceImage.ts`,
-`externalReferenceIdentity.ts`, `src/artifacts/externalReferenceArtifact{Writer,Reader}.ts`,
-`src/application/externalReferencePersistenceService.ts`) with its own
-identity, provenance, bounded image metadata, and a two-state
-(`imported`/`approved`) lifecycle - see `docs/CONTRACTS.md` "v0.7 Prompt 1
-external-reference artifact contract" for the exact shape. It follows the
-same identity/persistence/diagnostics/export conventions as every existing
-artifact family (deterministic canonicalize-then-sha256 request identity,
-nonce-based fresh instance identity, atomic temp-dir-then-rename persistence,
-the shared `DIAGNOSTIC_CODES` vocabulary) without reusing or duplicating the
-observation, comparison, or contract engines themselves - an external
-reference is desired-design evidence, never an `ObservationArtifact`, an
-approved baseline, or a runtime target.
-
-v0.7 Prompt 2 adds explicit reference regions and reusable reference-region
-relationships on top of that foundation (`domain/externalReferenceRegions.ts`,
-`externalReferenceRegionRelationships.ts`) - see `docs/CONTRACTS.md` "v0.7
-Prompt 2 explicit reference regions and relationships" for the exact shape.
-The relationship-derivation predicates are reused verbatim (now exported
-additively) from `domain/relationships.ts` rather than reimplemented, so
-reference-region geometry and runtime-target geometry can never diverge on
-the same underlying formula; only the geometry-only relationship families
-apply, since a static image exposes no DOM, scroll, or viewport evidence.
-v0.7 Prompt 3 adds selected design requirements, tolerance semantics, and
-reference-evidence adequacy on top of that region model
-(`domain/externalReferenceRequirements.ts`,
-`externalReferenceRequirementIdentity.ts`) - see `docs/CONTRACTS.md` "v0.7
-Prompt 3 selected design requirements, tolerance semantics, and
-reference-evidence adequacy" for the exact shape. Requirement categories are
-the exact v0.5 `AuthoredChangeScopeCategory` vocabulary, imported directly
-rather than reinvented, since that type carries no runtime-only coupling of
-its own; tolerance is a genuinely new, reference-owned type (never a reuse
-of `frontendContracts.ts`'s runtime/CSS-pixel-implicit `ContractTolerance`);
-and reference-evidence adequacy is a small, independently-owned vocabulary
-distinct from `boundedAgentContext.ts`'s runtime/static-correlation
-`Adequacy`. A region property or derived relationship is never promoted to
-an executable requirement automatically - only explicit user/configuration
-selection does that.
-
-v0.7 Prompt 4 adds explicit reference applicability
-(`domain/externalReferenceApplicability.ts`) and observation-side explicit
-state identity (`domain/explicitState.ts`, shared by both artifact
-families), plus one new pure domain module,
-`domain/externalReferenceCompatibility.ts`, that evaluates whether a
-candidate `ObservationArtifact` describes the same frontend state as a
-given `ExternalReferenceArtifact` - see `docs/CONTRACTS.md` "v0.7 Prompt 4
-reference applicability and candidate-state compatibility" for the exact
-shape. This is page/state-level only, never geometry or fidelity, and
-remains a wholly separate concern from Prompt 3's reference-evidence
-adequacy - the two can independently disagree (an adequate reference can be
-incomparable against a given candidate, and vice versa). Rather than
-inventing a second comparability engine, Prompt 4 extracts one new exported
-pure helper from v0.4's own `domain/comparisonEngine.ts`
-(`assessOptionalComparabilityDimension`) and reuses it from both v0.4's
-`evaluateComparability` (Observation-vs-Observation) and the new
-`evaluateReferenceCandidateCompatibility` (Reference-vs-Observation) - the
-one additive behavior change to v0.4 itself is that `evaluateComparability`
-now assesses (rather than always reporting unassessed) theme/authenticated-
-state/application-state whenever both observations declare
-`requestConfig.explicitState`, while every historical/legacy observation
-pair retains the exact prior unassessed-only behavior. No new persisted
-artifact kind is introduced for the compatibility result; it is a pure,
-on-demand function of two already-persisted artifacts.
-
-v0.7 Prompt 5 adds explicit reference-region <-> runtime-target binding
-(`domain/externalReferenceRuntimeBinding.ts`) - see `docs/CONTRACTS.md`
-"v0.7 Prompt 5 explicit reference-region <-> runtime-target binding" for
-the exact shape. It answers only "which stable v0.2 runtime target does
-this candidate observation resolve for each explicitly declared reference
-region", strictly downstream of Prompt 4's compatibility gate (reused
-verbatim, never duplicated) and strictly upstream of v0.6's own
-runtime/static correlation - the two identity domains (a Prompt 2
-`ReferenceRegion.id` and a v0.2 `NamedTarget.name`) never collapse into
-each other, and this stage stops at the runtime target, never reaching
-source ownership. Following v0.6's uncertainty discipline
-(`domain/boundedAgentContextCorrelation.ts`), binding never guesses through
-ambiguity - an ambiguously or unavailably resolved v0.2 target is reported
-as such, never silently treated as bound - though the actual per-status
-mapping (`bound`/`ambiguous`/`unavailable`) is binding's own, independently
-owned vocabulary, not a reuse of v0.6's `correlated`/`ambiguous`/
-`unavailable` correlation-status semantics (a different evidence boundary:
-correlation ranks *static candidates* for one runtime target, whereas
-binding resolves *one runtime target's own existence* for one declared
-correspondence). No second target resolver, no browser execution, and no
-new persisted artifact family were introduced; neither
-`ExternalReferenceArtifact` nor `ObservationArtifact` is mutated to carry a
-binding result, since a reference may later be evaluated against several
-candidates and an observation against several references.
-
-v0.7 Prompt 6 adds structured reference-vs-candidate fidelity evaluation
-(`domain/externalReferenceFidelity.ts`, `application/referenceFidelityEvaluationService.ts`,
-and the `evaluate-reference-fidelity` CLI command) - the first point in this
-stack where a reference's authored expectation is compared against live
-candidate evidence. See `docs/CONTRACTS.md` "v0.7 Prompt 6 structured
-reference-vs-candidate fidelity evaluation" for the exact shape. It is
-downstream of every prior v0.7 prompt and reuses each verbatim: Prompt 3's
-`deriveReferenceRequirementAdequacy`/`deriveReferenceRequirementExpectation`/
-`deriveReferenceRequirementMeasurement` (never redefined), Prompt 4's
-`evaluateReferenceCandidateCompatibility` (a hard gate, never duplicated),
-and Prompt 5's `evaluateReferenceRuntimeBindings` (the sole source of
-runtime-target identity - no automatic binding, no second target resolver).
-It also reuses v0.4's `deriveLayoutRelationships` for runtime relationship
-evidence, scoped to the exact requested relationship family (the same
-Prompt 3 bug-fix precedent). The one genuinely new problem this prompt
-solves is the reference-image-pixel <-> CSS-pixel coordinate mapping: a
-single explicit, deterministic full-frame scale derived from
-`reference.applicability.viewport` and the reference image's own
-dimensions, with a tiny independent aspect-ratio-coherence check (never a
-design tolerance) gating whether that mapping exists at all. No new
-persisted artifact family, no browser execution, and no source-ownership
-attribution - this is reference fidelity only, a separate concern from any
-later v0.5 baseline/per-change contract result or v0.7 overall verdict.
-
-v0.7 Prompt 7 adds bounded reference-fidelity projection into the existing
-v0.6 bounded-agent-context architecture (`domain/referenceFidelityProjection.ts`,
-plus additive extensions to `domain/boundedAgentContext.ts`,
-`domain/boundedAgentContextIdentity.ts`, and
-`domain/boundedAgentContextProjection.ts`) - see `docs/CONTRACTS.md` "v0.7
-Prompt 7 bounded reference-fidelity projection and v0.6 bounded-agent-
-context integration" for the exact shape. `projectBoundedAgentContext`
-itself, not a new parallel context system, gains one new optional input (an
-already-computed Prompt 6 fidelity evaluation): fidelity-relevant runtime
-targets fold into the exact same required/permitted-target-allocation,
-evidence-tiering, omission/truncation, and adequacy machinery v0.5 contract
-clauses already compete in, and a new `fidelity?:
-BoundedReferenceFidelityProjection` field on `BoundedAgentContextArtifact`
-(mirroring `correlations?`'s own additive, non-version-bumping precedent
-from v0.6 Batch 3) carries a bounded, priority-ordered selection of Prompt
-6's non-passing requirement results plus passing protected/preserved
-context. No second bounded-context architecture, no recomputation of Prompt
-2-6/v0.4/v0.5 logic, and no change to v0.6's own runtime/static correlation
-(`deriveRuntimeStaticCorrelations`/`attachRuntimeStaticCorrelations` are
-untouched and reused exactly as before) - a caller joins fidelity, target,
-and correlation evidence by the one stable v0.2 runtime target id all three
-already share. Every new field is optional and additive; a pre-Prompt-7
-caller supplying no fidelity evidence receives byte-identical output,
-including logical identity.
-
-v0.7 Prompt 8 adds the first complete, controlled end-to-end external-
-reference correction workflow (`domain/referenceCorrectionWorkflow.ts`,
-`domain/referenceCorrectionIdentity.ts`) - see `docs/CONTRACTS.md` "v0.7
-Prompt 8 controlled end-to-end external-reference coding-agent correction
-workflow" for the exact shape. This is a narrowly-scoped coordinator, not a
-second workflow engine: it exposes exactly two pure operations -
-`prepareReferenceCorrection` (pre-change evidence -> a bounded coding-agent
-handoff, built from Prompt 1/3/4/5/6/7's existing engines) and
-`reviewReferenceCorrectionAttempt` (a fresh post-edit candidate -> one
-composed overall result, built from v0.4's `compareObservations`, v0.7
-Prompt 6's `evaluateReferenceCandidateFidelity`, and v0.5's
-`evaluateFrontendContract`) - with an explicit, un-automatable seam between
-them where an external implementation actor edits target source. Overall
-`'pass'` requires both reference fidelity `'pass'` and v0.5 contract
-evaluation `'PASS'` - matching the selected design reference is necessary
-but never sufficient, so a candidate that visually satisfies the reference
-while regressing an active protected or preserved contract clause still
-resolves to overall `'fail'`. Review identity is a deterministic hash of
-`{referenceRequestId, baselineObservationId, baselineContractId,
-baselineContractClauses, changeContractId, changeContractClauses,
-bindingDeclarations}`; attempt identity is a deterministic hash of
-`{reviewRequestId, candidateObservationId}`. `reviewReferenceCorrectionAttempt`
-rejects any call whose supplied `reviewRequestId` does not match what its own
-baseline/contract/reference/binding inputs recompute - the mechanism that
-makes "every attempt evaluates against the same approved baseline" an
-enforced invariant, not just a documented one. No new persisted artifact
-family, no CLI surface, and - most importantly - no code path anywhere in
-this module (or anything it calls) that opens, parses, or writes a target
-source file: real candidate capture remains the caller's own responsibility
-through the existing, unmodified real-Chromium observation pipeline.
+# Architecture
+
+## v0.10 visual workflow boundaries
+
+`VisualChangeWorkflowArtifact` (`1.0.0`) is the only new persisted v0.10
+family. It owns frozen scope, explicit activation/restoration, immutable
+attempt and review revisions, and optional references to governance results.
+The Viewer is the human workflow entry; `checkProject` remains the canonical
+evaluator. `VisualChangeAgentHandoff` (`1.0.0`) is a generated, non-persisted
+transfer contract. An external human or coding agent edits source. Optional
+orchestrator metadata is traceability only and Observer never imports or runs
+the orchestrator. Human acceptance is separate from baseline/reference
+governance and never rewrites prior workflow evidence.
+
+## v0.8.1 project workflow
+
+Versioned project configuration (`1.0.0` compatibility plus current `1.1.0`
+acceptance input), upward discovery, centralized managed paths, and the atomic
+alias catalog live under `src/projectWorkflow`. Aliases select exact canonical
+artifact directories; they never replace artifact identities.
+
+Project `check` validates the selected baseline artifact before candidate
+capture. The capture still takes URL, viewport, targets, and operational
+defaults from current project configuration. Only the validated baseline's
+optional `scrollScenario` and `explicitState` are replayed through the
+existing normalized request and observation path. The project-config schema
+does not own these fields. Explicit state remains declarative identity
+metadata; replay does not establish application or session state.
+
+`src/application/projectCheckService.ts` composes the existing observation,
+comparison, contract-evaluation, reference-reader, explicit-binding,
+compatibility, and fidelity owners. `src/projectWorkflow/checkAcceptance.ts`
+owns contained acceptance-input resolution and shared file-wrapper parsing.
+`checkResult.ts` owns the bounded ephemeral projection, not a persisted check
+artifact or evaluation engine. Status precedence is `BLOCKED`, then `FAIL`,
+then `PASS` when all configured executable dimensions pass, then
+`REVIEW_REQUIRED` when comparison is the only evidence. Canonical observations,
+comparisons, and contract evaluations remain persisted; reference fidelity and
+the workflow result remain in memory/presentation.
+
+## Current package architecture
+
+The current repository is one published TypeScript ESM package
+(`@dailephd/my-frontend-observer@0.10.1`). The CLI remains
+`my-frontend-observer`; the npm scope does not rename the product or artifact
+identities.
+
+- `src/cli.ts` is the real, thin public CLI parsing/dispatch/presentation
+  boundary for the current command surface (`observe`, `compare`,
+  `approve-baseline`, `save-change-contract`, `evaluate-contract`,
+  `import-reference`, `approve-reference`, `evaluate-reference-fidelity`,
+  `view`, `init`, `capture`, `check`); argument parsing and output formatting
+  only, per command - domain semantics remain owned by application/domain
+  services rather than the CLI. v0.6 added no new CLI command; v0.7 added the
+  three external-reference commands; v0.8 added `view`; v0.8.1 added `init`,
+  `capture`, and `check` and made `view` project-aware while preserving its
+  standalone `--root` behavior.
+- `src/index.ts` is the library entry point re-exporting the observer-owned
+  contracts/functions from every layer below, including the v0.6 bounded-agent-
+  context projection and runtime/static correlation surface, and the v0.7
+  external-reference/region/requirement/applicability/compatibility/binding/
+  fidelity/correction-workflow surface (`prepareReferenceCorrection`/
+  `reviewReferenceCorrectionAttempt` remain programmatic-only, with no CLI
+  command).
+- `scripts/clean.mjs` safely removes only the project `dist/` directory.
+- `scripts/check-docs.mjs` validates the canonical documentation foundation,
+  roadmap version presence, and the no-batches rule.
+- TypeScript, ESLint, Vitest, and package configuration provide foundation
+  validation, now exercised by real product tests (`tests/unit/`,
+  `tests/browser/`).
+
+Batch 1 added the observation domain/schema and safety-policy layer
+(`src/domain/`, `src/request/`, `src/safety/`). Batch 2 added a real
+Playwright Chromium browser adapter (`src/browser/`), a minimal application
+seam invoking it (`src/application/`), and a deterministic browser
+fixture/test boundary (`tests/fixtures/`, `tests/browser/`, run via
+`npm run test:browser`). Batch 3 extended that single browser adapter with an
+internal page/target measurement module (`src/browser/evidenceCapture.ts`)
+that reads page and explicit-CSS-target evidence from the same live,
+already-ready page used for the screenshot - no second browser/page is ever
+opened, and Playwright objects still never leave `src/browser/`. Batch 4
+added the artifact ownership boundary itself: `src/artifacts/artifactWriter.ts`
+is the one canonical place that writes an observation to disk (temp
+directory, then one atomic rename into `<outputLocation>/<observationId>/`),
+and `src/application/observationPersistence.ts` assembles the frozen
+`ObservationArtifact` from a browser-capture result before handing it to the
+writer. The artifact layer has no Playwright dependency and is testable
+without launching Chromium. Batch 5 completed the boundary chain: `src/cli.ts`
+parses `observe` arguments (CLI-syntax errors only - e.g. malformed
+`WIDTHxHEIGHT`), constructs a raw request, and hands it to the existing
+Batch 1 `normalizeRequest`; on success it calls one new application-level use
+case, `observe()` in `src/application/observationPersistence.ts`, which runs
+the existing `runBrowserCapture` exactly once and, only on success, the
+existing artifact writer exactly once, then returns a small observer-owned
+`ApplicationObservationResult` (observation id, completion state, artifact
+path, target/diagnostic counts) for the CLI to print. The CLI never imports
+Playwright or the filesystem-write path directly. Batch 6 closed the
+remaining real-Chromium coverage gap (a genuine navigation failure, distinct
+from a readiness timeout or a pre-launch safety rejection) and validated the
+packed npm tarball end to end in a clean consumer environment, independent
+of the source checkout. At the end of the v0.1 implementation there was no
+controlled-scroll or comparison behavior.
+
+## Current v0.2 architecture (released/current architecture)
+
+v0.2 extends the same architecture rather than adding a parallel one.
+`src/request/request.ts` now owns a canonical `{name, locators}` target
+model (`TargetLocator`, six frozen kinds) in place of the old CSS-only
+shape; the legacy `{name, selector}` input still normalizes into it. The one
+existing browser-side target resolver/measurement module,
+`src/browser/evidenceCapture.ts`, was extended - not replaced - to resolve
+all six locator kinds against the live page through a single Playwright
+`Locator` per attempt, honor the frozen ordered-fallback/ambiguity/
+unavailable-no-fallback contract, and converge every kind on the same
+measurement path (`captureResolvedTargetRecord`); it additionally computes
+bounded semantic state, derived landmark identity, and configured-target-
+only DOM containment from the same already-resolved elements in the same
+capture pass - no second browser/page, no second resolution algorithm.
+`src/domain/schema.ts` extends `TargetEvidenceRecord`/`TargetResolution`
+additively for schema `1.1.0`, with matching structural validation in
+`isValidObservationArtifact`. `src/cli.ts` gained one CLI/input-boundary-
+only addition, `--targets-file`: it reads and validates only the JSON root
+wrapper (via the already-imported `node:fs`, never `node:fs/promises`) and
+hands the parsed `targets` value into the existing `RawObservationRequest`/
+`normalizeRequest()` path unchanged - there is no second application
+observation use case, and Playwright objects still never leave
+`src/browser/`. The artifact writer, application observation use case, and
+overall boundary chain (`CLI → normalizeRequest → observe() →
+runBrowserCapture → artifact writer`) are unchanged from v0.1.
+
+## Current v0.3 architecture (released/current architecture)
+
+v0.3 extends the same single-observation architecture again; it does not add
+a second browser lifecycle, target resolver, or artifact path.
+`src/request/request.ts` adds one optional `scrollScenario` field to
+`NormalizedObservationRequest` (`ScrollScenario { action }`, exactly
+`window-scroll-by` or `target-scroll-by`); `src/domain/schema.ts` adds the
+matching bounded runtime evidence types (`ScrollRuntimeSnapshot`,
+`ViewportRelationEvidence`, `OverflowEvidence`, `ScrollScenarioTransition`,
+`ScrollOwnerInterpretation`) and structural validation for schema `1.2.0`
+(additive over `1.1.0`). `src/domain/scrollEvidence.ts` holds the pure,
+browser-independent derivations (viewport relation, actual overflow,
+transitions, and `deriveScrollOwner`) so they are unit-testable without
+Chromium. `src/browser/scrollCapture.ts` holds the one browser-side scenario
+capture module: it reuses `evidenceCapture.ts#resolveConfiguredTargets` (now
+exported) to resolve configured targets exactly once, captures an initial
+`ScrollRuntimeSnapshot`, performs the one immediate scroll
+(`window.scrollBy`/`element.scrollBy`, both `behavior: 'instant'`), waits
+exactly two `requestAnimationFrame` cycles, and captures a final snapshot -
+all inside `chromiumAdapter.ts#captureViewportInternal`'s existing single
+navigate → ready → capture flow, strictly before the unchanged
+screenshot/`capturePageEvidence`/`captureTargetEvidence` calls, so every
+downstream capture (including a no-scenario request, which skips this block
+entirely) describes only the final state. `src/cli.ts` gained one CLI/input-
+boundary-only addition, `--scroll-scenario-file`: mirroring
+`--targets-file`, it reads and validates only the file readability/JSON-
+validity/non-array-object-root shape and hands the parsed value straight
+into `RawObservationRequest.scrollScenario` - every scenario/action rule
+(kind, deltas, target reference) stays owned by `normalizeRequest()`. There
+is still one canonical `observe()` application use case and one artifact
+writer; `scrollScenarioEvidence` is simply one more optional field on the
+same `ObservationArtifact`.
+
+## Current v0.4 architecture (released/current architecture)
+
+v0.4 adds one new downstream pipeline that consumes `ObservationArtifact`
+values rather than producing them - it never adds a second browser lifecycle,
+target resolver, or observation engine:
+
+```text
+ObservationArtifact before  ObservationArtifact after
+        \                          /
+         `--------.       .-------'
+                    \     /
+              artifact reader (src/artifacts/artifactReader.ts)
+                       ↓
+              comparability evaluation (src/domain/comparisonEngine.ts)
+                       ↓
+    canonical relationship derivation, called for each side independently
+              (src/domain/relationships.ts#deriveLayoutRelationships)
+                       ↓
+              canonical comparison derivation
+              (src/domain/comparisonEngine.ts#compareObservations)
+                       ↓
+                ComparisonArtifact
+                       ↓
+    atomic comparison writer (src/artifacts/comparisonArtifactWriter.ts)
+
+CLI `compare`
+        ↓
+application service only (src/application/comparisonService.ts)
+        ↓
+[reader → domain comparison → writer, as above]
+```
+
+`src/domain/relationships.ts` froze the layout-relationship contract and
+implements the one canonical pure derivation,
+`deriveLayoutRelationships(observation, options?)`: horizontal/vertical
+order, area overlap, relative width, geometric fit, vertical sequencing,
+page-width fit/exceeds, and a standalone `deriveTargetClipping(record)` -
+all computed only from an already-captured `ObservationArtifact`'s own
+`targetEvidence`/`pageEvidence`, never from a second browser query. DOM
+containment is read directly from the existing v0.2 `TargetContainment`
+evidence rather than re-derived, and stays a distinct concept from
+geometric fit.
+
+`src/domain/comparisonEngine.ts` implements the one canonical pure
+before/after engine, `compareObservations(before, after, config?)`:
+validates both source artifacts, evaluates comparability *before* any
+rendered difference is calculated, calls `deriveLayoutRelationships` once
+per side with the same tolerance, and derives target/page differences and
+relationship changes. `src/artifacts/comparisonArtifactWriter.ts` persists
+the result atomically (sibling temp directory, then one rename) as
+`<outputLocation>/<comparisonId>/manifest.json` only - no screenshot is
+copied; the manifest's `before`/`after` references point back to the
+source observations' own `screenshot.path`. `src/application/
+comparisonService.ts` is the one application-layer seam: `compareAndPersist`
+takes two in-memory `ObservationArtifact`s and does exactly one comparison
+plus exactly one persist; `compareAndPersistFromArtifactRoots` is a thin
+wrapper that additionally reads both sides from disk via the existing
+`src/artifacts/artifactReader.ts#readObservationArtifact` reader (itself
+just a `manifest.json` parse plus the same `isValidObservationArtifact`
+structural gate the writer uses).
+
+`src/cli.ts` gained one new top-level command, `compare`
+(`--before`/`--after`/`--output`/`--config-file`), implemented with the same
+thin-CLI-boundary discipline as `observe`: `parseCompareArgs` handles only
+argument shape/duplication, an optional `loadComparisonConfigFile` reads and
+validates only file readability/JSON-validity/non-array-object-root (exactly
+like `--targets-file`/`--scroll-scenario-file`), and the command body calls
+`compareAndPersistFromArtifactRoots` exactly once. **The CLI's comparison
+path never launches Chromium** - `src/cli.ts` imports nothing from
+`src/browser/` or `src/artifacts/` (it only reaches persistence and artifact
+reading indirectly, through the application-layer seam above), matching the
+same import-boundary discipline already enforced for `observe`.
+
+## Current v0.5 architecture (released/current architecture)
+
+v0.5 adds one new downstream layer that consumes `ComparisonArtifact` values
+(plus the source `ObservationArtifact` pair) rather than producing them - no
+new browser lifecycle, target resolver, or comparison engine is added:
+
+```text
+ObservationArtifact before + after
+              ↓
+existing v0.4 comparison/relationship pipeline (unchanged)
+              ↓
+        ComparisonArtifact
+              ↓                                PersistentBaselineContract
+              |                                          +
+              `------------------------→   PerChangeContract
+                                                          ↓
+                        canonical contract evaluation
+                        (src/domain/frontendContractEvaluation.ts#evaluateFrontendContract)
+                                                          ↓
+                        clause results + unexpected changes + overall PASS/FAIL
+```
+
+`src/domain/frontendContracts.ts` froze the contract/change-scope type,
+constant, and structural-validator vocabulary (Batch 1); `src/domain/
+frontendContractIdentity.ts` froze deterministic contract/baseline/clause
+identity in the same canonicalize+sha256(+opaque-nonce) style as `src/domain/
+comparisonIdentity.ts`. `src/domain/frontendContractEvaluation.ts#evaluateFrontendContract`
+(Batch 2) is the one canonical pure evaluation entry point: it validates its
+five inputs (before/after `ObservationArtifact`, `ComparisonArtifact`,
+`PersistentBaselineContract`, `PerChangeContract`) are structurally coherent
+and mutually consistent, calculates the active baseline clause set after
+explicit supersession, detects bounded structural conflicts, evaluates every
+active clause via the frozen 15-primitive vocabulary against the existing
+`ComparisonArtifact`/`ObservationArtifact` evidence (never re-deriving
+clipping/relationship/scroll-owner facts), classifies unaccounted-for
+`ComparisonArtifact.differences` entries as `unexpected`, and derives one
+overall `PASS`/`FAIL` verdict. It performs no I/O, launches no browser, and
+persists nothing - `src/domain/frontendContractEvaluation.ts` itself remains
+untouched by the persistence layer below (Batch 3).
+
+Batch 3 adds the persistence/application boundary around this frozen domain,
+without redefining it:
+
+```text
+        ComparisonArtifact (read via new src/artifacts/comparisonArtifactReader.ts)
+              +
+PersistentBaselineContract / PerChangeContract
+(read/written via src/artifacts/frontendContractArtifactReader.ts / ...Writer.ts)
+              ↓
+src/application/frontendContractEvaluationService.ts#evaluateAndPersist
+              ↓
+    evaluateFrontendContract()  [called exactly once, unmodified]
+              ↓
+src/domain/frontendContractEvaluationArtifact.ts
+    (minimal additive persisted envelope around the frozen result)
+              ↓
+src/artifacts/frontendContractEvaluationArtifactWriter.ts
+    (atomic write, exactly once on a structurally constructible result)
+```
+
+`evaluateAndPersistFromArtifactRoots` is the CLI-facing wrapper, reading
+before/after observations through the existing `readObservationArtifact` (no
+second observation reader), the comparison and both contract classes
+through the new readers, then delegating to `evaluateAndPersist` exactly
+once - mirroring `application/comparisonService.ts#compareAndPersistFromArtifactRoots`'s
+own thin-wrapper shape.
+
+Batch 4 exposes this through the same thin-CLI boundary already established
+by `observe`/`compare`:
+
+```text
+src/cli.ts (argument parsing, JSON-file-shape checks, help/output formatting,
+            exit-code selection only)
+        ↓
+src/application/frontendContractPersistenceService.ts#approveAndPersistBaseline
+src/application/frontendContractPersistenceService.ts#persistPerChangeContract
+src/application/frontendContractEvaluationService.ts#evaluateAndPersistFromArtifactRoots
+        ↓
+domain validators (isValidPersistentBaselineContract / isValidPerChangeContract)
++ artifact readers/writers (Batch 3)
++ evaluateFrontendContract() (Batch 2, unmodified)
+```
+
+Three new top-level commands - `approve-baseline`, `save-change-contract`,
+`evaluate-contract` - each parse only CLI-syntax concerns (duplicate/missing
+flags, JSON-file readability/parseability/object-root shape) and delegate to
+exactly one application-layer call; `src/cli.ts` imports no artifact writer/
+reader module and no browser code, matching the existing `observe`/`compare`
+import-boundary discipline exactly. `approveAndPersistBaseline` adds the one
+new coherence check Batch 3 did not need: verifying a baseline contract's
+frozen `sourceObservation` reference actually matches the supplied
+observation artifact before persisting - explicit approval only, never
+inferred from a `compare` or `evaluate-contract` result. `--enforce` on
+`evaluate-contract` is applied only after evaluation and persistence have
+already completed; it selects the process exit status for an already-final
+`FAIL` result and is never part of any identity or persisted field.
+
+## Current v0.6 architecture (released as `0.6.0`)
+
+v0.6 adds one new downstream, read-only layer that consumes existing v0.1-v0.5
+evidence (`ObservationArtifact`, `ComparisonArtifact`,
+`PersistentBaselineContract`/`PerChangeContract`, and evaluation results)
+plus caller-supplied bounded static candidate evidence - it adds no new
+browser lifecycle, target resolver, observation/comparison/contract engine,
+or persisted artifact family:
+
+```text
+ObservationArtifact(s) + ComparisonArtifact + contract/evaluation evidence
+              ↓
+src/domain/boundedAgentContextProjection.ts#projectBoundedAgentContext
+              ↓
+    BoundedRuntimeTargetProjection
+    (page/viewport identity, stable targets, geometry, runtime behavior,
+     relationships, before/after differences, contract results,
+     requested/expected-dependent/protected/preserved scope reused verbatim
+     from src/domain/frontendContracts.ts, diagnostics, artifact/screenshot
+     references, provenance, adequacy, omission, truncation)
+              ↓
+src/domain/boundedAgentContextCorrelation.ts
+    #deriveRuntimeStaticCorrelations / #attachRuntimeStaticCorrelations
+              ↓
+    RuntimeStaticCorrelation[] (correlated / ambiguous / unavailable,
+    competing candidates preserved verbatim - never collapsed to one owner)
+              ↓
+src/index.ts (public export/correlation boundary only)
+```
+
+`src/domain/boundedAgentContext.ts` freezes the bounded-projection and
+correlation type/constant vocabulary (`Adequacy`, `ADEQUACY_REASON_CODES`,
+`OmissionRecord`, `TruncationRecord`, `BOUNDED_AGENT_CONTEXT_ARTIFACT_KIND`,
+schema `1.0.0`). `src/domain/boundedAgentContextIdentity.ts` derives a
+deterministic logical identity distinct from a fresh per-execution instance
+identity, in the same canonicalize+hash style as
+`comparisonIdentity.ts`/`frontendContractIdentity.ts`.
+`boundedAgentContextProjection.ts` performs no browser I/O and re-derives
+nothing already owned upstream - it reads already-captured artifacts and
+reuses the existing v0.4 relationship/comparison evidence and v0.5
+change-scope clause types directly. `boundedAgentContextCorrelation.ts`
+accepts only plain, caller-supplied candidate static-evidence records; it has
+**no** dependency on `@dailephd/my-dev-kit`, since the audit that preceded
+implementation found no generic static-side retrieval capability actually
+missing (see `docs/ROADMAP.md` v0.6 "Dependency direction" - the "determine
+whether my-dev-kit requires a static-side change" step concluded no).
+Runtime target identity is carried through this module verbatim; the module
+never adds a `sourceOwner`/`causedBy`-shaped field, preserving the
+architectural rule that runtime identity never silently becomes source
+ownership.
+
+This layer is a programmatic export/correlation boundary only: `src/index.ts`
+re-exports its full type/function surface, but there is no new CLI command,
+no `src/artifacts/boundedAgentContext*` writer/reader, and no orchestrator or
+lab code in this repository - those remain separate sibling-repository
+responsibilities per the Milestone 6 ownership split in
+`docs/PROJECT_MILESTONES.md`.
+
+## v0.7-v0.10 reference-evidence architecture constraints
+
+The external visual-reference capability (v0.7) is released as package
+version `0.7.0` - see "v0.7 Prompt 1" through "v0.7 Prompt 8" below for the
+actual architecture, and `docs/CURRENT_STATE.md` for release state. It
+extends the existing v0.1-v0.6 evidence architecture rather than becoming a
+UI-only feature or a parallel visual-comparison stack. v0.8 (interactive
+viewer) is released as package version `0.8.0`. v0.9 (structured visual
+annotation) is released as package version `0.9.0` - see "v0.9 visual
+annotation architecture" below. v0.10 (full graphical human-LLM workflow) is
+released as `0.10.0`; v0.10.1 adds narrow project-check baseline context
+replay without changing these evidence domains. The constraints below apply
+to v0.9 and v0.10.
+
+The evidence domains remain distinct:
+
+```text
+runtime observation A ↔ runtime observation B
+→ existing before/after comparison
+
+approved baseline/per-change contract ↔ candidate runtime evidence
+→ existing canonical contract evaluation
+
+external visual reference ↔ candidate runtime evidence
+→ reference applicability + structured fidelity evaluation (v0.7,
+  released as `0.7.0` - see "v0.7 Prompt 4" and "v0.7 Prompt 6" below)
+```
+
+An external reference is not an `ObservationArtifact`, and a reference region
+is not a runtime target. The released v0.7 implementation preserves explicit
+identity and provenance for the reference image/version, reference regions,
+applicable viewport/theme/application state, authored requirements, tolerances,
+approval/supersession state, and reference-region/runtime-target bindings.
+Bindings are explicit and evaluate to `bound`, `ambiguous`, or `unavailable`;
+they never silently become source ownership.
+
+The non-UI reference model and structured reference-vs-candidate evaluation
+were established in v0.7 before v0.8. v0.8 may render side-by-side images,
+overlays, measurements, bindings, provenance, and fidelity results, but it must
+consume those existing engines and must not invent a second reference model or
+evaluation engine. v0.9 may author annotations against either runtime
+screenshots or external references, but both coordinate/identity domains remain
+explicit and feed the same canonical contract/change-scope semantics. v0.10
+combines both visual entry modes with the existing correction loop.
+
+Where a reference requirement is executable, it uses the existing v0.5
+requested/expected-dependent/protected/preserved semantics. Informational or
+unassessed reference evidence remains non-executable until explicitly selected.
+There is no reference-only PASS/FAIL taxonomy.
+
+The released reference evaluation reuses existing relationship/value
+conventions where they mean the same thing and adds distinct reference-owned
+units only where the image evidence requires them. v0.7 does not use pixel or
+image-region similarity as a success mechanism; a later bounded similarity
+feature may supplement structured evidence if separately designed, but it must
+not replace browser-authoritative runtime geometry, canonical contract
+evaluation, or explicit relationship evidence.
+
+Candidate rendering still uses the one existing Chromium observation engine.
+The observer remains non-mutating. `my-dev-kit` remains the static/source
+evidence owner, and the v0.6 correlation/bounded-context boundary remains the
+route for attaching relevant source evidence to reference-driven correction
+packets. Heavy reference image bytes are referenced rather than copied into
+every downstream context/evaluation record.
+
+Theme, application-state, viewport, and authenticated-state applicability are
+checked before reference fidelity is interpreted through the released v0.7
+compatibility path, which reuses v0.4 comparability conventions. If reference
+and candidate do not represent compatible intended states, the result is
+explicitly incompatible/incomparable rather than a fabricated visual difference
+set. v0.8, released as package version `0.8.0`, displays this result exactly
+as required rather than redefining the state model - see "v0.8 Batch 5"
+below.
+
+The constraints above were carried out by the actual v0.7 implementation
+described in "v0.7 Prompt 1" through "v0.7 Prompt 8" below: explicit
+identity/provenance, applicability/compatibility, region-to-target bindings,
+requested/expected-dependent/protected/preserved reuse, and the non-mutating
+Chromium/correlation boundaries all remain as constrained here. v0.8 (see
+"v0.8 Batch 1" through "v0.8 Batch 8" below) applied them unchanged, and so
+does the implemented v0.9 annotation layer. They continue to apply unchanged
+to the still-future v0.10 work.
+
+The exact public artifact names, schema versions, persistence layout, supported
+image formats, coordinate model, requirement/tolerance primitives, and fidelity
+behavior were frozen by the actual v0.7 implementation below, not by earlier
+planning language. Style/asset-similarity mechanisms remain future unless
+separately implemented.
+
+## v0.8 Batch 1 (Viewer runtime and PWA foundation) — implemented
+
+Batch 1 of the frozen `docs/plans/v0.8-implementation-plan.md` establishes
+only the viewer runtime/build shell — no evidence indexing, artifact reading,
+or evidence UI. It does not implement any of the v0.7-derived reference/
+fidelity/binding display constraints above; those remain future work for
+later v0.8 batches, which must consume this runtime boundary rather than
+redefine it.
+
+```text
+my-frontend-observer view [--root <evidence-root>]
+        |
+        v
+  thin CLI dispatch (src/cli.ts: parseViewArgs/runViewCommand)
+        |
+        v
+  viewer application seam (src/viewerServer/viewerService.ts: startViewer)
+        |
+        v
+  Node local server, loopback-only (src/viewerServer/httpServer.ts)
+        |
+        +---------------------+----------------------+
+        |                                             |
+        v                                             v
+  built viewer assets (dist/viewer)          GET /api/status
+  (React + TypeScript + Vite PWA)            (session/root identity only)
+```
+
+- **Node server boundary** (`src/viewerServer/`): binds only to `127.0.0.1`
+  on one fixed default port (`4319`, `src/viewerServer/port.ts`); serves only
+  the built viewer assets plus the one read-only status endpoint; resolves
+  every requested path against the built assets root and fails closed on any
+  path that would resolve outside it; accepts no write HTTP methods; performs
+  no artifact reading, browser observation, or mutation. `--root` is
+  validated operationally (exists, is a directory) and exposed only as an
+  opaque status string — it is never interpreted as Observer evidence in this
+  batch.
+- **Browser application** (`viewer/`): a React + TypeScript + Vite app, built
+  independently of `src/` via `viewer/tsconfig.json` and `viewer/vite.config.ts`,
+  output to `dist/viewer` inside the existing package `dist` allowlist (no
+  second npm package). Renders an honest foundation shell only — product
+  identity, live session status via `/api/status`, and placeholder
+  navigation/workspace/details regions — never fabricated evidence.
+- **PWA**: `vite-plugin-pwa` generates a web app manifest (`standalone`
+  display, stable `start_url`/`scope`, installability icons) and a service
+  worker that precaches only the built application shell. It declares no
+  `runtimeCaching` rules, so future evidence/media/API routes remain
+  network/server-backed rather than silently served as stale cached truth
+  when the local server is unavailable (enforced by
+  `tests/unit/viewerPwaBuild.test.ts`, which asserts on the actual built
+  `sw.js`, not a hand-written approximation). An install affordance appears
+  only when the browser actually fires `beforeinstallprompt`; its absence is
+  shown honestly, never as a disabled-looking fake control.
+- **CLI**: `view [--root <evidence-root>] [--port <n>] [--no-open]` remains a
+  thin dispatcher — it parses syntax, delegates once to `startViewer`, prints
+  the URL/root, and optionally best-effort opens the system browser (failure
+  there is never fatal to server startup). All v0.1-v0.7 commands are
+  unchanged.
+
+This batch introduces no second observer, relationship engine, comparison
+engine, contract engine, reference model, or bounded-context builder — there
+is nothing yet for the viewer to consume beyond its own runtime identity.
+
+## v0.8 Batch 2 (Evidence indexing, canonical readers, and lazy data boundary) — implemented
+
+Batch 2 adds the safe, read-only data boundary between existing on-disk
+Observer evidence and the Batch 1 viewer runtime, entirely under
+`src/viewerServer/evidence/`. It introduces no new persisted artifact family,
+no schema migration, and no second validator — every recognized candidate is
+decided exclusively by the existing canonical reader/validator for its
+family (`src/artifacts/*Reader.ts`).
+
+```text
+GET /api/index                     bounded discovery + classification -> metadata only
+GET /api/artifacts/<handle>        one canonical-reader read, on demand -> full projection
+GET /api/media/<handle>/<role>     one resolved, contained media file, streamed on demand
+```
+
+- **Discovery** (`evidence/discovery.ts`): a bounded, deterministic walk
+  beneath `--root` that opens only files literally named `manifest.json` (the
+  one filename every current persisted family uses) — no other file is ever
+  read or classified, so arbitrary files can never become evidence merely by
+  existing under the root. Directory entries that are symlinks/junctions are
+  never followed. Bounds (`evidence/limits.ts`): traversal depth 6,
+  directories visited 2000, candidate manifests 1000, index records 500,
+  manifest read size 2,000,000 bytes — chosen after inspecting that every
+  current writer produces a shallow `<outputLocation>/<id>/manifest.json`
+  shape (see `docs/CONTRACTS.md`), not a deep tree.
+- **Classification is not validation** (`evidence/classify.ts`): peeks only
+  `artifactKind`/`schemaVersion` (plus, where the shared kind is ambiguous,
+  tries each existing reader/validator in turn — e.g. baseline vs. per-change
+  contract) to decide *which* existing canonical reader to call; the reader's
+  own structural validator remains the sole authority. Six honest, mutually
+  exclusive states: `supported`, `unsupported-version`, `invalid-structure`,
+  `unrecognized-kind`, `malformed-json`, `unreadable` — never collapsed into
+  one boolean, and never conflated with an artifact's own `completion`
+  state (passed through separately, only for the families that carry one:
+  observation and external-reference). A manifest declaring the
+  `bounded-agent-context` kind is classified `unrecognized-kind`: v0.6/v0.7
+  never added a disk writer/reader for that family (confirmed via direct
+  source inspection and `@dailephd/my-dev-kit` search), so Batch 2 does not
+  invent persistence-shaped handling for it.
+- **Viewer handles** (`evidence/handles.ts`, `evidence/pathSafety.ts`): a
+  handle is a family-prefixed, percent-encoded, root-relative directory path
+  — never a raw filesystem path accepted from the browser. Every route that
+  accepts a handle re-decodes and re-resolves it against the evidence root,
+  re-checks containment, and re-classifies that one candidate before serving
+  anything; a handle whose backing directory or manifest no longer matches
+  what was indexed fails closed as unknown, never stale.
+- **Ephemeral projection** (`evidence/projection.ts`): `EvidenceMetadataRecord`
+  (bounded, `/api/index`-shaped: handle, family, support state, logical id,
+  schema version, completion where applicable, media availability summary,
+  a handful of related ids) and `EvidenceArtifactDetail` (the already-
+  validated domain object, wrapped with `handle`/`family` — no new evidence
+  schema, no recomputation, no persistence).
+- **Media resolution** (`evidence/mediaResolver.ts`): `screenshot` (observation),
+  `image` (imported external reference), and `source-image` (approved
+  external reference) are the only three recognized roles. An approved
+  reference's image is never assumed to live in the approved artifact's own
+  directory — its `sourceReference.referenceId` is looked up against the
+  current index to find the actual owning imported artifact
+  (`evidence/index.ts#findImportedReferenceDir`), exactly matching the v0.7
+  reference-ownership contract in `docs/CONTRACTS.md`. A genuinely missing
+  screenshot/image/source artifact is reported as 404, never fabricated.
+- **PWA cache boundary preserved, not re-verified from scratch**: every new
+  route lives under `/api/`, already covered by Batch 1's
+  `denylist:[/^\/api\//]` navigation-fallback rule — no new `runtimeCaching`
+  entry was needed or added (`tests/unit/viewerPwaBuild.test.ts` asserts this
+  against the real built `sw.js`).
+- **Minimal UI** (`viewer/src/hooks/useEvidenceIndex.ts`,
+  `useArtifactDetail.ts`, `components/EvidenceList.tsx`,
+  `ArtifactPreview.tsx`): a bounded evidence list (metadata-first) plus
+  on-demand full-artifact loading on selection, with every support state
+  shown honestly. No screenshot rendering, SVG overlay, or comparison/
+  contract/reference visualization exists yet — that begins in Batch 3.
+
+## v0.8 Batch 3 (Runtime observation inspection and SVG overlays) — implemented
+
+Batch 3 makes one already-supported `ObservationArtifact` (Batch 2's data
+boundary, unchanged) genuinely understandable: a real screenshot, SVG target
+overlays in the observation's own canonical coordinate domain, target
+selection/inspection, and canonical layout-relationship display. No second
+relationship engine, no client-side evidence derivation, no new persisted
+artifact.
+
+**Coordinate audit (the load-bearing decision for this batch)**: target
+geometry (`TargetGeometry.x/y/width/height`) is captured via
+`el.getBoundingClientRect()` (`src/browser/evidenceCapture.ts`) - CSS pixels,
+relative to the current viewport's top-left, at the same live page state the
+screenshot is taken from. The screenshot itself is `page.screenshot({type:
+'png'})` (`src/browser/chromiumAdapter.ts`), Playwright's default
+(non-fullPage) mode, against a browser context created with no
+`deviceScaleFactor` override (`browser.newContext({viewport})`) - so it
+defaults to `1`, meaning every observation this repository can currently
+produce has a screenshot whose raw PNG pixel dimensions equal
+`requestConfig.viewport.width × requestConfig.viewport.height` exactly (1
+CSS pixel = 1 PNG pixel). `requestConfig.viewport` (a required, strongly-typed
+field on every valid `ObservationArtifact`, distinct from the loosely-typed
+`pageEvidence` bag) is therefore the canonical, always-present source for the
+SVG display frame.
+
+**SVG coordinate model** (`viewer/src/components/TargetOverlaySvg.tsx`): the
+`<svg>` root's `viewBox` is `0 0 {requestConfig.viewport.width}
+{requestConfig.viewport.height}` - the exact frame `getBoundingClientRect()`
+already used. The screenshot loads into a `<image>` element filling that same
+viewBox (`preserveAspectRatio="none"`, since the two frames are already
+pixel-identical). Target `<rect>` elements use `geometry.x/y/width/height`
+completely unchanged - no rounding, no `devicePixelRatio` multiplication, no
+clamping; geometry lying partly outside the viewBox is drawn at its real
+coordinates and clipped only by the SVG root's default `overflow: hidden`
+(a display-only effect, verified never to touch the underlying evidence
+value - `tests/unit/observationCoordinateMapping.test.ts`). This is robust
+even if a future capture path used a different `deviceScaleFactor`: the
+`<image>`/viewBox scaling is presentation-only browser behavior, never a
+manual pixel calculation in this codebase. `devicePixelRatio` (captured as
+`pageEvidence.devicePixelRatio`) is shown as informational observation-level
+evidence only and is never consulted for any geometry calculation.
+
+**Server additions** (`src/viewerServer/evidence/observationView.ts`, one new
+route `GET /api/observations/<handle>/relationships`): the only new
+server-side computation this batch adds is one thin, defense-in-depth-wrapped
+call to the existing canonical, pure `deriveLayoutRelationships` (`src/domain/
+relationships.ts`) - never a second relationship predicate implementation.
+Mirrors the exact handle-decode → contained-dir-resolve → re-classify
+discipline `loadArtifactByHandle`/`resolveMedia` already established in
+Batch 2; a handle for a non-`observation` family or a non-`supported`
+candidate is rejected (`409`) before derivation is even attempted. The
+existing `GET /api/artifacts/<handle>` (full `ObservationArtifact`) and
+`GET /api/media/<handle>/screenshot` (Batch 2, unchanged) remain the only
+other data sources the observation workspace uses - no new artifact
+projection endpoint was needed, since the full validated domain object
+already contains everything the target/observation inspector displays.
+
+**Client-side presentation only** (`viewer/src/observation/targetOrder.ts`,
+`viewer/src/components/{ObservationWorkspace,TargetList,TargetOverlaySvg,
+ObservationInspector,EvidenceFieldView}.tsx`): React selects, orders
+(by the observation's own authored `requestConfig.targets` order, not
+incidental object-key order), and formats already-fetched canonical fields.
+It never resolves targets, computes relationships, or derives
+visibility/overflow/scroll-owner semantics - `deriveLayoutRelationships`
+runs exclusively on the server (above). An unresolved target (`not-found`/
+`ambiguous`/`unavailable`) is selectable from the target list and shown
+honestly in the inspector, but never receives a fabricated `<rect>` -
+`orderedTargets()`'s `hasGeometry` flag is `true` only when
+`geometry.state` is `'available'` or `'partial'`.
+
+**Selection**: viewer presentation state only (React `useState`, reset on
+observation change), never persisted, synchronized in both directions
+between the target list, the SVG `<rect>` (`role="button"`, keyboard-
+operable), and the inspector via the target's existing stable `name`.
+
+**Overlay toggles**: geometry, labels (disabled when geometry is off), and
+relationships - each independently toggleable and purely presentational
+(hiding/showing already-rendered elements), never altering the underlying
+evidence or the fetched artifact/graph.
+
+**PWA cache boundary preserved**: the new `/api/observations/*` route lives
+under the same `/api/` prefix Batch 1's `navigateFallbackDenylist` already
+denylists - no service-worker configuration change was needed
+(`tests/unit/viewerPwaBuild.test.ts` asserts this against the real built
+`sw.js`).
+
+## v0.8 Batch 4 (Before/after comparison and contract/change-scope inspection) — implemented
+
+Batch 4 exposes the existing v0.4 `ComparisonArtifact` and v0.5
+`FrontendContractEvaluationArtifact` through the viewer, entirely under
+`src/viewerServer/evidence/{linkedEvidence,comparisonView,evaluationView}.ts`
+and `viewer/src/components/{ComparisonWorkspace,EvaluationWorkspace,
+ComparisonObservationPane,ClauseResultRow}.tsx`. **`compareObservations` and
+`evaluateFrontendContract` are never called anywhere in this batch** - every
+displayed comparison/evaluation field is read unchanged from its persisted
+artifact via the existing Batch 2 `GET /api/artifacts/<handle>`.
+
+- **Exact linked-evidence resolution** (`evidence/linkedEvidence.ts`): given
+  a `ComparisonSourceObservationReference`/`FrontendContractObservationReference`,
+  a `comparisonId`+`comparisonRequestId` pair, or a `baselineId`/`contractId`,
+  resolves the matching indexed artifact by **exact identity only**
+  (`observationId`+`requestId`+`producer.version`+`observationSchemaVersion`
+  for observations; the id fields themselves for comparisons/contracts) -
+  never by folder name, screenshot filename, URL, target-set, or geometry
+  similarity. Zero matches → `missing`; two or more exact matches →
+  `ambiguous` (never silently picks one). Mirrors the exact bounded-walk
+  pattern Batch 2's `findImportedReferenceDir` already established.
+- **Two additive, read-only routes**: `GET /api/comparisons/<handle>/view`
+  (resolves the comparison's `before`/`after`) and
+  `GET /api/evaluations/<handle>/view` (resolves `comparison`, `baseline`,
+  `change`, `before`, `after`) - both under `/api/`, both GET/HEAD-only, both
+  returning only resolved-handle-or-missing-or-ambiguous status, never a
+  duplicated copy of the linked artifact's own payload (the browser fetches
+  that separately through the existing `GET /api/artifacts/<handle>`, reusing
+  Batch 2's on-demand-loading contract exactly).
+- **Before/after visual reuse, not reimplementation**: `ComparisonObservationPane.tsx`
+  is built entirely from Batch 3's existing lower-level primitives
+  (`useArtifactDetail`, `orderedTargets`, `TargetOverlaySvg`) - no second
+  screenshot-loading, coordinate-transform, or geometry-rendering code
+  exists. The comparison's own persisted `relationshipsBefore`/
+  `relationshipsAfter` are passed directly into `TargetOverlaySvg`'s existing
+  `relationships` prop - never recomputed via `deriveLayoutRelationships`.
+  `TargetOverlaySvg` gained one small additive, optional `highlightNames`
+  prop (alongside the existing single-select `selected`) so a
+  relationship-subject difference or a two-target contract primitive
+  (`targets-do-not-overlap`, `target-fits-inside`, etc.) can emphasize both
+  named targets at once without changing Batch 3's existing single-select
+  interaction contract.
+- **Difference/relationship-change/clause presentation is evidence display,
+  not re-derivation**: `ComparisonWorkspace.tsx` renders `differences`,
+  `relationshipChanges`, `configurationChanges` (kept visually distinct from
+  appeared/disappeared runtime differences), and `expectedDependencyEvidence`
+  exactly as persisted, labeling dependency outcomes as explicit non-causal
+  evidence. `comparability` (comparable/comparable-with-warnings/incomparable
+  plus blocking/warning/unassessed reasons) is shown honestly; an
+  `incomparable` result is visually unmistakable
+  (`.comparability-banner--incomparable`).
+- **Clause joining by exact `clauseId` only** (`EvaluationWorkspace.tsx`):
+  baseline clauses (from the linked `PersistentBaselineContract`) and
+  per-change clauses (from the linked `PerChangeContract`) are joined to the
+  evaluation's `clauseResults` by exact id - never by target/primitive-shape/
+  category/position. A `clauseId` absent from both loaded contracts is shown
+  as an honest "unresolved clause definition", never fabricated. Baseline
+  clause active/superseded status comes exclusively from the evaluation
+  artifact's own `activeBaselineClauseIds`/`supersededBaselineClauseIds` -
+  never recomputed from clause overlap. `pass`/`fail`/`unavailable`/
+  `conflict` are preserved exactly (never collapsed to a boolean);
+  `unavailable` shows its reason, `conflict` shows its reason and
+  `conflictingClauseIds`.
+- **Overall verdict is authoritative and unmistakable**: `overallVerdict`
+  (`PASS`/`FAIL`) is rendered directly from the artifact, in a large
+  `.overall-verdict--PASS`/`.overall-verdict--FAIL` banner - the UI never
+  computes it from visible rows. The required safety case (a `requested`
+  clause `pass` alongside a `protected`/`preserved` clause `fail` still
+  producing overall `FAIL`) and the all-pass case are both proven against
+  real, canonically-evaluated fixtures (`tests/support/evidenceFixtures.ts#writeFullPipelineFixture`/
+  `writeAllPassPipelineFixture`) in real Chromium
+  (`tests/browser/comparisonEvaluationWorkspace.test.ts`) - `overallVerdict`
+  is never hand-edited to construct either demonstration.
+- **Target/relationship cross-highlighting uses only explicit canonical
+  identity**: `primitiveTargetNames()` (`viewer/src/contract/clauseTargets.ts`)
+  extracts a contract primitive's named target field(s) (`target`, `targetA`/
+  `targetB`, `target`+`container`, `subjectTarget`/`relatedTarget`) by an
+  exhaustive switch over `ContractPrimitiveKind` - page-level primitives
+  (`document-width-fits-viewport`, `scroll-owner-is-document`) return no
+  names, so clicking them never fabricates a target highlight.
+- **PWA cache boundary preserved**: both new routes live under `/api/`,
+  already covered by Batch 1's `navigateFallbackDenylist`; verified against
+  the real built `sw.js`.
+
+## v0.8 Batch 5 (External reference and reference/candidate inspection) — implemented
+
+- **Reference indexing/media already existed (Batch 2), unchanged**: the
+  `external-reference-imported`/`external-reference-approved` families,
+  `GET /api/media/<handle>/image` (imported), and
+  `GET /api/media/<handle>/source-image` (approved, resolved through
+  `findImportedReferenceDir`'s exact `referenceId` walk) were already built
+  in Batch 2 and required no change here - Batch 5 only adds the visual
+  workspace consuming them.
+- **Two new additive, read-only routes**
+  (`src/viewerServer/evidence/referenceView.ts`):
+  `GET /api/references/<handle>/view` derives the selected reference's own
+  region-relationship graph (`deriveReferenceRegionRelationships`) and
+  requirement adequacy (`deriveReferenceRequirementAdequacy`) - both pure
+  functions over the artifact's own persisted `regions`/`requirements`,
+  never persisted, never a second derivation engine (mirrors Batch 3's
+  `getObservationRelationships` server-side-derivation pattern).
+  `GET /api/references/<handle>/candidate/<handle>/view` evaluates
+  reference/candidate compatibility through the existing canonical
+  `evaluateReferenceCandidateCompatibility` (never a second, viewer-owned
+  compatibility model) and separately lists every existing
+  `FrontendContractEvaluationArtifact` whose own persisted `after` reference
+  exactly identifies the candidate, for explicit, never-auto-selected
+  optional display.
+- **Reference-image SVG coordinate model is a genuinely distinct domain from
+  the candidate's runtime SVG** (`ReferenceRegionOverlaySvg.tsx`): `viewBox`
+  is the reference image's own pixel dimensions (never the candidate's CSS
+  viewport, never devicePixelRatio-multiplied); each region's canonical
+  `{x, y, width, height}` is rendered unchanged. Because this is a different
+  coordinate domain and data source from `TargetOverlaySvg` (runtime CSS
+  pixels, `TargetGeometry`), it is a separate, sibling component rather than
+  a parameterization of the existing one - reuse would have silently
+  conflated the two domains. The candidate side, in contrast, reuses Batch
+  3/4's exact `ComparisonObservationPane`/`TargetOverlaySvg` machinery
+  unchanged (a synthetic `{status:'resolved', handle}` `LinkStatus` is
+  constructed once a candidate is explicitly chosen).
+- **Reference region selection and runtime target selection are two
+  independent, never-synchronized selection domains**
+  (`ReferenceWorkspace.tsx`): selecting a reference region never selects or
+  highlights a runtime target, even when both happen to share the same
+  string name (proven with a real Chromium fixture deliberately naming both
+  `"header"` - `tests/browser/referenceCandidateWorkspace.test.ts`, Case E).
+  No binding connector/highlight-across-panes exists in this batch - that is
+  Batch 6's explicit-binding-interaction scope.
+- **Compatibility vs. reference adequacy vs. candidate fidelity are kept
+  strictly distinct, never conflated**: compatibility
+  (`comparable`/`comparable-with-warnings`/`incomparable` plus
+  blocking/warning/unassessed reasons) comes only from
+  `evaluateReferenceCandidateCompatibility`; reference-side requirement
+  adequacy (`adequate`/`partial`/`inadequate`) comes only from
+  `deriveReferenceRequirementAdequacy`; candidate fidelity is never computed
+  in this batch at all - the UI always shows an explicit "not evaluated in
+  this batch" note rather than ever implying a fidelity PASS from a
+  compatibility PASS or an adequate reference (task §32/§33 boundary,
+  `evaluateReferenceCandidateFidelity` is never imported/called anywhere in
+  Batch 5).
+- **Optional contract/evaluation context is opt-in, never inferred**
+  (`ReferenceWorkspace.tsx`): when the reference/candidate view lists more
+  than one exactly-matching evaluation artifact, the developer must
+  explicitly pick one from a `<select>` - the newest/first match is never
+  silently chosen, and with zero selected the candidate's contract status
+  reads "not selected/not available", never a fabricated PASS.
+- **Imported vs. approved image ownership preserved exactly as Batch 2 built
+  it**: an imported reference's image is fetched from its own directory; an
+  approved reference's image is fetched from its exact imported source via
+  `sourceReference.referenceId`, never assumed co-located, never
+  duplicated - proven with a real Chromium fixture asserting the two
+  `<image href>` values resolve to the `image`/`source-image` roles
+  respectively (Cases A/B).
+- **PWA cache boundary preserved**: both new routes live under `/api/`,
+  already covered by Batch 1's `navigateFallbackDenylist`; verified against
+  the real built `sw.js` (no new `registerRoute`, no `/api/references`
+  precache entry).
+
+## v0.8 Batch 6 (Explicit-binding interaction, zoom/pan, conditional lock, and on-demand reference fidelity) — implemented
+
+- **`view --bindings-file <json-file>`**: reuses the exact same operational
+  binding-file wrapper parser (`loadBindingsFile` in `src/cli.ts`) that
+  `evaluate-reference-fidelity --bindings-file` already used - one shared
+  parser, never a second divergent one. The file is read once at startup;
+  its declarations become `ViewerServerState.bindingDeclarations` (an opaque
+  `unknown[]` until validated against a specific reference); the file path
+  itself is never persisted, returned, or exposed to the browser. Reference-
+  specific declaration validity (region existence, shape) is deferred to the
+  moment a reference is actually selected server-side, via the existing
+  canonical `isValidReferenceRuntimeBindingDeclarations` - never checked at
+  startup without a reference.
+- **Two new additive, read-only routes**
+  (`src/viewerServer/evidence/referenceView.ts`):
+  `GET /api/references/<handle>/candidate/<handle>/bindings` validates the
+  session's declarations against the selected reference and calls the
+  existing canonical `evaluateReferenceRuntimeBindings` exactly once.
+  `GET /api/references/<handle>/candidate/<handle>/fidelity` is the explicit
+  on-demand fidelity trigger - calls the existing canonical
+  `evaluateReferenceCandidateFidelity` exactly once, using the exact same
+  session declarations, so its embedded `bindings` field and the `/bindings`
+  route's own result always structurally agree for identical inputs (same
+  pure function, same arguments). Neither route persists anything; both are
+  `GET` (idempotent, deterministic, ephemeral over already-selected explicit
+  input) - no mutation route was added.
+- **`deriveCoordinateScale` exported additively** from
+  `externalReferenceFidelity.ts` (previously module-private) - Batch 6's
+  view-lock eligibility reuses this exact function unchanged (same formula,
+  same `ASPECT_RATIO_MAPPING_TOLERANCE`, same no-applicable-viewport
+  failure) rather than a second aspect-ratio/scale implementation. The
+  existing `GET /api/references/<handle>/candidate/<handle>/view` route now
+  additionally returns `coordinateMapping: DeriveCoordinateScaleResult` -
+  purely a function of the reference, independent of the candidate.
+- **Explicit-binding cross-selection uses only canonical
+  `ReferenceRuntimeBindingResult.referenceRegion`/`.runtimeTarget` fields**
+  (`ReferenceWorkspace.tsx`): selecting a `bound` reference region
+  highlights (via `TargetOverlaySvg`'s existing Batch 4 `highlightNames`
+  prop - never the primary `selected`/`aria-pressed` target) its exact
+  declared runtime target; selecting a runtime target highlights every
+  region whose `bound` result names it (many-to-one, via a new additive
+  `highlightRegionIds` prop on `ReferenceRegionOverlaySvg`, matching
+  `TargetOverlaySvg`'s established highlight pattern). `ambiguous`/
+  `unavailable` results never cross-select. Proven with a real equal-name
+  ("header" region + "header" target) Chromium fixture: no cross-selection
+  without an explicit declaration, real cross-selection with one.
+- **Zoom/pan is a repository-owned, presentation-only hook**
+  (`viewer/src/hooks/useZoomPan.ts`): bounded `[1x, 8x]` scale, `×1.25`/
+  `÷1.25` step, expressed as one `{scale, focalX, focalY}` triple in the
+  pane's own source-coordinate frame (reference-image pixels or candidate
+  CSS pixels - never rewritten). Renders via an SVG `viewBox` override
+  (additive `viewBoxOverride`/`svgRef`/pointer-handler props on
+  `TargetOverlaySvg`/`ReferenceRegionOverlaySvg`, defaulting to Batch 3/5's
+  exact prior behavior when omitted) - image and overlay stay one
+  transformed unit automatically since both live inside the same `<svg>`
+  root, and native SVG hit-testing means selection keeps working correctly
+  under zoom/pan with no extra coordinate math. Panning uses the SVG
+  element's own `getScreenCTM()` to convert screen-space pointer deltas into
+  source-space deltas - reuses the browser's native transform rather than a
+  custom aspect-ratio-aware pixel calculation - and only engages (calling
+  `setPointerCapture`) once the pointer has moved past a small threshold, so
+  an ordinary click on a region/target rect is never hijacked into a
+  phantom drag. Fit and Reset are the same fitted-1x/centered default (task
+  §26 - no second presentation-only default was introduced).
+- **View lock reuses one single shared state, never two independently
+  synchronized states**: `ReferenceWorkspace.tsx` owns `refZoom`/`candZoom`
+  directly (always-controlled `useZoomPan` calls) and each pane's zoom/pan
+  action handler updates both states in one synchronous call when locked -
+  no reactive effect watches one pane's state to update the other, so no
+  feedback-loop risk exists. Lock is available only when a candidate is
+  selected, compatibility is not `incomparable`, and `coordinateMapping.ok`
+  is `true`; any change to that eligibility (including selecting a
+  different reference/candidate) immediately disables lock and shows an
+  actionable reason. Synchronization converts a candidate CSS-pixel focal
+  point/scale into reference-image-pixel space (and back) using only
+  `coordinateMapping.scale.scaleX`/`scaleY` - the exact same canonical
+  factor `deriveCoordinateScale` already produces, applied as a straight
+  multiply/divide (its own algebraic inverse), never a second mapping rule.
+- **Contract/fidelity independence is never collapsed into one status**:
+  the existing Batch 5 "Optional contract/evaluation context" section
+  (unchanged) and the new on-demand `ReferenceFidelityPanel` are two
+  separate sections rendering two separate canonical results
+  (`FrontendContractEvaluationArtifact.overallVerdict` and
+  `ReferenceCandidateFidelityEvaluation.state`) side by side; when both are
+  present, an explicit note states that fidelity does not override an
+  active contract failure. No new coordinator/aggregate verdict is computed
+  anywhere in this batch.
+- **PWA cache boundary preserved**: both new routes live under `/api/`,
+  already covered by Batch 1's `navigateFallbackDenylist`.
+
+## v0.8 Batch 7 (Bounded agent context, correlation, provenance, and raw evidence navigation) — implemented
+
+- **Bounded agent context remains programmatic-only**: no filesystem writer
+  was added for `BoundedAgentContextArtifact` (it is still not an
+  Observer-evidence-root artifact family - `src/viewerServer/evidence/classify.ts`'s
+  "known but unreadered kind" comment is unchanged). `view --context-file
+  <json-file>` reads exactly one already-serialized
+  `BoundedAgentContextArtifact` value directly (no wrapper object) as
+  explicit, session-only viewer input - read once at startup
+  (`src/cli.ts#loadContextFile`, mirroring `loadBindingsFile`'s exact
+  read/size-bound/parse shape), classified by
+  `src/viewerServer/context.ts#classifyContextFileContent` (reuses the
+  existing canonical `isValidBoundedAgentContextArtifact` - never a second
+  validator), and held only in `ViewerServerState.context` for the life of
+  the process. The file's size is bounded by the existing Batch 2
+  `MAX_MANIFEST_CANDIDATE_BYTES` (2,000,000 bytes) rather than a second
+  bound, since a context artifact's own frozen numeric caps already make it
+  far smaller in any realistic case.
+- **Three honest session states, never coerced into one another**: `'none'`
+  (no `--context-file`; every Batch 1-6 feature stays fully available),
+  `'unsupported-version'` (recognized `artifactKind`, a `schemaVersion`
+  other than the current one - the viewer still starts, showing this
+  state explicitly rather than either failing or misinterpreting the
+  fields), and `'valid'` (structurally validated current-schema context).
+  Every other problem (unreadable file, wrong `artifactKind`, a
+  structurally invalid *current*-schema artifact) fails viewer startup
+  clearly - an explicitly supplied file is never silently ignored.
+- **`GET /api/context`** (`httpServer.ts`) returns the session's exact
+  classified state; for `'valid'`, it additionally returns
+  `sourceResolution` - the result of resolving
+  `artifact.sources` against the current evidence root by **exact
+  canonical identity only**
+  (`src/viewerServer/evidence/contextSourceView.ts`, reusing/extending
+  Batch 4's `linkedEvidence.ts` resolver pattern with three additive
+  functions: `resolveObservationById` (bare `observationId`, the only
+  identity a context source reference actually carries),
+  `resolveEvaluationByIdentity`, and `resolveReferenceByIdentity`). Zero
+  matches → `missing`; two or more → `ambiguous` (never silently picks
+  one) - the same discipline every other Batch 4/5 resolver already
+  established.
+- **Raw structured evidence reuses the existing Batch 2 artifact-detail
+  route unchanged**: `RawEvidenceViewer.tsx` calls the existing
+  `useArtifactDetail`/`GET /api/artifacts/<handle>` for any exactly-resolved
+  source - no second full-artifact retrieval mechanism, no local filesystem
+  read, no arbitrary path accepted from the browser.
+  `EvidenceReference.path` values are always displayed as plain provenance
+  text, never passed to `fs.readFile`/`path.resolve`/a static file server.
+- **Bounded runtime targets, adequacy, omissions, truncations, and
+  correlation are rendered exactly as the validated artifact states them** -
+  never recomputed, never boolean-collapsed
+  (`ContextWorkspace.tsx`): `Adequacy.state`
+  (`adequate`/`partial`/`inadequate`) and reasons are shown verbatim;
+  absent bounded-target fields render "not included in this bounded
+  context", never a fabricated falsy/zero value; `required: true`
+  omissions/truncations render in a visually distinct
+  `.context-required-loss` block, separate from optional ones;
+  `correlations` absent renders "Static correlation not included in this
+  context" - never "unavailable" (that status is reserved for a real
+  per-target `RuntimeStaticCorrelationRecord` with zero candidates).
+  `correlated`/`ambiguous`/`unavailable` are preserved exactly; a
+  `correlated` record's one candidate is labeled "Correlated candidate", an
+  `ambiguous` record shows **every** supplied candidate with none visually
+  promoted, and `unavailable` fabricates zero candidates - matching the
+  frozen `CORRELATION_STATUSES` invariants
+  (`domain/boundedAgentContext.ts`) the validator itself already enforces.
+  All new UI text was audited against ownership/edit-authorization language
+  (no "owner"/"source owner"/"owned by") - correlation is presented as
+  evidence, never as edit authorization.
+- **Context-target ↔ runtime-target interaction never infers source
+  ownership**: selecting a bounded target or a correlation record uses only
+  exact `targetId`/`runtimeTargetId` string matching; for each *exactly
+  resolved* source observation, `SourceObservationTargetCheck` checks
+  membership in that observation's own already-fetched `targetEvidence`
+  (a plain lookup over already-loaded JSON, never a new derivation) and, if
+  more than one resolved source observation contains the same target id,
+  lists all of them rather than picking one.
+- **Bounded reference-fidelity projection is never recomputed, and is kept
+  visibly distinct from a live on-demand evaluation**: absent `fidelity`
+  renders "Reference fidelity not included in this bounded context" - never
+  implied as passing. When present, `mismatches` and `protectedContext` are
+  rendered in separate sections from the artifact's own fields exactly as
+  supplied; a `state: 'not-evaluated'` blocked projection always shows
+  `blockedBy` prominently and never renders an empty mismatch list as "no
+  problems". When the context's `referenceId`/`candidateObservationId`
+  exactly resolve within the current evidence root, `ContextWorkspace.tsx`
+  embeds the existing, unchanged Batch 6 `ReferenceFidelityPanel` (the same
+  on-demand `evaluateReferenceCandidateFidelity` trigger) directly beneath
+  the bounded projection, labeled "Bounded context fidelity projection"
+  above and "Current on-demand fidelity evaluation" below - two separate,
+  clearly labeled evidence instances, never silently merged or replaced.
+- **No runtime rebuild of context or correlation, and no my-dev-kit
+  execution from the shipped viewer**: grep-verified - `projectBoundedAgentContext(`,
+  `deriveRuntimeStaticCorrelations(`, and `attachRuntimeStaticCorrelations(`
+  appear nowhere under `src/viewerServer/` or `viewer/src/` (only in test/
+  fixture-generation code, per the frozen plan's explicit test-fixture
+  exception); no `child_process`/`npx @dailephd/my-dev-kit` invocation
+  exists in the viewer server or browser bundle.
+- **PWA cache boundary preserved**: `GET /api/context` lives under `/api/`,
+  already covered by Batch 1's `navigateFallbackDenylist`.
+
+## v0.8 Batch 8 (Integrated viewer acceptance, PWA hardening, and packaged proof) — implemented
+
+Batch 8 is the final v0.8 implementation batch. It is integration/hardening,
+not a new architecture layer: no new API route, no new CLI flag, and no new
+canonical-engine call site were added. See
+`docs/reports/v0.8-integrated-viewer-acceptance-batch8.md` for the full
+record.
+
+- **Closed three named real-browser coverage gaps**, each proved against the
+  actual built viewer through the actual loopback server, never a hand-edited
+  fixture verdict: many reference regions bound to one runtime target all
+  cross-highlight together (the pre-existing target→regions loop in
+  `ReferenceWorkspace.tsx` already iterated every matching binding - the gap
+  was in real-browser proof, not in the derivation); reference-fidelity
+  `fail` alongside a genuine frontend-contract `PASS` for the same candidate
+  display independently (the pre-existing independence note in
+  `ReferenceWorkspace.tsx` was already verdict-agnostic); a bounded context
+  whose sources include two observations sharing a stable target id lists
+  every matching source observation (the pre-existing
+  `SourceObservationTargetCheck` in `ContextWorkspace.tsx` already checked
+  membership per source independently, never picking one).
+- **One real accessibility defect found and fixed**: a cross-highlighted,
+  non-selected region/target `<rect>` (`TargetOverlaySvg.tsx`,
+  `ReferenceRegionOverlaySvg.tsx`) exposed no accessible state distinguishing
+  it from a plain unselected rect - `aria-pressed` correctly stayed `false`
+  (it is not the primary single-selection), but nothing else communicated
+  the highlight to assistive technology. Fixed by adding
+  `data-highlighted="true"` and an `aria-label` suffix
+  (`" (highlighted: related to current selection)"`) when highlighted and
+  not selected, leaving `aria-pressed` semantics untouched.
+- **First live-browser PWA proof suite** (`tests/browser/pwaHardening.test.ts`):
+  real service-worker registration and activation against the built shell;
+  the manifest fetched and confirmed `display: "standalone"`; zero Cache
+  Storage entries under any `/api/` pathname after normal use, confirming
+  the `navigateFallbackDenylist` boundary holds live, not just in the built
+  `sw.js` regex; and the hard server-down gate - after the server is closed
+  and the same page reloaded, the app shell still renders from the precache,
+  but the evidence-dependent surface shows the explicit
+  `.evidence-list__error` "Evidence index unavailable" state, with the
+  previously-visible evidence asserted absent. Install-control is proven
+  only via synthetic `beforeinstallprompt` dispatch (a genuine browser
+  install prompt was not observed under automation). Standalone-mode CDP
+  display-mode emulation was attempted but not observed to take effect -
+  recorded honestly, never overstated as actual OS-level installation proof.
+- **Packaged-candidate proof**: `npm pack` → clean consumer install (outside
+  the repository) → the actually-installed CLI executable (not repo
+  `dist/cli.js`) → the installed `view` server → real Chromium against the
+  packaged/installed server, not a source-checkout dev server. Read-only
+  evidence-hash proof (SHA-256 of every file in the exercised evidence root,
+  taken before and after the packaged-browser session) confirmed no
+  mutation and no new viewer-created artifact anywhere in the evidence root.
+- **Re-confirmed the no-second-engine invariant** across all eight batches by
+  re-running the exact `grep -rn` audit from earlier batches - unchanged
+  findings, no duplicate evidence engine exists.
+
+## v0.9 visual annotation architecture (released in 0.9.0)
+
+v0.9 is released as package version `0.9.0`. It adds one new
+evidence family and a narrow local authoring path to the existing viewer. It
+adds no new evaluator, no second contract or reference model, and no new
+PASS/FAIL semantics.
+
+**Evidence ownership**:
+
+- `src/domain/visualAnnotation.ts` owns `VisualAnnotationArtifact` (artifact
+  kind `my-frontend-observer/visual-annotation`, schema `1.0.0`): the source
+  union, structured marks, explicit associations, candidate/confirmed
+  interpretation, validation, and the pure overlay SVG renderer.
+- `src/domain/visualAnnotationIdentity.ts` owns deterministic request identity
+  and fresh instance identity.
+- `src/artifacts/visualAnnotationArtifactWriter.ts` and
+  `visualAnnotationArtifactReader.ts` own atomic persistence (temporary
+  `.tmp-<id>` directory, then rename) and canonical reading, including the
+  derived `annotation-overlay.svg` and its digest.
+- `src/application/visualAnnotationPersistenceService.ts` owns saving one
+  annotation or one superseding revision.
+
+**Coordinate domains**: runtime annotations use the observation's runtime CSS
+pixel space. Reference annotations use the reference image's own pixel space
+(for an approved reference, the owning imported image). The two domains are
+never mixed. Zoomed or panned drawing is mapped back through the SVG's own
+transform (`viewer/src/svg/sourceCoordinates.ts`).
+
+**Viewer discovery and media** (`src/viewerServer/evidence/`): the index
+classifies `visual-annotation` evidence and skips writer `.tmp-*`
+directories. `annotationView.ts` resolves an annotation's exact canonical
+source and reports `unavailable` instead of guessing a replacement. The media
+resolver serves the `annotation-overlay` role only after re-rendering the SVG
+from the artifact and verifying it, with a script-blocking sandbox policy.
+
+**Project-aware authoring security**: `src/viewerServer/authoringSecurity.ts`
+owns the in-memory 32-byte session capability and the Host, Origin, token,
+content-type, and content-encoding checks. `httpServer.ts` owns the shared
+bounded JSON gate and routes exactly three `POST` responsibilities.
+`view --root` never creates an authoring session, so the standalone
+arbitrary-root viewer stays read-only.
+
+1. `POST /api/annotations` (`src/viewerServer/annotationAuthoring.ts`) saves
+   a new annotation or a revision through the canonical persistence service,
+   with stale-parent conflict detection. This module also owns the single
+   per-session write queue used by all three routes.
+2. `POST /api/annotations/:handle/promote-contract`
+   (`src/viewerServer/annotationContractPromotion.ts`) calls
+   `src/application/visualAnnotationContractPromotionService.ts`. Selected
+   confirmed runtime intent becomes one canonical `PerChangeContract` through
+   the existing contract persistence service. Optional activation goes only
+   through `activateProjectChangeContract` in
+   `src/application/projectWorkflowService.ts`.
+3. `POST /api/annotations/:handle/materialize-reference`
+   (`src/viewerServer/annotationReferenceMaterialization.ts`) calls
+   `src/application/visualAnnotationReferenceMaterializationService.ts`.
+   Selected confirmed reference intent becomes a new imported
+   `ExternalReferenceArtifact` through the existing `importExternalReference`,
+   superseding the source. The image bytes come only from the safe media
+   resolver.
+
+Output locations come from `src/projectWorkflow/projectPaths.ts`
+(`annotations`, `contracts`, and `references` under
+`.frontend-observer/evidence`). The browser never supplies a path.
+
+**Viewer UI** (`viewer/src/`): `annotation/` holds pure presentation models
+(`annotationGeometry.ts`, `runtimeIntent.ts`, `referenceIntent.ts`,
+`confirmation.ts`). `components/AnnotationLayer.tsx`,
+`AnnotationToolbar.tsx`, `RuntimeAnnotationPanel.tsx`,
+`ReferenceAnnotationPanel.tsx`, `CandidateRegionPreviewLayer.tsx`, and
+`AnnotationPanelSections.tsx` render marks, tools, intent, promotion, and
+materialization. Hooks under `hooks/` hold draft, saved-list, session,
+pointer, promotion, and materialization state. The authoring token lives only
+in React memory.
+
+**Existing evaluators remain authoritative**: the canonical contract
+evaluator, reference relationship derivation, requirement adequacy, reference
+fidelity, and project `check` are unchanged. Annotation evidence feeds them
+only through promoted contracts and materialized references.
+
+## Retained v0.1 architecture constraints
+
+v0.1 planning preserved these approved boundaries without treating module
+names from the historical run as mandatory:
+
+```text
+thin command-line boundary
+        ↓
+reusable observation engine/application layer
+        ↓
+browser automation boundary
+        ↓
+observer-owned runtime evidence
+
+observer-owned domain/schema
+        ↓
+artifact ownership boundary
+
+deterministic fixture/test boundary
+        ↓
+browser-level validation
+```
+
+Use one browser engine implementation, keep browser logic out of presentation,
+avoid speculative plugin/multi-browser abstractions, and keep observed
+applications external. Versions before v0.6 did not add runtime coupling to
+sibling ecosystem projects. v0.6 adds only explicit bounded context and
+correlation/export contracts within this repository, preserving independent
+ownership; orchestrator-consumption and lab-compatibility work are separate
+sibling-repository deliverables, not part of this repository's architecture.
+
+The text/config-driven coding-agent workflow and the non-UI external-reference
+evidence foundation are operational as of v0.7. The viewer and annotation
+layers must consume the same canonical observation, relationship, comparison,
+contract, change-scope, reference, correlation, and context boundaries rather
+than creating parallel engines. The concrete implementation plan and module
+layout for each future version must be designed only after that version's
+planning workflow inspects the current repositories.
+
+v0.7 Prompt 1 implements only the bottom of that external-reference stack: a
+new, standalone `ExternalReferenceArtifact` evidence root
+(`src/domain/externalReference.ts`, `externalReferenceImage.ts`,
+`externalReferenceIdentity.ts`, `src/artifacts/externalReferenceArtifact{Writer,Reader}.ts`,
+`src/application/externalReferencePersistenceService.ts`) with its own
+identity, provenance, bounded image metadata, and a two-state
+(`imported`/`approved`) lifecycle - see `docs/CONTRACTS.md` "v0.7 Prompt 1
+external-reference artifact contract" for the exact shape. It follows the
+same identity/persistence/diagnostics/export conventions as every existing
+artifact family (deterministic canonicalize-then-sha256 request identity,
+nonce-based fresh instance identity, atomic temp-dir-then-rename persistence,
+the shared `DIAGNOSTIC_CODES` vocabulary) without reusing or duplicating the
+observation, comparison, or contract engines themselves - an external
+reference is desired-design evidence, never an `ObservationArtifact`, an
+approved baseline, or a runtime target.
+
+v0.7 Prompt 2 adds explicit reference regions and reusable reference-region
+relationships on top of that foundation (`domain/externalReferenceRegions.ts`,
+`externalReferenceRegionRelationships.ts`) - see `docs/CONTRACTS.md` "v0.7
+Prompt 2 explicit reference regions and relationships" for the exact shape.
+The relationship-derivation predicates are reused verbatim (now exported
+additively) from `domain/relationships.ts` rather than reimplemented, so
+reference-region geometry and runtime-target geometry can never diverge on
+the same underlying formula; only the geometry-only relationship families
+apply, since a static image exposes no DOM, scroll, or viewport evidence.
+v0.7 Prompt 3 adds selected design requirements, tolerance semantics, and
+reference-evidence adequacy on top of that region model
+(`domain/externalReferenceRequirements.ts`,
+`externalReferenceRequirementIdentity.ts`) - see `docs/CONTRACTS.md` "v0.7
+Prompt 3 selected design requirements, tolerance semantics, and
+reference-evidence adequacy" for the exact shape. Requirement categories are
+the exact v0.5 `AuthoredChangeScopeCategory` vocabulary, imported directly
+rather than reinvented, since that type carries no runtime-only coupling of
+its own; tolerance is a genuinely new, reference-owned type (never a reuse
+of `frontendContracts.ts`'s runtime/CSS-pixel-implicit `ContractTolerance`);
+and reference-evidence adequacy is a small, independently-owned vocabulary
+distinct from `boundedAgentContext.ts`'s runtime/static-correlation
+`Adequacy`. A region property or derived relationship is never promoted to
+an executable requirement automatically - only explicit user/configuration
+selection does that.
+
+v0.7 Prompt 4 adds explicit reference applicability
+(`domain/externalReferenceApplicability.ts`) and observation-side explicit
+state identity (`domain/explicitState.ts`, shared by both artifact
+families), plus one new pure domain module,
+`domain/externalReferenceCompatibility.ts`, that evaluates whether a
+candidate `ObservationArtifact` describes the same frontend state as a
+given `ExternalReferenceArtifact` - see `docs/CONTRACTS.md` "v0.7 Prompt 4
+reference applicability and candidate-state compatibility" for the exact
+shape. This is page/state-level only, never geometry or fidelity, and
+remains a wholly separate concern from Prompt 3's reference-evidence
+adequacy - the two can independently disagree (an adequate reference can be
+incomparable against a given candidate, and vice versa). Rather than
+inventing a second comparability engine, Prompt 4 extracts one new exported
+pure helper from v0.4's own `domain/comparisonEngine.ts`
+(`assessOptionalComparabilityDimension`) and reuses it from both v0.4's
+`evaluateComparability` (Observation-vs-Observation) and the new
+`evaluateReferenceCandidateCompatibility` (Reference-vs-Observation) - the
+one additive behavior change to v0.4 itself is that `evaluateComparability`
+now assesses (rather than always reporting unassessed) theme/authenticated-
+state/application-state whenever both observations declare
+`requestConfig.explicitState`, while every historical/legacy observation
+pair retains the exact prior unassessed-only behavior. No new persisted
+artifact kind is introduced for the compatibility result; it is a pure,
+on-demand function of two already-persisted artifacts.
+
+v0.7 Prompt 5 adds explicit reference-region <-> runtime-target binding
+(`domain/externalReferenceRuntimeBinding.ts`) - see `docs/CONTRACTS.md`
+"v0.7 Prompt 5 explicit reference-region <-> runtime-target binding" for
+the exact shape. It answers only "which stable v0.2 runtime target does
+this candidate observation resolve for each explicitly declared reference
+region", strictly downstream of Prompt 4's compatibility gate (reused
+verbatim, never duplicated) and strictly upstream of v0.6's own
+runtime/static correlation - the two identity domains (a Prompt 2
+`ReferenceRegion.id` and a v0.2 `NamedTarget.name`) never collapse into
+each other, and this stage stops at the runtime target, never reaching
+source ownership. Following v0.6's uncertainty discipline
+(`domain/boundedAgentContextCorrelation.ts`), binding never guesses through
+ambiguity - an ambiguously or unavailably resolved v0.2 target is reported
+as such, never silently treated as bound - though the actual per-status
+mapping (`bound`/`ambiguous`/`unavailable`) is binding's own, independently
+owned vocabulary, not a reuse of v0.6's `correlated`/`ambiguous`/
+`unavailable` correlation-status semantics (a different evidence boundary:
+correlation ranks *static candidates* for one runtime target, whereas
+binding resolves *one runtime target's own existence* for one declared
+correspondence). No second target resolver, no browser execution, and no
+new persisted artifact family were introduced; neither
+`ExternalReferenceArtifact` nor `ObservationArtifact` is mutated to carry a
+binding result, since a reference may later be evaluated against several
+candidates and an observation against several references.
+
+v0.7 Prompt 6 adds structured reference-vs-candidate fidelity evaluation
+(`domain/externalReferenceFidelity.ts`, `application/referenceFidelityEvaluationService.ts`,
+and the `evaluate-reference-fidelity` CLI command) - the first point in this
+stack where a reference's authored expectation is compared against live
+candidate evidence. See `docs/CONTRACTS.md` "v0.7 Prompt 6 structured
+reference-vs-candidate fidelity evaluation" for the exact shape. It is
+downstream of every prior v0.7 prompt and reuses each verbatim: Prompt 3's
+`deriveReferenceRequirementAdequacy`/`deriveReferenceRequirementExpectation`/
+`deriveReferenceRequirementMeasurement` (never redefined), Prompt 4's
+`evaluateReferenceCandidateCompatibility` (a hard gate, never duplicated),
+and Prompt 5's `evaluateReferenceRuntimeBindings` (the sole source of
+runtime-target identity - no automatic binding, no second target resolver).
+It also reuses v0.4's `deriveLayoutRelationships` for runtime relationship
+evidence, scoped to the exact requested relationship family (the same
+Prompt 3 bug-fix precedent). The one genuinely new problem this prompt
+solves is the reference-image-pixel <-> CSS-pixel coordinate mapping: a
+single explicit, deterministic full-frame scale derived from
+`reference.applicability.viewport` and the reference image's own
+dimensions, with a tiny independent aspect-ratio-coherence check (never a
+design tolerance) gating whether that mapping exists at all. No new
+persisted artifact family, no browser execution, and no source-ownership
+attribution - this is reference fidelity only, a separate concern from any
+later v0.5 baseline/per-change contract result or v0.7 overall verdict.
+
+v0.7 Prompt 7 adds bounded reference-fidelity projection into the existing
+v0.6 bounded-agent-context architecture (`domain/referenceFidelityProjection.ts`,
+plus additive extensions to `domain/boundedAgentContext.ts`,
+`domain/boundedAgentContextIdentity.ts`, and
+`domain/boundedAgentContextProjection.ts`) - see `docs/CONTRACTS.md` "v0.7
+Prompt 7 bounded reference-fidelity projection and v0.6 bounded-agent-
+context integration" for the exact shape. `projectBoundedAgentContext`
+itself, not a new parallel context system, gains one new optional input (an
+already-computed Prompt 6 fidelity evaluation): fidelity-relevant runtime
+targets fold into the exact same required/permitted-target-allocation,
+evidence-tiering, omission/truncation, and adequacy machinery v0.5 contract
+clauses already compete in, and a new `fidelity?:
+BoundedReferenceFidelityProjection` field on `BoundedAgentContextArtifact`
+(mirroring `correlations?`'s own additive, non-version-bumping precedent
+from v0.6 Batch 3) carries a bounded, priority-ordered selection of Prompt
+6's non-passing requirement results plus passing protected/preserved
+context. No second bounded-context architecture, no recomputation of Prompt
+2-6/v0.4/v0.5 logic, and no change to v0.6's own runtime/static correlation
+(`deriveRuntimeStaticCorrelations`/`attachRuntimeStaticCorrelations` are
+untouched and reused exactly as before) - a caller joins fidelity, target,
+and correlation evidence by the one stable v0.2 runtime target id all three
+already share. Every new field is optional and additive; a pre-Prompt-7
+caller supplying no fidelity evidence receives byte-identical output,
+including logical identity.
+
+v0.7 Prompt 8 adds the first complete, controlled end-to-end external-
+reference correction workflow (`domain/referenceCorrectionWorkflow.ts`,
+`domain/referenceCorrectionIdentity.ts`) - see `docs/CONTRACTS.md` "v0.7
+Prompt 8 controlled end-to-end external-reference coding-agent correction
+workflow" for the exact shape. This is a narrowly-scoped coordinator, not a
+second workflow engine: it exposes exactly two pure operations -
+`prepareReferenceCorrection` (pre-change evidence -> a bounded coding-agent
+handoff, built from Prompt 1/3/4/5/6/7's existing engines) and
+`reviewReferenceCorrectionAttempt` (a fresh post-edit candidate -> one
+composed overall result, built from v0.4's `compareObservations`, v0.7
+Prompt 6's `evaluateReferenceCandidateFidelity`, and v0.5's
+`evaluateFrontendContract`) - with an explicit, un-automatable seam between
+them where an external implementation actor edits target source. Overall
+`'pass'` requires both reference fidelity `'pass'` and v0.5 contract
+evaluation `'PASS'` - matching the selected design reference is necessary
+but never sufficient, so a candidate that visually satisfies the reference
+while regressing an active protected or preserved contract clause still
+resolves to overall `'fail'`. Review identity is a deterministic hash of
+`{referenceRequestId, baselineObservationId, baselineContractId,
+baselineContractClauses, changeContractId, changeContractClauses,
+bindingDeclarations}`; attempt identity is a deterministic hash of
+`{reviewRequestId, candidateObservationId}`. `reviewReferenceCorrectionAttempt`
+rejects any call whose supplied `reviewRequestId` does not match what its own
+baseline/contract/reference/binding inputs recompute - the mechanism that
+makes "every attempt evaluates against the same approved baseline" an
+enforced invariant, not just a documented one. No new persisted artifact
+family, no CLI surface, and - most importantly - no code path anywhere in
+this module (or anything it calls) that opens, parses, or writes a target
+source file: real candidate capture remains the caller's own responsibility
+through the existing, unmodified real-Chromium observation pipeline.