@dailephd/my-frontend-observer 0.9.1 → 0.10.1

package/docs/CONTRACTS.md

@@ -1,1926 +1,1971 @@
-# Contracts
-
-## Current contracts
-
-The observation artifact contract is published in the current
-`my-frontend-observer@0.7.0` package and proven both from the source checkout
-and from the packed npm tarball, on Windows, Linux, and macOS. The observation
-schema is `1.2.0` (see "v0.2 target contract" and "v0.3 scroll scenario
-contract" below):
-
-- artifact kind `my-frontend-observer/observation`, schema version `1.2.0`
-  (independent of the package version);
-- one artifact root per observation, `<outputLocation>/<observationId>/`,
-  containing exactly `manifest.json` (the full `ObservationArtifact`, with
-  page/target evidence embedded inline) and `screenshot.png` - there is no
-  separate `evidence.json`;
-- `manifest.json` is written last, after `screenshot.png`, via one atomic
-  directory rename, so a consumer never observes a partially-written
-  artifact; a filesystem failure anywhere in that sequence reports the
-  `artifact-write-failure` diagnostic and leaves no completed artifact;
-- internal artifact references (e.g. `screenshot.png`) are relative to the
-  artifact root, never an absolute machine path; the observation's logical
-  identity is its `observationId`, not its filesystem location;
-- evidence states `available`, `unavailable`, `not-applicable`, `partial`;
-  evidence sources `browser`, `computed-browser`, `derived`;
-- a stable diagnostic vocabulary (`src/domain/diagnostics.ts`) and completion
-  states `complete`, `partial`, `warning`, `invalid-request`, `fatal`
-  (`src/domain/completion.ts`);
-- observation/request identity, producer/package identity, and browser
-  provenance are all present in every persisted manifest.
-
-This contract is implemented and published; no public programmatic-API
-compatibility promise has been made for the observation engine itself. v0.6
-additionally publishes the bounded-agent-context/correlation programmatic surface
-described later in this document.
-
-## v0.2 target contract (shipped as part of this release)
-
-v0.2 introduces a canonical target-configuration model: each configured target has a stable
-observer-level `name` plus an ordered array of bounded `locators`
-(`role`, `id`, `data-attribute`, `semantic-element`, `css`, `text`). This
-identity is distinct from both the browser locator definition that resolves
-it and any source-code identity. The legacy `{name, selector}` shape remains
-accepted and normalizes to a one-item `css` locator, so every published
-`0.1.0` CLI invocation continues to work unchanged. Locator precedence is the
-configured array order; resolution stops on the first unique match, on any
-ambiguous match (never falling through to a later locator), or on an
-unevaluable locator - never silently. All six frozen locator kinds are now
-resolved against a real Chromium page (`role` via Playwright's accessibility-
-role/name locator with exact name matching, `id`/`data-attribute` via exact
-CSS attribute-equals matching that never reinterprets the configured value as
-selector syntax, `semantic-element` via the frozen tag set, `css` via the
-existing v0.1 behavior, `text` via exact-text matching only); every kind
-converges on the same measurement path, so locator strategy never changes the
-resulting target evidence shape.
-
-Each resolved target's evidence record additionally carries three bounded
-fields: `semanticState` (a first family of `disabled`/`expanded`/
-`checked`/`selected`/`pressed`/`current` values read from the element's own
-native form-control properties and explicit `aria-*` attributes - a key is
-present only when the browser exposes that state as applicable to this
-element, so an explicit `false` is always distinguishable from "not
-applicable"; `not-applicable` when no supported state applies at all);
-`landmark` (derived only from the already-captured browser-exposed
-role - never from locator kind or HTML tag - against the standard landmark
-role set `banner`/`navigation`/`main`/`complementary`/`contentinfo`/`form`/
-`region`/`search`); and `containment` (bounded DOM containment checked only
-among the other explicitly configured targets in the same observation, in
-configured order, never a layout/relationship graph - `available` when every
-other configured target was itself resolved and checked, `partial` when one
-or more could not be, `unavailable` when the target itself never resolved).
-Stable observer target identity is proven, not just declared: the same
-target configuration produces the same `requestId` across repeated
-observations (with a fresh `observationId` each time); changing a target's
-locator strategy while keeping its stable name changes `requestId` but not
-the `targetEvidence` key; and actual runtime disappearance of a
-still-configured target changes only its resolution status, never the
-`requestId`.
-
-The full canonical semantic target model above is reachable through the
-real public CLI: `my-frontend-observer observe --targets-file <json-file>`
-supplies the structured `{ "targets": [...] }` collection (see
-`docs/COMMANDS.md` "Structured semantic targets") as an alternative to the
-existing `--target id=css-selector` shorthand - the two are mutually
-exclusive per invocation, and both converge on the same
-`normalizeRequest()`/browser-resolver/artifact path, so a semantic
-observation produces exactly the same `manifest.json` shape as a
-CSS-shorthand one. Schema `1.1.0` was the v0.2 published artifact schema;
-schema `1.2.0` has been emitted since v0.3 and remains the observation schema
-in the current published v0.7.0 package, for both target-input modes
-(target semantics are unchanged from v0.2 - see the v0.3 scroll scenario
-contract below for what schema `1.2.0` actually adds). `--targets-file`'s
-local input path is never part of the persisted request identity or
-artifact.
-
-## v0.3 scroll scenario contract (shipped as part of this release)
-
-v0.3 introduces one optional, additive request/evidence concern: a bounded
-runtime scroll scenario, schema `1.2.0`.
-
-A normalized request may carry `scrollScenario: { action }` with exactly one
-of two frozen action kinds:
-
-- `{ "kind": "window-scroll-by", "deltaX": <int>, "deltaY": <int> }`
-- `{ "kind": "target-scroll-by", "target": "<stable target name>", "deltaX": <int>, "deltaY": <int> }`
-
-`deltaX`/`deltaY` are signed integers bounded to `[-20000, 20000]`; at least
-one must be non-zero. `target-scroll-by.target` refers only to an existing
-stable configured target `name` (never a selector) and resolves through the
-same canonical `resolveConfiguredTargets` algorithm every v0.2 locator kind
-already uses - there is no second target-resolution path. A request with no
-scenario normalizes and identifies exactly as it did before v0.3.
-
-Execution (both action kinds share one code path): perform the immediate,
-non-smooth scroll (`window.scrollBy`/`element.scrollBy`, `behavior:
-'instant'`) on the already-navigated, already-ready page; wait exactly two
-`requestAnimationFrame` cycles; capture a final runtime snapshot. No second
-browser, page, or navigation is ever created. The resulting scroll position
-is browser-authoritative and may be clamped by document/element boundaries;
-a scenario producing no movement is still a valid, successfully persisted
-observation.
-
-The scenario evidence lives entirely inside the existing `manifest.json` as
-one additional optional `scrollScenarioEvidence` field on `ObservationArtifact`
-- there is no separate `scroll.json`/`scenario.json`. It contains:
-
-- `initial`/`final`: bounded `ScrollRuntimeSnapshot`s (window `scrollX`/
-  `scrollY`; the browser's own scrolling-root/`documentElement`/`body`
-  metrics; per-configured-target `scrollTop`/`scrollLeft`/`scrollWidth`/
-  `scrollHeight`/`clientWidth`/`clientHeight`, actual overflow, bounding
-  rectangle, and viewport relation);
-- `transition`: bounded before/after change evidence (window scroll deltas;
-  per-target `scrollTop`/`scrollLeft`/bounding-position/viewport-relation
-  changes; `enteredViewport`/`leftViewport`) - never a generic recursive
-  diff, and a target is simply omitted when either side's evidence isn't
-  itself usable (e.g. it never resolved);
-- `scrollOwner`: one derived `EvidenceField<ScrollOwnerInterpretation>`
-  (`document` | `target:<stable-name>` | `none` | `indeterminate`), always
-  `source: "derived"` with non-empty `derivedFrom` naming the exact
-  contributing scroll-position measurements. Ownership is derived only from
-  observed `scrollTop`/`scrollLeft`/`window.scrollX`/`window.scrollY`
-  changes - never from bounding-rectangle movement (which moves for every
-  configured target whenever the document scrolls), computed overflow,
-  `position: fixed`/`sticky`, or DOM hierarchy.
-
-Actual dimensional overflow (`scrollWidth > clientWidth` /
-`scrollHeight > clientHeight`) is always reported separately from the
-computed `overflow-x`/`overflow-y` CSS declaration; a declared
-`overflow: auto` container with content that fits produces
-`horizontalOverflow`/`verticalOverflow: false`. Viewport relation
-(`above`/`intersecting`/`below`, `intersectsViewport`, `fullyWithinViewport`)
-is derived only from bounding geometry plus viewport size, relative to the
-browser viewport; a hidden/non-rendered target's viewport relation is
-`not-applicable`, never a fabricated geometry claim - hidden and offscreen
-remain distinct evidence concepts, and the existing `target-hidden`
-diagnostic is unaffected.
-
-The ordinary, already-existing `pageEvidence`/`targetEvidence`/
-`screenshot.png` for a scenario observation always describe this same final
-post-action state, never the pre-action state.
-
-The scenario request participates in `requestId`; the runtime result
-(actual scroll distance, clamping, or scroll-owner outcome) never does. The
-public entry point is `my-frontend-observer observe --scroll-scenario-file
-<json-file>` (see `docs/COMMANDS.md`); the file supplies the scenario value
-directly, and its local path is operational input only, exactly like
-`--targets-file`'s path - never persisted, never part of request identity.
-
-## v0.4 comparison contract (shipped as part of this release)
-
-**Current status: shipped as part of the published `my-frontend-observer@0.4.0`
-package and unchanged through the current `0.7.0` release.** Observation
-schema remains `1.2.0`. Comparison is a distinct artifact kind and schema,
-never a bump to the observation schema:
-
-- artifact kind: `my-frontend-observer/comparison`;
-- comparison schema: `1.0.0`.
-
-**Geometry tolerance**: `ComparisonConfig.geometryTolerancePx`, default
-`0.5` CSS px, bounded `[0, 10]`. Suppresses insignificant subpixel noise
-only - never a design contract, never permission for a change.
-
-**Layout relationship graph**: `deriveLayoutRelationships(observation,
-options?)` derives, per observation, a bounded `LayoutRelationshipGraph`
-among configured targets only (≤20 targets, ≤190 unordered pairs):
-horizontal order (`left-of`/`right-of`/`horizontally-overlapping`),
-vertical order (`above`/`below`/`vertically-overlapping`), area overlap
-(`overlaps`/`does-not-overlap`), relative width (`wider-than`/
-`narrower-than`/`equal-width-within-tolerance`), geometric fit
-(`fits-inside`/`does-not-fit-inside` - geometry-only, deliberately distinct
-from DOM containment), vertical sequencing (`follows-vertically`), and one
-page-level relationship (`document-width-fits-viewport`/
-`document-width-exceeds-viewport`). Every relationship carries explicit
-evidence-path provenance back to the source observation. A configured
-target lacking usable geometry is listed as honestly unresolved
-(`not-found`/`ambiguous`/`unavailable`/`hidden`), never fabricated as a
-zero-sized region.
-
-**Comparability**: evaluated before any rendered difference, using exactly
-three states (`comparable`/`comparable-with-warnings`/`incomparable`) with
-structured reasons, never a bare boolean. Hard incompatibilities (page URL,
-viewport, browser engine, scroll-scenario configuration mismatch) force
-`incomparable`; producer-version, browser-version, and target-configuration
-differences are warning-only; theme/authenticated-state/application-state
-identity are recorded as `unassessed` dimensions the observer does not yet
-model - never silently claimed identical. An `incomparable` result still
-persists a structurally valid `ComparisonArtifact` with empty rendered
-differences, not a fabricated comparison.
-
-**Difference categories**: `appeared`/`disappeared` (only for a stable
-target name configured on both sides, transitioning between a definite
-`not-found` and `matched` resolution status - never for a target merely
-added/removed from configuration, which is its own separate
-`configurationChanges` entry), `moved`/`resized` (tolerance-aware, a target
-may be both), `visibility-changed`, `clipping-changed` (reusing the
-canonical `deriveTargetClipping` helper, never re-derived), `horizontal-
-overflow-changed`/`vertical-overflow-changed` (actual dimensional overflow,
-reusing the existing `deriveOverflowEvidence` helper - never inferred from
-a CSS declaration alone), `containment-changed` (reusing existing v0.2
-`TargetContainment` evidence), `page-size-changed`, `scroll-owner-changed`
-(comparing `scrollScenarioEvidence.scrollOwner` only when scenario
-*configuration* already matched), `relative-position-changed` (a relation
-in the horizontal-order/vertical-order/area-overlap families changed - kept
-distinct from plain absolute target movement) and `relationship-changed`
-(every other relationship-family transition). Relationship changes are
-matched by structural identity (family + subject/related target, or the
-page-level key), never by array position.
-
-**Explicit dependency evidence**: `ComparisonConfig.expectedDependencies`
-lets a caller declare an expected relationship between two targets' numeric
-properties (`x`/`y`/`width`/`height`) and directions (`increase`/
-`decrease`/`change`/`unchanged`), always carrying `source:
-"explicit-config"`. The observer never synthesizes a declaration from
-observed co-change. Each declaration evaluates independently to exactly one
-of `consistent`/`not-observed`/`contradictory-to-declaration`/
-`unavailable` - never a causal claim (no `causedBy`/`causalConfidence`/
-`causalScore`/`dependencyStrength`) and never a PASS/FAIL/approval verdict.
-That distinction (evidence vs. contract verdict) is the boundary between
-v0.4 and v0.5+.
-
-**Comparison identity**: `comparisonRequestId` is a pure, deterministic
-function of `{beforeObservationId, afterObservationId, normalized
-ComparisonConfig}` - direction-sensitive (`compare(A, B) !==
-compare(B, A)`), and never includes an operational filesystem path.
-`comparisonId` is fresh per execution (same pattern as `observationId`).
-
-**Source references**: the comparison artifact retains enough logical
-identity to trace back to its authoritative source observations
-(`observationId`, `requestId`, `producer`, `observationSchemaVersion`, and
-the source `screenshot.path`) without embedding the full
-`ObservationArtifact` or copying screenshot bytes. The persisted comparison
-directory contains `manifest.json` only.
-
-The public entry point is `my-frontend-observer compare --before <root>
---after <root> --output <directory> [--config-file <json-file>]` (see
-`docs/COMMANDS.md`) - comparison itself never launches a browser.
-
-## v0.5 frontend contract and evaluation (shipped as part of this release)
-
-Downstream of the v0.4 observation/comparison/relationship evidence above,
-`src/domain/frontendContracts.ts` freezes the v0.5 contract/change-scope
-model, `src/domain/frontendContractIdentity.ts` freezes deterministic
-contract/baseline/clause identity, and `src/domain/frontendContractEvaluation.ts`
-implements the one canonical pure evaluation engine. Baseline/per-change
-contract persistence, evaluation-artifact persistence, explicit baseline
-approval, and public CLI exposure are all implemented and shipped (see
-"v0.5 contract and evaluation persistence" and "v0.5 public contract/
-evaluation commands" below).
-
-**Contract classes**: a `PersistentBaselineContract` (append/supersession-based
-history via an optional `supersedesBaselineId`) and a `PerChangeContract`
-(the allowed scope of one requested change). Both share `artifactKind:
-"my-frontend-observer/frontend-contract"` and `schemaVersion: "1.0.0"` - an
-independent family from the observation (`1.2.0`) and comparison (`1.0.0`)
-schemas; the frontend-contract schema constant happens to share the version
-string `1.0.0` with comparison's by coincidence only.
-
-**Four authored categories, one derived classification**: every per-change
-clause is authored as exactly one of `requested`, `expected-dependent`,
-`protected`, or `preserved`. `unexpected` is a fifth, *derived-only*
-classification the evaluator produces for a meaningful rendered difference no
-active clause accounts for - it can never be authored as a permission.
-
-**Bounded contract primitives**: 15 frozen `ContractPrimitive` kinds cover
-visibility, clipping, width bounds, non-overlap, relative width, vertical
-sequence, geometric fit (explicitly distinct from DOM containment),
-document-width-vs-viewport, scroll ownership, initial-viewport position,
-relationship-unchanged, and property-unchanged/increases/decreases - a closed
-vocabulary, never a generic expression language.
-
-**Contract tolerance**: `exact` / `absolute-px` / `percent`, independent of
-`ComparisonConfig.geometryTolerancePx` (which only suppresses insignificant
-comparison noise and is never contract authorization). Percent tolerance's
-denominator is the absolute before-value.
-
-**Required vs. permitted expected-dependent**: `required` clauses must occur
-compliantly to pass; `permitted` clauses accept no change or a compliant
-change, and fail only on a strictly contradictory change.
-
-**Evaluation result vocabulary**: each clause resolves to `pass` / `fail` /
-`unavailable` (with a required non-empty reason - required evidence gaps and
-an `incomparable` source comparison never fabricate a `pass`) / `conflict`
-(with at least two `conflictingClauseIds` - covers both an unresolved
-baseline/per-change contradiction and an unknown `supersedesBaselineClauseIds`
-reference). The overall verdict is `PASS` only when every clause result is
-`pass` and no unexpected change remains; otherwise `FAIL` - there is no
-partial-pass scoring.
-
-**Explicit supersession, never inferred**: a per-change clause may list
-`supersedesBaselineClauseIds` to remove specific baseline clauses from active
-evaluation. Two clauses that structurally contradict each other on the same
-(target, property) without explicit supersession produce a `conflict`, never
-a silent preference for one side.
-
-**Reuses existing v0.4 evidence directly**: the evaluator consumes an
-already-computed `ComparisonArtifact` (`differences`, `relationshipChanges`,
-`relationshipsBefore`/`relationshipsAfter`, `comparability`) and the source
-`ObservationArtifact` pair - it never re-launches a browser, re-resolves a
-target, or reimplements clipping/relationship/scroll-owner derivation.
-Unexpected-change derivation reads `ComparisonArtifact.differences` only
-(which already includes one difference per relationship change), so a single
-logical transition is never double-counted.
-
-## v0.5 contract and evaluation persistence (shipped as part of this release)
-
-Persistence consumes the frozen v0.5 domain above; it never redefines it.
-`src/artifacts/frontendContractArtifactWriter.ts`/`frontendContractArtifactReader.ts`
-persist and read both `PersistentBaselineContract` and `PerChangeContract`
-symmetrically (both already share `CONTRACT_ARTIFACT_KIND`/`CONTRACT_SCHEMA_VERSION`,
-so one writer/reader pair serves both contract classes) as
-`<outputLocation>/<baselineId|contractId>/manifest.json`, following the same
-atomic-write discipline as `artifacts/artifactWriter.ts`/`artifacts/comparisonArtifactWriter.ts`
-(sibling temporary directory, then one atomic rename; an existing directory at
-the final identity is a genuine collision and is rejected, never overwritten -
-prior baseline history is never rewritten). `src/artifacts/comparisonArtifactReader.ts`
-is a new Batch 3 addition (no comparison reader existed before) mirroring
-`artifacts/artifactReader.ts`'s discipline exactly, changing no comparison
-semantics and keeping comparison schema `1.0.0`.
-
-**Evaluation artifact envelope**: Batch 1 froze the evaluation-result
-vocabulary (`ClauseEvaluationResult`, `OverallVerdict`) but not a persistable
-envelope, so `src/domain/frontendContractEvaluationArtifact.ts` adds exactly
-that - `artifactKind: "my-frontend-observer/frontend-contract-evaluation"`,
-`schemaVersion: "1.0.0"` (its own independent family, distinct from
-observation/comparison/frontend-contract), an `evaluationId`/`evaluationRequestId`
-pair, bounded `before`/`after` source-observation references, and
-`comparisonId`/`comparisonRequestId` plus `contracts: {baselineId,
-contractId}` references - never an embedded `ObservationArtifact` or copied
-screenshot. It reuses `ClauseEvaluationResult`/`OverallVerdict`/
-`UnexpectedChangeResult` unchanged and contains no evaluation logic itself.
-`evaluationRequestId` is a deterministic function of `{baselineId,
-contractId, beforeObservationId, afterObservationId, comparisonRequestId}`
-(`frontendContractIdentity.ts#buildFrontendContractEvaluationRequestIdentity` -
-deliberately `comparisonRequestId`, not the fresh-per-execution
-`comparisonId`, so semantically identical evaluations share an identity);
-`evaluationId` reuses the existing generic `buildFrontendContractInstanceIdentity`
-unchanged. `src/artifacts/frontendContractEvaluationArtifactWriter.ts`/
-`frontendContractEvaluationArtifactReader.ts` persist/read it with the same
-atomic-write discipline as above.
-
-**Application seam**: `src/application/frontendContractEvaluationService.ts#evaluateAndPersist`
-calls the existing pure `evaluateFrontendContract` exactly once and - only
-for a structurally constructible result, whether the verdict is `PASS` or
-`FAIL` - persists exactly one evaluation artifact; an `{ok: false}` evaluator
-result (evidence could not be constructed into an evaluation at all) is never
-persisted as a fabricated artifact. `evaluateAndPersistFromArtifactRoots` is
-the future-CLI-facing wrapper: it reads two observations through the existing
-`readObservationArtifact` (never a second observation reader), the
-comparison and the two contracts through the readers above, then delegates
-to `evaluateAndPersist` exactly once.
-
-## v0.5 public contract/evaluation commands (shipped as part of this release)
-
-Three public commands expose the persistence/evaluation contract above (see
-`docs/COMMANDS.md` for exact flags/output/exit behavior, not duplicated
-here):
-
-- `approve-baseline` → `frontendContractPersistenceService.ts#approveAndPersistBaseline`
-  → validates a `PersistentBaselineContract` and its `sourceObservation`
-  coherence against a supplied observation artifact → persists via
-  `frontendContractArtifactWriter.ts`. The only baseline-approval act in the
-  observer.
-- `save-change-contract` → `frontendContractPersistenceService.ts#persistPerChangeContract`
-  → validates a `PerChangeContract` (rejecting a baseline contract, an
-  authored `unexpected` category, or any other structural violation) →
-  persists via the same writer. Persistence only, never approval.
-- `evaluate-contract` → `frontendContractEvaluationService.ts#evaluateAndPersistFromArtifactRoots`
-  → `evaluateFrontendContract` exactly once → `frontendContractEvaluationArtifactWriter.ts`
-  exactly once. `--enforce` affects only the process exit status for an
-  already-persisted `FAIL` verdict.
-
-No command infers baseline approval or supersession automatically - not
-`compare`, not a `PASS` evaluation, not any artifact writer.
-
-This full command sequence is proven against real Chromium observations (not
-hand-constructed artifacts) - see "v0.5 real-browser workflow proof" below.
-
-## v0.5 real-browser workflow proof (shipped as part of this release)
-
-`tests/browser/cliFrontendContracts.test.ts` and
-`scripts/dev/builtCliFrontendContractsBrowserSmoke.mjs` drive the complete
-`observe` → `approve-baseline` → `save-change-contract` → `observe` →
-`compare` → `evaluate-contract` sequence against a real disposable local HTTP
-fixture and real Chromium, proving two scenarios:
-
-- a fully successful contract change - a real observed navigation-width
-  decrease and workspace-width increase, both satisfying their authored
-  `requested`/`expected-dependent` clauses, an unchanged `protected` rail
-  width, and an unclipped `preserved` navigation - overall `PASS`;
-- the "milestone signature" failure - the same locally successful requested
-  change (navigation shrinks, workspace expands, both still `pass`)
-  co-occurring with a genuine `protected` right-rail width regression (a real
-  `resized` comparison difference) and a genuine `preserved` navigation
-  clipping regression (a real `clipping-changed` difference, `not-clipped` →
-  `clipped`) - overall `FAIL`.
-
-Both scenarios confirm: `--enforce` changes only the process exit status
-(`0` without it, nonzero with it) for the identical persisted
-`evaluationRequestId`/`clauseResults`; every source observation and
-comparison artifact is byte-identical before and after evaluation; the
-evaluation directory contains `manifest.json` only (no copied screenshot);
-and no operational filesystem path is ever serialized into a persisted
-manifest. This is real-browser evidence layered on top of the CLI-level
-proof in `tests/unit/cliFrontendContracts.test.ts` and the Chromium-free
-`scripts/dev/builtCliFrontendContractsSmoke.mjs` - it does not replace them.
-
-## v0.6 bounded agent context and correlation contract (released as `0.6.0`)
-
-**Current status: released as package version `0.6.0`, tag `v0.6.0`, from
-the canonical `canonicalization/v0.6` lineage.** Bounded-agent-context is a new, independent
-artifact-kind family, schema `1.0.0` (`BOUNDED_AGENT_CONTEXT_ARTIFACT_KIND =
-"my-frontend-observer/bounded-agent-context"`) - never a bump to
-observation/comparison/frontend-contract/evaluation schemas, which remain
-`1.2.0`/`1.0.0`/`1.0.0`/`1.0.0` respectively. Unlike those families, there is
-**no disk artifact writer/reader** for bounded-agent-context: it is a pure
-programmatic contract and derivation layer, exported from `src/index.ts`
-only.
-
-**Bounded runtime projection**
-(`src/domain/boundedAgentContextProjection.ts#projectBoundedAgentContext`)
-produces a `BoundedRuntimeTargetProjection` from already-captured v0.1-v0.5
-evidence, containing: page/viewport identity; stable target identities;
-important geometry and runtime behavior; layout/behavior relationships;
-before/after differences; contract clause results; requested/expected-
-dependent/protected/preserved scope - reusing `src/domain/
-frontendContracts.ts`'s existing clause types verbatim, never a
-reimplementation; diagnostics; screenshot/artifact references; provenance;
-and explicit `OmissionRecord`/`TruncationRecord` metadata with bounded
-aggregate-cap summarization once a limit is reached.
-
-**Adequacy**: every projection carries an `Adequacy` value
-(`adequate`/`partial`/`inadequate`) plus a structured, closed
-`ADEQUACY_REASON_CODES` vocabulary - evidence existing is not itself
-adequacy; a required omission or an `incomparable`/unavailable upstream
-source is reflected honestly rather than silently reported as sufficient.
-
-**Runtime/static correlation**
-(`src/domain/boundedAgentContextCorrelation.ts#deriveRuntimeStaticCorrelations`/
-`attachRuntimeStaticCorrelations`) evaluates each stable runtime target
-against caller-supplied candidate static-evidence records into exactly one of
-three outcomes: `correlated`, `ambiguous` (multiple competing candidates,
-all preserved and visible - never silently resolved to one), or
-`unavailable` (no supported candidate). The module accepts only plain,
-already-retrieved candidate records and has no dependency on
-`@dailephd/my-dev-kit` - the audit preceding implementation found no generic
-static-side retrieval capability actually missing (see `docs/ROADMAP.md` v0.6
-"Dependency direction"). A runtime target identity is carried through
-verbatim; correlation never produces a `sourceOwner`/`causedBy`-shaped field,
-so a stable runtime identity is never silently reported as source ownership.
-
-**Identity**: `src/domain/boundedAgentContextIdentity.ts#buildBoundedAgentContextRequestIdentity`/
-`buildBoundedAgentContextInstanceIdentity` follow the same
-canonicalize+sha256(+opaque-nonce) pattern as `comparisonIdentity.ts`/
-`frontendContractIdentity.ts`: a deterministic logical identity distinct from
-a fresh per-execution instance identity.
-
-**Export/public boundary**: `src/index.ts` exports the complete
-bounded-agent-context/correlation type and function surface as a
-programmatic library contract. There is no CLI command (`observe`/`compare`/
-`approve-baseline`/`save-change-contract`/`evaluate-contract` remain the only
-public commands) and no orchestrator/lab code in this repository - bounded
-runtime-evidence consumption by `my-dev-kit-orchestrator` and exact
-readers/fixtures/evaluation in `my-dev-kit-lab` are separate sibling-
-repository deliverables outside `my-frontend-observer`'s public surface.
-
-**Compatibility evidence**: cross-repository neutral verification (observer
-`514bf3bb513764815a0a5b9e508d5836aa7d7fd8`, orchestrator `9473e4c`, lab
-`271e72c`) passed with 6/6 requirement coverage and no known product
-blockers; on the canonical worktree, `npm run typecheck`, `npm run lint`,
-`npm test` (627 tests), `npm run test:browser` (120 tests), `npm run
-test:security`, `npm run build`, and `npm run check:docs` all pass.
-
-## v0.7 external visual-reference contract direction (released as `0.7.0`; v0.8 viewer released as `0.8.0`; v0.9 released as `0.9.0`; v0.10 still future)
-
-External visual-reference support is released as package version `0.7.0`
-(see "v0.7 Prompt 1" through "v0.7 Prompt 8" below for the exact contract).
-The exact public type names, artifact kinds, schema versions, persistence
-layout, and command/programmatic entry points were designed during v0.7
-implementation from current repository precedent, following the constraints
-below. v0.8 (released as package version `0.8.0` - see
-`docs/CURRENT_STATE.md`) has preserved them. v0.9 (implemented, not yet
-released) preserves them too. v0.10 remains future and must continue to
-preserve them.
-
-**Distinct evidence domain**: an external reference is desired-design evidence,
-not an `ObservationArtifact` and not the "before" side of a v0.4
-`ComparisonArtifact`. Reference design vs candidate is distinct from both
-before vs after comparison and frontend-contract evaluation. The implementation
-must not fake this distinction by wrapping a raster image in an observation
-shape.
-
-**Reference identity and provenance**: a future reference contract must preserve
-a deterministic logical reference identity/version where appropriate, source
-image reference plus dimensions/format, provenance, bounded region definitions,
-applicable viewport/theme/application-state identity, authored design intent,
-relationship/style evidence where supported, limits/diagnostics, and approval/
-supersession history. Operational filesystem paths must not become semantic
-identity. A raw imported image never silently becomes an approved active
-reference.
-
-**Reference regions and runtime targets stay distinct**: a reference region
-must have its own identity and coordinate semantics. Reference-region to runtime-
-target association must be explicit and capable of representing ambiguity or
-unavailability. Runtime target identity and reference identity must never
-silently become static source ownership; static association still goes through
-the v0.6 runtime/static correlation boundary.
-
-**Applicability before fidelity**: viewport, theme, application state, and
-other selected compatibility dimensions must be evaluated before ordinary
-reference/candidate differences are produced. If the reference and candidate
-represent different intended states, the result must be explicitly incompatible
-or incomparable rather than filled with fabricated visual failures. Planning
-should reuse or extend the canonical v0.4 comparability conventions where they
-mean the same thing rather than invent an unrelated reference-only state model.
-
-**Canonical contract semantics remain authoritative**: executable reference-
-derived requirements must map into the existing v0.5 authored categories
-`requested`, `expected-dependent`, `protected`, or `preserved`. The derived-only
-`unexpected` classification remains derived-only. Informational or unassessed
-reference evidence may stay outside executable contract evaluation until
-explicitly promoted. A second reference-only PASS/FAIL taxonomy is forbidden.
-
-**Tolerance separation**: reference-fidelity tolerances are not automatically
-the same as v0.4 `ComparisonConfig.geometryTolerancePx` or v0.5 contract
-tolerances. Planning must define property-specific semantics for reference
-geometry, spacing, selected style evidence, text/font rendering differences,
-asset-sensitive regions, and optional image similarity. One global pixel-perfect
-threshold is not an acceptable contract.
-
-**Structured evidence first**: geometry, relationships, authored requirements,
-applicability, provenance, and selected bounded style/asset evidence remain
-inspectable primary evidence. Screenshot-region or image-similarity evidence may
-supplement them where reliable, but pixel similarity alone must not determine
-success and must never override active baseline/per-change contracts.
-
-**Bounded correction evidence**: future reference/candidate results must support
-a bounded projection suitable for coding-agent correction, such as reference
-measurement, candidate measurement, delta, failed relationship/style condition,
-relevant reference/runtime identities, provenance, and active protected/
-preserved constraints. Heavy reference image bytes should be referenced, not
-copied into every downstream context packet.
-
-**Approval and supersession**: reference import, reference approval, baseline
-approval, reference supersession, and baseline supersession are separate acts.
-A reference-fidelity `PASS`, a frontend-contract `PASS`, or a successful
-before/after comparison must not silently approve or replace any reference or
-baseline.
-
-The v0.8 viewer, released as package version `0.8.0`, consumes this v0.7
-reference/evaluation contract exactly as required - it creates no UI-only
-reference model (see `docs/ARCHITECTURE.md` "v0.8 Batch 5"/"v0.8 Batch 6"
-and `docs/reports/v0.8-reference-candidate-inspection-batch5.md`). v0.9
-annotations (released in `0.9.0`) originate from runtime
-screenshots or external references, preserve which source identity and
-coordinate system they belong to, and feed the same canonical contract and
-reference semantics - see "v0.9 visual annotation contract" below. v0.10
-combines both entry modes into the full correction/approval workflow.
-
-## v0.9 visual annotation contract (released in 0.9.0)
-
-v0.9 is released as `@dailephd/my-frontend-observer@0.9.0`.
-
-**Artifact**: `VisualAnnotationArtifact`, artifact kind
-`my-frontend-observer/visual-annotation`, schema version `1.0.0`. It stores one
-exact canonical source (a runtime observation, or an imported or approved
-external reference), the source coordinate space (runtime CSS pixels or
-reference-image pixels), and bounded structured items. Each item has a stable
-`annotationItemId`, one mark (point, rectangle, line, arrow, or note), an
-optional explicit association, and an interpretation. A revision sets
-`supersedesAnnotationId` and never rewrites its parent. The overlay SVG is
-derived from the artifact and verified before it is served.
-
-**An annotation is not a contract.** Saving an annotation never creates a
-contract clause, a reference requirement, or a PASS/FAIL rule. Marks and
-visible pixels are evidence. Overlap between a mark and a target or region is
-not ownership and never creates an association.
-
-**Interpretation states**: `uninterpreted`, `candidate`, and `confirmed`.
-Confirmation is explicit and records `confirmedAt`. Editing the mark,
-association, or intent of a confirmed item withdraws the confirmation.
-
-**Runtime intent to contract**:
-
-- Only selected, confirmed, supported runtime intent is promoted. Promotion
-  creates one normal canonical `PerChangeContract` through the existing
-  contract persistence service.
-- Supported mappings use the existing `ContractPrimitive` vocabulary only.
-  `move` maps to `property-increases`/`property-decreases` on `x` or `y`.
-  `resize` maps to `property-increases`/`property-decreases` on `width` or
-  `height`. `preserve` maps to `property-unchanged-within-tolerance` for a
-  target property, or to `relationship-unchanged` for an explicitly associated
-  canonical relationship.
-- Categories are the canonical `requested`, `expected-dependent` (with a
-  required `required` or `permitted` mode), `protected`, and `preserved`.
-  `unexpected` is never authored; it stays evaluator-derived.
-- `remove` can be confirmed and saved, but it is not promotable in v0.9. The
-  contract vocabulary has no target-absent primitive, and no approximate
-  clause is fabricated.
-- `inspect` intent and notes are informational and never promoted.
-- Each clause's `supportingEvidence` records the annotation source and item
-  paths. Promotion never activates the contract unless explicitly requested,
-  and it never approves a baseline.
-
-**Reference intent to a new reference revision**:
-
-- Only selected, confirmed `reference-region` (`create` or `refine`) and
-  `reference-requirement` items are materialized. `inspect` and
-  `asset-sensitive` intent stay informational.
-- The result is a new imported `ExternalReferenceArtifact`, created through the
-  existing canonical import service. It supersedes the selected source
-  reference (the approved reference id when the source is approved) and has
-  lifecycle `imported`. It is never approved automatically.
-- Source regions keep their order. A refine replaces the rectangle of an
-  existing source region and keeps its id. Creates are appended in selection
-  order. Duplicate creates, duplicate refines, and create-then-refine in one
-  request are rejected.
-- Source requirements stay first with identical recomputed ids. Selected
-  requirements are appended in selection order and validated against the final
-  regions. A selected relationship requirement must still hold for the final
-  geometry. Measurement requirements store only the subject and tolerance.
-- Applicability, label, and the exact source image bytes are preserved. The
-  source reference is never modified, and project reference acceptance is not
-  changed.
-
-Existing contract, reference relationship, adequacy, and fidelity evaluators
-remain the only source of verdicts. v0.9 adds no annotation evaluator.
-
-## Approved v0.1 design inputs
-
-The historical greenfield scaffold plan recorded these v0.1 design decisions:
-
-- artifact kind `my-frontend-observer/observation`;
-- schema version `1.0.0`, independent of package version;
-- one portable directory containing `manifest.json`, `evidence.json`, and
-  `screenshot.png`;
-- evidence states `available`, `unavailable`, `not-applicable`, and `partial`;
-- evidence sources `browser`, `computed-browser`, and `derived`;
-- bounded explicitly requested targets, provenance, diagnostics, completion
-  state, limits, and relative artifact references.
-
-These were planning inputs only at the time they were recorded. As shown in
-"Current contracts" above, the implemented contract matches them except for
-the file layout: there is no separate `evidence.json` - page/target evidence
-is embedded directly inside `manifest.json`.
-
-Comparison and relationship contracts belong to v0.4, and canonical
-change-scope contracts belong to v0.5 - see "v0.5 frontend contract and
-evaluation" above for the full shipped contract model, identity, evaluation
-engine, persistence, baseline approval, and CLI exposure. Bounded
-agent-context and runtime/static correlation contracts are v0.6 - see "v0.6
-bounded agent context and correlation contract" above for the full released
-model. The text/config-driven coding-agent review plus non-graphical external
-visual-reference foundation is v0.7 - see "v0.7 Prompt 1 external-reference
-artifact contract" below for the foundation layer implemented so far. Viewer
-consumption of that reference model is released in v0.8 (see "v0.7 external
-visual-reference contract direction" above); dual-context annotation follows
-in v0.9; both visual entry modes converge with the existing workflow in
-v0.10.
-
-## v0.7 Prompt 1 external-reference artifact contract
-
-Released as `0.7.0`. This is the foundation layer only: identity,
-provenance, bounded image metadata, and a two-state lifecycle for one
-externally supplied design-reference image. It implements no region,
-geometry, relationship, requirement, tolerance, binding, or fidelity-
-evaluation contract - those belong to later v0.7 prompts.
-
-An external reference is a distinct evidence root, not a variant of
-`ObservationArtifact`: it never reuses `ARTIFACT_KIND`/`SCHEMA_VERSION`
-(observation), `COMPARISON_ARTIFACT_KIND`, or `CONTRACT_ARTIFACT_KIND`, and
-those existing types gain no new field from this contract.
-
-```ts
-const EXTERNAL_REFERENCE_ARTIFACT_KIND = 'my-frontend-observer/external-reference';
-const EXTERNAL_REFERENCE_SCHEMA_VERSION = '1.0.0'; // independent of package.json version and every other family's schema version
-
-type ExternalReferenceImageFormat = 'png' | 'jpeg' | 'webp';
-
-interface ExternalReferenceImageReference {
-  path: string; // bare relative filename within the artifact's own directory
-  format: ExternalReferenceImageFormat;
-  width: number;
-  height: number;
-  byteLength: number;
-  sha256: string; // identity-bearing content hash of the raw image bytes
-}
-
-// Points back to the imported artifact that owns the image, without copying its bytes - mirrors ComparisonSourceObservationReference.
-interface ExternalReferenceSourceReference {
-  referenceId: string;
-  referenceRequestId: string;
-  producer: { name: 'my-frontend-observer'; version: string };
-  schemaVersion: '1.0.0';
-  image: ExternalReferenceImageReference;
-}
-
-// Exactly two persisted states - no literal 'superseded' variant (see below).
-type ExternalReferenceLifecycleState = { state: 'imported' } | { state: 'approved'; approvedAt: string };
-
-interface ExternalReferenceArtifactBase {
-  artifactKind: 'my-frontend-observer/external-reference';
-  schemaVersion: '1.0.0';
-  referenceRequestId: string; // deterministic logical identity - shared by an imported artifact and every artifact produced by approving it
-  referenceId: string; // fresh per-persisted-instance identity
-  producer: { name: 'my-frontend-observer'; version: string };
-  provenance: { importedAt: string; label?: string };
-  supersedesReferenceId?: string; // explicit, forward-only supersession of a prior reference's referenceId
-  diagnostics: Diagnostic[];
-  completion: CompletionState;
-}
-
-// lifecycle.state === 'imported': owns the image.
-interface ImportedExternalReferenceArtifact extends ExternalReferenceArtifactBase {
-  lifecycle: { state: 'imported' };
-  image: ExternalReferenceImageReference;
-}
-
-// lifecycle.state === 'approved': references, never copies, the imported artifact's image.
-interface ApprovedExternalReferenceArtifact extends ExternalReferenceArtifactBase {
-  lifecycle: { state: 'approved'; approvedAt: string };
-  sourceReference: ExternalReferenceSourceReference;
-}
-
-type ExternalReferenceArtifact = ImportedExternalReferenceArtifact | ApprovedExternalReferenceArtifact;
-```
-
-Key rules:
-
-- `referenceRequestId` is a pure function of `{imageSha256, format, width,
-  height, supersedesReferenceId}` only - never a filesystem path, output
-  location, label, or timestamp. Byte-identical image content imported from a
-  different operational root produces the same `referenceRequestId`;
-  changing any of those fields changes it.
-- `referenceId` is fresh (nonce-based) on every persisted write, including
-  every approval of an already-imported reference.
-- Importing an image never approves it (`lifecycle.state` is always
-  `'imported'` immediately after import, regardless of a supplied label or
-  supersession target). Approval is a single explicit act
-  (`approveExternalReference`, mirroring `approveAndPersistBaseline`) that
-  refuses anything not currently in the `'imported'` state.
-- Approving persists a *new* artifact instance (same `referenceRequestId`,
-  fresh `referenceId`) carrying a `sourceReference` back to the imported
-  artifact - it never mutates the imported artifact's own manifest, and never
-  copies the image bytes a second time.
-- Supersession is represented only as a forward pointer
-  (`supersedesReferenceId` on the newer artifact); there is deliberately no
-  literal `'superseded'` lifecycle state, so an existing persisted artifact's
-  own manifest is never rewritten - immutability holds unconditionally rather
-  than depending on careful mutation discipline.
-- Supported formats are frozen to exactly `png`/`jpeg`/`webp`, detected from
-  header/magic bytes only (never a caller-declared file extension), bounded
-  to `EXTERNAL_REFERENCE_MAX_IMAGE_BYTES` (20,000,000 bytes) and
-  `[EXTERNAL_REFERENCE_MIN_DIMENSION_PX, EXTERNAL_REFERENCE_MAX_DIMENSION_PX]`
-  (`[1, 8192]`) pixels per side. No OCR, no raster decode, no computer
-  vision, no automatic region detection.
-
-Persisted as `<outputLocation>/<referenceId>/manifest.json` (+
-`reference.<ext>` for an `'imported'` artifact only), via the same atomic
-temp-dir-then-rename discipline as every other artifact family
-(`src/artifacts/externalReferenceArtifactWriter.ts` /
-`externalReferenceArtifactReader.ts`). CLI: `import-reference <image-file>
---output <dir> [--label] [--supersedes <root>]` and `approve-reference
---reference <root> --output <dir> [--supersedes <root>]`.
-
-## v0.7 Prompt 2 explicit reference regions and relationships
-
-Released as `0.7.0`. Additive extension of the Prompt 1 contract above:
-one new, optional `regions?: ReferenceRegion[]` field on
-`ExternalReferenceArtifact` (both lifecycle variants), plus a pure,
-non-persisted relationship-derivation capability. No schema version bump -
-`EXTERNAL_REFERENCE_SCHEMA_VERSION` remains `'1.0.0'`, because the field is
-genuinely optional/additive and every Prompt 1 artifact (which predates this
-field entirely) remains valid without it.
-
-```ts
-// domain/externalReferenceRegions.ts
-interface ReferenceRegionRectangle { x: number; y: number; width: number; height: number; }
-interface ReferenceRegion { id: string; rectangle: ReferenceRegionRectangle; }
-
-// Pure derived geometry - never persisted, always recomputed, so it can never drift from the rectangle above.
-interface ReferenceRegionGeometry {
-  x: number; y: number; width: number; height: number;
-  right: number; bottom: number; centerX: number; centerY: number;
-}
-
-const REFERENCE_REGION_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/; // same convention as request/request.ts's target-name pattern
-const MAX_REFERENCE_REGIONS = 20; // same bound value as request/request.ts's MAX_TARGETS - independently owned, coincidentally equal
-```
-
-Region coordinate semantics: origin at the reference image's top-left
-corner, x increasing rightward, y increasing downward, unit is
-reference-image pixels (explicitly not CSS pixels - a static image has no
-CSS box model), coordinates may be fractional. A region's rectangle must lie
-entirely within its owning image's own already-validated
-width/height - out-of-bounds geometry is rejected outright, never clamped.
-
-Key rules:
-
-- Only `{x, y, width, height}` is canonical/authored. `right`, `bottom`,
-  `centerX`, `centerY` are pure calculations over it
-  (`deriveReferenceRegionGeometry`) - never a second, potentially-drifting
-  stored copy of the same fact.
-- Region content is identity-bearing:
-  `buildExternalReferenceRequestIdentity` gained an additive, optional
-  trailing `regions` parameter. Omitting it entirely (every Prompt 1 call
-  site, and any Prompt 2 call that legitimately has no regions) produces the
-  byte-identical hash Prompt 1 already produced - the parameter is left out
-  of the hashed view rather than defaulted to `null`, unlike
-  `supersedesReferenceId`. Authored region order participates in identity
-  (arrays are never reordered by the shared `canonicalize()`), mirroring
-  `domain/identity.ts`'s treatment of configured targets.
-- Region IDs are unique case-insensitively within one artifact (mirroring
-  `request/request.ts`'s target-name dedup convention exactly).
-- `import-reference` gained an optional `--regions-file <json-file>` of the
-  form `{ "regions": [...] }` (same object-root-wrapper convention as
-  `--targets-file`); a legacy invocation without it behaves exactly as in
-  Prompt 1. `approve-reference` carries an imported artifact's `regions`
-  forward verbatim (never re-validated, never re-derived, never dropped) -
-  approval never adds, removes, or edits regions.
-- One new diagnostic code, `invalid-reference-region` (error), covers every
-  region-validation failure (missing/duplicate/malformed id,
-  non-finite/negative/zero geometry, out-of-image-bounds, over the bounded
-  region count) - deliberately not split into several codes, per the
-  "don't proliferate diagnostics" convention.
-
-Reference-region relationships (`domain/externalReferenceRegionRelationships.ts`)
-reuse the exact same pure, tolerance-aware geometry predicates that
-`domain/relationships.ts#deriveLayoutRelationships` uses for runtime targets
-(`horizontalOrderOf`/`verticalOrderOf`/`areaOverlapOf`/`relativeWidthOf`/
-`geometricFitOf`/`verticalSequenceOf`, now exported additively from that
-module with unchanged formulas) and the same `PairwiseRelationshipKind`
-vocabulary and `EvidenceReference` type - never a duplicated or
-reinterpreted copy. Only the six geometry-only families apply (horizontal
-order, vertical order, area overlap, relative width, geometric fit, vertical
-sequencing); DOM containment, scroll ownership, runtime visibility, and
-page-width-vs-viewport are runtime/browser concepts with no reference-image
-equivalent and are not reused. `fits-inside`/`does-not-fit-inside` is
-geometry-only fit - it never claims DOM containment, which an external image
-cannot expose.
-
-```ts
-interface ReferenceRegionRelationship {
-  kind: PairwiseRelationshipKind;
-  subjectRegion: string;   // deliberately distinct field name from PairwiseLayoutRelationship's subjectTarget
-  relatedRegion: string;
-  evidence: EvidenceReference[]; // e.g. { path: 'regions.header.rectangle' } - never a targetEvidence/browser path
-}
-```
-
-Relationships are **not persisted** on the artifact - `deriveReferenceRegionRelationships(referenceRequestId, regions, options)`
-is a pure, deterministic, synchronous function any caller (a future prompt,
-a test) calls on demand against an artifact's own `regions` field, avoiding
-any possibility of a persisted relationship graph drifting from the region
-data it was derived from. Bounded at `MAX_REFERENCE_REGIONS` regions ->
-`MAX_REFERENCE_REGION_PAIRS` pairs `x` 6 families =
-`MAX_REFERENCE_REGION_RELATIONSHIP_RECORDS` records maximum - the same
-bounding shape as `relationships.ts`'s `MAX_PAIRWISE_RELATIONSHIP_RECORDS`.
-This is a maximum capacity, never a required minimum region count - there is
-no contract requiring any specific number of authored regions.
-
-A reference relationship is a fact about the reference image's geometry
-only. It is not a design requirement, not a pass/fail verdict, and does not
-claim a runtime target or source owner exists - see
-`docs/WORKFLOWS.md` "Current external-reference foundation workflow" for
-where those later concepts (Prompt 3+) will attach.
-
-## v0.7 Prompt 3 selected design requirements, tolerance semantics, and reference-evidence adequacy
-
-Released as `0.7.0`. Additive extension of the Prompt 1/2 contracts
-above: one new, optional `requirements?: ExternalReferenceRequirement[]`
-field on `ExternalReferenceArtifact` (both lifecycle variants). No schema
-version bump - same reasoning as Prompt 2's `regions` field.
-
-**Central distinction**: a region's geometry is REFERENCE EVIDENCE -
-everything visibly/measurably present in the image. A requirement is
-SELECTED DESIGN INTENT - only what the user/configuration explicitly chose
-as mattering for later candidate evaluation. Nothing in this repository ever
-turns a region property or a derived relationship into a requirement
-automatically.
-
-```ts
-// domain/externalReferenceRequirements.ts
-
-// Reused directly from domain/frontendContracts.ts - not reinvented as a
-// "reference-only" taxonomy; that type carries no runtime-only coupling.
-// 'unexpected' remains impossible to author (not a member of this union).
-type AuthoredChangeScopeCategory = 'requested' | 'expected-dependent' | 'protected' | 'preserved';
-type ExpectedDependentMode = 'required' | 'permitted'; // required only (and exactly) when category === 'expected-dependent'
-
-type ReferenceRequirementRegionProperty = 'x' | 'y' | 'width' | 'height' | 'right' | 'bottom' | 'centerX' | 'centerY'; // exactly ReferenceRegionGeometry's own fields
-type ReferenceRequirementMeasurement = 'vertical-gap' | 'horizontal-gap' | 'center-x-delta' | 'center-y-delta' | 'left-edge-delta' | 'right-edge-delta';
-
-type ReferenceRequirementSubject =
-  | { kind: 'region-property'; region: string; property: ReferenceRequirementRegionProperty }
-  | { kind: 'region-relationship'; subjectRegion: string; relatedRegion: string; relationship: PairwiseRelationshipKind } // reused from relationships.ts - geometry-only families only
-  | { kind: 'region-measurement'; subjectRegion: string; relatedRegion: string; measurement: ReferenceRequirementMeasurement };
-
-// Deliberately NOT a reuse of frontendContracts.ts's ContractTolerance: that
-// type's 'absolute-px' is implicitly runtime/CSS pixels. Reference-image
-// pixels are a distinct, explicitly-labeled unit - nothing here assumes
-// 1 reference pixel = 1 CSS pixel (Prompt 6 will need an explicit mapping).
-type ReferenceRequirementTolerance = { kind: 'exact' } | { kind: 'absolute-reference-px'; amount: number } | { kind: 'percent'; amount: number };
-
-interface ExternalReferenceRequirement {
-  requirementId: string; // system-computed from {subject, category, expectedDependentMode, tolerance} only - never authored
-  category: AuthoredChangeScopeCategory;
-  expectedDependentMode?: ExpectedDependentMode;
-  subject: ReferenceRequirementSubject;
-  tolerance?: ReferenceRequirementTolerance; // required for region-property/region-measurement; must be absent for region-relationship
-}
-```
-
-Key rules:
-
-- Requirement identity (`requirementId`) is always system-computed
-  (`buildReferenceRequirementIdentity`, mirroring
-  `frontendContractIdentity.ts#buildClauseIdentity`'s exact shape) - the raw
-  authored input (`RawReferenceRequirement`) has no `requirementId` field at
-  all, and supplying one is a validation error. Unlike v0.5's
-  `BaselineClause`/`PerChangeClause` (which need an author-visible `clauseId`
-  for cross-document `supersedesBaselineClauseIds` references), Prompt 3
-  requirements have no cross-document reference need yet, so trusting an
-  authored id would only invite drift between a user-typed id and the
-  content it claims to identify.
-- The reference-side expected value/relationship is never stored on the
-  requirement or the artifact - `deriveReferenceRequirementExpectation()` is
-  a pure function computed on demand from the artifact's own `regions`,
-  eliminating the exact drift risk of persisting e.g. `width: 424` alongside
-  a region whose rectangle could (in principle) later disagree with it.
-- A requirement referencing a region id that does not exist in the
-  artifact's own `regions` is a **structural validation failure** (rejected
-  at construction/import time), never merely "unavailable" reference
-  evidence - `isValidReferenceRequirements` checks this before any
-  requirement reaches adequacy computation.
-- **Duplicate/conflicting subject rule**: no two requirements in one
-  collection may share the same structural subject (same region+property,
-  or the same unordered region pair + relationship, or + measurement),
-  regardless of category. This single rule covers both "duplicate
-  requirement" and "conflicting categories on the same subject" (e.g. the
-  same region/property authored as both `requested` and `protected`) -
-  v0.5's `evaluateFrontendContract#primitivesConflict` is a *runtime-
-  evaluation-time* detector (it needs before/after `ObservationArtifact`
-  evidence that does not exist yet at this stage) and could not be reused
-  safely; Prompt 3 restricts invalid combinations at authoring time instead,
-  per the documented precedent-review outcome.
-- Bounded at `MAX_REFERENCE_REQUIREMENTS` (50) requirements per artifact -
-  a maximum capacity, never a required minimum (there is no contract
-  requiring any specific number of authored requirements).
-- One new diagnostic code, `invalid-reference-requirement` (error), covers
-  every requirement-authoring validation failure - deliberately not split
-  further, per the "don't proliferate diagnostics" convention already used
-  for `invalid-reference-region`.
-- `import-reference` gained an optional `--requirements-file <json-file>`
-  (`{ "requirements": [...] }`, same object-root-wrapper convention as
-  `--regions-file`/`--targets-file`); `approve-reference` carries an
-  imported artifact's `requirements` forward verbatim (never re-validated,
-  never re-derived, never dropped), exactly mirroring how it already
-  handles `regions`.
-
-**Reference-evidence adequacy** (`deriveReferenceRequirementAdequacy(regions, requirements)`)
-answers only "does the reference definition itself contain enough evidence
-to understand every selected requirement?" - never "does a runtime
-target/candidate exist" (that is Prompt 4/5's responsibility). It is its own
-small, reference-owned vocabulary (`REFERENCE_REQUIREMENT_ADEQUACY_STATES` =
-`'adequate' | 'partial' | 'inadequate'`, and exactly two reason codes,
-`no-selected-requirements` and `missing-reference-relationship-evidence`) -
-deliberately **not** a reuse of
-`boundedAgentContext.ts`'s `Adequacy`/`ADEQUACY_REASON_CODES`, which
-describe runtime-target/static-correlation concerns that do not exist at
-this stage; mislabeling reference adequacy as bounded-agent-context adequacy
-would conflate two genuinely different evidence domains. Zero selected
-requirements is explicitly `inadequate` (a region-rich, fully-valid
-reference is still not usable for a correction task until the user has
-actually selected what matters) - this is a documented product decision,
-not an oversight. The result is never a numeric score, always structured
-and inspectable, with reasons ordered deterministically by authored
-requirement position.
-
-```ts
-interface ReferenceRequirementAdequacy {
-  status: 'adequate' | 'partial' | 'inadequate';
-  totalRequirements: number;
-  evaluableRequirements: number;
-  unavailableRequirements: number;
-  reasons: { code: 'no-selected-requirements' | 'missing-reference-relationship-evidence'; requirementId?: string; detail?: string }[];
-}
-```
-
-## v0.7 Prompt 4 reference applicability and candidate-state compatibility
-
-Released as `0.7.0`. Additive extension of the Prompt 1/2/3 contracts
-above: one new, optional `applicability?: ExternalReferenceApplicability`
-field on `ExternalReferenceArtifact` (both lifecycle variants), one new,
-optional `explicitState?: ExplicitStateDimensions` field on
-`ObservationArtifact.requestConfig`, and one new pure module,
-`domain/externalReferenceCompatibility.ts`, that answers a single question:
-"does this external reference describe the same frontend state as this
-candidate `ObservationArtifact`?" No schema version bump on either artifact
-- same reasoning as Prompt 2/3's additive fields.
-
-**Central distinction**: this is page/state-level compatibility only -
-never geometry, never fidelity, never a visual/pixel comparison, and never
-region-to-runtime-target binding (Prompt 5). It answers "should a
-reference-vs-candidate geometry comparison even be attempted", not "does the
-candidate match the reference". Reference-evidence adequacy (Prompt 3) and
-reference/candidate compatibility (Prompt 4) are deliberately independent:
-a reference can be `adequate` (enough selected requirements to evaluate)
-while simultaneously `incomparable` against a given candidate (wrong
-viewport/theme/state), and vice versa - neither result constrains the
-other.
-
-**State identity is always explicit, never inferred.** `theme`,
-`applicationState`, and `authenticatedState` are caller/configuration-
-supplied labels only. The observer never reads screenshot pixels, CSS, DOM
-classes/text, URLs, source code, filenames, accessibility labels,
-localStorage, or cookies to determine state - there is no automatic state
-detection anywhere in this codebase, and Prompt 4 does not add any. Labels
-are bounded opaque identities (`^[A-Za-z0-9_-]{1,64}$`, the same pattern
-already used for target names and region ids) compared by exact,
-case-sensitive string equality only - `"dark"` and `"one-dark"` are
-unrelated labels, never fuzzy-matched or normalized.
-
-```ts
-// domain/explicitState.ts - shared by both ObservationArtifact and ExternalReferenceArtifact
-type AuthenticatedState = 'authenticated' | 'unauthenticated'; // closed vocabulary - never a place for credentials/tokens/cookies/session ids
-interface ExplicitStateDimensions {
-  theme?: string;
-  applicationState?: string;
-  authenticatedState?: AuthenticatedState;
-}
-// isValidExplicitStateDimensions requires at least one dimension declared and rejects any unsupported field -
-// this is a bounded, closed shape, never an arbitrary Record<string, unknown> metadata bag.
-
-// domain/externalReferenceApplicability.ts
-interface ApplicableViewport { width: number; height: number } // CSS pixels, bounds [200, 3840] mirroring request.ts's own viewport bounds
-interface ExternalReferenceApplicability extends ExplicitStateDimensions {
-  viewport?: ApplicableViewport;
-}
-```
-
-**Reference image size is never the same concept as applicable viewport.**
-`ExternalReferenceImageReference.width/height` (Prompt 1) describes the
-reference image's own pixel dimensions - a property of the image file,
-detected from its header bytes. `applicability.viewport` describes the
-CSS-pixel runtime viewport the design *represents* - a reference image may
-be captured at any resolution or device-pixel-ratio (e.g. a 1920x1080
-screenshot representing a 960x540 CSS-pixel layout at 2x DPR). Nothing in
-`externalReferenceApplicability.ts` reads or derives a viewport from image
-dimensions; `isValidExternalReferenceApplicability` is its own validator
-(not a reuse of `isValidExplicitStateDimensions`, whose "at least one
-dimension" rule would incorrectly reject a viewport-only applicability
-object).
-
-**v0.4 comparability is reused, not duplicated.** `domain/comparison.ts`
-gained four additive reason codes (`viewport-unassessed`, `theme-mismatch`,
-`authenticated-state-mismatch`, `application-state-mismatch` - the
-`*-unassessed` codes for theme/authenticated-state/application-state
-already existed from v0.4) and two optional fields on `ComparabilityReason`
-(`referenceValue?: string`, `candidateValue?: string`, populated only for a
-mismatch reason). `domain/comparisonEngine.ts` gained one new exported pure
-helper, `assessOptionalComparabilityDimension(mismatchCode, unassessedCode,
-beforeValue, afterValue, mismatchMessage, unassessedMessage)`, extracted
-from - and now used by - both v0.4's own `evaluateComparability`
-(Observation-vs-Observation) and the new
-`evaluateReferenceCandidateCompatibility` (Reference-vs-Observation). The
-rule is identical either way: both values defined and equal -> no reason;
-both defined and different -> a `blocking` mismatch reason (with
-`referenceValue`/`candidateValue` populated); either value undefined ->
-an `unassessed` reason. This is a genuine, additive improvement to v0.4's
-own behavior: `evaluateComparability` now assesses theme/authenticated-
-state/application-state as matching or blocking-mismatched whenever *both*
-observations declare `requestConfig.explicitState`, rather than always
-reporting them unassessed - but every historical observation pair (and any
-pair where either side omits `explicitState`) retains the exact old
-unassessed-only behavior, verified by the frozen `evaluateComparability`
-regression test that predates this batch.
-
-```ts
-// domain/externalReferenceCompatibility.ts
-interface ReferenceCandidateCompatibilityResult {
-  referenceId: string;
-  referenceRequestId: string;
-  candidateObservationId: string;
-  candidateRequestId: string;
-  compatibility: ComparabilityResult; // v0.4's own reused result type - state/reasons, never a boolean or a visual score
-}
-function evaluateReferenceCandidateCompatibility(reference: ExternalReferenceArtifact, candidate: ObservationArtifact): ReferenceCandidateCompatibilityResult;
-```
-
-Key rules:
-
-- Pure and synchronous - no browser, no filesystem, no network, no target
-  binding. Only `reference.applicability` and
-  `candidate.requestConfig.viewport`/`candidate.requestConfig.explicitState`
-  are consulted; reference regions/requirements are never read here (a
-  distinct, separate concern - see Prompt 3 above).
-- A dimension the reference constrains but the candidate entirely omits
-  (or vice versa) is `unassessed`, never treated as compatible-by-default
-  and never fabricated as a mismatch - fail-closed, honest non-assessment.
-- A reference that declares no `applicability` at all produces a fully
-  `unassessed` (never automatically `incomparable`, never automatically
-  `comparable` beyond "no blocking reasons found") result across all four
-  dimensions - Prompt 1/2/3 references remain fully usable, just
-  unassessed for compatibility until applicability is authored.
-- No automatic persisted compatibility artifact. This is a pure
-  programmatic result, produced on demand by an application/CLI caller
-  that already holds both a reference and a candidate artifact - inventing
-  a new persisted artifact kind for a value this cheap to recompute would
-  add drift risk (a candidate/reference re-imported later could silently
-  disagree with a stale persisted compatibility record) with no
-  corresponding benefit; this may be revisited only if a later prompt's
-  architecture proves persistence necessary.
-- Identity impact: `buildExternalReferenceRequestIdentity` gained a final
-  optional `applicability` parameter (omitted, never `null`, when absent -
-  byte-identical to Prompt 1/2/3 hashes for every call that doesn't supply
-  it); `buildRequestIdentity` gained a final optional `explicitState`
-  parameter with the identical omission convention. Neither identity
-  function ever takes a file path.
-- CLI: `import-reference` gained an optional `--applicability-file
-  <json-file>` (the raw, unwrapped applicability object - not a
-  `{ "requirements": [...] }`-style wrapper, since applicability is a
-  single object rather than a named list); `observe` gained an optional
-  `--state-file <json-file>` (the raw, unwrapped `ExplicitStateDimensions`
-  object). Both follow the existing `--scroll-scenario-file` convention
-  exactly: relative paths resolve from the current working directory, the
-  path itself is never persisted or included in any identity, and CLI code
-  owns only flag syntax/file reading/JSON parsing/object-root validation -
-  all semantic validation happens in the domain layer.
-
-## v0.7 Prompt 5 explicit reference-region <-> runtime-target binding
-
-Released as `0.7.0`. One new pure domain module,
-`domain/externalReferenceRuntimeBinding.ts`, answering "which stable
-observer runtime target, if any, does this candidate observation resolve
-for each explicitly declared reference region?" No new field is added to
-either `ExternalReferenceArtifact` or `ObservationArtifact` - both remain
-exactly as Prompt 4 left them - and no schema version bump on either.
-
-**Two identity domains, kept strictly separate.** A binding declaration
-names a Prompt 2 `ReferenceRegion.id` and a v0.2 `NamedTarget.name` (the
-stable observer runtime target identity established since v0.2 - never a
-CSS selector, DOM node handle, source file, React component name, or
-my-dev-kit node id). These two strings living in the same textual namespace
-never implies a binding - a region id `"header"` and a target name
-`"header"` bind to each other only because of an explicit declaration, not
-because the strings match (verified by a dedicated test: the same
-observation with and without the explicit declaration produces `bound`
-only in the former case).
-
-```ts
-// domain/externalReferenceRuntimeBinding.ts
-interface ReferenceRuntimeBindingDeclaration {
-  referenceRegion: string; // Prompt 2 ReferenceRegion.id
-  runtimeTarget: string;   // v0.2 NamedTarget.name
-}
-
-const REFERENCE_RUNTIME_BINDING_STATUSES = ['bound', 'ambiguous', 'unavailable'] as const;
-
-interface ReferenceRuntimeBindingResult {
-  referenceRegion: string;
-  runtimeTarget: string;
-  status: 'bound' | 'ambiguous' | 'unavailable';
-  reasonCode?: 'runtime-target-not-configured' | 'runtime-target-not-found' | 'runtime-target-ambiguous' | 'runtime-target-evidence-unavailable';
-  detail: string;
-  targetResolutionStatus?: TargetSelectionStatus; // v0.2's own resolution status, when evidence for it exists
-  targetVisible?: boolean; // provenance only - never affects status
-}
-
-interface ReferenceRuntimeBindingEvaluation {
-  referenceId: string;
-  referenceRequestId: string;
-  candidateObservationId: string;
-  candidateRequestId: string;
-  compatibility: ComparabilityResult; // reused verbatim from v0.7 Prompt 4
-  bindings: ReferenceRuntimeBindingResult[]; // empty exactly when compatibility.state === 'incomparable'
-}
-
-function evaluateReferenceRuntimeBindings(
-  reference: ExternalReferenceArtifact,
-  candidate: ObservationArtifact,
-  declarations: readonly ReferenceRuntimeBindingDeclaration[],
-): { ok: true; evaluation: ReferenceRuntimeBindingEvaluation } | { ok: false; reason: string };
-```
-
-Key rules:
-
-- **Explicit, never inferred.** A binding declaration is user/configuration
-  input asserting a conceptual correspondence; this module never discovers
-  it from screenshot geometry, matching names, matching text, or source
-  code. There is no automatic-matching algorithm anywhere in this module.
-- **Reuses, never duplicates.** The compatibility gate reuses
-  `evaluateReferenceCandidateCompatibility` (Prompt 4) verbatim - viewport/
-  theme/application-state/authenticated-state comparison logic is never
-  re-implemented here. Runtime-target resolution reuses `targetPresence`
-  (v0.4 `comparisonEngine.ts`, now additively exported alongside
-  `assessOptionalComparabilityDimension`) - the exact same "how do I read a
-  `TargetEvidenceRecord`'s resolution" rule v0.4's own before/after target
-  comparison already uses. No second target resolver, no browser launch, no
-  Chromium query, no selector evaluation, no live-DOM inspection - this
-  module consumes only an already-captured `ObservationArtifact`'s
-  `requestConfig.targets`/`targetEvidence`.
-- **Compatibility gates before evaluation, structurally.** If
-  `evaluateReferenceCandidateCompatibility` reports `incomparable`,
-  `bindings` is the empty array and the caller reads the reason from the
-  embedded `compatibility` field - there is no binding-local "incompatible"
-  status; Prompt 4's compatibility result is represented exactly once, not
-  duplicated into a parallel vocabulary.
-- **Two-layer validation.** Reference-region existence, declaration shape,
-  bounds, and duplicate/conflict rules are validated structurally against
-  the `ExternalReferenceArtifact` alone (`isValidReferenceRuntimeBindingDeclarations`)
-  - independent of any candidate, mirroring Prompt 3's "unknown region
-  reference is a structural validation failure" precedent exactly: a
-  declaration naming a nonexistent reference region, or any reference with
-  no `regions` declared at all, fails the whole evaluation closed before a
-  candidate is even considered. Runtime-target availability, by contrast,
-  is evaluated per-candidate inside `evaluateReferenceRuntimeBindings`
-  itself, since the same declaration can be `bound` against one candidate
-  and `unavailable` against another.
-- **Duplicate/conflicting-declaration rule** (mirrors Prompt 3's
-  requirement-subject uniqueness rule): no two declarations may name the
-  same `referenceRegion` (case-insensitively), whether they agree on
-  `runtimeTarget` (an exact duplicate) or disagree (a conflict) - both fail
-  the same way, never silently resolved by keeping the first. The reverse -
-  several distinct reference regions naming the same `runtimeTarget` - is
-  deliberately allowed (e.g. two design sub-regions legitimately
-  corresponding to one runtime container element).
-- **Target-resolution-state handling.** `targetPresence`'s four outcomes
-  map onto binding status as: `matched` -> `bound`; `ambiguous` -> `ambiguous`
-  (the candidate's own configured target resolved ambiguously - never
-  reported bound even though its stable name exists); `not-found` ->
-  `unavailable` (`runtime-target-not-found` - the target was configured but
-  the resolver found nothing on the page); no usable resolution evidence at
-  all -> `unavailable` (`runtime-target-evidence-unavailable`). A declared
-  `runtimeTarget` that was never part of the candidate's configured target
-  set at all is a fifth, CLI/config-boundary-only outcome -> `unavailable`
-  (`runtime-target-not-configured`) - never a dynamic page search.
-- **Hidden-target decision.** A uniquely resolved (`matched`) but hidden
-  target is still reported `bound` - visibility never changes `status`.
-  `targetVisible` (from the existing `TargetVisibility` evidence, when
-  available) is carried as provenance only. Binding identity (does a stable
-  correspondence exist) and later fidelity evaluability (can this evidence
-  actually be used to check the design) are treated as distinct questions;
-  this prompt answers only the former.
-- **Not every region needs a binding.** `isValidReferenceRuntimeBindingDeclarations`
-  never requires full region coverage - a reference may have regions no
-  declaration names at all (they simply have no bound runtime target for
-  this candidate). This is not a completeness gate; Prompt 6 (or later) may
-  add one for the regions that selected requirements actually need.
-- **No persisted artifact family.** `evaluateReferenceRuntimeBindings` is a
-  pure, on-demand function over an already-persisted reference, an
-  already-persisted candidate observation, and an in-memory declaration
-  collection. No `ExternalReferenceBindingArtifact` (or equivalent) is
-  introduced - the same "cheap to recompute, persisting invites drift"
-  reasoning Prompt 4 already applied to its own compatibility result.
-  Neither the reference nor the observation artifact is ever rewritten to
-  carry a binding result: a design reference may later be evaluated against
-  several different candidates, and one observation may be evaluated
-  against several different references, so binding is kept as downstream,
-  candidate-specific, reference-specific derived evidence rather than
-  mutating either immutable source artifact.
-- **No new identity function.** Unlike `buildRequestIdentity`/
-  `buildExternalReferenceRequestIdentity`, no hash-based logical identity is
-  computed for a binding declaration or its evaluated result - there is no
-  persistence and no cross-document reference-by-id need yet (mirroring
-  Prompt 4's `ReferenceCandidateCompatibilityResult`, which took the same
-  approach). Provenance is instead carried directly as plain fields
-  (`referenceId`, `referenceRequestId`, `candidateObservationId`,
-  `candidateRequestId`, plus each result's own `referenceRegion`/
-  `runtimeTarget`) - already deterministic, already sufficient for a caller
-  to trace every result back to its inputs, without inventing a fifth
-  identity-hashing convention for a value this prompt does not persist.
-- **Deterministic ordering.** `bindings` preserves authored declaration
-  order (mirroring the "authored order is semantic" convention already used
-  for regions/requirements) rather than sorting by any derived key.
-- **Bounded.** `MAX_REFERENCE_RUNTIME_BINDINGS` (20) caps the declaration
-  collection, mirroring `MAX_REFERENCE_REGIONS`.
-- **No public CLI surface yet.** Only the programmatic
-  `evaluateReferenceRuntimeBindings`/`isValidReferenceRuntimeBindingDeclarations`
-  functions are exported. A standalone CLI command was deliberately not
-  added merely for symmetry with `import-reference`/`observe`; Prompt 6
-  (structured fidelity evaluation) is expected to become the first concrete
-  consumer and public-surface owner for this capability.
-
-## v0.7 Prompt 6 structured reference-vs-candidate fidelity evaluation
-
-Released as `0.7.0`. One new pure domain module,
-`domain/externalReferenceFidelity.ts`, and its CLI-facing counterpart,
-`application/referenceFidelityEvaluationService.ts` plus the new
-`evaluate-reference-fidelity` CLI command - the first point in this whole
-v0.7 stack where a reference's authored expectation is actually compared
-against live candidate evidence. No new artifact field, no schema version
-bump: this prompt reuses Prompt 1-5's artifacts and result types entirely.
-
-```ts
-// domain/externalReferenceFidelity.ts
-const REFERENCE_REQUIREMENT_FIDELITY_STATUSES = ['pass', 'fail', 'unavailable'] as const;
-const REFERENCE_FIDELITY_STATES = ['not-evaluated', 'pass', 'fail'] as const;
-const REFERENCE_FIDELITY_BLOCK_REASONS = ['reference-inadequate', 'incompatible'] as const;
-
-interface ReferenceRequirementFidelityResult {
-  requirementId: string;
-  category: AuthoredChangeScopeCategory;
-  expectedDependentMode?: ExpectedDependentMode;
-  subject: ReferenceRequirementSubject;
-  boundRuntimeTargets: string[];
-  status: 'pass' | 'fail' | 'unavailable';
-  reasonCode?: 'reference-evidence-unavailable' | 'reference-relationship-not-exhibited' | 'binding-unavailable' | 'candidate-evidence-unavailable' | 'coordinate-mapping-unavailable'; // present iff status === 'unavailable'
-  detail?: string;
-  // region-property/region-measurement subjects only:
-  referenceValue?: number;      // reference-image pixels
-  candidateRawValue?: number;   // CSS pixels, as captured
-  candidateValue?: number;      // candidateRawValue converted into reference-image-pixel space
-  delta?: number;               // candidateValue - referenceValue
-  tolerance?: ReferenceRequirementTolerance;
-  // region-relationship subjects only:
-  expectedRelationship?: PairwiseRelationshipKind;
-  actualRelationship?: PairwiseRelationshipKind;
-}
-
-interface ReferenceCandidateFidelityEvaluation {
-  referenceId: string;
-  referenceRequestId: string;
-  candidateObservationId: string;
-  candidateRequestId: string;
-  adequacy: ReferenceRequirementAdequacy; // reused verbatim from Prompt 3
-  compatibility?: ComparabilityResult;    // reused verbatim from Prompt 4; absent only when adequacy itself is inadequate
-  bindings?: ReferenceRuntimeBindingEvaluation; // reused verbatim from Prompt 5; absent when an earlier gate blocked
-  state: 'not-evaluated' | 'pass' | 'fail';
-  blockedBy?: 'reference-inadequate' | 'incompatible'; // present iff state === 'not-evaluated'
-  requirementResults: ReferenceRequirementFidelityResult[]; // empty iff state === 'not-evaluated'
-}
-
-function evaluateReferenceCandidateFidelity(
-  reference: ExternalReferenceArtifact,
-  candidate: ObservationArtifact,
-  bindingDeclarations: readonly ReferenceRuntimeBindingDeclaration[],
-  options?: { geometryTolerancePx?: number },
-): { ok: true; evaluation: ReferenceCandidateFidelityEvaluation } | { ok: false; reason: string };
-```
-
-**Result vocabulary.** `pass`/`fail`/`unavailable` is reused from v0.5's
-`CLAUSE_RESULT_STATUSES` shape (the same honest three-state idea: a result
-either satisfies its condition, fails it, or cannot be evaluated - never a
-score) but is its own independently-owned constant, deliberately excluding
-v0.5's fourth member, `'conflict'` - Prompt 6 has no cross-requirement
-authoring-conflict concept (each requirement is evaluated independently
-against its own subject), so reusing `conflict` would invite a status this
-prompt can never actually produce.
-
-**Evaluation order (frozen, never reordered):** reference structural
-validation -> candidate structural validation -> binding-declaration
-structural validation -> Prompt 3 reference adequacy -> Prompt 4
-compatibility -> Prompt 5 binding evaluation -> per-requirement candidate-
-evidence/coordinate-mapping checks -> per-requirement tolerance/
-relationship comparison -> overall result. The first three (structural
-validation) failures return `{ ok: false, reason }` - a caller/config error,
-never a fidelity outcome. The next two (adequacy `inadequate`, compatibility
-`incomparable`) short-circuit to `state: 'not-evaluated'` with an empty
-`requirementResults` - an earlier blocking gate never lets an ordinary
-PASS/FAIL requirement set get fabricated past it. `adequacy` "partial" (some,
-but not all, authored requirements individually unavailable) does **not**
-block evaluation - it proceeds normally, and the individual unavailable
-reference-side requirements simply also report `unavailable` at the
-per-requirement level (their own reference-evidence problem, re-derived
-identically by `evaluateOneRequirement`, not looked up from the adequacy
-result).
-
-**Coordinate mapping - the central problem this prompt solves.** Prompt 2
-regions and Prompt 3 tolerances are authored in reference-image pixels;
-`ObservationArtifact` target geometry is CSS pixels. This module establishes
-exactly one explicit, deterministic scale from `reference.applicability.viewport`
-(the CSS-pixel runtime viewport, Prompt 4) and the reference image's own
-pixel dimensions (Prompt 1) - `scaleX = imageWidth / viewportWidth`,
-`scaleY = imageHeight / viewportHeight` - and converts every candidate
-measurement into reference-image-pixel space before comparing it against a
-Prompt 3 tolerance. It never assumes 1 reference-image pixel equals 1 CSS
-pixel, and it never performs cropping, offset, rotation, or perspective
-registration - only a deliberately bounded full-frame mapping. `scaleX`/
-`scaleY` must agree within a small, independently-owned coordinate-mapping-
-validity tolerance (1% relative, never a user-authored design tolerance) or
-the mapping is rejected outright; a reference with no applicable viewport at
-all likewise has no mapping. Either way, every numeric (`region-property`/
-`region-measurement`) requirement becomes `unavailable`/`coordinate-mapping-unavailable`
-- categorical `region-relationship` requirements are unaffected (they never
-need a scale). Horizontal fields (`x`/`width`/`right`/`centerX` and the
-horizontal measurements) always scale by `scaleX`; vertical fields (`y`/
-`height`/`bottom`/`centerY` and the vertical measurements) always scale by
-`scaleY` - this falls out automatically from converting a full
-`TargetGeometry` into a `ReferenceRegionGeometry`-shaped value per axis,
-never a hand-picked per-property axis table.
-
-**Tolerance is reused exactly, never redefined.** A single rule -
-`abs(delta) <= allowedAmount` - covers all three Prompt 3 tolerance kinds:
-`exact` is simply the zero-tolerance case (`allowedAmount = 0`);
-`absolute-reference-px` uses its authored `amount` directly (already in
-reference-image pixels); `percent`'s denominator is `Math.abs(referenceValue)`,
-mirroring v0.5's own `toleranceToPx` "may vary by up to N%" convention
-exactly (independently reimplemented in reference-image-pixel units, never
-imported - `frontendContractEvaluation.ts`'s `ContractTolerance` is a
-different, CSS-pixel-implicit unit). No hidden epsilon is added anywhere;
-subpixel precision is preserved through to the final comparison, so a
-tolerance-boundary value (e.g. delta exactly equal to the allowed amount)
-passes and one unit past it fails, exactly as authored.
-
-**Region-property evaluation** reads `TargetGeometry` from the bound
-target's `targetEvidence` entry, converts it into a `ReferenceRegionGeometry`-
-shaped value (adding `centerX`/`centerY`, computed identically to
-`deriveReferenceRegionGeometry`) both raw (CSS) and scaled (reference-image
-pixels), and reads `[subject.property]` off each - `candidateRawValue`
-(CSS) and `candidateValue` (reference-image pixels) are both reported.
-
-**Region-measurement evaluation** converts *both* bound targets' geometries
-the same way and calls the existing `deriveReferenceRequirementMeasurement`
-(Prompt 3) on the converted geometries directly - reusing Prompt 3's exact
-gap/delta formulas rather than reimplementing a parallel "runtime version"
-of them, and never inventing a generic geometry expression language. A
-geometrically-undefined gap (the two targets overlap on the relevant axis)
-is `unavailable`, mirroring Prompt 3's own reference-side treatment of the
-identical situation.
-
-**Region-relationship evaluation** first confirms the reference itself
-actually exhibits its own selected relationship (`deriveReferenceRequirementExpectation`'s
-`matches` field) - if not, the result is `unavailable`/
-`reference-relationship-not-exhibited` (a reference-authoring problem, never
-a candidate `fail`). It then resolves both bound targets and calls the
-canonical `deriveLayoutRelationships` (v0.4) over the *whole* candidate
-observation - never a second, parallel relationship formula - and looks up
-the pairwise record for the bound target pair **scoped to the exact
-requested relationship family** (an independently-owned, third duplicate of
-the same `RELATIONSHIP_FAMILY_GROUPS` shape already used by
-`frontendContractEvaluation.ts` and `externalReferenceRequirements.ts` -
-this is the same real bug class Prompt 3 fixed: matching the first record
-for a target pair regardless of family would silently compare against the
-wrong relationship kind). A record only derivable in the reversed target
-order is `unavailable`, never auto-flipped - identical to Prompt 3's own
-reference-side handling of the same situation. `pass` requires the
-candidate's actual relationship kind to equal the requirement's authored
-`relationship` exactly.
-
-**Binding gate.** Every subject's dependent reference region(s) must have a
-`bound` (never `ambiguous`/`unavailable`, and never simply absent from the
-supplied declarations) Prompt 5 binding result, or the requirement is
-`unavailable`/`binding-unavailable` - this module never guesses another
-target and never auto-binds based on geometry or names. A `bound` target
-that is not visible (`TargetVisibility.visible !== true`, including when
-visibility evidence itself is unavailable) is treated as having no usable
-geometry - `unavailable`/`candidate-evidence-unavailable` - preserving the
-distinction between "binding succeeded" (Prompt 5's question) and "this
-evidence is usable for fidelity evaluation" (this prompt's question): a
-hidden-but-uniquely-resolved target still has a stable identity, but its
-geometry is never treated as meaningful for a numeric/relationship
-comparison.
-
-**Categories are preserved, never given different PASS/FAIL rules.**
-`category`/`expectedDependentMode` are carried through to each result as
-provenance only; Prompt 3 never implemented a `required`-vs-`permitted`
-directional evaluation difference for its own expectation/adequacy
-derivation (unlike v0.5's runtime-directional contract clauses), so Prompt 6
-does not invent one now - every requirement in the reference's authored
-collection is evaluated by the identical rule and counts identically toward
-the overall result, regardless of category.
-
-**Overall fidelity result.** For an evaluated (non-blocked) pair, `state`
-is `'pass'` only when every requirement result is `'pass'`; any `'fail'` or
-`'unavailable'` result forces `state: 'fail'` - there is no meaningful third
-overall bucket once evaluation has actually run, since "some/all
-unavailable" and "some/all fail" both equally mean "not every selected
-requirement is confirmed satisfied." A reference with zero selected
-requirements never reaches this stage at all - it is `inadequate` (Prompt
-3's own zero-requirements rule) and therefore `not-evaluated`, never a
-meaningless `pass`.
-
-**Persistence decision: none.** `evaluateReferenceCandidateFidelity` (and
-its CLI-facing wrapper, `evaluateReferenceCandidateFidelityFromArtifactRoots`)
-is a pure, on-demand function over already-persisted/in-memory evidence -
-no new `ExternalReferenceFidelityEvaluationArtifact` (or equivalent) is
-introduced. Rationale, identical to Prompt 4/5's own precedent: the result
-is cheap to recompute deterministically from its inputs (a reference, a
-candidate, and a caller-supplied binding-declaration collection), and
-persisting it would invite drift with no corresponding benefit at this
-stage; this may be revisited only if Prompt 7's architecture proves
-persistence necessary.
-
-**CLI**: `evaluate-reference-fidelity --reference <root> --candidate <root>
-[--bindings-file <json-file>] [--enforce]` - the CLI surface Prompt 5
-deliberately deferred. `--bindings-file` follows the exact
-`--requirements-file`/`--regions-file` wrapped-object convention
-(`{ "bindings": [...] }`); CLI code owns only flag syntax/file reading/JSON
-parsing/root-shape validation, with every binding-declaration rule staying
-owned by `isValidReferenceRuntimeBindingDeclarations`. `--enforce` mirrors
-`evaluate-contract`'s exact precedent: it changes only the process exit
-status for an already-computed `state: 'fail'` result, never the printed
-content - and has no effect on `not-evaluated`, which always exits 0 (a
-compatibility/adequacy blocker is a successful, structured, honest
-non-evaluation, never an execution error and never a design mismatch).
-Persists nothing; there is no `--output` flag.
-
-## v0.7 Prompt 7 bounded reference-fidelity projection and v0.6 bounded-agent-context integration
-
-Released as `0.7.0`. Additive extension of the v0.6 bounded-agent-context
-contract above and of the v0.7 Prompt 6 fidelity evaluator - no new bounded-
-context artifact family, no second visual-context system, no schema version
-bump (`BOUNDED_AGENT_CONTEXT_SCHEMA_VERSION` stays `1.0.0`, following the
-exact precedent already set when `correlations?` was added in v0.6 Batch 3).
-
-**Chosen integration owner.** `projectBoundedAgentContext` itself gains one
-new optional input (`fidelity?: ReferenceCandidateFidelityEvaluation`, plus
-`fidelityRequired?: boolean`) rather than a separate `VisualAgentContext`/
-`VisualPromptPacket`/`ReferencePromptBuilder`. This was chosen over a pure
-post-hoc "attach" step (the shape `attachRuntimeStaticCorrelations` uses)
-because fidelity-relevant runtime targets must compete fairly for
-`MAX_RUNTIME_TARGETS` capacity and receive the exact same geometry/
-visibility/screenshot assembly contract-clause-derived targets already get -
-an attach-only step run after target allocation could never produce that. A
-new pure module, `domain/referenceFidelityProjection.ts`
-(`projectReferenceFidelity`), derives the bounded, prioritized fidelity
-content plus the target-id/omission/truncation contributions
-`projectBoundedAgentContext` folds into its own existing pipeline - it is
-not a second fidelity-evaluation engine, only a selection over Prompt 6's
-already-computed result.
-
-```ts
-// domain/boundedAgentContext.ts - additive
-interface BoundedAgentContextSourceReferences {
-  // ...unchanged fields...
-  referenceId?: string;       // new, optional
-  referenceRequestId?: string; // new, optional
-}
-
-const MAX_FIDELITY_MISMATCHES = 15;
-const MAX_FIDELITY_PROTECTED_CONTEXT = 10; // reuses MAX_RELATIONSHIP_EVIDENCE_PER_TARGET's value
-
-interface BoundedReferenceFidelityProjection {
-  referenceId: string;
-  referenceRequestId: string;
-  candidateObservationId: string;
-  candidateRequestId: string;
-  adequacy: ReferenceRequirementAdequacy;   // reused verbatim from Prompt 3
-  compatibility?: ComparabilityResult;      // reused verbatim from Prompt 4
-  state: ReferenceFidelityState;            // reused verbatim from Prompt 6
-  blockedBy?: ReferenceFidelityBlockReason; // reused verbatim from Prompt 6
-  mismatches: ReferenceRequirementFidelityResult[];      // bounded, prioritized non-pass requirements (Prompt 6 type, unmodified)
-  protectedContext: ReferenceRequirementFidelityResult[]; // bounded passing protected/preserved requirements, as "do not break this" context
-}
-
-interface BoundedAgentContextArtifact {
-  // ...unchanged fields...
-  fidelity?: BoundedReferenceFidelityProjection; // new, optional - mirrors `correlations?`'s own additive precedent exactly
-}
-```
-
-**Selection policy** (`domain/referenceFidelityProjection.ts#projectReferenceFidelity`):
-only Prompt 6's non-`pass` requirement results are ever candidates for
-`mismatches` - passing requirements are never dumped by default, satisfying
-this prompt's "bounded coding-agent use" design goal. Each candidate is
-classified into a tier by its authored category/mode, reusing
-`boundedAgentContextProjection.ts#clauseTier`'s exact rule (duplicated, not
-imported, per this repository's established per-module small-helper
-convention - never a reference-specific protected/preserved taxonomy):
-`protected`/`preserved` are always `required`; `expected-dependent` is
-`required` only in `'required'` mode; `requested` and `expected-dependent`/
-`'permitted'` are `optional`.
-
-**Priority policy**: 1) `fail` + `required` tier, 2) `unavailable` +
-`required` tier, 3) any other non-`pass` (optional-tier) result. Within one
-priority class, Prompt 6's own authored requirement order is preserved (a
-stable sort by priority rank only) - never re-ranked by an opaque score.
-The final `mismatches` array is reported in priority order (highest first),
-not restored to authored order, since the whole point of prioritization is
-that the most actionable evidence appears first when the set is large.
-
-**Cap values**: `MAX_FIDELITY_MISMATCHES = 15` and
-`MAX_FIDELITY_PROTECTED_CONTEXT = 10` (reusing
-`MAX_RELATIONSHIP_EVIDENCE_PER_TARGET`'s value) - both judgment-call bounds
-in the same spirit as v0.6 Batch 1's own frozen caps (no measured fixture
-corpus exists yet for either concept).
-
-**Omission/truncation behavior**: reuses `OmissionRecord`/`TruncationRecord`
-wholesale, no second reporting model. When mismatches exceed the cap, a
-`{subject: 'fidelity-mismatches', limit, actualCount, required}` truncation
-is recorded, plus one `{subject: 'fidelity-mismatch:<requirementId>',
-reason: 'required-evidence-lost-by-bound', required: true}` omission for
-*each* dropped required-tier mismatch (optional-tier drops are truncated
-but never separately omitted as "required loss", since they were never
-required). `protectedContext` truncation is always `required: false` - it
-is confirmatory/passing context, never a design-fidelity failure. These
-records are folded into `projectBoundedAgentContext`'s own `omissions`/
-`truncations` arrays *before* its existing aggregate `capOmissions`/
-`capTruncations` calls and its existing adequacy computation run - fidelity
-loss is never a separate adequacy code path, it simply participates in the
-exact same `anyRequiredLoss`/`anyOptionalLoss` rule every other evidence
-source already uses.
-
-**Adequacy behavior**: a `not-evaluated` fidelity (blocked by Prompt 6's own
-`reference-inadequate`/`incompatible` gates) is never converted into "no
-problems" - `projectReferenceFidelity` records an explicit
-`{subject: 'fidelity', reason: 'unsupported-or-unavailable', required,
-detail}` omission, where `required` defaults to `true` (supplying a
-fidelity evaluation to be projected at all is itself the signal that the
-task depends on it, mirroring `CorrelationTargetInput.required`'s existing
-v0.6 convention - callers who want fidelity as purely incidental context set
-`fidelityRequired: false`). A `required: true` fidelity omission, folded
-into the existing adequacy computation, prevents `adequacy.state` from
-remaining `'adequate'` (it becomes `'partial'`, or `'inadequate'` when
-combined with other required loss reaching the existing threshold) - it is
-never silently ignored. A `required: false` omission can degrade adequacy
-to at most `'partial'`, per v0.6's own pre-existing "optional-only loss
-never means inadequate" rule - unchanged, not redefined. A `pass` fidelity
-result contributes no omissions/truncations at all and never degrades
-adequacy.
-
-**Not-evaluated fidelity behavior**: preserved exactly as Prompt 6 reported
-it - `fidelity.state`/`fidelity.blockedBy` on the output artifact are a
-direct pass-through of Prompt 6's own values, with `mismatches`/
-`protectedContext` both empty (there is nothing to select from an empty
-`requirementResults`).
-
-**Per-target organization**: every fidelity mismatch's `boundRuntimeTargets`
-(Prompt 5/6's own field, never truncated) becomes a required- or permitted-
-tier addition to `projectBoundedAgentContext`'s existing target-id sets,
-so those runtime targets receive full `BoundedRuntimeTargetProjection`
-treatment (geometry/visibility/overflow/scrollOwner/screenshotRef) through
-the exact existing assembly code - no duplicated target-projection logic.
-Reference regions are never used as a correlation or target-selection key;
-only the already-bound stable v0.2 runtime target ids are.
-
-**Multi-target relationship representation**: a `region-relationship`
-mismatch's `boundRuntimeTargets` array (already carrying both bound
-targets, from Prompt 6) is used as-is - both targets are added to the
-required/permitted set, so both appear in `targets`. Nothing collapses a
-two-target relationship failure onto a single target.
-
-**Static-correlation reuse**: entirely unchanged. `deriveRuntimeStaticCorrelations`/
-`attachRuntimeStaticCorrelations` are not modified, not called from within
-this prompt's new code, and remain the caller's own separate step -
-`BoundedRuntimeTargetProjection.targetId`/`RuntimeStaticCorrelationRecord.runtimeTargetId`
-already share the same stable v0.2 identity a fidelity mismatch's
-`boundRuntimeTargets` also uses, so a caller (Prompt 8) joins fidelity,
-target, and correlation evidence by that one shared id without this module
-ever needing to read source, run my-dev-kit, or choose among ambiguous
-candidates itself.
-
-**Ambiguous/unavailable correlation behavior**: unaffected - a
-`RuntimeStaticCorrelationRecord` with `status: 'ambiguous'` continues to
-preserve every competing candidate (v0.6's own frozen invariant,
-untouched), and `status: 'unavailable'` never causes a fidelity mismatch
-for that same runtime target to be dropped - the two evidence kinds
-(runtime fidelity, static correlation) are attached independently and
-neither erases the other.
-
-**Provenance**: every included mismatch remains traceable to the reference
-(`sources.referenceId`/`referenceRequestId`, new), the requirement
-(`requirementId`, `category`, `subject` - naming its reference region(s)),
-the Prompt 5 binding (`boundRuntimeTargets`), the candidate
-(`sources.observationIds`), and the full Prompt 6 evidence
-(`referenceValue`/`candidateRawValue`/`candidateValue`/`delta`/`tolerance`
-or `expectedRelationship`/`actualRelationship`) - nothing is replaced by a
-prose-only summary. No raw image bytes are ever embedded (fidelity carries
-only identifiers and numeric/categorical evidence, never pixels), and no
-source-ownership field (`sourceOwner`/`sourceFile`/`component`/`symbol`/
-`causedBy`) is ever produced - Prompt 7 stops at the runtime target exactly
-as Prompt 6 did; v0.6's own, unmodified static correlation is the only
-source-adjacent evidence this context ever carries, and it remains
-evidence, never edit authorization.
-
-**Identity impact**: `buildBoundedAgentContextRequestIdentity` gained a
-final optional `fidelity?: unknown` parameter - omitted (never `null`) from
-the hashed semantic view when absent, so every pre-Prompt-7 call site keeps
-producing its exact byte-identical hash (verified by a frozen-vector-style
-regression test). When present, the caller's already-derived, bounded
-`BoundedReferenceFidelityProjection` (not the raw Prompt 6 evaluation) is
-hashed, so identity changes exactly when the content a caller would
-actually receive changes - never merely because an unselected, dropped
-requirement result changed somewhere upstream. `sources.referenceId`/
-`referenceRequestId` follow the identical omit-when-absent convention.
-Operational paths were never an identity input for this artifact family to
-begin with (no path parameter exists anywhere in this contract), so path
-independence holds trivially.
-
-**Schema-version decision**: no bump. Every new field
-(`BoundedAgentContextSourceReferences.referenceId`/`referenceRequestId`,
-`BoundedAgentContextArtifact.fidelity`) is additive and optional; a
-pre-Prompt-7 artifact/consumer remains fully valid and behaviorally
-unchanged with all of them absent, matching the exact precedent
-`correlations?` already established without a version bump in v0.6 Batch 3.
-
-**Persistence decision: none.** `projectBoundedAgentContext` and
-`projectReferenceFidelity` both remain pure, programmatic, in-memory
-functions - no new writer/reader, no new artifact family. This mirrors
-Prompt 6's own "no persisted fidelity artifact" decision and v0.6's
-existing "bounded agent context is library-only" architecture.
-
-**CLI decision**: none added. v0.6 bounded agent context has never had a
-CLI surface, and this prompt does not introduce one - Prompt 8 is expected
-to become the first concrete consumer of `projectBoundedAgentContext`'s
-(now fidelity-aware) programmatic output.
-
-## v0.7 Prompt 8 controlled end-to-end external-reference coding-agent correction workflow
-
-Released as `0.7.0`. One new pure domain module,
-`domain/referenceCorrectionWorkflow.ts`, plus its identity counterpart,
-`domain/referenceCorrectionIdentity.ts` - the first stage that composes
-every Prompt 1-7 and v0.1/v0.4/v0.5/v0.6 owner into one traceable
-reference-driven correction cycle. It reimplements none of them: reference
-lifecycle/adequacy (Prompt 1/3), compatibility (Prompt 4), binding (Prompt
-5), fidelity (Prompt 6), bounded context (Prompt 7), runtime comparison
-(v0.4 `compareObservations`), and contract evaluation (v0.5
-`evaluateFrontendContract`) are all called, never re-derived. No new
-persisted artifact family, no CLI surface, no remote AI dependency, and no
-mechanism anywhere in this module (or any module it calls) that edits
-target source.
-
-```ts
-// domain/referenceCorrectionWorkflow.ts
-function prepareReferenceCorrection(input: {
-  reference: ExternalReferenceArtifact;       // must be approved
-  baselineObservation: ObservationArtifact;   // approved baseline / pre-change state
-  baselineContract: PersistentBaselineContract;
-  changeContract: PerChangeContract;
-  bindingDeclarations: readonly ReferenceRuntimeBindingDeclaration[];
-  currentObservation: ObservationArtifact;    // fidelity is measured against this (= baselineObservation for the canonical proof)
-  generatedAt: string; producerVersion: string; projectionProfile: ProjectionProfile;
-}): { ok: true; status: 'handoff-ready'; reviewRequestId: string; fidelity: ReferenceCandidateFidelityEvaluation; handoff: ReferenceCorrectionHandoff }
-  | { ok: true; status: 'blocked-not-evaluated'; reviewRequestId: string; fidelity: ReferenceCandidateFidelityEvaluation }
-  | { ok: false; reason: string };
-
-function reviewReferenceCorrectionAttempt(input: {
-  // ...same reference/baselineObservation/baselineContract/changeContract/bindingDeclarations...
-  reviewRequestId: string;              // must match the id prepareReferenceCorrection returned for this exact semantic review
-  candidateObservation: ObservationArtifact; // fresh, post-edit capture
-  priorAttemptId?: string;
-}): { ok: true; attempt: ReferenceCorrectionAttemptResult } | { ok: false; reason: string };
-```
-
-**Workflow architecture.** A narrowly-scoped coordinator, not a second
-workflow engine: it holds no stage catalog, no job scheduler, and no
-generic orchestration graph. It performs exactly two operations - "prepare"
-(pre-change evidence -> bounded handoff) and "review" (post-edit candidate
--> one composed overall result) - matching this prompt's own explicit
-guidance that the external-edit boundary must remain a visible seam between
-two separate calls, never one command that blocks waiting for an external
-actor.
-
-**New owners introduced**: `prepareReferenceCorrection`,
-`reviewReferenceCorrectionAttempt` (composition only - no new evaluation
-logic), `buildReferenceCorrectionReviewIdentity`/
-`buildReferenceCorrectionAttemptIdentity` (deterministic identity, see
-below), and the plain `ReferenceCorrectionHandoff`/
-`ReferenceCorrectionAttemptResult` result shapes.
-
-**Existing owners reused, verbatim**: `isApprovedExternalReferenceArtifact`
-(Prompt 1), `isValidReferenceRuntimeBindingDeclarations` (Prompt 5),
-`evaluateReferenceCandidateFidelity` (Prompt 6), `projectBoundedAgentContext`
-(Prompt 7, itself now fidelity-aware), `compareObservations` (v0.4),
-`evaluateFrontendContract` (v0.5). None of their internal logic is
-inspected, duplicated, or reimplemented by this module - only their
-top-level results are read.
-
-**Approved-reference/approved-baseline requirement.** `prepareReferenceCorrection`
-and `reviewReferenceCorrectionAttempt` both fail closed (`{ok: false}`) if
-`reference` is not in the `'approved'` lifecycle state (Prompt 1's own
-`isApprovedExternalReferenceArtifact` guard) - an imported-but-unapproved
-reference is never treated as an authoritative target design. Neither
-function ever calls `approveExternalReference`/`approveAndPersistBaseline`
-itself; approval remains the caller's own separate, explicit action.
-
-**Pre-change candidate = approved baseline observation**, for the canonical
-proof: `prepareReferenceCorrection`'s `currentObservation` and
-`baselineObservation` are the same value, so the initial reference fidelity
-can genuinely `FAIL` (measuring the gap between the current, already-
-approved implementation and the desired new design) while the baseline
-itself stays fully valid and approved. A caller's own architecture may
-supply a distinct `currentObservation` only when justified - the workflow
-does not require them to be identical, only that `currentObservation` and
-`candidateObservation` are always independently validated
-`ObservationArtifact`s.
-
-**Preparation (phase A)**: validates the common preconditions (approved
-reference, matching baseline/contract coherence, valid binding
-declarations), evaluates reference fidelity via Prompt 6 against
-`currentObservation`, and - only when that evaluation actually produced a
-result (`state !== 'not-evaluated'`) - projects it into a bounded context
-via Prompt 7/v0.6 and returns the `ReferenceCorrectionHandoff`. A
-`not-evaluated` fidelity (inadequate reference, or reference/candidate
-incompatible state) is reported as `status: 'blocked-not-evaluated'` -
-carrying the full Prompt 6 result for inspection, but never a fabricated
-handoff pretending evidence is adequate. An ambiguous or unavailable
-required binding does **not** block preparation outright - it still
-produces a `handoff-ready` result, with the ambiguity/unavailability
-visible directly in that requirement's own `unavailable`/`binding-
-unavailable` mismatch (Prompt 6's own honest per-requirement reporting,
-unchanged), so the external actor sees exactly why that specific
-requirement cannot yet be assessed.
-
-**The handoff** (`ReferenceCorrectionHandoff`) carries `reviewRequestId`,
-`referenceId`/`referenceRequestId`, `baselineObservationId`,
-`currentObservationId`, the full Prompt 7 `boundedContext` (already
-containing bounded fidelity mismatches, protected/preserved context,
-adequacy/omission/truncation, and - when the caller supplied it - runtime/
-static correlation), and a fixed, four-line `verificationPlan` explaining
-in plain language what will be re-checked after the edit (fresh Chromium
-capture, reference re-evaluation, v0.4/v0.5 re-evaluation, and the exact
-overall-PASS rule) - never reduced to "make it look like the screenshot".
-No raw reference image bytes, no full `ObservationArtifact`, and no source
-excerpt are ever included.
-
-**Handoff persistence: none.** The handoff is a plain, JSON-serializable,
-in-memory value returned directly to the caller - no new writer/reader, no
-new artifact family. A caller that needs the handoff to cross a process/
-session boundary (e.g. to hand it to an external coding-agent process) is
-free to serialize it with its own mechanism; observer product code does not
-own a persisted handoff artifact. This was a deliberate "smallest possible"
-choice: the handoff's only genuinely new identity is `reviewRequestId`
-(already deterministic and recomputable from stable inputs - see below), so
-nothing about it requires observer-managed persistence to remain
-traceable.
-
-**Review identity** (`buildReferenceCorrectionReviewIdentity`): a pure
-function of `{referenceRequestId, baselineObservationId,
-baselineContractId, baselineContractClauses, changeContractId,
-changeContractClauses, bindingDeclarations}` only - never a timestamp,
-never an operational file path. Deliberately hashes each contract's own
-authored `clauses` content, not merely its `baselineId`/`contractId` label:
-unlike this repository's content-derived identities elsewhere (e.g.
-`ObservationArtifact.observationId`), a `PersistentBaselineContract`'s
-`baselineId` and a `PerChangeContract`'s `contractId` are plain, caller-
-authored strings (`approveAndPersistBaseline` persists `contract.baselineId`
-verbatim, never recomputing it from `clauses`) - so two structurally valid
-contracts could in principle share an id while authoring different clauses.
-Hashing clause content directly closes that gap (caught during this
-prompt's own independent-judge review before being reported PASS - see the
-report's Tooling incidents section). `reviewReferenceCorrectionAttempt`
-recomputes this same hash from its own inputs and rejects the call
-(`{ok: false}`) if the caller-supplied `reviewRequestId` does not match -
-this is the mechanism that makes "no hidden baseline change" an enforced
-invariant rather than a documented intention: an attempt claiming to belong
-to a review while actually supplying a different baseline observation,
-baseline contract (id or clause content), per-change contract (id or clause
-content), reference, or binding set can never silently succeed.
-
-**Attempt identity** (`buildReferenceCorrectionAttemptIdentity`): a pure,
-deterministic function of `{reviewRequestId, candidateObservationId}` only
-- deliberately never a fresh random nonce. Every candidate observation
-already carries its own fresh, collision-resistant instance identity (v0.1's
-`buildObservationIdentity`), so hashing it together with the review it was
-captured for gives an attempt id that is both reproducible (the same
-review+candidate pair always yields the same `attemptId`) and guaranteed
-distinct per real capture.
-
-**Attempt history**: caller-managed, not observer-persisted. Because both
-workflow functions are pure (no internal mutable state, no side effects),
-an already-returned `ReferenceCorrectionAttemptResult` can never be
-overwritten by a later call - a caller that keeps every attempt result it
-receives (in memory, in its own log, or in its own storage) has a complete,
-immutable, traceable history for free, linked via each attempt's own
-`reviewRequestId` (shared across all attempts of one review),
-`priorAttemptId` (an optional, purely informational link to the immediately
-preceding attempt, carried through unchanged - never consulted by the
-evaluation logic itself), and `attemptId`.
-
-**Baseline-across-attempts rule**: enforced structurally, not merely
-documented. Every call to `reviewReferenceCorrectionAttempt` requires the
-caller to re-supply `baselineObservation`/`baselineContract` in full, and
-`compareObservations`/`evaluateFrontendContract` are always invoked with
-that same baseline against the fresh `candidateObservation` - there is no
-code path anywhere in this module that compares one candidate against a
-prior candidate instead. Combined with the `reviewRequestId` coherence
-check above, a caller cannot silently swap in a different baseline between
-attempts of the same review without the call being rejected.
-
-**Overall result composition.** `ReferenceCorrectionOverallState =
-'not-evaluated' | 'pass' | 'fail'`:
-
-- `fidelity.state === 'not-evaluated'` -> overall `'not-evaluated'` - Prompt
-  6's own explicit blocked state is preserved exactly, never collapsed into
-  an ordinary `'fail'`.
-- otherwise, `fidelity.state === 'pass' && contractEvaluation.overallVerdict === 'PASS'`
-  -> overall `'pass'`; anything else -> overall `'fail'`.
-
-A structurally-incomparable baseline/candidate pair is *not* given its own
-third overall bucket - v0.5's own `evaluateFrontendContract` already
-returns `'FAIL'` (never `'PASS'`) for that case, per its own established,
-unmodified precedent, and this workflow reuses that decision rather than
-re-litigating it. `approvalEligible` is a plain, read-only boolean
-(`true` iff `overallState === 'pass'`) - it is never itself an approval
-action; the caller must still invoke the existing explicit
-`approveAndPersistBaseline`/`approveExternalReference` owners separately,
-and neither is ever called from within this module.
-
-**Correction iteration**: `reviewReferenceCorrectionAttempt` is called once
-per candidate; the caller decides whether and when to call it again after
-another external edit. There is no loop, no polling, no automatic retry,
-and no mechanism in this module that itself waits for or drives an external
-implementation step - the production boundary between "prepare a handoff"
-and "review a candidate" is the explicit seam a human or an external
-process controls.
-
-**Source-editing boundary**: absolute. Neither this module nor anything it
-calls opens, reads, parses, or writes any target source file; both public
-operations accept only already-captured `ObservationArtifact`s and already-
-approved contract/reference artifacts. Real-Chromium candidate capture is
-always the caller's own responsibility, through the existing, unmodified
-observation pipeline (`runBrowserCapture`/`buildObservationArtifact`, the
-same functions `application/observationPersistence.ts#observe` already
-uses) - Prompt 8 adds no second browser adapter, screenshot engine, target
-resolver, or evidence-capture path.
+# Contracts
+
+## Visual-change workflow artifact (`1.0.0`, v0.10 Batch 1)
+
+`my-frontend-observer/visual-change-workflow` is the immutable Observer-owned history envelope for one frozen visual-change request. It records a deterministic `visualChangeRequestId`, a fresh `visualChangeWorkflowId`, optional forward-only `supersedesVisualChangeWorkflowId`, exact references to existing canonical evidence, zero to twenty bounded attempt records, optional activation/governance result references, producer metadata, and creation provenance.
+
+The two entry modes are exactly `actual-frontend` and `reference`. Reference mode stores validated explicit runtime binding declarations in canonical `bindings.json`; the manifest pins its SHA-256 and declaration count. Actual mode never writes that file. Project-relative evidence references must remain contained portable paths; source artifacts and media are referenced rather than copied.
+
+Request identity hashes semantic scope only. It excludes timestamps and operational storage locations. Workflow instance identity is fresh for every explicit persistence. Attempt identity is deterministic over the visual-change request ID and candidate observation ID. Human review state is exactly `pending`, `correction-requested`, `accepted`, or `abandoned`; this foundation validates structure but does not implement the later acceptance rule or execute checks.
+
+The v0.10 Batch 2 application composition explicitly activates either the frozen per-change contract or the frozen approved reference and workflow-owned bindings in project acceptance. Activation and restoration preserve unrelated configuration, use compensating atomic writes across mutable project configuration and immutable workflow revisions, and refuse acceptance drift. A workflow check resolves an alias only when its catalog identity and artifact location exactly match the frozen baseline, then invokes the existing `checkProject` owner once. Only a canonical result containing both baseline and candidate summaries can append a pending attempt revision; the snapshot is a bounded direct projection of that result and does not repeat evaluation.
+
+The v0.10 Batch 3 Viewer exposes bounded workflow inspection at `GET /api/visual-changes/:handle/view` in both standalone and project-aware sessions. Create, activate, check, and restore POST operations are project-aware only, reuse the existing in-memory authoring capability and request guards, accept no filesystem paths, and delegate to the Batch 2 application service. Every new response is `no-store`. Successful immutable mutations return the exact new workflow ID so the Viewer can refresh and reselect that revision without guessing. The Viewer protocol remains `1.3.0`.
+
+Project-aware `check` resolves and validates its immutable baseline before
+candidate capture. Candidate URL, viewport, targets, and ordinary operational
+settings still come from project configuration. The check replays only the
+validated baseline request's optional `scrollScenario` and `explicitState`
+through `normalizeRequest` and the canonical observer. Scroll is executed by
+the normal browser capture path. `explicitState` replay retains the
+caller-declared comparison identity only; it never infers or establishes
+browser, application, theme, or session state. Project config remains schema
+1.1.0 and does not accept either field; `init` and normal `capture` remain
+project-config-only.
+
+The v0.10 Batch 4 actual-frontend entry route promotes only explicitly selected, saved, confirmed, canonically promotable runtime intent without activating project acceptance. It freezes the exact resulting contract instance with the saved annotation, source observation, and configured persistent baseline contract through the Batch 2 workflow-creation owner. Repeated equivalent starts share `contractRequestId` while receiving fresh contract, visual-change request, and workflow instance identities. Activation remains a later explicit workflow action.
+
+Reference entry freezes only an exact approved reference, an annotation authored
+against that exact instance, an exact baseline observation, and explicitly
+authored valid bindings. Adequacy, compatibility, complete required-region
+coverage, and canonical binding evaluation fail closed. Imported references,
+inferred bindings, and session bindings are not executable workflow scope.
+
+`VisualChangeAgentHandoff` uses handoff kind
+`my-frontend-observer/visual-change-agent-handoff` and version `1.0.0`. It is a
+bounded non-artifact transfer contract and is never discovered or persisted as
+Observer evidence. It includes confirmed scope, Observer-owned bounded context,
+optional unchanged supplemental context, the exact post-edit check instruction,
+and optional non-authoritative orchestrator correlation.
+
+The current cycle is derived from the latest attempt. A pending attempt blocks
+another check or handoff until explicit correction, acceptance, or abandonment.
+Only the latest canonical PASS may be accepted. Review changes only the latest
+attempt's review object in a fresh workflow revision. Governance references may
+be recorded only after acceptance and only for already-persisted canonical
+approval results; they do not perform approval or change project configuration.
+No existing evidence schema changed for v0.10.
+
+## Current contracts
+
+The observation artifact contract is published in the current
+`my-frontend-observer@0.7.0` package and proven both from the source checkout
+and from the packed npm tarball, on Windows, Linux, and macOS. The observation
+schema is `1.2.0` (see "v0.2 target contract" and "v0.3 scroll scenario
+contract" below):
+
+- artifact kind `my-frontend-observer/observation`, schema version `1.2.0`
+  (independent of the package version);
+- one artifact root per observation, `<outputLocation>/<observationId>/`,
+  containing exactly `manifest.json` (the full `ObservationArtifact`, with
+  page/target evidence embedded inline) and `screenshot.png` - there is no
+  separate `evidence.json`;
+- `manifest.json` is written last, after `screenshot.png`, via one atomic
+  directory rename, so a consumer never observes a partially-written
+  artifact; a filesystem failure anywhere in that sequence reports the
+  `artifact-write-failure` diagnostic and leaves no completed artifact;
+- internal artifact references (e.g. `screenshot.png`) are relative to the
+  artifact root, never an absolute machine path; the observation's logical
+  identity is its `observationId`, not its filesystem location;
+- evidence states `available`, `unavailable`, `not-applicable`, `partial`;
+  evidence sources `browser`, `computed-browser`, `derived`;
+- a stable diagnostic vocabulary (`src/domain/diagnostics.ts`) and completion
+  states `complete`, `partial`, `warning`, `invalid-request`, `fatal`
+  (`src/domain/completion.ts`);
+- observation/request identity, producer/package identity, and browser
+  provenance are all present in every persisted manifest.
+
+This contract is implemented and published; no public programmatic-API
+compatibility promise has been made for the observation engine itself. v0.6
+additionally publishes the bounded-agent-context/correlation programmatic surface
+described later in this document.
+
+## v0.2 target contract (shipped as part of this release)
+
+v0.2 introduces a canonical target-configuration model: each configured target has a stable
+observer-level `name` plus an ordered array of bounded `locators`
+(`role`, `id`, `data-attribute`, `semantic-element`, `css`, `text`). This
+identity is distinct from both the browser locator definition that resolves
+it and any source-code identity. The legacy `{name, selector}` shape remains
+accepted and normalizes to a one-item `css` locator, so every published
+`0.1.0` CLI invocation continues to work unchanged. Locator precedence is the
+configured array order; resolution stops on the first unique match, on any
+ambiguous match (never falling through to a later locator), or on an
+unevaluable locator - never silently. All six frozen locator kinds are now
+resolved against a real Chromium page (`role` via Playwright's accessibility-
+role/name locator with exact name matching, `id`/`data-attribute` via exact
+CSS attribute-equals matching that never reinterprets the configured value as
+selector syntax, `semantic-element` via the frozen tag set, `css` via the
+existing v0.1 behavior, `text` via exact-text matching only); every kind
+converges on the same measurement path, so locator strategy never changes the
+resulting target evidence shape.
+
+Each resolved target's evidence record additionally carries three bounded
+fields: `semanticState` (a first family of `disabled`/`expanded`/
+`checked`/`selected`/`pressed`/`current` values read from the element's own
+native form-control properties and explicit `aria-*` attributes - a key is
+present only when the browser exposes that state as applicable to this
+element, so an explicit `false` is always distinguishable from "not
+applicable"; `not-applicable` when no supported state applies at all);
+`landmark` (derived only from the already-captured browser-exposed
+role - never from locator kind or HTML tag - against the standard landmark
+role set `banner`/`navigation`/`main`/`complementary`/`contentinfo`/`form`/
+`region`/`search`); and `containment` (bounded DOM containment checked only
+among the other explicitly configured targets in the same observation, in
+configured order, never a layout/relationship graph - `available` when every
+other configured target was itself resolved and checked, `partial` when one
+or more could not be, `unavailable` when the target itself never resolved).
+Stable observer target identity is proven, not just declared: the same
+target configuration produces the same `requestId` across repeated
+observations (with a fresh `observationId` each time); changing a target's
+locator strategy while keeping its stable name changes `requestId` but not
+the `targetEvidence` key; and actual runtime disappearance of a
+still-configured target changes only its resolution status, never the
+`requestId`.
+
+The full canonical semantic target model above is reachable through the
+real public CLI: `my-frontend-observer observe --targets-file <json-file>`
+supplies the structured `{ "targets": [...] }` collection (see
+`docs/COMMANDS.md` "Structured semantic targets") as an alternative to the
+existing `--target id=css-selector` shorthand - the two are mutually
+exclusive per invocation, and both converge on the same
+`normalizeRequest()`/browser-resolver/artifact path, so a semantic
+observation produces exactly the same `manifest.json` shape as a
+CSS-shorthand one. Schema `1.1.0` was the v0.2 published artifact schema;
+schema `1.2.0` has been emitted since v0.3 and remains the observation schema
+in the current published v0.7.0 package, for both target-input modes
+(target semantics are unchanged from v0.2 - see the v0.3 scroll scenario
+contract below for what schema `1.2.0` actually adds). `--targets-file`'s
+local input path is never part of the persisted request identity or
+artifact.
+
+## v0.3 scroll scenario contract (shipped as part of this release)
+
+v0.3 introduces one optional, additive request/evidence concern: a bounded
+runtime scroll scenario, schema `1.2.0`.
+
+A normalized request may carry `scrollScenario: { action }` with exactly one
+of two frozen action kinds:
+
+- `{ "kind": "window-scroll-by", "deltaX": <int>, "deltaY": <int> }`
+- `{ "kind": "target-scroll-by", "target": "<stable target name>", "deltaX": <int>, "deltaY": <int> }`
+
+`deltaX`/`deltaY` are signed integers bounded to `[-20000, 20000]`; at least
+one must be non-zero. `target-scroll-by.target` refers only to an existing
+stable configured target `name` (never a selector) and resolves through the
+same canonical `resolveConfiguredTargets` algorithm every v0.2 locator kind
+already uses - there is no second target-resolution path. A request with no
+scenario normalizes and identifies exactly as it did before v0.3.
+
+Execution (both action kinds share one code path): perform the immediate,
+non-smooth scroll (`window.scrollBy`/`element.scrollBy`, `behavior:
+'instant'`) on the already-navigated, already-ready page; wait exactly two
+`requestAnimationFrame` cycles; capture a final runtime snapshot. No second
+browser, page, or navigation is ever created. The resulting scroll position
+is browser-authoritative and may be clamped by document/element boundaries;
+a scenario producing no movement is still a valid, successfully persisted
+observation.
+
+The scenario evidence lives entirely inside the existing `manifest.json` as
+one additional optional `scrollScenarioEvidence` field on `ObservationArtifact`
+- there is no separate `scroll.json`/`scenario.json`. It contains:
+
+- `initial`/`final`: bounded `ScrollRuntimeSnapshot`s (window `scrollX`/
+  `scrollY`; the browser's own scrolling-root/`documentElement`/`body`
+  metrics; per-configured-target `scrollTop`/`scrollLeft`/`scrollWidth`/
+  `scrollHeight`/`clientWidth`/`clientHeight`, actual overflow, bounding
+  rectangle, and viewport relation);
+- `transition`: bounded before/after change evidence (window scroll deltas;
+  per-target `scrollTop`/`scrollLeft`/bounding-position/viewport-relation
+  changes; `enteredViewport`/`leftViewport`) - never a generic recursive
+  diff, and a target is simply omitted when either side's evidence isn't
+  itself usable (e.g. it never resolved);
+- `scrollOwner`: one derived `EvidenceField<ScrollOwnerInterpretation>`
+  (`document` | `target:<stable-name>` | `none` | `indeterminate`), always
+  `source: "derived"` with non-empty `derivedFrom` naming the exact
+  contributing scroll-position measurements. Ownership is derived only from
+  observed `scrollTop`/`scrollLeft`/`window.scrollX`/`window.scrollY`
+  changes - never from bounding-rectangle movement (which moves for every
+  configured target whenever the document scrolls), computed overflow,
+  `position: fixed`/`sticky`, or DOM hierarchy.
+
+Actual dimensional overflow (`scrollWidth > clientWidth` /
+`scrollHeight > clientHeight`) is always reported separately from the
+computed `overflow-x`/`overflow-y` CSS declaration; a declared
+`overflow: auto` container with content that fits produces
+`horizontalOverflow`/`verticalOverflow: false`. Viewport relation
+(`above`/`intersecting`/`below`, `intersectsViewport`, `fullyWithinViewport`)
+is derived only from bounding geometry plus viewport size, relative to the
+browser viewport; a hidden/non-rendered target's viewport relation is
+`not-applicable`, never a fabricated geometry claim - hidden and offscreen
+remain distinct evidence concepts, and the existing `target-hidden`
+diagnostic is unaffected.
+
+The ordinary, already-existing `pageEvidence`/`targetEvidence`/
+`screenshot.png` for a scenario observation always describe this same final
+post-action state, never the pre-action state.
+
+The scenario request participates in `requestId`; the runtime result
+(actual scroll distance, clamping, or scroll-owner outcome) never does. The
+public entry point is `my-frontend-observer observe --scroll-scenario-file
+<json-file>` (see `docs/COMMANDS.md`); the file supplies the scenario value
+directly, and its local path is operational input only, exactly like
+`--targets-file`'s path - never persisted, never part of request identity.
+
+## v0.4 comparison contract (shipped as part of this release)
+
+**Current status: shipped as part of the published `my-frontend-observer@0.4.0`
+package and unchanged through the current `0.7.0` release.** Observation
+schema remains `1.2.0`. Comparison is a distinct artifact kind and schema,
+never a bump to the observation schema:
+
+- artifact kind: `my-frontend-observer/comparison`;
+- comparison schema: `1.0.0`.
+
+**Geometry tolerance**: `ComparisonConfig.geometryTolerancePx`, default
+`0.5` CSS px, bounded `[0, 10]`. Suppresses insignificant subpixel noise
+only - never a design contract, never permission for a change.
+
+**Layout relationship graph**: `deriveLayoutRelationships(observation,
+options?)` derives, per observation, a bounded `LayoutRelationshipGraph`
+among configured targets only (≤20 targets, ≤190 unordered pairs):
+horizontal order (`left-of`/`right-of`/`horizontally-overlapping`),
+vertical order (`above`/`below`/`vertically-overlapping`), area overlap
+(`overlaps`/`does-not-overlap`), relative width (`wider-than`/
+`narrower-than`/`equal-width-within-tolerance`), geometric fit
+(`fits-inside`/`does-not-fit-inside` - geometry-only, deliberately distinct
+from DOM containment), vertical sequencing (`follows-vertically`), and one
+page-level relationship (`document-width-fits-viewport`/
+`document-width-exceeds-viewport`). Every relationship carries explicit
+evidence-path provenance back to the source observation. A configured
+target lacking usable geometry is listed as honestly unresolved
+(`not-found`/`ambiguous`/`unavailable`/`hidden`), never fabricated as a
+zero-sized region.
+
+**Comparability**: evaluated before any rendered difference, using exactly
+three states (`comparable`/`comparable-with-warnings`/`incomparable`) with
+structured reasons, never a bare boolean. Hard incompatibilities (page URL,
+viewport, browser engine, scroll-scenario configuration mismatch) force
+`incomparable`; producer-version, browser-version, and target-configuration
+differences are warning-only; theme/authenticated-state/application-state
+identity are recorded as `unassessed` dimensions the observer does not yet
+model - never silently claimed identical. An `incomparable` result still
+persists a structurally valid `ComparisonArtifact` with empty rendered
+differences, not a fabricated comparison.
+
+**Difference categories**: `appeared`/`disappeared` (only for a stable
+target name configured on both sides, transitioning between a definite
+`not-found` and `matched` resolution status - never for a target merely
+added/removed from configuration, which is its own separate
+`configurationChanges` entry), `moved`/`resized` (tolerance-aware, a target
+may be both), `visibility-changed`, `clipping-changed` (reusing the
+canonical `deriveTargetClipping` helper, never re-derived), `horizontal-
+overflow-changed`/`vertical-overflow-changed` (actual dimensional overflow,
+reusing the existing `deriveOverflowEvidence` helper - never inferred from
+a CSS declaration alone), `containment-changed` (reusing existing v0.2
+`TargetContainment` evidence), `page-size-changed`, `scroll-owner-changed`
+(comparing `scrollScenarioEvidence.scrollOwner` only when scenario
+*configuration* already matched), `relative-position-changed` (a relation
+in the horizontal-order/vertical-order/area-overlap families changed - kept
+distinct from plain absolute target movement) and `relationship-changed`
+(every other relationship-family transition). Relationship changes are
+matched by structural identity (family + subject/related target, or the
+page-level key), never by array position.
+
+**Explicit dependency evidence**: `ComparisonConfig.expectedDependencies`
+lets a caller declare an expected relationship between two targets' numeric
+properties (`x`/`y`/`width`/`height`) and directions (`increase`/
+`decrease`/`change`/`unchanged`), always carrying `source:
+"explicit-config"`. The observer never synthesizes a declaration from
+observed co-change. Each declaration evaluates independently to exactly one
+of `consistent`/`not-observed`/`contradictory-to-declaration`/
+`unavailable` - never a causal claim (no `causedBy`/`causalConfidence`/
+`causalScore`/`dependencyStrength`) and never a PASS/FAIL/approval verdict.
+That distinction (evidence vs. contract verdict) is the boundary between
+v0.4 and v0.5+.
+
+**Comparison identity**: `comparisonRequestId` is a pure, deterministic
+function of `{beforeObservationId, afterObservationId, normalized
+ComparisonConfig}` - direction-sensitive (`compare(A, B) !==
+compare(B, A)`), and never includes an operational filesystem path.
+`comparisonId` is fresh per execution (same pattern as `observationId`).
+
+**Source references**: the comparison artifact retains enough logical
+identity to trace back to its authoritative source observations
+(`observationId`, `requestId`, `producer`, `observationSchemaVersion`, and
+the source `screenshot.path`) without embedding the full
+`ObservationArtifact` or copying screenshot bytes. The persisted comparison
+directory contains `manifest.json` only.
+
+The public entry point is `my-frontend-observer compare --before <root>
+--after <root> --output <directory> [--config-file <json-file>]` (see
+`docs/COMMANDS.md`) - comparison itself never launches a browser.
+
+## v0.5 frontend contract and evaluation (shipped as part of this release)
+
+Downstream of the v0.4 observation/comparison/relationship evidence above,
+`src/domain/frontendContracts.ts` freezes the v0.5 contract/change-scope
+model, `src/domain/frontendContractIdentity.ts` freezes deterministic
+contract/baseline/clause identity, and `src/domain/frontendContractEvaluation.ts`
+implements the one canonical pure evaluation engine. Baseline/per-change
+contract persistence, evaluation-artifact persistence, explicit baseline
+approval, and public CLI exposure are all implemented and shipped (see
+"v0.5 contract and evaluation persistence" and "v0.5 public contract/
+evaluation commands" below).
+
+**Contract classes**: a `PersistentBaselineContract` (append/supersession-based
+history via an optional `supersedesBaselineId`) and a `PerChangeContract`
+(the allowed scope of one requested change). Both share `artifactKind:
+"my-frontend-observer/frontend-contract"` and `schemaVersion: "1.0.0"` - an
+independent family from the observation (`1.2.0`) and comparison (`1.0.0`)
+schemas; the frontend-contract schema constant happens to share the version
+string `1.0.0` with comparison's by coincidence only.
+
+**Four authored categories, one derived classification**: every per-change
+clause is authored as exactly one of `requested`, `expected-dependent`,
+`protected`, or `preserved`. `unexpected` is a fifth, *derived-only*
+classification the evaluator produces for a meaningful rendered difference no
+active clause accounts for - it can never be authored as a permission.
+
+**Bounded contract primitives**: 15 frozen `ContractPrimitive` kinds cover
+visibility, clipping, width bounds, non-overlap, relative width, vertical
+sequence, geometric fit (explicitly distinct from DOM containment),
+document-width-vs-viewport, scroll ownership, initial-viewport position,
+relationship-unchanged, and property-unchanged/increases/decreases - a closed
+vocabulary, never a generic expression language.
+
+**Contract tolerance**: `exact` / `absolute-px` / `percent`, independent of
+`ComparisonConfig.geometryTolerancePx` (which only suppresses insignificant
+comparison noise and is never contract authorization). Percent tolerance's
+denominator is the absolute before-value.
+
+**Required vs. permitted expected-dependent**: `required` clauses must occur
+compliantly to pass; `permitted` clauses accept no change or a compliant
+change, and fail only on a strictly contradictory change.
+
+**Evaluation result vocabulary**: each clause resolves to `pass` / `fail` /
+`unavailable` (with a required non-empty reason - required evidence gaps and
+an `incomparable` source comparison never fabricate a `pass`) / `conflict`
+(with at least two `conflictingClauseIds` - covers both an unresolved
+baseline/per-change contradiction and an unknown `supersedesBaselineClauseIds`
+reference). The overall verdict is `PASS` only when every clause result is
+`pass` and no unexpected change remains; otherwise `FAIL` - there is no
+partial-pass scoring.
+
+**Explicit supersession, never inferred**: a per-change clause may list
+`supersedesBaselineClauseIds` to remove specific baseline clauses from active
+evaluation. Two clauses that structurally contradict each other on the same
+(target, property) without explicit supersession produce a `conflict`, never
+a silent preference for one side.
+
+**Reuses existing v0.4 evidence directly**: the evaluator consumes an
+already-computed `ComparisonArtifact` (`differences`, `relationshipChanges`,
+`relationshipsBefore`/`relationshipsAfter`, `comparability`) and the source
+`ObservationArtifact` pair - it never re-launches a browser, re-resolves a
+target, or reimplements clipping/relationship/scroll-owner derivation.
+Unexpected-change derivation reads `ComparisonArtifact.differences` only
+(which already includes one difference per relationship change), so a single
+logical transition is never double-counted.
+
+## v0.5 contract and evaluation persistence (shipped as part of this release)
+
+Persistence consumes the frozen v0.5 domain above; it never redefines it.
+`src/artifacts/frontendContractArtifactWriter.ts`/`frontendContractArtifactReader.ts`
+persist and read both `PersistentBaselineContract` and `PerChangeContract`
+symmetrically (both already share `CONTRACT_ARTIFACT_KIND`/`CONTRACT_SCHEMA_VERSION`,
+so one writer/reader pair serves both contract classes) as
+`<outputLocation>/<baselineId|contractId>/manifest.json`, following the same
+atomic-write discipline as `artifacts/artifactWriter.ts`/`artifacts/comparisonArtifactWriter.ts`
+(sibling temporary directory, then one atomic rename; an existing directory at
+the final identity is a genuine collision and is rejected, never overwritten -
+prior baseline history is never rewritten). `src/artifacts/comparisonArtifactReader.ts`
+is a new Batch 3 addition (no comparison reader existed before) mirroring
+`artifacts/artifactReader.ts`'s discipline exactly, changing no comparison
+semantics and keeping comparison schema `1.0.0`.
+
+**Evaluation artifact envelope**: Batch 1 froze the evaluation-result
+vocabulary (`ClauseEvaluationResult`, `OverallVerdict`) but not a persistable
+envelope, so `src/domain/frontendContractEvaluationArtifact.ts` adds exactly
+that - `artifactKind: "my-frontend-observer/frontend-contract-evaluation"`,
+`schemaVersion: "1.0.0"` (its own independent family, distinct from
+observation/comparison/frontend-contract), an `evaluationId`/`evaluationRequestId`
+pair, bounded `before`/`after` source-observation references, and
+`comparisonId`/`comparisonRequestId` plus `contracts: {baselineId,
+contractId}` references - never an embedded `ObservationArtifact` or copied
+screenshot. It reuses `ClauseEvaluationResult`/`OverallVerdict`/
+`UnexpectedChangeResult` unchanged and contains no evaluation logic itself.
+`evaluationRequestId` is a deterministic function of `{baselineId,
+contractId, beforeObservationId, afterObservationId, comparisonRequestId}`
+(`frontendContractIdentity.ts#buildFrontendContractEvaluationRequestIdentity` -
+deliberately `comparisonRequestId`, not the fresh-per-execution
+`comparisonId`, so semantically identical evaluations share an identity);
+`evaluationId` reuses the existing generic `buildFrontendContractInstanceIdentity`
+unchanged. `src/artifacts/frontendContractEvaluationArtifactWriter.ts`/
+`frontendContractEvaluationArtifactReader.ts` persist/read it with the same
+atomic-write discipline as above.
+
+**Application seam**: `src/application/frontendContractEvaluationService.ts#evaluateAndPersist`
+calls the existing pure `evaluateFrontendContract` exactly once and - only
+for a structurally constructible result, whether the verdict is `PASS` or
+`FAIL` - persists exactly one evaluation artifact; an `{ok: false}` evaluator
+result (evidence could not be constructed into an evaluation at all) is never
+persisted as a fabricated artifact. `evaluateAndPersistFromArtifactRoots` is
+the future-CLI-facing wrapper: it reads two observations through the existing
+`readObservationArtifact` (never a second observation reader), the
+comparison and the two contracts through the readers above, then delegates
+to `evaluateAndPersist` exactly once.
+
+## v0.5 public contract/evaluation commands (shipped as part of this release)
+
+Three public commands expose the persistence/evaluation contract above (see
+`docs/COMMANDS.md` for exact flags/output/exit behavior, not duplicated
+here):
+
+- `approve-baseline` → `frontendContractPersistenceService.ts#approveAndPersistBaseline`
+  → validates a `PersistentBaselineContract` and its `sourceObservation`
+  coherence against a supplied observation artifact → persists via
+  `frontendContractArtifactWriter.ts`. The only baseline-approval act in the
+  observer.
+- `save-change-contract` → `frontendContractPersistenceService.ts#persistPerChangeContract`
+  → validates a `PerChangeContract` (rejecting a baseline contract, an
+  authored `unexpected` category, or any other structural violation) →
+  persists via the same writer. Persistence only, never approval.
+- `evaluate-contract` → `frontendContractEvaluationService.ts#evaluateAndPersistFromArtifactRoots`
+  → `evaluateFrontendContract` exactly once → `frontendContractEvaluationArtifactWriter.ts`
+  exactly once. `--enforce` affects only the process exit status for an
+  already-persisted `FAIL` verdict.
+
+No command infers baseline approval or supersession automatically - not
+`compare`, not a `PASS` evaluation, not any artifact writer.
+
+This full command sequence is proven against real Chromium observations (not
+hand-constructed artifacts) - see "v0.5 real-browser workflow proof" below.
+
+## v0.5 real-browser workflow proof (shipped as part of this release)
+
+`tests/browser/cliFrontendContracts.test.ts` and
+`scripts/dev/builtCliFrontendContractsBrowserSmoke.mjs` drive the complete
+`observe` → `approve-baseline` → `save-change-contract` → `observe` →
+`compare` → `evaluate-contract` sequence against a real disposable local HTTP
+fixture and real Chromium, proving two scenarios:
+
+- a fully successful contract change - a real observed navigation-width
+  decrease and workspace-width increase, both satisfying their authored
+  `requested`/`expected-dependent` clauses, an unchanged `protected` rail
+  width, and an unclipped `preserved` navigation - overall `PASS`;
+- the "milestone signature" failure - the same locally successful requested
+  change (navigation shrinks, workspace expands, both still `pass`)
+  co-occurring with a genuine `protected` right-rail width regression (a real
+  `resized` comparison difference) and a genuine `preserved` navigation
+  clipping regression (a real `clipping-changed` difference, `not-clipped` →
+  `clipped`) - overall `FAIL`.
+
+Both scenarios confirm: `--enforce` changes only the process exit status
+(`0` without it, nonzero with it) for the identical persisted
+`evaluationRequestId`/`clauseResults`; every source observation and
+comparison artifact is byte-identical before and after evaluation; the
+evaluation directory contains `manifest.json` only (no copied screenshot);
+and no operational filesystem path is ever serialized into a persisted
+manifest. This is real-browser evidence layered on top of the CLI-level
+proof in `tests/unit/cliFrontendContracts.test.ts` and the Chromium-free
+`scripts/dev/builtCliFrontendContractsSmoke.mjs` - it does not replace them.
+
+## v0.6 bounded agent context and correlation contract (released as `0.6.0`)
+
+**Current status: released as package version `0.6.0`, tag `v0.6.0`, from
+the canonical `canonicalization/v0.6` lineage.** Bounded-agent-context is a new, independent
+artifact-kind family, schema `1.0.0` (`BOUNDED_AGENT_CONTEXT_ARTIFACT_KIND =
+"my-frontend-observer/bounded-agent-context"`) - never a bump to
+observation/comparison/frontend-contract/evaluation schemas, which remain
+`1.2.0`/`1.0.0`/`1.0.0`/`1.0.0` respectively. Unlike those families, there is
+**no disk artifact writer/reader** for bounded-agent-context: it is a pure
+programmatic contract and derivation layer, exported from `src/index.ts`
+only.
+
+**Bounded runtime projection**
+(`src/domain/boundedAgentContextProjection.ts#projectBoundedAgentContext`)
+produces a `BoundedRuntimeTargetProjection` from already-captured v0.1-v0.5
+evidence, containing: page/viewport identity; stable target identities;
+important geometry and runtime behavior; layout/behavior relationships;
+before/after differences; contract clause results; requested/expected-
+dependent/protected/preserved scope - reusing `src/domain/
+frontendContracts.ts`'s existing clause types verbatim, never a
+reimplementation; diagnostics; screenshot/artifact references; provenance;
+and explicit `OmissionRecord`/`TruncationRecord` metadata with bounded
+aggregate-cap summarization once a limit is reached.
+
+**Adequacy**: every projection carries an `Adequacy` value
+(`adequate`/`partial`/`inadequate`) plus a structured, closed
+`ADEQUACY_REASON_CODES` vocabulary - evidence existing is not itself
+adequacy; a required omission or an `incomparable`/unavailable upstream
+source is reflected honestly rather than silently reported as sufficient.
+
+**Runtime/static correlation**
+(`src/domain/boundedAgentContextCorrelation.ts#deriveRuntimeStaticCorrelations`/
+`attachRuntimeStaticCorrelations`) evaluates each stable runtime target
+against caller-supplied candidate static-evidence records into exactly one of
+three outcomes: `correlated`, `ambiguous` (multiple competing candidates,
+all preserved and visible - never silently resolved to one), or
+`unavailable` (no supported candidate). The module accepts only plain,
+already-retrieved candidate records and has no dependency on
+`@dailephd/my-dev-kit` - the audit preceding implementation found no generic
+static-side retrieval capability actually missing (see `docs/ROADMAP.md` v0.6
+"Dependency direction"). A runtime target identity is carried through
+verbatim; correlation never produces a `sourceOwner`/`causedBy`-shaped field,
+so a stable runtime identity is never silently reported as source ownership.
+
+**Identity**: `src/domain/boundedAgentContextIdentity.ts#buildBoundedAgentContextRequestIdentity`/
+`buildBoundedAgentContextInstanceIdentity` follow the same
+canonicalize+sha256(+opaque-nonce) pattern as `comparisonIdentity.ts`/
+`frontendContractIdentity.ts`: a deterministic logical identity distinct from
+a fresh per-execution instance identity.
+
+**Export/public boundary**: `src/index.ts` exports the complete
+bounded-agent-context/correlation type and function surface as a
+programmatic library contract. There is no CLI command (`observe`/`compare`/
+`approve-baseline`/`save-change-contract`/`evaluate-contract` remain the only
+public commands) and no orchestrator/lab code in this repository - bounded
+runtime-evidence consumption by `my-dev-kit-orchestrator` and exact
+readers/fixtures/evaluation in `my-dev-kit-lab` are separate sibling-
+repository deliverables outside `my-frontend-observer`'s public surface.
+
+**Compatibility evidence**: cross-repository neutral verification (observer
+`514bf3bb513764815a0a5b9e508d5836aa7d7fd8`, orchestrator `9473e4c`, lab
+`271e72c`) passed with 6/6 requirement coverage and no known product
+blockers; on the canonical worktree, `npm run typecheck`, `npm run lint`,
+`npm test` (627 tests), `npm run test:browser` (120 tests), `npm run
+test:security`, `npm run build`, and `npm run check:docs` all pass.
+
+## v0.7 external visual-reference contract direction (preserved through released v0.10)
+
+External visual-reference support is released as package version `0.7.0`
+(see "v0.7 Prompt 1" through "v0.7 Prompt 8" below for the exact contract).
+The exact public type names, artifact kinds, schema versions, persistence
+layout, and command/programmatic entry points were designed during v0.7
+implementation from current repository precedent, following the constraints
+below. v0.8 (released as package version `0.8.0` - see
+`docs/CURRENT_STATE.md`) has preserved them. v0.9 is released and preserves
+them. The implemented and released v0.10 workflow preserves them too.
+
+**Distinct evidence domain**: an external reference is desired-design evidence,
+not an `ObservationArtifact` and not the "before" side of a v0.4
+`ComparisonArtifact`. Reference design vs candidate is distinct from both
+before vs after comparison and frontend-contract evaluation. The implementation
+must not fake this distinction by wrapping a raster image in an observation
+shape.
+
+**Reference identity and provenance**: a future reference contract must preserve
+a deterministic logical reference identity/version where appropriate, source
+image reference plus dimensions/format, provenance, bounded region definitions,
+applicable viewport/theme/application-state identity, authored design intent,
+relationship/style evidence where supported, limits/diagnostics, and approval/
+supersession history. Operational filesystem paths must not become semantic
+identity. A raw imported image never silently becomes an approved active
+reference.
+
+**Reference regions and runtime targets stay distinct**: a reference region
+must have its own identity and coordinate semantics. Reference-region to runtime-
+target association must be explicit and capable of representing ambiguity or
+unavailability. Runtime target identity and reference identity must never
+silently become static source ownership; static association still goes through
+the v0.6 runtime/static correlation boundary.
+
+**Applicability before fidelity**: viewport, theme, application state, and
+other selected compatibility dimensions must be evaluated before ordinary
+reference/candidate differences are produced. If the reference and candidate
+represent different intended states, the result must be explicitly incompatible
+or incomparable rather than filled with fabricated visual failures. Planning
+should reuse or extend the canonical v0.4 comparability conventions where they
+mean the same thing rather than invent an unrelated reference-only state model.
+
+**Canonical contract semantics remain authoritative**: executable reference-
+derived requirements must map into the existing v0.5 authored categories
+`requested`, `expected-dependent`, `protected`, or `preserved`. The derived-only
+`unexpected` classification remains derived-only. Informational or unassessed
+reference evidence may stay outside executable contract evaluation until
+explicitly promoted. A second reference-only PASS/FAIL taxonomy is forbidden.
+
+**Tolerance separation**: reference-fidelity tolerances are not automatically
+the same as v0.4 `ComparisonConfig.geometryTolerancePx` or v0.5 contract
+tolerances. Planning must define property-specific semantics for reference
+geometry, spacing, selected style evidence, text/font rendering differences,
+asset-sensitive regions, and optional image similarity. One global pixel-perfect
+threshold is not an acceptable contract.
+
+**Structured evidence first**: geometry, relationships, authored requirements,
+applicability, provenance, and selected bounded style/asset evidence remain
+inspectable primary evidence. Screenshot-region or image-similarity evidence may
+supplement them where reliable, but pixel similarity alone must not determine
+success and must never override active baseline/per-change contracts.
+
+**Bounded correction evidence**: future reference/candidate results must support
+a bounded projection suitable for coding-agent correction, such as reference
+measurement, candidate measurement, delta, failed relationship/style condition,
+relevant reference/runtime identities, provenance, and active protected/
+preserved constraints. Heavy reference image bytes should be referenced, not
+copied into every downstream context packet.
+
+**Approval and supersession**: reference import, reference approval, baseline
+approval, reference supersession, and baseline supersession are separate acts.
+A reference-fidelity `PASS`, a frontend-contract `PASS`, or a successful
+before/after comparison must not silently approve or replace any reference or
+baseline.
+
+The v0.8 viewer, released as package version `0.8.0`, consumes this v0.7
+reference/evaluation contract exactly as required - it creates no UI-only
+reference model (see `docs/ARCHITECTURE.md` "v0.8 Batch 5"/"v0.8 Batch 6"
+and `docs/reports/v0.8-reference-candidate-inspection-batch5.md`). v0.9
+annotations (released in `0.9.0`) originate from runtime
+screenshots or external references, preserve which source identity and
+coordinate system they belong to, and feed the same canonical contract and
+reference semantics - see "v0.9 visual annotation contract" below. v0.10
+combines both entry modes into the full correction/approval workflow.
+
+## v0.9 visual annotation contract (released in 0.9.0)
+
+v0.9 is released as `@dailephd/my-frontend-observer@0.9.0`.
+
+**Artifact**: `VisualAnnotationArtifact`, artifact kind
+`my-frontend-observer/visual-annotation`, schema version `1.0.0`. It stores one
+exact canonical source (a runtime observation, or an imported or approved
+external reference), the source coordinate space (runtime CSS pixels or
+reference-image pixels), and bounded structured items. Each item has a stable
+`annotationItemId`, one mark (point, rectangle, line, arrow, or note), an
+optional explicit association, and an interpretation. A revision sets
+`supersedesAnnotationId` and never rewrites its parent. The overlay SVG is
+derived from the artifact and verified before it is served.
+
+**An annotation is not a contract.** Saving an annotation never creates a
+contract clause, a reference requirement, or a PASS/FAIL rule. Marks and
+visible pixels are evidence. Overlap between a mark and a target or region is
+not ownership and never creates an association.
+
+**Interpretation states**: `uninterpreted`, `candidate`, and `confirmed`.
+Confirmation is explicit and records `confirmedAt`. Editing the mark,
+association, or intent of a confirmed item withdraws the confirmation.
+
+**Runtime intent to contract**:
+
+- Only selected, confirmed, supported runtime intent is promoted. Promotion
+  creates one normal canonical `PerChangeContract` through the existing
+  contract persistence service.
+- Supported mappings use the existing `ContractPrimitive` vocabulary only.
+  `move` maps to `property-increases`/`property-decreases` on `x` or `y`.
+  `resize` maps to `property-increases`/`property-decreases` on `width` or
+  `height`. `preserve` maps to `property-unchanged-within-tolerance` for a
+  target property, or to `relationship-unchanged` for an explicitly associated
+  canonical relationship.
+- Categories are the canonical `requested`, `expected-dependent` (with a
+  required `required` or `permitted` mode), `protected`, and `preserved`.
+  `unexpected` is never authored; it stays evaluator-derived.
+- `remove` can be confirmed and saved, but it is not promotable in v0.9. The
+  contract vocabulary has no target-absent primitive, and no approximate
+  clause is fabricated.
+- `inspect` intent and notes are informational and never promoted.
+- Each clause's `supportingEvidence` records the annotation source and item
+  paths. Promotion never activates the contract unless explicitly requested,
+  and it never approves a baseline.
+
+**Reference intent to a new reference revision**:
+
+- Only selected, confirmed `reference-region` (`create` or `refine`) and
+  `reference-requirement` items are materialized. `inspect` and
+  `asset-sensitive` intent stay informational.
+- The result is a new imported `ExternalReferenceArtifact`, created through the
+  existing canonical import service. It supersedes the selected source
+  reference (the approved reference id when the source is approved) and has
+  lifecycle `imported`. It is never approved automatically.
+- Source regions keep their order. A refine replaces the rectangle of an
+  existing source region and keeps its id. Creates are appended in selection
+  order. Duplicate creates, duplicate refines, and create-then-refine in one
+  request are rejected.
+- Source requirements stay first with identical recomputed ids. Selected
+  requirements are appended in selection order and validated against the final
+  regions. A selected relationship requirement must still hold for the final
+  geometry. Measurement requirements store only the subject and tolerance.
+- Applicability, label, and the exact source image bytes are preserved. The
+  source reference is never modified, and project reference acceptance is not
+  changed.
+
+Existing contract, reference relationship, adequacy, and fidelity evaluators
+remain the only source of verdicts. v0.9 adds no annotation evaluator.
+
+## Approved v0.1 design inputs
+
+The historical greenfield scaffold plan recorded these v0.1 design decisions:
+
+- artifact kind `my-frontend-observer/observation`;
+- schema version `1.0.0`, independent of package version;
+- one portable directory containing `manifest.json`, `evidence.json`, and
+  `screenshot.png`;
+- evidence states `available`, `unavailable`, `not-applicable`, and `partial`;
+- evidence sources `browser`, `computed-browser`, and `derived`;
+- bounded explicitly requested targets, provenance, diagnostics, completion
+  state, limits, and relative artifact references.
+
+These were planning inputs only at the time they were recorded. As shown in
+"Current contracts" above, the implemented contract matches them except for
+the file layout: there is no separate `evidence.json` - page/target evidence
+is embedded directly inside `manifest.json`.
+
+Comparison and relationship contracts belong to v0.4, and canonical
+change-scope contracts belong to v0.5 - see "v0.5 frontend contract and
+evaluation" above for the full shipped contract model, identity, evaluation
+engine, persistence, baseline approval, and CLI exposure. Bounded
+agent-context and runtime/static correlation contracts are v0.6 - see "v0.6
+bounded agent context and correlation contract" above for the full released
+model. The text/config-driven coding-agent review plus non-graphical external
+visual-reference foundation is v0.7 - see "v0.7 Prompt 1 external-reference
+artifact contract" below for the foundation layer implemented so far. Viewer
+consumption of that reference model is released in v0.8 (see "v0.7 external
+visual-reference contract direction" above); dual-context annotation follows
+in v0.9; both visual entry modes converge with the existing workflow in
+v0.10.
+
+## v0.7 Prompt 1 external-reference artifact contract
+
+Released as `0.7.0`. This is the foundation layer only: identity,
+provenance, bounded image metadata, and a two-state lifecycle for one
+externally supplied design-reference image. It implements no region,
+geometry, relationship, requirement, tolerance, binding, or fidelity-
+evaluation contract - those belong to later v0.7 prompts.
+
+An external reference is a distinct evidence root, not a variant of
+`ObservationArtifact`: it never reuses `ARTIFACT_KIND`/`SCHEMA_VERSION`
+(observation), `COMPARISON_ARTIFACT_KIND`, or `CONTRACT_ARTIFACT_KIND`, and
+those existing types gain no new field from this contract.
+
+```ts
+const EXTERNAL_REFERENCE_ARTIFACT_KIND = 'my-frontend-observer/external-reference';
+const EXTERNAL_REFERENCE_SCHEMA_VERSION = '1.0.0'; // independent of package.json version and every other family's schema version
+
+type ExternalReferenceImageFormat = 'png' | 'jpeg' | 'webp';
+
+interface ExternalReferenceImageReference {
+  path: string; // bare relative filename within the artifact's own directory
+  format: ExternalReferenceImageFormat;
+  width: number;
+  height: number;
+  byteLength: number;
+  sha256: string; // identity-bearing content hash of the raw image bytes
+}
+
+// Points back to the imported artifact that owns the image, without copying its bytes - mirrors ComparisonSourceObservationReference.
+interface ExternalReferenceSourceReference {
+  referenceId: string;
+  referenceRequestId: string;
+  producer: { name: 'my-frontend-observer'; version: string };
+  schemaVersion: '1.0.0';
+  image: ExternalReferenceImageReference;
+}
+
+// Exactly two persisted states - no literal 'superseded' variant (see below).
+type ExternalReferenceLifecycleState = { state: 'imported' } | { state: 'approved'; approvedAt: string };
+
+interface ExternalReferenceArtifactBase {
+  artifactKind: 'my-frontend-observer/external-reference';
+  schemaVersion: '1.0.0';
+  referenceRequestId: string; // deterministic logical identity - shared by an imported artifact and every artifact produced by approving it
+  referenceId: string; // fresh per-persisted-instance identity
+  producer: { name: 'my-frontend-observer'; version: string };
+  provenance: { importedAt: string; label?: string };
+  supersedesReferenceId?: string; // explicit, forward-only supersession of a prior reference's referenceId
+  diagnostics: Diagnostic[];
+  completion: CompletionState;
+}
+
+// lifecycle.state === 'imported': owns the image.
+interface ImportedExternalReferenceArtifact extends ExternalReferenceArtifactBase {
+  lifecycle: { state: 'imported' };
+  image: ExternalReferenceImageReference;
+}
+
+// lifecycle.state === 'approved': references, never copies, the imported artifact's image.
+interface ApprovedExternalReferenceArtifact extends ExternalReferenceArtifactBase {
+  lifecycle: { state: 'approved'; approvedAt: string };
+  sourceReference: ExternalReferenceSourceReference;
+}
+
+type ExternalReferenceArtifact = ImportedExternalReferenceArtifact | ApprovedExternalReferenceArtifact;
+```
+
+Key rules:
+
+- `referenceRequestId` is a pure function of `{imageSha256, format, width,
+  height, supersedesReferenceId}` only - never a filesystem path, output
+  location, label, or timestamp. Byte-identical image content imported from a
+  different operational root produces the same `referenceRequestId`;
+  changing any of those fields changes it.
+- `referenceId` is fresh (nonce-based) on every persisted write, including
+  every approval of an already-imported reference.
+- Importing an image never approves it (`lifecycle.state` is always
+  `'imported'` immediately after import, regardless of a supplied label or
+  supersession target). Approval is a single explicit act
+  (`approveExternalReference`, mirroring `approveAndPersistBaseline`) that
+  refuses anything not currently in the `'imported'` state.
+- Approving persists a *new* artifact instance (same `referenceRequestId`,
+  fresh `referenceId`) carrying a `sourceReference` back to the imported
+  artifact - it never mutates the imported artifact's own manifest, and never
+  copies the image bytes a second time.
+- Supersession is represented only as a forward pointer
+  (`supersedesReferenceId` on the newer artifact); there is deliberately no
+  literal `'superseded'` lifecycle state, so an existing persisted artifact's
+  own manifest is never rewritten - immutability holds unconditionally rather
+  than depending on careful mutation discipline.
+- Supported formats are frozen to exactly `png`/`jpeg`/`webp`, detected from
+  header/magic bytes only (never a caller-declared file extension), bounded
+  to `EXTERNAL_REFERENCE_MAX_IMAGE_BYTES` (20,000,000 bytes) and
+  `[EXTERNAL_REFERENCE_MIN_DIMENSION_PX, EXTERNAL_REFERENCE_MAX_DIMENSION_PX]`
+  (`[1, 8192]`) pixels per side. No OCR, no raster decode, no computer
+  vision, no automatic region detection.
+
+Persisted as `<outputLocation>/<referenceId>/manifest.json` (+
+`reference.<ext>` for an `'imported'` artifact only), via the same atomic
+temp-dir-then-rename discipline as every other artifact family
+(`src/artifacts/externalReferenceArtifactWriter.ts` /
+`externalReferenceArtifactReader.ts`). CLI: `import-reference <image-file>
+--output <dir> [--label] [--supersedes <root>]` and `approve-reference
+--reference <root> --output <dir> [--supersedes <root>]`.
+
+## v0.7 Prompt 2 explicit reference regions and relationships
+
+Released as `0.7.0`. Additive extension of the Prompt 1 contract above:
+one new, optional `regions?: ReferenceRegion[]` field on
+`ExternalReferenceArtifact` (both lifecycle variants), plus a pure,
+non-persisted relationship-derivation capability. No schema version bump -
+`EXTERNAL_REFERENCE_SCHEMA_VERSION` remains `'1.0.0'`, because the field is
+genuinely optional/additive and every Prompt 1 artifact (which predates this
+field entirely) remains valid without it.
+
+```ts
+// domain/externalReferenceRegions.ts
+interface ReferenceRegionRectangle { x: number; y: number; width: number; height: number; }
+interface ReferenceRegion { id: string; rectangle: ReferenceRegionRectangle; }
+
+// Pure derived geometry - never persisted, always recomputed, so it can never drift from the rectangle above.
+interface ReferenceRegionGeometry {
+  x: number; y: number; width: number; height: number;
+  right: number; bottom: number; centerX: number; centerY: number;
+}
+
+const REFERENCE_REGION_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/; // same convention as request/request.ts's target-name pattern
+const MAX_REFERENCE_REGIONS = 20; // same bound value as request/request.ts's MAX_TARGETS - independently owned, coincidentally equal
+```
+
+Region coordinate semantics: origin at the reference image's top-left
+corner, x increasing rightward, y increasing downward, unit is
+reference-image pixels (explicitly not CSS pixels - a static image has no
+CSS box model), coordinates may be fractional. A region's rectangle must lie
+entirely within its owning image's own already-validated
+width/height - out-of-bounds geometry is rejected outright, never clamped.
+
+Key rules:
+
+- Only `{x, y, width, height}` is canonical/authored. `right`, `bottom`,
+  `centerX`, `centerY` are pure calculations over it
+  (`deriveReferenceRegionGeometry`) - never a second, potentially-drifting
+  stored copy of the same fact.
+- Region content is identity-bearing:
+  `buildExternalReferenceRequestIdentity` gained an additive, optional
+  trailing `regions` parameter. Omitting it entirely (every Prompt 1 call
+  site, and any Prompt 2 call that legitimately has no regions) produces the
+  byte-identical hash Prompt 1 already produced - the parameter is left out
+  of the hashed view rather than defaulted to `null`, unlike
+  `supersedesReferenceId`. Authored region order participates in identity
+  (arrays are never reordered by the shared `canonicalize()`), mirroring
+  `domain/identity.ts`'s treatment of configured targets.
+- Region IDs are unique case-insensitively within one artifact (mirroring
+  `request/request.ts`'s target-name dedup convention exactly).
+- `import-reference` gained an optional `--regions-file <json-file>` of the
+  form `{ "regions": [...] }` (same object-root-wrapper convention as
+  `--targets-file`); a legacy invocation without it behaves exactly as in
+  Prompt 1. `approve-reference` carries an imported artifact's `regions`
+  forward verbatim (never re-validated, never re-derived, never dropped) -
+  approval never adds, removes, or edits regions.
+- One new diagnostic code, `invalid-reference-region` (error), covers every
+  region-validation failure (missing/duplicate/malformed id,
+  non-finite/negative/zero geometry, out-of-image-bounds, over the bounded
+  region count) - deliberately not split into several codes, per the
+  "don't proliferate diagnostics" convention.
+
+Reference-region relationships (`domain/externalReferenceRegionRelationships.ts`)
+reuse the exact same pure, tolerance-aware geometry predicates that
+`domain/relationships.ts#deriveLayoutRelationships` uses for runtime targets
+(`horizontalOrderOf`/`verticalOrderOf`/`areaOverlapOf`/`relativeWidthOf`/
+`geometricFitOf`/`verticalSequenceOf`, now exported additively from that
+module with unchanged formulas) and the same `PairwiseRelationshipKind`
+vocabulary and `EvidenceReference` type - never a duplicated or
+reinterpreted copy. Only the six geometry-only families apply (horizontal
+order, vertical order, area overlap, relative width, geometric fit, vertical
+sequencing); DOM containment, scroll ownership, runtime visibility, and
+page-width-vs-viewport are runtime/browser concepts with no reference-image
+equivalent and are not reused. `fits-inside`/`does-not-fit-inside` is
+geometry-only fit - it never claims DOM containment, which an external image
+cannot expose.
+
+```ts
+interface ReferenceRegionRelationship {
+  kind: PairwiseRelationshipKind;
+  subjectRegion: string;   // deliberately distinct field name from PairwiseLayoutRelationship's subjectTarget
+  relatedRegion: string;
+  evidence: EvidenceReference[]; // e.g. { path: 'regions.header.rectangle' } - never a targetEvidence/browser path
+}
+```
+
+Relationships are **not persisted** on the artifact - `deriveReferenceRegionRelationships(referenceRequestId, regions, options)`
+is a pure, deterministic, synchronous function any caller (a future prompt,
+a test) calls on demand against an artifact's own `regions` field, avoiding
+any possibility of a persisted relationship graph drifting from the region
+data it was derived from. Bounded at `MAX_REFERENCE_REGIONS` regions ->
+`MAX_REFERENCE_REGION_PAIRS` pairs `x` 6 families =
+`MAX_REFERENCE_REGION_RELATIONSHIP_RECORDS` records maximum - the same
+bounding shape as `relationships.ts`'s `MAX_PAIRWISE_RELATIONSHIP_RECORDS`.
+This is a maximum capacity, never a required minimum region count - there is
+no contract requiring any specific number of authored regions.
+
+A reference relationship is a fact about the reference image's geometry
+only. It is not a design requirement, not a pass/fail verdict, and does not
+claim a runtime target or source owner exists - see
+`docs/WORKFLOWS.md` "Current external-reference foundation workflow" for
+where those later concepts (Prompt 3+) will attach.
+
+## v0.7 Prompt 3 selected design requirements, tolerance semantics, and reference-evidence adequacy
+
+Released as `0.7.0`. Additive extension of the Prompt 1/2 contracts
+above: one new, optional `requirements?: ExternalReferenceRequirement[]`
+field on `ExternalReferenceArtifact` (both lifecycle variants). No schema
+version bump - same reasoning as Prompt 2's `regions` field.
+
+**Central distinction**: a region's geometry is REFERENCE EVIDENCE -
+everything visibly/measurably present in the image. A requirement is
+SELECTED DESIGN INTENT - only what the user/configuration explicitly chose
+as mattering for later candidate evaluation. Nothing in this repository ever
+turns a region property or a derived relationship into a requirement
+automatically.
+
+```ts
+// domain/externalReferenceRequirements.ts
+
+// Reused directly from domain/frontendContracts.ts - not reinvented as a
+// "reference-only" taxonomy; that type carries no runtime-only coupling.
+// 'unexpected' remains impossible to author (not a member of this union).
+type AuthoredChangeScopeCategory = 'requested' | 'expected-dependent' | 'protected' | 'preserved';
+type ExpectedDependentMode = 'required' | 'permitted'; // required only (and exactly) when category === 'expected-dependent'
+
+type ReferenceRequirementRegionProperty = 'x' | 'y' | 'width' | 'height' | 'right' | 'bottom' | 'centerX' | 'centerY'; // exactly ReferenceRegionGeometry's own fields
+type ReferenceRequirementMeasurement = 'vertical-gap' | 'horizontal-gap' | 'center-x-delta' | 'center-y-delta' | 'left-edge-delta' | 'right-edge-delta';
+
+type ReferenceRequirementSubject =
+  | { kind: 'region-property'; region: string; property: ReferenceRequirementRegionProperty }
+  | { kind: 'region-relationship'; subjectRegion: string; relatedRegion: string; relationship: PairwiseRelationshipKind } // reused from relationships.ts - geometry-only families only
+  | { kind: 'region-measurement'; subjectRegion: string; relatedRegion: string; measurement: ReferenceRequirementMeasurement };
+
+// Deliberately NOT a reuse of frontendContracts.ts's ContractTolerance: that
+// type's 'absolute-px' is implicitly runtime/CSS pixels. Reference-image
+// pixels are a distinct, explicitly-labeled unit - nothing here assumes
+// 1 reference pixel = 1 CSS pixel (Prompt 6 will need an explicit mapping).
+type ReferenceRequirementTolerance = { kind: 'exact' } | { kind: 'absolute-reference-px'; amount: number } | { kind: 'percent'; amount: number };
+
+interface ExternalReferenceRequirement {
+  requirementId: string; // system-computed from {subject, category, expectedDependentMode, tolerance} only - never authored
+  category: AuthoredChangeScopeCategory;
+  expectedDependentMode?: ExpectedDependentMode;
+  subject: ReferenceRequirementSubject;
+  tolerance?: ReferenceRequirementTolerance; // required for region-property/region-measurement; must be absent for region-relationship
+}
+```
+
+Key rules:
+
+- Requirement identity (`requirementId`) is always system-computed
+  (`buildReferenceRequirementIdentity`, mirroring
+  `frontendContractIdentity.ts#buildClauseIdentity`'s exact shape) - the raw
+  authored input (`RawReferenceRequirement`) has no `requirementId` field at
+  all, and supplying one is a validation error. Unlike v0.5's
+  `BaselineClause`/`PerChangeClause` (which need an author-visible `clauseId`
+  for cross-document `supersedesBaselineClauseIds` references), Prompt 3
+  requirements have no cross-document reference need yet, so trusting an
+  authored id would only invite drift between a user-typed id and the
+  content it claims to identify.
+- The reference-side expected value/relationship is never stored on the
+  requirement or the artifact - `deriveReferenceRequirementExpectation()` is
+  a pure function computed on demand from the artifact's own `regions`,
+  eliminating the exact drift risk of persisting e.g. `width: 424` alongside
+  a region whose rectangle could (in principle) later disagree with it.
+- A requirement referencing a region id that does not exist in the
+  artifact's own `regions` is a **structural validation failure** (rejected
+  at construction/import time), never merely "unavailable" reference
+  evidence - `isValidReferenceRequirements` checks this before any
+  requirement reaches adequacy computation.
+- **Duplicate/conflicting subject rule**: no two requirements in one
+  collection may share the same structural subject (same region+property,
+  or the same unordered region pair + relationship, or + measurement),
+  regardless of category. This single rule covers both "duplicate
+  requirement" and "conflicting categories on the same subject" (e.g. the
+  same region/property authored as both `requested` and `protected`) -
+  v0.5's `evaluateFrontendContract#primitivesConflict` is a *runtime-
+  evaluation-time* detector (it needs before/after `ObservationArtifact`
+  evidence that does not exist yet at this stage) and could not be reused
+  safely; Prompt 3 restricts invalid combinations at authoring time instead,
+  per the documented precedent-review outcome.
+- Bounded at `MAX_REFERENCE_REQUIREMENTS` (50) requirements per artifact -
+  a maximum capacity, never a required minimum (there is no contract
+  requiring any specific number of authored requirements).
+- One new diagnostic code, `invalid-reference-requirement` (error), covers
+  every requirement-authoring validation failure - deliberately not split
+  further, per the "don't proliferate diagnostics" convention already used
+  for `invalid-reference-region`.
+- `import-reference` gained an optional `--requirements-file <json-file>`
+  (`{ "requirements": [...] }`, same object-root-wrapper convention as
+  `--regions-file`/`--targets-file`); `approve-reference` carries an
+  imported artifact's `requirements` forward verbatim (never re-validated,
+  never re-derived, never dropped), exactly mirroring how it already
+  handles `regions`.
+
+**Reference-evidence adequacy** (`deriveReferenceRequirementAdequacy(regions, requirements)`)
+answers only "does the reference definition itself contain enough evidence
+to understand every selected requirement?" - never "does a runtime
+target/candidate exist" (that is Prompt 4/5's responsibility). It is its own
+small, reference-owned vocabulary (`REFERENCE_REQUIREMENT_ADEQUACY_STATES` =
+`'adequate' | 'partial' | 'inadequate'`, and exactly two reason codes,
+`no-selected-requirements` and `missing-reference-relationship-evidence`) -
+deliberately **not** a reuse of
+`boundedAgentContext.ts`'s `Adequacy`/`ADEQUACY_REASON_CODES`, which
+describe runtime-target/static-correlation concerns that do not exist at
+this stage; mislabeling reference adequacy as bounded-agent-context adequacy
+would conflate two genuinely different evidence domains. Zero selected
+requirements is explicitly `inadequate` (a region-rich, fully-valid
+reference is still not usable for a correction task until the user has
+actually selected what matters) - this is a documented product decision,
+not an oversight. The result is never a numeric score, always structured
+and inspectable, with reasons ordered deterministically by authored
+requirement position.
+
+```ts
+interface ReferenceRequirementAdequacy {
+  status: 'adequate' | 'partial' | 'inadequate';
+  totalRequirements: number;
+  evaluableRequirements: number;
+  unavailableRequirements: number;
+  reasons: { code: 'no-selected-requirements' | 'missing-reference-relationship-evidence'; requirementId?: string; detail?: string }[];
+}
+```
+
+## v0.7 Prompt 4 reference applicability and candidate-state compatibility
+
+Released as `0.7.0`. Additive extension of the Prompt 1/2/3 contracts
+above: one new, optional `applicability?: ExternalReferenceApplicability`
+field on `ExternalReferenceArtifact` (both lifecycle variants), one new,
+optional `explicitState?: ExplicitStateDimensions` field on
+`ObservationArtifact.requestConfig`, and one new pure module,
+`domain/externalReferenceCompatibility.ts`, that answers a single question:
+"does this external reference describe the same frontend state as this
+candidate `ObservationArtifact`?" No schema version bump on either artifact
+- same reasoning as Prompt 2/3's additive fields.
+
+**Central distinction**: this is page/state-level compatibility only -
+never geometry, never fidelity, never a visual/pixel comparison, and never
+region-to-runtime-target binding (Prompt 5). It answers "should a
+reference-vs-candidate geometry comparison even be attempted", not "does the
+candidate match the reference". Reference-evidence adequacy (Prompt 3) and
+reference/candidate compatibility (Prompt 4) are deliberately independent:
+a reference can be `adequate` (enough selected requirements to evaluate)
+while simultaneously `incomparable` against a given candidate (wrong
+viewport/theme/state), and vice versa - neither result constrains the
+other.
+
+**State identity is always explicit, never inferred.** `theme`,
+`applicationState`, and `authenticatedState` are caller/configuration-
+supplied labels only. The observer never reads screenshot pixels, CSS, DOM
+classes/text, URLs, source code, filenames, accessibility labels,
+localStorage, or cookies to determine state - there is no automatic state
+detection anywhere in this codebase, and Prompt 4 does not add any. Labels
+are bounded opaque identities (`^[A-Za-z0-9_-]{1,64}$`, the same pattern
+already used for target names and region ids) compared by exact,
+case-sensitive string equality only - `"dark"` and `"one-dark"` are
+unrelated labels, never fuzzy-matched or normalized.
+
+```ts
+// domain/explicitState.ts - shared by both ObservationArtifact and ExternalReferenceArtifact
+type AuthenticatedState = 'authenticated' | 'unauthenticated'; // closed vocabulary - never a place for credentials/tokens/cookies/session ids
+interface ExplicitStateDimensions {
+  theme?: string;
+  applicationState?: string;
+  authenticatedState?: AuthenticatedState;
+}
+// isValidExplicitStateDimensions requires at least one dimension declared and rejects any unsupported field -
+// this is a bounded, closed shape, never an arbitrary Record<string, unknown> metadata bag.
+
+// domain/externalReferenceApplicability.ts
+interface ApplicableViewport { width: number; height: number } // CSS pixels, bounds [200, 3840] mirroring request.ts's own viewport bounds
+interface ExternalReferenceApplicability extends ExplicitStateDimensions {
+  viewport?: ApplicableViewport;
+}
+```
+
+**Reference image size is never the same concept as applicable viewport.**
+`ExternalReferenceImageReference.width/height` (Prompt 1) describes the
+reference image's own pixel dimensions - a property of the image file,
+detected from its header bytes. `applicability.viewport` describes the
+CSS-pixel runtime viewport the design *represents* - a reference image may
+be captured at any resolution or device-pixel-ratio (e.g. a 1920x1080
+screenshot representing a 960x540 CSS-pixel layout at 2x DPR). Nothing in
+`externalReferenceApplicability.ts` reads or derives a viewport from image
+dimensions; `isValidExternalReferenceApplicability` is its own validator
+(not a reuse of `isValidExplicitStateDimensions`, whose "at least one
+dimension" rule would incorrectly reject a viewport-only applicability
+object).
+
+**v0.4 comparability is reused, not duplicated.** `domain/comparison.ts`
+gained four additive reason codes (`viewport-unassessed`, `theme-mismatch`,
+`authenticated-state-mismatch`, `application-state-mismatch` - the
+`*-unassessed` codes for theme/authenticated-state/application-state
+already existed from v0.4) and two optional fields on `ComparabilityReason`
+(`referenceValue?: string`, `candidateValue?: string`, populated only for a
+mismatch reason). `domain/comparisonEngine.ts` gained one new exported pure
+helper, `assessOptionalComparabilityDimension(mismatchCode, unassessedCode,
+beforeValue, afterValue, mismatchMessage, unassessedMessage)`, extracted
+from - and now used by - both v0.4's own `evaluateComparability`
+(Observation-vs-Observation) and the new
+`evaluateReferenceCandidateCompatibility` (Reference-vs-Observation). The
+rule is identical either way: both values defined and equal -> no reason;
+both defined and different -> a `blocking` mismatch reason (with
+`referenceValue`/`candidateValue` populated); either value undefined ->
+an `unassessed` reason. This is a genuine, additive improvement to v0.4's
+own behavior: `evaluateComparability` now assesses theme/authenticated-
+state/application-state as matching or blocking-mismatched whenever *both*
+observations declare `requestConfig.explicitState`, rather than always
+reporting them unassessed - but every historical observation pair (and any
+pair where either side omits `explicitState`) retains the exact old
+unassessed-only behavior, verified by the frozen `evaluateComparability`
+regression test that predates this batch.
+
+```ts
+// domain/externalReferenceCompatibility.ts
+interface ReferenceCandidateCompatibilityResult {
+  referenceId: string;
+  referenceRequestId: string;
+  candidateObservationId: string;
+  candidateRequestId: string;
+  compatibility: ComparabilityResult; // v0.4's own reused result type - state/reasons, never a boolean or a visual score
+}
+function evaluateReferenceCandidateCompatibility(reference: ExternalReferenceArtifact, candidate: ObservationArtifact): ReferenceCandidateCompatibilityResult;
+```
+
+Key rules:
+
+- Pure and synchronous - no browser, no filesystem, no network, no target
+  binding. Only `reference.applicability` and
+  `candidate.requestConfig.viewport`/`candidate.requestConfig.explicitState`
+  are consulted; reference regions/requirements are never read here (a
+  distinct, separate concern - see Prompt 3 above).
+- A dimension the reference constrains but the candidate entirely omits
+  (or vice versa) is `unassessed`, never treated as compatible-by-default
+  and never fabricated as a mismatch - fail-closed, honest non-assessment.
+- A reference that declares no `applicability` at all produces a fully
+  `unassessed` (never automatically `incomparable`, never automatically
+  `comparable` beyond "no blocking reasons found") result across all four
+  dimensions - Prompt 1/2/3 references remain fully usable, just
+  unassessed for compatibility until applicability is authored.
+- No automatic persisted compatibility artifact. This is a pure
+  programmatic result, produced on demand by an application/CLI caller
+  that already holds both a reference and a candidate artifact - inventing
+  a new persisted artifact kind for a value this cheap to recompute would
+  add drift risk (a candidate/reference re-imported later could silently
+  disagree with a stale persisted compatibility record) with no
+  corresponding benefit; this may be revisited only if a later prompt's
+  architecture proves persistence necessary.
+- Identity impact: `buildExternalReferenceRequestIdentity` gained a final
+  optional `applicability` parameter (omitted, never `null`, when absent -
+  byte-identical to Prompt 1/2/3 hashes for every call that doesn't supply
+  it); `buildRequestIdentity` gained a final optional `explicitState`
+  parameter with the identical omission convention. Neither identity
+  function ever takes a file path.
+- CLI: `import-reference` gained an optional `--applicability-file
+  <json-file>` (the raw, unwrapped applicability object - not a
+  `{ "requirements": [...] }`-style wrapper, since applicability is a
+  single object rather than a named list); `observe` gained an optional
+  `--state-file <json-file>` (the raw, unwrapped `ExplicitStateDimensions`
+  object). Both follow the existing `--scroll-scenario-file` convention
+  exactly: relative paths resolve from the current working directory, the
+  path itself is never persisted or included in any identity, and CLI code
+  owns only flag syntax/file reading/JSON parsing/object-root validation -
+  all semantic validation happens in the domain layer.
+
+## v0.7 Prompt 5 explicit reference-region <-> runtime-target binding
+
+Released as `0.7.0`. One new pure domain module,
+`domain/externalReferenceRuntimeBinding.ts`, answering "which stable
+observer runtime target, if any, does this candidate observation resolve
+for each explicitly declared reference region?" No new field is added to
+either `ExternalReferenceArtifact` or `ObservationArtifact` - both remain
+exactly as Prompt 4 left them - and no schema version bump on either.
+
+**Two identity domains, kept strictly separate.** A binding declaration
+names a Prompt 2 `ReferenceRegion.id` and a v0.2 `NamedTarget.name` (the
+stable observer runtime target identity established since v0.2 - never a
+CSS selector, DOM node handle, source file, React component name, or
+my-dev-kit node id). These two strings living in the same textual namespace
+never implies a binding - a region id `"header"` and a target name
+`"header"` bind to each other only because of an explicit declaration, not
+because the strings match (verified by a dedicated test: the same
+observation with and without the explicit declaration produces `bound`
+only in the former case).
+
+```ts
+// domain/externalReferenceRuntimeBinding.ts
+interface ReferenceRuntimeBindingDeclaration {
+  referenceRegion: string; // Prompt 2 ReferenceRegion.id
+  runtimeTarget: string;   // v0.2 NamedTarget.name
+}
+
+const REFERENCE_RUNTIME_BINDING_STATUSES = ['bound', 'ambiguous', 'unavailable'] as const;
+
+interface ReferenceRuntimeBindingResult {
+  referenceRegion: string;
+  runtimeTarget: string;
+  status: 'bound' | 'ambiguous' | 'unavailable';
+  reasonCode?: 'runtime-target-not-configured' | 'runtime-target-not-found' | 'runtime-target-ambiguous' | 'runtime-target-evidence-unavailable';
+  detail: string;
+  targetResolutionStatus?: TargetSelectionStatus; // v0.2's own resolution status, when evidence for it exists
+  targetVisible?: boolean; // provenance only - never affects status
+}
+
+interface ReferenceRuntimeBindingEvaluation {
+  referenceId: string;
+  referenceRequestId: string;
+  candidateObservationId: string;
+  candidateRequestId: string;
+  compatibility: ComparabilityResult; // reused verbatim from v0.7 Prompt 4
+  bindings: ReferenceRuntimeBindingResult[]; // empty exactly when compatibility.state === 'incomparable'
+}
+
+function evaluateReferenceRuntimeBindings(
+  reference: ExternalReferenceArtifact,
+  candidate: ObservationArtifact,
+  declarations: readonly ReferenceRuntimeBindingDeclaration[],
+): { ok: true; evaluation: ReferenceRuntimeBindingEvaluation } | { ok: false; reason: string };
+```
+
+Key rules:
+
+- **Explicit, never inferred.** A binding declaration is user/configuration
+  input asserting a conceptual correspondence; this module never discovers
+  it from screenshot geometry, matching names, matching text, or source
+  code. There is no automatic-matching algorithm anywhere in this module.
+- **Reuses, never duplicates.** The compatibility gate reuses
+  `evaluateReferenceCandidateCompatibility` (Prompt 4) verbatim - viewport/
+  theme/application-state/authenticated-state comparison logic is never
+  re-implemented here. Runtime-target resolution reuses `targetPresence`
+  (v0.4 `comparisonEngine.ts`, now additively exported alongside
+  `assessOptionalComparabilityDimension`) - the exact same "how do I read a
+  `TargetEvidenceRecord`'s resolution" rule v0.4's own before/after target
+  comparison already uses. No second target resolver, no browser launch, no
+  Chromium query, no selector evaluation, no live-DOM inspection - this
+  module consumes only an already-captured `ObservationArtifact`'s
+  `requestConfig.targets`/`targetEvidence`.
+- **Compatibility gates before evaluation, structurally.** If
+  `evaluateReferenceCandidateCompatibility` reports `incomparable`,
+  `bindings` is the empty array and the caller reads the reason from the
+  embedded `compatibility` field - there is no binding-local "incompatible"
+  status; Prompt 4's compatibility result is represented exactly once, not
+  duplicated into a parallel vocabulary.
+- **Two-layer validation.** Reference-region existence, declaration shape,
+  bounds, and duplicate/conflict rules are validated structurally against
+  the `ExternalReferenceArtifact` alone (`isValidReferenceRuntimeBindingDeclarations`)
+  - independent of any candidate, mirroring Prompt 3's "unknown region
+  reference is a structural validation failure" precedent exactly: a
+  declaration naming a nonexistent reference region, or any reference with
+  no `regions` declared at all, fails the whole evaluation closed before a
+  candidate is even considered. Runtime-target availability, by contrast,
+  is evaluated per-candidate inside `evaluateReferenceRuntimeBindings`
+  itself, since the same declaration can be `bound` against one candidate
+  and `unavailable` against another.
+- **Duplicate/conflicting-declaration rule** (mirrors Prompt 3's
+  requirement-subject uniqueness rule): no two declarations may name the
+  same `referenceRegion` (case-insensitively), whether they agree on
+  `runtimeTarget` (an exact duplicate) or disagree (a conflict) - both fail
+  the same way, never silently resolved by keeping the first. The reverse -
+  several distinct reference regions naming the same `runtimeTarget` - is
+  deliberately allowed (e.g. two design sub-regions legitimately
+  corresponding to one runtime container element).
+- **Target-resolution-state handling.** `targetPresence`'s four outcomes
+  map onto binding status as: `matched` -> `bound`; `ambiguous` -> `ambiguous`
+  (the candidate's own configured target resolved ambiguously - never
+  reported bound even though its stable name exists); `not-found` ->
+  `unavailable` (`runtime-target-not-found` - the target was configured but
+  the resolver found nothing on the page); no usable resolution evidence at
+  all -> `unavailable` (`runtime-target-evidence-unavailable`). A declared
+  `runtimeTarget` that was never part of the candidate's configured target
+  set at all is a fifth, CLI/config-boundary-only outcome -> `unavailable`
+  (`runtime-target-not-configured`) - never a dynamic page search.
+- **Hidden-target decision.** A uniquely resolved (`matched`) but hidden
+  target is still reported `bound` - visibility never changes `status`.
+  `targetVisible` (from the existing `TargetVisibility` evidence, when
+  available) is carried as provenance only. Binding identity (does a stable
+  correspondence exist) and later fidelity evaluability (can this evidence
+  actually be used to check the design) are treated as distinct questions;
+  this prompt answers only the former.
+- **Not every region needs a binding.** `isValidReferenceRuntimeBindingDeclarations`
+  never requires full region coverage - a reference may have regions no
+  declaration names at all (they simply have no bound runtime target for
+  this candidate). This is not a completeness gate; Prompt 6 (or later) may
+  add one for the regions that selected requirements actually need.
+- **No persisted artifact family.** `evaluateReferenceRuntimeBindings` is a
+  pure, on-demand function over an already-persisted reference, an
+  already-persisted candidate observation, and an in-memory declaration
+  collection. No `ExternalReferenceBindingArtifact` (or equivalent) is
+  introduced - the same "cheap to recompute, persisting invites drift"
+  reasoning Prompt 4 already applied to its own compatibility result.
+  Neither the reference nor the observation artifact is ever rewritten to
+  carry a binding result: a design reference may later be evaluated against
+  several different candidates, and one observation may be evaluated
+  against several different references, so binding is kept as downstream,
+  candidate-specific, reference-specific derived evidence rather than
+  mutating either immutable source artifact.
+- **No new identity function.** Unlike `buildRequestIdentity`/
+  `buildExternalReferenceRequestIdentity`, no hash-based logical identity is
+  computed for a binding declaration or its evaluated result - there is no
+  persistence and no cross-document reference-by-id need yet (mirroring
+  Prompt 4's `ReferenceCandidateCompatibilityResult`, which took the same
+  approach). Provenance is instead carried directly as plain fields
+  (`referenceId`, `referenceRequestId`, `candidateObservationId`,
+  `candidateRequestId`, plus each result's own `referenceRegion`/
+  `runtimeTarget`) - already deterministic, already sufficient for a caller
+  to trace every result back to its inputs, without inventing a fifth
+  identity-hashing convention for a value this prompt does not persist.
+- **Deterministic ordering.** `bindings` preserves authored declaration
+  order (mirroring the "authored order is semantic" convention already used
+  for regions/requirements) rather than sorting by any derived key.
+- **Bounded.** `MAX_REFERENCE_RUNTIME_BINDINGS` (20) caps the declaration
+  collection, mirroring `MAX_REFERENCE_REGIONS`.
+- **No public CLI surface yet.** Only the programmatic
+  `evaluateReferenceRuntimeBindings`/`isValidReferenceRuntimeBindingDeclarations`
+  functions are exported. A standalone CLI command was deliberately not
+  added merely for symmetry with `import-reference`/`observe`; Prompt 6
+  (structured fidelity evaluation) is expected to become the first concrete
+  consumer and public-surface owner for this capability.
+
+## v0.7 Prompt 6 structured reference-vs-candidate fidelity evaluation
+
+Released as `0.7.0`. One new pure domain module,
+`domain/externalReferenceFidelity.ts`, and its CLI-facing counterpart,
+`application/referenceFidelityEvaluationService.ts` plus the new
+`evaluate-reference-fidelity` CLI command - the first point in this whole
+v0.7 stack where a reference's authored expectation is actually compared
+against live candidate evidence. No new artifact field, no schema version
+bump: this prompt reuses Prompt 1-5's artifacts and result types entirely.
+
+```ts
+// domain/externalReferenceFidelity.ts
+const REFERENCE_REQUIREMENT_FIDELITY_STATUSES = ['pass', 'fail', 'unavailable'] as const;
+const REFERENCE_FIDELITY_STATES = ['not-evaluated', 'pass', 'fail'] as const;
+const REFERENCE_FIDELITY_BLOCK_REASONS = ['reference-inadequate', 'incompatible'] as const;
+
+interface ReferenceRequirementFidelityResult {
+  requirementId: string;
+  category: AuthoredChangeScopeCategory;
+  expectedDependentMode?: ExpectedDependentMode;
+  subject: ReferenceRequirementSubject;
+  boundRuntimeTargets: string[];
+  status: 'pass' | 'fail' | 'unavailable';
+  reasonCode?: 'reference-evidence-unavailable' | 'reference-relationship-not-exhibited' | 'binding-unavailable' | 'candidate-evidence-unavailable' | 'coordinate-mapping-unavailable'; // present iff status === 'unavailable'
+  detail?: string;
+  // region-property/region-measurement subjects only:
+  referenceValue?: number;      // reference-image pixels
+  candidateRawValue?: number;   // CSS pixels, as captured
+  candidateValue?: number;      // candidateRawValue converted into reference-image-pixel space
+  delta?: number;               // candidateValue - referenceValue
+  tolerance?: ReferenceRequirementTolerance;
+  // region-relationship subjects only:
+  expectedRelationship?: PairwiseRelationshipKind;
+  actualRelationship?: PairwiseRelationshipKind;
+}
+
+interface ReferenceCandidateFidelityEvaluation {
+  referenceId: string;
+  referenceRequestId: string;
+  candidateObservationId: string;
+  candidateRequestId: string;
+  adequacy: ReferenceRequirementAdequacy; // reused verbatim from Prompt 3
+  compatibility?: ComparabilityResult;    // reused verbatim from Prompt 4; absent only when adequacy itself is inadequate
+  bindings?: ReferenceRuntimeBindingEvaluation; // reused verbatim from Prompt 5; absent when an earlier gate blocked
+  state: 'not-evaluated' | 'pass' | 'fail';
+  blockedBy?: 'reference-inadequate' | 'incompatible'; // present iff state === 'not-evaluated'
+  requirementResults: ReferenceRequirementFidelityResult[]; // empty iff state === 'not-evaluated'
+}
+
+function evaluateReferenceCandidateFidelity(
+  reference: ExternalReferenceArtifact,
+  candidate: ObservationArtifact,
+  bindingDeclarations: readonly ReferenceRuntimeBindingDeclaration[],
+  options?: { geometryTolerancePx?: number },
+): { ok: true; evaluation: ReferenceCandidateFidelityEvaluation } | { ok: false; reason: string };
+```
+
+**Result vocabulary.** `pass`/`fail`/`unavailable` is reused from v0.5's
+`CLAUSE_RESULT_STATUSES` shape (the same honest three-state idea: a result
+either satisfies its condition, fails it, or cannot be evaluated - never a
+score) but is its own independently-owned constant, deliberately excluding
+v0.5's fourth member, `'conflict'` - Prompt 6 has no cross-requirement
+authoring-conflict concept (each requirement is evaluated independently
+against its own subject), so reusing `conflict` would invite a status this
+prompt can never actually produce.
+
+**Evaluation order (frozen, never reordered):** reference structural
+validation -> candidate structural validation -> binding-declaration
+structural validation -> Prompt 3 reference adequacy -> Prompt 4
+compatibility -> Prompt 5 binding evaluation -> per-requirement candidate-
+evidence/coordinate-mapping checks -> per-requirement tolerance/
+relationship comparison -> overall result. The first three (structural
+validation) failures return `{ ok: false, reason }` - a caller/config error,
+never a fidelity outcome. The next two (adequacy `inadequate`, compatibility
+`incomparable`) short-circuit to `state: 'not-evaluated'` with an empty
+`requirementResults` - an earlier blocking gate never lets an ordinary
+PASS/FAIL requirement set get fabricated past it. `adequacy` "partial" (some,
+but not all, authored requirements individually unavailable) does **not**
+block evaluation - it proceeds normally, and the individual unavailable
+reference-side requirements simply also report `unavailable` at the
+per-requirement level (their own reference-evidence problem, re-derived
+identically by `evaluateOneRequirement`, not looked up from the adequacy
+result).
+
+**Coordinate mapping - the central problem this prompt solves.** Prompt 2
+regions and Prompt 3 tolerances are authored in reference-image pixels;
+`ObservationArtifact` target geometry is CSS pixels. This module establishes
+exactly one explicit, deterministic scale from `reference.applicability.viewport`
+(the CSS-pixel runtime viewport, Prompt 4) and the reference image's own
+pixel dimensions (Prompt 1) - `scaleX = imageWidth / viewportWidth`,
+`scaleY = imageHeight / viewportHeight` - and converts every candidate
+measurement into reference-image-pixel space before comparing it against a
+Prompt 3 tolerance. It never assumes 1 reference-image pixel equals 1 CSS
+pixel, and it never performs cropping, offset, rotation, or perspective
+registration - only a deliberately bounded full-frame mapping. `scaleX`/
+`scaleY` must agree within a small, independently-owned coordinate-mapping-
+validity tolerance (1% relative, never a user-authored design tolerance) or
+the mapping is rejected outright; a reference with no applicable viewport at
+all likewise has no mapping. Either way, every numeric (`region-property`/
+`region-measurement`) requirement becomes `unavailable`/`coordinate-mapping-unavailable`
+- categorical `region-relationship` requirements are unaffected (they never
+need a scale). Horizontal fields (`x`/`width`/`right`/`centerX` and the
+horizontal measurements) always scale by `scaleX`; vertical fields (`y`/
+`height`/`bottom`/`centerY` and the vertical measurements) always scale by
+`scaleY` - this falls out automatically from converting a full
+`TargetGeometry` into a `ReferenceRegionGeometry`-shaped value per axis,
+never a hand-picked per-property axis table.
+
+**Tolerance is reused exactly, never redefined.** A single rule -
+`abs(delta) <= allowedAmount` - covers all three Prompt 3 tolerance kinds:
+`exact` is simply the zero-tolerance case (`allowedAmount = 0`);
+`absolute-reference-px` uses its authored `amount` directly (already in
+reference-image pixels); `percent`'s denominator is `Math.abs(referenceValue)`,
+mirroring v0.5's own `toleranceToPx` "may vary by up to N%" convention
+exactly (independently reimplemented in reference-image-pixel units, never
+imported - `frontendContractEvaluation.ts`'s `ContractTolerance` is a
+different, CSS-pixel-implicit unit). No hidden epsilon is added anywhere;
+subpixel precision is preserved through to the final comparison, so a
+tolerance-boundary value (e.g. delta exactly equal to the allowed amount)
+passes and one unit past it fails, exactly as authored.
+
+**Region-property evaluation** reads `TargetGeometry` from the bound
+target's `targetEvidence` entry, converts it into a `ReferenceRegionGeometry`-
+shaped value (adding `centerX`/`centerY`, computed identically to
+`deriveReferenceRegionGeometry`) both raw (CSS) and scaled (reference-image
+pixels), and reads `[subject.property]` off each - `candidateRawValue`
+(CSS) and `candidateValue` (reference-image pixels) are both reported.
+
+**Region-measurement evaluation** converts *both* bound targets' geometries
+the same way and calls the existing `deriveReferenceRequirementMeasurement`
+(Prompt 3) on the converted geometries directly - reusing Prompt 3's exact
+gap/delta formulas rather than reimplementing a parallel "runtime version"
+of them, and never inventing a generic geometry expression language. A
+geometrically-undefined gap (the two targets overlap on the relevant axis)
+is `unavailable`, mirroring Prompt 3's own reference-side treatment of the
+identical situation.
+
+**Region-relationship evaluation** first confirms the reference itself
+actually exhibits its own selected relationship (`deriveReferenceRequirementExpectation`'s
+`matches` field) - if not, the result is `unavailable`/
+`reference-relationship-not-exhibited` (a reference-authoring problem, never
+a candidate `fail`). It then resolves both bound targets and calls the
+canonical `deriveLayoutRelationships` (v0.4) over the *whole* candidate
+observation - never a second, parallel relationship formula - and looks up
+the pairwise record for the bound target pair **scoped to the exact
+requested relationship family** (an independently-owned, third duplicate of
+the same `RELATIONSHIP_FAMILY_GROUPS` shape already used by
+`frontendContractEvaluation.ts` and `externalReferenceRequirements.ts` -
+this is the same real bug class Prompt 3 fixed: matching the first record
+for a target pair regardless of family would silently compare against the
+wrong relationship kind). A record only derivable in the reversed target
+order is `unavailable`, never auto-flipped - identical to Prompt 3's own
+reference-side handling of the same situation. `pass` requires the
+candidate's actual relationship kind to equal the requirement's authored
+`relationship` exactly.
+
+**Binding gate.** Every subject's dependent reference region(s) must have a
+`bound` (never `ambiguous`/`unavailable`, and never simply absent from the
+supplied declarations) Prompt 5 binding result, or the requirement is
+`unavailable`/`binding-unavailable` - this module never guesses another
+target and never auto-binds based on geometry or names. A `bound` target
+that is not visible (`TargetVisibility.visible !== true`, including when
+visibility evidence itself is unavailable) is treated as having no usable
+geometry - `unavailable`/`candidate-evidence-unavailable` - preserving the
+distinction between "binding succeeded" (Prompt 5's question) and "this
+evidence is usable for fidelity evaluation" (this prompt's question): a
+hidden-but-uniquely-resolved target still has a stable identity, but its
+geometry is never treated as meaningful for a numeric/relationship
+comparison.
+
+**Categories are preserved, never given different PASS/FAIL rules.**
+`category`/`expectedDependentMode` are carried through to each result as
+provenance only; Prompt 3 never implemented a `required`-vs-`permitted`
+directional evaluation difference for its own expectation/adequacy
+derivation (unlike v0.5's runtime-directional contract clauses), so Prompt 6
+does not invent one now - every requirement in the reference's authored
+collection is evaluated by the identical rule and counts identically toward
+the overall result, regardless of category.
+
+**Overall fidelity result.** For an evaluated (non-blocked) pair, `state`
+is `'pass'` only when every requirement result is `'pass'`; any `'fail'` or
+`'unavailable'` result forces `state: 'fail'` - there is no meaningful third
+overall bucket once evaluation has actually run, since "some/all
+unavailable" and "some/all fail" both equally mean "not every selected
+requirement is confirmed satisfied." A reference with zero selected
+requirements never reaches this stage at all - it is `inadequate` (Prompt
+3's own zero-requirements rule) and therefore `not-evaluated`, never a
+meaningless `pass`.
+
+**Persistence decision: none.** `evaluateReferenceCandidateFidelity` (and
+its CLI-facing wrapper, `evaluateReferenceCandidateFidelityFromArtifactRoots`)
+is a pure, on-demand function over already-persisted/in-memory evidence -
+no new `ExternalReferenceFidelityEvaluationArtifact` (or equivalent) is
+introduced. Rationale, identical to Prompt 4/5's own precedent: the result
+is cheap to recompute deterministically from its inputs (a reference, a
+candidate, and a caller-supplied binding-declaration collection), and
+persisting it would invite drift with no corresponding benefit at this
+stage; this may be revisited only if Prompt 7's architecture proves
+persistence necessary.
+
+**CLI**: `evaluate-reference-fidelity --reference <root> --candidate <root>
+[--bindings-file <json-file>] [--enforce]` - the CLI surface Prompt 5
+deliberately deferred. `--bindings-file` follows the exact
+`--requirements-file`/`--regions-file` wrapped-object convention
+(`{ "bindings": [...] }`); CLI code owns only flag syntax/file reading/JSON
+parsing/root-shape validation, with every binding-declaration rule staying
+owned by `isValidReferenceRuntimeBindingDeclarations`. `--enforce` mirrors
+`evaluate-contract`'s exact precedent: it changes only the process exit
+status for an already-computed `state: 'fail'` result, never the printed
+content - and has no effect on `not-evaluated`, which always exits 0 (a
+compatibility/adequacy blocker is a successful, structured, honest
+non-evaluation, never an execution error and never a design mismatch).
+Persists nothing; there is no `--output` flag.
+
+## v0.7 Prompt 7 bounded reference-fidelity projection and v0.6 bounded-agent-context integration
+
+Released as `0.7.0`. Additive extension of the v0.6 bounded-agent-context
+contract above and of the v0.7 Prompt 6 fidelity evaluator - no new bounded-
+context artifact family, no second visual-context system, no schema version
+bump (`BOUNDED_AGENT_CONTEXT_SCHEMA_VERSION` stays `1.0.0`, following the
+exact precedent already set when `correlations?` was added in v0.6 Batch 3).
+
+**Chosen integration owner.** `projectBoundedAgentContext` itself gains one
+new optional input (`fidelity?: ReferenceCandidateFidelityEvaluation`, plus
+`fidelityRequired?: boolean`) rather than a separate `VisualAgentContext`/
+`VisualPromptPacket`/`ReferencePromptBuilder`. This was chosen over a pure
+post-hoc "attach" step (the shape `attachRuntimeStaticCorrelations` uses)
+because fidelity-relevant runtime targets must compete fairly for
+`MAX_RUNTIME_TARGETS` capacity and receive the exact same geometry/
+visibility/screenshot assembly contract-clause-derived targets already get -
+an attach-only step run after target allocation could never produce that. A
+new pure module, `domain/referenceFidelityProjection.ts`
+(`projectReferenceFidelity`), derives the bounded, prioritized fidelity
+content plus the target-id/omission/truncation contributions
+`projectBoundedAgentContext` folds into its own existing pipeline - it is
+not a second fidelity-evaluation engine, only a selection over Prompt 6's
+already-computed result.
+
+```ts
+// domain/boundedAgentContext.ts - additive
+interface BoundedAgentContextSourceReferences {
+  // ...unchanged fields...
+  referenceId?: string;       // new, optional
+  referenceRequestId?: string; // new, optional
+}
+
+const MAX_FIDELITY_MISMATCHES = 15;
+const MAX_FIDELITY_PROTECTED_CONTEXT = 10; // reuses MAX_RELATIONSHIP_EVIDENCE_PER_TARGET's value
+
+interface BoundedReferenceFidelityProjection {
+  referenceId: string;
+  referenceRequestId: string;
+  candidateObservationId: string;
+  candidateRequestId: string;
+  adequacy: ReferenceRequirementAdequacy;   // reused verbatim from Prompt 3
+  compatibility?: ComparabilityResult;      // reused verbatim from Prompt 4
+  state: ReferenceFidelityState;            // reused verbatim from Prompt 6
+  blockedBy?: ReferenceFidelityBlockReason; // reused verbatim from Prompt 6
+  mismatches: ReferenceRequirementFidelityResult[];      // bounded, prioritized non-pass requirements (Prompt 6 type, unmodified)
+  protectedContext: ReferenceRequirementFidelityResult[]; // bounded passing protected/preserved requirements, as "do not break this" context
+}
+
+interface BoundedAgentContextArtifact {
+  // ...unchanged fields...
+  fidelity?: BoundedReferenceFidelityProjection; // new, optional - mirrors `correlations?`'s own additive precedent exactly
+}
+```
+
+**Selection policy** (`domain/referenceFidelityProjection.ts#projectReferenceFidelity`):
+only Prompt 6's non-`pass` requirement results are ever candidates for
+`mismatches` - passing requirements are never dumped by default, satisfying
+this prompt's "bounded coding-agent use" design goal. Each candidate is
+classified into a tier by its authored category/mode, reusing
+`boundedAgentContextProjection.ts#clauseTier`'s exact rule (duplicated, not
+imported, per this repository's established per-module small-helper
+convention - never a reference-specific protected/preserved taxonomy):
+`protected`/`preserved` are always `required`; `expected-dependent` is
+`required` only in `'required'` mode; `requested` and `expected-dependent`/
+`'permitted'` are `optional`.
+
+**Priority policy**: 1) `fail` + `required` tier, 2) `unavailable` +
+`required` tier, 3) any other non-`pass` (optional-tier) result. Within one
+priority class, Prompt 6's own authored requirement order is preserved (a
+stable sort by priority rank only) - never re-ranked by an opaque score.
+The final `mismatches` array is reported in priority order (highest first),
+not restored to authored order, since the whole point of prioritization is
+that the most actionable evidence appears first when the set is large.
+
+**Cap values**: `MAX_FIDELITY_MISMATCHES = 15` and
+`MAX_FIDELITY_PROTECTED_CONTEXT = 10` (reusing
+`MAX_RELATIONSHIP_EVIDENCE_PER_TARGET`'s value) - both judgment-call bounds
+in the same spirit as v0.6 Batch 1's own frozen caps (no measured fixture
+corpus exists yet for either concept).
+
+**Omission/truncation behavior**: reuses `OmissionRecord`/`TruncationRecord`
+wholesale, no second reporting model. When mismatches exceed the cap, a
+`{subject: 'fidelity-mismatches', limit, actualCount, required}` truncation
+is recorded, plus one `{subject: 'fidelity-mismatch:<requirementId>',
+reason: 'required-evidence-lost-by-bound', required: true}` omission for
+*each* dropped required-tier mismatch (optional-tier drops are truncated
+but never separately omitted as "required loss", since they were never
+required). `protectedContext` truncation is always `required: false` - it
+is confirmatory/passing context, never a design-fidelity failure. These
+records are folded into `projectBoundedAgentContext`'s own `omissions`/
+`truncations` arrays *before* its existing aggregate `capOmissions`/
+`capTruncations` calls and its existing adequacy computation run - fidelity
+loss is never a separate adequacy code path, it simply participates in the
+exact same `anyRequiredLoss`/`anyOptionalLoss` rule every other evidence
+source already uses.
+
+**Adequacy behavior**: a `not-evaluated` fidelity (blocked by Prompt 6's own
+`reference-inadequate`/`incompatible` gates) is never converted into "no
+problems" - `projectReferenceFidelity` records an explicit
+`{subject: 'fidelity', reason: 'unsupported-or-unavailable', required,
+detail}` omission, where `required` defaults to `true` (supplying a
+fidelity evaluation to be projected at all is itself the signal that the
+task depends on it, mirroring `CorrelationTargetInput.required`'s existing
+v0.6 convention - callers who want fidelity as purely incidental context set
+`fidelityRequired: false`). A `required: true` fidelity omission, folded
+into the existing adequacy computation, prevents `adequacy.state` from
+remaining `'adequate'` (it becomes `'partial'`, or `'inadequate'` when
+combined with other required loss reaching the existing threshold) - it is
+never silently ignored. A `required: false` omission can degrade adequacy
+to at most `'partial'`, per v0.6's own pre-existing "optional-only loss
+never means inadequate" rule - unchanged, not redefined. A `pass` fidelity
+result contributes no omissions/truncations at all and never degrades
+adequacy.
+
+**Not-evaluated fidelity behavior**: preserved exactly as Prompt 6 reported
+it - `fidelity.state`/`fidelity.blockedBy` on the output artifact are a
+direct pass-through of Prompt 6's own values, with `mismatches`/
+`protectedContext` both empty (there is nothing to select from an empty
+`requirementResults`).
+
+**Per-target organization**: every fidelity mismatch's `boundRuntimeTargets`
+(Prompt 5/6's own field, never truncated) becomes a required- or permitted-
+tier addition to `projectBoundedAgentContext`'s existing target-id sets,
+so those runtime targets receive full `BoundedRuntimeTargetProjection`
+treatment (geometry/visibility/overflow/scrollOwner/screenshotRef) through
+the exact existing assembly code - no duplicated target-projection logic.
+Reference regions are never used as a correlation or target-selection key;
+only the already-bound stable v0.2 runtime target ids are.
+
+**Multi-target relationship representation**: a `region-relationship`
+mismatch's `boundRuntimeTargets` array (already carrying both bound
+targets, from Prompt 6) is used as-is - both targets are added to the
+required/permitted set, so both appear in `targets`. Nothing collapses a
+two-target relationship failure onto a single target.
+
+**Static-correlation reuse**: entirely unchanged. `deriveRuntimeStaticCorrelations`/
+`attachRuntimeStaticCorrelations` are not modified, not called from within
+this prompt's new code, and remain the caller's own separate step -
+`BoundedRuntimeTargetProjection.targetId`/`RuntimeStaticCorrelationRecord.runtimeTargetId`
+already share the same stable v0.2 identity a fidelity mismatch's
+`boundRuntimeTargets` also uses, so a caller (Prompt 8) joins fidelity,
+target, and correlation evidence by that one shared id without this module
+ever needing to read source, run my-dev-kit, or choose among ambiguous
+candidates itself.
+
+**Ambiguous/unavailable correlation behavior**: unaffected - a
+`RuntimeStaticCorrelationRecord` with `status: 'ambiguous'` continues to
+preserve every competing candidate (v0.6's own frozen invariant,
+untouched), and `status: 'unavailable'` never causes a fidelity mismatch
+for that same runtime target to be dropped - the two evidence kinds
+(runtime fidelity, static correlation) are attached independently and
+neither erases the other.
+
+**Provenance**: every included mismatch remains traceable to the reference
+(`sources.referenceId`/`referenceRequestId`, new), the requirement
+(`requirementId`, `category`, `subject` - naming its reference region(s)),
+the Prompt 5 binding (`boundRuntimeTargets`), the candidate
+(`sources.observationIds`), and the full Prompt 6 evidence
+(`referenceValue`/`candidateRawValue`/`candidateValue`/`delta`/`tolerance`
+or `expectedRelationship`/`actualRelationship`) - nothing is replaced by a
+prose-only summary. No raw image bytes are ever embedded (fidelity carries
+only identifiers and numeric/categorical evidence, never pixels), and no
+source-ownership field (`sourceOwner`/`sourceFile`/`component`/`symbol`/
+`causedBy`) is ever produced - Prompt 7 stops at the runtime target exactly
+as Prompt 6 did; v0.6's own, unmodified static correlation is the only
+source-adjacent evidence this context ever carries, and it remains
+evidence, never edit authorization.
+
+**Identity impact**: `buildBoundedAgentContextRequestIdentity` gained a
+final optional `fidelity?: unknown` parameter - omitted (never `null`) from
+the hashed semantic view when absent, so every pre-Prompt-7 call site keeps
+producing its exact byte-identical hash (verified by a frozen-vector-style
+regression test). When present, the caller's already-derived, bounded
+`BoundedReferenceFidelityProjection` (not the raw Prompt 6 evaluation) is
+hashed, so identity changes exactly when the content a caller would
+actually receive changes - never merely because an unselected, dropped
+requirement result changed somewhere upstream. `sources.referenceId`/
+`referenceRequestId` follow the identical omit-when-absent convention.
+Operational paths were never an identity input for this artifact family to
+begin with (no path parameter exists anywhere in this contract), so path
+independence holds trivially.
+
+**Schema-version decision**: no bump. Every new field
+(`BoundedAgentContextSourceReferences.referenceId`/`referenceRequestId`,
+`BoundedAgentContextArtifact.fidelity`) is additive and optional; a
+pre-Prompt-7 artifact/consumer remains fully valid and behaviorally
+unchanged with all of them absent, matching the exact precedent
+`correlations?` already established without a version bump in v0.6 Batch 3.
+
+**Persistence decision: none.** `projectBoundedAgentContext` and
+`projectReferenceFidelity` both remain pure, programmatic, in-memory
+functions - no new writer/reader, no new artifact family. This mirrors
+Prompt 6's own "no persisted fidelity artifact" decision and v0.6's
+existing "bounded agent context is library-only" architecture.
+
+**CLI decision**: none added. v0.6 bounded agent context has never had a
+CLI surface, and this prompt does not introduce one - Prompt 8 is expected
+to become the first concrete consumer of `projectBoundedAgentContext`'s
+(now fidelity-aware) programmatic output.
+
+## v0.7 Prompt 8 controlled end-to-end external-reference coding-agent correction workflow
+
+Released as `0.7.0`. One new pure domain module,
+`domain/referenceCorrectionWorkflow.ts`, plus its identity counterpart,
+`domain/referenceCorrectionIdentity.ts` - the first stage that composes
+every Prompt 1-7 and v0.1/v0.4/v0.5/v0.6 owner into one traceable
+reference-driven correction cycle. It reimplements none of them: reference
+lifecycle/adequacy (Prompt 1/3), compatibility (Prompt 4), binding (Prompt
+5), fidelity (Prompt 6), bounded context (Prompt 7), runtime comparison
+(v0.4 `compareObservations`), and contract evaluation (v0.5
+`evaluateFrontendContract`) are all called, never re-derived. No new
+persisted artifact family, no CLI surface, no remote AI dependency, and no
+mechanism anywhere in this module (or any module it calls) that edits
+target source.
+
+```ts
+// domain/referenceCorrectionWorkflow.ts
+function prepareReferenceCorrection(input: {
+  reference: ExternalReferenceArtifact;       // must be approved
+  baselineObservation: ObservationArtifact;   // approved baseline / pre-change state
+  baselineContract: PersistentBaselineContract;
+  changeContract: PerChangeContract;
+  bindingDeclarations: readonly ReferenceRuntimeBindingDeclaration[];
+  currentObservation: ObservationArtifact;    // fidelity is measured against this (= baselineObservation for the canonical proof)
+  generatedAt: string; producerVersion: string; projectionProfile: ProjectionProfile;
+}): { ok: true; status: 'handoff-ready'; reviewRequestId: string; fidelity: ReferenceCandidateFidelityEvaluation; handoff: ReferenceCorrectionHandoff }
+  | { ok: true; status: 'blocked-not-evaluated'; reviewRequestId: string; fidelity: ReferenceCandidateFidelityEvaluation }
+  | { ok: false; reason: string };
+
+function reviewReferenceCorrectionAttempt(input: {
+  // ...same reference/baselineObservation/baselineContract/changeContract/bindingDeclarations...
+  reviewRequestId: string;              // must match the id prepareReferenceCorrection returned for this exact semantic review
+  candidateObservation: ObservationArtifact; // fresh, post-edit capture
+  priorAttemptId?: string;
+}): { ok: true; attempt: ReferenceCorrectionAttemptResult } | { ok: false; reason: string };
+```
+
+**Workflow architecture.** A narrowly-scoped coordinator, not a second
+workflow engine: it holds no stage catalog, no job scheduler, and no
+generic orchestration graph. It performs exactly two operations - "prepare"
+(pre-change evidence -> bounded handoff) and "review" (post-edit candidate
+-> one composed overall result) - matching this prompt's own explicit
+guidance that the external-edit boundary must remain a visible seam between
+two separate calls, never one command that blocks waiting for an external
+actor.
+
+**New owners introduced**: `prepareReferenceCorrection`,
+`reviewReferenceCorrectionAttempt` (composition only - no new evaluation
+logic), `buildReferenceCorrectionReviewIdentity`/
+`buildReferenceCorrectionAttemptIdentity` (deterministic identity, see
+below), and the plain `ReferenceCorrectionHandoff`/
+`ReferenceCorrectionAttemptResult` result shapes.
+
+**Existing owners reused, verbatim**: `isApprovedExternalReferenceArtifact`
+(Prompt 1), `isValidReferenceRuntimeBindingDeclarations` (Prompt 5),
+`evaluateReferenceCandidateFidelity` (Prompt 6), `projectBoundedAgentContext`
+(Prompt 7, itself now fidelity-aware), `compareObservations` (v0.4),
+`evaluateFrontendContract` (v0.5). None of their internal logic is
+inspected, duplicated, or reimplemented by this module - only their
+top-level results are read.
+
+**Approved-reference/approved-baseline requirement.** `prepareReferenceCorrection`
+and `reviewReferenceCorrectionAttempt` both fail closed (`{ok: false}`) if
+`reference` is not in the `'approved'` lifecycle state (Prompt 1's own
+`isApprovedExternalReferenceArtifact` guard) - an imported-but-unapproved
+reference is never treated as an authoritative target design. Neither
+function ever calls `approveExternalReference`/`approveAndPersistBaseline`
+itself; approval remains the caller's own separate, explicit action.
+
+**Pre-change candidate = approved baseline observation**, for the canonical
+proof: `prepareReferenceCorrection`'s `currentObservation` and
+`baselineObservation` are the same value, so the initial reference fidelity
+can genuinely `FAIL` (measuring the gap between the current, already-
+approved implementation and the desired new design) while the baseline
+itself stays fully valid and approved. A caller's own architecture may
+supply a distinct `currentObservation` only when justified - the workflow
+does not require them to be identical, only that `currentObservation` and
+`candidateObservation` are always independently validated
+`ObservationArtifact`s.
+
+**Preparation (phase A)**: validates the common preconditions (approved
+reference, matching baseline/contract coherence, valid binding
+declarations), evaluates reference fidelity via Prompt 6 against
+`currentObservation`, and - only when that evaluation actually produced a
+result (`state !== 'not-evaluated'`) - projects it into a bounded context
+via Prompt 7/v0.6 and returns the `ReferenceCorrectionHandoff`. A
+`not-evaluated` fidelity (inadequate reference, or reference/candidate
+incompatible state) is reported as `status: 'blocked-not-evaluated'` -
+carrying the full Prompt 6 result for inspection, but never a fabricated
+handoff pretending evidence is adequate. An ambiguous or unavailable
+required binding does **not** block preparation outright - it still
+produces a `handoff-ready` result, with the ambiguity/unavailability
+visible directly in that requirement's own `unavailable`/`binding-
+unavailable` mismatch (Prompt 6's own honest per-requirement reporting,
+unchanged), so the external actor sees exactly why that specific
+requirement cannot yet be assessed.
+
+**The handoff** (`ReferenceCorrectionHandoff`) carries `reviewRequestId`,
+`referenceId`/`referenceRequestId`, `baselineObservationId`,
+`currentObservationId`, the full Prompt 7 `boundedContext` (already
+containing bounded fidelity mismatches, protected/preserved context,
+adequacy/omission/truncation, and - when the caller supplied it - runtime/
+static correlation), and a fixed, four-line `verificationPlan` explaining
+in plain language what will be re-checked after the edit (fresh Chromium
+capture, reference re-evaluation, v0.4/v0.5 re-evaluation, and the exact
+overall-PASS rule) - never reduced to "make it look like the screenshot".
+No raw reference image bytes, no full `ObservationArtifact`, and no source
+excerpt are ever included.
+
+**Handoff persistence: none.** The handoff is a plain, JSON-serializable,
+in-memory value returned directly to the caller - no new writer/reader, no
+new artifact family. A caller that needs the handoff to cross a process/
+session boundary (e.g. to hand it to an external coding-agent process) is
+free to serialize it with its own mechanism; observer product code does not
+own a persisted handoff artifact. This was a deliberate "smallest possible"
+choice: the handoff's only genuinely new identity is `reviewRequestId`
+(already deterministic and recomputable from stable inputs - see below), so
+nothing about it requires observer-managed persistence to remain
+traceable.
+
+**Review identity** (`buildReferenceCorrectionReviewIdentity`): a pure
+function of `{referenceRequestId, baselineObservationId,
+baselineContractId, baselineContractClauses, changeContractId,
+changeContractClauses, bindingDeclarations}` only - never a timestamp,
+never an operational file path. Deliberately hashes each contract's own
+authored `clauses` content, not merely its `baselineId`/`contractId` label:
+unlike this repository's content-derived identities elsewhere (e.g.
+`ObservationArtifact.observationId`), a `PersistentBaselineContract`'s
+`baselineId` and a `PerChangeContract`'s `contractId` are plain, caller-
+authored strings (`approveAndPersistBaseline` persists `contract.baselineId`
+verbatim, never recomputing it from `clauses`) - so two structurally valid
+contracts could in principle share an id while authoring different clauses.
+Hashing clause content directly closes that gap (caught during this
+prompt's own independent-judge review before being reported PASS - see the
+report's Tooling incidents section). `reviewReferenceCorrectionAttempt`
+recomputes this same hash from its own inputs and rejects the call
+(`{ok: false}`) if the caller-supplied `reviewRequestId` does not match -
+this is the mechanism that makes "no hidden baseline change" an enforced
+invariant rather than a documented intention: an attempt claiming to belong
+to a review while actually supplying a different baseline observation,
+baseline contract (id or clause content), per-change contract (id or clause
+content), reference, or binding set can never silently succeed.
+
+**Attempt identity** (`buildReferenceCorrectionAttemptIdentity`): a pure,
+deterministic function of `{reviewRequestId, candidateObservationId}` only
+- deliberately never a fresh random nonce. Every candidate observation
+already carries its own fresh, collision-resistant instance identity (v0.1's
+`buildObservationIdentity`), so hashing it together with the review it was
+captured for gives an attempt id that is both reproducible (the same
+review+candidate pair always yields the same `attemptId`) and guaranteed
+distinct per real capture.
+
+**Attempt history**: caller-managed, not observer-persisted. Because both
+workflow functions are pure (no internal mutable state, no side effects),
+an already-returned `ReferenceCorrectionAttemptResult` can never be
+overwritten by a later call - a caller that keeps every attempt result it
+receives (in memory, in its own log, or in its own storage) has a complete,
+immutable, traceable history for free, linked via each attempt's own
+`reviewRequestId` (shared across all attempts of one review),
+`priorAttemptId` (an optional, purely informational link to the immediately
+preceding attempt, carried through unchanged - never consulted by the
+evaluation logic itself), and `attemptId`.
+
+**Baseline-across-attempts rule**: enforced structurally, not merely
+documented. Every call to `reviewReferenceCorrectionAttempt` requires the
+caller to re-supply `baselineObservation`/`baselineContract` in full, and
+`compareObservations`/`evaluateFrontendContract` are always invoked with
+that same baseline against the fresh `candidateObservation` - there is no
+code path anywhere in this module that compares one candidate against a
+prior candidate instead. Combined with the `reviewRequestId` coherence
+check above, a caller cannot silently swap in a different baseline between
+attempts of the same review without the call being rejected.
+
+**Overall result composition.** `ReferenceCorrectionOverallState =
+'not-evaluated' | 'pass' | 'fail'`:
+
+- `fidelity.state === 'not-evaluated'` -> overall `'not-evaluated'` - Prompt
+  6's own explicit blocked state is preserved exactly, never collapsed into
+  an ordinary `'fail'`.
+- otherwise, `fidelity.state === 'pass' && contractEvaluation.overallVerdict === 'PASS'`
+  -> overall `'pass'`; anything else -> overall `'fail'`.
+
+A structurally-incomparable baseline/candidate pair is *not* given its own
+third overall bucket - v0.5's own `evaluateFrontendContract` already
+returns `'FAIL'` (never `'PASS'`) for that case, per its own established,
+unmodified precedent, and this workflow reuses that decision rather than
+re-litigating it. `approvalEligible` is a plain, read-only boolean
+(`true` iff `overallState === 'pass'`) - it is never itself an approval
+action; the caller must still invoke the existing explicit
+`approveAndPersistBaseline`/`approveExternalReference` owners separately,
+and neither is ever called from within this module.
+
+**Correction iteration**: `reviewReferenceCorrectionAttempt` is called once
+per candidate; the caller decides whether and when to call it again after
+another external edit. There is no loop, no polling, no automatic retry,
+and no mechanism in this module that itself waits for or drives an external
+implementation step - the production boundary between "prepare a handoff"
+and "review a candidate" is the explicit seam a human or an external
+process controls.
+
+**Source-editing boundary**: absolute. Neither this module nor anything it
+calls opens, reads, parses, or writes any target source file; both public
+operations accept only already-captured `ObservationArtifact`s and already-
+approved contract/reference artifacts. Real-Chromium candidate capture is
+always the caller's own responsibility, through the existing, unmodified
+observation pipeline (`runBrowserCapture`/`buildObservationArtifact`, the
+same functions `application/observationPersistence.ts#observe` already
+uses) - Prompt 8 adds no second browser adapter, screenshot engine, target
+resolver, or evidence-capture path.