@dailephd/my-frontend-observer 0.9.0 → 0.9.1

package/docs/plans/v0.9.1-implementation-plan.md

@@ -0,0 +1,468 @@
+# v0.9.1 Implementation Plan — PWA Hard-Gate Isolation
+
+Status: frozen planning authority; implementation not started.
+
+Base release: v0.9.0.
+
+Target maintenance version: v0.9.1.
+
+Primary defect owner: `tests/browser/pwaHardening.test.ts`.
+
+This plan is concrete implementation authority for the bounded v0.9.1
+maintenance patch. ROADMAP owns the version-level goal and constraints; this
+file owns the exact correction strategy, sequencing, tests, and gates.
+
+## 1. Problem statement
+
+The released PWA browser coverage contains a test named:
+
+`HARD GATE: after the server goes down, a reload never presents previously-fetched evidence as current`.
+
+That test passes in the normal file/suite order but fails when selected alone
+with Vitest `-t`.
+
+The current first PWA `describe` block creates one evidence root, one viewer
+server, and one persistent Chromium context in `beforeAll`. It launches that
+context from a fixed profile under:
+
+`.my-dev-kit-workflow/v0.8/batch-08/pwa-profile`.
+
+Earlier tests in the same block register/activate the service worker, navigate
+the app, and exercise cache behavior before the hard gate runs. The hard gate
+therefore benefits from state that it did not establish itself. The fixed
+profile can also retain service-worker/cache state across local runs.
+
+The hard gate currently waits for an active service-worker registration before
+shutting down the server. An active registration is not equivalent to proving
+that the current page is controlled by that worker or that the shell needed for
+offline reload has definitely been precached.
+
+This is a test-isolation defect. There is currently no evidence that v0.9.0
+serves stale evidence as current or that production PWA semantics are wrong.
+
+## 2. Frozen maintenance invariant
+
+A test explicitly designated `HARD GATE`, `SECURITY GATE`, or
+`ACCEPTANCE GATE` must:
+
+- establish every prerequisite material to the claim it makes;
+- pass when selected independently in a fresh process/environment;
+- not require another test to run first;
+- not depend on a fixed browser profile or historical cache/filesystem state;
+- own and clean up disposable servers, evidence roots, browser profiles,
+  contexts, and similar mutable state where those resources are part of the
+  experiment.
+
+The PWA hard gate is the first explicit application of this invariant.
+
+## 3. Scope
+
+v0.9.1 owns:
+
+- isolation of the PWA hard-gate experiment;
+- removal of hidden dependency on the historical fixed Chromium profile for
+  that gate;
+- explicit service-worker control proof;
+- explicit app-shell cache prerequisite proof;
+- explicit `/api/` cache exclusion proof within the hard gate;
+- explicit server/network-unavailable proof before the offline reload;
+- explicit stale-evidence-absence proof after the offline reload;
+- deterministic cleanup;
+- a dedicated command/gate that runs the hard gate by itself;
+- complete browser/security regression after the correction;
+- documentation reconciliation and normal patch readiness if the user elects
+  to publish v0.9.1.
+
+## 4. Explicit exclusions
+
+The patch must not, merely to make the test pass:
+
+- change production service-worker caching policy;
+- add runtime caching for `/api/` or evidence/media;
+- weaken the stale-evidence hard gate;
+- change Viewer protocol or evidence schemas;
+- add a product feature or CLI command;
+- add v0.10 workflow behavior;
+- add arbitrary sleeps/retries as a substitute for state proof;
+- enforce test ordering;
+- retain a fixed persistent profile as an implicit fixture.
+
+If the corrected self-contained experiment fails after all prerequisites are
+proven, stop and classify a product defect before modifying production code.
+
+## 5. Target test architecture
+
+The hard gate becomes one complete experiment with this lifecycle:
+
+```text
+fresh temporary evidence root
+→ populate deterministic reference/annotation fixture
+→ fresh viewer server
+→ fresh temporary persistent Chromium profile
+→ fresh BrowserContext
+→ fresh page
+→ navigate while server is live
+→ wait for service-worker registration/activation
+→ prove current page is service-worker controlled
+→ prove required application shell is present in Cache Storage
+→ prove /api/ entries are absent from Cache Storage
+→ prove live evidence is visible
+→ close viewer server
+→ prove server/API network is unavailable
+→ reload
+→ prove shell still renders
+→ prove evidence surface reports unavailable
+→ prove previously visible evidence identity is absent
+→ close context
+→ close server if still open
+→ remove evidence root
+→ remove browser profile
+```
+
+No prior `it()` may be part of this lifecycle.
+
+## 6. Resource ownership
+
+### 6.1 Evidence root
+
+Create a test-owned root with `mkdtemp()` under the OS temporary directory.
+
+Populate it through the existing canonical deterministic fixture helpers used by
+the current PWA test. The hard gate should still include the real annotation
+needed for annotation/media route coverage when that remains relevant to the
+cache boundary.
+
+Remove the root in `finally`/test cleanup even after a failed assertion where
+practical.
+
+### 6.2 Viewer server
+
+Start a dedicated viewer server for the hard gate. Do not reuse a server from a
+describe-level `beforeAll`.
+
+The server may be closed deliberately in the middle of the experiment; cleanup
+must tolerate an already-closed server.
+
+### 6.3 Chromium profile/context
+
+Create a fresh temporary persistent profile, for example:
+
+```ts
+const profileRoot = await mkdtemp(
+  path.join(tmpdir(), 'my-frontend-observer-pwa-hard-gate-'),
+);
+```
+
+Launch:
+
+```ts
+const context = await chromium.launchPersistentContext(profileRoot, {
+  headless: true,
+});
+```
+
+The hard gate must not use
+`.my-dev-kit-workflow/v0.8/batch-08/pwa-profile`.
+
+Remove the temporary profile after closing the context.
+
+## 7. Service-worker readiness proof
+
+Before shutting down the server, prove two distinct conditions.
+
+First, the registration is ready and has an active worker:
+
+```ts
+const registrationState = await page.evaluate(async () => {
+  const registration = await navigator.serviceWorker.ready;
+  return {
+    active: registration.active !== null,
+    scope: registration.scope,
+  };
+});
+```
+
+Second, the current page is actually controlled:
+
+```ts
+await page.waitForFunction(
+  () => navigator.serviceWorker.controller !== null,
+  undefined,
+  { timeout: 10_000 },
+);
+```
+
+If the first navigation installs/activates the worker without immediately
+controlling the current page, perform a normal reload while the server is still
+available, then wait for `navigator.serviceWorker.controller !== null`.
+
+Do not replace these proofs with a fixed sleep.
+
+## 8. App-shell cache proof
+
+Before server shutdown, inspect Cache Storage from the page and prove that the
+Workbox/app-shell precache contains the resources necessary for the offline
+navigation shell.
+
+The assertion should use stable build-level expectations rather than hashed
+asset filenames where possible. It must prove that a cache exists and that a
+navigation/app-shell response is available; it must not simply infer cache
+readiness from `registration.active`.
+
+If the exact stable cache representation requires inspection during
+implementation, record that concrete representation in the implementation
+report and test the narrowest durable condition.
+
+## 9. API cache exclusion proof
+
+The hard gate itself must inspect Cache Storage and prove that cached requests
+do not contain paths beginning with:
+
+`/api/`.
+
+The separate focused `never caches /api/ responses` test may remain, but the
+hard gate cannot rely on that test having run first.
+
+No runtime caching rule for evidence/API may be added.
+
+## 10. Live evidence proof
+
+Before server shutdown:
+
+- wait for the first real evidence item;
+- prove it is visible;
+- capture/assert a deterministic evidence identity/text such as the fixture's
+  `many-regions-candidate` identity.
+
+That exact previously visible identity becomes the stale-data negative
+assertion after the offline reload.
+
+## 11. Server/network-down proof
+
+After `server.close()`, prove that the authoritative network endpoint is no
+longer available before evaluating offline behavior.
+
+Use a bounded direct request/fetch that must fail because the server is gone.
+Do not infer network unavailability solely from the fact that `close()`
+resolved.
+
+The cache/service-worker may still satisfy app-shell navigation; the proof of
+server unavailability must target server-backed evidence/API behavior.
+
+## 12. Offline reload proof
+
+Reload the controlled page after the server is proven unavailable.
+
+Require:
+
+- the precached viewer shell still renders;
+- the evidence-dependent UI reaches its explicit unavailable/error state;
+- body/UI text contains the existing unavailable message;
+- the previously visible evidence identity is absent.
+
+The safety invariant remains unchanged: a cached shell is permitted; stale
+authoritative evidence is not.
+
+## 13. Cleanup guarantees
+
+Cleanup must be deterministic and tolerant of the intentional mid-test server
+shutdown.
+
+At minimum:
+
+- close page/context;
+- close server if not already closed;
+- remove evidence root recursively;
+- remove temporary persistent profile recursively.
+
+Do not leave the hard gate's browser state under `.my-dev-kit-workflow`.
+
+If cleanup errors are currently swallowed too broadly, preserve enough
+diagnostic information that a leaked profile/server can be debugged without
+turning cleanup into a product semantic change.
+
+## 14. Other PWA tests
+
+The focused tests for:
+
+- service-worker registration;
+- manifest validity;
+- API cache exclusion;
+- install-control behavior;
+- standalone display-mode proof;
+
+remain valuable and should retain their narrow assertions.
+
+Where the first PWA describe still uses a shared persistent context for the
+non-hard-gate tests, replace any fixed historical profile with a fresh
+describe-owned temporary profile and remove it in cleanup. This prevents
+cross-run contamination even when those focused tests continue sharing state
+within their describe.
+
+The hard gate itself must not share that context/profile.
+
+## 15. Dedicated isolated command
+
+Add one repository-owned command so isolation remains a permanent gate.
+
+Preferred package script:
+
+```json
+"test:pwa-hard-gate": "vitest run --config vitest.browser.config.ts tests/browser/pwaHardening.test.ts -t \"HARD GATE\""
+```
+
+Use repository naming conventions if a better exact script name already exists,
+but keep one explicit isolated command.
+
+This command must start from normal test setup and must not require another test
+to have run first.
+
+## 16. Security/readiness integration
+
+The isolated hard-gate command must be part of the applicable security or
+release-readiness validation path so future full-suite success cannot hide a
+regression in test independence.
+
+Do not remove the normal complete
+`tests/browser/pwaHardening.test.ts`/browser/security execution. The isolated
+proof is additive.
+
+If adding the dedicated command to `npm run test:security` would cause the
+same expensive test to run redundantly in a harmful way, keep the command
+separate and wire it into pre-release readiness explicitly. Choose the smallest
+repository-consistent integration, and document the decision.
+
+## 17. Implementation sequence
+
+### Batch 1 — Isolate and strengthen the hard-gate experiment
+
+Primary owner:
+
+`tests/browser/pwaHardening.test.ts`
+
+Expected work:
+
+- replace hard-gate shared state with test-owned fresh resources;
+- replace fixed persistent-profile dependence with temporary profile ownership;
+- add explicit active-registration and current-client-controller proof;
+- add explicit shell-cache and API-cache-exclusion proof;
+- add explicit server/API-down proof;
+- preserve the existing offline-shell/stale-evidence assertions;
+- make cleanup deterministic;
+- make the hard gate pass independently.
+
+Batch 1 acceptance:
+
+```text
+isolated HARD GATE PASS
+full pwaHardening.test.ts PASS
+no production file modified
+no fixed-profile dependence in the hard gate
+```
+
+If the isolated experiment still demonstrates stale evidence or cannot satisfy
+the existing product contract after all prerequisites are proven, STOP with a
+product-defect verdict before Batch 2.
+
+### Batch 2 — Freeze the isolation gate and run full regression
+
+Expected work:
+
+- add the dedicated package script;
+- add the isolation proof to the appropriate security/readiness path;
+- update development/CI/current-state documentation from planned to
+  implemented wording;
+- run complete unit/browser/security/build/docs/package validation;
+- perform patch release readiness if v0.9.1 publication is requested.
+
+Batch 2 acceptance:
+
+```text
+test:pwa-hard-gate PASS
+full browser suite PASS
+security suite PASS
+typecheck PASS
+lint PASS
+unit tests PASS
+build PASS
+docs check PASS
+pack dry run PASS
+no unintended production semantic change
+```
+
+## 18. Required implementation tests
+
+At minimum prove:
+
+1. hard gate passes alone from a clean temporary profile;
+2. hard gate passes when the whole PWA file runs;
+3. hard gate passes in the normal full browser suite;
+4. hard gate passes in the security validation path;
+5. repeated isolated executions do not depend on state from the prior run;
+6. no `/api/` request is present in Cache Storage at the shutdown boundary;
+7. the current client is controlled before shutdown;
+8. the shell cache prerequisite is explicitly established;
+9. the server/API is explicitly unavailable before offline reload;
+10. stale evidence identity is absent after reload;
+11. temporary profile/evidence state is cleaned up.
+
+## 19. Production-code escalation rule
+
+Expected initial classification:
+
+```text
+TEST_DEFECT
+PRODUCT_CHANGE_REQUIRED = false
+```
+
+If the corrected clean-state experiment fails because production behavior
+actually violates the stale-evidence safety contract:
+
+- do not loosen the test;
+- do not add retry/sleep until it happens to pass;
+- capture the exact runtime evidence;
+- stop the maintenance batch;
+- report a product defect;
+- revise this plan explicitly before changing production PWA/service-worker
+  code.
+
+## 20. Version/package expectations
+
+v0.9.1 is a maintenance patch. No canonical evidence schema version is expected
+to change.
+
+No new runtime dependency is expected.
+
+If implementation remains test/documentation-only, package runtime bytes may be
+unchanged apart from version/docs if the user elects to publish v0.9.1. The
+release decision must be made after implementation evidence rather than by
+inventing a product change solely to justify a package release.
+
+## 21. Documentation reconciliation after implementation
+
+When implementation passes:
+
+- `CURRENT_STATE.md` changes from planned to implemented status;
+- `ROADMAP.md` records v0.9.1 as implemented/released only when that state is
+  actually true;
+- `DEVELOPMENT.md` and `CI_CD.md` retain the durable gate-isolation rule;
+- `CHANGELOG.md` receives the actual implemented correction under
+  `[Unreleased]` or the final v0.9.1 section at release preparation;
+- historical v0.9.0 reports remain unchanged.
+
+## 22. Final implementation verdicts
+
+Use a precise result.
+
+Expected success before release:
+
+`PASS_V0_9_1_PWA_HARD_GATE_ISOLATION`
+
+Use a blocker such as:
+
+`BLOCKED_V0_9_1_PRODUCT_PWA_DEFECT_DISCOVERED`
+
+if the self-contained experiment reveals a real production failure.
+
+Do not claim v0.9.1 released until the normal release workflow actually
+completes.