@vgai/engine 0.5.15 → 0.5.17

package/src/adapter/adapter-module.ts

@@ -100,18 +100,6 @@ export interface AdapterRegion {
   readonly id: string;
   /** What the host hands this root. */
   readonly surface: AdapterSurface;
-  /**
-   * `true` = this region grades the game's own DEV LAYER (the manifest root's
-   * `dev: true`), not shipped game content.
-   *
-   * Carried here because a dev root occupies the same MEDIUM as the content
-   * root beside it — a dev GUI is a `dom` root next to the HUD's `dom` root —
-   * and anything that maps a subject to "the region on this surface" would
-   * otherwise be choosing between them by array order. A region consumer that
-   * means shipped content says so by skipping `dev` regions (the loader's
-   * `regionForSurface` does), rather than by guessing which one matched.
-   */
-  readonly dev: boolean;
   /** Projection library, by name. */
   readonly projector: ProjectorName;
   /**
@@ -162,8 +150,68 @@ export interface AdapterRegion {
    * how a declaration slot turns back into a language.
    */
   readonly include?: readonly string[];
+  /**
+   * Surfaces this root mounts BESIDE {@link AdapterRegion.surface}, each with
+   * the source files that render on it. Together with `surface` — the manifest
+   * root's own adapter, which is always the PRIMARY — this states the root's
+   * FULL mounted surface set (decision, 2026-08-16; ARCHITECTURE-CORE §The
+   * editor protocol).
+   *
+   * A root is not always one surface. The shipped case is an R3F game whose
+   * `three` root mounts a canvas AND adopts a DOM HUD beside it
+   * (`adoptGameDomRoot` already adopts the pair together): its HUD modules
+   * render react-dom host elements, and `userData-oid` on a `<div>` is a prop
+   * react-dom does not recognize, so the editor must know they are the `dom`
+   * half. Before this slot there was nowhere to say so — `id` names the
+   * manifest root this region grades, so a second `dom` region for such a root
+   * would either name a root the host would try to MOUNT (fabrication, which
+   * the anti-shim rule forbids) or name no root at all.
+   *
+   * Each mount's `include` is REQUIRED and carries the same glob vocabulary as
+   * {@link AdapterRegion.include} (`**`, `*`, `?`). A mount with no files would
+   * declare a surface without saying which source renders on it, which answers
+   * no question any reader asks.
+   *
+   * READER: the same one — `resolveFileRegion`'s rung 1. A file claimed by a
+   * region's own `include` AND by a mount is a contradiction in the game's own
+   * declaration and settles nothing, exactly as two regions claiming one file
+   * do; it falls through to reach, and failing that to the caller's loud
+   * ambiguous path.
+   *
+   * {@link regionsFromManifestRoots} emits none: the manifest states one
+   * adapter per root and NOTHING infers a second surface from source text.
+   * Where the declaration and what a file renders disagree, the disagreement is
+   * reported as drift (the editor's `OID003`), never resolved by reading bytes.
+   */
+  readonly mounts?: readonly AdapterRegionMount[];
 }
 
+/**
+ * One ADDITIONAL surface a root mounts, and the source files that render on it.
+ * See {@link AdapterRegion.mounts}.
+ */
+export interface AdapterRegionMount {
+  /** The surface this part of the root mounts on. */
+  readonly surface: AdapterSurface;
+  /** Project-relative globs (`**`, `*`, `?`) naming the files that render here. */
+  readonly include: readonly string[];
+}
+
+const AdapterRegionMountSchema = z
+  .object({
+    surface: z
+      .enum(['three', 'canvas', 'dom'])
+      .describe('An additional surface this root mounts, beside the manifest root’s own adapter'),
+    include: z
+      .array(z.string().min(1))
+      .min(1)
+      .describe(
+        'Project-relative globs (`**`, `*`, `?`) naming the source files that render on this ' +
+          'additional surface',
+      ),
+  })
+  .strict();
+
 const AdapterRegionBasisSchema = z
   .object({
     up: z.enum(['y', 'z']).describe('World axis pointing away from the ground'),
@@ -175,12 +223,6 @@ const AdapterRegionSchema = z
   .object({
     id: z.string().min(1).describe('Manifest root id this region grades'),
     surface: z.enum(['three', 'canvas', 'dom']).describe('Render surface the host hands this root'),
-    dev: z
-      .boolean()
-      .describe(
-        "true = this region grades the game's own dev layer, not shipped content (the " +
-          "manifest root's `dev: true`)",
-      ),
     projector: z.enum(PROJECTOR_NAMES).describe('Projection library serving this surface, by name'),
     dialect: z
       .string()
@@ -204,6 +246,14 @@ const AdapterRegionSchema = z
         'Project-relative globs (`**`, `*`, `?`) naming source files this region owns, for files ' +
           'no root entry’s import closure reaches; a declared include wins over reach',
       ),
+    mounts: z
+      .array(AdapterRegionMountSchema)
+      .min(1)
+      .optional()
+      .describe(
+        'Surfaces this root mounts BESIDE its own adapter, each with the files that render on ' +
+          'them; with `surface`, the root’s full mounted surface set',
+      ),
   })
   .strict();
 
@@ -220,6 +270,73 @@ const RegionBindingSchema = z.union([
   z.array(AdapterRegionSchema).min(1),
 ]);
 
+/**
+ * The per-region PARAMETERS the `'manifest-roots'` rule takes — see
+ * {@link AdapterDefinition.regionIncludes}. Exactly the two fields of an
+ * {@link AdapterRegion} the mechanical derivation cannot produce, because
+ * neither is a fact the manifest states: which files a region owns beyond
+ * its entry's reach, and which surfaces its root mounts beside its own.
+ */
+export interface AdapterRegionOverlay {
+  /** See {@link AdapterRegion.include}. */
+  readonly include?: readonly string[];
+  /** See {@link AdapterRegion.mounts}. */
+  readonly mounts?: readonly AdapterRegionMount[];
+}
+
+const AdapterRegionOverlaySchema = z
+  .object({
+    include: z
+      .array(z.string().min(1))
+      .min(1)
+      .optional()
+      .describe(
+        'Project-relative globs (`**`, `*`, `?`) naming source files this derived region owns, ' +
+          'for files no root entry’s import closure reaches; a declared include wins over reach',
+      ),
+    mounts: z
+      .array(AdapterRegionMountSchema)
+      .min(1)
+      .optional()
+      .describe(
+        'Surfaces this root mounts BESIDE its own adapter, each with the files that render on ' +
+          'them; with the derived region’s own surface, the root’s full mounted surface set',
+      ),
+  })
+  .strict()
+  .refine((value) => value.include !== undefined || value.mounts !== undefined, {
+    message:
+      'regionIncludes entry declares neither `include` nor `mounts` — an empty overlay states ' +
+      'nothing the derivation did not already say. Remove it, or name the files it owns.',
+  });
+
+/**
+ * PARAMETERS FOR THE RULE, keyed by manifest root id (decision, 2026-08-17;
+ * ARCHITECTURE-CORE §The editor protocol, "Declared includes LAYER onto the
+ * manifest-roots rule").
+ *
+ * The finder-selection shape, one level up: `regions: 'manifest-roots'` SELECTS
+ * the mechanical derivation, and this table DECLARES the per-region parameters
+ * it cannot derive. The two compose — {@link regionsFromManifestRoots} merges
+ * them — so a first-party project states one include without hand-writing its
+ * whole region table, and adding a root still grows the table for free.
+ *
+ * Illegal beside an explicit `regions` LIST, and rejected by name: that form is
+ * the full REPLACEMENT, and its entries carry `include`/`mounts` themselves.
+ * Two homes for one fact is how a declaration goes stale in one of them.
+ *
+ * MEASURED BASIS (PR #2281, verified twice): the region binding was
+ * replace-only, so no `nativeAdapter()` project could declare a single include
+ * without restating every region — which is what blocked the source-text R3F
+ * floor's retirement across the five shipped 3D projects.
+ */
+const RegionIncludesSchema = z
+  .record(z.string().min(1), AdapterRegionOverlaySchema)
+  .describe(
+    'Per-region parameters for the `manifest-roots` rule, keyed by manifest root id: the ' +
+      '`include` globs and `mounts` surfaces the mechanical derivation cannot produce',
+  );
+
 /**
  * The MECHANICAL derivation behind the `'manifest-roots'` rule: one region per
  * declared root, its surface and adapter identity read straight off the
@@ -228,13 +345,20 @@ const RegionBindingSchema = z.union([
  *
  * The per-surface library table below is an ENGINE fact, stated once:
  *
- * | root `adapter`        | projector | dialect       | anchors                            |
- * |-----------------------|-----------|---------------|------------------------------------|
- * | `three`               | `three`   | `r3f`         | source-prop, construction-literal   |
- * | `canvas`              | `pixi`    | `pixi-react`  | source-prop, construction-literal   |
- * | `dom`                 | `dom`     | `jsx`         | source-prop                        |
- * | `{module,surface}`    | (surface) | `null`        | live-only                          |
- * | `{ingest,surface}`    | (surface) | `null`        | live-only                          |
+ * | root `adapter`        | projector | dialect       | anchors                                              |
+ * |-----------------------|-----------|---------------|------------------------------------------------------|
+ * | `three`               | `three`   | `r3f`         | source-prop, source-structure, construction-literal  |
+ * | `canvas`              | `pixi`    | `pixi-react`  | source-prop, source-structure, construction-literal  |
+ * | `dom`                 | `dom`     | `jsx`         | source-prop, source-structure                        |
+ * | `{module,surface}`    | (surface) | `null`        | live-only                                            |
+ * | `{ingest,surface}`    | (surface) | `null`        | live-only                                            |
+ *
+ * `source-structure` rides with every first-party dialect because all three
+ * write through the SAME structural door (`/__ui-source/struct`) — a region
+ * that can rewrite a JSX attribute in a file can rewrite that file's element
+ * tree. It is listed separately rather than folded into `source-prop` because
+ * they are different doors: a lane could lose one and keep the other, and the
+ * matrix has to be able to say so.
  *
  * A module/ingest root's truth is the game's own source, which no first-party
  * dialect writer authors — so it declares `live-only` rather than implying a
@@ -244,46 +368,82 @@ const RegionBindingSchema = z.union([
  * Every derived region carries {@link NATIVE_REGION_BASIS} outright, so the
  * editor's ground plane READS a declaration on the native path too — the
  * default is published, never assumed at the read site.
+ *
+ * It DERIVES no {@link AdapterRegion.include} and no {@link AdapterRegion.mounts},
+ * and there is no derivation that could: the manifest states ONE adapter per
+ * root and names only its entry, so a root's extra owned files and its second
+ * mounted surface are facts only the game can state. It states them as
+ * `regionIncludes` PARAMETERS, which this function merges onto the region it
+ * derives for that root — the rule stays selected, the parameters are declared
+ * (ARCHITECTURE-CORE §The editor protocol, "Declared includes LAYER onto the
+ * manifest-roots rule"). A key naming no declared root merges onto nothing;
+ * the LOADER reports that, because only it can see both sides.
  */
-export function regionsFromManifestRoots(roots: readonly ResolvedAdapterRoot[]): AdapterRegion[] {
-  return roots.map((root) => {
-    const surface = root.surface;
-    const dev = root.dev;
-    const firstParty = root.adapter.type === 'builtin';
-    const projector: ProjectorName = surface === 'canvas' ? 'pixi' : surface;
-    const basis = NATIVE_REGION_BASIS;
-    if (!firstParty) {
-      return {
-        id: root.id,
-        surface,
-        dev,
-        projector,
-        dialect: null,
-        anchors: ['live-only'] as const,
-        basis,
-      };
-    }
-    if (surface === 'dom') {
-      return {
-        id: root.id,
-        surface,
-        dev,
-        projector,
-        dialect: 'jsx',
-        anchors: ['source-prop'] as const,
-        basis,
-      };
-    }
+export function regionsFromManifestRoots(
+  roots: readonly ResolvedAdapterRoot[],
+  regionIncludes: Readonly<Record<string, AdapterRegionOverlay>> = {},
+): AdapterRegion[] {
+  return roots.map((root) => ({
+    ...derivedRegion(root),
+    ...overlayOf(regionIncludes[root.id]),
+  }));
+}
+
+/** The declared half of a merged region — omitted keys leave the derived
+ *  region untouched, so an overlay can only ADD what the rule cannot derive. */
+function overlayOf(overlay: AdapterRegionOverlay | undefined): Partial<AdapterRegion> {
+  if (!overlay) return {};
+  return {
+    ...(overlay.include ? { include: overlay.include } : {}),
+    ...(overlay.mounts ? { mounts: overlay.mounts } : {}),
+  };
+}
+
+/** Region ids an overlay names that no declared root answers to. A typo here
+ *  would otherwise be a declaration that silently does nothing, which is the
+ *  failure class the whole declaration lane exists to end. */
+export function unmatchedRegionIncludeIds(
+  roots: readonly ResolvedAdapterRoot[],
+  regionIncludes: Readonly<Record<string, AdapterRegionOverlay>>,
+): string[] {
+  const declared = new Set(roots.map((root) => root.id));
+  return Object.keys(regionIncludes).filter((id) => !declared.has(id));
+}
+
+/** One root's region, before any declared parameters are merged onto it. */
+function derivedRegion(root: ResolvedAdapterRoot): AdapterRegion {
+  const surface = root.surface;
+  const firstParty = root.adapter.type === 'builtin';
+  const projector: ProjectorName = surface === 'canvas' ? 'pixi' : surface;
+  const basis = NATIVE_REGION_BASIS;
+  if (!firstParty) {
     return {
       id: root.id,
       surface,
-      dev,
       projector,
-      dialect: surface === 'three' ? 'r3f' : 'pixi-react',
-      anchors: ['source-prop', 'construction-literal'] as const,
+      dialect: null,
+      anchors: ['live-only'] as const,
       basis,
     };
-  });
+  }
+  if (surface === 'dom') {
+    return {
+      id: root.id,
+      surface,
+      projector,
+      dialect: 'jsx',
+      anchors: ['source-prop', 'source-structure'] as const,
+      basis,
+    };
+  }
+  return {
+    id: root.id,
+    surface,
+    projector,
+    dialect: surface === 'three' ? 'r3f' : 'pixi-react',
+    anchors: ['source-prop', 'source-structure', 'construction-literal'] as const,
+    basis,
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -292,9 +452,7 @@ export function regionsFromManifestRoots(roots: readonly ResolvedAdapterRoot[]):
 
 /**
  * The rule form of a finder's region targeting: every region the host mounts
- * from an exported composition (a root with an `entry`) that is not a declared
- * DEV layer. A dev root is the game's own dev GUI — the manifest already says
- * so (`dev: true`), so skipping it reads a declaration rather than guessing.
+ * from an exported composition — a root with an `entry`.
  */
 export const EXPORTED_COMPOSITION_REGIONS = 'exported-composition-regions';
 
@@ -385,10 +543,44 @@ const FinderSelectionSchema = z.union([
 export type SceneReach =
   /** Mounting the region IS opening it — the single-composition degenerate case. */
   | { readonly kind: 'root-mount' }
-  /** The entrypoint's own selection table reaches it under `key`. */
-  | { readonly kind: 'entrypoint-selection'; readonly selection: string; readonly key: string }
+  /**
+   * The entrypoint's own selection table reaches it under `key`.
+   *
+   * `active` is the SECOND load-bearing fact about the same slot: the
+   * entrypoint indexes its table with one key right now (`scenes[activeScene]`),
+   * and that key's composition is literally what mounting the region renders.
+   * So an active entry is the region's own standing document — it NAMES that
+   * document rather than earning a second one beside it, exactly as
+   * `root-mount` does. Absent means "not known to be the one at the slot",
+   * which is the honest answer whenever the key cannot be read statically; it
+   * is never a guess, and it is per-entry because two regions each have their
+   * own slot with its own occupant.
+   */
+  | {
+      readonly kind: 'entrypoint-selection';
+      readonly selection: string;
+      readonly key: string;
+      readonly active?: boolean;
+    }
   /** A portable story mounts it in isolation. */
   | { readonly kind: 'story'; readonly storyId: string }
+  /**
+   * The RUNNING game's own published scenes contract reaches it, under
+   * `sceneId` (`adapter/ingest/game-contract.ts`'s `scenes.list()` ids).
+   *
+   * This is the LIVE reach: opening it while playing means asking the game to
+   * navigate, the way its own buttons do. An authorable entry that also names
+   * `source` can independently own an Edit isolation document; reach never
+   * decides whether a source composition can be mounted as a piece.
+   *
+   * A DECLARATION, never an inference: the host does not sniff a mapping
+   * between a table entry and a contract id, and it does not assume the two
+   * vocabularies coincide. The adapter states which contract id this entry is,
+   * and the host validates that id against the game's OWN `list()` at the
+   * moment it navigates — so a game that stops publishing the scene refuses by
+   * name instead of navigating somewhere else.
+   */
+  | { readonly kind: 'game-contract'; readonly sceneId: string }
   /** Declared, with no code path that opens it. */
   | { readonly kind: 'none'; readonly reason: string };
 
@@ -399,9 +591,11 @@ const SceneReachSchema = z.union([
       kind: z.literal('entrypoint-selection'),
       selection: z.string().min(1),
       key: z.string().min(1),
+      active: z.boolean().optional(),
     })
     .strict(),
   z.object({ kind: z.literal('story'), storyId: z.string().min(1) }).strict(),
+  z.object({ kind: z.literal('game-contract'), sceneId: z.string().min(1) }).strict(),
   z.object({ kind: z.literal('none'), reason: z.string().min(1) }).strict(),
 ]);
 
@@ -437,6 +631,10 @@ export interface SceneEntry {
   readonly authorable: boolean;
   readonly reach: SceneReach;
   readonly source?: SceneSource;
+  /** Optional adapter-declared prerequisite run before `source` is constructed
+   *  in Edit isolation. The export is a zero-argument function; the host never
+   *  infers setup from neighboring filenames or game globals. */
+  readonly isolationSetup?: SceneSource;
   /** Which finder produced it; absent = the adapter stated it outright. */
   readonly finder?: FinderName;
 }
@@ -450,6 +648,7 @@ const SceneEntrySchema = z
     authorable: z.boolean(),
     reach: SceneReachSchema,
     source: SceneSourceSchema.optional(),
+    isolationSetup: SceneSourceSchema.optional(),
     finder: z.enum(FINDER_NAMES).optional(),
   })
   .strict();
@@ -481,32 +680,128 @@ const AdapterSceneTableSchema = z
 // Observation
 // ---------------------------------------------------------------------------
 
+/**
+ * The two faces a declaration projects onto. They are exactly the two
+ * `DebugAdapter` halves (`adapter/system-adapter.ts`): `state` becomes a
+ * provider (`providers()` / `state(name)`), `command` becomes a verb
+ * (`commands()` / `invoke(name, args)`). There is deliberately no third kind —
+ * see {@link OBSERVATION_KIND_REFUSAL}.
+ */
+export const OBSERVATION_KINDS = ['command', 'state'] as const;
+export type ObservationKind = (typeof OBSERVATION_KINDS)[number];
+
+/**
+ * Why a declaration may not name a `SystemAdapters` slot here.
+ *
+ * A game's system slots are already declared through the game contract's own
+ * `systemAdapters` carrier (`adapter/ingest/game-contract.ts`), which validates
+ * each slot per-surface and reports a malformed one BY NAME
+ * (`contract-system-adapters.ts`). A second door onto the same slots is exactly
+ * the two-declarations-one-slot problem `game-contract.ts` records for `debug`,
+ * where it says outright that a second door "would let a game declare two
+ * different debug planes with no rule for which wins".
+ */
+const OBSERVATION_KIND_REFUSAL =
+  "observation.kind must be 'command' or 'state' — the two DebugAdapter faces a declaration " +
+  'projects onto. A SystemAdapters slot is declared through the game contract’s `systemAdapters` ' +
+  'carrier, which validates it per-surface; declaring one here would be a second door onto the ' +
+  'same slot with no rule for which wins.';
+
 /**
  * One statically declared observation slot. Declaring a slot and ANSWERING it
  * live are separate facts (the two-state rule): a slot declared here whose
- * `answer` throws or whose game never booted reads as broken, never as
- * "the game has none".
+ * `answer` throws, whose `answer` is absent, or whose game never booted reads as
+ * broken, never as "the game has none". The projector
+ * (`adapter/ingest/observation-debug-adapter.ts`) keeps that distinction: an
+ * unanswerable slot is still LISTED, and refuses by name when read.
  */
 export interface ObservationDeclaration {
   readonly id: string;
-  readonly kind: 'system' | 'command' | 'state';
+  readonly kind: ObservationKind;
+  readonly description?: string | undefined;
+  /** Command execution side; omitted means a local app-owned command. */
+  readonly locus?: 'client' | 'server' | undefined;
   /**
    * Lazily evaluated against the mounted game. The field may be a closure; the
    * TABLE around it stays statically readable, which is the whole discipline.
+   *
+   * What `game` IS is the host's to hand over and is stated at the projector:
+   * for an ingest mount it is the REALM the game's own modules ran in, because
+   * a foreign game's public handles are the only thing the host can honestly
+   * pass (`observation-debug-adapter.ts`).
    */
-  readonly answer?: (game: unknown) => unknown;
+  readonly answer?: (game: unknown, ...args: unknown[]) => unknown;
 }
 
 const ObservationDeclarationSchema = z
   .object({
     id: z.string().min(1),
-    kind: z.enum(['system', 'command', 'state']),
+    kind: z.enum(OBSERVATION_KINDS, { error: () => OBSERVATION_KIND_REFUSAL }),
+    description: z.string().min(1).optional(),
+    locus: z.enum(['client', 'server']).optional(),
     answer: z
       .custom<(game: unknown) => unknown>((value) => typeof value === 'function', {
         message: 'observation.answer must be a function evaluated against the mounted game',
       })
       .optional(),
   })
+  .strict()
+  .refine((value) => value.kind === 'command' || value.locus === undefined, {
+    path: ['locus'],
+    message: 'observation.locus is valid only for a command declaration',
+  });
+
+// ---------------------------------------------------------------------------
+// Native input
+// ---------------------------------------------------------------------------
+
+/** The action value shapes the session input door already speaks. */
+export const ADAPTER_INPUT_VALUE_TYPES = [
+  'digital',
+  'scalar',
+  'vector2',
+  'pointerDelta',
+  'pointerPosition',
+] as const;
+export type AdapterInputValueType = (typeof ADAPTER_INPUT_VALUE_TYPES)[number];
+export type AdapterInputValue = boolean | number | { readonly x: number; readonly y: number };
+
+/** One action in an app-owned input store. */
+export interface AdapterInputAction {
+  readonly name: string;
+  readonly valueType: AdapterInputValueType;
+}
+
+/**
+ * Adapter-side binding from the universal session input door to a game's
+ * ordinary input store. The game owns both its physical-device listeners and
+ * its state; this table only tells the host how to drive that same state for a
+ * bot or live REPL session. No component imports this contract.
+ */
+export interface AdapterInputBinding {
+  /** Manifest root whose native scheduler consumes these actions. */
+  readonly root: string;
+  /** Current action vocabulary. A closure permits an app-owned dynamic map. */
+  readonly actions: (game: unknown) => readonly AdapterInputAction[];
+  /** Apply one action through the app's own input-store write path. */
+  readonly set: (game: unknown, action: string, value: AdapterInputValue) => void;
+  /** Release every app-owned virtual action. */
+  readonly clear: (game: unknown) => void;
+}
+
+const AdapterInputBindingSchema = z
+  .object({
+    root: z.string().min(1),
+    actions: z.custom<AdapterInputBinding['actions']>((value) => typeof value === 'function', {
+      message: 'input.actions must be a function returning the app-owned action vocabulary',
+    }),
+    set: z.custom<AdapterInputBinding['set']>((value) => typeof value === 'function', {
+      message: 'input.set must be a function writing the app-owned input store',
+    }),
+    clear: z.custom<AdapterInputBinding['clear']>((value) => typeof value === 'function', {
+      message: 'input.clear must be a function releasing app-owned virtual actions',
+    }),
+  })
   .strict();
 
 // ---------------------------------------------------------------------------
@@ -516,8 +811,16 @@ const ObservationDeclarationSchema = z
 /** The adapter module's default export, after {@link defineAdapter}. */
 export interface AdapterDefinition {
   readonly regions: RegionBinding;
+  /**
+   * Per-region parameters for the `'manifest-roots'` RULE, keyed by manifest
+   * root id — the `include` globs and `mounts` surfaces the mechanical
+   * derivation cannot produce. {@link regionsFromManifestRoots} merges them;
+   * an explicit `regions` LIST carries its own and rejects these by name.
+   */
+  readonly regionIncludes: Readonly<Record<string, AdapterRegionOverlay>>;
   readonly scenes: AdapterSceneTable;
   readonly observation: readonly ObservationDeclaration[];
+  readonly input?: AdapterInputBinding | undefined;
 }
 
 /** What a game writes. Every field optional — the near-empty adapter is the
@@ -525,17 +828,44 @@ export interface AdapterDefinition {
  *  native. */
 export interface AdapterDefinitionInput {
   readonly regions?: RegionBinding;
+  readonly regionIncludes?: Readonly<Record<string, AdapterRegionOverlay>>;
   readonly scenes?: AdapterSceneTable;
   readonly observation?: readonly ObservationDeclaration[];
+  readonly input?: AdapterInputBinding | undefined;
 }
 
+/**
+ * Why the two forms may not be combined, said in the error a game's author
+ * reads. An explicit region list REPLACES the derivation and its entries carry
+ * `include`/`mounts` themselves; layering a second table over it would put one
+ * fact in two homes, with no rule for which wins.
+ */
+const REGION_INCLUDES_WITH_LIST_REFUSAL =
+  '`regionIncludes` states parameters for the `manifest-roots` RULE, so it cannot be paired ' +
+  'with an explicit `regions` list — that form is the full replacement, and each entry carries ' +
+  'its own `include`/`mounts`. Move these globs onto the matching `regions[]` entry, or drop the ' +
+  'list and let the derivation run.';
+
 export const AdapterDefinitionSchema = z
   .object({
     regions: RegionBindingSchema.optional(),
+    regionIncludes: RegionIncludesSchema.optional(),
     scenes: AdapterSceneTableSchema.optional(),
     observation: z.array(ObservationDeclarationSchema).optional(),
+    input: AdapterInputBindingSchema.optional(),
   })
-  .strict();
+  .strict()
+  // An EMPTY table beside a list is fine and must stay fine: `defineAdapter`
+  // publishes `regionIncludes: {}` on every definition, and its output is
+  // parsed a second time by the host's loader — a refusal on the key's mere
+  // presence would reject the module's own valid output on the round trip.
+  .refine(
+    (value) =>
+      value.regionIncludes === undefined ||
+      Object.keys(value.regionIncludes).length === 0 ||
+      !Array.isArray(value.regions),
+    { message: REGION_INCLUDES_WITH_LIST_REFUSAL },
+  );
 
 /**
  * Validate and freeze a game's binding table.
@@ -557,8 +887,10 @@ export function defineAdapter(input: AdapterDefinitionInput = {}): AdapterDefini
   }
   return Object.freeze({
     regions: input.regions ?? 'manifest-roots',
+    regionIncludes: Object.freeze({ ...(input.regionIncludes ?? {}) }),
     scenes: Object.freeze({ ...(input.scenes ?? {}) }),
     observation: Object.freeze([...(input.observation ?? [])]),
+    ...(input.input ? { input: input.input } : {}),
   });
 }
 
@@ -566,8 +898,9 @@ export function defineAdapter(input: AdapterDefinitionInput = {}): AdapterDefini
 export interface NativeAdapterOptions {
   /** Scene-table entries this game states outright, beside what the finders find. */
   readonly scenes?: readonly SceneEntry[];
-  /** Observation slots this game declares. */
-  readonly observation?: readonly ObservationDeclaration[];
+  /** Per-region `include`/`mounts` parameters for the derivation — see
+   *  {@link AdapterDefinition.regionIncludes}. */
+  readonly regionIncludes?: Readonly<Record<string, AdapterRegionOverlay>>;
 }
 
 /**
@@ -580,6 +913,7 @@ export interface NativeAdapterOptions {
 export function nativeAdapter(options: NativeAdapterOptions = {}): AdapterDefinition {
   return defineAdapter({
     regions: 'manifest-roots',
+    ...(options.regionIncludes ? { regionIncludes: options.regionIncludes } : {}),
     scenes: {
       ...(options.scenes ? { entries: options.scenes } : {}),
       find: [
@@ -587,7 +921,6 @@ export function nativeAdapter(options: NativeAdapterOptions = {}): AdapterDefini
         { finder: 'prefabsFromStories' },
       ],
     },
-    ...(options.observation ? { observation: options.observation } : {}),
   });
 }