docs(painter): state painter-never-measures as hard invariant (SD-2957)

Update painter-dom README and layout-engine AGENTS.md (CLAUDE.md is a
symlink) to document the two hard invariants enforced by the architecture
boundary tests: no paint-time DOM measurement (Guard E) and resolve stage
as the unique source of truth (no resolvedItem?.X ?? fragment.X coalescing).

Replaces aspirational 'painter is dumb' language with what's actually
ratchet-protected.

Author: tupizz

packages/layout-engine/AGENTS.md

@@ -22,16 +22,29 @@ ProseMirror Doc → pm-adapter → FlowBlock[] → layout-engine → Layout[] 
 
 ## Key Insight: DomPainter is "Dumb"
 
-DomPainter receives a single paint-ready input — `ResolvedLayout` — with
-positioned fragments, pre-resolved styles, and `fragment` back-pointers on
-every `ResolvedPaintItem` — and renders the result to DOM. It does NOT do
-layout logic, measurement, or PM-adapter conversion (that's upstream in
-`layout-engine/` / `layout-resolved/` / `pm-adapter/`).
-
-The painter has zero runtime imports from `@superdoc/pm-adapter`,
-`@superdoc/layout-bridge`, or `@superdoc/layout-resolved`. Architecture
-boundary tests in `tests/src/architecture-boundaries.test.ts` (Guard D)
-enforce this.
+DomPainter receives a single paint-ready input — `ResolvedLayout` — and
+renders the result to DOM. It does NOT do layout logic, measurement, or
+PM-adapter conversion (that's upstream in `layout-engine/` /
+`layout-resolved/` / `pm-adapter/`).
+
+This is enforced as two hard invariants, not aspirational language:
+
+1. **No upstream package imports.** The painter has zero runtime imports
+   from `@superdoc/pm-adapter`, `@superdoc/layout-bridge`, or
+   `@superdoc/layout-resolved`. Guard D in
+   `tests/src/architecture-boundaries.test.ts` enforces this (SD-2836).
+2. **No paint-time DOM measurement.** The painter never reads
+   `clientHeight`, `offsetWidth`, or `getBoundingClientRect` off rendered
+   content. Every size and offset comes pre-computed from the resolved
+   layout. If a required field is missing, the painter throws — it does
+   not rescue incomplete upstream data by measuring. Scroll/viewport
+   plumbing and interactive ruler drag handlers are the only exempt
+   consumers. Guard E enforces this (SD-2957).
+
+The painter also does not coalesce resolved-item fields with the legacy
+`fragment` back-pointer (no `resolvedItem?.X ?? fragment.X` patterns); the
+resolve stage is the unique source of truth for every field the painter
+reads.
 
 ## Common Tasks
 

packages/layout-engine/painters/dom/README.md

@@ -36,6 +36,24 @@ painter.setProviders(newHeader, newFooter); // optional helper for provider chan
 Notes:
 - `paint()` takes only `{ resolvedLayout }` — no raw `Layout`, `blocks`, or `measures`.
 - Header/footer providers must return a `PageDecorationPayload` whose `items` are
-  aligned 1:1 with `fragments` (same length, same order).
+  aligned 1:1 with `fragments` (same length, same order). `offset` is required.
 - Virtualization is opt-in and only supported in vertical mode (windowed pages with spacers).
 - Renderer is read-only: no editing/input handling is included here.
+
+## Hard invariants
+
+- **The painter never measures the DOM at paint time.** Every size, offset,
+  and dimension consumed during rendering must come pre-computed on the
+  `ResolvedLayout` it receives. If a required field is missing, the painter
+  throws — it does not paper over incomplete upstream data with `clientHeight`,
+  `offsetWidth`, or element cloning. Scroll/viewport plumbing and interactive
+  ruler handles are the only allowed DOM-measurement consumers; both are
+  delineated in `painters/dom/src/ruler/` and the scroll mapping in
+  `renderer.ts`. Enforced by Guard E in `tests/src/architecture-boundaries.test.ts`
+  (SD-2957).
+- **The resolve stage is the unique source of truth for every field the
+  painter reads.** The painter does not coalesce resolved-item fields with
+  the legacy `fragment` back-pointer; if `resolvedItem?.X` is absent, that's
+  a producer-completeness issue to fix in `layout-resolved`, not at paint
+  time. Enforced by absence — any future regression to a `?? fragment.X`
+  fallback fails review.