@dailephd/my-frontend-observer 0.10.0 → 0.10.1

package/docs/reports/v0.10-batch5-reference-driven-entry.md

@@ -1,238 +1,238 @@
-# v0.10 Batch 5 Reference-Driven Entry
-
-## 1. Verdict
-
-PASS. The original attempt remained preserved as failure history below. The correction completed the frozen responsibility coverage, independent browser proofs, and PWA hard-gate synchronization repair; every mandatory canonical command is green.
-
-## 2. Repository
-
-- Repository: `C:\Users\daile\Projects\my-frontend-observer`
-- Starting commit: `eeb8154180eea7cd143921f3fe52c328e153aab4`
-- Branch: `feature/v0.10-full-visual-workflow`
-
-## 3. Retrieval and fresh index
-
-- Resolved my-dev-kit: `1.12.4`; CLI reported `1.12.4`.
-- Install: `.my-dev-kit-workflow/tools/v0.10-batch5/`.
-- Index: `.my-dev-kit-context/indexes/my-frontend-observer-v0.10-batch5-20260922`.
-- Command: `node .my-dev-kit-workflow/tools/v0.10-batch5/node_modules/@dailephd/my-dev-kit/dist/cli.js index --root C:\Users\daile\Projects\my-frontend-observer --src src --src viewer/src --src tests --src scripts --out C:\Users\daile\Projects\my-frontend-observer\.my-dev-kit-context\indexes\my-frontend-observer-v0.10-batch5-20260922 --call-graph --json`.
-- Summary: 299 files, 2,460 symbols, 4,669 edges, zero index-level warnings/errors.
-- Syntax, call graph, frontend semantic, and frontend reachability were complete. Data-model and classification were partial with 820 and 2,407 warnings.
-
-## 4. Reused precedents and owners
-
-The implementation reuses `approveExternalReference`, `deriveReferenceRequirementAdequacy`, `isValidReferenceRuntimeBindingDeclarations`, `evaluateReferenceRuntimeBindings`, `buildReferenceRequirement`, `createProjectVisualChangeWorkflow`, the exact annotation/source view, project alias catalog, serialized authoring queue, Batch 3 authoring security, exact workflow-ID navigation, and Batch 2 activation.
-
-## 5. Approval route and supersession
-
-`POST /api/references/:handle/approve` accepts exactly `{}` and only a supported imported reference. It resolves a declared predecessor to one exact supported reference root and fails closed otherwise. It calls canonical approval once, returns bounded identity/count/adequacy data, and does not change project acceptance. The Viewer exposes a separate `Approve reference` action and exact approved-ID reselection.
-
-## 6. Materialization separation
-
-Existing materialization remains imported-only. It does not approve, create a workflow, activate acceptance, or run a check.
-
-## 7. Reference workflow start
-
-`POST /api/references/:handle/start-visual-change` accepts only `annotationHandle`, `itemIds`, `baselineObservationHandle`, and `bindings`. It requires an approved route target, exact approved-reference annotation source, confirmed executable reference intent already represented in the approved artifact, adequate requirements, an exact aliased baseline observation, configured reference acceptance, canonical compatibility, canonical declaration validation, complete required-region coverage, and `bound` canonical results.
-
-## 8. Baseline contract and scope
-
-The route freezes the selected exact observation. It freezes a valid configured persistent baseline contract only when contract acceptance exists. It creates the existing `VisualChangeReferenceScope` with contained project-relative paths and delegates persistence to `createProjectVisualChangeWorkflow`. Creation does not activate or change project configuration.
-
-## 9. Viewer binding authoring
-
-The workflow-binding draft is separate from session bindings, begins empty, and resets when the reference or baseline observation changes. Region/target selection alone does not bind. `Add workflow binding` creates an explicit pair; a duplicate region is disabled until explicit `Remove`. Different regions may use the same target. The existing reference-intent checkbox selection is shared with workflow start.
-
-## 10. Navigation, activation, and automatic checks
-
-Successful creation uses the existing exact workflow-ID callback to switch to Visual changes. Activation remains the existing explicit Batch 2 action. No materialization, approval, creation, or activation path invokes a check.
-
-## 11. Identity proof
-
-Unit tests prove that changing the approved reference, binding declaration, baseline observation, or saved annotation revision changes `visualChangeRequestId` through the unchanged Batch 1 identity owner.
-
-## 12. Validation
-
-- `npm run typecheck`: PASS.
-- `npm run lint`: PASS.
-- Focused suites: PASS, 58 tests.
-- `npm test`: PASS, 95 files and 1,500 tests.
-- `npm run build`: PASS.
-- `npm run test:browser`: FAIL, 29 files/277 tests passed; the unchanged PWA hard gate timed out at `navigator.serviceWorker.ready`.
-- `npm run test:pwa-hard-gate`: FAIL with the same 60-second timeout, both before and after a fresh build and with Playwright API diagnostics.
-- `npm run test:security`: FAIL because its 16 unit files/168 tests and other browser security tests passed, but the same PWA hard gate timed out.
-- `npm run check:docs`: PASS.
-- `git diff --check`: PASS (line-ending conversion warnings only).
-
-## 13. Browser acceptance and materialization/approval proof
-
-The frozen independent Batch 5 real-browser acceptance gate and focused materialization-plus-approval proof are not yet implemented. Existing Batch 1-4 browser regressions passed except for the unchanged PWA timeout described above. These missing proofs are ordinary correctable work and prevent PASS.
-
-## 14. Protocol and schema preservation
-
-`VIEWER_PROTOCOL_VERSION` remains `1.3.0`. No external-reference, annotation, visual-change, project-config, or observation schema was changed.
-
-## 15. Full-file read accounting
-
-Whole source/test fallback reads were used after bounded search, lookup, slice, symbol source, local dependency expansion, and continuation proved that my-dev-kit stores symbol start lines without reliable end lines and truncated multi-symbol bundles at the output/block bounds.
-
-- `viewer/src/components/ReferenceWorkspace.tsx` (493 lines, source): establish complete hook/state/JSX insertion points after symbol source omitted the function tail; changed implementation.
-- `src/viewerServer/annotationReferenceMaterialization.ts` (115 lines, source): establish the complete serialized materialization adapter precedent; did not change that file.
-- `src/viewerServer/evidence/index.ts` (153 lines, source): establish exact supported-handle and unique identity behavior; did not change that file.
-- `src/application/visualAnnotationReferenceMaterializationService.ts` (222 lines, source): establish exact intent representation and canonical requirement construction; did not change that file.
-- `src/domain/externalReferenceRuntimeBinding.ts` (290 lines, source): establish complete validator/evaluator result shape and hidden-target semantics; did not change that file.
-- `viewer/src/components/ArtifactPreview.tsx` (82 lines, source): establish reference workspace callback ownership; changed implementation.
-- `viewer/src/hooks/useRuntimeVisualChangeStart.ts` (19 lines, source): establish hook lifecycle/request precedent; did not change that file.
-- `viewer/src/App.tsx` (104 lines, source): establish exact workflow navigation and record selection ownership; changed implementation.
-- `viewer/src/hooks/useEvidenceIndex.ts` (42 lines, source): establish refresh return shape; did not change that file.
-
-Other source inspection used bounded ranges. Canonical documentation reads are excluded from source/test fallback accounting.
-
-## 16. Batch 6 and later exclusions
-
-No coding-agent handoff, orchestrator integration, source editing, automatic retry/check, correction, review, acceptance, abandon, final baseline/reference governance, version bump, release, publication, PR, or Batch 6 work was implemented.
-
-## 17. Exact next action
-
-Commit the reviewed Batch 5 files with `feat: add v0.10 reference visual change flow`, push the shared feature branch, and stop. Batch 6 begins only under a separate authorized task.
-
-## 18. Correction continuation (2026-09-22)
-
-The uncommitted implementation was preserved. Correction work added focused approval/start-route coverage, the two required fresh-state Chromium proofs, reference-mutation concurrency protection, and a state-based PWA readiness synchronization. No reference-domain redesign occurred.
-
-- Correction my-dev-kit: `1.12.4`, pinned at `.my-dev-kit-workflow/tools/v0.10-batch5-correction/`; CLI identity matched exactly.
-- Correction index: `.my-dev-kit-context/indexes/my-frontend-observer-v0.10-batch5-correction-20260922`.
-- Exact command: `node .my-dev-kit-workflow/tools/v0.10-batch5-correction/node_modules/@dailephd/my-dev-kit/dist/cli.js index --root C:\Users\daile\Projects\my-frontend-observer --src src --src viewer/src --src tests --src scripts --out C:\Users\daile\Projects\my-frontend-observer\.my-dev-kit-context\indexes\my-frontend-observer-v0.10-batch5-correction-20260922 --call-graph --json`.
-- Index result: 304 files, 2,480 symbols, 4,761 call-graph edges, zero index warnings/errors; syntax/call-graph/frontend analyzers complete; data-model/classification partial with 834/2,429 warnings.
-
-## 19. Required browser proofs
-
-`MATERIALIZATION + APPROVAL PROOF: keeps import and approval explicit, immutable, superseding, and acceptance-neutral` passes independently. It creates its project/evidence/server/context, proves the successor remains imported until the separate click, then proves fresh approval identity, request identity preservation, supersession, source/import immutability, exact approved reselection, and unchanged project acceptance.
-
-`ACCEPTANCE GATE: creates and explicitly activates an exact reference-mode workflow without running a check` passes independently. It creates a valid aliased baseline and adequate approved reference, authors/saves/confirms exact-source intent in Chromium, explicitly authors both bindings, creates and reselects the exact inactive workflow, proves exact annotation/reference/baseline/bindings and zero attempts, explicitly activates, proves same request/new workflow identity and exact acceptance paths, and proves zero attempts/latest check `none` remain.
-
-## 20. PWA diagnosis and correction
-
-The initial failure was **Class C — test synchronization defect**. On the loopback secure origin, the Service Worker API was present, built `/`, `/index.html`, `/registerSW.js`, `/sw.js`, and `/manifest.webmanifest` were HTTP-available, and `getRegistration()` reached an active worker at the exact origin scope while Chromium on this Windows host left the first `navigator.serviceWorker.ready` synchronization unresolved. There was no worker-script, registration, request, console, or precache failure.
-
-The hard gate now uses bounded Playwright polling of `getRegistration()` until the exact registration exists, is active, and owns `${origin}/`. It then separately retains the controller assertion and every substantive safety fact: live evidence, shell/entry precache, zero `/api/` cache entries, live API reachability, Node-side server-down proof, offline shell reload, controlled page, explicit unavailable evidence, stale identity disappearance, and cleanup. It does not manually register a worker, add sleeps/retries, cache API/media/evidence, or weaken any assertion.
-
-- First isolated hard gate: PASS (1 passed, 6 skipped).
-- Second consecutive fresh-profile hard gate: PASS (1 passed, 6 skipped).
-- Complete `pwaHardening.test.ts`: PASS (7/7).
-- Canonical browser: PASS (30 files, 280 tests).
-- Canonical security: PASS (16 unit files/168 tests; 3 browser files/77 tests; nested hard gate PASS).
-
-## 21. TST-B5 responsibility ledger
-
-Every entry below names the concrete automated proof. Shared tests are intentionally repeated where one scenario establishes several frozen facts.
-
-| ID | Test file — exact test name | Result |
-|---|---|---|
-| TST-B5-001 | `referenceApproval.test.ts` — `returns 404 for an unknown handle, 409 for an approved reference, and requires project authoring security` | PASS |
-| TST-B5-002 | same named approval rejection test | PASS |
-| TST-B5-003 | `referenceApproval.test.ts` — `approves exactly once into one fresh immutable instance, preserves request identity, leaks no path, and leaves acceptance unchanged` | PASS |
-| TST-B5-004 | same named immutable approval test | PASS |
-| TST-B5-005 | same named immutable approval test | PASS |
-| TST-B5-006 | `referenceAnnotationMaterialization.test.ts` — `MATERIALIZATION + APPROVAL PROOF: keeps import and approval explicit, immutable, superseding, and acceptance-neutral` | PASS |
-| TST-B5-007 | `referenceApproval.test.ts` — `fails closed when a declared predecessor cannot be uniquely resolved` | PASS |
-| TST-B5-008 | named immutable approval test | PASS |
-| TST-B5-009 | named immutable approval test | PASS |
-| TST-B5-010 | named approval rejection/security test | PASS |
-| TST-B5-011 | `referenceVisualChangeRoute.test.ts` — `rejects imported scope, exact-source mismatch, non-executable intent, missing alias, missing acceptance, and structural binding errors` | PASS |
-| TST-B5-012 | `referenceVisualChangeRoute.test.ts` — `creates an exact inactive reference scope with optional contract omitted, zero attempts, no config mutation, and no path leakage` | PASS |
-| TST-B5-013 | named route rejection test | PASS |
-| TST-B5-014 | named route rejection test | PASS |
-| TST-B5-015 | `referenceAnnotationMaterialization.test.ts` — `keeps informational and candidate items unselectable, and forced API requests for them are rejected without a write` | PASS |
-| TST-B5-016 | materialization subset test plus `ACCEPTANCE GATE...` exact represented region | PASS |
-| TST-B5-017 | `materializes only the selected subset: a created region and a requirement against it, never the unselected create` | PASS |
-| TST-B5-018 | `referenceCandidateWorkspace.test.ts` — `shows the image with no region rectangles and an honest "no requirements selected" state` | PASS |
-| TST-B5-019 | Batch 5 `ACCEPTANCE GATE...` | PASS |
-| TST-B5-020 | named route rejection test | PASS |
-| TST-B5-021 | named route rejection test | PASS |
-| TST-B5-022 | named route rejection test | PASS |
-| TST-B5-023 | `visualChangeProjectWorkflowService.test.ts` — `freezes exact project evidence without activating acceptance, then activates and restores immutable revisions` | PASS |
-| TST-B5-024 | named exact inactive reference-scope test | PASS |
-| TST-B5-025 | `externalReferenceRuntimeBinding.test.ts` — `F: an incompatible reference/candidate viewport blocks ordinary binding evaluation - no bound result fabricated` | PASS |
-| TST-B5-026 | named route rejection test | PASS |
-| TST-B5-027 | named route rejection test | PASS |
-| TST-B5-028 | named route rejection test | PASS |
-| TST-B5-029 | `referenceVisualChangeRoute.test.ts` — `allows several required regions to bind explicitly to the same unique runtime target` | PASS |
-| TST-B5-030 | named route rejection test | PASS |
-| TST-B5-031 | `externalReferenceRuntimeBinding.test.ts` — `D: an ambiguously resolved runtime target is reported ambiguous, never bound` | PASS |
-| TST-B5-032 | `externalReferenceRuntimeBinding.test.ts` — `C: an unknown runtime target (not configured on this candidate) is reported unavailable` | PASS |
-| TST-B5-033 | named exact inactive reference-scope test | PASS |
-| TST-B5-034 | named exact inactive reference-scope test | PASS |
-| TST-B5-035 | named exact inactive reference-scope test | PASS |
-| TST-B5-036 | named exact inactive reference-scope test | PASS |
-| TST-B5-037 | named exact inactive reference-scope test | PASS |
-| TST-B5-038 | named exact inactive reference-scope test | PASS |
-| TST-B5-039 | named exact inactive reference-scope test | PASS |
-| TST-B5-040 | named exact inactive reference-scope test | PASS |
-| TST-B5-041 | named exact inactive reference-scope test | PASS |
-| TST-B5-042 | named exact inactive reference-scope test | PASS |
-| TST-B5-043 | `MATERIALIZATION + APPROVAL PROOF...` | PASS |
-| TST-B5-044 | `materializes a confirmed created region into a new imported revision without approval, config change, or switching the viewed reference` | PASS |
-| TST-B5-045 | `MATERIALIZATION + APPROVAL PROOF...` | PASS |
-| TST-B5-046 | `MATERIALIZATION + APPROVAL PROOF...` | PASS |
-| TST-B5-047 | `MATERIALIZATION + APPROVAL PROOF...` | PASS |
-| TST-B5-048 | Batch 5 `ACCEPTANCE GATE...` | PASS |
-| TST-B5-049 | `referenceBindingFidelityWorkspace.test.ts` — `a reference region and runtime target sharing the literal name "header" never cross-select without an explicit declaration` | PASS |
-| TST-B5-050 | same named no-inference binding test | PASS |
-| TST-B5-051 | Batch 5 `ACCEPTANCE GATE...` | PASS |
-| TST-B5-052 | Batch 5 `ACCEPTANCE GATE...` | PASS |
-| TST-B5-053 | Batch 5 `ACCEPTANCE GATE...` (authored pair has explicit `Remove`) | PASS |
-| TST-B5-054 | `externalReferenceRuntimeBinding.test.ts` — `J: rejects a conflicting declaration mapping the same reference region to two different targets, never silently choosing the first` | PASS |
-| TST-B5-055 | fresh-project Batch 5 `ACCEPTANCE GATE...` | PASS |
-| TST-B5-056 | fresh baseline selection in Batch 5 `ACCEPTANCE GATE...` | PASS |
-| TST-B5-057 | Batch 5 `ACCEPTANCE GATE...` | PASS |
-| TST-B5-058 | `referenceVisualChangeAuthoring.test.ts` — `accepts exactly the four start fields and rejects activation/path injection` | PASS |
-| TST-B5-059 | same closed-request test | PASS |
-| TST-B5-060 | Batch 5 `ACCEPTANCE GATE...` | PASS |
-| TST-B5-061 | Batch 5 `ACCEPTANCE GATE...` | PASS |
-| TST-B5-062 | Batch 5 `ACCEPTANCE GATE...` | PASS |
-| TST-B5-063 | Batch 5 `ACCEPTANCE GATE...` | PASS |
-| TST-B5-064 | Batch 5 `ACCEPTANCE GATE...` | PASS |
-| TST-B5-065 | Batch 5 `ACCEPTANCE GATE...` | PASS |
-| TST-B5-066 | Batch 5 `ACCEPTANCE GATE...` | PASS |
-| TST-B5-067 | Batch 5 `ACCEPTANCE GATE...` | PASS |
-| TST-B5-068 | Batch 5 `ACCEPTANCE GATE...` | PASS |
-| TST-B5-069 | Batch 5 `ACCEPTANCE GATE...` | PASS |
-| TST-B5-070 | Batch 5 `ACCEPTANCE GATE...` | PASS |
-| TST-B5-071 | `referenceVisualChangeAuthoring.test.ts` — `changes identity when approved reference changes` | PASS |
-| TST-B5-072 | same table test — `changes identity when binding changes` | PASS |
-| TST-B5-073 | same table test — `changes identity when baseline observation changes` | PASS |
-| TST-B5-074 | same table test — `changes identity when annotation revision changes` | PASS |
-| TST-B5-075 | reference annotation authoring save/revision suite in canonical browser run | PASS |
-| TST-B5-076 | reference annotation explicit confirmation suite in canonical browser run | PASS |
-| TST-B5-077 | first four named `referenceAnnotationMaterialization.test.ts` tests | PASS |
-| TST-B5-078 | six named `referenceCandidateWorkspace.test.ts` cases | PASS |
-| TST-B5-079 | `referenceBindingFidelityWorkspace.test.ts` — `clicking a bound reference region cross-highlights its exact declared runtime target, and vice versa` | PASS |
-| TST-B5-080 | same file — `Case G: a real canonical PASS is displayed with requirement values only after the explicit trigger is clicked` | PASS |
-| TST-B5-081 | canonical `npm test` Batch 1 suites | PASS |
-| TST-B5-082 | canonical `npm test` Batch 2 suites | PASS |
-| TST-B5-083 | canonical browser/security Batch 3 suites | PASS |
-| TST-B5-084 | `runtimeAnnotationContractPromotion.test.ts` — `ACCEPTANCE GATE: creates an inactive actual workflow from confirmed runtime intent and explicitly activates its immutable revision` | PASS |
-| TST-B5-085 | viewer protocol assertion suite; `VIEWER_PROTOCOL_VERSION = '1.3.0'` | PASS |
-
-## 22. Final correction validation
-
-- `npm run typecheck`: PASS.
-- `npm run lint`: PASS.
-- `npm test`: PASS, 97 files/1,506 tests.
-- Focused approval/start-route: PASS, 12 tests.
-- Focused Batch 5 browser proof file: PASS, 6 tests.
-- `npm run test:browser`: PASS, 30 files/280 tests.
-- `npm run test:security`: PASS.
-- `npm run test:pwa-hard-gate`: PASS twice consecutively, plus once inside security.
-- Full `pwaHardening.test.ts`: PASS, 7 tests.
-- `npm run build`: PASS; generated PWA precache has 10 entries.
-- `npm run check:docs`: PASS.
-- `git diff --check`: PASS (Git line-ending notices only).
-- Viewer protocol remains `1.3.0`; no governed schema version changed.
-
-## 23. Correction retrieval and fallback accounting
-
-Correction retrieval followed search → lookup → slice → exact symbol source → continuation/dependency expansion → bounded ranges. Correction-run additional full source/test file reads: none.
-
-The historical fallback ledger in section 15 is retained unchanged.
+# v0.10 Batch 5 Reference-Driven Entry
+
+## 1. Verdict
+
+PASS. The original attempt remained preserved as failure history below. The correction completed the frozen responsibility coverage, independent browser proofs, and PWA hard-gate synchronization repair; every mandatory canonical command is green.
+
+## 2. Repository
+
+- Repository: `C:\Users\daile\Projects\my-frontend-observer`
+- Starting commit: `eeb8154180eea7cd143921f3fe52c328e153aab4`
+- Branch: `feature/v0.10-full-visual-workflow`
+
+## 3. Retrieval and fresh index
+
+- Resolved my-dev-kit: `1.12.4`; CLI reported `1.12.4`.
+- Install: `.my-dev-kit-workflow/tools/v0.10-batch5/`.
+- Index: `.my-dev-kit-context/indexes/my-frontend-observer-v0.10-batch5-20260922`.
+- Command: `node .my-dev-kit-workflow/tools/v0.10-batch5/node_modules/@dailephd/my-dev-kit/dist/cli.js index --root C:\Users\daile\Projects\my-frontend-observer --src src --src viewer/src --src tests --src scripts --out C:\Users\daile\Projects\my-frontend-observer\.my-dev-kit-context\indexes\my-frontend-observer-v0.10-batch5-20260922 --call-graph --json`.
+- Summary: 299 files, 2,460 symbols, 4,669 edges, zero index-level warnings/errors.
+- Syntax, call graph, frontend semantic, and frontend reachability were complete. Data-model and classification were partial with 820 and 2,407 warnings.
+
+## 4. Reused precedents and owners
+
+The implementation reuses `approveExternalReference`, `deriveReferenceRequirementAdequacy`, `isValidReferenceRuntimeBindingDeclarations`, `evaluateReferenceRuntimeBindings`, `buildReferenceRequirement`, `createProjectVisualChangeWorkflow`, the exact annotation/source view, project alias catalog, serialized authoring queue, Batch 3 authoring security, exact workflow-ID navigation, and Batch 2 activation.
+
+## 5. Approval route and supersession
+
+`POST /api/references/:handle/approve` accepts exactly `{}` and only a supported imported reference. It resolves a declared predecessor to one exact supported reference root and fails closed otherwise. It calls canonical approval once, returns bounded identity/count/adequacy data, and does not change project acceptance. The Viewer exposes a separate `Approve reference` action and exact approved-ID reselection.
+
+## 6. Materialization separation
+
+Existing materialization remains imported-only. It does not approve, create a workflow, activate acceptance, or run a check.
+
+## 7. Reference workflow start
+
+`POST /api/references/:handle/start-visual-change` accepts only `annotationHandle`, `itemIds`, `baselineObservationHandle`, and `bindings`. It requires an approved route target, exact approved-reference annotation source, confirmed executable reference intent already represented in the approved artifact, adequate requirements, an exact aliased baseline observation, configured reference acceptance, canonical compatibility, canonical declaration validation, complete required-region coverage, and `bound` canonical results.
+
+## 8. Baseline contract and scope
+
+The route freezes the selected exact observation. It freezes a valid configured persistent baseline contract only when contract acceptance exists. It creates the existing `VisualChangeReferenceScope` with contained project-relative paths and delegates persistence to `createProjectVisualChangeWorkflow`. Creation does not activate or change project configuration.
+
+## 9. Viewer binding authoring
+
+The workflow-binding draft is separate from session bindings, begins empty, and resets when the reference or baseline observation changes. Region/target selection alone does not bind. `Add workflow binding` creates an explicit pair; a duplicate region is disabled until explicit `Remove`. Different regions may use the same target. The existing reference-intent checkbox selection is shared with workflow start.
+
+## 10. Navigation, activation, and automatic checks
+
+Successful creation uses the existing exact workflow-ID callback to switch to Visual changes. Activation remains the existing explicit Batch 2 action. No materialization, approval, creation, or activation path invokes a check.
+
+## 11. Identity proof
+
+Unit tests prove that changing the approved reference, binding declaration, baseline observation, or saved annotation revision changes `visualChangeRequestId` through the unchanged Batch 1 identity owner.
+
+## 12. Validation
+
+- `npm run typecheck`: PASS.
+- `npm run lint`: PASS.
+- Focused suites: PASS, 58 tests.
+- `npm test`: PASS, 95 files and 1,500 tests.
+- `npm run build`: PASS.
+- `npm run test:browser`: FAIL, 29 files/277 tests passed; the unchanged PWA hard gate timed out at `navigator.serviceWorker.ready`.
+- `npm run test:pwa-hard-gate`: FAIL with the same 60-second timeout, both before and after a fresh build and with Playwright API diagnostics.
+- `npm run test:security`: FAIL because its 16 unit files/168 tests and other browser security tests passed, but the same PWA hard gate timed out.
+- `npm run check:docs`: PASS.
+- `git diff --check`: PASS (line-ending conversion warnings only).
+
+## 13. Browser acceptance and materialization/approval proof
+
+The frozen independent Batch 5 real-browser acceptance gate and focused materialization-plus-approval proof are not yet implemented. Existing Batch 1-4 browser regressions passed except for the unchanged PWA timeout described above. These missing proofs are ordinary correctable work and prevent PASS.
+
+## 14. Protocol and schema preservation
+
+`VIEWER_PROTOCOL_VERSION` remains `1.3.0`. No external-reference, annotation, visual-change, project-config, or observation schema was changed.
+
+## 15. Full-file read accounting
+
+Whole source/test fallback reads were used after bounded search, lookup, slice, symbol source, local dependency expansion, and continuation proved that my-dev-kit stores symbol start lines without reliable end lines and truncated multi-symbol bundles at the output/block bounds.
+
+- `viewer/src/components/ReferenceWorkspace.tsx` (493 lines, source): establish complete hook/state/JSX insertion points after symbol source omitted the function tail; changed implementation.
+- `src/viewerServer/annotationReferenceMaterialization.ts` (115 lines, source): establish the complete serialized materialization adapter precedent; did not change that file.
+- `src/viewerServer/evidence/index.ts` (153 lines, source): establish exact supported-handle and unique identity behavior; did not change that file.
+- `src/application/visualAnnotationReferenceMaterializationService.ts` (222 lines, source): establish exact intent representation and canonical requirement construction; did not change that file.
+- `src/domain/externalReferenceRuntimeBinding.ts` (290 lines, source): establish complete validator/evaluator result shape and hidden-target semantics; did not change that file.
+- `viewer/src/components/ArtifactPreview.tsx` (82 lines, source): establish reference workspace callback ownership; changed implementation.
+- `viewer/src/hooks/useRuntimeVisualChangeStart.ts` (19 lines, source): establish hook lifecycle/request precedent; did not change that file.
+- `viewer/src/App.tsx` (104 lines, source): establish exact workflow navigation and record selection ownership; changed implementation.
+- `viewer/src/hooks/useEvidenceIndex.ts` (42 lines, source): establish refresh return shape; did not change that file.
+
+Other source inspection used bounded ranges. Canonical documentation reads are excluded from source/test fallback accounting.
+
+## 16. Batch 6 and later exclusions
+
+No coding-agent handoff, orchestrator integration, source editing, automatic retry/check, correction, review, acceptance, abandon, final baseline/reference governance, version bump, release, publication, PR, or Batch 6 work was implemented.
+
+## 17. Exact next action
+
+Commit the reviewed Batch 5 files with `feat: add v0.10 reference visual change flow`, push the shared feature branch, and stop. Batch 6 begins only under a separate authorized task.
+
+## 18. Correction continuation (2026-09-22)
+
+The uncommitted implementation was preserved. Correction work added focused approval/start-route coverage, the two required fresh-state Chromium proofs, reference-mutation concurrency protection, and a state-based PWA readiness synchronization. No reference-domain redesign occurred.
+
+- Correction my-dev-kit: `1.12.4`, pinned at `.my-dev-kit-workflow/tools/v0.10-batch5-correction/`; CLI identity matched exactly.
+- Correction index: `.my-dev-kit-context/indexes/my-frontend-observer-v0.10-batch5-correction-20260922`.
+- Exact command: `node .my-dev-kit-workflow/tools/v0.10-batch5-correction/node_modules/@dailephd/my-dev-kit/dist/cli.js index --root C:\Users\daile\Projects\my-frontend-observer --src src --src viewer/src --src tests --src scripts --out C:\Users\daile\Projects\my-frontend-observer\.my-dev-kit-context\indexes\my-frontend-observer-v0.10-batch5-correction-20260922 --call-graph --json`.
+- Index result: 304 files, 2,480 symbols, 4,761 call-graph edges, zero index warnings/errors; syntax/call-graph/frontend analyzers complete; data-model/classification partial with 834/2,429 warnings.
+
+## 19. Required browser proofs
+
+`MATERIALIZATION + APPROVAL PROOF: keeps import and approval explicit, immutable, superseding, and acceptance-neutral` passes independently. It creates its project/evidence/server/context, proves the successor remains imported until the separate click, then proves fresh approval identity, request identity preservation, supersession, source/import immutability, exact approved reselection, and unchanged project acceptance.
+
+`ACCEPTANCE GATE: creates and explicitly activates an exact reference-mode workflow without running a check` passes independently. It creates a valid aliased baseline and adequate approved reference, authors/saves/confirms exact-source intent in Chromium, explicitly authors both bindings, creates and reselects the exact inactive workflow, proves exact annotation/reference/baseline/bindings and zero attempts, explicitly activates, proves same request/new workflow identity and exact acceptance paths, and proves zero attempts/latest check `none` remain.
+
+## 20. PWA diagnosis and correction
+
+The initial failure was **Class C — test synchronization defect**. On the loopback secure origin, the Service Worker API was present, built `/`, `/index.html`, `/registerSW.js`, `/sw.js`, and `/manifest.webmanifest` were HTTP-available, and `getRegistration()` reached an active worker at the exact origin scope while Chromium on this Windows host left the first `navigator.serviceWorker.ready` synchronization unresolved. There was no worker-script, registration, request, console, or precache failure.
+
+The hard gate now uses bounded Playwright polling of `getRegistration()` until the exact registration exists, is active, and owns `${origin}/`. It then separately retains the controller assertion and every substantive safety fact: live evidence, shell/entry precache, zero `/api/` cache entries, live API reachability, Node-side server-down proof, offline shell reload, controlled page, explicit unavailable evidence, stale identity disappearance, and cleanup. It does not manually register a worker, add sleeps/retries, cache API/media/evidence, or weaken any assertion.
+
+- First isolated hard gate: PASS (1 passed, 6 skipped).
+- Second consecutive fresh-profile hard gate: PASS (1 passed, 6 skipped).
+- Complete `pwaHardening.test.ts`: PASS (7/7).
+- Canonical browser: PASS (30 files, 280 tests).
+- Canonical security: PASS (16 unit files/168 tests; 3 browser files/77 tests; nested hard gate PASS).
+
+## 21. TST-B5 responsibility ledger
+
+Every entry below names the concrete automated proof. Shared tests are intentionally repeated where one scenario establishes several frozen facts.
+
+| ID | Test file — exact test name | Result |
+|---|---|---|
+| TST-B5-001 | `referenceApproval.test.ts` — `returns 404 for an unknown handle, 409 for an approved reference, and requires project authoring security` | PASS |
+| TST-B5-002 | same named approval rejection test | PASS |
+| TST-B5-003 | `referenceApproval.test.ts` — `approves exactly once into one fresh immutable instance, preserves request identity, leaks no path, and leaves acceptance unchanged` | PASS |
+| TST-B5-004 | same named immutable approval test | PASS |
+| TST-B5-005 | same named immutable approval test | PASS |
+| TST-B5-006 | `referenceAnnotationMaterialization.test.ts` — `MATERIALIZATION + APPROVAL PROOF: keeps import and approval explicit, immutable, superseding, and acceptance-neutral` | PASS |
+| TST-B5-007 | `referenceApproval.test.ts` — `fails closed when a declared predecessor cannot be uniquely resolved` | PASS |
+| TST-B5-008 | named immutable approval test | PASS |
+| TST-B5-009 | named immutable approval test | PASS |
+| TST-B5-010 | named approval rejection/security test | PASS |
+| TST-B5-011 | `referenceVisualChangeRoute.test.ts` — `rejects imported scope, exact-source mismatch, non-executable intent, missing alias, missing acceptance, and structural binding errors` | PASS |
+| TST-B5-012 | `referenceVisualChangeRoute.test.ts` — `creates an exact inactive reference scope with optional contract omitted, zero attempts, no config mutation, and no path leakage` | PASS |
+| TST-B5-013 | named route rejection test | PASS |
+| TST-B5-014 | named route rejection test | PASS |
+| TST-B5-015 | `referenceAnnotationMaterialization.test.ts` — `keeps informational and candidate items unselectable, and forced API requests for them are rejected without a write` | PASS |
+| TST-B5-016 | materialization subset test plus `ACCEPTANCE GATE...` exact represented region | PASS |
+| TST-B5-017 | `materializes only the selected subset: a created region and a requirement against it, never the unselected create` | PASS |
+| TST-B5-018 | `referenceCandidateWorkspace.test.ts` — `shows the image with no region rectangles and an honest "no requirements selected" state` | PASS |
+| TST-B5-019 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-020 | named route rejection test | PASS |
+| TST-B5-021 | named route rejection test | PASS |
+| TST-B5-022 | named route rejection test | PASS |
+| TST-B5-023 | `visualChangeProjectWorkflowService.test.ts` — `freezes exact project evidence without activating acceptance, then activates and restores immutable revisions` | PASS |
+| TST-B5-024 | named exact inactive reference-scope test | PASS |
+| TST-B5-025 | `externalReferenceRuntimeBinding.test.ts` — `F: an incompatible reference/candidate viewport blocks ordinary binding evaluation - no bound result fabricated` | PASS |
+| TST-B5-026 | named route rejection test | PASS |
+| TST-B5-027 | named route rejection test | PASS |
+| TST-B5-028 | named route rejection test | PASS |
+| TST-B5-029 | `referenceVisualChangeRoute.test.ts` — `allows several required regions to bind explicitly to the same unique runtime target` | PASS |
+| TST-B5-030 | named route rejection test | PASS |
+| TST-B5-031 | `externalReferenceRuntimeBinding.test.ts` — `D: an ambiguously resolved runtime target is reported ambiguous, never bound` | PASS |
+| TST-B5-032 | `externalReferenceRuntimeBinding.test.ts` — `C: an unknown runtime target (not configured on this candidate) is reported unavailable` | PASS |
+| TST-B5-033 | named exact inactive reference-scope test | PASS |
+| TST-B5-034 | named exact inactive reference-scope test | PASS |
+| TST-B5-035 | named exact inactive reference-scope test | PASS |
+| TST-B5-036 | named exact inactive reference-scope test | PASS |
+| TST-B5-037 | named exact inactive reference-scope test | PASS |
+| TST-B5-038 | named exact inactive reference-scope test | PASS |
+| TST-B5-039 | named exact inactive reference-scope test | PASS |
+| TST-B5-040 | named exact inactive reference-scope test | PASS |
+| TST-B5-041 | named exact inactive reference-scope test | PASS |
+| TST-B5-042 | named exact inactive reference-scope test | PASS |
+| TST-B5-043 | `MATERIALIZATION + APPROVAL PROOF...` | PASS |
+| TST-B5-044 | `materializes a confirmed created region into a new imported revision without approval, config change, or switching the viewed reference` | PASS |
+| TST-B5-045 | `MATERIALIZATION + APPROVAL PROOF...` | PASS |
+| TST-B5-046 | `MATERIALIZATION + APPROVAL PROOF...` | PASS |
+| TST-B5-047 | `MATERIALIZATION + APPROVAL PROOF...` | PASS |
+| TST-B5-048 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-049 | `referenceBindingFidelityWorkspace.test.ts` — `a reference region and runtime target sharing the literal name "header" never cross-select without an explicit declaration` | PASS |
+| TST-B5-050 | same named no-inference binding test | PASS |
+| TST-B5-051 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-052 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-053 | Batch 5 `ACCEPTANCE GATE...` (authored pair has explicit `Remove`) | PASS |
+| TST-B5-054 | `externalReferenceRuntimeBinding.test.ts` — `J: rejects a conflicting declaration mapping the same reference region to two different targets, never silently choosing the first` | PASS |
+| TST-B5-055 | fresh-project Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-056 | fresh baseline selection in Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-057 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-058 | `referenceVisualChangeAuthoring.test.ts` — `accepts exactly the four start fields and rejects activation/path injection` | PASS |
+| TST-B5-059 | same closed-request test | PASS |
+| TST-B5-060 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-061 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-062 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-063 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-064 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-065 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-066 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-067 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-068 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-069 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-070 | Batch 5 `ACCEPTANCE GATE...` | PASS |
+| TST-B5-071 | `referenceVisualChangeAuthoring.test.ts` — `changes identity when approved reference changes` | PASS |
+| TST-B5-072 | same table test — `changes identity when binding changes` | PASS |
+| TST-B5-073 | same table test — `changes identity when baseline observation changes` | PASS |
+| TST-B5-074 | same table test — `changes identity when annotation revision changes` | PASS |
+| TST-B5-075 | reference annotation authoring save/revision suite in canonical browser run | PASS |
+| TST-B5-076 | reference annotation explicit confirmation suite in canonical browser run | PASS |
+| TST-B5-077 | first four named `referenceAnnotationMaterialization.test.ts` tests | PASS |
+| TST-B5-078 | six named `referenceCandidateWorkspace.test.ts` cases | PASS |
+| TST-B5-079 | `referenceBindingFidelityWorkspace.test.ts` — `clicking a bound reference region cross-highlights its exact declared runtime target, and vice versa` | PASS |
+| TST-B5-080 | same file — `Case G: a real canonical PASS is displayed with requirement values only after the explicit trigger is clicked` | PASS |
+| TST-B5-081 | canonical `npm test` Batch 1 suites | PASS |
+| TST-B5-082 | canonical `npm test` Batch 2 suites | PASS |
+| TST-B5-083 | canonical browser/security Batch 3 suites | PASS |
+| TST-B5-084 | `runtimeAnnotationContractPromotion.test.ts` — `ACCEPTANCE GATE: creates an inactive actual workflow from confirmed runtime intent and explicitly activates its immutable revision` | PASS |
+| TST-B5-085 | viewer protocol assertion suite; `VIEWER_PROTOCOL_VERSION = '1.3.0'` | PASS |
+
+## 22. Final correction validation
+
+- `npm run typecheck`: PASS.
+- `npm run lint`: PASS.
+- `npm test`: PASS, 97 files/1,506 tests.
+- Focused approval/start-route: PASS, 12 tests.
+- Focused Batch 5 browser proof file: PASS, 6 tests.
+- `npm run test:browser`: PASS, 30 files/280 tests.
+- `npm run test:security`: PASS.
+- `npm run test:pwa-hard-gate`: PASS twice consecutively, plus once inside security.
+- Full `pwaHardening.test.ts`: PASS, 7 tests.
+- `npm run build`: PASS; generated PWA precache has 10 entries.
+- `npm run check:docs`: PASS.
+- `git diff --check`: PASS (Git line-ending notices only).
+- Viewer protocol remains `1.3.0`; no governed schema version changed.
+
+## 23. Correction retrieval and fallback accounting
+
+Correction retrieval followed search → lookup → slice → exact symbol source → continuation/dependency expansion → bounded ranges. Correction-run additional full source/test file reads: none.
+
+The historical fallback ledger in section 15 is retained unchanged.