feat(example): the outpost pays for its own shader before anyone sees it

C2. Scope held: `gym`, `arena`, and C1's cell geometry, radii and criteria are
untouched. One existing visible thing in the cell — the beacon — gains the
project's only `.esmaterial`.

That is what makes the attribution structural rather than argued. Home held zero
material-owned programs before this and holds zero now, so a program the material
path owns cannot have been built by anything the player has already walked past.
A rare stock flag would have had to be argued about; this cannot.

`render.mesh.materialPrograms` is the instrument: cumulative, read-only, and
emitted from a collect that was going to run anyway. Nothing here asks for
readiness in order to observe it — an observer that did would be the one paying
the compile, and the frame it asked about would be clean because of the asking.
The packaged game cannot reach the prewarm probe at all: that ABI is absent from
a release build, so this is a property of the binary and not of discipline.

Three criteria, and the first is a guard rather than a claim: it fails the day
the home half gains a material, which is the day the other two stop being about
the outpost. Then the outpost is prepared with nothing of it in the world and the
program is ALREADY built; then it is resident and visible and the count has not
moved. A cumulative counter that reads 1 before publication and 1 after is a
frame delta of zero without sampling every frame to say so.

Four sabotages, all pre-registered, all fire where they should. Removing the
material: both claims fail on nothing unique having been exercised. Putting the
same material at home: only the guard fires, and the other two stay green —
which is precisely why it is there. Disconnecting readiness while still letting
publication proceed: preparation buys nothing, and the count goes 0 before the
boundary to 1 after it. That last one is also the control this needed, because
it shows the counter CAN see a build that happens late.

`shader-readiness` is certified now, with `runBy` and a release criterion of its
own name. One command answers two questions; a claim nobody names is one nobody
notices going missing. 46/47, and only `settings` is left.

Author: esengine

examples/third-person-3d/assets/materials/beacon.esmaterial

@@ -0,0 +1,19 @@
+{
+  "version": "1.0",
+  "type": "material",
+  "shader": "builtin:model",
+  "blendMode": 9,
+  "depthTest": true,
+  "depthWrite": true,
+  "cull": 1,
+  "properties": {
+    "u_emissive": {
+      "r": 0.95,
+      "g": 0.78,
+      "b": 0.22,
+      "a": 1
+    },
+    "u_metallic": 0.15,
+    "u_roughness": 0.35
+  }
+}

examples/third-person-3d/assets/materials/beacon.esmaterial.meta

@@ -0,0 +1,6 @@
+{
+  "uuid": "91765692-eb29-4bd0-88d8-f87969ab2b0d",
+  "version": "2.0",
+  "type": "material",
+  "importer": {}
+}

examples/third-person-3d/assets/scenes/main.esscene

@@ -5375,7 +5375,8 @@
               "g": 0.85,
               "b": 0.4,
               "a": 1
-            }
+            },
+            "material": "assets/materials/beacon.esmaterial"
           }
         },
         {

src/esengine/renderer/plugins/MeshPlugin.cpp

@@ -703,6 +703,12 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
     ES_PROFILE_COUNTER("render.mesh.lodGathers", lodGathers);
     ES_PROFILE_COUNTER("render.mesh.programAsks", programAsks);
     ES_PROFILE_COUNTER("render.mesh.programCompiles", compiled_this_frame_);
+    // Material-owned programs built so far, CUMULATIVE. Read-only: an observer
+    // that had to ask for readiness to see it would be the one paying, and the
+    // frame it asked about would be clean because of the asking.
+    if (ctx.materials != nullptr) {
+        ES_PROFILE_COUNTER("render.mesh.materialPrograms", ctx.materials->builtVariantCount());
+    }
     if (compiled_this_frame_ > 0) {
         ES_PROFILE_COUNTER("render.mesh.compiledKey", last_compiled_variant_);
     }

tools/goldenProjects.mjs

@@ -275,9 +275,6 @@ export const EVIDENCE = {
  * coverage — the same bargain check-project-settings strikes.
  */
 export const KNOWN_GAPS = {
-  // A work item, not a dispensation: the staleness check below forces the entry
-  // out the moment a project certifies it.
-  'shader-readiness': 'no golden project watches the frame something first appears on; needs a runBy a release criterion schedules',
   // Present in the engine and shown by non-golden samples, but never carried
   // through the chain by a project the release argues from.
   settings: 'Celestial Heights persists language, effects and key bindings and reads them back at boot; volume waits on the game having sound',
@@ -380,7 +377,11 @@ export const GOLDEN = [
   {
     id: 'third-person-3d',
     certifies: ['third-person', 'level-of-detail', 'ssao', 'navigation-3d',
-                'root-motion', 'animation-events', 'world-streaming'],
+                'root-motion', 'animation-events', 'world-streaming', 'shader-readiness'],
+    // A packaged frame looks the same whether first sight of the outpost cost a
+    // compile or not; the run is what reads the counter on both sides of the
+    // boundary. Scheduled by `a-streamed-place-is-ready-before-it-is-seen`.
+    runBy: 'node tools/verify-third-person.mjs',
     targets: ['web'],
     tier: 'pr',
     // The character walks on the key it declares. What it DOES on the way is

tools/releaseGate.mjs

@@ -67,6 +67,17 @@ export const CRITERIA = [
     answeredBy: 'node tools/verify-third-person.mjs',
     needs: ['tools/verify-third-person.mjs', 'examples/third-person-3d/project.esproject'],
   },
+  {
+    id: 'a-streamed-place-is-ready-before-it-is-seen',
+    says: 'a streamed place pays its own shader requirements while it is being prepared,'
+      + ' not on the frame the player first sees it',
+    // The same command as above, deliberately under its own name: deleting the
+    // shader half would leave the character half green, and the registry unable
+    // to say what this command still owes.
+    answeredBy: 'node tools/verify-third-person.mjs',
+    needs: ['tools/verify-third-person.mjs',
+            'examples/third-person-3d/assets/materials/beacon.esmaterial'],
+  },
   {
     id: '3d-runs-where-it-ships',
     host: 'android',

tools/verify-third-person.mjs

@@ -496,18 +496,19 @@ const START = { y: 60, z: 120 };
 // on is persistent, and one outpost past the causeway is the only thing cut into
 // a cell. The claim is gameplay only a resident cell makes possible.
 function excursion({ out, frames, swings = 0, back = 0 }) {
-    const holds = [{ key: 'KeyS', from: 0, to: out }];
+    const holds = out > 0 ? [{ key: 'KeyS', from: 0, to: out }] : [];
     for (let i = 0; i < swings; i++) holds.push({ key: 'KeyJ', from: 225 + i * 20, to: 228 + i * 20 });
     if (back > 0) holds.push({ key: 'KeyW', from: out + 10, to: out + 10 + back });
     const r = runElectron([
         LAUNCHER, '--dir', dir, '--w', String(W), '--h', String(H),
         '--settle', '30', '--timeout', '120000', '--scene', 'main', '--streaming',
         '--gameplay', 'Player,Camera', '--combat', 'Player:Sentry,Beacon,Player',
-        '--ai', 'Sentry', '--input', JSON.stringify({ holds, frames }),
+        '--ai', 'Sentry', '--render', '--input', JSON.stringify({ holds, frames }),
     ], { encoding: 'utf8', cwd: ROOT });
     return {
         at: reading(r.stdout, 'gameplay'),
         world: reading(r.stdout, 'streaming'),
+        counters: reading(r.stdout, 'render') ?? {},
         combat: reading(r.stdout, 'combat') ?? { targets: {} },
         ai: reading(r.stdout, 'ai') ?? { found: false },
     };
@@ -565,6 +566,46 @@ const HOME_AGENTS = 1;
           + ` ${seen.combat?.targets?.Sentry === undefined ? 'gone' : 'still there'}`);
 }
 
+// The outpost's beacon carries the project's ONLY material, so a program that
+// path owns cannot have been built by anything at home. `materialPrograms` counts
+// them cumulatively, and reading it asks for nothing.
+const materials = (seen) => seen.counters?.['render.mesh.materialPrograms'] ?? -1;
+
+{
+    // The guard, not the claim: it fails the day the home half gains a material,
+    // which is the day everything below stops being about the outpost.
+    const home = excursion({ out: 0, frames: 40 });
+    check('nothing at home needs the material the outpost brings',
+          materials(home) === 0 && (home.world?.residentCells?.length ?? 9) === 0,
+          `${materials(home)} material program(s) with the outpost unpublished`);
+}
+
+{
+    // Prepared, and nothing of it in the world yet — and the program is built.
+    // This is where the compile is meant to be paid, and it is the reading that
+    // says it was.
+    const near = excursion({ out: 130, frames: 170 });
+    check('the outpost pays for its own shader while it is still only prepared',
+          near.world?.preparedCells?.includes('main.cell_0_2') === true
+          && (near.world?.residentCells?.length ?? 9) === 0 && materials(near) === 1,
+          `prepared ${JSON.stringify(near.world?.preparedCells)}, resident`
+          + ` ${JSON.stringify(near.world?.residentCells)}, ${materials(near)} material program(s)`);
+}
+
+{
+    // And seeing it adds nothing. The counter is cumulative, so one that is
+    // already 1 before publication and 1 after is a frame delta of zero without
+    // sampling every frame to say so.
+    const there = excursion({ out: 300, frames: 400 });
+    check('first sight of the outpost pays no shader compile',
+          there.world?.residentCells?.includes('main.cell_0_2') === true
+          && materials(there) === 1
+          && (there.counters?.['render.mesh.programCompiles'] ?? -1) === 0,
+          `resident ${JSON.stringify(there.world?.residentCells)},`
+          + ` ${materials(there)} material program(s) — the same one preparation built —`
+          + ` and ${there.counters?.['render.mesh.programCompiles']} stock compile(s) on the frame`);
+}
+
 const failed = results.filter((r) => !r.ok);
 console.log(`\nverify-third-person: ${results.length - failed.length}/${results.length}`
     + ' behaviour(s) hold up in the packaged game.');