@vgai/engine 0.5.14 → 0.5.16

package/src/adapter/entrypoint-selection-source.ts

@@ -0,0 +1,159 @@
+/**
+ * Serve-time rewrite of an entrypoint's swap-slot key.
+ *
+ * The scenes finder (`adapter/finders/scenes-from-entrypoint-selection.ts`)
+ * READS the same facts this module WRITES: a module-level `const <selection>
+ * = { … }` table, indexed by one identifier whose own module-level `const`
+ * is a string literal (`const activeScene = 'main'`). This is not an
+ * extraction of that finder — the finder stays the adapter-selected discovery
+ * algorithm, import-banned everywhere except the adapter loader. The rewrite
+ * is a host-owned mount parameter: play remounts the same entrypoint with a
+ * different declared key, without a new adapter slot and without mutating
+ * the file on disk.
+ *
+ * `typescript` is the same parser the finder already uses. This module is
+ * host-side only — a game's `vgai.adapter.ts` must not import it.
+ */
+
+import ts from 'typescript';
+
+export type EntrypointSelectionRewrite =
+  | { readonly ok: true; readonly source: string; readonly changed: boolean }
+  | { readonly ok: false; readonly reason: string };
+
+function parse(path: string, source: string): ts.SourceFile {
+  return ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+}
+
+function selectionTable(sf: ts.SourceFile, name: string): ts.ObjectLiteralExpression | undefined {
+  for (const statement of sf.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || declaration.name.text !== name) continue;
+      const initializer = declaration.initializer;
+      if (initializer && ts.isObjectLiteralExpression(initializer)) return initializer;
+    }
+  }
+  return undefined;
+}
+
+function propertyKey(property: ts.ObjectLiteralElementLike): string | undefined {
+  const name = property.name;
+  if (!name) return undefined;
+  if (ts.isIdentifier(name) || ts.isStringLiteral(name)) return name.text;
+  return undefined;
+}
+
+function tableKeys(table: ts.ObjectLiteralExpression): string[] {
+  const keys: string[] = [];
+  for (const property of table.properties) {
+    const key = propertyKey(property);
+    if (key !== undefined) keys.push(key);
+  }
+  return keys;
+}
+
+/** The identifier in `scenes[activeScene]`, or a failure to read one. */
+function indexingIdentifier(sf: ts.SourceFile, selection: string): string | undefined | null {
+  const names = new Set<string>();
+  let unreadable = false;
+  const visit = (node: ts.Node): void => {
+    if (
+      ts.isElementAccessExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === selection
+    ) {
+      if (ts.isIdentifier(node.argumentExpression)) names.add(node.argumentExpression.text);
+      else unreadable = true;
+    }
+    ts.forEachChild(node, visit);
+  };
+  ts.forEachChild(sf, visit);
+  if (names.size === 0 && !unreadable) return undefined;
+  if (names.size !== 1 || unreadable) return null;
+  return [...names][0];
+}
+
+function moduleLevelStringLiteral(sf: ts.SourceFile, name: string): ts.StringLiteral | undefined {
+  for (const statement of sf.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || declaration.name.text !== name) continue;
+      const initializer = declaration.initializer;
+      if (initializer && ts.isStringLiteral(initializer)) return initializer;
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Rewrite the entrypoint so its swap slot mounts `key` instead of the
+ * source-declared occupant.
+ *
+ * Fails (never guesses) when the source is not the template's shape: no
+ * table, a key the table does not declare, or an index that is not a
+ * module-level `const` string. A no-op rewrite (`key` already at the slot)
+ * is still `ok` — remounting the same key is a real restart.
+ */
+export function rewriteEntrypointSelectionKey(
+  source: string,
+  path: string,
+  selection: string,
+  key: string,
+): EntrypointSelectionRewrite {
+  const sf = parse(path, source);
+  const table = selectionTable(sf, selection);
+  if (!table) {
+    return {
+      ok: false,
+      reason:
+        `${path} declares no module-level \`const ${selection} = { … }\` selection table, ` +
+        'so the host cannot remount it at another key.',
+    };
+  }
+  const keys = tableKeys(table);
+  if (!keys.includes(key)) {
+    return {
+      ok: false,
+      reason:
+        `"${key}" is not a key of ${path}'s \`${selection}\` table ` +
+        `(known: ${keys.length > 0 ? keys.join(', ') : 'none'}).`,
+    };
+  }
+  const identifier = indexingIdentifier(sf, selection);
+  if (identifier === undefined) {
+    return {
+      ok: false,
+      reason: `${path} never indexes \`${selection}\`, so there is no slot key to rewrite.`,
+    };
+  }
+  if (identifier === null) {
+    return {
+      ok: false,
+      reason:
+        `${path} indexes \`${selection}\` with something other than one single identifier, ` +
+        'so the host cannot rewrite the key it mounts.',
+    };
+  }
+  const literal = moduleLevelStringLiteral(sf, identifier);
+  if (!literal) {
+    return {
+      ok: false,
+      reason:
+        `${path} indexes \`${selection}\` with \`${identifier}\`, which is not a ` +
+        'module-level `const` bound to a string literal — the running game cannot be ' +
+        'sent to another key by rewriting the slot.',
+    };
+  }
+  if (literal.text === key) return { ok: true, source, changed: false };
+  const start = literal.getStart(sf);
+  const end = literal.getEnd();
+  const quote = source[start] ?? "'";
+  return {
+    ok: true,
+    source: `${source.slice(0, start)}${quote}${key}${quote}${source.slice(end)}`,
+    changed: true,
+  };
+}

package/src/adapter/finders/scenes-from-entrypoint-selection.ts

@@ -15,7 +15,13 @@
  *
  * Two answers, and the difference is declared rather than sniffed:
  *   - the adapter names a `selection` identifier ⇒ read that module-level
- *     table and answer one entry per key, each reachable through it;
+ *     table and answer one entry per key, each reachable through it — plus
+ *     WHICH key the entrypoint indexes it with right now (`scenes[activeScene]`
+ *     → `const activeScene = 'main'`), marked `reach.active`. That reference is
+ *     load-bearing for the same reason the table is: the running world renders
+ *     exactly that key's composition, which is why the host can treat the
+ *     active entry as the region's own standing document rather than a second
+ *     tab beside it;
  *   - the adapter names none ⇒ the entrypoint mounts ONE composition, and the
  *     answer is the single-scene DEGENERATE table: the region's own
  *     composition, opened by mounting the region.
@@ -152,6 +158,109 @@ function propertyKey(property: ts.ObjectLiteralElementLike): string | undefined
   return undefined;
 }
 
+/**
+ * The identifier the entrypoint INDEXES the selection table with — the
+ * `activeScene` in `scenes[activeScene]`.
+ *
+ * `undefined` when the module never indexes the table, or indexes it with
+ * anything other than one single identifier: both are honest "cannot be read",
+ * and the caller turns each into its own note.
+ */
+function indexingIdentifier(sf: ts.SourceFile, selection: string): string | undefined | null {
+  const names = new Set<string>();
+  let unreadable = false;
+  const visit = (node: ts.Node): void => {
+    if (
+      ts.isElementAccessExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === selection
+    ) {
+      if (ts.isIdentifier(node.argumentExpression)) names.add(node.argumentExpression.text);
+      else unreadable = true;
+    }
+    ts.forEachChild(node, visit);
+  };
+  ts.forEachChild(sf, visit);
+  if (names.size === 0 && !unreadable) return undefined; // never indexed at all
+  if (names.size !== 1 || unreadable) return null; // indexed, but not readably
+  return [...names][0];
+}
+
+/**
+ * The string a module-level `const <name> = '…'` binds, or `undefined`.
+ *
+ * `const` and a STRING LITERAL are both required: a `let` can be reassigned and
+ * a computed initializer is not a fact the source states, so neither can be
+ * reported as the key the game executes. A type annotation
+ * (`const activeScene: keyof typeof scenes = 'main'`) is irrelevant here — the
+ * initializer is what runs.
+ */
+function moduleLevelString(sf: ts.SourceFile, name: string): string | undefined {
+  for (const statement of sf.statements) {
+    if (!ts.isVariableStatement(statement)) continue;
+    if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || declaration.name.text !== name) continue;
+      const initializer = declaration.initializer;
+      if (initializer && ts.isStringLiteral(initializer)) return initializer.text;
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * WHICH key the entrypoint mounts at its slot right now, read off the source
+ * the game itself executes.
+ *
+ * Every failure is a NOTE and answers `undefined`: an unread active key costs
+ * a retitle, while a guessed one would open the wrong composition as the
+ * region's own document.
+ */
+function activeSelectionKey(
+  entrypoint: EntrypointSource,
+  sf: ts.SourceFile,
+  selection: string,
+  keys: readonly string[],
+  notes: string[],
+): string | undefined {
+  const identifier = indexingIdentifier(sf, selection);
+  if (identifier === undefined) {
+    notes.push(
+      `scenesFromEntrypointSelection: ${entrypoint.path} never indexes \`${selection}\`, so ` +
+        'which of its compositions the entrypoint mounts is not stated in the source and no ' +
+        'entry is settled as the active one.',
+    );
+    return undefined;
+  }
+  if (identifier === null) {
+    notes.push(
+      `scenesFromEntrypointSelection: ${entrypoint.path} indexes \`${selection}\` with ` +
+        'something other than one single identifier, so the key it mounts cannot be read ' +
+        'statically.',
+    );
+    return undefined;
+  }
+  const key = moduleLevelString(sf, identifier);
+  if (key === undefined) {
+    notes.push(
+      `scenesFromEntrypointSelection: ${entrypoint.path} indexes \`${selection}\` with ` +
+        `\`${identifier}\`, which is not a module-level \`const\` bound to a string literal, ` +
+        'so the key it mounts cannot be read statically.',
+    );
+    return undefined;
+  }
+  if (!keys.includes(key)) {
+    notes.push(
+      `scenesFromEntrypointSelection: ${entrypoint.path} mounts \`${selection}\` under ` +
+        `"${key}", which is not a key of that table. The entrypoint and its own selection ` +
+        'table disagree.',
+    );
+    return undefined;
+  }
+  return key;
+}
+
 /** The identifier a selection entry's value names, if it names one at all. */
 function propertyIdentifier(property: ts.ObjectLiteralElementLike): string | undefined {
   if (ts.isShorthandPropertyAssignment(property)) return property.name.text;
@@ -219,14 +328,17 @@ function degenerateEntry(entrypoint: EntrypointSource, sf: ts.SourceFile): Scene
   };
 }
 
-/** One entry per key of the entrypoint's own selection table. */
+/**
+ * One entry per key of the entrypoint's own selection table, plus WHICH of
+ * them the entrypoint currently mounts at the slot (`active`).
+ */
 function selectionEntries(
   entrypoint: EntrypointSource,
   sf: ts.SourceFile,
   selection: string,
   resolveModule: ScenesFromEntrypointSelectionInput['resolveModule'],
   notes: string[],
-): SceneEntry[] {
+): { entries: SceneEntry[]; active: string | undefined } {
   const table = selectionTable(sf, selection);
   if (!table) {
     notes.push(
@@ -234,11 +346,12 @@ function selectionEntries(
         `\`const ${selection} = { … }\` selection table. Nothing is assumed in its ` +
         'place — fix the adapter’s `selection` or the entrypoint.',
     );
-    return [];
+    return { entries: [], active: undefined };
   }
 
   const bindings = importedBindings(sf);
-  const entries: SceneEntry[] = [];
+  const keys: string[] = [];
+  const built: { key: string; label: string; source: SceneSource | undefined }[] = [];
   for (const property of table.properties) {
     const key = propertyKey(property);
     if (key === undefined) {
@@ -249,23 +362,35 @@ function selectionEntries(
       continue;
     }
     const identifier = propertyIdentifier(property);
-    const source = sourceFor(
-      identifier ? bindings.get(identifier) : undefined,
-      entrypoint.path,
-      resolveModule,
-    );
-    entries.push({
-      id: key,
+    keys.push(key);
+    built.push({
+      key,
       label: identifier ?? key,
-      kind: 'scene',
-      region: entrypoint.regionId,
-      authorable: true,
-      reach: { kind: 'entrypoint-selection', selection, key },
-      ...(source ? { source } : {}),
-      finder: 'scenesFromEntrypointSelection',
+      source: sourceFor(
+        identifier ? bindings.get(identifier) : undefined,
+        entrypoint.path,
+        resolveModule,
+      ),
     });
   }
-  return entries;
+
+  const active = activeSelectionKey(entrypoint, sf, selection, keys, notes);
+  const entries = built.map(({ key, label, source }) => ({
+    id: key,
+    label,
+    kind: 'scene' as const,
+    region: entrypoint.regionId,
+    authorable: true,
+    reach: {
+      kind: 'entrypoint-selection' as const,
+      selection,
+      key,
+      ...(key === active ? { active: true } : {}),
+    },
+    ...(source ? { source } : {}),
+    finder: 'scenesFromEntrypointSelection' as const,
+  }));
+  return { entries, active };
 }
 
 /**
@@ -280,6 +405,7 @@ export function scenesFromEntrypointSelection(
 ): FinderResult {
   const notes: string[] = [];
   const entries: SceneEntry[] = [];
+  const active: string[] = [];
 
   for (const entrypoint of targetedEntrypoints(params, input.entrypoints, notes)) {
     if (entrypoint.source === null) {
@@ -290,15 +416,20 @@ export function scenesFromEntrypointSelection(
       continue;
     }
     const sf = parse(entrypoint.path, entrypoint.source);
-    entries.push(
-      ...(params.selection === undefined
-        ? [degenerateEntry(entrypoint, sf)]
-        : selectionEntries(entrypoint, sf, params.selection, input.resolveModule, notes)),
-    );
+    if (params.selection === undefined) {
+      entries.push(degenerateEntry(entrypoint, sf));
+      continue;
+    }
+    const found = selectionEntries(entrypoint, sf, params.selection, input.resolveModule, notes);
+    entries.push(...found.entries);
+    if (found.active !== undefined) active.push(found.active);
   }
 
-  // One candidate settles the default; two or more is a choice, and a choice
-  // belongs to the adapter author.
-  const only = entries.length === 1 ? entries[0] : undefined;
-  return only ? { entries, default: only.id, notes } : { entries, notes };
+  // The ACTIVE key settles the default outright: the entrypoint states which
+  // composition it mounts, so this is the finder READING an answer rather than
+  // choosing between candidates. Failing that, one candidate settles it; two or
+  // more is a choice, and a choice belongs to the adapter author.
+  const settled =
+    active.length === 1 ? active[0] : entries.length === 1 ? entries[0]?.id : undefined;
+  return settled !== undefined ? { entries, default: settled, notes } : { entries, notes };
 }

package/src/adapter/first-party-systems.ts

@@ -20,6 +20,7 @@ import type {
   AudioMeterFrame,
   AudioMeterHandle,
   AudioRecordingHandle,
+  NavBakeParams,
   NavigationAdapter,
   NavPoint,
 } from './system-adapter';
@@ -229,14 +230,27 @@ export function createAudioSystemAdapter(audio: GameAudio): AudioAdapter {
 
 /** First-party `NavigationAdapter` over the engine `NavMeshManager` — the
  *  blessed recast implementation, including the optional bake/export/crowd
- *  capabilities the editor's Navigation panel binds through. */
-export function createNavigationAdapter(nav: NavMeshManager): NavigationAdapter {
+ *  capabilities the editor's Navigation panel binds through.
+ *
+ * `clear` is deliberately owner-supplied: a manager cannot know which gameplay
+ * objects retain CrowdAgent handles, so disposing it generically would leave
+ * those handles pointing at freed WASM memory. A game that grants clear owns
+ * releasing/rebinding those references in the same callback. `bake` may be
+ * overridden for the same reason when a live crowd must be rebuilt. */
+export function createNavigationAdapter(
+  nav: NavMeshManager,
+  ownerCapabilities: {
+    readonly bake?: (meshes: THREE.Mesh[], params?: NavBakeParams) => boolean;
+    readonly clear?: (scene: THREE.Scene) => void;
+  } = {},
+): NavigationAdapter {
   return {
     hasNavMesh: () => nav.hasNavMesh(),
     findPath: (start: NavPoint, end: NavPoint) => nav.findPath(start, end) as NavPoint[],
     debugMesh: (scene: THREE.Scene) => nav.getDebugMesh(scene) as unknown as THREE.Object3D | null,
-    bake: (meshes, params) => nav.buildFromMeshes(meshes, params),
+    bake: ownerCapabilities.bake ?? ((meshes, params) => nav.buildFromMeshes(meshes, params)),
     exportData: () => nav.exportData(),
+    ...(ownerCapabilities.clear ? { clear: ownerCapabilities.clear } : {}),
     crowdAgents: () => nav.getCrowdAgents(),
   };
 }

package/src/adapter/index.ts

@@ -33,6 +33,7 @@ export type {
   AuthoringCapabilities,
   AuthoringProvenance,
   AuthoringProviderKey,
+  AuthoringTruth,
   BoxEditProvider,
   BoxEditReferencePoint,
   ColorSampleProvider,
@@ -40,7 +41,6 @@ export type {
   ComponentInstanceDescription,
   ComponentInstanceOverride,
   ComponentInstancesProvider,
-  CreationSiteProvider,
   DOMRectLike,
   EditorNode,
   EditorNodeRole,
@@ -62,12 +62,18 @@ export type {
   SpatialPoint3,
   StoriesProvider,
   StoryRef,
+  StructuralClipboardOutcome,
+  StructuralIdsWrite,
+  StructuralIdWrite,
+  StructuralWriteOutcome,
   StructureProvider,
   TextProvider,
   TransformChannel,
   TransformEditability,
   TransformObservation,
   TransformProvider,
+  TransformSourceCommitProvider,
+  TruthProvider,
   WriteAck,
   WriteAnchorKind,
 } from './authoring';
@@ -77,6 +83,11 @@ export {
   measureAuthoringProviders,
   WRITE_ANCHOR_KINDS,
 } from './authoring';
+export {
+  AUTHORING_ADAPTER_SHAPE,
+  AUTHORING_PROVIDER_SHAPES,
+  HIERARCHY_PROVIDER_SHAPE,
+} from './authoring-seam-contract';
 export type { ColyseusNetworkingConfig } from './colyseus-networking-adapter';
 export type {
   CanvasHostContext,
@@ -97,6 +108,32 @@ export type {
   SurfaceAdapter,
   SurfaceAdapterFor,
 } from './root-adapter';
+export {
+  MOUNTED_CANVAS_SURFACE_SHAPE,
+  MOUNTED_DOM_SURFACE_SHAPE,
+  MOUNTED_ROOT_BASE_SHAPE,
+  MOUNTED_THREE_SURFACE_SHAPE,
+  ROOT_ADAPTER_SHAPE,
+  ROOT_STATE_OBSERVER_SHAPE,
+} from './root-seam-contract';
+export type {
+  SeamEvidenceOutcome,
+  SeamEvidenceReceipt,
+  SeamEvidenceSource,
+  SeamEvidenceState,
+  SeamEvidenceVerdict,
+  SeamProofStage,
+  SeamShape,
+} from './seam-evidence';
+export {
+  defineSeamShape,
+  gradeSeamCarrier,
+  gradeSeamEvidence,
+  inspectSeamShape,
+  SEAM_PROOF_STAGES,
+  SeamEvidenceLedger,
+  seamStageAtLeast,
+} from './seam-evidence';
 export type { MountedSetupThreeRoot, SetupThreeRootConfig } from './setup-three-root-adapter';
 export type {
   AudioAdapter,
@@ -111,6 +148,7 @@ export type {
   CameraRuntimeSnapshot,
   CameraRuntimeTransition,
   ConnectionState,
+  DebugAdapter,
   NavCrowdAgentState,
   NavigationAdapter,
   NavPoint,
@@ -136,4 +174,16 @@ export type {
 /** The two narrowings of the tagged `SystemAdapters['physics']` union — see
  *  `PhysicsAdapter`'s comment for why it is tagged at all. */
 export { displayKeyedPhysics, nodeKeyedPhysics } from './system-adapter';
+export {
+  AUDIO_ADAPTER_SHAPE,
+  CAMERA_ADAPTER_SHAPE,
+  DEBUG_ADAPTER_SHAPE,
+  NAVIGATION_ADAPTER_SHAPE,
+  NETWORKING_ADAPTER_SHAPE,
+  PHYSICS_2D_ADAPTER_SHAPE,
+  PHYSICS_ADAPTER_SHAPE,
+  RENDER_DEBUG_ADAPTER_SHAPE,
+  SYSTEM_ADAPTERS_SHAPE,
+  SYSTEM_PROVIDER_SHAPES,
+} from './system-seam-contract';
 export type { Transform, TransformOwner } from './transform';

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

@@ -43,7 +43,16 @@
  */
 
 import type { SystemAdapters } from '../system-adapter';
+import {
+  AUDIO_ADAPTER_SHAPE,
+  CAMERA_ADAPTER_SHAPE,
+  NAVIGATION_ADAPTER_SHAPE,
+  NETWORKING_ADAPTER_SHAPE,
+  PHYSICS_ADAPTER_SHAPE,
+  RENDER_DEBUG_ADAPTER_SHAPE,
+} from '../system-seam-contract';
 import type { VgaiGameSystemAdapters, VgaiGameSystemEmpty, VgaiGameSystems } from './game-contract';
+import { GAME_SYSTEM_ADAPTERS_SHAPE } from './game-contract-seams';
 
 /** The slots a game may declare through the contract (`debug` is projected from
  *  `commands`/`state` instead — see {@link VgaiGameSystemAdapters}). */
@@ -58,25 +67,14 @@ export type ContractSystemSlot = keyof VgaiGameSystemAdapters;
  * 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'],
-  camera: ['snapshot', 'subscribe'],
-  renderDebug: ['captureFrame'],
-};
+const SYSTEM_SHAPES = {
+  physics: PHYSICS_ADAPTER_SHAPE,
+  networking: NETWORKING_ADAPTER_SHAPE,
+  navigation: NAVIGATION_ADAPTER_SHAPE,
+  audio: AUDIO_ADAPTER_SHAPE,
+  camera: CAMERA_ADAPTER_SHAPE,
+  renderDebug: RENDER_DEBUG_ADAPTER_SHAPE,
+} as const satisfies Record<ContractSystemSlot, object>;
 
 /**
  * The render surface a declaration is being read ON — the same three words
@@ -100,14 +98,9 @@ const PHYSICS_KEYING_BY_SURFACE: Readonly<Record<ContractSurface, 'node-id' | 'd
 
 /** 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',
-  'camera',
-  'renderDebug',
-];
+export const CONTRACT_SYSTEM_SLOTS = Object.keys(
+  GAME_SYSTEM_ADAPTERS_SHAPE,
+) as ContractSystemSlot[];
 
 /** One slot the game positively answered as having nothing behind it. */
 export interface ContractSystemEmptySlot {
@@ -143,9 +136,12 @@ function isEmptyRecord(value: object): value is VgaiGameSystemEmpty {
 
 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);
+  for (const [member, spec] of Object.entries(
+    SYSTEM_SHAPES[slot] as Readonly<Record<string, { readonly optional: boolean }>>,
+  )) {
+    if (spec.optional) continue;
+    if (typeof (value as Record<string, unknown>)[member] !== 'function') {
+      missing.push(member);
     }
   }
   return missing;