@dailephd/my-frontend-observer 0.8.1 → 0.9.0

package/docs/reports/v0.9-architecture-retrieval.md

@@ -0,0 +1,567 @@
+# v0.9 Architecture Retrieval
+
+## 1. VERDICT
+
+`PASS_V0_9_ARCHITECTURE_RETRIEVAL_COMPLETE`
+
+This is a current-source inspection report for planning only. It does not select
+or recommend a v0.9 architecture.
+
+## 2. Repository identity
+
+- Repository: `C:\Users\daile\Projects\my-frontend-observer` (the working copy
+  available in this environment; repository instructions identify the logical
+  repository as `Z:\Users\newuser\Projects\my-frontend-observer`).
+- Branch: `master`.
+- HEAD: `473713d240af09e752eeb8e00735738c4927b16d`.
+- Package version: `0.8.1`.
+- Preflight worktree: clean. The initial `git status --short` produced no
+  entries.
+- No commit, push, reset, checkout, stash, or clean operation was performed.
+
+## 3. my-dev-kit retrieval evidence
+
+### Index
+
+- Existing same-repository/version indexes found before indexing: none under
+  `.my-dev-kit-context/indexes/`.
+- Removed or replaced older indexes: none.
+- Installed/published command version: `@dailephd/my-dev-kit 1.12.3`.
+- Fresh index path:
+  `.my-dev-kit-context/indexes/my-frontend-observer-v0.8.1-20260916T202252`.
+- The CLI contract supports repeated `--src`; one invocation covered both
+  production roots:
+
+  ```text
+  npx --yes @dailephd/my-dev-kit index --root . --src src --src viewer --out .my-dev-kit-context/indexes/my-frontend-observer-v0.8.1-20260916T202252 --json
+  ```
+
+- Index result: 126 TypeScript files, 1,170 symbols, 2,168 edges; syntax,
+  frontend semantic, and frontend reachability artifacts completed without
+  errors. Data-model and classification analyzers reported warnings but did
+  not prevent the index from being produced.
+
+### Retrieval commands and selected nodes
+
+- Retrieval help commands used:
+  `npx --yes @dailephd/my-dev-kit search --help`, `lookup --help`,
+  `slice --help`, and `source --help`.
+- Search commands, all against the fresh index, were:
+  `search --query artifactWriter`, `ExternalReferenceArtifact`,
+  `FrontendContractEvaluationArtifact`, `projectBoundedAgentContext`,
+  `TargetOverlaySvg`, `ReferenceRegionOverlaySvg`, `ReferenceWorkspace`,
+  `useZoomPan`, `deriveCoordinateScale`, `ReferenceRegion`,
+  `AuthoredChangeScopeCategory`, and `projectWorkflow`, each with
+  `--limit 10 --json`.
+- Selected search node IDs included:
+  - `symbol:src/domain/frontendContractEvaluationArtifact.ts#FrontendContractEvaluationArtifact`
+  - `symbol:src/domain/externalReferenceRegions.ts#ReferenceRegion`
+  - `symbol:src/domain/frontendContracts.ts#AuthoredChangeScopeCategory`
+  - `symbol:src/artifacts/externalReferenceArtifactWriter.ts#writeExternalReferenceArtifact`
+  - `symbol:viewer/src/components/TargetOverlaySvg.tsx#TargetOverlaySvg`
+  - `symbol:viewer/src/components/ReferenceRegionOverlaySvg.tsx#ReferenceRegionOverlaySvg`
+  - `symbol:viewer/src/hooks/useZoomPan.ts#useZoomPan`
+  - `symbol:src/viewerServer/viewerService.ts#startViewer`
+  - `symbol:src/projectWorkflow/aliasCatalog.ts#AliasCatalog`
+  - `symbol:src/domain/boundedAgentContextProjection.ts#projectBoundedAgentContext`
+- Lookup commands used for the writer, viewer startup, both SVG components,
+  and `ReferenceRegion`, with `--depth 2 --json`.
+- Slice commands used for the external-reference writer, viewer startup, and
+  reference overlay, with `--depth 2 --direction both --json`; the overlay
+  slice also used `--include-event-handlers`.
+- Source commands retrieved exact symbols/ranges for the artifact domain,
+  external-reference writer, viewer startup, both workspaces and overlays,
+  zoom/pan, contract vocabulary, alias catalog, and evidence discovery.
+  Three attempted source node names did not exist (`writeArtifact`,
+  `persistExternalReference`, `ProjectConfig`, and `discoverEvidence` in the
+  attempted symbol spelling); the owning exported symbols were then inspected
+  by bounded file/range retrieval.
+- Exact source command form was:
+  `npx --yes @dailephd/my-dev-kit source --index <index> --node <selected-node> --include-local-deps --max-bundle-lines <bound> --format plain`.
+- Whole-file fallback count for production or test source: `0`. Bounded
+  retrieval and line-ranged source inspection answered the questions. The full
+  `agents.txt` read was repository operating-instruction reading, not a
+  production/test fallback.
+
+## 4. Existing artifact-family architecture
+
+### Domain and validation owners
+
+- Observation domain/schema: `src/domain/schema.ts`; `ObservationArtifact`,
+  `isValidObservationArtifact`, `ARTIFACT_KIND`, and `SCHEMA_VERSION`.
+- Observation identity: `src/domain/identity.ts#buildRequestIdentity` is
+  deterministic SHA-256 over semantic request configuration; output location,
+  timeout, timestamps, and runtime results are excluded. Fresh instance
+  identity is `buildObservationIdentity`.
+- Comparison domain/engine/identity: `src/domain/comparison.ts`,
+  `src/domain/comparisonEngine.ts`, and `src/domain/comparisonIdentity.ts`.
+  Comparison persistence is `src/artifacts/comparisonArtifactWriter.ts` and
+  `comparisonArtifactReader.ts`.
+- Frontend baseline/per-change contracts: `src/domain/frontendContracts.ts`.
+  It owns `PersistentBaselineContract`, `PerChangeContract`, primitive and
+  clause representations, structural validators, and the shared contract kind
+  and schema version.
+- Contract identity: `src/domain/frontendContractIdentity.ts` owns
+  `buildFrontendContractRequestIdentity`, fresh
+  `buildFrontendContractInstanceIdentity`, clause identity, and evaluation
+  request identity.
+- Contract evaluation artifact: `src/domain/frontendContractEvaluationArtifact.ts`
+  owns `FrontendContractEvaluationArtifact`, its schema/kind, builder, and
+  structural validator. The artifact references baseline/contract, before/after
+  observations, comparison request identity, verdict, clause results, and
+  unexpected changes.
+- External reference domain: `src/domain/externalReference.ts`, with identity
+  in `src/domain/externalReferenceIdentity.ts`. `ExternalReferenceArtifact` is
+  the imported/approved lifecycle union. Request identity includes image
+  content/dimensions, supersession, and supplied regions/requirements/
+  applicability; instance identity adds fresh random bytes.
+
+### Readers, writers, application seams, CLI, and exports
+
+- Observation writer/reader: `src/artifacts/artifactWriter.ts#writeObservationArtifact`
+  and `src/artifacts/artifactReader.ts#readObservationArtifact`; the writer
+  persists `manifest.json` and `screenshot.png`.
+- Comparison writer/reader: `src/artifacts/comparisonArtifactWriter.ts#writeComparisonArtifact`
+  and `src/artifacts/comparisonArtifactReader.ts#readComparisonArtifact`.
+- Contract writer/reader: `src/artifacts/frontendContractArtifactWriter.ts#writePersistentBaselineContract`,
+  `writePerChangeContract`, `frontendContractArtifactReader.ts#readPersistentBaselineContract`,
+  and `readPerChangeContract`.
+- Evaluation writer/reader:
+  `src/artifacts/frontendContractEvaluationArtifactWriter.ts#writeFrontendContractEvaluationArtifact`
+  and `frontendContractEvaluationArtifactReader.ts#readFrontendContractEvaluationArtifact`.
+- External reference writer/reader:
+  `src/artifacts/externalReferenceArtifactWriter.ts#writeExternalReferenceArtifact`
+  and `externalReferenceArtifactReader.ts#readExternalReferenceArtifact`.
+- Application persistence seams:
+  `src/application/observationPersistence.ts`, `comparisonService.ts`,
+  `frontendContractPersistenceService.ts`,
+  `frontendContractEvaluationService.ts`, and
+  `externalReferencePersistenceService.ts`. The latter is the canonical
+  `importExternalReference`/approval use case and calls the identity, domain
+  validation, reader, and writer owners.
+- CLI integration and dispatch are in `src/cli.ts`. The current commands
+  include `observe`, `compare`, `approve-baseline`, `save-change-contract`,
+  `evaluate-contract`, `import-reference`, `approve-reference`,
+  `evaluate-reference-fidelity`, plus project `init`, `capture`, `check`, and
+  `view`.
+- Public library exports are in `src/index.ts`. The current file exports domain
+  types/validators/builders and contract/reference artifact readers/writers;
+  it is the public export boundary rather than an implementation layer.
+
+### Persistence pattern
+
+All established artifact writers validate before writing, derive a final
+directory from the fresh instance ID, refuse an existing final directory, write
+to a sibling `.tmp-<id>` directory, write `manifest.json` (and observation
+media where owned), then atomically rename the temporary directory. On failure,
+the temporary directory is removed. Readers parse and structurally validate the
+manifest; they do not silently coerce unsupported versions.
+
+### Tests
+
+- `tests/unit/artifactWriter.test.ts` suite `artifactWriter` protects complete
+  observation roots, required media, round trips, and no-overwrite behavior.
+- `tests/unit/artifactWriterFailure.test.ts` protects invalid input and
+  filesystem failure handling.
+- `tests/browser/artifactPersistence.test.ts` protects real-browser/CLI
+  persistence paths.
+- `tests/unit/comparisonIdentity.test.ts`, `comparisonPersistence.test.ts`,
+  `comparisonArtifactWriterFailure.test.ts`, and
+  `tests/unit/frontendContractIdentity.test.ts` protect deterministic identity,
+  fresh instance IDs, persistence, and failure behavior.
+- `tests/unit/frontendContracts.test.ts`, `frontendContractPersistence.test.ts`,
+  `frontendContractEvaluation.test.ts`, and `frontendContractEvaluationArtifact.test.ts`
+  protect structural clauses, persistence service behavior, evaluation, and
+  artifact validation.
+- `tests/unit/externalReferenceIdentity.test.ts`,
+  `externalReferenceArtifactWriter.test.ts`,
+  `externalReferencePersistence.test.ts`, and
+  `tests/browser/referenceCorrectionWorkflow.test.ts` protect reference
+  identity, writer/reader behavior, import/approval/supersession, and the
+  real workflow.
+
+An annotation artifact is not assumed here. The existing extension options are
+to reuse an existing family only if its domain contract actually fits, or add a
+new family following the same domain-validator/identity-reader-writer/
+application/CLI/export/test pattern.
+
+## 5. Existing viewer-server architecture
+
+- Startup/application seam: `src/viewerServer/viewerService.ts#startViewer`.
+  It validates the root, selects built assets via `defaultViewerAssetsRoot`,
+  passes session-only bindings/context/alias metadata into
+  `createViewerServer`, and listens only on `127.0.0.1` using
+  `src/viewerServer/port.ts`.
+- HTTP routing: `src/viewerServer/httpServer.ts#handleRequest`.
+  Only `GET` and `HEAD` are accepted; other methods receive `405` and
+  `Allow: GET, HEAD`. The server serves status/index/artifact/media APIs,
+  relationship, comparison, evaluation, reference, candidate, binding, and
+  fidelity/context routes, plus the static viewer shell.
+- Evidence discovery/indexing: `src/viewerServer/evidence/discovery.ts#discoverManifests`
+  finds bounded `manifest.json` files; `evidence/index.ts#buildEvidenceIndexMetadata`
+  rebuilds metadata on every request, limits records, classifies, and projects
+  metadata. `loadArtifactByHandle` performs on-demand full loading and
+  revalidation.
+- Classification: `src/viewerServer/evidence/classify.ts#classifyManifest`.
+  Supported families are observation, comparison, baseline contract, change
+  contract, contract evaluation, imported external reference, and approved
+  external reference. It dispatches to the canonical reader for each family;
+  the reader remains the structural authority. New persisted families are not
+  discovered automatically: classification requires an explicit kind/version
+  branch, reader, and family projection.
+- Handles and containment: `evidence/handles.ts` creates/decodes opaque
+  evidence-relative handles; `evidence/pathSafety.ts#resolveContainedDir` and
+  `resolveContainedFile` fail closed on traversal, separators, NULs, and
+  absolute escape. `mediaResolver.ts#resolveMedia` restricts roles and uses
+  `lstat` to reject non-regular files and symlink-like escapes.
+- Media resolution: `evidence/mediaResolver.ts#resolveMedia` resolves
+  observation `screenshot`, imported-reference `image`, and approved-reference
+  `source-image`. Approved source image resolution uses the canonical logical
+  `referenceId` to rediscover the imported artifact; it does not treat a stored
+  path as provenance.
+- Observation relationship route: `httpServer.ts` dispatches
+  `/api/observations/:handle/relationships` to
+  `evidence/observationView.ts#getObservationRelationships`, which invokes the
+  canonical relationship derivation once for the selected observation.
+- Comparison/evaluation routes: `/api/comparisons/:handle/view` and
+  `/api/evaluations/:handle/view` dispatch to `comparisonView.ts` and
+  `evaluationView.ts`. They resolve canonical artifacts and linked evidence;
+  they do not recompute comparison or contract evaluation in the browser.
+- Reference route: `/api/references/:handle/view` dispatches to
+  `referenceView.ts#getReferenceView`, which invokes exactly the canonical
+  `deriveReferenceRegionRelationships` and
+  `deriveReferenceRequirementAdequacy` functions over persisted regions and
+  requirements. These results are ephemeral projections, not persisted.
+- Candidate route: `/api/references/:reference/candidate/:candidate/view`
+  invokes canonical compatibility and coordinate/fidelity support in
+  `referenceView.ts`; it also discovers referenced evaluation handles.
+- Binding route: `/api/references/:reference/candidate/:candidate/bindings`
+  invokes `isValidReferenceRuntimeBindingDeclarations` and
+  `evaluateReferenceRuntimeBindings` using startup-supplied session input.
+- Fidelity route: `/api/references/:reference/candidate/:candidate/fidelity`
+  invokes `getReferenceFidelity`, which uses the canonical
+  `deriveCoordinateScale` and `evaluateReferenceCandidateFidelity` path.
+- Context route: `src/viewerServer/context.ts` classifies a supplied
+  bounded-agent-context artifact at startup; the viewer does not rebuild it.
+
+The one-canonical-engine rule is visible in these server call sites: the
+viewer server may resolve, call, and project supplied evidence, but it is not a
+second relationship, compatibility, binding, fidelity, bounded-context, or
+runtime/static-correlation engine. Viewer routes are read-only and session
+bindings/context are not persisted.
+
+Closest server tests are `tests/unit/viewerServer.test.ts`,
+`viewerEvidenceServer.test.ts`, `referenceViewerServer.test.ts`,
+`contextViewerServer.test.ts`, `paths.test.ts`, and `evidenceDiscovery.test.ts`.
+
+## 6. Runtime screenshot coordinate architecture
+
+- `viewer/src/components/ObservationWorkspace.tsx#ObservationWorkspace` owns
+  presentation selection (`selected`), overlay toggles, ordered targets, the
+  screenshot media URL, and the relationship hook. Selection resets when the
+  artifact handle changes.
+- `viewer/src/observation/targetOrder.ts#orderedTargets` owns deterministic
+  target ordering.
+- `viewer/src/components/TargetOverlaySvg.tsx#TargetOverlaySvg` renders the
+  screenshot and target geometry. Its `viewBox` is
+  `0 0 requestConfig.viewport.width requestConfig.viewport.height`; the
+  viewport is the captured CSS-pixel frame. The `<image>` fills that frame and
+  target `geometry.x/y/width/height` is used unchanged.
+- No `devicePixelRatio` multiplication, rounding, or clamping is performed.
+  Out-of-frame geometry remains evidence and is only clipped by SVG display
+  overflow. Missing/partial geometry does not receive a fabricated rectangle.
+- Selection and highlighting are UI-only props: `selected` drives
+  `aria-pressed` and the selected class; optional `highlightNames` is a visual
+  secondary emphasis. Click and Enter/Space keyboard handlers call `onSelect`.
+- `viewer/src/hooks/useZoomPan.ts#useZoomPan` owns presentation zoom/pan. It
+  uses scale `1..8`, step `1.25`, derives viewBox from frame dimensions and
+  focal point, resets uncontrolled state on frame changes, and maps pointer
+  coordinates with `getScreenCTM().inverse()`. Pan begins only after a 3-screen-
+  pixel drag threshold; focal points clamp to the frame. `ZoomPanBinding` is a
+  rendering-only subset passed to the SVG leaf.
+
+Closest protection is `tests/browser/observationSvgWorkspace.test.ts`, covering
+  screenshot/media loading, exact rectangles, unresolved targets, selection in
+  both directions, relationship connectors, and aspect-ratio/viewBox alignment.
+  Zoom/pan coverage is in `tests/browser/observationComparison.test.ts`,
+  `referenceCandidateWorkspace.test.ts`, and the focused viewer workspace
+  suites; the hook’s direct unit coverage is in the corresponding viewer hook
+  test locations where present.
+
+## 7. External-reference coordinate architecture
+
+- `src/domain/externalReferenceRegions.ts#ReferenceRegion` is the canonical
+  authored region: `{id, rectangle:{x,y,width,height}}`.
+- Reference coordinates are reference-image pixels, origin at the image
+  top-left, with fractional values permitted. They are never CSS pixels.
+  `isValidReferenceRegionRectangle` rejects non-finite, negative, or nonpositive
+  values; `isValidReferenceRegions` bounds count, deduplicates IDs
+  case-insensitively, and rejects rectangles outside image dimensions. Derived
+  right/bottom/centers are recomputed, not persisted.
+- `viewer/src/components/ReferenceWorkspace.tsx#ReferenceWorkspace` owns
+  selected region, candidate handle/target selection, overlay toggles,
+  optional evaluation selection, explicit binding highlights, and view lock.
+  It resets presentation state when the reference handle changes.
+- `viewer/src/components/ReferenceRegionOverlaySvg.tsx#ReferenceRegionOverlaySvg`
+  uses `viewBox="0 0 imageWidth imageHeight"`, renders the reference image at
+  those dimensions, and renders `region.rectangle` unchanged. Its IDs are
+  `data-region-id` values and are not runtime target names.
+- The reference overlay has separate `requirementRegionIds` and
+  `highlightRegionIds` presentation props. A bound cross-selection highlights
+  the other domain without changing that domain’s primary interactive
+  selection.
+- Reference and runtime views share the `useZoomPan` interaction machinery,
+  but each supplies its own frame dimensions and SVG coordinate domain.
+  `deriveCoordinateScale` in `src/domain/externalReferenceFidelity.ts` is the
+  canonical cross-domain mapping used by fidelity evaluation; it is not a
+  reason to merge region identity with target identity.
+
+Closest tests are `tests/browser/referenceCandidateWorkspace.test.ts`,
+`referenceBindingFidelityWorkspace.test.ts`, `referenceCorrectionWorkflow.test.ts`,
+and `tests/unit/referenceViewerServer.test.ts`. They protect image/region
+selection, explicit binding cross-highlighting, no implicit equal-name binding,
+zoom/pan/view lock, and server-side canonical derivation.
+
+## 8. Reference-region / requirement / binding / fidelity architecture
+
+- Regions are explicit user/configuration input carried in imported and approved
+  external-reference artifacts. Rectangle geometry is persisted; derived
+  geometry and region relationships are not.
+- Region relationships are derived by
+  `src/domain/externalReferenceRegionRelationships.ts#deriveReferenceRegionRelationships`.
+- Requirements are explicit design intent over regions. Their domain is
+  `src/domain/externalReferenceRequirements.ts`; requirement identity is in
+  `externalReferenceRequirementIdentity.ts`, and adequacy is derived by
+  `deriveReferenceRequirementAdequacy`. Requirement categories reuse
+  `AuthoredChangeScopeCategory`; `unexpected` cannot be authored.
+- Applicability is explicit external-reference input owned by
+  `src/domain/externalReferenceApplicability.ts` and participates in reference
+  identity. It is not inferred by the viewer.
+- Bindings are session/configuration input owned by
+  `src/domain/externalReferenceRuntimeBinding.ts`. The viewer startup receives
+  declarations, validates/evaluates them per selected pair, and does not
+  persist them. Binding identity is therefore not an artifact identity.
+- Compatibility is derived by `externalReferenceCompatibility.ts`.
+- Coordinate scale and fidelity are derived by
+  `externalReferenceFidelity.ts`; fidelity is not the same as compatibility,
+  adequacy, or binding status.
+- Imported and approved reference artifacts are persisted; region relationships,
+  adequacy, compatibility, binding evaluation, coordinate mapping, and fidelity
+  are derived on demand or evaluation-artifact output, depending on workflow.
+- `externalReferencePersistenceService.ts` validates and persists authored
+  regions/requirements/applicability as part of import/approval. Approval carries
+  these fields forward from imported evidence; it does not mutate the prior
+  artifact.
+
+## 9. Existing contract/change-scope architecture
+
+- Owner: `src/domain/frontendContracts.ts`.
+- Authored categories are exactly `requested`, `expected-dependent`, `protected`,
+  and `preserved`; `unexpected` is only a derived evaluator classification.
+- Contract primitives are a closed vocabulary in `CONTRACT_PRIMITIVE_KINDS`.
+  Clauses carry primitive-specific subjects and optional bounded tolerances.
+- `PersistentBaselineContract` and `PerChangeContract` share the artifact kind
+  and schema but are structurally distinct and are selected by their
+  `contractClass`/validator shape.
+- Baseline approval is owned by
+  `src/application/frontendContractPersistenceService.ts#approveAndPersistBaseline`.
+  Per-change persistence is `persistPerChangeContract`. Both validate with the
+  domain validator and delegate to the artifact writer; no viewer operation
+  constructs or approves contracts.
+- Evaluation is owned by
+  `src/application/frontendContractEvaluationService.ts` and the canonical
+  domain evaluator. The evaluation artifact persists clause results and
+  unexpected changes, but a failure verdict is a valid artifact, not a write
+  failure.
+- Viewer display is projection/UI only: `src/viewerServer/evidence/evaluationView.ts`,
+  `viewer/src/components/EvaluationWorkspace.tsx`, and clause-target helpers.
+- There is no existing public function that turns arbitrary annotation input
+  into a confirmed contract intent. The existing public service accepts already
+  structured/authored baseline or per-change contracts and deliberately keeps
+  approval separate from observation, comparison, and evaluation.
+
+## 10. v0.8.1 project/alias architecture
+
+- Project configuration: `src/projectWorkflow/projectConfig.ts` owns
+  `frontend-observer.json`, schema versions `1.0.0`/`1.1.0`, project targets,
+  default baseline, and optional acceptance paths. It delegates target/request
+  validation to `normalizeRequest` and rejects non-portable or escaping paths.
+- Project discovery: `src/projectWorkflow/projectDiscovery.ts` discovers the
+  nearest project config; `src/application/projectWorkflowService.ts` owns
+  initialization, named capture, replacement, and viewer state loading.
+- Managed paths: `src/projectWorkflow/projectPaths.ts` derives
+  `.frontend-observer/catalog.json`, `.frontend-observer/evidence`, and
+  `.frontend-observer/evidence/observations` from one project root.
+- Alias catalog: `src/projectWorkflow/aliasCatalog.ts` stores schema `1.0.0`
+  records containing alias, canonical `observationId`, canonical `requestId`,
+  and `relativeArtifactDir`. It is atomically written and validated for safe
+  relative directories.
+- Aliases are selectors, not persisted artifact identities. The canonical
+  observation directory and its `observationId` remain authoritative. Replacement
+  creates a fresh observation instance and leaves the prior directory intact;
+  the catalog changes which current artifact the alias selects.
+- Viewer startup receives ephemeral
+  `ViewerAliasMetadata`; `buildEvidenceIndexMetadata` attaches an alias only to
+  the matching observation relative directory. Artifact handles and logical IDs
+  remain canonical.
+- `view` discovers project evidence when `--root` is omitted. `init`, `capture`,
+  and `check` dispatch through `src/cli.ts` to application/project workflow
+  owners rather than embedding persistence semantics.
+- A future artifact could be placed under the project evidence root only by
+  using a canonical artifact-relative directory and identity; the alias catalog
+  must not be used as provenance. The current evidence classifier does not
+  accept arbitrary new persisted families without explicit classification and
+  reader branches.
+
+## 11. Persistence/lifecycle precedents
+
+- Observation, comparison, contract, evaluation, and external-reference writers
+  use immutable per-instance directories, sibling temporary directories, atomic
+  rename, no-overwrite checks, and cleanup on failure.
+- Request/logical identity is deterministic from canonical semantic content;
+  instance identity is fresh and opaque. Timestamps are not used as the sole
+  instance identity.
+- External reference import and approval support an explicit `supersedes`
+  reference. `externalReferencePersistenceService.ts` reads the superseded
+  artifact to resolve its logical ID, while the writer writes a new artifact.
+- Contract baseline approval preserves an authored `supersedesBaselineId` and
+  never mutates or removes the prior baseline. Evaluation preserves source
+  references and creates a fresh `evaluationId`.
+- Alias replacement updates the alias catalog only; previous canonical artifact
+  directories remain unchanged.
+- There is no current forward-pointer mutation in artifact manifests beyond
+  explicit supersession/reference fields, and no writer silently replaces prior
+  evidence.
+
+## 12. Closest test architecture
+
+- A. Structural validation: `tests/unit/schema.test.ts`,
+  `comparison.test.ts`, `frontendContracts.test.ts`,
+  `externalReference.test.ts`, and `frontendContractEvaluationArtifact.test.ts`.
+  Protect required fields, versions, closed vocabularies, geometry, and
+  lifecycle validation.
+- B. Identity determinism: `tests/unit/identity.test.ts`,
+  `comparisonIdentity.test.ts`, `frontendContractIdentity.test.ts`, and
+  `externalReferenceIdentity.test.ts`. Protect semantic hashing, array order,
+  exclusion of paths/timestamps, and fresh instance IDs.
+- C. Writer/reader round trip: `tests/unit/artifactWriter.test.ts`,
+  `comparisonPersistence.test.ts`, `frontendContractPersistence.test.ts`,
+  `externalReferencePersistence.test.ts`, and
+  `tests/browser/artifactPersistence.test.ts`.
+- D. Application persistence service: `tests/unit/observationPersistence.test.ts`,
+  `comparisonPersistence.test.ts`, `frontendContractPersistence.test.ts`, and
+  `externalReferencePersistence.test.ts`.
+- E. CLI parsing/orchestration: `tests/unit/cli.test.ts`,
+  `cliFrontendContracts.test.ts`, `cliExternalReference.test.ts`,
+  `cliEvaluateReferenceFidelity.test.ts`, and `cliProjectWorkflow.test.ts`.
+- F. Viewer discovery/classification: `tests/unit/evidenceDiscovery.test.ts`.
+  Protect deterministic manifest discovery, family classification, honest
+  malformed/unsupported states, metadata-only indexing, and no arbitrary-file
+  inclusion.
+- G. Path containment: `tests/unit/paths.test.ts`,
+  `tests/unit/viewerEvidenceServer.test.ts`, and `tests/unit/policy.test.ts`.
+  Protect portable paths, root containment, symlink handling, and method/error
+  boundaries.
+- H. Runtime SVG selection/highlighting: `tests/browser/observationSvgWorkspace.test.ts`.
+  Protect exact geometry, unresolved-target omission, list/SVG selection, and
+  visual highlights.
+- I. Reference SVG selection/highlighting: `tests/browser/referenceCandidateWorkspace.test.ts`
+  and `referenceBindingFidelityWorkspace.test.ts`.
+- J. Zoom/pan: `tests/browser/observationComparison.test.ts`,
+  `referenceCandidateWorkspace.test.ts`, and focused workspace scenarios in the
+  browser suite. These protect fit/reset, viewBox, pointer pan, and view lock.
+- K. Explicit binding cross-selection: `tests/browser/referenceBindingFidelityWorkspace.test.ts`
+  (`Case A - explicit bound cross-selection`). It protects declared-only,
+  many-to-one reverse highlighting and keeps primary selection separate.
+- L. Real-browser viewer behavior: `tests/browser/viewerIntegratedAcceptance.test.ts`,
+  `viewerEvidenceShell.test.ts`, `observationSvgWorkspace.test.ts`,
+  `referenceCandidateWorkspace.test.ts`, and
+  `referenceBindingFidelityWorkspace.test.ts`.
+- M. PWA/API cache boundary: `tests/browser/pwaHardening.test.ts` protects real
+  service-worker registration, shell precache, no `/api/` cache entries, and
+  explicit unavailable state when the server is down.
+- N. Packed installed-package viewer smoke: `scripts/ci/runPackedViewerSmoke.mjs`.
+  It owns pack/install/launch checks for the shipped viewer boundary; the
+  analogous observation package path is `runPackedObservationSmoke.mjs`.
+- O. Project-aware viewer behavior: `tests/browser/projectWorkflowViewer.test.ts`
+  and `tests/browser/projectCheckWorkflow.test.ts`; unit ownership is
+  `tests/unit/projectWorkflow.test.ts`, `projectCheckService.test.ts`, and
+  `projectCheckResult.test.ts`. These protect init/capture/replace, canonical
+  paths, alias projection, and project check flow.
+
+## 13. Package/release boundary
+
+- `package.json#files` allows `dist`, `README.md`, `CHANGELOG.md`, `docs`, and
+  `LICENSE`; source `src/`, `viewer/src/`, and tests are not package payload.
+- `npm run build` runs `tsc -p tsconfig.json` and `vite build --config
+  viewer/vite.config.ts`, producing compiled library/CLI output and
+  `dist/viewer` assets.
+- `package.json#exports["."]` exposes `./dist/index.js`; the CLI bin is
+  `dist/cli.js`.
+- A new public persisted domain capability needs its domain/application/artifact
+  code compiled into `dist`, any public types/functions added deliberately to
+  `src/index.ts`, CLI dispatch/help if applicable, viewer server classification/
+  routes/projections if displayable, and viewer build output if UI changes.
+- `scripts/ci/runPackedViewerSmoke.mjs` is the packed-candidate viewer proof;
+  `tests/browser/*` real-Chromium suites are source-checkout behavior proof.
+  Source tests alone do not prove npm package contents.
+
+## 14. Planner-relevant constraints
+
+- `ReferenceRegionOverlaySvg` and `TargetOverlaySvg` intentionally use separate
+  coordinate domains. Reference-region identity is not runtime-target identity.
+- Runtime target geometry is captured/rendered in viewport CSS pixels without
+  device-pixel-ratio conversion, rounding, or clamping.
+- The viewer is GET/HEAD-only, loopback-only, read-only, metadata-first, and
+  must not become an evidence or domain derivation engine.
+- Evidence discovery currently requires explicit artifact-family classification
+  and canonical reader dispatch; arbitrary new manifests are reported as
+  unrecognized rather than auto-supported.
+- Canonical readers remain the sole structural validation authority at the
+  viewer boundary.
+- Viewer derivation call sites are explicit: observation relationships in
+  `observationView.ts`, reference relationships/adequacy and pair computations
+  in `referenceView.ts`, and route dispatch in `httpServer.ts`.
+- Bindings and bounded context are session input. They are read once by startup,
+  not persisted or browser-selected by file path.
+- Aliases select canonical artifact directories and never provide artifact
+  provenance or replace canonical IDs.
+- Artifact persistence is immutable by precedent: fresh instance directory,
+  atomic temp-directory rename, no overwrite, and previous artifacts retained.
+- Supersession is represented as authored logical identity/reference data; it
+  does not authorize destructive mutation of the superseded artifact.
+- `unexpected` is evaluator output, not an authored contract category.
+- Reference-image pixels are not runtime/CSS pixels; cross-domain interpretation
+  goes through the existing coordinate-scale/fidelity owners.
+- PWA caching may cache shell/assets but must not make stale evidence/API/media
+  responses authoritative after the evidence root or server changes.
+- Shipping a capability requires the compiled `dist` boundary, public exports
+  where applicable, CLI/viewer integration where applicable, and packed smoke
+  coverage, not only source-checkout tests.
+
+## 15. Open questions genuinely not answerable from current code
+
+- The current implementation does not define whether v0.9 authored visual
+  annotations are a new persisted artifact family, fields on an existing family,
+  or a separate authored layer; that is a planner-owned product/architecture
+  decision.
+- The current code does not define the semantic identity inputs, supersession
+  rules, or media payload shape for a future annotation artifact.
+- The current code does not define whether annotation authoring should be
+  exposed through a CLI, project workflow, viewer-only session, or another
+  application service.
+- The current viewer has no mutation route; the authorization and persistence
+  boundary for any future authoring interaction is therefore unresolved by
+  existing code.
+- The current code does not specify how authored annotation geometry should
+  behave when a runtime viewport or reference image is resized or unavailable;
+  existing runtime and reference coordinate contracts remain the only grounded
+  precedents.
+
+## 16. Retrieval compliance
+
+- my-dev-kit used before whole production/test source reads: `yes`.
+- Full-file production/test fallbacks: `0`.
+- Unexplained full-file fallbacks: `0`.
+- The only generated managed retrieval state is the fresh index listed in
+  section 3. The only requested tracked repository report is this file.