swayfx-mosaic/tooling/probes/step20c-overnight/matrix/README.md

# Prospective v3: D3-mosaic only

**EXPERIMENTAL / Runtime NOT RUN; independent review PENDING.**
This revision is usable only for the unused `D3-mosaic` case. Every other case
is refused by the entry gate. Consumed v2 results, tokens and receipts are
unchanged. D2-mosaic remains INCONCLUSIVE and cannot be retried.

Before editing, all 578 files of accepted v2, its freeze/review and all matrix
modules were copied with exact SHA256 verification into
`LAB/matrix/executed-v2-archive/`. `archive-map.json` explicitly binds original
paths to archival paths. The original freeze hash remains
`a20ccb39095ca35363119b5cfe4b5c839c1a75863bd72a097686aeac76dd7d7f`.
Original source paths now contain this prospective revision; verification of
executed v2 uses the archival bytes. The v3 freeze binds and verifies that
complete archive, current import closure, binaries and clients, reports and
executed offline receipt. Its separate scope is
`OVERNIGHT_MATRIX_D3_PROSPECTIVE_V3`; it grants no author acceptance.

The actual pinned layer-shell constructor creates a descriptor popup host for
wallpaper even without an XDG popup. Before launching the owner, D3 records the
one live marker process, exactly one wallpaper layer creation, no IPC popup
owner, and at least two complete callbacks containing the same pre-existing
host. All baseline callbacks are retained. Opening then requires exactly this
unchanged known host and one new stable root; unknown or additional hosts,
missing known host, reordered indexes, missing owner/workspace, wrong geometry
and every erroneous comparable root clip are refused. Raw callbacks retain
both hosts and their original indexes. Identity selection uses only membership
in the pre-owner set, never the latest box or clipped index. The existing live
XDG parent/grab hierarchy and exact IPC ancestry bind the new root to the owner.

Constructor + timing + cardinality give bounded association. Native layer/root
owner IDs, host child count and atomic transaction generation are not observed.
The D2 replay tests validate only this fixture algorithm and never upgrade D2's
result. There is no compositor, client, package or production change.

The v2 preparation description below is historical context. Its general
fourteen-case dispatch is superseded by the single prospective v3 gate.

# Overnight output/lifetime/effects/ordering matrix

**EXPERIMENTAL / PREPARATION. Runtime NOT RUN; independent review PENDING.**
This fixture changes no compositor, UX, package, cumulative patch, desktop or
historical LAB. It recompiles only private C17 clients, preserving every source,
protocol XML/scanner input and output, command and resulting binary hash.
STEP20C remains NEXT; production multi-output NOT YET SUPPORTED.

`protocols.py` defines fourteen unique cases. The private `protocols.json` is
compared with that exact mapping by the gate. Every case specifies the scientific
question, output physical/logical geometry, preconditions, client placement,
ordered actions, point computation, ceilings, stop criteria and raw retention.
`engine.py` provides one small shared Session; `cases.py` supplies bounded
scenarios. No massive historical runner is copied. Existing model/protocol
functions are imported with their exact dependency hashes in a separate matrix
freeze. C's reviewer cannot grant matrix acceptance.

| Cases | Actual planned captures per run | Scientific ceiling |
| --- | ---: | --- |
| D1 pristine/Mosaic | 8 | sampled vertical true A/B grabs/crossing/input/dismissal |
| D2 pristine/Mosaic | 9 | sampled scale1.25 geometry after actual asymmetric markers |
| D3 pristine/Mosaic | 9 | sampled R90 scale1.25 geometry after actual asymmetric markers |
| D4 pristine/Mosaic | 17 | resize/clamp/migration sampled geometry; no atomic generation |
| E1 Mosaic | 12 | sampled fully hidden owner and same live chain return |
| E2 Mosaic | 8 | always INCONCLUSIVE for saved identity/render: native traces absent |
| E3 pristine/Mosaic | 18 | sampled effects/cache RGB, never complete damage/cache equivalence |
| F pristine/Mosaic | 8 | INCONCLUSIVE for native buffer identity/atomic input epoch |

Matrix158 + C37 + optional G17 =212/220 captures. Matrix14 + C3 + optional G1
=18/18 runs. These are fixed planned allocations below the ticket ceilings;
failures consume reservations and are never refunded. Each case independently
checks remaining global budget. Failure in another independent case does not
invent a dispatch veto, transfer a PASS or authorize a retry.

D1 uses real vertical outputs(0,0)/(0,600), native575-height vertical client and
actual y600 root/child crossing. D2 uses logical H1(-800,0,800,600) physical
1000x750 scale1.25, H2 normal. D3 uses the same logical boxes and H1 physical
750x1000 transform string90. Five distinct marker colors, positions and actual
PNG dimensions establish the frame before any coordinate conversion. The
marker source PNG is generated client content, recorded separately from actual
captures. Every injection uses the observed logical output union, never applies
scale twice, and recomputes a solid measured interior and fresh wire/local
coordinates. Rectangles remain half open.

The pristine standard origin uses IPC rect+window offset: exported rect.y already
includes decoration. Its exterior is the source-backed inverse(rect.y-deco,
rect.height+deco). Candidate applied origins come from PI_OWNER exterior scene
plus actual decoration/window offsets. Assignment, applied scene, native SHM,
configure, output logical, physical mode and PNG frame are distinct observations.
Root association requires the unique live XDG hierarchy and exact owner ancestry;
PI_POPUP has no owner field. No private generation is invented.

D4 opens clients before camera calibration, records startup blank H1, resizes H1
to960 atx-960 then back800 atx-800, and migrates workspace1 H1→H2→H1 once.
The Mosaic request derives maximum from frozen minimum640 policy, known gaps0
and exact row child count; it requests maximum+960 once and checks actual clamp.
Pristine clamp is NOT EXERCISED. Captures preserve all migration states, logical
order/IDs and legitimate popup dismissal. Input is never sent to an old invisible
surface. Closing owner/fillers restores blank H1 and exact full H2.

E1 preopens two prefix and two trailing fillers around the owner, then calibrates
once, opens two genuine grabs, clicks visible B, computes a hide camera from the
applied owner's endpoint, requires zero owner intersection and empty root clip,
checks no popup pixels on either output and no popup enter, returns by the exact
inverse, requires unchanged object IDs/no popup_done/recreation, clicks B again
and closes normally. The optional second invisible click is omitted.

E2 keeps the compiled default200ms timeout. It receives a genuine configure,
records HELD serial and independent wire configure with no ACK, captures only
what the real scheduling permits, and waits for the natural transaction timeout.
A capture named held may already follow timeout; the receipt explicitly says
NOT EXERCISED for native saved content. The responsive client continues dispatch;
natural ping responses are retained if present. No forced ACK, timer override,
code-level save or invented saved-buffer node is used. H2 sampled equality cannot
upgrade native saved identity or rendering from INCONCLUSIVE.

E3 uses the retained duplicate-configure-safe checker layer and translucent XDG
client. Shadow/no-shadow comparisons precede a classic floating glass wholly
inside H1 (source selects classic for floating). This samples retained ordinary floating
classic filtering, not Mosaic-tiled classic clipping. That same client is then retiled
and recalibrated once for settled tiled optimized blur. Explicit background
A/B/A commands drive real cache reconstruction. Every state has whole H2 capture.
An absent visible shadow or classic ROI is recorded NOT EXERCISED and does not
abort independent optimized measurements. Pristine lacks OBC trace. Native cache
observations, final drawing and input remain distinct; historical maxRGB6 is no
new threshold. No shader/cache/readback edit or compositor rebuild is used.

F uses a nongrab toplevel with real wl_surface input-region commits. Full/empty/
full right-button recipients, focus, gaps geometry, candidate camera forward/
inverse and standard/Mosaic return are sampled within bounds. Native pairs are
selected by exact(output,commit_seq), at most12, with missing presents explicit.
Independent client wire input, PI scene/owner/root, TEMPORAL_DAMAGE and commit/
present remain separate. Native buffer references/releases and hit epochs are
absent from the candidate. No scheduler manipulation, interval-seeking flood,
forced timing or GPU readback is used. Unobserved natural interleaving remains
NOT EXERCISED; buffer identity/atomic generation remain NOT PROVEN.

Global run reservation precedes runtime/socket/process creation; local durable
reservations precede every camera, chain, grab, click/move, configuration,
mutation and capture. Typed local counters reconcile exact event sequences and
immutable limits. A unique O_EXCL token makes each failed attempt unretryable.
Private runtime0700 and cleared inherited desktop/loader environment are required;
every swaymsg has explicit -s. Actual renderer startup lines and proc maps bind
candidate/pristine, wlroots and static/private SceneFX. Active watchdog143s,
run150s, per-log32MiB and shared cleanup deadlines bound all owned process groups.
Actual terminal IPC codes, process exit codes, rescue and runtime removal survive
failures. Cleanup failure downgrades the outcome and keeps measurement status.

## Separate independent review

Preparation entry: `PYTHONDONTWRITEBYTECODE=1 python matrix/prepare.py`.
This compiles clients only and is O_EXCL for its new private directory. Two
failed offline preparations on absent historical close_a context are retained
under matrix-client-preparation-failure01/02; the final region client reuses only
the exact command branch, with unique-line matching. No graphical attempt followed.
Initial offline tests23PASS/1FAIL asserted205 instead of actual203 planned PNG;
G was subsequently assigned17 captures, so final whole-batch planning is212.
that failed receipt stays preserved. Final negative tests and AST checks are
actual execution, not an acceptance generator or proof of graphics.

`gate.freeze()` writes LAB/matrix/freeze.json with every final source, reused
module, client source/protocol/binary, source audit, exact binary/library, pristine
provenance and executed receipt. No author-generated acceptance exists.
An independent read-only reviewer writes LAB/matrix/review.json with:
status ACCEPTED, independent=true, read_only=true, blockers=[],
scope OVERNIGHT_MATRIX_FINAL_BYTES, freeze_sha256=SHA256(freeze.json),
files=the exact frozen files mapping, report_file=absolute report,
report_sha256=its exact SHA256. Changed bytes invalidate acceptance.

Only after acceptance: `PYTHONDONTWRITEBYTECODE=1 python matrix/run.py D1-pristine`
(or another exact case key). The gate fails before any token/run reservation if
review, source/client/binary identity, ownership, socket/process state or budget
is invalid. The author performs no run and grants no acceptance. Independent
review may refuse technically incomplete predicates before any case consumes
its budget; raw results never upgrade unsupported scientific claims.