[Fix, Test] (Espryt): drive a unit's sampler through the CSO's own twin on the handle arm - the record arm looked a content-addressed handle up in the identity-keyed registry and could never hit, so only the pre-handle program pass ever put a glBindSampler'd object on the driver (P4a seam F-4)

.github/workflows/apk.yml

@@ -6,6 +6,10 @@ on:
       - dev
       - Feat/Backend-Direct-GLES
       - Feat/Backend-Direct-Vulkan
+      # TEMPORARY, remove before merging the MGPipe work into dev: the disaggregation
+      # branch runs the full lane on every push so a phase's landing is not gated on
+      # someone remembering to dispatch the workflow by hand.
+      - feat/disaggregated
   workflow_dispatch:
 
 jobs:
@@ -61,6 +65,8 @@ jobs:
         uses: android-actions/setup-android@v4
         with:
           accept-android-sdk-licenses: false
+          packages: platform-tools
+          cmdline-tools-version: 13114758
 
       - name: Accept Android SDK licenses
         run: yes | sdkmanager --licenses >/dev/null
@@ -293,6 +299,8 @@ jobs:
         uses: android-actions/setup-android@v4
         with:
           accept-android-sdk-licenses: false
+          packages: platform-tools
+          cmdline-tools-version: 13114758
 
       - name: Accept Android SDK licenses
         run: yes | sdkmanager --licenses >/dev/null
@@ -368,6 +376,8 @@ jobs:
         uses: android-actions/setup-android@v4
         with:
           accept-android-sdk-licenses: false
+          packages: platform-tools
+          cmdline-tools-version: 13114758
 
       - name: Accept Android SDK licenses
         run: yes | sdkmanager --licenses >/dev/null

.gitmodules

@@ -34,3 +34,6 @@
 [submodule "include/ska"]
 	path = include/ska
 	url = https://github.com/MobileGL-Dev/flat_hash_map.git
+[submodule "3rdparty/flatbuffers"]
+	path = 3rdparty/flatbuffers
+	url = https://github.com/google/flatbuffers.git

MobileGL/ConfigLoader.cpp

@@ -7,6 +7,12 @@
 // End of Source File Header
 
 #include "Config.h"
+#if MOBILEGL_PIPE_PUSH
+// For kMGPipeSubsystemsMigratedAtP5e, the push build's PipePush default (the P2, P3a and P4a
+// constants beside it are the phase-by-phase controls, not the default). Push-only, so the
+// pull build's translation unit is unchanged.
+#include <MG_Pipe/MGPipe.h>
+#endif
 
 #include <cerrno>
 #include <cstdlib>
@@ -19,6 +25,15 @@ namespace MobileGL::MG_Config {
     // Zero/default-initialized at static-init time (all fields have constexpr-friendly
     // defaults), so it is safe to read even if MG_ConfigLoader::Init has not run yet.
     FeaturesTable Features;
+#if MOBILEGL_BUILD_DISAGGREGATED
+    // Same contract, and for the same reason: MG_Backend::Init() reads Transport, and a
+    // build order that put it before MG_ConfigLoader::Init() must see Monolith rather than
+    // a torn enum. Defined only here - in a pull build Config.h makes Transport a constexpr
+    // and there is nothing to define.
+    TransportMode Transport = TransportMode::Monolith;
+    String TransportEndpoint;
+    IpcTable Ipc;
+#endif
 } // namespace MobileGL::MG_Config
 
 namespace MobileGL::MG_ConfigLoader {
@@ -159,6 +174,38 @@ namespace MobileGL::MG_ConfigLoader {
         return static_cast<Uint32>(parsedValue);
     }
 
+    // Same contract as QueryEnvUint32, over 64 bits and accepting an explicit 0x prefix: the
+    // one consumer is a subsystem BITMASK, and a bitmask written in decimal is unreadable.
+    // Decimal otherwise - never strtoull's base 0, whose "leading zero means octal" rule
+    // silently read MOBILEGL_PIPE_PUSH=010 as 8 - and a '-' anywhere is rejected rather than
+    // wrapped, which strtoull would otherwise do without complaint (-1 -> every bit set).
+    inline Uint64 QueryEnvUint64(const String& key, Uint64 defaultValue) {
+        auto it = acceptedEnvVariablesMap->find(key);
+        if (it == acceptedEnvVariablesMap->end()) {
+            return defaultValue;
+        }
+
+        const String& value = it->second;
+        const char* text = value.c_str();
+        int base = 10;
+        if (value.size() > 2 && text[0] == '0' && (text[1] == 'x' || text[1] == 'X')) {
+            text += 2;
+            base = 16;
+        }
+        char* parseEnd = nullptr;
+        errno = 0;
+        const bool negative = value.find('-') != String::npos;
+        const unsigned long long parsedValue = negative ? 0 : std::strtoull(text, &parseEnd, base);
+        if (negative || parseEnd == text || *parseEnd != '\0' || errno == ERANGE) {
+            MGLOG_W("Config: Ignoring invalid env variable %s='%s'; expected a non-negative integer "
+                    "(decimal, or 0x-prefixed hexadecimal), using default %llu",
+                    key.c_str(), value.c_str(), static_cast<unsigned long long>(defaultValue));
+            return defaultValue;
+        }
+
+        return static_cast<Uint64>(parsedValue);
+    }
+
     inline void InitFeatures() {
         auto& features = MG_Config::Features;
         features.DisableTimerQuery = QueryEnvFlag("MOBILEGL_DISABLE_TIMERQUERY");
@@ -207,6 +254,40 @@ namespace MobileGL::MG_ConfigLoader {
         features.EsprytWidenPacked16Storage =
             QueryEnvQuirkOverride("MOBILEGL_ESPRYT_WIDEN_PACKED16_STORAGE");
         features.MagmaPrimGenQueryReroute = QueryEnvQuirkOverride("MOBILEGL_MAGMA_PRIMGEN_QUERY_REROUTE");
+        // MGPipe. Nothing here needs adding to an allow-list: InitializeAcceptedEnvVariables
+        // accepts every MOBILEGL_ / LIBGL_ prefixed variable in the environment, so a name
+        // that starts with MOBILEGL_ is visible to these queries by construction.
+#if MOBILEGL_PIPE_PUSH
+        // A push build with the knob unset runs every subsystem migrated so far, so the
+        // shipped path is the one the gates measure; MOBILEGL_PIPE_PUSH=0 in the
+        // environment is the all-subsystems-pull control that reproduces P1 exactly, and
+        // kMGPipeSubsystemsMigratedAtP3a (0x1ff) is the phase-by-phase control - P4a's four
+        // subsystems off, everything P3a landed still on.
+        features.PipePush = QueryEnvUint64("MOBILEGL_PIPE_PUSH", MG_Pipe::kMGPipeSubsystemsMigratedAtP5e);
+#else
+        // Meaningless in a pull build: there is nothing to push. Config.h documents 0 as
+        // "pull everything" and that stays literally true.
+        features.PipePush = QueryEnvUint64("MOBILEGL_PIPE_PUSH", 0);
+#endif
+        features.PipeVerify = QueryEnvFlag("MOBILEGL_PIPE_VERIFY");
+#if MOBILEGL_PIPE_PUSH
+        // Defaults ON: read as a tri-state so only an explicitly falsy value turns it off.
+        features.PipeVerifyFatal =
+            QueryEnvQuirkOverride("MOBILEGL_PIPE_VERIFY_FATAL") != MG_Config::QuirkOverride::ForceOff;
+        QueryEnvVariable("MOBILEGL_PIPE_VERIFY_CORRUPT", features.PipeVerifyCorrupt, "");
+        QueryEnvVariable("MOBILEGL_PIPE_POISON_OMIT", features.PipePoisonOmit, "");
+        features.PipeHandleAbaControl = QueryEnvFlag("MOBILEGL_PIPE_HANDLE_ABA_CONTROL");
+#endif
+        features.PipeStats = QueryEnvFlag("MOBILEGL_PIPE_STATS");
+        // Defaults ON, so the flag has to be read as a tri-state rather than as a plain
+        // truthy check: unset must keep the memos, and only an explicitly falsy value may
+        // drop them.
+        features.PipeLegacyMemos =
+            QueryEnvQuirkOverride("MOBILEGL_PIPE_LEGACY_MEMOS") != MG_Config::QuirkOverride::ForceOff;
+        features.PipeTexelRetainMb = QueryEnvUint32("MOBILEGL_PIPE_TEXEL_RETAIN_MB", 0, 0, 4096);
+        features.PipeIndexMirrorMb = QueryEnvUint32("MOBILEGL_PIPE_INDEX_MIRROR_MB", 64, 0, 4096);
+        features.PipeStatsPeriod = QueryEnvUint32("MOBILEGL_PIPE_STATS_PERIOD", 120, 1, 1000000);
+        QueryEnvVariable("MOBILEGL_PIPE_STATS_FILE", features.PipeStatsFile, "");
     }
 
     inline void InitBackendType() {
@@ -225,12 +306,128 @@ namespace MobileGL::MG_ConfigLoader {
 #undef ENTRY
     }
 
+#if MOBILEGL_BUILD_DISAGGREGATED
+    // MOBILEGL_TRANSPORT = monolith | inproc | spawn | unix:<path> | pipe:<name>
+    // (ARCHITECTURE.md:583). Shaped after InitBackendType above: an exact-name table, then
+    // one fallback that names what it did instead. The two prefixed forms are the only
+    // reason this is not literally that function's ENTRY macro.
+    //
+    // spawn / unix: / pipe: PARSE AND THEN REFUSE. They are P6's, and the refusal is NAMED
+    // rather than silent, because the failure this avoids is a P6 lane that set
+    // MOBILEGL_TRANSPORT=spawn, fell back to monolith, and went green on the wrong arm.
+    // The mode is left at Monolith so nothing half-initializes.
+    inline void InitTransport() {
+        String value;
+        QueryEnvVariable("MOBILEGL_TRANSPORT", value, "monolith");
+        String lowered = value;
+        std::transform(lowered.begin(), lowered.end(), lowered.begin(),
+                       [](unsigned char c) { return static_cast<char>(std::tolower(c)); });
+
+        MG_Config::TransportEndpoint.clear();
+        if (lowered.empty() || lowered == "monolith") {
+            MG_Config::Transport = MG_Config::TransportMode::Monolith;
+            return;
+        }
+        if (lowered == "inproc") {
+            MG_Config::Transport = MG_Config::TransportMode::InProcess;
+            MGLOG_I("Config: MOBILEGL_TRANSPORT=inproc - the MGPipe record stream crosses a real "
+                    "ring to an apply thread");
+            return;
+        }
+        // The three P6 forms. Recognised precisely, so the diagnostic can say "not yet"
+        // rather than "unknown", which are different bugs on the operator's side.
+        if (lowered == "spawn" || lowered.compare(0, 5, "unix:") == 0 ||
+            lowered.compare(0, 5, "pipe:") == 0) {
+            MGLOG_E("Config: MOBILEGL_TRANSPORT='%s' names a transport P6 implements and P5 does "
+                    "not; staying on monolith. This run is NOT a split run.",
+                    value.c_str());
+            MG_Config::Transport = MG_Config::TransportMode::Monolith;
+            return;
+        }
+        MGLOG_W("Config: Ignoring invalid env variable MOBILEGL_TRANSPORT='%s'; expected "
+                "monolith|inproc|spawn|unix:<path>|pipe:<name>, using monolith",
+                value.c_str());
+        MG_Config::Transport = MG_Config::TransportMode::Monolith;
+    }
+
+    // The MOBILEGL_IPC_* family (Config.h IpcTable). Parsed unconditionally rather than only
+    // when Transport != Monolith: a knob that silently means nothing on one arm of an A/B is
+    // how an A/B stops being one, and the ranges below are the diagnostics.
+    inline void InitIpc() {
+        auto& ipc = MG_Config::Ipc;
+        QueryEnvVariable("MOBILEGL_IPC_SERVER_PATH", ipc.ServerPath, "");
+        // Both ring floors are 1 MiB, not 0: a ring caps ONE record at half its size, and
+        // the catalogue's largest fixed payload (MGPFramebufferState, 304 bytes) plus a
+        // create_shader_state archive already needs far more than a toy ring. The ceilings
+        // are sanity, not policy.
+        ipc.RingMb = QueryEnvUint32("MOBILEGL_IPC_RING_MB", 8, 1, 1024);
+        ipc.StageMb = QueryEnvUint32("MOBILEGL_IPC_STAGE_MB", 32, 1, 4096);
+        ipc.SpinUs = QueryEnvUint32("MOBILEGL_IPC_SPIN_US", 50, 0, 1000000);
+        // 0 is admitted ON PURPOSE and is the negative control of exit gate E3(a): it turns
+        // the persistent-map push OFF, and PersistentCoherentMapScenario must go red.
+        ipc.PersistentBlockKb = QueryEnvUint32("MOBILEGL_IPC_PERSISTENT_BLOCK_KB", 64, 0, 65536);
+        // Whole-range push is the 0 arm; with it on (default) only blocks whose
+        // xxHash64 changed since the last push are shipped.
+        ipc.PersistentHashSuppress = QueryEnvUint32("MOBILEGL_IPC_PERSISTENT_HASH_SUPPRESS", 1, 0, 1);
+        ipc.BatchWaits = QueryEnvUint32("MOBILEGL_IPC_BATCH_WAITS", 1, 0, 1);
+        // The verify harness compares the pushed block against the applier per verb; a
+        // batched queue lets the comparer read a supplied field mid-apply, which is a
+        // torn read rather than a divergence. The batch is therefore off whenever the
+        // shadow comparer is armed.
+        if (MG_Config::Features.PipeVerify) ipc.BatchWaits = 0;
+        // 2 is the only tier P5 implements (R-6). 0 and 1 parse here and are refused at the
+        // point of use, which is where the "P11" in the message belongs.
+        ipc.AdoptTier = QueryEnvUint32("MOBILEGL_IPC_ADOPT_TIER", 2, 0, 2);
+        ipc.VerbBarrier = QueryEnvUint32("MOBILEGL_IPC_VERB_BARRIER", 1, 0, 1);
+        // P5e (MG_Remote/CONTRACT-P5E.md §1). The wait rule's A/B, parsed here like every
+        // other IPC knob and armed only where the server publishes kCapRunAheadApply.
+        ipc.RunAhead = QueryEnvUint32("MOBILEGL_IPC_RUN_AHEAD", 1, 0, 1);
+        // ... and forced OFF by the verify harness for BatchWaits' reason, one step further:
+        // run-ahead's whole point is that the client stops filling gPipeInputs for an
+        // unbarriered record, and the comparator has nothing left to compare when it does.
+        if (MG_Config::Features.PipeVerify) ipc.RunAhead = 0;
+        // The present credit (ruling 4). 1 is one frame of overlap; 8 is the ceiling because a
+        // deeper queue buys nothing on a CPU-bound client and pays for it in latency. 0 is NOT
+        // admitted: a credit of zero would mean "publish no present at all".
+        ipc.PresentCredit = QueryEnvUint32("MOBILEGL_IPC_PRESENT_CREDIT", 1, 1, 8);
+        ipc.StrictErrors = QueryEnvFlag("MOBILEGL_IPC_STRICT_ERRORS");
+        ipc.Audit = QueryEnvFlag("MOBILEGL_IPC_AUDIT");
+        QueryEnvVariable("MOBILEGL_IPC_SERVER_AFFINITY", ipc.ServerAffinity, "auto");
+
+        if (MG_Config::Transport == MG_Config::TransportMode::Monolith) return;
+        // One line, on the arm where these numbers decide behaviour, because every one of
+        // them is a number a bug report has to quote.
+        MGLOG_I("Config: IPC ring=%uMiB stage=%uMiB spin=%uus persistent-block=%uKiB "
+                "adopt-tier=%u verb-barrier=%u run-ahead=%u present-credit=%u strict=%d "
+                "audit=%d affinity='%s'",
+                ipc.RingMb, ipc.StageMb, ipc.SpinUs, ipc.PersistentBlockKb, ipc.AdoptTier,
+                ipc.VerbBarrier, ipc.RunAhead, ipc.PresentCredit,
+                static_cast<int>(ipc.StrictErrors), static_cast<int>(ipc.Audit),
+                ipc.ServerAffinity.c_str());
+        if (ipc.VerbBarrier == 0) {
+            MGLOG_W("Config: MOBILEGL_IPC_VERB_BARRIER=0 is the R-1 NEGATIVE CONTROL and is "
+                    "expected to fail: the client still pulls 31 of 63 PipeInputs fields from a "
+                    "live GLContext, so an unbarriered queue lets the server read future values");
+        }
+        if (ipc.PersistentBlockKb == 0) {
+            MGLOG_W("Config: MOBILEGL_IPC_PERSISTENT_BLOCK_KB=0 is the E3(a) NEGATIVE CONTROL: "
+                    "the persistent-map push is OFF and a coherent-map scenario must go red");
+        }
+    }
+#endif
+
     void Init() {
         MGLOG_D("Loading configuration from environment variables...");
         InitializeAcceptedEnvVariables();
 
         InitBackendType();
         InitFeatures();
+#if MOBILEGL_BUILD_DISAGGREGATED
+        // After InitFeatures, so the one line InitIpc logs is the last word on this run's
+        // configuration, and before the accepted-env map is destroyed just below.
+        InitTransport();
+        InitIpc();
+#endif
 
         // Destroy the map since we won't need it anymore
         acceptedEnvVariablesMap.reset();

MobileGL/Init.cpp

@@ -17,6 +17,7 @@
 #include <MG_Impl/GLImpl/Sync/GL_Sync.h>
 #include <MG_Impl/GLImpl/Query/GL_Query.h>
 #include <MG_Util/Async/ShaderCompilePool.h>
+#include <MG_Util/Metrics/PipeStats.h>
 #include <MG_Util/ShaderTranspiler/ShaderCompiler.h>
 #include <MG_State/GLState/ProgramState/ProgramTranslationCache.h>
 #include <MG_Util/ShaderTranspiler/TranslationCache.h>
@@ -42,6 +43,20 @@ namespace MobileGL {
             if (logLifecycle) {
                 MGLOG_I("MobileGL closing...");
             }
+#if MOBILEGL_BUILD_DISAGGREGATED
+            // P5: the split roles come down FIRST - ARCHITECTURE.md:537's order puts the whole
+            // of it before MobileGL::Destroy(), and this function IS MobileGL::Destroy. A no-op
+            // in a monolith RUN; absent from a monolith BUILD, because G1 admits no new pull
+            // symbol and no resized one (the first version called it unconditionally and moved
+            // DestroyImpl by 32 bytes). See BackendObjects.h for why the position rather than
+            // the call is the load-bearing part.
+            MG_Backend::ShutdownSplitRoles();
+#endif
+            // Before any subsystem the counters name goes away, and before the last frame's
+            // numbers can be lost: emits the final summary line and, when
+            // MOBILEGL_PIPE_STATS_FILE is set, the JSON dump. A no-op when the counters are
+            // off, and idempotent.
+            MG_Util::PipeStats::Shutdown();
             // First, before anything else is torn down. In-flight compile/link jobs own
             // their own inputs and are safe against everything below EXCEPT glslang's
             // process globals and the TShader/TProgram objects hanging off pGLContext,
@@ -102,6 +117,10 @@ namespace MobileGL {
         MGLOG_I("Initializing MobileGL...");
         MG_ConfigLoader::Init();
         MGLOG_I("Config loaded");
+        // Immediately after the config load and before anything can count: the MGPipe
+        // boundary counters latch their enable flag here, so every counting site in the
+        // two backends is a load of an already-settled global for the rest of the run.
+        MG_Util::PipeStats::Init();
         MG_State::Init();
         MGLOG_D("MG_State initialized");
         MG_Backend::Init();