automated-qa 0.11.0

package/references/atlas.md

@@ -0,0 +1,338 @@
+# Frontend failure atlas
+
+Every way a frontend fails, organised by **pipeline position** — the order is
+information: a defect at L1 makes every check below it meaningless, because you
+are testing a build nobody is serving.
+
+This is **atlas v2**. The frozen v1 taxonomy — what every archive, fid, diff
+and external consumer that predates v2 still resolves against — lives at
+`references/atlas-v1.md` / `lib/qa/atlas-v1.mjs` and is never edited again. A
+finding's coordinate is `(atlasVersion, atlas)`; missing `atlasVersion` on a
+record means v1.
+
+Detection column:
+
+| | Meaning |
+|---|---|
+| **S** | Static. `classify.mjs` / `inventory.mjs`. Free, exhaustive, runs on save. |
+| **R** | Runtime invariant. `sweep.mjs` + `probe.js`. No per-feature authoring. |
+| **G** | Generated journey. Derived from the route×entity matrix. |
+| **H** | Human intent. The irreducible part — one question per entity. |
+| **A** | Architecture-dependent: applies only if you chose that architecture. |
+
+`†` = observed in this user's own session corpus (86 sessions, 532 findings).
+
+---
+
+## L1 — Delivery: the code under test is not the code being served
+
+Everything below L1 is void if L1 is wrong. Check it first, always.
+
+| # | Class | Det |
+|---|---|---|
+| 1.1 | Build-time env (`NEXT_PUBLIC_*`, `VITE_*`) set at runtime — never reaches the browser † | S |
+| 1.2 | CDN/edge cache not invalidated after deploy; old bundle still served † | R |
+| 1.3 | Two hosts serving different builds; health check green against a placeholder † | R |
+| 1.4 | Service worker serving a stale app shell | R |
+| 1.5 | `ChunkLoadError` — hashed chunk gone after deploy, open tabs break | R |
+| 1.6 | Wrong `basePath`/`assetPrefix` → every asset 404s | R |
+| 1.7 | Env var present in CI, absent in the runtime image | S |
+| 1.8 | Build succeeded with a stub/fallback module aliased in | S |
+| 1.9 | Verified on preview, shipped from prod — different pipeline † | H |
+| 1.10 | Route's first visit failed, retry succeeded — intermittent; reported as `route.flaky`, never as a silent pass | R |
+| 1.11 | Route reached only through two or more intermediate paths — a redirect chain, not a direct landing (`route.indirect-landing`; auth bounces are reported as unreached, not here) | R |
+
+## L2 — Contracts and boundaries: the typed line between two sides is not honoured
+
+**New in v2.** A typed boundary (an API client, a generated schema, a shared
+type) exists precisely so the two sides of it cannot silently disagree. This
+layer is what fires when something crosses that line unchecked. An
+authorization disagreement caught here carries an Access impact tag rather
+than becoming a second, duplicate L7 finding.
+
+| # | Class | Det |
+|---|---|---|
+| 2.1 | Typed-boundary bypass — a raw/untyped value crosses an API or component boundary that declares a generated or validated type, skipping the check the type exists to enforce | S |
+| 2.2 | Application contract, fixture, or RBAC drift — the client's assumed shape/permission set has diverged from what the server (or its schema/fixture) actually declares | S |
+| 2.3 | Authenticated-transport bypass — a request goes direct to the app's own API while every sibling caller goes through an authenticated client, so whatever that client attaches (session token, error contract) is absent. Source cannot see the endpoint's authentication contract, so this is a candidate for the real-persona lane to confirm with a live 401, never a confirmed defect on its own | S |
+
+## L3 — Arrival: the data never gets there
+
+| # | Class | Det |
+|---|---|---|
+| 3.10 | Request never fired (`enabled: false`, conditional hook) | R |
+| 3.11 | 401/403 — token not attached, or expired mid-session | R |
+| 3.12 | HTTP 200 with an empty array — wrong tenant or filter scope | G |
+| 3.13 | Only page 1 rendered; pagination never wired | G |
+| 3.14 | Race: the slower response overwrites the newer one | S+R |
+| 3.15 | Waterfall — dependent sequential fetches; partial at every instant | R |
+| 3.16 | Response applied after unmount; no `AbortController` | S |
+| 3.17 | Cache-key collision — two queries share one key | S |
+| 3.18 | Cache-key over-specificity — one entity cached under N key shapes | S |
+| 3.19 | Retry storm → rate limit → looks like "no data" | R |
+| 3.20 | CORS preflight failure — invisible behind a dev proxy | R |
+| 3.21 | Parse failure returns `undefined`, treated as empty | R |
+| 3.22 | Same-origin JSON array carried N>0 records; every list on the page rendered zero rows — the data arrived and was never rendered | R |
+| 3.23 | An endpoint TEMPLATE answered 5xx, aggregated across the cell rather than per response (`network.endpoint-5xx`) | R |
+| 3.24 | The same (method, endpoint template) fired 3+ times in one passive page load — a refetch loop or a missing cache key, with no user action to explain it (`network.duplicate-request`) | R |
+| 3.25 | Fewer distinct endpoint templates fired than the route's declared query hooks — the "suspiciously low, not zero" case 3.10 cannot see (`network.request-count-below-declared`; only filed when the import-graph join is trusted) | R |
+| 3.26 | A cross-origin request failed — a third-party script, font, analytics or CDN asset the page depends on (`network.requestfailed.external`) | R |
+
+## L4 — Synchronisation: data arrives, then diverges
+
+**The cross-page sync bug lives here.** `inventory.mjs syncRisks` finds most of
+it statically, with blast radius.
+
+| # | Class | Det |
+|---|---|---|
+| 4.22 | **Server entity copied into a client store** — a second source of truth the query cache cannot invalidate | S |
+| 4.23 | Mutation with no invalidation → every sibling view stale | S |
+| 4.24 | Invalidation targets the wrong key — nothing the written resource's readers query under; blast radius resolved | S |
+| 4.25 | Optimistic update never reconciled with server truth | G |
+| 4.26 | Optimistic update not rolled back on error | G |
+| 4.27 | Two components own one mutation; only one invalidates | S |
+| 4.28 | Derived state not recomputed — `useState(props.x)`, stale closure, dead memo | S |
+| 4.29 | Tearing — external store read without `useSyncExternalStore` under concurrent rendering | S |
+| 4.30 | Cross-tab divergence (no storage/broadcast sync) | A |
+| 4.31 | Realtime subscription not re-established after reconnect | A |
+| 4.32 | Form draft silently overwritten by a background refetch | G |
+| 4.33 | Deleted entity still referenced by a cached list | G |
+| 4.34 | Pagination cache not reset on filter change → mixed pages | G |
+| 4.35 | Write succeeded through the real form, then client-side navigation to a blast-radius route refetched nothing and shows the old value — 4.23/4.24 confirmed live (`--mutate`) | R |
+
+## L5 — Rendering/representation: the frame paints wrong, or the value in it lies
+
+Old Rendering (lifecycle) and old Value (serialisation) merge here: both are
+"the DOM says something the data doesn't support," one at the shape level, one
+at the value level. Cheapest class to detect, highest hit rate, almost nobody
+checks it.
+
+| # | Class | Det |
+|---|---|---|
+| 5.34 | Missing loading state → empty shell paints first | S+R |
+| 5.35 | Missing error state → failure renders as empty, silently | S |
+| 5.36 | **Missing empty state → an empty list and a failed fetch are indistinguishable** | S+R |
+| 5.37 | Suspense boundary converts an error into a permanent spinner | R |
+| 5.38 | Error boundary catches and renders nothing | S |
+| 5.39 | Hydration mismatch — SSR output ≠ first client render | R |
+| 5.40 | List key collision (`key={index}`) → possible local state or focus mismatch when a list reorders | S |
+| 5.41 | Effect dependency bug → infinite render, or never runs | S |
+| 5.42 | Conditional hook order violation | S |
+| 5.43 | Portal/modal escapes its theme or stacking context | R |
+| 5.44 | Virtualised list renders zero rows at certain heights | R |
+| 5.45 | Layout shift on data arrival (no reserved space) | R |
+| 5.46 | `undefined` rendered as text † (this one reached a live API in prod) | R |
+| 5.47 | `NaN` rendered | R |
+| 5.48 | `[object Object]` rendered | R |
+| 5.49 | `Invalid Date` rendered | R |
+| 5.50 | The string `"null"` rendered | R |
+| 5.51 | Unresolved template variable † | R |
+| 5.52 | Timezone — the date shifts by a day | H |
+| 5.53 | Currency — cents/dollars confusion, float rounding | H |
+| 5.54 | Locale/number formatting inconsistent between views | H |
+| 5.55 | Unescaped HTML or raw markdown shown | S |
+| 5.56 | Truncation with no ellipsis or title | R |
+| 5.57 | Enum rendered raw (`in_progress`, not "In progress") | R |
+| 5.58 | Precision loss on large IDs (JS number vs int64) | H |
+| 5.59 | Fabricated success — the run reports a pass that the underlying evidence does not support. Currently unmeasured: no encoded oracle exists, and this class has no producer | R |
+
+## L6 — Interaction and control flow
+
+| # | Class | Det |
+|---|---|---|
+| 6.59 | **Double submit** — no pending guard → duplicate records | S |
+| 6.60 | Navigation during a pending mutation → lost write | G |
+| 6.61 | Back button does not restore list state, scroll, or filters | G |
+| 6.62 | Refresh on a deep link loses required state | G |
+| 6.63 | Unsaved-changes guard missing | S |
+| 6.64 | Interactive element covered by another element — clicks land on the occluder (`interact.click-occluded`; open dialogs and `pointer-events:none` overlays excluded) | R |
+| 6.65 | Focus lost after an action → keyboard user stranded | R |
+| 6.66 | Client validation passes; server rejects with an unhandled error shape | G |
+| 6.67 | Disabled state not conveyed — looks clickable, does nothing | R |
+| 6.68 | Async action with no feedback → the user clicks again | S |
+| 6.69 | A control the surface should render never appeared, waited for rather than raced (`interact.never-appeared`) | R |
+| 6.70 | A control appeared but was never clickable — a different defect from never appearing, and it needs a different fix (`interact.not-clickable`) | R |
+| 6.71 | **Inert affordance** — a control was clicked and nothing observable followed: no DOM mutation, no request, no navigation, no ARIA state change (`interact.inert-control`) | R |
+| 6.72 | Clicking a control throws — the handler errors where a user would click (`interact.click-error`) | R |
+
+## L7 — Access, identity, client security
+
+| # | Class | Det |
+|---|---|---|
+| 7.69 | Role-gated route reachable by deep link | G |
+| 7.70 | UI hides an action the API allows — or shows one it denies | G |
+| 7.71 | Tenant scope missing from a query → cross-tenant leak | G |
+| 7.72 | Session expiry → redirect loop, or silent empty data | R |
+| 7.73 | Stale permissions cached after a role change | G |
+| 7.74 | XSS sink — unsanitised HTML injection | S |
+| 7.75 | Prototype pollution — merging untrusted payload into an object | S |
+| 7.76 | DOM clobbering — a named element shadowing a global | S |
+| 7.77 | CSP violation blocking a real resource | R |
+| 7.78 | `SameSite=None` cookie without `Secure` — the browser rejects it; auth silently absent (`security.cookie-samesite-none-insecure`) | R |
+
+## L8 — Responsive and layout
+
+Tap target moved to L9 in v2 — it is an accessibility class (touch reachability), not a layout one.
+
+| # | Class | Det |
+|---|---|---|
+| 8.79 | Horizontal scroll at 320/390 | R |
+| 8.80 | Overlap or clipping at a breakpoint | R |
+| 8.82 | Long content (400-char name) breaks the layout | R |
+| 8.83 | Broken image with no fallback dimension | R |
+| 8.84 | Dark-mode override missed † | R |
+| 8.85 | Font swap shift | R |
+| 8.86 | Fixed height clips content at large text size or zoom | R |
+
+## L9 — Accessibility
+
+| # | Class | Det |
+|---|---|---|
+| 9.87 | Contrast below threshold | R |
+| 9.88 | Control with no accessible name | R |
+| 9.89 | Keyboard trap, or unreachable control | R |
+| 9.90 | Focus order does not follow visual order | R |
+| 9.91 | No visible focus ring | R |
+| 9.92 | Async result with no live region | S |
+| 9.93 | Tap target < 24px — **excluding sr-only elements** † (moved from L8 in v2: reachability by touch is an accessibility property) | R |
+| 9.94 | ARIA state attribute the element's role does not support — `aria-selected`, `aria-pressed` (the rest of the `aria-allowed-attr` table is not measured) | R |
+
+## L10 — Performance
+
+| # | Class | Det |
+|---|---|---|
+| 10.93 | Long task > 200ms — input blocked for that window (INP) | R |
+| 10.94 | CLS > 0.1 — content moves under the cursor | R |
+| 10.95 | LCP > 2500ms | R |
+| 10.96 | Layout thrash — geometry read after DOM write, in a loop | R |
+| 10.97 | Memory leak — heap retained after GC across navigation | R |
+| 10.98 | Unstable context value → re-render storm, memoisation dead | S |
+| 10.99 | Unbounded list render | S |
+| 10.100 | Bundle size regression | S |
+| 10.101 | Preloaded resource never used — Chrome's own diagnostic, exact-matched (`perf.unused-preload`) | R |
+
+## L11 — Verification integrity
+
+**The highest-leverage layer and the one nobody writes down.** Every class here
+makes the layers above report green while broken.
+
+| # | Class | Det |
+|---|---|---|
+| 11.101 | Capture fires before render → the gate measures nothing † *"worse than no gate — it consumes the verification slot without occupying it"* | H |
+| 11.102 | Baseline captured from the buggy build → locks the bug in as correct | H |
+| 11.103 | An assertion that cannot fail (empty selector, truthy on undefined) | H |
+| 11.104 | The check ran against the wrong host or build † | R |
+| 11.105 | Test skipped or filtered, reported green | H |
+| 11.106 | Claim inflation — report says 103, reality is 1 † | H |
+| 11.107 | **Verified at the wrong layer — API green, UI broken** † | G |
+| 11.108 | Fixture regenerated from actual output → the test becomes a screenshot of the bug † | H |
+| 11.109 | Gate returns "inconclusive" and is read as pass | H |
+| 11.110 | Route absent from the sweep because the route list is hardcoded | S |
+| 11.111 | The dark-mode pass could not run — the theme seeding itself threw, so "dark renders correctly" was never measured (`theme.check-failed`) | R |
+| 11.112 | The `--mutate` replay could not complete, so nothing is claimed about the write either way (`mutate.failed`) | R |
+| 11.113 | Import-walk vs request-log blind spot — the static import graph and the runtime request log disagree about what a route depends on, and neither is trusted as the superset of the other | R |
+| 11.114 | Wrong-layer verification (of the harness itself) — a claim scoped to one detection mode (S or R) is verified using evidence produced by the other mode, and reported as if the claimed mode had actually run | S |
+| 11.115 | Incomplete denominator — a pass/fail claim is reported without stating how many of what, or the denominator silently drops an unmeasured/unreached population instead of naming it | S |
+| 11.116 | Unmeasured promoted to pass — a route, cell, or class the run never reached is folded into the passing count instead of `report.unreached` | S |
+
+11.107 is the mechanism behind "Claude said it was built": the API was checked,
+it answered correctly, and the UI had no password field because the env var was
+inlined at build time. Verification at one layer says nothing about the layer
+above it.
+
+---
+
+## The advanced concept list, sorted by what you can do with it
+
+Concepts split three ways. Only the middle column is testable — but the first
+column is what tells you **where to place the probe**, so it is not wasted.
+
+### Mechanisms — explain why a class exists; not themselves testable
+
+Reconciliation · Fiber · virtual DOM diffing · structural sharing · referential
+equality · immutable data patterns · event loop (macro/microtasks) · scheduler
+priorities · time slicing · concurrent rendering · critical rendering path ·
+paint vs composite vs layout · browser compositing layers · GPU acceleration ·
+subpixel rendering · tree shaking internals · garbage collection timing ·
+accessibility tree · virtual DOM complexity · priority inversion
+
+Read these to know *why* `key={index}` corrupts rows (reconciliation), why a new
+object literal kills memoisation (referential equality), why a geometry read
+after a write stalls (layout → paint → composite ordering).
+
+### Observable — these ARE the runtime probes
+
+| Concept | Becomes | Atlas |
+|---|---|---|
+| Hydration / selective hydration | React #418/#423/#425 in console; click before hydrate is dropped | 5.39 |
+| Tearing in concurrent UI | external store read without `useSyncExternalStore` | 4.29 |
+| Stale closure problem | effect with `[]` deps reading state | 4.28 |
+| Memoisation pitfalls | Provider value is a fresh literal each render | 10.98 |
+| Layout thrashing | geometry reads interleaved with writes in one frame | 10.96 |
+| Long tasks API / FID / INP | longest task > 200ms | 10.93 |
+| CLS / LCP | PerformanceObserver, buffered | 10.94-95 |
+| Detached DOM nodes / leak detection | heap retained after GC across navigation | 10.97 |
+| `ResizeObserver` loop limit | its own console error — free once console is a gate | 5.41 |
+| `MutationObserver` cost | forced-reflow counter | 10.96 |
+| Render waterfalls | dependent request chain ≥ 3 | 3.15 |
+| `AbortController` | fetch in effect without a signal | 3.16 |
+| Backpressure / streaming fetch | unconsumed reader → stalled render | 3.21 |
+| Task starvation | long task + no yield | 10.93 |
+| Service Worker lifecycle traps | stale app shell; buildId mismatch | 1.4 |
+| Cache invalidation / SWR / ETag vs Cache-Control | response headers on the sweep | 1.2 |
+| Code splitting / dynamic import chunking | `ChunkLoadError` | 1.5 |
+| CORS preflight | failed OPTIONS | 3.20 |
+| CSP / Trusted Types | `securitypolicyviolation` | 7.77 |
+| SameSite cookie modes | cookie attributes after login | 7.78 |
+| XSS / CSRF / DOM clobbering / prototype pollution | static sink detection | 7.74-76 |
+| Race conditions in UI state | two fetches, slower wins | 3.14 |
+| Optimistic UI rollback | mutate → force error → assert revert | 4.26 |
+| Idempotent UI actions | double-submit guard | 6.59 |
+| Deterministic rendering | render twice, diff | 11.103 |
+| Preload / prefetch / preconnect, priority hints | resource timing on the sweep | 10.95 |
+| IndexedDB | quota + upgrade failure paths | A |
+| ARIA live regions | async result with no announcement | 9.92 |
+| Pointer events | tap target + hit testing | 9.93 |
+| Speculative prerendering | double-fired effects on prerender | A |
+
+### Architecture — change which classes apply, not what you check
+
+Islands · partial hydration · streaming SSR · server components · edge rendering
+· micro-frontend orchestration · module federation · Shadow DOM · custom
+elements · Web Components interop · Web Workers vs Service Workers ·
+`SharedArrayBuffer` · transferable objects · `OffscreenCanvas` · WebAssembly ·
+WebRTC · CRDTs · event sourcing · finite state modelling · offline conflict
+resolution · CSS containment
+
+Pick one and a whole column of classes switches on. Islands and partial
+hydration make 5.39 and "click before hydrate" primary. Micro-frontends and
+module federation make 1.3 (two hosts, different builds) a weekly event. CRDTs
+and offline make 4.30-4.31 the dominant risk. **Configuration, not new code.**
+
+---
+
+## Evaluated and deliberately not implemented
+
+Each of these was specced far enough to know why it must not ship yet. A rule
+that fires on healthy apps costs more than the class it catches.
+
+| Check | Why not |
+|---|---|
+| duplicate-in-flight-request (3.14's runtime half) | needs a proven guard separating React StrictMode's double-invoke from a real race; ship only with a StrictMode fixture asserted silent |
+| bundle-size-regression (10.100's runtime half) | needs a per-repo build-output path; no universal baseline location in monorepos |
+| render-blocking-head-script | fires on deliberately synchronous analytics snippets — "verify this is intentional" is not a defect claim |
+| missing-live-region-for-async-status (9.92) | scoping unresolved: a live region far from the toast is still a live region; the conservative gate leaves mostly misses |
+| indexeddb-open-error | too narrow — apps touch IndexedDB through libraries that already handle it |
+| deterministic-rendering (render twice, diff) | the noisiest possible rule: timestamps, counters, carousels and A/B buckets are legitimately non-deterministic |
+| CSRF-token-presence | token-auth and SameSite-cookie architectures are both healthy without one; the absence proves nothing |
+
+## Adding a class
+
+1. Reproduce it once, by hand.
+2. Add the rule to `classify.mjs` (S) or `probe.js` (R).
+3. Plant an instance in `references/fixture.html` or `selftest-static.sh`.
+4. Confirm the selftest **fails without the fix and passes with it**.
+5. Give it a number here.
+
+Step 4 is the one people skip, and skipping it produces 11.103 — a rule that
+occupies the verification slot while asserting nothing.

package/references/verify.crud.example.json

@@ -0,0 +1 @@
+{"schema_version":2,"personas":["owner","reader"],"beacon_paths":["/api/telemetry"],"flows":[{"name":"example","route":"/things","declared_endpoint":"/api/things","cleanup_required":true,"production":false},{"name":"example-crosscheck","route":"/things/{fixtureId}","journey":"open-thing","declared_endpoint":"/api/things/{fixtureId}","cleanup_required":true,"production":false,"crosscheck":{"entity":"thing","writer":"owner","observers":[{"persona":"owner","expect":"visible"},{"persona":"reader","expect":"redacted"}],"authoritative_readback":"thingByFixtureId","targets":[{"id":"things-list","route":"/things","role":"collection","transition":"client-navigation","representation":{"selector":"[data-qa-thing-title]","field":"title","type":"string"}}]}}]}

package/references/verify.impact.example.json

@@ -0,0 +1 @@
+{"schema_version":1,"defaults":{"tenant_scope":1,"data_sensitivity":1,"sla_weight":1,"regulatory_weight":0},"policy_note":"Values are repository policy inputs; the agent never infers revenue or compliance status."}

package/references/verify.shadow.example.json

@@ -0,0 +1 @@
+{"schema_version":1,"allow_routes":["/dashboard"],"allow_endpoints":["/api/example"],"retention_days":7,"tenant_partition":"fixture","replay":{"isolated":true,"production":false}}

package/schemas/agent-result.schema.json

@@ -0,0 +1,135 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://frontend-verify.dev/schemas/agent-result.schema.json",
+  "title": "agent-result.json",
+  "description": "lib/qa/agent-result.mjs — the schema-validated AgentResult a compatible qa-agent binary returns, embedded verbatim under run.json's `agent` key and archived as its own canonical file so the manifest can bind its digest without hashing run.json.",
+  "type": "object",
+  "required": ["schemaVersion", "protocolVersion", "status", "runId", "mode", "lane", "binary", "inputs", "dimensions", "limitations"],
+  "additionalProperties": true,
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "protocolVersion": { "const": 1 },
+    "status": { "type": "string", "enum": ["measured", "unmeasured", "invalid"] },
+    "runId": { "type": "string", "minLength": 1 },
+    "mode": { "type": "string", "enum": ["static", "runtime"] },
+    "lane": { "type": "string", "enum": ["source", "public-runtime", "mock-contract", "real-integration", "mfa-integration"] },
+    "binary": {
+      "type": "object",
+      "required": ["sha256", "protocolVersion"],
+      "additionalProperties": true,
+      "properties": {
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "protocolVersion": { "type": "integer", "minimum": 1 }
+      }
+    },
+    "inputs": { "type": "array", "items": { "$ref": "#/$defs/input" } },
+    "dimensions": {
+      "type": "object",
+      "additionalProperties": { "$ref": "#/$defs/dimension" },
+      "properties": {
+        "routePriority": { "$ref": "#/$defs/routePriorityDimension" },
+        "coherenceObligations": { "$ref": "#/$defs/coherenceObligationsDimension" }
+      }
+    },
+    "limitations": { "type": "array", "items": { "type": "string" } }
+  },
+  "$defs": {
+    "input": {
+      "type": "object",
+      "required": ["name", "sha256", "bytes"],
+      "additionalProperties": true,
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "bytes": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "typedReason": {
+      "type": "string",
+      "enum": [
+        "no-sweep-input", "no-binary", "incompatible-protocol", "unsupported-platform",
+        "not-requested", "malformed-output", "schema-invalid", "digest-mismatch",
+        "load-failed", "graph-integrity-failed", "no-coherence-input", "legacy-coherence-input"
+      ]
+    },
+    "dimension": {
+      "oneOf": [
+        { "type": "object", "required": ["status", "value"], "additionalProperties": true, "properties": { "status": { "const": "measured" } } },
+        { "type": "object", "required": ["status", "reason"], "additionalProperties": true, "properties": { "status": { "const": "unmeasured" }, "reason": { "$ref": "#/$defs/typedReason" } } },
+        { "type": "object", "required": ["status", "reason"], "additionalProperties": true, "properties": { "status": { "const": "invalid" }, "reason": { "$ref": "#/$defs/typedReason" } } }
+      ]
+    },
+    "collection": {
+      "type": "object",
+      "required": ["items", "returned", "total", "truncated"],
+      "additionalProperties": true,
+      "properties": {
+        "items": { "type": "array" },
+        "returned": { "type": "integer", "minimum": 0 },
+        "total": { "type": "integer", "minimum": 0 },
+        "truncated": { "type": "boolean" }
+      }
+    },
+    "routePriorityItem": {
+      "type": "object",
+      "required": ["route", "confidence", "expectedInformation"],
+      "additionalProperties": true,
+      "properties": {
+        "route": { "type": "string" },
+        "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+        "expectedInformation": { "type": "number", "minimum": 0, "maximum": 1 }
+      }
+    },
+    "routePriorityDimension": {
+      "oneOf": [
+        {
+          "type": "object", "required": ["status", "value"], "additionalProperties": true,
+          "properties": {
+            "status": { "const": "measured" },
+            "value": {
+              "type": "object",
+              "required": ["items", "returned", "total", "truncated"],
+              "additionalProperties": true,
+              "properties": {
+                "items": { "type": "array", "items": { "$ref": "#/$defs/routePriorityItem" } },
+                "returned": { "type": "integer", "minimum": 0 },
+                "total": { "type": "integer", "minimum": 0 },
+                "truncated": { "type": "boolean" }
+              }
+            }
+          }
+        },
+        { "type": "object", "required": ["status", "reason"], "additionalProperties": true, "properties": { "status": { "const": "unmeasured" }, "reason": { "$ref": "#/$defs/typedReason" } } },
+        { "type": "object", "required": ["status", "reason"], "additionalProperties": true, "properties": { "status": { "const": "invalid" }, "reason": { "$ref": "#/$defs/typedReason" } } }
+      ]
+    },
+    "coherenceObligationsDimension": {
+      "oneOf": [
+        {
+          "type": "object", "required": ["status", "value"], "additionalProperties": false,
+          "properties": {
+            "status": { "const": "measured" },
+            "value": {
+              "type": "object",
+              "required": ["schemaVersion", "coverage", "universe", "invariants", "families", "unattributed", "obligationIds", "operationIds", "sideChannelIds", "cacheKeys", "reads", "mutations", "surfaces", "operations", "sideChannels", "obligations", "perRoute", "plan"],
+              "additionalProperties": false,
+              "properties": {
+                "schemaVersion": { "const": 2 }, "coverage": { "type": "object" }, "universe": { "type": "object" },
+                "invariants": { "type": "array" }, "families": { "type": "array" }, "unattributed": { "type": "object" },
+                "obligationIds": { "type": "array", "items": { "type": "string", "pattern": "^[a-f0-9]{64}$" } },
+                "operationIds": { "type": "array", "items": { "type": "string", "pattern": "^[a-f0-9]{64}$" } },
+                "sideChannelIds": { "type": "array", "items": { "type": "string", "pattern": "^[a-f0-9]{64}:sha256:[a-f0-9]{64}$" } },
+                "cacheKeys": { "type": "array" }, "reads": { "type": "array" }, "mutations": { "type": "array" }, "surfaces": { "type": "array" },
+                "operations": { "type": "array" }, "sideChannels": { "type": "array" },
+                "obligations": { "type": "array" },
+                "perRoute": { "type": "array" }, "plan": { "type": "object" }
+              }
+            }
+          }
+        },
+        { "type": "object", "required": ["status", "reason"], "additionalProperties": true, "properties": { "status": { "const": "unmeasured" }, "reason": { "$ref": "#/$defs/typedReason" } } },
+        { "type": "object", "required": ["status", "reason"], "additionalProperties": true, "properties": { "status": { "const": "invalid" }, "reason": { "$ref": "#/$defs/typedReason" } } }
+      ]
+    }
+  }
+}

package/schemas/analysis.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://frontend-verify.dev/schemas/analysis.schema.json",
+  "title": "analysis.json",
+  "type": "object",
+  "required": ["schemaVersion", "source", "evidence", "features", "context", "graphs", "risks", "stories", "mutationContracts", "proof", "fixQueue", "beforeAfter", "coverage"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": {"const": 1},
+    "source": {"type": "object", "required": ["inventoryIdentity", "sourceDigest", "researchRunId"], "additionalProperties": false, "properties": {"inventoryIdentity": {"type": ["string", "null"]}, "sourceDigest": {"type": ["string", "null"]}, "researchRunId": {"type": ["string", "null"]}}},
+    "evidence": {"type": "array", "items": {"type": "object", "required": ["id", "kind", "fact", "sources", "uses", "confidence"], "additionalProperties": false, "properties": {"id": {"type": "string"}, "kind": {"type": "string"}, "fact": {"type": "string"}, "sources": {"type": "array", "items": {"type": "object", "required": ["file", "verified"], "additionalProperties": false, "properties": {"file": {"type": "string"}, "verified": {"type": "boolean"}}}}, "uses": {"type": "array", "items": {"type": "string"}}, "confidence": {"enum": ["high", "medium", "low"]}}}},
+    "features": {"type": "array", "items": {"type": "object", "required": ["id", "route", "owner", "personas", "requirements", "expectedBehavior", "evidence", "surfaces", "producers", "consumers", "consistencyRules", "rbac", "coverage"], "additionalProperties": false, "properties": {"id": {"type": "string"}, "route": {"type": "string"}, "owner": {"type": "string"}, "personas": {"type": "array", "items": {"type": "string"}}, "requirements": {"type": "array", "items": {"type": "object", "required": ["id", "status", "text"], "additionalProperties": false, "properties": {"id": {"type": "string"}, "status": {"type": "string"}, "text": {"type": "string"}}}}, "expectedBehavior": {"type": "string"}, "evidence": {"type": "array", "items": {"type": "string"}}, "surfaces": {"type": "array", "items": {"type": "string"}}, "producers": {"type": "array", "items": {"type": "object", "required": ["action", "source"], "additionalProperties": false, "properties": {"action": {"type": "string"}, "source": {"type": "string"}}}}, "consumers": {"type": "array", "items": {"type": "string"}}, "consistencyRules": {"type": "array", "items": {"type": "string"}}, "rbac": {"type": "object", "required": ["personas", "status"], "additionalProperties": false, "properties": {"personas": {"type": "array", "items": {"type": "string"}}, "status": {"type": "string"}}}, "coverage": {"type": "object", "required": ["verifiedAppearances", "inferredConnections", "unmeasuredBehavior"], "additionalProperties": false, "properties": {"verifiedAppearances": {"type": "array", "items": {"type": "string"}}, "inferredConnections": {"type": "array", "items": {"type": "string"}}, "unmeasuredBehavior": {"type": "array", "items": {"type": "string"}}}}}}}, "context": {"type": "object"}, "graphs": {"type": "object", "required": ["mermaid", "ascii"], "additionalProperties": false, "properties": {"mermaid": {"type": "string"}, "ascii": {"type": "string"}}}, "risks": {"type": "array"}, "stories": {"type": "array"}, "mutationContracts": {"type": "array"}, "proof": {"type": "array"}, "fixQueue": {"type": "array"}, "beforeAfter": {"type": "object"},
+    "coverage": {"type": "object", "required": ["scope", "declared", "executable", "attempted", "passed", "failed", "unmeasured", "invalid", "exclusions", "rule"], "additionalProperties": false, "properties": {"scope": {"type": "string"}, "declared": {"type": "integer", "minimum": 0}, "executable": {"type": "integer", "minimum": 0}, "attempted": {"type": "integer", "minimum": 0}, "passed": {"type": "integer", "minimum": 0}, "failed": {"type": "integer", "minimum": 0}, "unmeasured": {"type": "integer", "minimum": 0}, "invalid": {"type": "integer", "minimum": 0}, "exclusions": {"type": "integer", "minimum": 0}, "rule": {"type": "string"}}}
+  }
+}

package/schemas/classify.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://frontend-verify.dev/schemas/classify.schema.json",
+  "title": "classify.json",
+  "description": "bin/classify.mjs — static per-file defect classifier.",
+  "type": "object",
+  "required": ["root", "files", "counts", "byRule", "findings", "waived", "cache"],
+  "additionalProperties": true,
+  "properties": {
+    "root": { "type": "string" },
+    "atlasVersion": { "type": "integer", "enum": [1, 2] },
+    "files": { "type": "integer", "minimum": 0 },
+    "cache": { "$ref": "#/$defs/cache" },
+    "counts": {
+      "type": "object",
+      "required": ["total", "waived"],
+      "additionalProperties": { "type": "integer", "minimum": 0 },
+      "properties": {
+        "total": { "type": "integer", "minimum": 0 },
+        "waived": { "type": "integer", "minimum": 0 },
+        "P0": { "type": "integer", "minimum": 0 },
+        "P1": { "type": "integer", "minimum": 0 },
+        "P2": { "type": "integer", "minimum": 0 },
+        "P3": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "byRule": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } },
+    "findings": { "type": "array", "items": { "$ref": "#/$defs/finding" } },
+    "waived": { "type": "array", "items": { "$ref": "#/$defs/finding" } }
+  },
+  "$defs": {
+    "cache": {
+      "type": "object",
+      "description": "the content-identity cache lib/qa/source-snapshot.mjs computes -- see CLAUDE.md 'Outputs are byte-stable'.",
+      "required": ["hit", "identity", "schemaVersion", "sourceDigest", "computedAt"],
+      "additionalProperties": true,
+      "properties": {
+        "hit": { "type": "boolean" },
+        "identity": { "type": ["string", "null"] },
+        "schemaVersion": { "type": "integer", "minimum": 1 },
+        "sourceDigest": { "type": "string" },
+        "computedAt": { "type": "string" },
+        "reusedAt": { "type": "string" }
+      }
+    },
+    "finding": {
+      "type": "object",
+      "required": ["rule", "severity", "file", "line", "detail", "atlas"],
+      "additionalProperties": true,
+      "properties": {
+        "rule": { "type": "string", "minLength": 1 },
+        "severity": { "type": "string", "enum": ["P0", "P1", "P2", "P3"] },
+        "file": { "type": "string" },
+        "line": { "type": "integer", "minimum": 1 },
+        "detail": { "type": "string" },
+        "atlas": { "type": ["string", "null"] },
+        "waived": { "type": "boolean" }
+      }
+    }
+  }
+}