Files
MobileGL/docs/Disaggregated/notes/p5/p5-results/s1-v1.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

36 KiB
Raw Blame History

s1 — session and transport, v1

Branch p5/s1, worktree ~/w7/p5-s1, base feat/disaggregated @ 5175f9cc. Commit range 5175f9cc..4cf59428, four commits.

# commit what
1 5f6c2eca Transport/: SessionSegments, SessionProducer, SessionConsumer, the Watermark namespace, ReplySlot.h, EventRing.h, RoleMemory.h
2 0ff8dbde protocol.fbs + regenerated header
3 b0857f38 ClientSession, ServerSession, CapsAbiFingerprint, ReplyPool::PostReply
4 4cf59428 MG_Test/Wire/SessionTest.cpp (18 cases) + its CMake entry

No new .cpp was added to the root CMakeLists.txt: every new implementation went into a file the disaggregated source list already carries (Transport/Ring.cpp, Transport/ShmSegment.cpp, the two session .cpps) and everything else is a header. That is deliberate — w1, c1 and v1 all have new files to declare and the P4a lesson was that they would all append at the same point. If a later package needs a new .cpp under MG_Remote/, it is the first one, and it should go through the integrator so the four appends are one edit.


1. Acceptance numbers

1.1 The four self-tests

gate result
G1 (symbol_report.py --threshold 0, ~/w7/p5-before-libMobileGL.so → build-linux/libMobileGL.so) .text 10806323 -> 10806323 (+0, +0.000%); 27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed
four build dirs pull / push / verify / split all rc=0; CTestTestfile.cmake confirmed present in each before any verdict was reported
ctest -L unit pull 1785/1785, push 1785/1785, verify 1785/1785, split 1860/1860 (the 1842 baseline + s1's 18)
ctest -L integration-gpu in build-push with MOBILEGL_TRANSPORT=monolith 1117/1117, and build-push's full ctest -N list is byte-identical to ~/w7/p5-before-ctest-names.txt (2902 names) — G2/G14
generators gen_pipe.py --check up to date; --self-test 9 negative-control trips + positive control OK; gen_pipe_dirty_surface.py --check clean; gen_protocol.py --check clean after the schema edit
purity check_include_closure.py: 4 probes, 0 skipped, 0 problems — every new Transport/ header stays clear of MobileGL/Includes.h
nm role check pull MG_Remote symbols 0; split 275

Existing Wire suites unmoved: ctest -R '^Ring|^Doorbell|^Framing|^FdPassing|^InProcessTransport|^Protocol|^Session' in build-split = 75/75 (52 pre-existing + c0's 5 + s1's 18). ProtocolSmokeTest.cpp was not edited, including its UnionTagsAreFrozenWireValues case — the schema change was not a wire break.

1.2 What SessionTest pins (18 cases)

  • SessionSegmentsAreRealSharedMemoryAndNotAHeapAllocation — the four segments carry real descriptors. This is the mechanical check that inproc did not quietly become new[].
  • TheRingIsTheLargestPowerOfTwoLeftAfterTheControlPage, TheDefaultGeometryIsTheFourContractSizes — the geometry, including the deviation in §2.1.
  • TheMemoryLedgerIsPerRoleAndIsReleasedOnClose — the peak-RSS hooks t1 consumes.
  • TwoThreadsMoveTwentyThousandRecordsAndAgreeOnEveryOne — the acceptance run, over a 32 KiB ring so it wraps ~10 times and the filler is under load rather than in one contrived case.
  • One case per watermark rule: SubmittedSeqIsThePublishersAndIsPurelyDiagnostic, AppliedSeqAdvancesExactlyOncePerRecordAndIsNeverBatched, RetiredSeqMayTrailTheApplyButCanNeverOvertakeIt, CompletedFrameSerialIsTheServersAndIsIndependentOfAppliedSeq, PresentAckSerialIsWaitedOnWithGreaterOrEqualAndWakesThroughTheReverseBell.
  • AWrapFillerDoesNotAdvanceTheSessionsAppliedSeq — R-9's last sentence, against the session's own counter rather than against Pop's behaviour (RingTest already pins that half).
  • AReplyIsAddressedBySeqAndCarriesItsSeqBackForSelfCheck (seq 13 must NOT read seq 5's answer out of slot 5), DeclinedIsARealAnswerWithNoPayload, and a death test for "a reply larger than its slot is Fatal, not truncated".
  • TheEventRingCarriesTheThreeReverseCallbacks, AFullEventRingLatchesTheFlagRatherThanDecidingWhatToDoAboutIt.
  • ShutdownUnparksTheApplyThreadAndTheJoinIsBounded — InProcessTransportTest.cpp:344's shape, 5 s bounded with detach() on timeout, so a lost wakeup is red and not a wedged CI job. It also asserts that a producer blocked in the verb barrier comes back as ShutDown.
  • TheAbiFingerprintChangesWhenAnyOfItsInputsDoes.

2. Rulings I made that the brief and the contract did not

Each says what would overturn it.

2.1 The command ring is 4 MiB, not 8, and one record is capped at 2 MiB, not 4

CONTRACT-P5 §5 and Config.h's MOBILEGL_IPC_RING_MB comment both say "8 MiB caps one record at 4 MiB". That arithmetic treats the whole segment as ring bytes and does not subtract the control page. Ring.h:11-13 puts RingControl at the HEAD of SEG_CMD, it is 4096 bytes by static_assert, and RingProducer requires a POWER-OF-TWO capacity because the indexing is a mask (Ring.cpp:89-103). So an 8 MiB SEG_CMD leaves 8 MiB − 4096, and the largest power of two that fits is 4 MiB → MaxRecordBytes() == 2 MiB.

I took the deviation in the direction that is safe: the announced SegmentRef.sizeBytes stays the four pinned numbers (8 / 32 / 8 MiB + 256 KiB, ProtocolSmokeTest.cpp:72) and the ring inside SEG_CMD is half of its segment. R-10's obligation is to PROVE no record approaches the cap, and a lower cap makes that proof fire earlier and louder rather than later and silently.

Two alternatives, both rejected and why:

  • announce sizeBytes = 4096 + 8 MiB — breaks the four sizes the brief says to copy and that ProtocolSmokeTest.cpp:72 pins, and is the number a P6 peer has to mmap;
  • move RingControl out of SEG_CMD — needs a fifth SegmentRef that Welcome does not have.

SEG_STAGE is unaffected: RingControl holds TWO cursor triples and the stage triple is the second, so SEG_STAGE has no control page of its own and 32 MiB is already a power of two. SEG_EVENT gets its own control page (a third cursor set would resize the 4096-byte shared page), so its 256 KiB yields a 128 KiB ring.

Overturned by: a decision that SegmentRef.sizeBytes may carry ring + one page; or a RingProducer that accepts a non-power-of-two capacity.

2.2 CapsSnapshot gains callMask and backendType; Hello/Welcome gain abiFingerprint

Table 0 deletes four CapsSnapshot fields and names no carrier for MGPCaps::CallMask — but R-8/C-4 makes CallMask the only legal client-side source of "does the server consume this family", and dynamicParameters is the image of DynamicBackendParameters, which CallMask is not a member of. Without a carrier, R-8 is unimplementable for a second time. Likewise CapsMirror::Backend() must return the server's BackendType and nothing on the control plane carried it (Hello.backendType is the client's request).

Four appends, all safe: the deleted four were the LAST four fields, so no surviving field moved a vtable slot, and every addition is at the end.

table added why
CapsSnapshot callMask: ulong R-8/C-4's consumer mask + the nine MGPCapBits
CapsSnapshot backendType: uint CapsMirror::Backend(); frontend branches take a wrong arm rather than fail on a value they do not know
Hello abiFingerprint: ulong table 0's ABI agreement; Hello already carried the string, not the sizes
Welcome buildFingerprint: string, abiFingerprint: ulong the server's half of the same assertion; the string is only so the Fatal can name both builds

Overturned by: folding CallMask into the head of the dynamicParameters blob (cheaper on the wire, worse to read), or carrying the server's backend type inside rendererInfo.

2.3 The SERVER creates all four segments; the client attaches

Welcome announces all four SegmentRefs and Welcome is server → client, and ServerSession::Accept's own doc comment says "maps the four segments". "Client-owned" in protocol.fbs's comments is about who WRITES a segment, not who allocates it. Under inproc the client attaches to the same mapping under its own ledger role; under spawn that call becomes ShmSegment::Adopt of the fds the server passed by SCM_RIGHTS, which is why nothing below SessionSegments knows which it was.

2.4 Reply pool geometry: 8 slots of 1 MiB

ReplyPool::SlotBytes() is "sized from the scenario's largest read rather than guessed", and the trade is the opposite way round from the obvious one: while the verb barrier holds, the in-flight depth is exactly ONE, so every extra slot buys nothing except a smaller maximum answer. 8 MiB / 8 = 1 MiB, which covers a 512×512 RGBA8 ReadPixels. The slot count must be a power of two (the addressing is a mask, and a division on the apply thread in the reply path of every blocking call is not free). Overturned by: t1's scenarios needing a bigger single read, which is spelled as a lower slot count, not a higher one. P9 re-chooses the whole geometry when it makes the pool asynchronous.

2.5 ReplyPool::PostReply is implemented inside v1's PipeApplier.cpp

The SEG_REPLY slot pool is s1's deliverable (BRIEF §5) but c0 declared the class in Server/PipeApplier.h, which is v1's file. The resolution: the addressing lives once, in Transport/ReplySlot.h, which the CLIENT reads the same slots back through; PostReply's body is a two-line delegation that rebuilds the view from ReplyPool's existing four members. v1's header is untouched, ReplyPool's members are untouched, and every PipeApplier::* body is untouched — the diff in v1's file is one #include and one function body.

2.6 The consumer mask and the cap bits are setters with derived defaults, and v1 owns the answer

Nothing in the tree produces MGPCaps::CallMask — it is declared at MGPipeTypes.h:133 and written by nobody. So ServerSession takes both halves through setters:

  • SetConsumedSubsystems(mask). The default derives from the only registration that exists: PipeFill.cpp:920's P4aFamilyHasItsConsumer says every P4a family hangs off MGPipeGetResourceOps() and that there is deliberately "no per-family registration to add", so the default is kMGPipeSubsystemsMigratedAtP2 when that table is null and kMGPipeSubsystemsMigratedAtP4a when it is not. This is a default, not a ruling — v1 should confirm or replace it. Publishing a bit the server does not consume is ID-39's shape from the other side: the client emits and nothing applies.
  • SetCapabilityBits(bits). The default sets only kCapResidentSubData, from MGPipeResourceOpsHaveSubDataResident(). Every other bit is 0, deliberately: R-15's cross-cutting rule is that a cap bit set on a guess answers "supported" for a path that does not exist, which is how a split lane produces a plausible picture for the wrong reason. kCapNeedsHostIndexBytes / kCapNeedsHostUboBytes stay 0 for all of P5 by ruling.

2.7 Doorbell placement — contract §3.9, implemented as ruled

The two accessors stay off ITransport. ServerSession::ConsumerDoorbell() / ProducerDoorbell() resolve the pair from ITransport::Role() in one switch in one file, and P6 adds one arm there rather than two virtuals every transport has to find a home for. Everything else takes SessionProducer& / SessionConsumer&, which already hold the right two references, so no call site outside those two functions knows which bell is which.


3. What does NOT run yet, and why that is the honest answer

ServerSession::Accept and ClientSession::Start are complete and compile, and each runs end-to-end until it reaches a dependency that has not landed:

call stops at owner
ServerSession::Accept step 5 Wire::SegmentTable::Install / InstallProcessResolver w1
ServerSession::PublishCapsSnapshot EncodeFormatCapabilities / EncodeRendererInfo w1
ClientSession::Start step 8 ServerLoop::Start v1
ClientSession::EmitAndWait still c0's stub — the barrier is c1's c1

All four are c0's named-Fatal stubs and they abort loudly. I deliberately did not route around any of them: a session that skipped Install and carried on would be a decoder with no segments, which is the "split lane ran monolith and went green" shape the whole phase exists to prevent. The consequence is that SessionTest pins the Transport-level session pair — which is the ring-owning object scout-transport §3/§7.1 and the exit gate are actually about — and not the two role classes. The first end-to-end Accept runs the day w1 lands.

s1 supplies the four primitives c1's EmitAndWait composes from, so that the barrier's wait and the reply's wait stay ONE wait (R-3/R-5): Encoder(), Producer() (publish → submittedSeq → ring, in that order), WaitForApplied(seq, timeoutMs), ReadReply(seq, …).


4. Where I think the brief or the contract is wrong

  1. §5's "8 MiB caps one record at 4 MiB" is off by 2× — §2.1 above. Config.h's MOBILEGL_IPC_RING_MB comment carries the same arithmetic and should be corrected with it.
  2. Table 0 deletes tableSlotMask without giving MGPCaps::CallMask a carrier, which leaves R-8/C-4 unimplementable for the same reason R-8 was unimplementable before c0 fixed it — §2.2. The contract's §6.1 argues against "a SECOND mask field", which is not the same as arguing against the first one.
  3. CapsSnapshot has no carrier for the server's BackendType and CapsMirror::Backend() needs one — §2.2.
  4. The brief's "Welcome's four SegmentRef sizes … 照抄" and §5's record cap cannot both be satisfied, because the control page has to come out of one of them. I kept the announced sizes; the integrator should say if that was the wrong half to keep.

5. Accounts left open

  • P6 (spawn). SessionSegments::AttachInProcess is the one function that becomes an ShmSegment::Adopt path; ConsumerDoorbell/ProducerDoorbell gain one SocketTransport arm each. Welcome's four SegmentRefs are already cross-checked against the server's real mapping on the client side, so the assertion that would otherwise first run in P6 runs today.
  • P9. SEG_EVENT's overflow POLICY. The mechanism is here — a full ring latches eventRingFull, a dropped lossy event counts in eventDropped, and EventRingProducer::Reserve returns nullptr rather than deciding — but nothing chooses between blocking, dropping and escalating. The reply pool's geometry is P9's too, once seq becomes "the id's initial value".
  • P7. The fixed-width DynamicBackendParameters rewrite that would make CapsAbiFingerprint() unnecessary.
  • The git stamp inside the fingerprint is weak and is there for diagnostics. GIT_COMMIT_HASH_SHORT is captured at CMake CONFIGURE time, so an incremental build after a commit still reports the configured hash (this is the same trap as android-build-bisect-traps). The three sizeofs are the load-bearing inputs; under P6's same-machine same-binary spawn all four are trivially equal.
  • Duplication. ReceiveEnvelope + ParseEnvelope + FatalAbiMismatch are ~30 lines repeated in ClientSession.cpp and ServerSession.cpp. Left as-is because factoring them out needs a new header under MG_Remote/ and both copies are s1's; worth folding into whatever control-plane helper P6 needs anyway.
  • MOBILEGL_IPC_ADOPT_TIER, PERSISTENT_BLOCK_KB, STRICT_ERRORS, AUDIT, SERVER_AFFINITY, SERVER_PATH are parsed by c0 and read by nobody in s1's surface — they belong to b1, p1 and v1. s1 reads RingMb, StageMb, SpinUs and VerbBarrier.

6. Files

Owned and changed: MG_Remote/Transport/{SessionRings.h, ReplySlot.h, EventRing.h, RoleMemory.h} (new), Transport/{Ring.cpp, ShmSegment.cpp}, MG_Remote/Protocol/{protocol.fbs, generated/protocol_generated.h}, MG_Remote/CapsCodec.cpp (the CapsAbiFingerprint half only), MG_Remote/Client/ClientSession.{h,cpp}, MG_Remote/Server/ServerSession.{h,cpp}, MG_Test/Wire/{SessionTest.cpp, CMakeLists.txt}.

Touched outside my ownership, minimally and by necessity: MG_Remote/Server/PipeApplier.cpp — one #include and ReplyPool::PostReply's body (§2.5). No PipeApplier::* body, no header, no .def, no generator, no root CMakeLists.txt.

Logs kept: ~/w7/p5-s1-round2.log — the whole final acceptance in one file (four builds, G1, purity, generators, the four unit lanes, integration-gpu, the name identity, the flake hunt) — plus ~/w7/p5-s1-symbols.md, ~/w7/p5-s1-names-push.txt, and the scripts ~/w7/p5-s1-{gate,verify2,cfg,setup,submodlinks,genproto}.sh. ~/w7/p5-s1-flatc-build/flatc is the pinned flatc, kept so gen_protocol.py re-runs without a rebuild.


7. Fix round 1 — against s1-review-v1.md (1 BLOCKER, 8 MAJOR, 7 MINOR, 3 QUESTION)

Commits 4cf59428..7c8d2b44, five. 7eff493d B-1, 0732e1bb M-1, 31099ef7 the Transport MAJORs, ffa90ccc the Client MAJORs, 7c8d2b44 the seven new cases.

The review is right on every finding I could check, including the two it graded as judgement calls, and it is right about the thing I got most wrong: §2.1's rejection of the zero-cost geometry was false on the facts, and I should have checked ProtocolSmokeTest.cpp before citing it. It constrains the schema's ability to carry a number, not what a session announces. Everything below is what changed; where I did not change something I say why in one line.

7.1 Acceptance, re-run in full at 7c8d2b44

gate result
four builds pull / push / verify / split all rc=0, CTestTestfile.cmake confirmed first
G1 --threshold 0 .text 10806323 -> 10806323 (+0, +0.000%); 27811 -> 27811 defined symbols: 0 added, 0 removed, 0 resized, 0 renamed — unmoved
ctest -L unit pull 1785, push 1785, verify 1785, split 1867 (1842 baseline + 25), 0 failed
ctest -L integration-gpu, build-push, MOBILEGL_TRANSPORT=monolith 1117 / 1117
ctest -N name set vs p5-before-ctest-names.txt identical, 2902 names, sorted diff 0 lines
gen_protocol.py --check clean — the committed header is byte-identical to what the pinned flatc produces from the edited schema
gen_pipe.py --check / --self-test up to date; 9 negative-control trips, positive control OK
purity 4 probes, 0 skipped, 0 problem(s)
nm role check pull MG_Remote 0, split 282
flake whole Wire lane (82 tests) -j 8 × 8 reps: 0 failing reps. SessionTest --gtest_repeat=30: 25 × 30, rc=0

One observation that is NOT drift and should not be read as one: gen_pipe_dirty_surface.py --check prints a census line whose "N members are written outside those roots" went 385 (base) → 427 (here). --check returns 0 and no generated artifact is dirty; git diff over MG_State/GLState, MG_Impl and MG_Pipe against the base is empty. The number moves because that count is over writes found anywhere outside STATE_ROOTS and the script states its own imprecision in the same line — "a FIELD token is not scoped to a type" — so MG_Remote's new members (m_slots, m_appliedSeq, …) land in it. It only ever WIDENS the undecided set. My gate script's | tail -1 shows that census instead of a verdict; that is a reporting wart in ~/w7/p5-s1-gate.sh, not a result.

7.2 BLOCKER

B-1 — fixed, and the fix is the absence of a mechanism rather than a better one. DeriveConsumedSubsystems() and DeriveCapabilityBits() are deleted, and with them the reads of MGPipeGetResourceOps() and MGPipeResourceOpsHaveSubDataResident() (both includes removed). ServerSession::CallMask() now calls FatalUnsetCallMask — MGLOG_F + std::abort, named Fatal{UnsetCallMask} — when either half was never set, so the omission is loud at the first CapsSnapshot instead of silent for a phase. PublishCapsSnapshot reaches it before it builds a buffer. Accept additionally emits one MGLOG_W when the mask is unset, in the same shape as the existing missing-backend line, so the warning arrives even for a session that publishes no snapshot. CallMaskIsSet() is the non-fatal probe for a caller that can handle the absence.

Both setters are mandatory, not just the consumer one. SetCapabilityBits(0) is a legitimate and explicit answer — "this server offers no optional capability" — and is the right call while the packages that own each bit land; what is refused is not saying. The reviewer's severity note ("downgraded to MAJOR by any mechanism that makes an unconfirmed mask loud or fatal") is the exact shape of what landed.

7.3 MAJOR

M-1 — fixed, (deprecated). The four retired CapsSnapshot fields keep their declarations with (deprecated), so slots 14 / 16 / 18 / 20 stay burned and callMask / backendType moved to 22 / 24 (verified in the regenerated header). No ABI-major bump, no wire break, no accessor generated for the retired names. My original report's "four appends, all safe … every addition is at the end" was wrong in flatbuffers' sense and the reviewer's reading of the base header is correct. The report's "ProtocolSmokeTest was not edited … so the schema change was not a wire break" was a non-sequitur; that file pins union tags and enum values only. SessionTest.CapsSnapshotFieldIds‑ AreFrozenAndTheRetiredSlotsStayBurned is now the first test in the tree that pins a table field id, and it covers the Hello / Welcome appends too.

M-2 — fixed. SizesFromConfig() is called whenever SetSegmentSizes did not run (m_sizesSet), instead of behind a condition that could never be true. MOBILEGL_IPC_RING_MB and _STAGE_MB now reach the mapping. My §5's claim that s1 "reads RingMb, StageMb, SpinUs and VerbBarrier" is true as of this commit and was not before.

M-3 — fixed in both files. envelope->msg_as_Hello() == nullptr / msg_as_Welcome() == nullptr are now part of the same guard as the tag check. SessionTest.AVerifiableFrameCanCarryANullUnion‑ Payload builds the reviewer's 24-byte shape and asserts that it verifies, carries the identifier, reports msg_type() == Hello and hands back nullptr — so the guard cannot be simplified away by someone who assumes verification implies a payload.

M-4 — fixed. Stop()'s !m_started branch closes the client's view, then ServerSessionInstance().Close(), then the transports — so the five post-Accept failure paths no longer leave the server m_accepted (which made every later Start return MOBILEGL_ERR_INVALID_ARGUMENT for the life of the process), no longer leave the process resolver installed, and no longer destroy a transport that ServerSession still points into.

M-5 — fixed. SessionConsumer::ApplyOne now tracks m_retirableCursor, which stops AT the first kRecBorrowSlot record and does not move again until RetireBorrowedUpTo releases it; RetireThrough publishes through PublishRetiredUpTo instead of PublishRetired, which stored the local tail into both tails and handed back every popped byte. PublishRetiredUpTo now has a caller. SessionTest.ABorrowedSlotIsNotHandedBackUntilItIsReleased asserts cmdRetiredTail < cmdAppliedTail while the borrow is held, and equality after the release, with RingCursorsValid at both points. The header comments and the code now say the same thing.

M-6 — fixed, the reviewer's alternative. AttachInProcess dups each of the owner's descriptors and goes through ShmSegment::Adopt + Map on POSIX, so the inproc peer has its own mapping, its own fd and its own lifetime — the attach half, which is exactly what P6 replaces with an SCM_RIGHTS adopt, is exercised now, and the raw aliasing that made M-4's ordering load-bearing is gone. Windows still aliases (there is no Adopt there; the section travels by name) and now says so in place. SessionTest.TheInprocPeerGetsItsOwnMappingOfTheSameSharedMemory pins different fds, different virtual addresses, stores visible in both directions, and an owner unaffected by the peer's Close. The SessionTest fixture was rewired so each role drives its own mapping, which is the shape spawn has.

M-7 — fixed by taking the alternative, not by correcting the documents. The knob now names the ring and the segment is ring + one control page: SessionSegmentSizes is CmdRingBytes / StageRingBytes / ReplyBytes / EventRingBytes, and SegmentBytesForRing() is the one place the page is added. So SEG_CMD's ring is 8 MiB, MaxRecordBytes() is 4 MiB, and CONTRACT-P5 §5 and Config.h:471-473 are true as written — no edit to either of c0's files is needed, which is the better outcome since neither is mine to change. It also reclaims the 4 190 208 + 129 920 bytes that were mapped and unreachable. SegmentRef.sizeBytes announces the mapping size (8 MiB + 4096), which is what a spawn peer must mmap; the four numbers a reader recognises are the ring sizes, which is what the knobs name. My §2.1 above is superseded by this section and its citation of ProtocolSmokeTest.cpp:72 was wrong.

M-8 — fixed. AdvanceMonotonic on a backwards move is now Fatal{ProtocolCorruption, "watermark"} rather than an MGLOG_E and a return, because the logged version left every later advance a no-op and every WaitForApplied(kWaitForever) blocked for ever — a hang with one ERROR line. SessionTestDeath.AWatermarkThatMovesBackwardsIsFatalRatherThanIgnored is the control. One consequence, handled at the one boundary where a stale argument is legitimate: SessionProducer::PublishAndNotify clamps its submittedSeq argument up to m_lastPublishedSeq before publishing, because republishing an older bound (teardown does exactly that) is publishing LATE, which R-9 permits, and is not the same thing as a watermark moving back.

7.4 MINOR

# disposition
m-1 Fixed. m_owns = true moves before the create/map loop, so Close() on an in-loop failure really closes segments 0..n-1 as ShmSegment.h:66 promises.
m-2 Fixed. RoleMemory.h's comment now says INFO, matches the implementation, and names the grep tag MG_Remote memory[.
m-3 Fixed. The three post-attach failure paths in Accept call Close() rather than m_shm.Close(), so m_consumer / m_replies / m_events / m_transport are not left pointing into unmapped memory.
m-4 Fixed as far as it can be without an atomic header: the pool now REFUSES a geometry whose slots would not be 8-aligned, and a base that is not itself 8-aligned, so the 8-byte Seq the self-check reads is always naturally aligned. SessionTest.AReplyGeometryThatWouldMisalignASlotHeaderIsRefused. Making the stamp a real std::atomic_ref is P9's, together with the widening m-5 asks for.
m-5 Not fixed; written into the accounts. A drift of exactly slotCount lands on the same slot with a matching stamp. It cannot arise under R-1's depth-1 barrier, and the fix (a generation beside the seq) belongs with P9, which is what removes the barrier. Named in ReplySlot.h's header so it is not rediscovered.
m-6 Fixed by documentation, where the defect was. RetireThrough's comment now says IT IS MANDATORY and why — FreeBytes() reclaims against retiredTail only, so an apply loop that never calls it wedges the producer on the first full ring. v1 writes that loop.
m-7 Fixed. ReplySlotPool::m_size and ClientSession::m_caps are gone; ClientSession reads MG_Config::Ipc through two #if MOBILEGL_BUILD_DISAGGREGATED helpers, the shape ServerSession already used.

7.5 QUESTION

q-1 — changed. SessionProducer::LastPublishedSeq() is the producer's own count and teardown's drain uses it instead of RingControl::submittedSeq, which Ring.h:72-77 explicitly permits to lag. Under MOBILEGL_IPC_VERB_BARRIER=0 the two differ and the old drain would have under-waited and freed an emitter-owned var-tail while a record still named it. SessionTest.TheProducerRemembersWhatItPublishedEvenIfTheWatermarkLags.

q-2 — changed. SessionConsumer::CompleteFrame / ReturnPresentCredit advance and ring; ServerSession's two methods delegate to them. The free functions in namespace Watermark stay advance-only and now say so in the header, because the advance and the doorbell are two separate stores and only the pair is a wakeup.

q-3 — changed. ServerSession::PublishEvents() is the sanctioned path and picks the bell itself; EventRingProducer::PublishAndNotify's two-argument form stays for the test that drives the ring directly, with a header line saying to prefer the session's.

7.6 What fix round 1 changed in the accounts

  • SetConsumedSubsystems / SetCapabilityBits are now blocking for v1, in the literal sense: a server that publishes a snapshot without calling both aborts. That is deliberate and is the whole of B-1's fix. v1 should call them where it registers the backend.
  • The record cap is 4 MiB again, so CONTRACT-P5 §5's arithmetic is the one to size against and the correction I asked for in §4.1 is withdrawn. §4.2/§4.3 (no carrier for CallMask, none for the server's BackendType) still stand.
  • RetireThrough is mandatory for whoever writes the apply loop, and RetireBorrowedUpTo(cursor) is how a borrowed slot comes back once completedFrameSerial passes it. Nothing sets kRecBorrowSlot yet.
  • The duplication noted in §5 (ReceiveEnvelope / ParseEnvelope / FatalAbiMismatch in both session .cpps) is unchanged and still worth folding into whatever control-plane helper P6 needs.

8. Fix round 2 — w1's SEG_STAGE ruling, and the flag-space collisions

Commit 69cf5a0c (branch total 5175f9cc..69cf5a0c, 10 commits). Something did need to change.

8.1 Who owns the stage cursors now: NOBODY, and that is now pinned

The integrator's first question answers clean: no RingConsumer is or ever was constructed over RingCursorSet::Stage anywhere in ClientSession, ServerSession or the test fixture. The second question did not: I was constructing a stage RingProducer, held by SessionProducer, published by PublishAndNotify and waited on by WaitForStageSpace. With w1's encoder owning staging, that is the half-wiring the integrator warned about, and it is not merely dead — it is a guaranteed hang: the producer publishes stageHead, nothing advances stageAppliedTail or stageRetiredTail, so FreeBytes() reaches 0 the first time the head laps the capacity and never recovers, and WaitForStageSpace blocks for ever after the first 32 MiB of staging.

Removed: SessionProducer::m_stage, its Attach parameter, Stage(), WaitForStageSpace() and the stage Publish(); ClientSession::m_stage; the fixture's stageProducer. PipeWireEncoder's stage argument is now nullptr — c0's signature predates w1's ruling, the encoder reaches SEG_STAGE through the SegmentTable view, and nullptr is the honest value. Flagged for w1 / the integrator: if w1's encoder still wants that parameter, the fix is to delete it from the signature, not to hand it a producer over a triple nobody consumes.

RingControl's stage triple is kept and documented, not removed: RingCursorSet, Ring.cpp's three cursor accessors and RingTest's fixture are all written against a two-triple page, and P8/P11's shadow and adopt segments are the ring-shaped users it was reserved for. Ring.h now carries a paragraph saying it is dead in P5 on purpose, who owns staging instead, and what the middle state costs — and SessionTest.TheStageCursorTripleStaysDeadAcrossAWholeSession drives 500 records through SEG_CMD and asserts all three stage cursors are still 0 while cmdHead and retiredSeq moved. That is the difference between "on purpose" and "forgotten": one of them is a test.

retiredSeq's text was already right and needed no change — Ring.h's watermark table, the Watermark::AdvanceRetired comment and SessionTest.RetiredSeqMayTrailTheApplyButCanNeverOvertakeIt all say the staging allocator reclaims behind retiredSeq, which is exactly w1's allocator. What was wrong is now fixed: three places called SEG_STAGE a ring (SessionRings.h's header block, ShmSegment.cpp's DeriveViews, one SessionTest comment). SessionSegmentSizes::StageRingBytes → StageBytes, SessionSegments::StageCapacity() → StageBytes(), and the power-of-two rounding is gone — it was a ring requirement, and keeping it would have silently turned an operator's MOBILEGL_IPC_STAGE_MB=24 into 16, which is M-2's class of defect one knob along.

8.2 The flag-space collisions

RingRecordHeader::flags is read in exactly two places of mine, and there are three colliding bits, not one — w1's kReplySlot ≡ kRecVarTail is the least dangerous of them:

bit MGPipeCallFlags RingRecordFlags consequence if a call's flags reach the header
2 kVarTail kRecPad worst: Pop skipped every var-tail record as a wrap filler, silently, record lost, nothing logged
3 kHostSpan kRecBorrowSlot my ApplyOne stops reclaiming ring bytes behind it — the producer wedges on the first full ring
4 kReplySlot kRecVarTail a blocking call reads as having a tail it does not have

Translating is the encoder's job, but neither of my two readers now depends on it:

  • RingConsumer::Pop requires a filler to carry kRecPad AND kind == kRingPadRecordKind. A genuine filler always does (Reserve writes it); a call record always carries a real opcode, because the catalogue starts at 1. One comparison turns a lost record into a delivered one. SessionTest.ARecordWearingThePadBitIsDeliveredRatherThanEatenAsAFiller.
  • SessionConsumer counts and names every kRecBorrowSlot sighting (BorrowedRecordsSeen(), one MGLOG_E on the first). P5 implements no borrowed slots and is ruled to produce no host spans either, so the bit arriving is the collision; the conservative arm is still taken, but a producer that then wedges has a line saying why. SessionTest.ABorrowSlotSightingIsCountedRatherThanJustActedOn.
  • Four static_asserts in ServerSession.cpp — the nearest .cpp that legally sees both headers, since nothing under Transport/ may reach MobileGL/Includes.h — pin all three collisions and the two bits that agree, so a renumber of either enum is a build break rather than news. Ring.h's RingRecordFlags carries the table in prose.

8.3 Reply-pool sizing from MGPipeCallFlagsFor — not yet, by instruction

kDefaultReplySlotCount is still 8 and is still justified by depth, not by a count of kReplySlot rows (§2.4: while the verb barrier holds the in-flight depth is one, so fewer slots and bigger replies is the right trade). Nothing in my pool sizing hard-codes which calls have a reply, so there is no false derivation to remove. I will switch the sizing to MGPipeCallFlagsFor when the integrator says c0's four Bool acceptance rows have landed.

8.4 Acceptance, re-run in full at 69cf5a0c

Every number from §7.1 reproduces, with the two test counts up: four builds rc=0; G1 .text 10806323 -> 10806323 (+0), 27811 -> 27811, 0/0/0/0; ctest -L unit 1785 / 1785 / 1785 and split 1870 (1842 + 28); integration-gpu in build-push under MOBILEGL_TRANSPORT=monolith 1117 / 1117 with the ctest -N name set identical to the 2902-name baseline; gen_protocol.py --check clean; gen_pipe.py --check / --self-test clean; purity 4 probes / 0 problems; nm pull 0, split 282. Flake: the whole Wire lane (85 tests) at -j 8 × 8 reps, 0 failing reps; SessionTest --gtest_repeat=30, 28 × 30, rc=0. RingTest is unmoved at 21/21, which is the check that mattered for the Pop change.