@vgai/engine 0.5.13 → 0.5.15

package/src/adapter/adapter-module.ts

@@ -0,0 +1,607 @@
+/**
+ * `vgai.adapter.ts` — THE ADAPTER MODULE CONTRACT.
+ *
+ * ARCHITECTURE-CORE §The editor protocol, "The adapter is the game's own
+ * module": the editor is a universal CLIENT of a fixed protocol and every game
+ * supplies a SERVER — its adapter. That adapter is the game's OWN module,
+ * `vgai.adapter.ts`, sitting beside `vgai.project.json`, default-exporting
+ * {@link defineAdapter}'s result.
+ *
+ * It is CODE (bindings are expressions — a scene entry may carry a closure the
+ * host evaluates against the mounted game) with a CONFIG's discipline: the top
+ * level is a STATICALLY EVALUABLE BINDING TABLE, readable without booting the
+ * game. Concretely, that is the split this module enforces:
+ *
+ *   - the TABLE SHAPE — regions, the scene table, observation declarations —
+ *     is plain data, validated by {@link AdapterDefinitionSchema} the moment
+ *     the module is evaluated. `.strict()` throughout: an unrecognized key is
+ *     an error naming the key, never a silent pass-through (CLAUDE.md,
+ *     "Unknown input must REJECT LOUDLY").
+ *   - individual FIELDS may be closures, evaluated lazily against the mounted
+ *     game (`ObservationDeclaration.answer`). A closure is never required to
+ *     read the table.
+ *
+ * **Zero inference.** A binding is a DECLARATION or a finder SELECTION the
+ * adapter makes — never something the host sniffs out. Finder algorithms
+ * (scenes from an entrypoint selection, prefabs from story registrations, …)
+ * ship host-side under `adapter/finders/`, and this module names them by
+ * SELECTION only ({@link FinderSelection}). That is deliberate and load-bearing
+ * twice over:
+ *   1. the engine never runs a finder nobody selected — enforced mechanically
+ *      by `packages/engine/test/finder-import-boundary.test.ts`, whose only
+ *      sanctioned importer of the finder namespace is the editor's adapter
+ *      loader;
+ *   2. this module therefore imports NOTHING from `adapter/finders/`, so a
+ *      game's `vgai.adapter.ts` pulls no finder implementation (and no source
+ *      parser) into its own bundle. The dependency runs one way: finders
+ *      import their parameter types from HERE.
+ *
+ * The manifest keeps only what must be readable without evaluating any module
+ * — identity, roots, boot mode, `server.room`. Everything that binds behavior
+ * is the adapter's. This wave adds NO manifest field.
+ */
+
+import { z } from 'zod';
+import type { ResolvedAdapterRoot } from '../manifest/load';
+import type { AdapterSurface } from './adapter-surface';
+import { WRITE_ANCHOR_KINDS, type WriteAnchorKind } from './authoring';
+
+// ---------------------------------------------------------------------------
+// Regions
+// ---------------------------------------------------------------------------
+
+/**
+ * The projector serving a surface — one per surface, host-owned
+ * (ARCHITECTURE-CORE: "Projection — nodes, stable identity, bounds, picking …
+ * one projector per surface"). Named, never imported: the adapter states WHICH
+ * library serves the region; the host binds the implementation.
+ */
+export const PROJECTOR_NAMES = ['three', 'pixi', 'dom'] as const;
+export type ProjectorName = (typeof PROJECTOR_NAMES)[number];
+
+/**
+ * A region's WORLD BASIS — which axis points up, and where its ground sits.
+ *
+ * The editor needs a ground plane to place a dropped asset or a probe point on.
+ * That plane used to be the constant `y = 0` compiled into `editor-viewport.ts`,
+ * which is a guess about the GAME's convention: a Z-up world (the CAD/Blender
+ * idiom foreign R3F games routinely carry) got its drops silently projected onto
+ * the wrong plane. It is exactly the shape "zero inference" names — a fact the
+ * game's author can state, so the fix is a declaration slot rather than a
+ * smarter sniff (ARCHITECTURE-CORE §The editor protocol).
+ */
+export interface AdapterRegionBasis {
+  /** World axis pointing away from the ground. */
+  readonly up: 'y' | 'z';
+  /** Ground offset along {@link up}, in world units. */
+  readonly groundHeight: number;
+}
+
+/**
+ * The NATIVE basis — what {@link regionsFromManifestRoots} emits and what a
+ * region that declares none is read as. +Y up, ground at 0: three.js' own
+ * convention, which every first-party root is authored in. Stated as a value so
+ * "the default" has one home instead of a copy at each reader.
+ */
+export const NATIVE_REGION_BASIS: AdapterRegionBasis = Object.freeze({
+  up: 'y',
+  groundHeight: 0,
+});
+
+/**
+ * One matrix REGION: a root, its surface, and the library selections that
+ * serve it. Universality lives at region granularity — which libraries serve a
+ * surface is a per-surface ENGINE fact, so a new surface root in an existing
+ * game is one manifest line and one derived region, never new adapter code
+ * (that is exactly what {@link regionsFromManifestRoots} does).
+ */
+export interface AdapterRegion {
+  /** The manifest root this region grades. */
+  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;
+  /**
+   * Dialect writer, by name (`r3f`, `jsx`, `pixi-react`, …) — the truth
+   * family's source writer for this region. `null` states outright that the
+   * host writes no source here: the region's truth is the game's own code,
+   * which the host does not author (a module or ingest root).
+   */
+  readonly dialect: string | null;
+  /**
+   * Anchor kinds this region's writer serves, drawn from the compile-pinned
+   * {@link WRITE_ANCHOR_KINDS} vocabulary. A kind absent here is a red cell in
+   * the matrix, which is a work order — never a silently unsupported edit.
+   */
+  readonly anchors: readonly WriteAnchorKind[];
+  /**
+   * This region's world basis. Omitted = {@link NATIVE_REGION_BASIS}, which is
+   * a DECLARED default (the native adapter emits it outright), not a silent
+   * fallback — same shape as an absent `vgai.adapter.ts` meaning
+   * `nativeAdapter()`.
+   */
+  readonly basis?: AdapterRegionBasis;
+  /**
+   * Project-relative globs naming source files this region OWNS, for the
+   * ambiguous remainder that import reach cannot place.
+   *
+   * A file's surface/dialect is derived from WHICH REGION'S IMPORT CLOSURE
+   * reaches it — a load-bearing fact, because the region's manifest entry is
+   * what the host actually executes at mount (the game would break first if it
+   * lied). Reach through several regions of the SAME surface is unambiguous;
+   * reach through regions of DIFFERING surfaces, or through none at all, is
+   * genuinely undecidable from outside, and this is where the game's author
+   * states the answer instead of the host guessing it from the file's bytes.
+   *
+   * READER: `packages/editor/src/ui-source/file-region-resolver.ts`'s
+   * `resolveFileRegion`, consulted BEFORE reach — a declared include wins,
+   * because it is a first-party statement about this exact file. Every OID
+   * stamping tier, the HMR classifier, the R3F authoring diagnostics and
+   * Content's component grouping read that one resolver.
+   *
+   * {@link regionsFromManifestRoots} emits none: the native default is PURE
+   * reach, and a first-party project that needs an include has a module its
+   * roots do not reach, which is a fact worth stating rather than absorbing.
+   *
+   * Glob vocabulary is deliberately the small one every reader already knows:
+   * `**` (any depth, including none), `*` (one segment, no `/`), `?` (one
+   * character). No brace expansion, no negation — a second syntax to learn is
+   * how a declaration slot turns back into a language.
+   */
+  readonly include?: readonly string[];
+}
+
+const AdapterRegionBasisSchema = z
+  .object({
+    up: z.enum(['y', 'z']).describe('World axis pointing away from the ground'),
+    groundHeight: z.number().describe('Ground offset along `up`, in world units'),
+  })
+  .strict();
+
+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()
+      .min(1)
+      .nullable()
+      .describe(
+        'Dialect writer serving this region, by name; null states outright that the host writes ' +
+          "no source here (the region's truth is the game's own code)",
+      ),
+    anchors: z
+      .array(z.enum(WRITE_ANCHOR_KINDS as [WriteAnchorKind, ...WriteAnchorKind[]]))
+      .describe('Anchor kinds this region’s writer serves'),
+    basis: AdapterRegionBasisSchema.optional().describe(
+      'World basis (up axis + ground height); omit for the native +Y / 0 default',
+    ),
+    include: z
+      .array(z.string().min(1))
+      .min(1)
+      .optional()
+      .describe(
+        'Project-relative globs (`**`, `*`, `?`) naming source files this region owns, for files ' +
+          'no root entry’s import closure reaches; a declared include wins over reach',
+      ),
+  })
+  .strict();
+
+/**
+ * How a definition supplies its regions: the RULE `'manifest-roots'` (the
+ * native default — a declaration may be a rule rather than a list, the way
+ * `roots[]` never enumerates a world's contents), or an explicit list a game
+ * with novel bindings states outright.
+ */
+export type RegionBinding = 'manifest-roots' | readonly AdapterRegion[];
+
+const RegionBindingSchema = z.union([
+  z.literal('manifest-roots'),
+  z.array(AdapterRegionSchema).min(1),
+]);
+
+/**
+ * The MECHANICAL derivation behind the `'manifest-roots'` rule: one region per
+ * declared root, its surface and adapter identity read straight off the
+ * RESOLVED manifest (`@engine/manifest/load` already decided both — this never
+ * re-derives them).
+ *
+ * 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                          |
+ *
+ * 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
+ * write path it does not have. That is a red cell and therefore a work order,
+ * which is the point of stating it.
+ *
+ * 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.
+ */
+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,
+      };
+    }
+    return {
+      id: root.id,
+      surface,
+      dev,
+      projector,
+      dialect: surface === 'three' ? 'r3f' : 'pixi-react',
+      anchors: ['source-prop', 'construction-literal'] as const,
+      basis,
+    };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Finder selections
+// ---------------------------------------------------------------------------
+
+/**
+ * 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.
+ */
+export const EXPORTED_COMPOSITION_REGIONS = 'exported-composition-regions';
+
+/**
+ * `scenesFromEntrypointSelection` — read the entrypoint's ACTIVE-SCENE
+ * SELECTION, the load-bearing reference (the game itself executes it, so it
+ * cannot drift: the game would break first).
+ */
+export interface ScenesFromEntrypointSelectionParams {
+  readonly finder: 'scenesFromEntrypointSelection';
+  /**
+   * Which regions' entrypoints to read: named region ids, or the rule
+   * {@link EXPORTED_COMPOSITION_REGIONS}.
+   */
+  readonly regions: readonly string[] | typeof EXPORTED_COMPOSITION_REGIONS;
+  /**
+   * Identifier of the entrypoint's module-level selection table — the
+   * `const <selection> = { <sceneId>: <Component>, … }` binding the entrypoint
+   * renders at its swap slot.
+   *
+   * OMIT for an entrypoint that mounts ONE composition: the finder then answers
+   * with the single-scene degenerate table (the root's own composition, opened
+   * by mounting the region). Only legal alongside exactly one named region —
+   * a selection identifier is a fact about ONE entrypoint's source, so pairing
+   * it with the rule form is rejected by name rather than applied to whichever
+   * region happened to match.
+   */
+  readonly selection?: string;
+}
+
+/**
+ * `prefabsFromStories` — read the colocated portable-CSF story registrations.
+ * A prefab is an ordinary source component a designer independently places,
+ * declared by a story whose `meta.component` names it; the story registration
+ * is the load-bearing reference here (removing it removes the declaration).
+ * Zero parameters: the selection IS the whole configuration.
+ */
+export interface PrefabsFromStoriesParams {
+  readonly finder: 'prefabsFromStories';
+}
+
+/** Every finder this engine ships, as the adapter's concrete SELECTION. */
+export type FinderSelection = ScenesFromEntrypointSelectionParams | PrefabsFromStoriesParams;
+
+/** The finder names, as a value — what the loader's dispatcher switches on. */
+export const FINDER_NAMES = ['scenesFromEntrypointSelection', 'prefabsFromStories'] as const;
+export type FinderName = (typeof FINDER_NAMES)[number];
+
+const ScenesFromEntrypointSelectionSchema = z
+  .object({
+    finder: z.literal('scenesFromEntrypointSelection'),
+    regions: z
+      .union([z.array(z.string().min(1)).min(1), z.literal(EXPORTED_COMPOSITION_REGIONS)])
+      .describe('Region ids whose entrypoints carry the selection, or the rule form'),
+    selection: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(
+        "Identifier of the entrypoint's module-level scene selection table; omit for a " +
+          'single-composition entrypoint',
+      ),
+  })
+  .strict()
+  .refine((value) => value.selection === undefined || Array.isArray(value.regions), {
+    message:
+      'scenesFromEntrypointSelection: `selection` names an identifier in ONE entrypoint’s ' +
+      `source, so it cannot be paired with the \`${EXPORTED_COMPOSITION_REGIONS}\` rule — ` +
+      'name the region explicitly (`regions: ["<rootId>"]`).',
+  });
+
+const PrefabsFromStoriesSchema = z.object({ finder: z.literal('prefabsFromStories') }).strict();
+
+const FinderSelectionSchema = z.union([
+  ScenesFromEntrypointSelectionSchema,
+  PrefabsFromStoriesSchema,
+]);
+
+// ---------------------------------------------------------------------------
+// The scene table
+// ---------------------------------------------------------------------------
+
+/**
+ * How the RUNNING game is navigated to an entry — the `reachable` honesty
+ * clause, stated rather than assumed. An entry whose reach is `none` is a
+ * declared-but-unreachable scene: a red cell carrying its own reason.
+ */
+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 }
+  /** A portable story mounts it in isolation. */
+  | { readonly kind: 'story'; readonly storyId: string }
+  /** Declared, with no code path that opens it. */
+  | { readonly kind: 'none'; readonly reason: string };
+
+const SceneReachSchema = z.union([
+  z.object({ kind: z.literal('root-mount') }).strict(),
+  z
+    .object({
+      kind: z.literal('entrypoint-selection'),
+      selection: z.string().min(1),
+      key: z.string().min(1),
+    })
+    .strict(),
+  z.object({ kind: z.literal('story'), storyId: z.string().min(1) }).strict(),
+  z.object({ kind: z.literal('none'), reason: z.string().min(1) }).strict(),
+]);
+
+/** Where an entry's composition lives in the game's own source. */
+export interface SceneSource {
+  /** Project-relative path. */
+  readonly path: string;
+  /** Named export; omit when the module default-exports it. */
+  readonly export?: string;
+}
+
+const SceneSourceSchema = z
+  .object({ path: z.string().min(1), export: z.string().min(1).optional() })
+  .strict();
+
+/**
+ * One entry of the scene table. Scenes and prefabs are SIBLINGS here — both
+ * are registered compositions the editor opens in isolation through the same
+ * verb, differing only in instance site (ARCHITECTURE-CORE §Roots: "A scene is
+ * a ROLE, not a kind … the same kind of thing as a prefab").
+ */
+export interface SceneEntry {
+  readonly id: string;
+  readonly label: string;
+  /** `scene` (swaps at the entrypoint's slot) or `prefab` (placed by a designer). */
+  readonly kind: 'scene' | 'prefab';
+  /** Owning region id; `null` for a project-scoped entry bound to no one root. */
+  readonly region: string | null;
+  /**
+   * `true` = a composition a designer authors (it earns a matrix column).
+   * `false` = TRAVERSAL: boot/loading choreography, which gets no column.
+   */
+  readonly authorable: boolean;
+  readonly reach: SceneReach;
+  readonly source?: SceneSource;
+  /** Which finder produced it; absent = the adapter stated it outright. */
+  readonly finder?: FinderName;
+}
+
+const SceneEntrySchema = z
+  .object({
+    id: z.string().min(1),
+    label: z.string().min(1),
+    kind: z.enum(['scene', 'prefab']),
+    region: z.string().min(1).nullable(),
+    authorable: z.boolean(),
+    reach: SceneReachSchema,
+    source: SceneSourceSchema.optional(),
+    finder: z.enum(FINDER_NAMES).optional(),
+  })
+  .strict();
+
+/**
+ * The adapter's scene table: entries stated outright, finder selections the
+ * host runs to produce the rest, and the entry open by default.
+ */
+export interface AdapterSceneTable {
+  readonly entries?: readonly SceneEntry[];
+  readonly find?: readonly FinderSelection[];
+  /**
+   * Id of the entry open by default. Omit to let the finder's own answer
+   * stand — the host never picks one on its own, so "no default" stays a fact
+   * rather than becoming whichever entry sorted first.
+   */
+  readonly default?: string;
+}
+
+const AdapterSceneTableSchema = z
+  .object({
+    entries: z.array(SceneEntrySchema).optional(),
+    find: z.array(FinderSelectionSchema).optional(),
+    default: z.string().min(1).optional(),
+  })
+  .strict();
+
+// ---------------------------------------------------------------------------
+// Observation
+// ---------------------------------------------------------------------------
+
+/**
+ * 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".
+ */
+export interface ObservationDeclaration {
+  readonly id: string;
+  readonly kind: 'system' | 'command' | 'state';
+  /**
+   * Lazily evaluated against the mounted game. The field may be a closure; the
+   * TABLE around it stays statically readable, which is the whole discipline.
+   */
+  readonly answer?: (game: unknown) => unknown;
+}
+
+const ObservationDeclarationSchema = z
+  .object({
+    id: z.string().min(1),
+    kind: z.enum(['system', 'command', 'state']),
+    answer: z
+      .custom<(game: unknown) => unknown>((value) => typeof value === 'function', {
+        message: 'observation.answer must be a function evaluated against the mounted game',
+      })
+      .optional(),
+  })
+  .strict();
+
+// ---------------------------------------------------------------------------
+// The definition
+// ---------------------------------------------------------------------------
+
+/** The adapter module's default export, after {@link defineAdapter}. */
+export interface AdapterDefinition {
+  readonly regions: RegionBinding;
+  readonly scenes: AdapterSceneTable;
+  readonly observation: readonly ObservationDeclaration[];
+}
+
+/** What a game writes. Every field optional — the near-empty adapter is the
+ *  first-party case, and an adapter's SIZE measures the game's distance from
+ *  native. */
+export interface AdapterDefinitionInput {
+  readonly regions?: RegionBinding;
+  readonly scenes?: AdapterSceneTable;
+  readonly observation?: readonly ObservationDeclaration[];
+}
+
+export const AdapterDefinitionSchema = z
+  .object({
+    regions: RegionBindingSchema.optional(),
+    scenes: AdapterSceneTableSchema.optional(),
+    observation: z.array(ObservationDeclarationSchema).optional(),
+  })
+  .strict();
+
+/**
+ * Validate and freeze a game's binding table.
+ *
+ * Called TWICE by design and with one schema: once here, in the game's own
+ * module, so a malformed table fails at the author's own file with the key
+ * named; and once in the host's loader, because the loaded default export is
+ * untrusted input crossing a module boundary. Two call sites, one rule — not
+ * two ways to say the same thing.
+ */
+export function defineAdapter(input: AdapterDefinitionInput = {}): AdapterDefinition {
+  const parsed = AdapterDefinitionSchema.safeParse(input);
+  if (!parsed.success) {
+    throw new Error(
+      `vgai.adapter.ts: invalid adapter definition — ${parsed.error.issues
+        .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+        .join('; ')}`,
+    );
+  }
+  return Object.freeze({
+    regions: input.regions ?? 'manifest-roots',
+    scenes: Object.freeze({ ...(input.scenes ?? {}) }),
+    observation: Object.freeze([...(input.observation ?? [])]),
+  });
+}
+
+/** Extra bindings a near-native game adds without restating the native ones. */
+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[];
+}
+
+/**
+ * THE NATIVE DEFAULT — regions derived mechanically from the manifest's
+ * `roots[]`, and a scene table produced by the two shipped finders. This is
+ * what a first-party project ships (`export default nativeAdapter()`), and it
+ * is also what a project with NO `vgai.adapter.ts` gets: that absence is the
+ * declared native default, not a silent fallback.
+ */
+export function nativeAdapter(options: NativeAdapterOptions = {}): AdapterDefinition {
+  return defineAdapter({
+    regions: 'manifest-roots',
+    scenes: {
+      ...(options.scenes ? { entries: options.scenes } : {}),
+      find: [
+        { finder: 'scenesFromEntrypointSelection', regions: EXPORTED_COMPOSITION_REGIONS },
+        { finder: 'prefabsFromStories' },
+      ],
+    },
+    ...(options.observation ? { observation: options.observation } : {}),
+  });
+}
+
+/**
+ * Parse an untrusted default export (the loaded `vgai.adapter.ts`) into a
+ * definition. Rejects loudly — an unknown key, a bad finder name, a
+ * `selection` paired with the rule form all fail by name.
+ */
+export function parseAdapterDefinition(value: unknown): AdapterDefinition {
+  if (value === null || typeof value !== 'object') {
+    throw new Error(
+      'vgai.adapter.ts must default-export defineAdapter({…}) / nativeAdapter() — ' +
+        `got ${value === null ? 'null' : typeof value}`,
+    );
+  }
+  return defineAdapter(value as AdapterDefinitionInput);
+}