Files
MobileGL/docs/Disaggregated/notes/p4a/p4a-results/contract-v4.md
T
swung0x48 aba329cc53 [Docs] (Disaggregated): P6's plan and contract draft; the working notes move from a local directory into the repository
Two things land together: the plan and contract draft P6 needs before it starts, and the
working notes that until now existed on exactly one machine.

1. P6's plan and contract draft (neither started; not one line of code)

     docs/Disaggregated/P6-SPAWN-PLAN.md      the package plan
     docs/Disaggregated/P6-CONTRACT-DRAFT.md  the contract draft (moves to
                                              MG_Remote/CONTRACT-P6.md when c6 lands)

   The three findings that mattered, all written into the documents:

   a. P6 is SMALLER than its roadmap cell suggests. The transport primitives are already in
      the tree and already tested: SocketDoorbell including hangup detection and the two
      lost-wakeup fences (Doorbell.cpp:211-360, four cases in FdPassingTest), SCM_RIGHTS fd
      passing, ShmSegment::Adopt, and the SurfaceOp / WindowKind schema already defined in
      protocol.fbs. inproc uses a real second shm mapping rather than an alias, and
      SessionRings.h:22-28 says that was done so today is not the first time it runs. P6 is
      assembly plus a control plane plus a process, not "write a socket transport".

   b. The evidence for "P6 is only a transport swap" has EXPIRED. It was bought by P5c, whose
      audit found 59 direct memory accesses in a tree that already looked clean. P5e changed
      the tree again. So the first package, a6, is a read-only audit that writes no code, and
      every contract row that depends on it is marked PENDING a6 rather than decided in
      advance.

   c. P6 does not get a game running on the phone. ANativeWindow* is meaningless in the child,
      and protocol.fbs:186-196's own comment says Android transfers the window out of band -
      that band is P12. P6 lands pbuffer / surfaceless / offscreen, which is what HeadlessGL,
      the split-equivalent lane and trace replay need, and which is exactly what P6's own exit
      gate measures. A real window reaching the server is a named refusal. This gets its own
      section because "P6 is done" would otherwise read as "the game runs now".

   The contract adds rule G: a role may not name a process-local handle. It extends P5c's
   rule E (a role may not name the other role's memory) from memory to identity - EGLDisplay /
   EGLSurface / EGLContext / ANativeWindow* / fd number / pid / mapped address either cross as
   a token this contract defines or they do not cross, and a descriptor crosses only through
   SCM_RIGHTS, where the kernel renumbers it.

   What P5e left for P6 gets its own section. The latch semantics are already designed
   (ARCHITECTURE.md:504) and are copied unchanged. What is new is that after run-ahead the
   client no longer waits while the peer process can DIE: the client holds records that were
   published and will never be applied, and Android's freezer suspends the child without
   closing anything. So slow and dead must be distinguishable WITHOUT a timeout threshold.
   That is P6's only new design; everything else is carriage. It shares a predicate with E1's
   outstanding re-specification (ID-122), and the two should be designed together.

   Two gates carried over from P5e's lessons: G2 requires integration-spawn's test-name set to
   match integration-split's name for name, because a differing set means the lane is quietly
   running less; and the arm-proof gate requires every entry to record the child pid and
   transport=spawn in its OWN private log - ID-124 established that this kind of false green
   really happens, and a spawn lane that actually ran monolith would pass every other gate.
   S2's shape must be settled before it is written, and the document says why: E1 is the
   cautionary case.

2. The working notes move into the repository (docs/Disaggregated/notes/, 415 .md files)

   ROADMAP / CURRENT_STAGE_PROGRESS / MEASUREMENTS cite ruling numbers, audit line numbers and
   the provenance of gate figures from ~/w7/notes/, a directory that exists on one machine and
   is under no version control. A record cited hundreds of times that lives only locally is not
   a record, so it moves in whole, with its directory structure intact.

   Only .md moves. Scripts, run logs, census and gate result JSON, patches, APKs and nm dumps
   stay where they are: they are evidence DATA rather than documents - large, regenerated per
   run, and mostly carrying absolute paths and device serials that mean something only on the
   machine that produced them. The mapping and this split are written in
   docs/Disaggregated/notes/README.md.

   Two exceptions are recorded there too: P6's BRIEF has been promoted to a first-class
   document and keeps no copy under notes/, so the two cannot drift apart; and recovered/ holds
   material salvaged from failed workflow runs, which may duplicate the like-named phase
   directories and is kept because a few of those were the only complete version at the time.

   CI's citation lint takes docs/Disaggregated/*.md only (non-recursive), and notes/ is
   deliberately outside it: those notes' file:line citations were written against their own
   code heads, and resolving them against today's HEAD would fail wholesale - which is not an
   error, it is their correct state as a historical record. To check one, use the revision it
   declares (--rev).

3. Inconsistencies fixed in passing

   - README.md's status line still said P5e was in progress while the stage table already said
     closed.
   - CURRENT_STAGE_PROGRESS's next-step item 1 still listed the exit gate as pending, though
     (a) and (b) were run in the previous commit; rewritten to closed plus the one item that
     actually remains (E1).
   - ROADMAP's P6 row still had the pre-phase plan in three of its cells; it now carries the
     package order, the scope boundary and the two new gates.

Checked with check_doc_citations.py: 125 citations across docs/Disaggregated/*.md, 0 problems.
2026-09-18 23:31:39 -04:00

334 lines
23 KiB
Markdown

# P4a contract — c0d (Tracker.h): the two cross-package under-fires clientsp review v1 found
**Commit `9ea44389e7219f74794eccb8a32586ba9b6f806c`** on `refs/heads/p4a/contract`, parent
`17db7598` (= c0c = the pipe head at the time of writing). Two files, +269 / -6:
`MobileGL/MG_Impl/Pipe/Tracker.h` and `MobileGL/MG_Test/Pipe/TrackerTest.cpp`.
`PipeFill.cpp` is **not** touched: neither fix needed the `wants()` dirty-to-subsystem map to
move (see §1.3 and §2.4 for why that is the answer rather than a shortcut). `DirtySurface.def`
is **not** touched either, and §4 is the evidence that it did not need to be.
---
## 0. What the commit does, in one paragraph
Two shutters in `Tracker.h` could not see the state they exist to guard. `glBindSampler` moves
bit **12**'s generation and nothing else, so bit **13** — the bit `bind_sampler_states` is
emitted off — never fired for a sampler bind. And bits **6/7/8** (plus bit 14's program half)
read `GetCurrentProgram()`, which is null for the whole life of a bound separable program
pipeline, so after the first walk on a fresh context the entire program family latched `0` and
never moved again however the pipeline was restaged. Both are under-fires, which the file's own
rule calls the fatal direction; both are fixed by **widening the shutter**, which is where
over-firing is free. Four cases in `TrackerTest.cpp` pin them.
---
## 1. Fix 1 — `glBindSampler` now reaches `bind_sampler_states` (C-M4)
### 1.1 The defect, re-derived on this tree
`PipeFill.cpp:2262-2263` gates `EmitSamplerStates` on `wants(MGPipeDirty::NewSamplers)` — bit
13. Bit 13's shutter was `Mix(textureParams, ctx.GetSamplingResolutionGeneration())`.
`glBindSampler` is `GL_Sampler.cpp:360 BindSampler_State`, and it makes exactly two state calls:
* `MG_State::pGLContext->NoteTextureUnitTouched((Int)unit)` (`GL_Sampler.cpp:369`) →
`Core.h:139` → `TextureState.h:78 NoteUnitTouched`, whose `bindingChanged` defaults to `true`,
so it does `++m_textureBindGeneration` on **every** call — bit 12's counter;
* `textureUnit.SetSamplerObject(...)` (`GL_Sampler.cpp:372` / `:384`) →
`TextureUnit.cpp:28-39`, which calls `pGLContext->BumpTextureBindGeneration()` — bit 12's
counter again.
The only two writers of `BumpSamplingResolutionGeneration` in the tree are **parameter** paths
(`SamplerObject.cpp`, `TextureObject.cpp`). So the review's failure scenario holds exactly as
written: `glBindSampler(3, a); draw; glBindSampler(3, b); draw` fires bit 12 twice and bit 13
zero times, and the server's `BoundSamplerStates[3]` keeps naming `a`'s CSO. There is no pulled
twin to rescue it — `bind_sampler_states` has none, unlike the view set — and Espryt mixes
`SamplerStatesSerial` into a per-draw cache key (`DirectGLES.cpp`, the `SamplerViewsSerial` /
`SamplerStatesSerial` mix beside the `set_sampler_views` suppressor note), so the stale set is
also what its memo keys on.
### 1.2 The change
`Tracker.h:515-517` (comment `:496-514`):
```cpp
now[Index(MGPipeDirty::NewSamplers)] = MGPipeMixShutter(
MGPipeMixShutter(textureParams, ctx.GetSamplingResolutionGeneration()),
ctx.GetTextureBindGeneration());
```
### 1.3 Why the shutter and not `PipeFill.cpp`'s gate — the choice, stated
The review offered two one-line fixes: mix bit 12's generation into bit 13's shutter, or gate
`EmitSamplerStates` on `wants(NewSamplers) || wants(NewSamplerViews)`. **The shutter is the
correct one**, on the derivation of the three unit sets that the brief's D-G2 table gives:
* A **sampler-state set** entry is "the unit's sampler CSO, or the null handle when the unit has
no `SamplerObject` — the texture's built-in sampler then applies". So the set is a function of
*which sampler object is bound at each unit*, plus *which texture is bound there* whenever the
unit has no sampler object and the built-in sampler is what applies. `GetTextureBindGeneration`
is precisely the counter over which texture or sampler is bound at which unit: `Core.h:143-146`
defines it as bumped whenever a texture bind/unbind/delete changes which texture is bound at a
unit, and `TextureState.h:88-99` records that every texture **and sampler** bind entry point
routes through the `NoteUnitTouched` that bumps it. It is **an input to the set**, not another
bit's private business, so mixing it in is a correction to a shutter that was reading too
little — not a coupling of two bits.
* A **sampler bind** changes the sampler-state set and, correctly, also the view set (mipmap
completeness depends on the effective sampler), which is why bit 12 was already right. A
**texture bind** changes both too when the built-in sampler is in play. The asymmetry the
review noted — bit 12 firing, bit 13 not — was never a design, only a gap.
* The gate variant leaves the shutter itself still wrong, and three other consumers read it:
`gen_pipe_dirty_surface.py` derives `DirtySurface.def`'s bit answers **from the shutter**
(§4), the per-bit fire tallies (`m_fires`) are published as a measurement, and
`MGPipeSubsystemForDirty` makes the push bitmask "a true per-subsystem A/B rather than
approximately". A bit gated on another bit's shutter measures neither of those honestly.
Cost of the extra fires: bit 13 now also fires on every plain texture bind. That is bounded by
the emitter's own set-hash suppressor — `MGPipeSetHashSuppressorInstance().ShouldEmit(
BindSamplerStates, hash)` in `SamplerEmit.h`'s `EmitSamplerStates` — which `MGPipeTypes.h:614` makes
mandatory for every `kVarTail set_*` for exactly this traffic (MC 26.2 rebinds the same sampler
at every texture-unit switch). An over-fire costs the 192-entry walk and one XXH64, not a wire
record.
---
## 2. Fix 2 — the program family under a separable pipeline (C-M5)
### 2.1 The defect
`Tracker.h`'s old program block opened `const auto& program = ctx.GetCurrentProgram();` and did
everything under `if (program)`. `Core.cpp:609-631 GetProgramForDraw` shows what an application
that drives `glUseProgram(0); glBindProgramPipeline(P)` gets: `m_currentProgram` is null and the
draw program is the pipeline's composite. So bits 6, 7 and 8 all computed `0`, matched the `0`
they latched on the first (`!m_primed`) walk, and never fired again for the pipeline's whole
life. `Tracker.h` contained no reference to `ProgramPipelineObject` at all.
Rendering was not wrong, and the review is right about why: `GetProgramForDraw` is
emitted-and-still-pulled, the residual fill copies it at every verb, and that is exactly why
`DirtySurface.def:319` rules `BindProgramPipelineObject` `kPulledEveryVerb`. What breaks at P4a
is the **handle protocol**: `glUseProgramStages` makes `GetProgramForDraw` build composite B,
`EmitShaderState` is never called, so B gets no `ShaderCso` handle and no `create_shader_state`
while `set_draw_program` keeps naming composite A — a program D and E will see that the handle
protocol never announced. And bit 8 never firing means `set_global_constants` is never sent for
a pipeline draw at all, where the pull rescues nothing.
### 2.2 The change
`Tracker.h:361-421` adds an `else if` arm on the effective program source; the reasoning
paragraph is `:305-344`, and the file's own header summary is updated at `:30-40`.
```cpp
} else if (const auto& pipeline = ctx.GetBoundProgramPipeline(); pipeline) {
using Pipeline = MG_State::GLState::ProgramPipelineObject;
static_assert(sizeof(Pipeline::DrawProgramSignature) == 2 * Pipeline::kGraphicsStageCount * sizeof(Uint64), ...);
static_assert(sizeof(Pipeline::UniformMirrorVersions) == 2 * Pipeline::kGraphicsStageCount * sizeof(Uint64), ...);
Uint64 stageLinks = static_cast<Uint64>(ctx.GetBoundProgramPipelineName());
Uint64 stageState = 0;
Uint64 stageImages = 0;
for (SizeT stage = 0; stage < Pipeline::kGraphicsStageCount; ++stage) {
const auto& staged = pipeline->GetStageProgram(static_cast<ShaderStage>(stage));
if (!staged) continue;
stageLinks = Mix(Mix(stageLinks, staged->GetLifetimeId()), staged->GetLinkVersion());
stageState = Mix(Mix(Mix(stageState, staged->GetBackendStateVersion()),
Mix(staged->GetUBOContentVersion(), staged->GetBlockBindingVersion())),
staged->GetUniformWriteSetVersion());
stageImages = Mix(stageImages, staged->GetImageUnitVersion());
}
shader = stageLinks;
stageState = Mix(stageLinks, stageState);
bindings = Mix(stageState, stageImages);
constants = stageState;
programImages = Mix(stageLinks, stageImages);
}
```
### 2.3 Why these fields, and why the loop instead of the two helper functions
* **`{lifetimeId, linkVersion}` per graphics stage IS `ComputeDrawProgramSignature()`**
(`ProgramPipelineObject.h:94-105`), the key the composite cache is keyed on. Bit 6 therefore
fires **exactly** when `GetProgramForDraw` would hand back a different composite — exactly when
a new `ShaderCso` handle has to be minted. These are the same non-artefact fields the plain
program arm reads and the ones `Core.cpp:634-644` calls out as not passing through
`ProgramObject`'s join gate, so the tracker's "must not force a compile" rule is intact: no
join, no flatten, no `Link()`.
* **The four per-stage counters are `ComputeUniformMirrorVersions()`'s content**
(`:123-141`) — `backendStateVersion`, `uboContentVersion`, `blockBindingVersion`,
`uniformWriteSetVersion`. Under SSO per-program state is written to the **stage** programs and
only reaches the composite through `RefreshCompositeUniforms`, so those are the counters bits 7
and 8 have to watch. `GetImageUnitVersion` is read per stage as well, because D-G4 asks bit
14's shutter to keep reading all three **frontend** counters rather than any server-side epoch.
* **`stageLinks` is mixed into `bindings`, `constants` and `programImages`.** A composite
*rebuild* hands back a brand-new `ProgramObject` with an empty default uniform block and no
backend state at all (`SetCachedDrawProgram` clears the mirror versions with it), so a shutter
watching only the per-stage state counters would let a rebuilt composite inherit the bindings,
the constants and the image units of the one it replaced.
* **The pipeline NAME is mixed in** because two pipelines can carry the same stage set and each
caches its own composite object, so the signature alone would let a `glBindProgramPipeline`
between two such pipelines pass without a fire.
* **The two helper functions are not called, and that is a gate constraint rather than a
preference.** `gen_pipe_dirty_surface.py`'s `resolve_reader` follows an accessor only through
`return m_member;`-shaped bodies; both `Compute*` helpers build a **local** array and return
it, which it cannot place. Calling them made bits 6/7/8/14 `UNRESOLVED`, which cost
`X(UseProgram, NEW_SHADER)` its writer-taint reason and **broke self-test negative control 6b**
(`BumpTextureBindGeneration -> NEW_GLOBAL_CONSTANTS` must read UNDER-FIRING, and an unresolved
shutter turns that verdict into UNDECIDED). Measured, not guessed: with the helper calls,
`--self-test` printed *"negative control 6b did NOT trip"*. Reading the fields directly keeps
every one of those bits derivable — which is the only mechanism that can catch the **next**
under-fire here — and the two `static_asserts` are what tie the spelled-out pairs back to the
functions they mirror.
### 2.4 The residual hole, recorded rather than hidden
A pipeline **name recycled** by `glDeleteProgramPipelines` + `glGenProgramPipelines` back onto
the same stage programs at the same link versions, with no other program-family change between
the two draws, produces the same shutter value for a different composite object. A
`ProgramPipelineObject` has **no lifetime id and no wire object at all** —
`DirtySurface.def:348-353` says so where it rules `MarkProgramPipelineForDeletion`
`kUnpublishedDestroy` — so there is nothing else in `Tracker.h`'s reach to mix. Closing it needs
a generation counter on the frontend object, i.e. an `MG_State` change, which is out of this
commit's file scope. It is stated in the header comment at `Tracker.h:337-344`.
### 2.5 Bit 14 moved too
`programImages` feeds `NewShaderImages`'s shutter, so the same null-`GetCurrentProgram()` hole
made bit 14's program term constantly 0 under a pipeline. It is fixed by the same arm. This is
the same family as clientsp minor **C-m1** (the emitters keying on `GetProgramForDraw()`), but it
is only the tracker half; C-m1's compute-pipeline half is still C's.
---
## 3. The tests (A-owned, `MG_Test/Pipe/TrackerTest.cpp`)
Four cases, all in the existing `TrackerWalk` fixture, and all four added to
`MGL_TRACKER_TEST_LIST` (`:79-82`) so G2's "the pull and push ctest name sets are identical"
holds — they are visible SKIPs in a pull build.
| case | line | what it drives, and what it pins |
|---|---|---|
| `TrackerWalk.ASamplerBindAloneFiresTheSamplerStateBit` | `:635` | Makes the two calls `BindSampler_State` makes, in its order (`NoteTextureUnitTouched` then `SetSamplerObject`), rebinding unit 3 from sampler 1 to sampler 2 with **no parameter write anywhere**. Asserts `NEW_SAMPLERS` **and** `NEW_SAMPLER_VIEWS` fire, and that the next walk is 0 (the widened shutter does not fire forever). |
| `TrackerWalk.ARestagedProgramPipelineFiresTheProgramBits` | `:662` | Binds a pipeline with no program in use (asserting `GetCurrentProgram() == nullptr` as the premise), reaches steady state, then does what `glUseProgramStages` ends in — one `SetStageProgram`. Asserts bits 6, 7 and 8, then 0. |
| `TrackerWalk.ARelinkOfAStageProgramFiresTheProgramBits` | `:691` | Same setup with a stage already installed, then a real `ProgramObject::Link()` through the entry point `glLinkProgram` drives. The link *fails* (no shaders attached) on purpose: the link-observable versions are bumped in Link()'s **prologue**, before every early-out, which is the invalidation contract. Asserts bits 6, 7, 8, then 0. |
| `TrackerWalk.UseProgramZeroLeavesTheBoundPipelineDrivingTheProgramBits` | `:723` | The shape an application writes: a program in use over a bound pipeline, then `glUseProgram(0)`. Asserts bit 6 fires on the **handover** (the draw's program source changed), that it then settles, and that a subsequent stage change reaches bits 6/7/8 — i.e. the pipeline is the source now. |
All four pass in **all three** build dirs (`build-linux` pull, `build-push`, `build-verify`):
`4/4, 100%`, none skipped in the pull build (they are the `MGL_DECLARE_PULL_SKIP` stubs there and
report as passed).
---
## 4. Item (3): the two UNDECIDED dirty-surface rows stay marked
`MGP_DIRTY_SURFACE_UNDECIDED_LIST` still carries `X(UseProgram, NEW_SHADER)` and
`X(BindVertexArray, NEW_VERTEX_ELEMENTS)`, and **nothing this commit learned makes either
decidable**, because neither mark is about the shutter side:
```
UNDECIDED, no verdict: BindVertexArray <- NEW_VERTEX_ELEMENTS (the write analysis is not complete
for this mutator: Bind() writes 'Access', which it never declares ...)
UNDECIDED, no verdict: UseProgram <- NEW_SHADER (the write analysis is not complete for this
mutator: DestroyProgramSlot() writes 'attachedShaders', which it never declares ...)
```
Both reasons are **writer-side taints** — a call resolved by name into a body with an
unplaceable non-`m_` write — and they are properties of the scanner, not of the rows. Widening
bit 6's shutter cannot touch either. The reason strings after this commit are **byte-identical
to the ones c0 left**, `--check` still reports exactly 2 UNDECIDED, and self-test control 21
("the two P4a undecided marks are still needed") and control 18 ("a stale mark") both still trip.
So `DirtySurface.def` is unchanged: **no row moved, and no mark outlived its reason.**
One thing worth recording for whoever revisits this: the marks are one edit away from becoming
*shutter*-side (§2.3) — if a later change makes bit 6 read something `resolve_reader` cannot
place, the `UseProgram` mark silently changes meaning while staying green, and control 6b is what
notices, on a different bit.
---
## 5. Gates — every number
Run in `~/w7/p4a-contract`, `CCACHE_BASEDIR=/home/swung/w7`, `-j 8`,
`GLIBC_TUNABLES=glibc.malloc.tcache_count=0` for every ctest lane. All three build dirs already
existed and were rebuilt incrementally. **0 compiler errors, 0 warnings** attributable to this
commit (`grep -ci warning:` over the whole build log = 0).
| gate | result |
|---|---|
| **(a) G1** `symbol_report.py --before ~/w7/p4a-before-libMobileGL.so --after build-linux/libMobileGL.so --threshold 0 --fail-on-symbol-set-change --fail-on-added-bytes 0` | **rc 0 — 0 added / 0 removed / 0 resized / 0 renamed.** `.text` 10806323 → 10806323 (+0, +0.000%); `.data` 76840 → 76840; `.bss` 1296872 → 1296872; `.rodata` 1536538 → 1536538; total 17226471 → 17226471; file 19114360 → 19114360 bytes. 27811 → 27811 defined symbols, 27072 → 27072 normalised names, **27072 unchanged**. This is the check that says the fix is in push-only code: `Tracker.h` is inside `#if MOBILEGL_PIPE_PUSH`, so a pull-build symbol moving would mean it was placed wrongly. |
| **(b) unit, pull** `ctest --test-dir build-linux -L unit -j 8` | **rc 0, 100% passed, 0 failed out of 1642** |
| **(b) unit, push** `ctest --test-dir build-push -L unit -j 8` | **rc 0, 100% passed, 0 failed out of 1642** |
| **(b) unit, verify** `ctest --test-dir build-verify -L unit -j 8` | **rc 0, 100% passed, 0 failed out of 1642** |
| the four new cases, each lane | **4/4 passed** in build-linux, build-push and build-verify |
| ctest names pull == push | `diff` empty, **2608 == 2608** |
| names vs `~/w7/p4a-before-ctest-names.txt` (`LC_ALL=C` on both sort **and** `comm`) | **0 removed**, **20 added**, 2588 → 2608. The 20 = c0's 13 + c0b's 1 + c0c's 2 + **c0d's 4**. |
| **(c) G5** `p3a_untouched_regions.sh 37da3c3a HEAD` (re-run on the commit, not the dirty tree) | **rc 0**, the eleven pool / deferred-release / ring / flush-drain functions byte-identical |
| **(d)** `check_include_closure.py --mode both --compiler clang++ --self-test --require-all --expect-probes 4` | **rc 0 — 4 probes, 0 skipped, 0 problems, 6 negative controls tripped** |
| **(e)** `gen_pipe_dirty_surface.py --check` | **rc 0** — 79 mutators all mapped, no stale rows, 45 render-state answers derived, **10 other (mutator, bit) answers derived**, **0 COARSE**, **2 UNDECIDED** (both marked, both with their pre-existing writer-taint reason), 26 prose answers |
| `gen_pipe_dirty_surface.py --self-test` | **rc 0**, **27 negative controls, all tripped**; positive controls OK |
| `gen_pipe.py --check` | **rc 0**, generated files up to date; 71 calls, 72 verify payloads, 63 PipeInputs fields, 69 verbs, 477 inventory rows, 0 UNMAPPED |
| `gen_pipe.py --self-test` | **rc 0**, 7 negative controls tripped |
| `git diff --exit-code -- MobileGL/MG_Pipe/generated` | **rc 0** |
### 5.1 `integration-gpu -R DirectGLES`, before **and** after
Both runs are the full 491-test selection, both under 30 s, so the before side was taken for
real rather than by subset: `git stash push` of the two files → `cmake --build build-push` →
run → `git stash pop` → rebuild → re-ran the push unit lane to confirm the restored binary
(**100%, 0 failed out of 1642**).
| | tests | passed | failed | skipped | wall |
|---|---|---|---|---|---|
| **before** (`17db7598`, same build dir) | 491 | **100%** | **0** | 63 | — |
| **after** (`9ea44389`) | 491 | **100%** | **0** | 63 | 27.4 s (216.85 s·proc) |
The **skipped-test name sets are identical** (`diff` of the two sorted name lists is empty),
which is the check that matters here — a fix that turned a real case into a skip would otherwise
read as "no regression". **No regression.**
---
## 6. What packages B / C / D / E must know — which bit now fires when
**For C (clientsp / sampler-image-program) — the two majors it handed up are closed at the
source, so C's rework must NOT re-fix them:**
1. `NEW_SAMPLERS` (bit 13) now also fires on **any texture or sampler bind at any unit**
(`GetTextureBindGeneration`), not only on a sampler/texture *parameter* change. So
`EmitSamplerStates` is now reached for `glBindSampler` — the case C-M4 named — and also for
plain `glBindTexture` traffic. **C's set-hash suppressor is now load-bearing, not an
optimisation**: without it MC 26.2's per-batch rebinds become a variable-length record per
batch. C-m2's version-first skip in front of the CSO acquire is
worth more after this commit than before it — the extra fires land exactly on that path.
The `SamplerEmitTest` case that bumps `BumpTextureBindGeneration()` by hand and then calls
the emitter directly, now documents a path that really is reachable.
2. `NEW_SHADER` / `NEW_SHADER_BINDINGS` / `NEW_GLOBAL_CONSTANTS` (bits 6/7/8) and the program
term of `NEW_SHADER_IMAGES` (bit 14) now fire under a bound pipeline, on: a
`glBindProgramPipeline` to a different name; any `glUseProgramStages` that changes a stage; a
relink of any stage program; a `glUniform*` / `glProgramUniform*` / block-binding write to a
stage program; and `glUseProgram(0)` handing the draw to the pipeline. So `ProgramEmit.h`'s
`EmitShaderState` is now reached for composites, and **the composite resolver is reached the
way `CompositeResolver.h` expects** — which is what makes C-M1 (the `Live`/`Reset` early-return)
and C-M2 (the never-invalidated `(Cso, Version)` latch) reachable in practice rather than in
theory. C's rework should assume both are now on the hot path.
3. Nothing C owns needs to change *because of* this commit. `wants()`'s map is untouched, the
emitter entry points are untouched, and the subsystem assignment (`kMGPipeSubsystemSamplers`,
`kMGPipeSubsystemPrograms`) is unchanged.
**For B (clientfb / framebuffer-texture):** bit 13 firing on texture binds means the sampler
family's emitters now run on batches where only a texture moved. B's built-in-sampler `Acquire`
through C's cache (ID-14 / ID-15) is therefore exercised more often; the ref-count ruling in
ID-17 is what keeps that safe.
**For D (wire) and E (esprytdraw / esprytobj):** the important consequence is a **negative** one
— a re-composited program pipeline now gets a `ShaderCso` handle and a `create_shader_state`
*before* `set_draw_program` names it, so D's re-keyed twin tables will not see a program the
handle protocol never announced (`MGPipeSlots().FindByLifetimeId(ShaderCso, B)` will hit). E can
rely on `SamplerStatesSerial` advancing on a sampler bind, which is what its per-draw memo at
`DirectGLES.cpp` (the `SamplerViewsSerial` / `SamplerStatesSerial` mix) keys on; before this
commit that serial stood still across a
`glBindSampler`. Fire rates go up for bits 13 and 6/7/8, so the P4a fire-rate measurements
recorded against c0c are not comparable to ones taken after c0d.
**Rebase note:** every package rebasing onto pipe after c0d integrates gets `Tracker.h` at
`9ea44389`. Nobody but A may edit that file; a package that finds itself wanting to is looking at
a contract defect and should say so rather than patch around it.