@vgai/engine 0.5.11 → 0.5.13

package/src/adapter/authoring.ts

@@ -238,7 +238,7 @@ export interface InspectorProvider {
   /** Schema-driven — NOT fixed to `SceneEntity`. */
   properties(id: string): PropertyDescriptor[];
   get(id: string, path: string): unknown;
-  set(id: string, path: string, value: unknown): void;
+  set(id: string, path: string, value: unknown): void | Promise<void>;
   /**
    * Optional — REMOVE a property's authored override entirely (not "set to a
    * value"), letting whatever governs it in its absence take over. The one
@@ -281,6 +281,19 @@ export interface AssetSubjectProvider {
   entries?(): ReadonlyArray<{ id: string; subject: AuthoringAssetSubject }>;
 }
 
+/** A semantic jump from one authored subject to another document/subject.
+ * The adapter owns resolution and opening; the inspector only presents the
+ * title and exposes the same verb to human and serialized projections. */
+export interface RelatedSubjectLink {
+  readonly id: string;
+  readonly title: string;
+  open(): void;
+}
+
+export interface RelatedSubjectsProvider {
+  links(id: string): readonly RelatedSubjectLink[];
+}
+
 export interface StructureProvider {
   create(kind: string, parentId?: string): string;
   /**
@@ -384,26 +397,6 @@ export interface PersistenceProvider {
   applyExternal?(content: unknown, rawContent?: string): void;
 }
 
-/** D8 — mutually-exclusive root groups (radio roots): e.g. a "Scenes" group whose
- *  members are the game's scene roots, only one of which is loaded/active at a
- *  time (unlike ordinary sibling roots, which all coexist). */
-export interface RootGroup {
-  id: string; // stable, e.g. 'scenes'
-  label: string; // 'Scenes'
-  memberRootIds: string[]; // EditorNode ids; each is a hierarchy root
-  activeRootId: string | null;
-}
-export interface RootGroupsProvider {
-  groups(): RootGroup[];
-  activate(groupId: string, rootId: string): Promise<void> | void;
-}
-
-/** D8 — data-file → root mapping ("opening a file" = activating its root). */
-export interface FileMapProvider {
-  /** project-relative path → node id this adapter maps it to, else null. */
-  rootForFile(path: string): string | null;
-}
-
 /** D12 — per-layer viewport picking. Coordinates are client (browser) px. */
 export interface PickProvider {
   pick(clientX: number, clientY: number): string | null;
@@ -510,9 +503,11 @@ export interface BoxEditProvider {
   referencePoint?(id: string): BoxEditReferencePoint | null;
 }
 
-/** Text-content editing — currently OFF-contract (the react adapter has an `editText(id)`
- *  method, react-world-authoring-adapter.ts:728, not reachable via the contract). Bring it
- *  on so the overlay's double-click-to-edit-text (D3) is contract-driven. */
+/** Text-content editing, ON the contract: the react-world adapter implements this
+ *  provider (`react-world-authoring-adapter.ts`'s `readonly text: TextProvider`),
+ *  bringing its own `editText(id)` write path onto the seam, so the overlay's
+ *  double-click-to-edit-text (D3) is contract-driven rather than reaching for a
+ *  concrete adapter's method. */
 export interface TextProvider {
   /** the element's editable pure-text, or null if the body is dynamic/has child elements */
   get(id: string): string | null;
@@ -539,15 +534,46 @@ export interface ColorSampleProvider {
 }
 
 /**
- * WO-IDX1 — where a node's live object was CREATED in the game's own source.
+ * WO-IDX1 — where a node's live object CAME FROM in the game's own truth.
  *
- * `display` is the `file:line` the editor shows verbatim. The unanchored shape
+ * `display` is the string the editor shows verbatim. The unanchored shape
  * carries a `reason` rather than a blank, because "we don't know" and "a
  * library built it" are different facts and neither may present as silence
  * (the honest-floor rule).
+ *
+ * TWO ANCHORED KINDS, because a game has two kinds of truth and only one of
+ * them is source.
+ *
+ *  - `source` is the original: a `new` expression at a `file:line:col` in the
+ *    game's own code, which is where an edit to a constructor literal has to be
+ *    written.
+ *  - `data` is the sibling a level-based game needs. Descent's placed cargo —
+ *    the robots, the powerups, the hostages — reaches no source literal at all;
+ *    it is binary records inside `descent.hog` that the game parses at load. An
+ *    authored move of a robot is therefore an edit to THE GAME'S OWN DATA, and
+ *    the honest anchor is the data file plus the index of the record that
+ *    addresses the object inside it.
+ *
+ * `kind` is an explicit discriminant rather than an inferred one, so a consumer
+ * that only understands source anchors fails to compile against a data anchor
+ * instead of silently reading `line` off something that has none.
+ *
+ * A data record is EXACTLY ONE object by construction — an index addresses one
+ * record — so the "how many objects did this site construct?" question that
+ * governs a source write has no data-side analogue and must not be invented
+ * for one.
  */
 export type NodeCreationSite =
-  | { anchored: true; file: string; line: number; col: number; display: string }
+  | { anchored: true; kind: 'source'; file: string; line: number; col: number; display: string }
+  | {
+      anchored: true;
+      kind: 'data';
+      /** Project-relative path of the game's own data file, POSIX separators. */
+      file: string;
+      /** Index of the record inside that file which addresses this object. */
+      record: number;
+      display: string;
+    }
   | { anchored: false; reason: string };
 
 /**
@@ -571,12 +597,9 @@ export interface AuthoringAdapter {
   readonly inspector?: InspectorProvider;
   /** The selected node is an atomic asset that can open in the Asset Editor. */
   readonly assetSubject?: AssetSubjectProvider;
+  readonly related?: RelatedSubjectsProvider;
   readonly structure?: StructureProvider;
   readonly persistence?: PersistenceProvider;
-  /** D8 — mutually-exclusive root groups (radio roots). Absent ⇒ no grouped roots. */
-  readonly rootGroups?: RootGroupsProvider;
-  /** D8 — data-file → root mapping. Absent ⇒ this adapter maps no files to roots. */
-  readonly files?: FileMapProvider;
   /** D12 — per-layer viewport picking. Absent ⇒ this adapter is not pickable. */
   readonly pickable?: PickProvider;
   /** T0 (spec 27 §2) — per-node screen geometry for a DOM visual editor's overlay/

package/src/adapter/body-marks.ts

@@ -0,0 +1,69 @@
+/**
+ * The transform-AUTHORITY convention: how a game tells the host which of its
+ * nodes have their pose written by a rigid body rather than by the node itself.
+ *
+ * Sibling of `hierarchy-marks.ts`, and the same shape of idea. That module's
+ * marks answer "what IS this node" for the panel; this one answers "who WRITES
+ * this node's pose" for an edit. Both are written by GAME code at the seam that
+ * knows the answer, read generically by the host, and namespaced `vgai*` because
+ * they are the host's namespace on a node the game owns.
+ *
+ * ## Why it exists
+ *
+ * A world that simulates writes `node.position/quaternion` FROM its bodies every
+ * step. Setting the node is therefore not an edit — it is a value that survives
+ * until the next step and then vanishes, which is what "the gizmo does nothing"
+ * looks like from the outside. The edit has to reach the body.
+ *
+ * The host cannot find the body on its own. Three.js has no body concept, the
+ * body is usually not in the scene graph at all, and the mapping from node to
+ * body is private to whichever code built the pair. So the code that ATTACHES a
+ * body to a node draws the link in the same breath — one call, at the one place
+ * the answer is known — exactly as `markBuiltInternal` is called at the attach
+ * seam and never by a later sweep of the tree.
+ *
+ * ## Prefer the system adapter when you have one
+ *
+ * A game that already registers `SystemAdapters.physics` needs none of this: the
+ * adapter's `ownerOf`/`freeze`/`commit`/`unfreeze` is the richer answer, and the
+ * editor asks it first. This mark is for the case that seam cannot cover — a
+ * world whose bodies are built by ordinary per-scene code with no central
+ * registry to hand a `bodyFor(nodeId)` resolver (every translated import lane),
+ * where the only place node and body meet is the constructor that made both.
+ * Marked nodes reach the SAME four verbs through
+ * {@link createRapierBodyEditing}; this is a second SOURCE for one mechanism,
+ * not a second mechanism.
+ *
+ * ## What to mark
+ *
+ * The node whose pose the body writes — normally the body's own root node. Not
+ * subtree-scoped (unlike `vgaiBuiltInternal`): a child of a body-driven node
+ * inherits its parent's motion through the transform chain, and its own local
+ * pose is still the node's to keep. Mark exactly the node the sync writes.
+ */
+
+import type * as THREE from 'three';
+import { getUserData, setUserData } from '../ecs/user-data';
+import type { RapierEditableBody } from './rapier-physics-adapter';
+
+/**
+ * Declare that `body` owns `node`'s pose: a transform edit on `node` is applied
+ * to `body`, and the next step is what puts the result back on the node.
+ *
+ * Call it where the pair is created. `body` is the game's OWN Rapier body,
+ * passed through unchanged — the parameter type names five of Rapier's own
+ * methods structurally (see {@link RapierEditableBody}) because this repo
+ * legitimately resolves two copies of `@dimforge/rapier3d-compat` whose
+ * `RigidBody` classes are unrelated nominal types.
+ */
+export function markBodyOwnedNode(node: THREE.Object3D, body: RapierEditableBody): void {
+  setUserData(node, 'vgaiBodyOwner', body);
+}
+
+/** The body that owns `node`'s pose, or `undefined` for a node that owns its own. */
+export function bodyOwningNode(
+  node: THREE.Object3D | null | undefined,
+): RapierEditableBody | undefined {
+  const body = getUserData(node, 'vgaiBodyOwner');
+  return body ?? undefined;
+}

package/src/adapter/constraint.ts

@@ -0,0 +1,71 @@
+/**
+ * Format-neutral live mark for source-owned spatial constraints.
+ *
+ * The project capability that performs a solve attaches one or more marks to
+ * the Object3D that owns the constrained pose. The editor reads the marks to
+ * render an ordinary constraint stack and transient viewport handles. This is
+ * observation, not authored data: the owning TS/TSX and its ordinary target /
+ * pole Object3Ds remain the only source of truth.
+ */
+import type * as THREE from 'three';
+import { deleteUserData, getUserData, setUserData } from '../ecs/user-data';
+
+export type ConstraintStatus = 'ready' | 'disabled' | 'unresolved' | 'error';
+
+export interface ConstraintConfig {
+  /** Stable only within this mounted owner. */
+  readonly id: string;
+  readonly type: 'two-bone-ik' | 'ccd-ik' | (string & {});
+  readonly label: string;
+  readonly enabled: boolean;
+  readonly weight: number;
+  /** Evaluation order among constraints attached to this owner. */
+  readonly order: number;
+}
+
+export interface ConstraintSnapshot {
+  readonly status: ConstraintStatus;
+  readonly message?: string;
+  /** Root → effector, using the real bones from the live skeleton. */
+  readonly chain: readonly THREE.Object3D[];
+  readonly target: THREE.Object3D | null;
+  readonly pole: THREE.Object3D | null;
+  /** Effector-to-target distance after the latest solve, in world units. */
+  readonly error: number | null;
+}
+
+export interface ConstraintMark {
+  readonly config: ConstraintConfig;
+  getSnapshot(): ConstraintSnapshot;
+}
+
+export function constraintsOf(
+  object: THREE.Object3D | null | undefined,
+): readonly ConstraintMark[] {
+  const candidate = getUserData(object, 'constraints');
+  if (!Array.isArray(candidate)) return [];
+  return candidate.filter(
+    (entry): entry is ConstraintMark =>
+      Boolean(entry) &&
+      typeof entry === 'object' &&
+      typeof (entry as Partial<ConstraintMark>).getSnapshot === 'function' &&
+      Boolean((entry as Partial<ConstraintMark>).config),
+  );
+}
+
+/** Add or replace one constraint mark without disturbing sibling constraints. */
+export function setConstraintMark(object: THREE.Object3D, mark: ConstraintMark): void {
+  const next = constraintsOf(object).filter((entry) => entry.config.id !== mark.config.id);
+  setUserData(object, 'constraints', [...next, mark]);
+}
+
+/** Remove one mark, or the whole live projection when no id is supplied. */
+export function clearConstraintMark(object: THREE.Object3D, id?: string): void {
+  if (id === undefined) {
+    deleteUserData(object, 'constraints');
+    return;
+  }
+  const next = constraintsOf(object).filter((entry) => entry.config.id !== id);
+  if (next.length === 0) deleteUserData(object, 'constraints');
+  else setUserData(object, 'constraints', next);
+}

package/src/adapter/hierarchy-marks.ts

@@ -0,0 +1,155 @@
+/**
+ * The hierarchy-presentation convention: how a game tells the editor which
+ * parts of its LIVE scene graph are one component instance, and which parts are
+ * implementation rather than content.
+ *
+ * ## Why marks and not a second tree
+ *
+ * The live tree IS the display surface. A hierarchy derived from source would
+ * be a mirror layer — a second model of the world that drifts from the one on
+ * screen — so the boundaries a reader needs have to live ON the nodes. That is
+ * what these marks are, and it is the whole mechanism: a component WRAPS its
+ * functionality and MARKS its root; the editor supports the convention
+ * generically and never learns which library, importer or lane produced the
+ * node.
+ *
+ * ## STRUCTURE IS THE TREE'S JOB. MARKS ONLY CLASSIFY.
+ *
+ * There is deliberately no mark that says "show this row somewhere else". A
+ * group owns its children by CONTAINING them; a prefab owns its parts by
+ * CONTAINING them. If an object reads as belonging under something it is not
+ * parented to, the tree is wrong and the tree is what to fix — because the
+ * panel is not the only reader. `getWorldPosition`, raycasting, disposal,
+ * `traverse`, every physics or gameplay walk and every person reading the
+ * source all follow real parenthood, and a presentation-only "logical parent"
+ * would be true for exactly one of them.
+ *
+ * The usual reason a world gets this wrong is that three's parent chain is a
+ * TRANSFORM chain: `matrixWorld` is unconditionally `parent × local`, so an
+ * object that must not inherit its owner's pose — a physics-driven body writing
+ * a world transform every step, a world-space trail or decal, a follow camera
+ * that must escape its target's rotation — gets mounted at the scene root, and
+ * ownership is lost as a side effect. **That trade is not necessary.** Set
+ * `object.matrixWorldAutoUpdate = false` (three r144+) and the parent's
+ * propagation skips it: the object stays parented where it belongs and its
+ * `matrixWorld` becomes yours to write. Keep it parented, own the matrix, and
+ * the hierarchy needs no help.
+ *
+ * These two marks then have exactly one job left, which is CLASSIFICATION:
+ * which of the objects that really are here is the game, and which is the
+ * machinery underneath it.
+ *
+ * ## What the hierarchy is FOR
+ *
+ * It shows YOUR GAME: the structure you authored, plus the objects your game
+ * makes while it runs. Nothing else. Three consequences, and every rule below
+ * follows from them:
+ *
+ *  - **A spawned object is content.** A bullet you fired, a wave of enemies, a
+ *    prop pulled out of a pool and parented into the level — these are rows.
+ *    They exist, you can select them, and they are usually the exact things you
+ *    opened the panel to look at. An object your game frees stops being a row,
+ *    because it stopped existing.
+ *  - **An implementation artifact is not.** The bones behind a rig, the batched
+ *    renderer behind a particle system, the instanced-mesh pools behind a tile
+ *    field, the `target` object three needs in order to aim a directional
+ *    light: machinery a library or a helper builds so one thing you DID author
+ *    can work. It belongs UNDER that thing, folded, not beside it.
+ *  - **"Not in the source file" is the wrong test for either.** Half of a
+ *    running world is not in the source file — that is what running means.
+ *    Folding spawned gameplay because a document does not name it is the same
+ *    defect as listing bones, in the more damaging direction: the rows it loses
+ *    are the ones you were looking for.
+ *
+ * ## The two marks
+ *
+ * - {@link markComponentRoot} — "this subtree is one instance of `<name>`."
+ *   The editor renders it as ONE row, closed, expandable on demand. Put it on
+ *   the EARLIEST point the node exists: the constructor that makes it, or the
+ *   ref callback that receives it. A component whose root is a plain `<mesh>`
+ *   marks that mesh.
+ * - {@link markBuiltInternal} — "this is IMPLEMENTATION, not content." It is
+ *   **subtree-scoped**: marking the root of a built subtree marks everything
+ *   under it, so a 60-bone rig costs one call and folding is transitive. The
+ *   editor hides these rows and offers them behind the same "Reveal Internals"
+ *   action a source-backed instance's internals already use — revealed rows
+ *   are read-only, because there is no authored source for a rename or a
+ *   reparent to write to.
+ *
+ * An instance therefore reads as the parent of everything meaningful beneath
+ * it: content nested inside an implementation node is listed under the instance
+ * rather than lost with it (the editor's `hierarchy-component-marks.ts` calls
+ * that promotion), so marking a rig does not hide the mesh skinned to it.
+ *
+ * ## Mark it where the subtree is ATTACHED, by whoever attaches it
+ *
+ * A mark belongs at the attach seam: the code that puts an implementation
+ * subtree into the world marks it in the same breath, because that code is the
+ * only thing that knows the subtree is implementation. Not a later sweep of the
+ * tree — "everything present at time T that the source did not name" is the
+ * wrong predicate twice over. It arrives too early for anything attached
+ * asynchronously (a model clone landing after its bytes resolve, a node gated
+ * on an audio decode) and too late in principle for anything attached
+ * afterwards (every spawn) — and were it re-run to catch those, it would
+ * classify each spawned object as implementation, which is the second bullet
+ * above inverted. Attach-seam marking has neither failure: it fires once, at
+ * the moment the answer is known, and an unmarked node is content by default.
+ *
+ * The subtree scope is what keeps this cheap — one call per attached root, not
+ * one per node, so a rig or a pool costs one line at the one place that builds
+ * it.
+ *
+ * ## What is NOT built-internal
+ *
+ * A node your game means as content — even one a class rather than JSX
+ * constructs — is content. `vgaiBuiltInternal` is not "the editor cannot write
+ * this"; that question is `TransformProvider.editability`'s, answered per
+ * channel with a sentence. This mark answers "is this implementation", and
+ * getting it wrong hides real content.
+ *
+ * Both keys live in the typed `userData` registry (`../ecs/user-data.ts`) so
+ * their literal strings are spelled exactly once; this module is the only
+ * reader/writer, which is why the helpers below exist at all rather than
+ * `setUserData` calls scattered through emitters and prefabs.
+ */
+
+import type * as THREE from 'three';
+import { getUserData, setUserData } from '../ecs/user-data';
+
+/**
+ * Declare `node` the root of one component instance, displayed under `name`.
+ *
+ * `name` is the COMPONENT's name (`'Coin'`, `'HeroBox'`), not the instance's —
+ * the instance is already named by `node.name`, and the editor prints both.
+ */
+export function markComponentRoot(node: THREE.Object3D, name: string): void {
+  setUserData(node, 'vgaiComponentRoot', name);
+}
+
+/** The component name `node` is the root of, or `undefined` for an ordinary node. */
+export function componentRootName(node: THREE.Object3D | null | undefined): string | undefined {
+  const name = getUserData(node, 'vgaiComponentRoot');
+  return typeof name === 'string' && name ? name : undefined;
+}
+
+/** Whether `node` is a marked component-instance root. */
+export function isComponentRoot(node: THREE.Object3D | null | undefined): boolean {
+  return componentRootName(node) !== undefined;
+}
+
+/**
+ * Declare `node` (and everything under it) IMPLEMENTATION of whatever node it
+ * sits under, rather than content of its own. Call it on the ROOT of the built
+ * subtree only, at the seam that attaches it — see this module's header for why
+ * the seam and not a sweep.
+ */
+export function markBuiltInternal(node: THREE.Object3D): void {
+  setUserData(node, 'vgaiBuiltInternal', true);
+}
+
+/** Whether `node` itself carries the implementation mark. Ancestry is the
+ *  CALLER's walk — see this module's header for why the mark is subtree-scoped
+ *  but not restamped onto descendants. */
+export function isBuiltInternal(node: THREE.Object3D | null | undefined): boolean {
+  return getUserData(node, 'vgaiBuiltInternal') === true;
+}

package/src/adapter/index.ts

@@ -39,7 +39,6 @@ export type {
   DOMRectLike,
   EditorNode,
   EditorNodeRole,
-  FileMapProvider,
   HierarchyProvider,
   InspectorProvider,
   NodeCreationSite,
@@ -47,8 +46,8 @@ export type {
   PickProvider,
   PropertyDescriptor,
   RectProvider,
-  RootGroup,
-  RootGroupsProvider,
+  RelatedSubjectLink,
+  RelatedSubjectsProvider,
   SelectionProvider,
   SelectionResolution,
   StoriesProvider,

package/src/adapter/ingest/contract-system-adapters.ts

@@ -0,0 +1,174 @@
+/**
+ * Projects a game's declared {@link VgaiGameSystemAdapters}
+ * (`window.vgaiGame.systems.systemAdapters`) onto the host's ordinary
+ * {@link SystemAdapters} bag — the ingest-realm counterpart of a first-party
+ * world's `ctx.registerSystemAdapter`, and the sibling of
+ * `contract-debug-adapter.ts` (which owns the `debug` slot).
+ *
+ * ## Why a projection with a verdict per slot
+ *
+ * The ingestion bar (docs/BRINGING-AN-EXISTING-GAME.md §The ingestion
+ * checklist) admits exactly two terminal states per slot: IMPLEMENTED or
+ * IMPLEMENTED-EMPTY. `SystemAdapters` alone cannot express the second — an
+ * omitted key means "unsupported", which is the same shape as "nobody looked".
+ * So this returns THREE lists, and the caller hands the non-`bound` ones to the
+ * coverage report, where a positively-answered absence prints as terminal and an
+ * unanswered slot prints as a work order.
+ *
+ * ## Why the shape check
+ *
+ * A slot that declares `{}` would otherwise register as "implemented" and light
+ * up an editor panel over an object with no methods. Each slot therefore names
+ * the members its interface makes REQUIRED, and a declaration missing any of
+ * them is `malformed` — reported by name, never silently bound and never
+ * silently dropped. This is the same honesty the anti-shim rule asks of the
+ * other direction: a wrong "present" claim is as much a defect as a wrong
+ * "empty" one.
+ *
+ * Nothing here calls a declared method. Presence and shape only.
+ */
+
+import type { SystemAdapters } from '../system-adapter';
+import type { VgaiGameSystemAdapters, VgaiGameSystemEmpty, VgaiGameSystems } from './game-contract';
+
+/** The slots a game may declare through the contract (`debug` is projected from
+ *  `commands`/`state` instead — see {@link VgaiGameSystemAdapters}). */
+export type ContractSystemSlot = keyof VgaiGameSystemAdapters;
+
+/**
+ * The members each slot's interface makes NON-optional. A declaration missing
+ * one of these cannot honour the interface, whatever else it carries.
+ *
+ * This table is the single place the required surface is spelled; it is checked
+ * against the interfaces by the compiler at the point of use below (each list
+ * is typed as keys of its own adapter), so it cannot drift into naming a member
+ * that does not exist.
+ */
+const REQUIRED_MEMBERS: {
+  [K in ContractSystemSlot]: readonly (keyof NonNullable<SystemAdapters[K]>)[];
+} = {
+  physics: ['ownerOf', 'freeze', 'commit', 'unfreeze'],
+  networking: [
+    'peers',
+    'networkId',
+    'authority',
+    'editable',
+    'getConnectionState',
+    'getRoomInfo',
+    'getReplicationStats',
+    'subscribe',
+  ],
+  navigation: ['hasNavMesh', 'findPath', 'debugMesh'],
+  audio: ['setMuted', 'isMuted'],
+  renderDebug: ['captureFrame'],
+};
+
+/** Fixed slot order, so two reports of the same mount are diffable line for
+ *  line (the same rule the coverage report's row order follows). */
+export const CONTRACT_SYSTEM_SLOTS: readonly ContractSystemSlot[] = [
+  'physics',
+  'networking',
+  'navigation',
+  'audio',
+  'renderDebug',
+];
+
+/** One slot the game positively answered as having nothing behind it. */
+export interface ContractSystemEmptySlot {
+  readonly slot: ContractSystemSlot;
+  /** The game's own source-level evidence, verbatim. */
+  readonly evidence: string;
+}
+
+/** One slot whose declaration could not be honoured, and why. */
+export interface ContractSystemMalformedSlot {
+  readonly slot: ContractSystemSlot;
+  readonly reason: string;
+}
+
+export interface ContractSystemAdapterProjection {
+  /** Real adapters, ready to spread onto a `MountedRoot`'s `systems`. */
+  readonly bound: Partial<Pick<SystemAdapters, ContractSystemSlot>>;
+  /** Slots answered IMPLEMENTED-EMPTY, with the evidence. */
+  readonly empty: readonly ContractSystemEmptySlot[];
+  /** Slots declared but unusable — bound to nothing, reported by name. */
+  readonly malformed: readonly ContractSystemMalformedSlot[];
+}
+
+const EMPTY_PROJECTION: ContractSystemAdapterProjection = {
+  bound: {},
+  empty: [],
+  malformed: [],
+};
+
+function isEmptyRecord(value: object): value is VgaiGameSystemEmpty {
+  return (value as { present?: unknown }).present === false;
+}
+
+function missingMembers(slot: ContractSystemSlot, value: object): string[] {
+  const missing: string[] = [];
+  for (const member of REQUIRED_MEMBERS[slot]) {
+    if (typeof (value as Record<string, unknown>)[member as string] !== 'function') {
+      missing.push(member as string);
+    }
+  }
+  return missing;
+}
+
+/**
+ * Read the declared slots and sort each into exactly one verdict. A game that
+ * declared no `systemAdapters` at all projects to three empty lists — which is
+ * the "nobody answered" case, and is deliberately NOT the same as declaring
+ * every slot empty.
+ */
+export function projectContractSystemAdapters(
+  systems: VgaiGameSystems | undefined | null,
+): ContractSystemAdapterProjection {
+  const declared = systems?.systemAdapters;
+  if (!declared) return EMPTY_PROJECTION;
+
+  const bound: Record<string, unknown> = {};
+  const empty: ContractSystemEmptySlot[] = [];
+  const malformed: ContractSystemMalformedSlot[] = [];
+
+  for (const slot of CONTRACT_SYSTEM_SLOTS) {
+    const value: unknown = declared[slot];
+    if (value === undefined || value === null) continue;
+    if (typeof value !== 'object') {
+      malformed.push({
+        slot,
+        reason: `declared as ${typeof value}; expected an adapter object or { present: false, evidence }`,
+      });
+      continue;
+    }
+    if (isEmptyRecord(value)) {
+      const evidence = (value as VgaiGameSystemEmpty).evidence;
+      if (typeof evidence !== 'string' || evidence.trim() === '') {
+        // An empty claim with no evidence is exactly the "wrong empty claim"
+        // the bar calls a defect — it asserts an absence nobody can re-check.
+        malformed.push({
+          slot,
+          reason: 'declared `present: false` with no `evidence` string to back the absence',
+        });
+        continue;
+      }
+      empty.push({ slot, evidence });
+      continue;
+    }
+    const missing = missingMembers(slot, value);
+    if (missing.length > 0) {
+      malformed.push({
+        slot,
+        reason: `declared an adapter missing required member(s): ${missing.join(', ')}`,
+      });
+      continue;
+    }
+    bound[slot] = value;
+  }
+
+  return {
+    bound: bound as ContractSystemAdapterProjection['bound'],
+    empty,
+    malformed,
+  };
+}