ddd

docs/test-policy.md

@@ -0,0 +1,45 @@
+# Test tiers and source-guard inventory
+
+The release pipeline has four explicit tiers:
+
+- `npm run test:fast` — deterministic unit, contract, persistence, server, and
+  source-policy-compatible regression tests; no browser is launched.
+- `npm run test:browser` — the required real-browser interaction/performance
+  matrix plus the store UI flow. Each runner owns one temporary profile and one
+  process tree, closes it in `finally`, and never targets an unrelated Edge
+  process. The UI runner uses `playwright-core` only as a driver for the
+  system-provided Edge binary; it does not download a second browser.
+- `npm run test:storage` — opt-in large IndexedDB/archive scale coverage.
+- `npm run test:ci` — source policy, fast suite, and required browser release
+  behavior. CI sets the small bounded browser profile and runs one job at a
+  time.
+
+## Source-shape guard inventory
+
+The historical `source-smoke` and versioned `v47xx` files contain temporary
+implementation-shape tripwires. They remain only where no stable public seam
+exists yet. Their common reason is to prevent a known expensive or unsafe path
+from being accidentally restored. Their removal condition is one of:
+
+1. a pure module has a behavioral unit test;
+2. a browser test measures the user-visible DOM, timing, or computed style;
+3. a protocol/storage integration test covers the invariant; or
+4. a generated artifact equality test covers the contract.
+
+The following guards have already moved to public seams:
+
+| Area | Public seam | Replacement coverage |
+|---|---|---|
+| Pointer ownership | `createGestureCoordinator` | `interaction-ownership-test.js` |
+| Interaction scopes | `createInteractionState` | `interaction-ownership-test.js` |
+| 60 Hz latest-value scheduling | `createFrameScheduler` | `frame-drag-scheduler-test.js` and browser cadence probes |
+| Pickup lifecycle/queue | `createDragScheduler` | `frame-drag-scheduler-test.js` and release-drain behavior |
+| Cursor identity/presentation | `createCursorModel` | `architecture-boundaries-test.js` and browser cursor probes |
+| HTTP dispatch | `createHttpRouter` | `architecture-boundaries-test.js` and server integration |
+| Authentication | `createAuthenticator` | `architecture-boundaries-test.js` and server security integration |
+| Atomic JSON storage | `createJsonRepository` | recovery and server integration tests |
+
+When touching a remaining source assertion, migrate it to the nearest seam and
+delete the old assertion in the same change. New tests must not parse function
+source unless they enforce a documented repository policy that cannot be
+expressed as behavior.