MobileGL/docs/archive/notes/p5e/scout-S1.md

S1 — VAO / vertex input / index, under run-ahead

Head 2fde7034. Paths under MobileGL/. Arm assumed throughout: MOBILEGL_PIPE_PUSH with bits 7 and 8 set (ResourceSubsystemEnabled() / VertexInputSubsystemEnabled(), Managers.h:911-918), EsprytSlotTablesEnabled(), Transport != Monolith. The E note's a.1 is the starting map; the site set below is re-resolved and differs from it in three places, marked [new].

1. The live reads of this family, at 2fde7034

Legend as the E note's: live = frontend object/array dereference; id = GetLifetimeId() + a probe of MGPipeSlots(); mint = a write into the client allocator; rec = record arm. "hit" / "miss" is the memo state of the site's own memo.

#	site	what it dereferences	kind	when
1	DirectGLES.cpp:4772 ResolveVaoTwin(currentVAO) → :1617-1618	g_backendVertexArrayObjects.Find(vao.get()) → SlotTables.h:411-414 → HandleOf :436-449: stateObj->GetLifetimeId(), then the table's one-entry front memo (:444) or MGPipeSlots().FindByLifetimeId (:445-446); a miss takes GetOrCreate(vao) :215-266, which is MGPipeSlots().Acquire :247-248	live + id (mint on a first sight)	every draw; the GetLifetimeId() read runs on the memo hit too
2	DirectGLES.cpp:4775	currentVAO->GetConfigVersion()	live	every draw, unconditional
3	SyncVaoAttributeBuffersByHandle memo hit, :733	IsBufferDrawCleanByHandle(entry.handle, entry.resource, entry.frontend); under a transport Managers.cpp:3148-3150 does NOT dereference frontend	none (handle-only)	per distinct VBO, only when memo->vboCleanEpoch != bufferEpoch (:730)
4	same, dirty repair :735-736	currentVAOObject->GetAttribute(entry.attribIndex).Buffer → EnsureBufferResource(obj) → HandleOfBuffer (Managers.cpp:3444, :2922-2941, scope :2938)	live + id	on a dirty probe
5	same, memo miss :744-772	GetAllAttributes() (32 VertexAttribute, each a SharedPtr<BufferObject> + 10 scalars), attrib.Buffer, EnsureBufferResource(bufferObject) :764, HandleOfBuffer(bufferKey) :769	live + id (twice per distinct buffer)	memo key miss
6	IBO arm :896-925	currentVAOObject->GetIndexBufferBindingSlot().GetBoundObject() :897; HandleOfBuffer(possibleIBO.get()) :907; EnsureBufferResource(possibleIBO) :917	live + id	every indexed draw; :897 and :907 run on the hit too
7	SyncCurrentVAO :1641-1652 → SyncToBackend (Managers.cpp:4881-4892) → SyncToBackendFromApplier (:5160-5350)	nothing frontend — every field is st.BoundVertexElements / rec->Attributes[] / st.VertexBuffers[] / st.IndexBuffer.Res (:5220-5345)	rec	every draw
8	SyncCurrentVertexAttributeValues :1662-1719	MGB_CTX->GetBoundVertexArray() :1668; program->GetActiveAttributeLocationMask() :1672 (S4); vao->GetConfigVersion() :1683; miss: vao->GetAttribute(location).Enabled :1688; program->GetAttribType(location) :1701,:1715 (S4)	live	:1668,:1672,:1683 every draw with a program; :1688 on memo miss
9	:1700	MGB_CTX->GetCurrentVertexAttribute(location)	rec (set_vertex_attrib_defaults, RECORD_SUPPLIED — PipeFill.cpp:2304, :2594-2660)	pending-mask draws only
10	DrawArrays :6724-6735 (scope :6729), MultiDrawArrays :6767-6782 (scope :6775)	g_backendVertexArrayObjects.Find(currentVAO.get()), then SyncClientSideAttributesForDrawArrays(currentVAO, first, count) (Managers.cpp:5364-5468): GetAllAttributes(), and attrib.Offset dereferenced as a raw CLIENT POINTER :5382,:5430	live + id + client memory	every glDrawArrays / glMultiDrawArrays with a VAO bound
11	[new] BoundElementArrayBuffer() :6447-6452 / BoundElementArrayBufferId() :6456-6461, reached from ScopedRestartIndexSubstitution :6591, :6687	MGB_CTX->GetBoundVertexArray(), GetIndexBufferBindingSlot().GetBoundObject(), EnsureBufferResource(ibo) → HandleOfBuffer	live + id	every DrawElements-family call whose ResolveRestartSubstitution (:6464-6480) is not None; also MultiDraw.cpp:45,:905
12	[new] :1646 g_backendVertexArrayObjects.CollectGarbageIfNeeded()	no-op on the slot arm (Managers.h:558-563)	—	—

EnsureBufferResourceForHandle (Managers.cpp:3193-3435) holds the SharedPtr but reads nothing from it under a transport: the shadow base is resource->hostBytes (:3208-3222), SyncPersistentMappedRange is skipped (:3334-3341), definedness comes from the descriptor plus staged coverage (:3376-3385). (nullptr, h) is already the live shape at DirectGLES.cpp:953.

Scope sites this family owns: DirectGLES.cpp:1609, :6729, :6775 — 3 of the 20; plus every HandleOfBuffer reached from rows 4, 5, 6, 11 (Managers.cpp:2938).

2. What the records and the applier already carry

• create_vertex_elements / bind_vertex_elements / delete_vertex_elements — PipeCalls.def:151-153, all kCtxCso, therefore already published without a wait (ClientSession.cpp:915-922). Emitter VertexInputEmit.h:158-189 (EmitVertexElements) and :352-397 (EmitCreate, all 32 attributes and all 32 binding points, MGPVertexAttribWire MGPipeTypes.h:497-508). Applier record MGPipeVertexElementsRecord (PipeApply.h:389-400): Attributes[32], BindingPoints[32], server-owned ContentSerial bumped on every applied create, including a re-create on the same handle.
• set_vertex_buffers — PipeCalls.def:168 (kCtxState, kVarTail), emitter VertexInputEmit.h:200-247, record MGPVertexBuffers / MGPVertexBuffer (MGPipeTypes.h:805-836). Applier: VertexBuffers[32], VertexBufferStart/Count, VertexFetchBaseInstance, VertexBuffersSerial (PipeApply.h:598-616), bumped at PipeApply.cpp:2376-2377.
• set_index_buffer — PipeCalls.def:169, emitter VertexInputEmit.h:255-270, record MGPIndexBuffer (MGPipeTypes.h:839-845). Applier IndexBuffer + IndexBufferSerial (PipeApply.h:620-622), bumped at PipeApply.cpp:2391-2392.
• set_vertex_attrib_defaults — PipeCalls.def:177, PipeFill.cpp:2594-2660; all three views verbatim since P5c rv, so GetCurrentVertexAttribute is RECORD_SUPPLIED.
• Client-side dirty rules: bit 8 NewVertexElements = mix(lifetimeId, configVersion) (Tracker.h:294-298); bit 9 NewVertexBuffers = mix(mix(AnyVaoAttributeGeneration, vaoIdentity), pendingBaseInstance) (Tracker.h:542-543); bit 10 NewIndexBuffer = mix(vaoIdentity, mix(indexSlotVersion, boundLifetimeId)) (Tracker.h:558-566). All three emit at the validate point, order elements → buffers → index (PipeFill.cpp:3225-3233).
• Twin lifetime, already handle-shaped: ReleaseTwinsForWireObjectDeath(handle, VertexElementsCso) → g_backendVertexArrayObjects.ReleaseByHandle(handle) (Managers.cpp:352-353), plus the client's own MGPipeEmitVertexElementsDestroyAndFree (PipeFill.cpp:1050) and NoteRecordDestroyed (VertexInputEmit.h:319-329).
• SyncToBackendFromApplier (Managers.cpp:5160-5350) is the existence proof: the whole driver-VAO configuration is already produced from records with zero frontend reads, and its dirty gate is three server-owned serials plus the backend's own g_bufferBackendIdGeneration.

So the records cover the family in full except client-memory vertex arrays (§7).

3. The gap — what does not exist yet

G1. Nothing. For rows 1–9 and 11 there is no missing field: every value the server needs is already in MGPipeApplierState. This family's P5e work is a re-key and a re-source, not a record addition. That is the headline and it is what makes S1 cheap next to S2/S3/S5.

G2. Client-memory vertex arrays have no wire form. EmitVertexBuffers publishes Res = kMGPipeNullHandle for them by design (VertexInputEmit.h:196-199, :211-213) and the SERVER uploads the bytes by dereferencing the client pointer (Managers.cpp:5372-5466). The brief's "client-side arrays are already refused under split" is NOT confirmed — they are not refused. EmitTables.cpp refuses only client INDEX arrays for the multi-draw forms (:651 CLIENT_INDICES) and CLIENT_COMMANDS / UNBOUND_PARAMETER (:682,:685); nothing refuses a client vertex array. Options, in P5e order:

• (a) refuse, Fatal{UnmigratedVerb, "DrawArrays+CLIENT_ARRAYS"} raised on the GL thread in EmitDrawRecord's array arm, gated on the run-ahead caps bit so the lockstep arm is unchanged;
• (b) stage, a new tail on draw_vbo shaped exactly like kDrawHasUserIndices (MGPipeTypes.h:1430, codec PipeWireCodec.cpp:1985-1998): a per-attribute {BindingIndex, MGHostSpan} array staged whole from the draw's known [first, first+count) range. This is P8's HostResolve.cpp territory and is the honest answer. P5e should take (a) and name (b) as P8's, because (a) is two lines and makes visible a path that was never split-clean; (b) is a record and belongs with the index-array flattening it mirrors.

G3. One pin, not a field. The twin key below is only 1:1 while the vertex-elements CSO stays IDENTITY-addressed (VertexInputEmit.h:19-28, D-G1). If P7 ever content-addresses it, two frontend VAOs share a handle — and therefore one driver VAO name and its 64 scratch buffer ids (Managers.h:1204-1300). P5e must state that as a requirement of the key and pin it in a test, not leave it as a performance remark.

4. The retirement design

4.1 The twin key is st.BoundVertexElements. The handle ResolveVaoTwin resolves today is MGPipeSlots().Acquire(VertexElementsCso, vao->GetLifetimeId()) (SlotTables.h:247-248) — the SAME handle EmitVertexElements mints (VertexInputEmit.h:172) and the applier stores as BoundVertexElements (PipeApply.h:594). So:

BackendVertexArrayObject* ResolveVaoTwinByHandle() {          // split arm, no scope, no allocator
    const MGPipeHandle cso = MGPipeApplier().BoundVertexElements;
    if (MGPipeHandleIsNull(cso)) return nullptr;              // == "no VAO bound"
    auto& twin = g_backendVertexArrayObjects.GetOrCreate(cso); // SlotTables.h:294-340
    if (!twin) twin = MakeShared<BackendVertexArrayObject>();
    return twin.get();
}

PrepareForDraw:4770-4772 stops reading GetBoundVertexArray(); the null arm at :4816-4821 (BindBackendVAOId(0)) is reached from the null handle instead. No behaviour change: one driver VAO per frontend VAO, exactly as now. GetOrCreate(handle)'s backward-generation refusal (SlotTables.h:331-339) is the ABA answer, and ReleaseByHandle (SlotTables.h:394-408) the death answer — both already written and already called from Managers.cpp:352.

4.2 The buffer walk reads the applier, not the VAO. SyncVaoAttributeBuffersByHandle (:699-790) keeps its shape and loses its frontend argument:

• miss walk :744-772 → iterate i in [st.VertexBufferStart, +st.VertexBufferCount), skip MGPipeHandleIsNull(st.VertexBuffers[i].Res), dedupe on Res (a {slot,gen} compare replaces the pointer compare at :754-760), EnsureBufferResourceForHandle(nullptr, Res);
• entry.handle = Res directly — HandleOfBuffer at :769 deleted;
• dirty repair :735-736 → EnsureBufferResourceForHandle(nullptr, entry.handle);
• probe :733 → IsBufferDrawCleanByHandle(entry.handle, entry.resource, nullptr); the frontend parameter is already dead under a transport (Managers.cpp:3148-3150) and ResolvedDrawBuffers::Entry::frontend (Managers.h:1223) leaves the split arm, which also retires the dangling raw pointer the struct's own note warns about (:1224-1239);
• attribIndex (Managers.h:1241) becomes the BINDING index, kept only for diagnostics. Memo key is unchanged and already server-owned: {elementsHandle, elementsSerial, buffersSerial} (Managers.h:1263-1265), i.e. {BoundVertexElements, rec->ContentSerial, VertexBuffersSerial}.

4.3 The IBO arm. :896-925 → st.IndexBuffer.Res and st.IndexBufferSerial. The identity compare memo->iboHandle == iboHandle stays (the handle is now read from the applier, not probed); the extra HandleOfBuffer at :907 goes. Add iboSerial to the memo so a rebind that moved the serial re-ensures without a frontend read — the client shutter (Tracker.h:558-566) already fires on the slot version AND the bound lifetime id, so a redundant rebind is correctly suppressed.

4.4 The two config-version reads. :4775 is DEAD on this arm already (SyncNeccessaryBuffers uses vaoConfigVersion only in the legacy branch, :831-833): delete it under the transport check. :1683 is the key of PendingAttribValueMask (Managers.h:1286-1290); re-key it on {elementsHandle, elementsSerial, activeMask} and read rec->Attributes[location].Enabled (PipeApply.h:394) at :1688. Every configuration change re-creates the record and bumps ContentSerial (PipeApply.h:396-399), so the key is strictly stronger than the wrapping Uint16.

4.5 Clean / needs-re-sync, answered from server-owned serials only. After 4.2–4.4 the family's four questions are: BoundVertexElements + ContentSerial (configuration), VertexBuffersSerial (the buffer set), IndexBufferSerial (the element slot), CurrentBufferMutationEpoch() + syncedChangeSerial vs record->Serial (buffer content, Managers.cpp:3147-3153). The epoch is a backend atomic (Managers.cpp:794) bumped only from backend bodies, i.e. apply-thread memory under a transport — that must be pinned, not assumed (§7).

4.6 Scopes. DirectGLES.cpp:1609, :6729, :6775 are deleted with the sites they wrap; the HandleOfBuffer scope entries this family reaches (Managers.cpp:2938) lose their last vertex-input caller. After that, GetBoundVertexArray (FieldOwnership.def:72) has no Espryt draw-path reader left except the two client-array arms and the restart substitution (§4.7), so its row's retiring phase moves from "P8" to "P5e (Espryt)".

4.7 The restart substitution. BoundElementArrayBuffer() (:6447-6452) → st.IndexBuffer.Res; BoundElementArrayBufferId() (:6456-6461) → FindBufferResourceForHandle(st.IndexBuffer.Res) (resolve only, exactly as SyncToBackendFromApplier:5330 does). :6591's read in the substitution body takes the same.

5. Monolith / G1

Every edit above is inside an existing #if MOBILEGL_PIPE_PUSH arm that is already selected by VertexInputSubsystemEnabled() / ResourceSubsystemEnabled() (Managers.h:911-918) — the functions touched (SyncVaoAttributeBuffersByHandle, SyncToBackendFromApplier, BindAttributeBufferByHandle) do not exist in the pull build at all. ResolveVaoTwin is the one exception: its three arms (:1611-1622 slot, :1623-1636 legacy memo) stay, and the handle arm is added as a fourth guarded by Transport != Monolith, so MOBILEGL_PIPE_PUSH under Transport=monolith keeps Find(vao.get()) byte for byte. ResolvedDrawBuffers's frontend and configVersion members stay declared for the legacy arm (they are already outside the MOBILEGL_PIPE_PUSH block at Managers.h:1223,:1251), so no mangled name and no struct layout the pull build sees is changed. G2/G14: no new name enters the pull build's symbol set; the new ResolveVaoTwinByHandle is MOBILEGL_BUILD_DISAGGREGATED-only.

6. Red-once

1. Twin key. SanityTest.cpp:4083-4084 already pins that VertexElementsCso resolves through the handle arm. Add: with the twin keyed on BoundVertexElements, revert ResolveVaoTwin to Find(vao.get()) with the scope at :1609 removed → Fatal{RoleViolation, "MGPipeSlots"} naming HandleOf (SlotAllocator.cpp:22-38). The scope deletion is what makes the revert loud.
2. The buffer walk. New MG_Test case beside VertexInputEmit: publish set_vertex_buffers for buffers A,B, then repoint the frontend VAO's attribute 0 at C WITHOUT re-emitting, then run the sync — the walk must ensure A,B. Revert 4.2 and it ensures C; the case names st.VertexBuffers.
3. The index arm. Same shape on set_index_buffer / st.IndexBuffer.Res, with the frontend element slot rebound after publish. Revert 4.3 → red naming IndexBuffer.Res.
4. The attrib-value memo. Revert 4.4's key to GetConfigVersion() under run-ahead and the strict lane aborts Fatal{UnmigratedPipeInput, "GetBoundVertexArray@draw_vbo"} (PipeInputs.h:137-170, MGPipeStickyForwardPull) — this is P5e-3's detector doing the work.
5. Client arrays. With §3 G2 (a) in place: a glDrawArrays with an enabled client-memory attribute under run-ahead is a named refusal, and reverting the refusal is red by DoublePrecisionScenario / a new client-array scenario under integration-split-strict.
6. Integration, unchanged suites that must stay green under run-ahead: VertexAttribBindingScenario, VertexArrayEnableDisableScenario, PrimitiveRestartScenario, ResidentIndexScenario, MultiDrawScenario, DrawParametersScenario, DoublePrecisionScenario, HandleRecycleScenario, ObjectSubsystemControlScenario (the 0x0ff / 0x17f A/B at Managers.h:897-905 must keep its verdicts).

7. Risks and unsettled

• R1 (blocking, owned by S6/S8). Client-memory vertex arrays, §3 G2. Until refused or staged, the apply thread dereferences a raw client pointer per glDrawArrays and run-ahead makes the bytes movable. It also GENERATES and fills driver buffers on the apply thread (Managers.cpp:5392-5399,:5455-5457) — harmless, but it means SyncClientSideAttributesForDrawArrays cannot simply be deleted.
• R2. CurrentBufferMutationEpoch() (Managers.cpp:794, Managers.h's site enumeration) is the only non-serial input left in 4.5. It is an atomic and every bump found is in a backend body, but P5e must pin "no GL-thread bump under a transport" — a client-side bump would make the memo's clean stamp a cross-thread read.
• R3. SyncCurrentVertexAttributeValues cannot go run-ahead clean on S1's work alone: :1672, :1701, :1715 read the frontend program. S1's edits are a no-op for safety until S4 lands. Sequence S4's program twin before or with this function's edit.
• R4. The set_vertex_buffers window: Count is "highest ENABLED attribute + 1" (VertexInputEmit.h:203-207) while create_vertex_elements carries all 32 (VertexInputEmit.h:352-366). An attribute enabled in the record but outside the window resolves VertexBufferForAttributeIndex == nullptr (Managers.cpp:4795-4809) and is skipped at :5262. Unreachable today because both walks read the same Enabled bits in the same validate step; under run-ahead they still do (both are client-side, same step) — but it is the same class as S2's caveat A8 and should be pinned by a test rather than argued.
• R5. EnsureBufferResourceForHandle's hostBytes refresh (Managers.cpp:3370) is a self-assignment under a transport (:3217-3220 returns resource->hostBytes). Passing nullptr changes nothing — confirmed by reading, not measured. The fp64 narrowing (SyncFloat64AttributeAsFloat32ByHandle) reads resource->hostBytes, i.e. the server staged store, and is already server-owned.
• R6. g_bufferBackendIdGeneration (Managers.cpp:5172-5174) and the reset rule MGPipeApplierReset must ADVANCE VertexBuffersSerial/IndexBufferSerial rather than zero them — the long note at Managers.cpp:5176-5191 says the twin's whole gate depends on it. Under run-ahead an applier_reset is a waited control record (P5e-2), so this holds; if any package makes applier_reset fire-and-forget, this gate breaks first.
• R7, not settled. Whether ResolvedDrawBuffers should survive at all once the walk is over st.VertexBuffers[Start..+Count): that array is already a compact, deduped, handle-keyed list bounded by Count (1–3 entries on the Minecraft workload, not 32 cold slots). The memo may be pure cost after 4.2. Measure before keeping it.