@dailephd/my-frontend-observer 0.8.1 → 0.9.0

package/docs/reports/v0.9-final-pre-release-readiness.md

@@ -0,0 +1,209 @@
+# v0.9 Final Pre-release Readiness
+
+## 1. VERDICT
+
+`RUN_A` passed the complete final-readiness workflow on one exact
+post-correction commit: the candidate/static job, the exact-candidate package
+smoke on Windows, Linux and macOS, and Observer tutorial readiness on Windows,
+Linux and macOS.
+
+This is final pre-release readiness evidence for v0.9. It is not a release.
+The package version is unchanged at `0.8.1`, v0.9 is unreleased, and `master`
+has not been pushed.
+
+A second complete workflow run is required after this report is committed,
+because `docs/reports/` is inside the npm package and committing this file
+changes the candidate bytes.
+
+## 2. Repository identity
+
+- Repository: `C:\Users\daile\Projects\my-frontend-observer`
+- Branch: `validation/v0.9-final-readiness`
+- Entry HEAD: `116bf5f45513768d4dfc552545cc02e13265f02f`
+- Correction commit: `878598a1c3054f1b4d01363d1d6bdb27bb76fb29`
+- Package: `@dailephd/my-frontend-observer`
+- Package version: `0.8.1`
+- `docs/reports/v0.9-architecture-retrieval.md`: `S` skip-worktree preserved
+
+## 3. The failed run this replaces
+
+- Run: `35527166495`
+- URL: `https://github.com/dailephd/my-frontend-observer/actions/runs/35527166495`
+- Conclusion: failure
+
+That run is retained as history and contributes no passing evidence to the
+final candidate. Rerunning only its failed jobs would have proved nothing,
+because the scenario files, the lab version, the readiness verifier and the
+candidate bytes all changed.
+
+## 4. The three independent root causes
+
+The earlier compressed summary attributed the whole failure to tutorial
+portability. That was incomplete.
+
+1. Candidate/package job: failed in `npm test` because one scenario pause was
+   too short. `02-runtime-intent-contract.json/category-requested` declared
+   `pauseAfterMs` of `10900` where the frozen readability rule required
+   `11900`. The exact candidate tarball was therefore never built, so the
+   package matrix was `NOT_REACHED`.
+2. Windows tutorial job: the readiness verifier crashed with
+   `Cannot read properties of undefined (reading 'contractClass')` because
+   contract-reader success results were extracted through the wrong property.
+3. Ubuntu tutorial job: the same readiness verifier crash.
+4. macOS tutorial job: scenario 2 failed while using native-select keyboard
+   emulation.
+
+This was an Observer tutorial pacing fixture defect, an Observer readiness
+verifier bug, and a generic my-dev-kit-lab native-select portability gap. No
+core Observer product regression was established by that run.
+
+Two further readiness verifier defects, both in the same family as the second
+root cause, were found while proving the correction locally. They were
+unreachable before, because every earlier run died in scenario 2. Both are
+recorded in `docs/reports/v0.9-final-readiness-corrections.md`.
+
+## 5. The v0.4.9 migration
+
+- Lab pinned exactly to `@dailephd/my-dev-kit-lab@0.4.9`
+- Release commit: `3aca0e2f5969b0a8b414bcd361dec20ba70b8dc6`
+- Scenario, target-contract, run-result and manifest schema versions all remain
+  `1.0.0`
+- 85 native-select keyboard workaround steps were collapsed into 37 semantic
+  `select-option` actions
+- Remaining combobox `press` actions: 0
+- Option values were read from the owning viewer source, never inferred from
+  visible labels
+- One canonical scenario set; no OS-conditional steps
+- Lab Playwright remains `1.60.0`; Observer's own `playwright` dependency
+  remains `^1.62.1` and was not changed to match
+
+## 6. The readiness verifier correction
+
+The canonical frontend-contract readers return `contract`, not `artifact`. The
+verifier now reads contracts through a dedicated canonical helper that tries
+`readPersistentBaselineContract` and then `readPerChangeContract`, and fails
+with both validation reasons. No raw JSON is parsed to choose a reader and no
+third contract validator exists.
+
+The reference checks now use the canonical exported type guards
+`isApprovedExternalReferenceArtifact` and `isImportedExternalReferenceArtifact`
+instead of comparing `lifecycle` as a string, and the materialized image digest
+is compared through the artifacts' own identity-bearing `sha256` fields, which
+means that comparison actually executes rather than being silently skipped.
+
+## 7. The pacing correction
+
+The frozen rule is unchanged and was not weakened:
+
+```
+readingMs = max(1200, ceil((narration.length / 15) * 10) * 100)
+```
+
+Every step in all four scenarios was re-paced after the narration edits. All
+210 steps satisfy the rule. The candidate job proved this remotely by getting
+past `npm test`.
+
+## 8. RUN_A identity
+
+- Run id: `35584183782`
+- URL: `https://github.com/dailephd/my-frontend-observer/actions/runs/35584183782`
+- Head SHA: `878598a1c3054f1b4d01363d1d6bdb27bb76fb29`
+- Conclusion: success
+- Workflow: Pre-release readiness
+
+All seven required jobs passed:
+
+1. Package exact candidate (Linux, Node 24): success
+2. windows-latest exact-candidate smoke: success
+3. ubuntu-latest exact-candidate smoke: success
+4. macos-latest exact-candidate smoke: success
+5. windows-latest Observer tutorial readiness: success
+6. ubuntu-latest Observer tutorial readiness: success
+7. macos-latest Observer tutorial readiness: success
+
+## 9. RUN_A exact candidate package
+
+One tarball was built by the candidate job and used unchanged by all three
+package smokes. It was not repacked per platform.
+
+- Filename: `dailephd-my-frontend-observer-0.8.1.tgz`
+- SHA-256: `2a14c4ccae1b846a6a7454900c9f3e2b200952d4456f824b2db01c1d3d9b0c35`
+- File count: 366
+- Package version: `0.8.1`
+- Candidate commit: `878598a1c3054f1b4d01363d1d6bdb27bb76fb29`
+
+The published artifact was downloaded and independently verified. The
+recomputed SHA-256 matched the value the workflow recorded, and the archive
+contains 0 entries under `examples/v09-demo`, so the demo remains excluded from
+the npm package.
+
+## 10. RUN_A package results
+
+The exact candidate reached and passed the package matrix, which run
+`35527166495` never reached.
+
+- Windows exact-package smoke: PASS
+- Linux exact-package smoke: PASS
+- macOS exact-package smoke: PASS
+
+Each platform ran the packed observation smoke, the packed viewer smoke and the
+packed v0.9 annotation smoke against the installed tarball, not the source
+checkout.
+
+## 11. RUN_A tutorial results
+
+- Windows Observer tutorial readiness: PASS
+- Linux Observer tutorial readiness: PASS
+- macOS Observer tutorial readiness: PASS
+
+Each platform reported identical evidence:
+
+- lab version `0.4.9`
+- `observer-v09-annotation-basics`: `passed`, `cleanupErrors: []`, 2 annotations
+- `observer-v09-runtime-contract`: `passed`, `cleanupErrors: []`, 3 contracts
+- `observer-v09-reference-authoring`: `passed`, `cleanupErrors: []`, 2 references
+- `observer-v09-reference-materialization`: `passed`, `cleanupErrors: []`,
+  3 references
+- all required tutorial artifacts written and non-empty
+- canonical Observer evidence checks passed on every scenario
+- `demoSourceImmutable`: true
+- `repositoryUnchanged`: true
+
+macOS is the significant result. It previously failed in scenario 2 on native
+select keyboard emulation and now produces byte-identical evidence counts to
+Windows and Linux, which is the direct proof that the portability defect is
+closed.
+
+## 12. Native select portability gate
+
+All three platforms ran scenarios that use `select-option` for every native
+`<select>` semantic choice. No OS-specific keyboard navigation was
+reintroduced. `tests/unit/v09TutorialScenarios.test.ts` fails if a scenario
+drives a `combobox` locator with `press`, so the gate is enforced statically in
+the candidate job as well as behaviourally on each platform.
+
+## 13. Local evidence supporting RUN_A
+
+Recorded in full in `docs/reports/v0.9-final-readiness-corrections.md`:
+
+- `npm run typecheck`, `npm run lint`, `npm run build`, `npm run check:docs`:
+  PASS
+- `npm test`: PASS, 1453 tests in 89 files
+- `npm run test:browser`: PASS, 275 tests in 29 files
+- `npm run test:security`: PASS, 167 tests in 16 files plus 77 tests in 3 files
+- Local four-tutorial readiness: all four `passed`, `cleanupErrors: []`,
+  `demoSourceImmutable: true`, `repositoryUnchanged: true`
+- Local packed observation, viewer and v0.9 annotation smokes: PASS
+
+## 14. Release state
+
+- Package version: `0.8.1`, unchanged
+- v0.9: unreleased
+- No version bump, tag, GitHub Release or npm publication was performed
+- `master`: not pushed
+- Validation branch `validation/v0.9-final-readiness`: preserved
+- No Observer product semantics, artifact schema, command surface or dependency
+  was changed
+
+Passing final pre-release readiness does not authorize publication. The next
+stage is v0.9.0 controlled release preparation.