@dailephd/my-frontend-observer 0.8.1 → 0.9.1

package/docs/reports/v0.9-final-readiness-corrections.md

@@ -0,0 +1,530 @@
+# v0.9 Final Readiness Corrections
+
+## 1. VERDICT
+
+The failed final-readiness workflow run `35527166495` was decomposed into three
+independent defects and corrected. A fourth and a fifth defect, both in the same
+readiness verifier and both in the same family as the second, were found while
+proving the correction locally and are also fixed.
+
+No core Observer product regression was established by that run. Final readiness
+exposed:
+
+- an Observer tutorial pacing fixture defect,
+- an Observer readiness verifier bug,
+- and a generic my-dev-kit-lab native-select portability gap.
+
+The product's own semantics, artifacts and commands were not changed.
+
+## 2. Repository identity
+
+- Repository: `C:\Users\daile\Projects\my-frontend-observer`
+- Branch: `validation/v0.9-final-readiness`
+- Entry HEAD: `116bf5f45513768d4dfc552545cc02e13265f02f`
+- Package: `@dailephd/my-frontend-observer`
+- Package version: `0.8.1` (unchanged)
+- v0.9: unreleased
+- `master`: not pushed
+- `docs/reports/v0.9-architecture-retrieval.md`: `S` skip-worktree preserved
+
+## 3. Failed workflow identity
+
+- Run: `35527166495`
+- URL: `https://github.com/dailephd/my-frontend-observer/actions/runs/35527166495`
+- This run is recorded as history. It is not reused as passing evidence for the
+  final candidate.
+
+## 4. Failure decomposition
+
+The earlier compressed summary attributed the whole failure to tutorial
+portability. That was incomplete. The run contained three independent failures.
+
+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`. Because the candidate job failed, the exact candidate tarball was
+   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 through click, `ArrowDown` and `Enter` sequences.
+
+## 5. my-dev-kit-lab v0.4.9 release identity
+
+- Package: `@dailephd/my-dev-kit-lab`
+- Version pinned exactly: `0.4.9`
+- Release commit: `3aca0e2f5969b0a8b414bcd361dec20ba70b8dc6`
+- `npx --yes @dailephd/my-dev-kit-lab@0.4.9 --version` reported `0.4.9`
+- Scenario, target-contract, run-result and manifest schema versions all remain
+  `1.0.0`. No Observer scenario schema was migrated.
+- Lab Playwright remains `1.60.0`, so the workflow's exact lab-browser install
+  commands were left unchanged. Observer's own `playwright` dependency remains
+  `^1.62.1` and was not changed to match the lab.
+- Observer did not add `@dailephd/my-dev-kit-lab` to `dependencies` or
+  `devDependencies`. It remains an external tool invoked through `npx`.
+
+## 6. select-option contract
+
+The released action used is:
+
+```json
+{
+  "type": "select-option",
+  "locator": { "kind": "role", "role": "combobox", "name": "Intent category" },
+  "value": "requested"
+}
+```
+
+It maps to Playwright's `Locator.selectOption({ value })` and verifies that
+exactly the requested value was selected. v0.4.9 supports `value` only. The
+closed validator rejects `label`, `index`, `values` and multi-select arrays, so
+none of those are used.
+
+## 7. Native-select scenario migration inventory
+
+Option values were read from the owning viewer source, not guessed from labels:
+
+- `viewer/src/annotation/runtimeIntent.ts` for the runtime intent vocabularies.
+- `viewer/src/annotation/referenceIntent.ts` for the reference requirement
+  vocabularies.
+- `viewer/src/components/RuntimeAnnotationPanel.tsx` for the relationship select,
+  whose option values are `pairwise:<index>`.
+- `viewer/src/components/ReferenceAnnotationPanel.tsx` for the requirement
+  selects, whose relationship option values are the relationship index.
+- `examples/v09-demo/references/v09-reference-regions.json` for region ids in
+  import order: `header, hero, sidebar, content, cta, asset, footer`.
+
+Each migration below replaced a contiguous group of workaround steps with one
+semantic selection step. `01-annotation-basics.json` contains no native select
+interaction and was not modified.
+
+### 02-runtime-intent-contract
+
+- Runtime intent operation: press "m", press Enter, press Enter, now `select-option` value `move` in step `operation-move`
+- Move direction: click, press ArrowDown, press Enter, now `select-option` value `right` in step `direction-right`
+- Intent category: click, press ArrowDown, press Enter, now `select-option` value `requested` in step `category-requested`
+- Runtime intent operation: press ArrowDown x3, now `select-option` value `resize` in step `operation-resize`
+- Resize direction: press ArrowDown, now `select-option` value `wider` in step `resize-wider`
+- Intent category: press ArrowDown x2, now `select-option` value `expected-dependent` in step `category-expected`
+- Intent expected-dependent mode: press ArrowDown, now `select-option` value `required` in step `mode-required`
+- Runtime intent operation: press ArrowDown x5, now `select-option` value `preserve` in step `operation-preserve`
+- Intent category: press ArrowDown x3, now `select-option` value `protected` in step `category-protected`
+- Preserved property: press ArrowDown x2, now `select-option` value `y` in step `preserve-property`
+- Contract tolerance: press ArrowDown x2, now `select-option` value `absolute-px` in step `tolerance`
+- Canonical relationship to associate: press ArrowDown, now `select-option` value `pairwise:0` in step `relationship-choose`
+- Runtime intent operation: press ArrowDown x5, now `select-option` value `preserve` in step `rel-operation`
+- Intent category: press ArrowDown x4, now `select-option` value `preserved` in step `rel-category`
+- Runtime intent operation: press ArrowDown x4, now `select-option` value `remove` in step `remove-op`
+- Intent category: press ArrowDown, now `select-option` value `requested` in step `remove-category`
+- Runtime intent operation: press ArrowDown, now `select-option` value `inspect` in step `inspect-op`
+
+### 03-reference-authoring
+
+- Requirement category: press ArrowDown x3, now `select-option` value `protected` in step `property-category`
+- Requirement subject: press ArrowDown, now `select-option` value `region-property` in step `property-subject`
+- Requirement region: press ArrowDown x2, now `select-option` value `hero` in step `property-region`
+- Region property: press ArrowDown x3, now `select-option` value `width` in step `property-prop`
+- Tolerance: press ArrowDown x2, now `select-option` value `absolute-reference-px` in step `property-tolerance`
+- Requirement subject: press ArrowDown, now `select-option` value `region-relationship` in step `relationship-subject`
+- Requirement relationship: press ArrowDown, now `select-option` value `0` in step `relationship-pick`
+- Requirement category: press ArrowDown, now `select-option` value `preserved` in step `measurement-category`
+- Requirement subject: press ArrowDown, now `select-option` value `region-measurement` in step `measurement-subject`
+- Subject region: press ArrowDown x2, now `select-option` value `hero` in step `measurement-subject-region`
+- Related region: press ArrowDown x5, now `select-option` value `cta` in step `measurement-related`
+- Measurement: press ArrowDown, now `select-option` value `vertical-gap` in step `measurement-kind`
+
+### 04-reference-materialization
+
+- Requirement category: press ArrowDown x3, now `select-option` value `protected` in step `req-a-cat`
+- Requirement subject: press ArrowDown, now `select-option` value `region-property` in step `req-a-subject`
+- Requirement region: press ArrowDown x2, now `select-option` value `hero` in step `req-a-region`
+- Region property: press ArrowDown x3, now `select-option` value `width` in step `req-a-prop`
+- Tolerance: press ArrowDown x2, now `select-option` value `absolute-reference-px` in step `req-a-tol`
+- Requirement category: press ArrowDown, now `select-option` value `preserved` in step `req-b-cat`
+- Requirement region: press ArrowDown x5, now `select-option` value `footer` in step `req-b-region`
+- Region property: press ArrowDown, now `select-option` value `height` in step `req-b-prop`
+
+Counts:
+
+- `SELECT_OPTION_MIGRATION_COUNT`: 37
+- Collapsed workaround steps: 85 (83 `press`, 2 `click`)
+- `NATIVE_SELECT_KEYBOARD_WORKAROUNDS_BEFORE`: 83
+- `NATIVE_SELECT_KEYBOARD_WORKAROUNDS_REMAINING`: 0
+- Scenario step totals: 258 before, 210 after
+
+## 8. Keyboard-workaround removal
+
+Narration that described obsolete automation mechanics was removed, for example
+"The first press lands on inspect", "stepped from the top of the list", and the
+single-word stepping lines such as "Move.", "Resize.", "Remove.". Conceptual
+explanation was preserved, including why a category or tolerance is chosen and
+why `unexpected` cannot be authored.
+
+`press` remains a legal tutorial action and is still permitted. Only `press`
+acting as a surrogate for `<select>` choice was removed. After migration the
+four scenarios contain no `press` action at all, because every remaining one had
+been a combobox surrogate.
+
+Two scenario steps that opened a select with `click` before stepping it were
+part of the same workaround and were collapsed into the semantic selection.
+
+No OS-conditional scenario steps were introduced. One canonical scenario set
+remains.
+
+Presentation state was preserved rather than dropped while collapsing:
+
+- the `direction-right` callout was retained,
+- the `move-form-ready` screenshot, which was attached to the last step of a
+  collapsed group, was carried onto the single replacement step.
+
+## 9. Pacing correction
+
+The frozen rule is unchanged:
+
+```
+readingMs = max(1200, ceil((narration.length / 15) * 10) * 100)
+```
+
+The rule was not weakened, no test was deleted, and no CI special case was
+added. After all narration edits, every step in all four scenarios was
+re-paced with `pauseAfterMs = max(existing, readingMs)`, which raises any step
+that no longer covers its narration while preserving one deliberately longer
+dwell in `01-annotation-basics.json`.
+
+- `CATEGORY_REQUESTED_PACING_FIXED`: true (`10900` to `11900`)
+- `ALL_STEPS_MEET_READING_TIME_RULE`: true, 210 of 210 steps
+- Only the pacing of edited steps changed; `01-annotation-basics.json` is
+  byte-identical to its committed version.
+
+## 10. Readiness contract-reader root cause
+
+`scripts/run-v09-tutorial-readiness.mjs` used one helper for every canonical
+reader:
+
+```js
+async function readArtifact(reader, file) {
+  const result = await reader(file);
+  if (!result?.ok) fail(...);
+  return result.artifact;
+}
+```
+
+That is correct for `readVisualAnnotationArtifact` and
+`readExternalReferenceArtifact`, whose success result is `{ ok: true, artifact }`.
+
+It is wrong for the canonical frontend-contract readers. Their success results
+are:
+
+- `readPersistentBaselineContract` returns `{ ok: true, contract }`
+- `readPerChangeContract` returns `{ ok: true, contract }`
+
+Neither returns `artifact`. The script therefore pushed `undefined` for every
+valid contract, and the later `item.contractClass` evaluation threw
+`Cannot read properties of undefined (reading 'contractClass')`. This is why the
+Windows and Ubuntu jobs failed after otherwise running the tutorials.
+
+Reproduced against the three real contract manifests written by a local
+scenario 2 run:
+
+All three returned `undefined` from the old helper, and evaluating
+`contractClass` on that value threw
+`Cannot read properties of undefined (reading 'contractClass')`. The fixed
+reader returned a defined contract for each:
+
+1. the per-change contract promoted by the tutorial: `change`
+2. `tutorial-baseline/v09-tutorial-baseline`: `baseline`
+3. `tutorial-initial-change/v09-tutorial-initial-change`: `change`
+
+- `CONTRACTCLASS_CRASH_REPRODUCIBLE_BEFORE_FIX`: true
+- `CONTRACTCLASS_CRASH_CLOSED`: true
+
+## 11. Contract-reader correction
+
+A dedicated canonical contract reader was added. No optional-chaining
+workaround was used, no raw JSON was parsed to choose a reader, and no third
+contract validator was introduced:
+
+```js
+async function readContract(file) {
+  const baseline = await readPersistentBaselineContract(file);
+  if (baseline.ok) return baseline.contract;
+  const change = await readPerChangeContract(file);
+  if (change.ok) return change.contract;
+  fail(`canonical contract readers rejected ${file}: baseline=${baseline.reason}; change=${change.reason}`);
+}
+```
+
+Trying each canonical validator is what decides the contract class, so the raw
+`contractClass` dispatch was removed. `jsonFile()` became unused and was
+deleted, along with the now-unused `readFile` import. A later-unused `sha256()`
+helper was also removed. `BASELINE_READER_RESULT_PROPERTY` and
+`CHANGE_READER_RESULT_PROPERTY` are both `contract`.
+
+## 12. Two further readiness verifier defects found while proving the fix
+
+Once the `contractClass` crash was closed, the local run reached scenario 3 and
+scenario 4 evidence checks for the first time. Both were broken in the same
+family as the contract-reader defect: the script read canonical artifacts
+through a shape that does not exist.
+
+### 12.1 Reference lifecycle compared as a string
+
+The script used `item.lifecycle === 'approved'` and
+`item.lifecycle === 'imported'`. The canonical contract in
+`src/domain/externalReference.ts` is:
+
+```ts
+export interface ImportedExternalReferenceArtifact extends ExternalReferenceArtifactBase {
+  lifecycle: { state: 'imported' };
+  image: ExternalReferenceImageReference;
+}
+export interface ApprovedExternalReferenceArtifact extends ExternalReferenceArtifactBase {
+  lifecycle: { state: 'approved'; approvedAt: string };
+  sourceReference: ExternalReferenceSourceReference;
+}
+```
+
+`lifecycle` is an object, so both comparisons were always false and scenario 3
+could never pass. Verified against real evidence: both references reported
+`oldStringCompareWorks: false`.
+
+This was never reached in run `35527166495` because Windows and Ubuntu crashed
+in scenario 2 and macOS failed in scenario 2.
+
+Corrected to use the canonical exported type guards
+`isApprovedExternalReferenceArtifact` and `isImportedExternalReferenceArtifact`
+rather than a locally re-derived check.
+
+### 12.2 The materialized image digest comparison never executed
+
+The scenario 4 check was:
+
+```js
+const imagePath = (reference) => reference.image?.path ? path.join(...) : undefined;
+const sourceImage = imagePath(approved);
+const revisionImage = imagePath(imported[0]);
+if (sourceImage && revisionImage && sha256(...) !== sha256(...)) fail(...);
+```
+
+An approved artifact has no top-level `image`; it carries
+`sourceReference.image`. `sourceImage` was therefore always `undefined`, and the
+`sourceImage && revisionImage` guard made the comparison a silent no-op. The
+check reported success while proving nothing, which is exactly the
+absent-evidence-as-PASS failure the evidence-honesty rules forbid. Verified
+against real evidence: the approved artifact reported `hasTopLevelImage: false`.
+
+Corrected to compare the canonical identity-bearing digests directly, with no
+file re-hashing and no filesystem path construction:
+
+- source: `approved.sourceReference.image.sha256`
+- materialized: the successor's `image.sha256`
+
+A missing digest on either side now fails explicitly instead of being skipped.
+
+### 12.3 Imported-reference count assumption
+
+The scenario 4 check also required exactly one imported reference. Real
+evidence shows a materialization target holds three references: the original
+source import, the approval, and the materialized successor. So
+`imported.length !== 1` would have failed even after the lifecycle fix.
+
+The successor is now identified by the property that actually distinguishes it,
+namely that it carries requirements, while the reference the approval came from
+carries none. Observed: `importedCount: 2`, `materializedCount: 1`,
+`digestsMatch: true`.
+
+### 12.4 Diagnosability
+
+The scenario 3 and scenario 4 checks previously collapsed several distinct
+conditions into one generic message such as
+`reference authoring invariants failed`. Each condition now fails with its own
+message naming the actual cause and the observed counts.
+
+## 13. Local four-tutorial proof
+
+`npm run build` was run first, because `scripts/run-v09-tutorial-readiness.mjs`
+imports `../dist/index.js`.
+
+Before running the tutorials, all four scenarios were validated against the
+released lab:
+
+```
+npx --yes @dailephd/my-dev-kit-lab@0.4.9 tutorial validate --scenario <file> --target-contract <generated> --json
+```
+
+- `01-annotation-basics`: `status: valid`, `errors: []`
+- `02-runtime-intent-contract`: `status: valid`, `errors: []`
+- `03-reference-authoring`: `status: valid`, `errors: []`
+- `04-reference-materialization`: `status: valid`, `errors: []`
+
+This also proves the installed v0.4.9 validator accepts the exact released
+`select-option` shape, because every migrated step uses it.
+
+Static workaround audit across all four scenario files:
+
+- `COMBOBOX_PRESS_ACTION_COUNT`: 0
+- `select-option` actions: 37
+- Steps satisfying the reading-time rule: 210 of 210
+
+Full run, into a clean scratch output outside tracked repository files:
+
+```
+node scripts/run-v09-tutorial-readiness.mjs .my-dev-kit-workflow/adhoc/v09-final-readiness/tutorials-run
+```
+
+Result: exit 0, with every required condition met.
+
+- `observer-v09-annotation-basics`: `passed`, `cleanupErrors: []`
+- `observer-v09-runtime-contract`: `passed`, `cleanupErrors: []`
+- `observer-v09-reference-authoring`: `passed`, `cleanupErrors: []`
+- `observer-v09-reference-materialization`: `passed`, `cleanupErrors: []`
+- `demoSourceImmutable`: true
+- `repositoryUnchanged`: true
+- Tracked demo digest identical before and after: 19 files,
+  `3a65f1c822faaddd958d4f4f20ddedcbf415bd4d34de67bf75a34ddc35c32bef`
+
+One earlier local attempt failed on the final
+`repository status changed during tutorial readiness` guard. That was caused by
+this report being written while the run was in progress, not by the product or
+the scenarios. The guard behaved correctly. The run above was performed with a
+quiescent worktree.
+
+## 14. Canonical Observer evidence proof
+
+Every scenario's evidence was read back through the canonical readers.
+
+Scenario 2, the contract verifier gate, reached and passed canonical contract
+verification with no `contractClass` crash:
+
+- 3 contract manifests read through the canonical readers
+- promoted per-change contract found with exactly 2 clauses
+- no `inspect` clause present
+- no `remove` clause present
+- baseline contract `v09-tutorial-baseline` preserved
+
+Scenario 4, the reference verifier gate:
+
+- approved source reference exists, carrying 0 requirements
+- 2 imported references exist: the original source import and the successor
+- exactly 1 materialized successor, carrying 1 requirement
+- image digest unchanged and now actually compared:
+  `4bdb94db1096532dd886b7b8bd9ea4018f44ff0e3debb24e92cbf6132123538d`
+  on both the approved source reference and the materialized successor
+
+Scenario 1: 2 annotations with a valid supersession chain and all five mark
+kinds. Scenario 3: one external-reference annotation with exactly 7 items and an
+approved reference carrying 0 requirements.
+
+## 15. Full local regression
+
+- `npm run typecheck`: PASS
+- `npm run lint`: 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
+- `npm run build`: PASS
+- `npm run check:docs`: PASS, 17 required files
+- `npm pack --dry-run`: PASS, 366 files
+
+`tests/unit/v09TutorialScenarios.test.ts` passes, including pacing. The
+candidate-job failure is closed.
+
+## 16. Packed smoke results
+
+One local candidate tarball was built into the approved workflow root and used
+for all three smokes. Process-local `TEMP`/`TMP` were redirected into that root
+so no consumer install or browser profile was created elsewhere. No user or
+machine environment variable was changed.
+
+- Tarball: `dailephd-my-frontend-observer-0.8.1.tgz`
+- SHA-256: `8f8bcd5aab0607df35c9a56fcfa9ece9f286c115910c6e4b50b2384adf4469ad`
+- File count: 366
+
+Results:
+
+- Packed observation smoke: PASS, `"pass": true`, real Chromium
+  `153.0.8010.12`, `targetsFilePathLeaked: false`
+- Packed viewer smoke: PASS
+- Packed v0.9 annotation smoke: PASS
+
+This local tarball is local proof only. It is not the final candidate. The
+authoritative exact candidate is the one the workflow builds.
+
+## 17. Changed files
+
+- `examples/v09-demo/tutorials/02-runtime-intent-contract.json`
+- `examples/v09-demo/tutorials/03-reference-authoring.json`
+- `examples/v09-demo/tutorials/04-reference-materialization.json`
+- `examples/v09-demo/README.md`
+- `examples/v09-demo/scripts/generate-tutorial-target.mjs`
+- `scripts/run-v09-tutorial-readiness.mjs`
+- `tests/unit/v09TutorialScenarios.test.ts`
+- `tests/unit/v09TutorialTargetContract.test.ts`
+- `docs/WORKFLOWS.md`
+- `docs/CURRENT_STATE.md`
+- `docs/PROJECT_OVERVIEW.md`
+- `README.md`
+- `docs/reports/v0.9-final-readiness-corrections.md` (this report)
+
+`examples/v09-demo/tutorials/01-annotation-basics.json` was deliberately not
+modified.
+
+`.github/workflows/pre-release-readiness.yml` was inspected and needed no
+change. It never pinned the lab version; it delegates to
+`scripts/run-v09-tutorial-readiness.mjs`, where the pin was updated. Its exact
+lab Chromium installation already uses `playwright@1.60.0`, which v0.4.9 still
+declares.
+
+## 18. Test changes
+
+- `select-option` was added to the released lab action allowlist. All previously
+  released actions were kept.
+- A native-select portability regression test was added. It fails if any
+  scenario uses `action.type = "press"` against a locator with `kind = "role"`
+  and `role = "combobox"`, which freezes the rule that a native `<select>`
+  semantic choice must use `select-option`. It does not ban `press` generally.
+- The same test asserts the v0.4.9 value-only contract, so a scenario cannot
+  acquire `label`, `index` or `values`.
+- The guard was checked against a synthetic pre-migration step to confirm it is
+  not vacuous: it fires on a combobox `press`, and does not fire on a
+  `select-option` or on a legitimate non-combobox `press`.
+
+## 19. Scope audit
+
+- `MY_DEV_KIT_LAB_VERSION`: `0.4.9`, pinned exactly
+- `NATIVE_SELECT_KEYBOARD_WORKAROUNDS_REMAINING`: 0
+- `select-option` used semantically, one canonical scenario set
+- Pacing test passes and was not weakened
+- Contract verifier uses the canonical contract readers correctly
+- No `.artifact` extraction from contract-reader success results
+- No product `<select>` redesign, no custom dropdown, no tutorial-only control
+- No new Observer dependency; `@dailephd/my-dev-kit-lab` is not a dependency
+- Demo still excluded from the npm package: 0 of 365 packaged files match
+  `v09-demo`
+- Package version remains `0.8.1`; v0.9 remains unreleased; `master` not pushed
+- No Observer product semantics, artifact schema or command surface changed
+
+## 20. Remote readiness continuation
+
+Run `35527166495` cannot contribute passing evidence to the final candidate.
+The scenario files changed, the lab version changed, the readiness verifier
+changed and the candidate bytes changed, so rerunning only the failed jobs
+against the stale commit would prove nothing.
+
+A new complete workflow execution is required on the correction commit,
+covering:
+
+1. the candidate/static job, which must now get past `npm test` and build the
+   exact candidate tarball
+2. Windows, Linux and macOS exact-package smokes, which run 35527166495 never
+   reached
+3. Windows, Linux and macOS Observer tutorial readiness
+
+`RUN_A` is the first complete pass of the full workflow on one exact
+post-correction commit. Only after `RUN_A` exists may
+`docs/reports/v0.9-final-pre-release-readiness.md` be written. Because
+`docs/reports/` is inside the npm package, committing that report changes the
+candidate bytes, so a second full workflow run `RUN_B` is required on the exact
+report-containing commit.