MobileGL/docs/Disaggregated/notes/p5f/fc-contract-draft.md

fc — 控制面帧契约草稿（P5f 包 fc；CONTRACT-P5F.md 本体留给集成收口）

Status: DRAFT, landed in code by package fc on branch p5f/fc. Authority once integrated: this feeds CONTRACT-P5F.md. Until then it supplements CONTRACT-P5C (audit row G4, discharged here) and CONTRACT-P5E §2.5 (the wait-before-forwarder discipline, unchanged), and it answers the control-plane rows of docs/Disaggregated/P6-CONTRACT-DRAFT.md §4 ahead of schedule. Code anchors: MobileGL/MG_Remote/Server/SurfaceControlFrame.h (the frame), MobileGL/MG_Remote/Protocol/SurfaceOpCodec.{h,cpp} (the wire codec and the named refusals), MobileGL/MG_Remote/Server/ServerLoop.cpp (RunSurfaceControlFrame / ApplySurfaceControlFrame).

---

1. Ownership

1. A SurfaceControlFrame is a value. The poster fills the request fields; ownership of the slot's content passes to the channel at publish; the dispatch on the apply thread fills the reply half (ok, eglMajor, eglMinor) into the same value; the poster's copy-out happens after the blocking handshake returns. No field is a pointer and none may become one — the exhaustive constexpr structured binding in SurfaceControlFrame.h checks every member as an integer or enum. Adding a member without extending the binding fails compilation; changing a checked member to a pointer fails its static assertion. Trivially-copyable / standard-layout remain separate copyability checks: neither trait rejects pointers.
2. An unnumbered local request (seq == 0) is numbered by RunSurfaceControlFrame, from 1 per session. An already numbered wire request retains its client-minted sequence through dispatch and reply (P6-CONTRACT-DRAFT table 0); the server never renumbers it.
3. display / surface / readSurface / context are Uint64 tokens. Inproc they are the client's EGL handle values bit-cast — legal only because both roles share a process and a driver, and the N-3 tuple bookkeeping compares them by value. Under spawn they are client-minted dense tokens (P6-CONTRACT-DRAFT table 0, unchanged). No code may dereference a token as a pointer on a path a non-inproc transport can reach.
4. windowBackend + nativeToken + width/height carry a WindowHandle as values. The frame names the backend enum, never the wire's WindowKind; the two enums meet only inside SurfaceOpCodec.cpp's explicit tables (Surfaceless/Pbuffer are surface shapes and answer "no backend" there). A nativeToken whose backend is Android is an ANativeWindow* — an address in the client's process — and may never cross (§3.5). MetalLayer carries a CAMetalLayer* and has the same restriction.

2. Ordering

1. The channel keeps its P5 semantics: one blocking slot, m_callerMutex serialising posters, pumped by the apply thread between drain batches, publish-then-ring. Frames are FIFO against each other; they are NOT ordered against SEG_CMD records by the channel itself.
2. The client-side discipline that orders frames against records is unchanged and remains mandatory under spawn: WaitForApplyBeforeEglForwarder waits appliedSeq to LastPublishedSeq before every forwarder (CONTRACT-P5E §2.5), because the channel is pumped between drain batches and a control frame would otherwise overtake in-flight records.
3. All twelve ops stay blocking in fc, including the three f0-egl §4.3 marked relaxable (SetSwapInterval, ReleaseSurface, SetWindowHandle). Relaxing them to fire-and-forget is a P6 decision and must preserve: a SetWindowHandle is in effect before any later CreateWindowSurface (one ordered channel suffices), and ReleaseResources NEVER relaxes — MobileGL::Destroy() walks on the moment it answers (ServerLoop.h's header note).
4. Re-entrancy is unchanged: a post from the apply thread dispatches inline (the ~BackendObject_DirectGLES → ReleaseEGLResources path). This is thread semantics, not wire semantics; under spawn the destructor path runs server-side natively and never posts.

3. Error semantics

1. Loop down, backend alive → Fatal{ApplyThreadNotRunning} (M-7, unchanged).
2. Loop down, no backend → MOBILEGL_ERR_NOT_INITIALIZED, nothing runs on the caller (C2, unchanged).
3. Backend null at dispatch → MOBILEGL_ERR_NOT_INITIALIZED with ok=false; the forwarder's answer is the old false/void-drop, unchanged.
4. Successful void operations (SetSwapInterval, ReleaseSurface, ReleaseResources, SetWindowHandle) reply ok=true after completing on the apply thread; a null backend replies ok=false. The wire therefore preserves the success/failure distinction even though the inproc forwarder returns void.
5. Wire entry (ServerApplyWireSurfaceOp, the future P6 control pump's entry point; P5f drives it from tests only): a decode failure is Fatal{ProtocolCorruption, "SurfaceOp"}, never a dropped frame (a dropped control frame is a client waiting on a reply that never comes); a decoded WindowKind::AndroidNativeWindow is Fatal{UnmigratedSurface, "AndroidNativeWindow@P12"} — the window kind is legal schema, the token is the part that means nothing in the server's process, and real window arrival is P12. A decoded MetalLayer is similarly Fatal{UnmigratedSurface, "MetalLayer@P12"}, because its CAMetalLayer* also belongs to the client process. Inproc-only kinds (InitCapabilitiesInprocOnly, SwapBuffersInprocOnly, InitWindowSurfaceInprocOnly, ProbeForTesting) cannot arrive: the encoder refuses them (SurfaceWireError::InprocOnlyOpOnTheWire).
6. A frame that reaches the inproc dispatch with kind == None or a kind the switch does not know is Fatal{ProtocolCorruption, "SurfaceOp.kind"}; a windowBackend tag outside the enum is Fatal{ProtocolCorruption, "SurfaceOp.windowBackend"}. Inproc these are corruption shapes, not bad input — same discipline as the ring's header check.

4. Reply carriers — and the deliberate non-use of SurfaceReply.defaultFb

1. The default framebuffer's shape already crosses as kEventSurfaceChanged on SEG_EVENT (P5c ev), and the client drains it at the RPC return (BackendObject_Remote.cpp's create/resize arms). fc rules that SurfaceReply.defaultFb stays unset: two spellings of one fact is how the two sides come to disagree about it (the CapsSnapshot deprecated-fields lesson, protocol.fbs). Enabling it later is a schema amendment, not a silent flip.
2. The caps republish side effects are unchanged and are server-spontaneous frames on the wire: a real bind under MakeCurrent republishes (R-12 arm (a)); InitCapabilities publishes. The client's absorption point — pump the control plane after the RPC returns — is the same in both worlds: "after this op's reply, before the next op" is a total order the client can rely on.

5. What fc deliberately did NOT do

• No transport: no socket, no spawn pump, no client-minted token table (the frame fields are token-width already, so P6 is transport-only here).
• The two dead forwarders (ServerSwapEGLBuffers, ServerInitWindowSurface) and ServerInitCapabilities were NOT given wire ops (f0-egl F8/§4.2): they ride the inproc channel as inproc-only kinds because the function-pointer mailbox is gone entirely, and G14 forbids deleting their pinning tests.
• Blocking semantics, the shadow, the doorbell order and the C2 exit block: unchanged.