@vgai/engine 0.5.22 → 0.5.23

package/src/adapter/native-debug-module.ts

@@ -23,6 +23,7 @@ import type { Game } from '../runtime/game';
 import {
   CONTRACT_SYSTEM_SLOTS,
   type ContractSurface,
+  type ContractSystemEmptySlot,
   projectContractSystemAdapters,
 } from './ingest/contract-system-adapters';
 import type { VgaiGameSystemAdapters } from './ingest/game-contract';
@@ -447,6 +448,18 @@ export function installNativeDebugBindings(
 export interface NativeSystemsBinding {
   readonly rootId: string;
   readonly slots: Readonly<Partial<SystemAdapters>>;
+  /**
+   * The slots this root's `systems` table answered with `absent(reason)` — the
+   * positive absences, in the game's own words.
+   *
+   * They are carried rather than dropped because they are the ONLY thing that
+   * can tell a coverage reader "this game has no networking" apart from "nobody
+   * ever looked". Nothing is installed for them (that would be the stub adapter
+   * `absent()`'s own comment forbids); they exist to be READ — through
+   * `binding.observation.entrySystems`, which is the product door the coverage
+   * table renders from.
+   */
+  readonly absent: readonly ContractSystemEmptySlot[];
 }
 
 /**
@@ -478,13 +491,27 @@ export function nativeSystemsBindingFromEntryModule(
   if (Object.keys(projection.bound).length === 0 && projection.empty.length === 0) {
     throw new Error(`Root "${rootId}" exports an empty \`systems\` object.`);
   }
-  return { rootId, slots: projection.bound };
+  return { rootId, slots: projection.bound, absent: projection.empty };
 }
 
-/** Install every declared binding onto the mounted Game's game-scoped slot
- *  table (`Game.installDeclaredSystemAdapters`), where the ordinary
- *  `game.systemAdapters` merge picks them up ahead of any lingering component
- *  registration for the same root. */
+/**
+ * Install every declared binding onto the mounted Game's game-scoped slot
+ * table (`Game.installDeclaredSystemAdapters`), where the ordinary
+ * `game.systemAdapters` merge picks them up ahead of any lingering component
+ * registration for the same root.
+ *
+ * A root's ABSENCES travel the same call and install NOTHING — they are
+ * recorded, never bound, because the whole point of `absent()` is that no
+ * adapter exists to bind (see its comment: a marker, never a stub). They are
+ * recorded HERE rather than left on the binding alone so the answer is
+ * game-scoped, matching the registry every editor panel already reads: a
+ * `SystemAdapters` slot is filled by whichever root builds it, so "does this
+ * GAME have physics" cannot be answered one root at a time.
+ *
+ * A root that declares only absences therefore still calls through — skipping
+ * it on an empty `slots` map is what would drop exactly the games whose whole
+ * declaration is "I have none of these".
+ */
 export function installNativeSystemsBindings(
   game: Game,
   bindings: readonly NativeSystemsBinding[],
@@ -498,7 +525,16 @@ export function installNativeSystemsBindings(
     );
   }
   for (const binding of bindings) {
-    if (Object.keys(binding.slots).length === 0) continue;
-    install.call(game, binding.rootId, binding.slots);
+    if (Object.keys(binding.slots).length === 0 && binding.absent.length === 0) continue;
+    install.call(
+      game,
+      binding.rootId,
+      binding.slots,
+      binding.absent.map((slot) => ({
+        rootId: binding.rootId,
+        slot: slot.slot,
+        reason: slot.evidence,
+      })),
+    );
   }
 }

package/src/adapter/rapier-physics-adapter.ts

@@ -29,6 +29,15 @@ import type { Transform, TransformOwner } from './transform';
  * `@react-three/rapier` pins for R3F worlds (0.19). Their `RigidBody` classes
  * are unrelated NOMINAL types, so a shared helper that named either one could
  * not serve both callers.
+ *
+ * FLIP CONDITION: `@react-three/rapier` pins its rapier EXACTLY (`0.19.2` as
+ * of its 2.2.0 — check `npm view @react-three/rapier dependencies`), so an
+ * override or engine bump to any OTHER rapier version forks the wasm instance
+ * that library initializes against and is refused. This structural split
+ * collapses only when the engine's own `@dimforge/rapier3d-compat` and
+ * `@react-three/rapier`'s exact pin agree on one version — at that point the
+ * two `RigidBody` types are one nominal type again and this interface can
+ * name it directly.
  */
 export interface RapierEditableBody {
   isFixed(): boolean;
@@ -53,28 +62,66 @@ export interface RapierEditableBody {
  * answered differently by each Rapier owner, and a caller that cannot answer
  * one honestly omits it.
  */
+/**
+ * What asking this Rapier owner about a node id actually yields.
+ *
+ * THE TWO NEGATIVE ANSWERS ARE DIFFERENT FACTS, and collapsing them into one
+ * `undefined` is what let `ownerOf` answer `'editor'` — "the editor drives this
+ * node's transform" — for an id this world has never heard of. `'no-body'` is a
+ * real measurement about a real node; `'unresolved'` is this implementer saying
+ * it cannot answer at all.
+ */
+export type RapierBodyLookup =
+  | { readonly kind: 'body'; readonly body: RapierEditableBody }
+  /** The node exists here and simply has no physics body. */
+  | { readonly kind: 'no-body' }
+  /** This world does not know this node id. */
+  | { readonly kind: 'unresolved' };
+
+/** The refusal sentence for a protocol verb aimed at a node this world has
+ *  never heard of — named once so every verb says the same thing. */
+function unresolvedNodeRefusal(operation: string, nodeId: string): string {
+  return (
+    `[RapierPhysicsAdapter] ${operation}: this world does not know node id "${nodeId}", so ` +
+    'there is no body to drive. Refusing rather than reporting a completed write — gate on ' +
+    "ownerOf(id) !== 'unresolved' before driving physics from a game-scoped adapter."
+  );
+}
+
 export function createRapierBodyEditing(
-  bodyFor: (nodeId: string) => RapierEditableBody | null | undefined,
+  lookup: (nodeId: string) => RapierBodyLookup,
 ): Pick<PhysicsAdapter, 'ownerOf' | 'freeze' | 'commit' | 'unfreeze'> {
   /** Saved body types while frozen, so unfreeze can restore them. */
   const frozen = new Map<RapierEditableBody, number>();
 
+  /** The body for a verb that must actually reach one, or `null` when this node
+   *  genuinely has no physics. THROWS for an unknown id: the three verbs below
+   *  return `void`, so a silent return is indistinguishable from a completed
+   *  write, and `commit` in particular is a WRITE the caller believes landed. */
+  const bodyForWrite = (operation: string, nodeId: string): RapierEditableBody | null => {
+    const answer = lookup(nodeId);
+    if (answer.kind === 'unresolved') throw new Error(unresolvedNodeRefusal(operation, nodeId));
+    return answer.kind === 'body' ? answer.body : null;
+  };
+
   return {
     ownerOf(nodeId: string): TransformOwner {
-      const body = bodyFor(nodeId);
-      if (!body) return 'editor';
-      // A fixed body never moves on its own → the editor owns its transform.
-      return body.isFixed() ? 'editor' : 'physics';
+      const answer = lookup(nodeId);
+      if (answer.kind === 'unresolved') return 'unresolved';
+      // A node with no body, and a FIXED body (which never moves on its own),
+      // are both transforms the editor drives.
+      if (answer.kind === 'no-body') return 'editor';
+      return answer.body.isFixed() ? 'editor' : 'physics';
     },
     freeze(nodeId: string): void {
-      const body = bodyFor(nodeId);
+      const body = bodyForWrite('freeze', nodeId);
       if (!body || frozen.has(body)) return;
       frozen.set(body, body.bodyType());
       // Kinematic-position: the body stops simulating but tracks the pose we set.
       body.setBodyType(2 /* KinematicPositionBased */, true);
     },
     commit(nodeId: string, t: Transform): void {
-      const body = bodyFor(nodeId);
+      const body = bodyForWrite('commit', nodeId);
       if (!body) return;
       body.setTranslation({ x: t.position[0], y: t.position[1], z: t.position[2] }, true);
       body.setRotation(
@@ -83,7 +130,7 @@ export function createRapierBodyEditing(
       );
     },
     unfreeze(nodeId: string): void {
-      const body = bodyFor(nodeId);
+      const body = bodyForWrite('unfreeze', nodeId);
       if (!body) return;
       const prev = frozen.get(body);
       if (prev !== undefined) {
@@ -149,22 +196,31 @@ export function createRapierPhysicsAdapter(
     return contactBuf.subarray(0, contactCount * 3);
   };
 
-  /** The one place this adapter crosses from node id into Three's vocabulary. */
-  const bodyFor = (nodeId: string): RAPIER.RigidBody | undefined => {
-    const o = resolve(nodeId);
-    return o ? registry.get(o)?.body : undefined;
+  /** The one place this adapter crosses from node id into Three's vocabulary —
+   *  and the one place that can tell an UNKNOWN node from one with no body. */
+  const lookup = (nodeId: string): RapierBodyLookup => {
+    const object = resolve(nodeId);
+    if (!object) return { kind: 'unresolved' };
+    const body = registry.get(object)?.body;
+    return body ? { kind: 'body', body } : { kind: 'no-body' };
   };
 
-  return {
-    ...createRapierBodyEditing(bodyFor),
-    debugDraw: () => physics?.debugMesh ?? null,
-    setDebugDrawEnabled(enabled: boolean): void {
-      if (!physics) return;
+  const adapter: PhysicsAdapter = { ...createRapierBodyEditing(lookup) };
+  // The debug-draw and contact capabilities exist only where a physics CONTEXT
+  // does. They used to be attached unconditionally and then no-op internally:
+  // `setDebugDrawEnabled(true)` returned as if it had enabled something, and
+  // `contactPoints()` returned an empty view — "we looked and there are no
+  // contacts" — for a world with no simulation at all. Presence mirrors the
+  // capability, so `physics-debug.ts`'s existing `?.()` calls now see absence.
+  if (physics) {
+    adapter.debugDraw = () => physics.debugMesh;
+    adapter.setDebugDrawEnabled = (enabled: boolean): void => {
       // Same two fields the in-game KeyP toggle flips — the adapter's render
       // system reads `debugEnabled` and feeds `debugRender()` into the mesh.
       physics.debugEnabled = enabled;
       physics.debugMesh.visible = enabled;
-    },
-    contactPoints: collectContactPoints,
-  };
+    };
+    adapter.contactPoints = collectContactPoints;
+  }
+  return adapter;
 }

package/src/adapter/renderer-config.ts

@@ -4,7 +4,7 @@
  * It lives in the ADAPTER SEAM, not in a surface entry, because `WorldRendererConfig` IS part of
  * the root contract: `MountedThreeRoot.rendererConfig` reports it (`./root-adapter.ts`) and
  * `./root-seam-contract.ts` already lists it as a contract field. The seam defines the shape; the
- * surface entries and the editor CONFORM to it — `world3d-react/r3f-adapter.tsx` is the declarer,
+ * surface entries and the editor CONFORM to it — `world3d-react/r3f-root-factory.tsx` is the declarer,
  * `runtime/create-runtime.ts` the host, `editor/src/components/ViewportPanel.tsx` the editor's
  * applier. Do NOT move it back under `world3d-react/`: nothing here touches react, and a core
  * adapter file reaching into a react entry is exactly what `react-core-import-ban.test.ts` forbids
@@ -90,7 +90,7 @@ export interface WorldRendererConfig {
  * Apply `config` to `renderer`, returning the restore function that puts back what was there.
  *
  * `three` is passed in rather than imported for values so the enum constants come from the HOST's
- * three instance — the same identity rule `r3f-adapter.tsx` follows for the scene and camera.
+ * three instance — the same identity rule `r3f-root-factory.tsx` follows for the scene and camera.
  */
 export function applyWorldRendererConfig(
   three: typeof THREE,

package/src/adapter/root-adapter.ts

@@ -1,10 +1,10 @@
 /**
  * RootAdapter — the host ⇄ runtime contract. A ROOT is *anything that mounts*.
  *
- * This is the interface the host depends on. `GameSetupFn` is private to one
- * implementer (`SetupThreeRootAdapter`); first-party content and unmodified
- * external games are peer root adapters. A game is the manifest's complete
- * roots array, while each adapter owns exactly one root.
+ * This is the interface the host depends on. First-party content and
+ * unmodified external games are peer root adapters. A game is the
+ * manifest's complete roots array, while each adapter owns exactly one
+ * root.
  */
 
 import type { Container } from 'pixi.js';
@@ -136,8 +136,8 @@ export interface MountedReactRoot extends MountedRootBase {
 /** Every kind of live, mounted world. */
 export type MountedRoot = MountedThreeRoot | MountedPixiRoot | MountedReactRoot;
 
-/** Map a {@link AdapterSurface} to its mounted-world shape (mirrors `NodeOf`/
- *  `BodyOf`/`ColliderOf` in `ecs/behavior.ts`) — lets generic code over
+/** Map a {@link AdapterSurface} to its mounted-world shape — lets generic
+ *  code over
  *  `K extends AdapterSurface` name the right surface without a manual union. */
 export type MountedRootFor<K extends AdapterSurface> = K extends 'three'
   ? MountedThreeRoot
@@ -174,7 +174,7 @@ export interface RootAdapter<K extends AdapterSurface = 'three'> {
 }
 
 /**
- * One surface tag paired with an adapter typed FOR that surface (WO-34).
+ * One surface tag paired with an adapter typed FOR that surface.
  *
  * A resolver that turns a manifest root into a mountable
  * adapter handles every surface in one function, so its return type has to

package/src/adapter/system-adapter.ts

@@ -20,7 +20,19 @@ import type { Transform, TransformOwner } from './transform';
 export type PhysicsColliderShape =
   | { readonly type: 'cuboid'; readonly halfExtents: readonly [number, number, number] }
   | { readonly type: 'ball'; readonly radius: number }
-  | { readonly type: 'capsule'; readonly halfHeight: number; readonly radius: number };
+  | { readonly type: 'capsule'; readonly halfHeight: number; readonly radius: number }
+  /**
+   * A collider this seam has no plain-data projection for — a trimesh,
+   * heightfield, convex hull, cylinder, cone, …
+   *
+   * IT IS STILL A COLLIDER, and the body still has it. Implementations used to
+   * drop these from `colliders()` entirely, so a body whose only collider was a
+   * trimesh inspected as a body with NO physics at all. `kind` is the native
+   * shape's own name, so the inspector can say WHICH shape it cannot draw
+   * rather than implying nothing is there. Nothing may synthesize dimensions
+   * for one, and `previewCollider` refuses it.
+   */
+  | { readonly type: 'unsupported'; readonly kind: string };
 
 /** Plain-data projection of one native 3D physics collider. The owning
  * physics implementation keeps the actual collider; editor authoring only
@@ -249,12 +261,28 @@ export interface NetworkingAdapter {
   authority(nodeId: string): 'local' | 'remote' | 'server';
   /** Remote/server-authoritative nodes → inspect-only in the editor. */
   editable(nodeId: string): boolean;
-  /** Current connection lifecycle state. */
-  getConnectionState(): ConnectionState;
-  /** The active room's identity, or `null` when not connected to a room. */
-  getRoomInfo(): RoomInfo | null;
-  /** Replication activity snapshot, for a live network inspector panel. */
-  getReplicationStats(): ReplicationStats;
+  /**
+   * Optional capability: current connection lifecycle state.
+   *
+   * OPTIONAL for the same reason every other member here is — `'disconnected'`
+   * is a POSITIVE CLAIM about the link, and an implementer that never taught
+   * this adapter to read connection state has not made it. Absent ⇒ the
+   * inspector marks the section unsupported; it does not report a game as
+   * disconnected on the strength of nobody having looked.
+   */
+  getConnectionState?(): ConnectionState;
+  /**
+   * Optional capability: the active room's identity, or `null` when connected
+   * to no room. `null` is the ANSWER "there is no room", so absence of the
+   * accessor — "nothing here can tell you" — has to be a different thing.
+   */
+  getRoomInfo?(): RoomInfo | null;
+  /**
+   * Optional capability: replication activity snapshot, for a live network
+   * inspector panel. Zeroes are a measurement, not a default; an adapter with
+   * no counters omits this rather than reporting a quiet link.
+   */
+  getReplicationStats?(): ReplicationStats;
   /** Subscribe to changes in connection state / room / replication stats. */
   subscribe(cb: () => void): Unsubscribe;
   /** Optional capability: one plain-data (JSON-safe) snapshot of the
@@ -281,7 +309,7 @@ export interface NetworkingAdapter {
    *  (e.g. read off its own room state). The editor consumes this for display —
    *  a seat label — ONLY when a real implementer provides it, falling back to a
    *  generic label otherwise. */
-  getPlayerIdentity?(): NetPlayerIdentity;
+  getPlayerIdentity?(): NetPlayerIdentity | undefined;
   /** Optional capability, PAIRED with {@link getPlayerIdentity}: set the local
    *  player's identity through the game's OWN multiplayer mechanism. The editor
    *  renders an editable name field ONLY when a real implementer provides this
@@ -346,6 +374,13 @@ export interface NavCrowdAgentState {
  */
 export interface NavigationAdapter {
   hasNavMesh(): boolean;
+  /**
+   * `[]` means SEARCHED AND FOUND NO ROUTE — a fact about the level. An
+   * implementer with no navmesh to search, or whose query FAILED, THROWS
+   * instead; those are facts about the implementer, and collapsing all three
+   * into `[]` tells a caller the level is impassable when nobody looked.
+   * Gate on {@link hasNavMesh} where the first case is reachable.
+   */
   findPath(start: NavPoint, end: NavPoint): NavPoint[];
   debugMesh(scene: THREE.Scene): THREE.Object3D | null;
   /** (Re)build the navmesh from source meshes. Synchronous in the blessed

package/src/adapter/system-seam-contract.ts

@@ -53,9 +53,9 @@ export const NETWORKING_ADAPTER_SHAPE = defineSeamShape<NetworkingAdapter>()({
   networkId: { optional: false, kind: 'function', required: 'operation' },
   authority: { optional: false, kind: 'function', required: 'operation' },
   editable: { optional: false, kind: 'function', required: 'operation' },
-  getConnectionState: { optional: false, kind: 'function', required: 'operation' },
-  getRoomInfo: { optional: false, kind: 'function', required: 'operation' },
-  getReplicationStats: { optional: false, kind: 'function', required: 'operation' },
+  getConnectionState: { optional: true, kind: 'function', required: 'operation' },
+  getRoomInfo: { optional: true, kind: 'function', required: 'operation' },
+  getReplicationStats: { optional: true, kind: 'function', required: 'operation' },
   subscribe: { optional: false, kind: 'function', required: 'effect' },
   getStateSnapshot: { optional: true, kind: 'function', required: 'operation' },
   messageEvents: { optional: true, kind: 'function', required: 'operation' },

package/src/adapter/system-slot.ts

@@ -0,0 +1,291 @@
+/**
+ * `createSystemSlot` — THE implementation of the declared-slot façade, the
+ * seam between a STATIC `systems` declaration and a LIVE adapter that only
+ * exists once the world tree is mounted.
+ *
+ * WHY IT EXISTS. An entry declares its systems statically
+ * (`export const systems = { networking: networkingSystem() }`), while the
+ * thing being declared — a joined Colyseus room, a baked navmesh, a mounted
+ * `<Physics>`, a cutscene's camera ownership — is built inside the world tree,
+ * later, and may be replaced (reconnect, remount, hot restart) or go away
+ * (stop). The slot is a stable object the host installs at mount and holds
+ * forever; every call forwards to whatever is attached right now.
+ *
+ * ── THE HONESTY RULE, STATED IN ONE PLACE ───────────────────────────────────
+ * This is why the pattern is centralized: five hand-rolled copies disagreed
+ * about it, and each disagreement was found by a separate review.
+ *
+ *  - An **action** with no live target REFUSES BY NAME
+ *    (`<name>: <unattachedMessage>`). Never a silent no-op — a caller that
+ *    told the game to DO something must learn that it did not happen. An
+ *    action against a live adapter that lacks the member refuses the same
+ *    way, naming the member.
+ *  - A **read** answers its declared HONEST EMPTY — `'disconnected'`, `[]`,
+ *    `null`, `false`. That is not a fabrication: it is the truth of the
+ *    not-attached state, in the same vocabulary the editor's own edit-mode
+ *    adapters use. Reads are also the only kind safe to call from a per-frame
+ *    debug draw, which is why a throw into a rAF loop is never the answer.
+ *  - An **optional** member MIRRORS THE LIVE ADAPTER'S PRESENCE: absent while
+ *    unattached, and absent afterwards when the live adapter itself does not
+ *    provide it. Presence IS the consume-by-presence protocol's signal, so
+ *    the slot may never invent it. Each presence read CAPTURES the adapter it
+ *    saw and forwards to that same instance, so a detach between the read and
+ *    the call answers as the adapter the caller was handed rather than a
+ *    mid-flight swap.
+ *  - A **subscribe** member SURVIVES REATTACHMENT: listeners live on the
+ *    slot, never on the instance, and the slot re-binds its own single
+ *    subscription on every attach/detach. A panel that subscribed once to the
+ *    stable slot object is therefore never left holding a disposed system, and
+ *    it is notified when the live half appears or disappears.
+ *  - A member the config DOES NOT LIST does not exist on the slot at all.
+ *    That is how the anti-shim rule spells omission — e.g. `PhysicsAdapter`'s
+ *    `debugDraw`/`contactPoints` over `@react-three/rapier`, whose debug line
+ *    segments live inside the fiber tree and expose no handle. Absence is a
+ *    capability answer; a stub is a lie.
+ *
+ * ── RESOURCE OWNERSHIP ──────────────────────────────────────────────────────
+ * OWNER: whoever built the live adapter (the hook, the bridge component). The
+ * slot owns only the POINTER to it plus its own listener set and its own
+ * subscription to the live half. SHARERS: every reader of the declared
+ * system — editor inspectors, instruments. TEARDOWN: the function `attach`
+ * returns, and nothing else. It is IDENTITY-GUARDED — it clears only while
+ * the same instance is still attached, so a replace-then-teardown-the-old
+ * ordering cannot detach the new one — and detaching never disposes the
+ * adapter, because the slot did not create it.
+ *
+ * WHERE the slot module lives decides how many games share it. A slot in
+ * PROJECT-owned source (the four capability/example façades) is per Play
+ * instance, because the editor stamps mount ids onto project-owned import
+ * specifiers (`server/project-module-instance.ts`) — N instances get N module
+ * graphs and N slots. A slot in an ENGINE module is reached by bare
+ * specifier, which that stamping deliberately never touches, so it is ONE per
+ * page: every Play instance shares it, and concurrent instances' attaches
+ * contend (last attach wins; the loser's detach is dropped by the identity
+ * guard). `rapier-physics-bridge.tsx` is the one such slot today and warns
+ * loudly when contended — prefer project-owned slot modules for anything new.
+ *
+ * NOT A WRAPPER. The slot's members have the adapter interface's own exact
+ * signatures and hand back the implementation's own values; nothing stands
+ * between a caller and the live library object.
+ */
+
+import type { VgaiGameSystemEmpty } from './ingest/game-contract';
+
+/**
+ * `absent(reason)` — THE WHOLE-SLOT counterpart of the four per-member policies
+ * above, and the fifth line of the same honesty rule.
+ *
+ * The four policies answer "this slot exists but nothing is attached yet". This
+ * one answers a different question entirely: **this game will never have that
+ * subsystem, and here is what was searched.** A slot simply left out of the
+ * `systems` table cannot say that — an omitted key means "unsupported", which is
+ * the same shape as "nobody looked", and the coverage report has to file it as a
+ * work order forever. Declaring the absence turns an UNANSWERED row into a
+ * terminal one.
+ *
+ * ```ts
+ * export const systems = {
+ *   audio: sfxAudioSystem(),
+ *   physics: rapierPhysicsSystem(),
+ *   networking: absent('single-player: no Colyseus client anywhere in `src/`'),
+ * };
+ * ```
+ *
+ * ## It is a CONSTRUCTOR for the shape that already exists, not a second one
+ *
+ * The returned value IS `VgaiGameSystemEmpty` — the plain
+ * `{ present: false, evidence }` record an INGESTED game declares on
+ * `window.vgaiGame.systems.systemAdapters`, validated by the same single
+ * projection (`ingest/contract-system-adapters.ts`). There is one shape law, not
+ * two: a foreign game cannot import this helper and must stay able to write the
+ * record by hand, so nothing here may brand the runtime value. What the helper
+ * buys a FIRST-PARTY author is the reason-quality check moved to the call site —
+ * our own code failing its own contract fails fast, where an ingested game's
+ * same mistake is filed as a `malformed` verdict for its coverage report.
+ *
+ * ## It is a MARKER, never a stub adapter
+ *
+ * Do not answer an absent slot with an adapter whose methods return zeros. A
+ * `getConnectionState()` of `'disconnected'` on a game with no transport implies
+ * a connection that could exist; that is the fabrication the anti-shim rule
+ * forbids. The absence is STATED, and the host installs nothing for it.
+ *
+ * @param reason What was searched and what was found, in the game's own source
+ *   terms. "no netcode anywhere in `src/`" is a finished answer a reviewer can
+ *   re-run; "not implemented yet" is a plan, and is rejected here.
+ */
+export function absent(reason: string): VgaiGameSystemEmpty {
+  if (typeof reason !== 'string' || reason.trim() === '') {
+    throw new Error(
+      'absent(): an absence needs evidence — say what was searched and what was found ' +
+        '(e.g. "no Colyseus client anywhere in `src/`"), so a reviewer can re-run it. ' +
+        'An unevidenced absence asserts something nobody can re-check.',
+    );
+  }
+  return { present: false, evidence: reason };
+}
+
+/** Any adapter member. `never[]` args make the conditional match contravariantly. */
+type AnyFn = (...args: never[]) => unknown;
+
+/** The declared member's return type, used to type a `read`'s honest empty. */
+type MemberReturn<F> = NonNullable<F> extends (...args: never[]) => infer R ? R : never;
+
+/**
+ * The per-member policy. There are exactly four, and every member of every
+ * declared slot in the repo is one of them — see the honesty rule above.
+ */
+export type SystemSlotMemberSpec<F> =
+  | { readonly kind: 'action' }
+  | { readonly kind: 'read'; readonly empty: MemberReturn<F> }
+  | { readonly kind: 'subscribe' }
+  | { readonly kind: 'optional' };
+
+/** The keys of `T` whose values are callable (data properties are not slottable). */
+type FunctionMemberKeys<T> = {
+  [K in keyof T]-?: NonNullable<T[K]> extends AnyFn ? K : never;
+}[keyof T];
+
+/** Per-member policies. A member left out is left OFF the slot entirely. */
+export type SystemSlotMembers<T> = {
+  readonly [K in FunctionMemberKeys<T>]?: SystemSlotMemberSpec<T[K]>;
+};
+
+export interface SystemSlotConfig<T extends object> {
+  /**
+   * The slot's own name, used as the prefix of every refusal so a stack-less
+   * error still names the seam (`'networkingSystem'`, `'rapierPhysicsSystem'`).
+   */
+  readonly name: string;
+  /**
+   * The rest of an action's refusal while nothing is attached — the DOMAIN
+   * half of the message, naming what has not happened yet ("the world is not
+   * playing, or the navmesh has not finished building").
+   */
+  readonly unattachedMessage: string;
+  readonly members: SystemSlotMembers<T>;
+}
+
+export interface SystemSlot<T extends object> {
+  /**
+   * Publish `live` as the slot's target. Returns the ONE detach path, which
+   * is identity-guarded: it clears only while `live` is still the attached
+   * instance, and never disposes it.
+   */
+  attach(live: T): () => void;
+  /** The stable declared object. Hand THIS to the entry's `systems` map. */
+  readonly slot: T;
+}
+
+export function createSystemSlot<T extends object>(config: SystemSlotConfig<T>): SystemSlot<T> {
+  const { name, unattachedMessage, members } = config;
+
+  let live: T | null = null;
+  /** Subscribers to the stable slot object; they outlive any one live instance. */
+  const listeners = new Set<() => void>();
+  /** The slot's own single subscription to whatever is attached. */
+  let liveUnsubscribe: (() => void) | null = null;
+  let subscribeMember: string | null = null;
+
+  const asRecord = (value: object): Record<string, unknown> =>
+    value as unknown as Record<string, unknown>;
+
+  const liveMember = (member: string): AnyFn | undefined => {
+    if (!live) return undefined;
+    const value = asRecord(live)[member];
+    return typeof value === 'function' ? (value as AnyFn) : undefined;
+  };
+
+  const notify = (): void => {
+    for (const listener of [...listeners]) listener();
+  };
+
+  const bindLive = (): void => {
+    liveUnsubscribe?.();
+    liveUnsubscribe = null;
+    if (!live || subscribeMember === null || listeners.size === 0) return;
+    const subscribe = liveMember(subscribeMember);
+    if (!subscribe) return;
+    const result = subscribe.call(live, notify as never);
+    liveUnsubscribe = typeof result === 'function' ? (result as () => void) : null;
+  };
+
+  const target: Record<string, unknown> = {};
+
+  const declared = Object.entries(members) as [string, SystemSlotMemberSpec<unknown>][];
+  for (const [member, spec] of declared) {
+    switch (spec.kind) {
+      case 'action': {
+        // Refuse by name, twice over: no live adapter at all, or a live
+        // adapter that does not carry this member (only ever a foreign
+        // replacement — the blessed implementations carry all of theirs).
+        target[member] = (...args: never[]): unknown => {
+          if (!live) throw new Error(`${name}: ${unattachedMessage}`);
+          const fn = liveMember(member);
+          if (!fn) throw new Error(`${name}: the live adapter has no ${member}().`);
+          return fn.apply(live, args);
+        };
+        break;
+      }
+      case 'read': {
+        const { empty } = spec;
+        target[member] = (...args: never[]): unknown => {
+          const current = live;
+          const fn = liveMember(member);
+          const value = fn ? fn.apply(current, args) : undefined;
+          return value ?? empty;
+        };
+        break;
+      }
+      case 'subscribe': {
+        if (subscribeMember !== null) {
+          throw new Error(
+            `${name}: a slot declares at most one 'subscribe' member (${subscribeMember} and ${member}).`,
+          );
+        }
+        subscribeMember = member;
+        target[member] = (listener: () => void): (() => void) => {
+          listeners.add(listener);
+          bindLive();
+          return () => {
+            listeners.delete(listener);
+            bindLive();
+          };
+        };
+        break;
+      }
+      case 'optional': {
+        Object.defineProperty(target, member, {
+          enumerable: true,
+          configurable: true,
+          get(): AnyFn | undefined {
+            const current = live;
+            const fn = liveMember(member);
+            if (!fn) return undefined;
+            return (...args: never[]): unknown => fn.apply(current, args);
+          },
+        });
+        break;
+      }
+    }
+  }
+
+  const attach = (next: T): (() => void) => {
+    live = next;
+    bindLive();
+    notify();
+    return () => {
+      if (live !== next) return;
+      live = null;
+      bindLive();
+      notify();
+    };
+  };
+
+  // THE ONE CAST. `exactOptionalPropertyTypes` forbids an optional member
+  // whose getter can yield `undefined`, but that is precisely the honest
+  // shape here — the getter IS how presence mirrors the live adapter — and a
+  // reflectively built object cannot be typed structurally anyway. Callers
+  // see exactly the absent/present behavior the adapter interface documents.
+  return { attach, slot: target as T };
+}