@vgai/engine 0.2.0 → 0.4.0-canary.20260715.0

package/src/manifest/schema.ts

@@ -1,6 +1,6 @@
 // T3.1 slice 1 — the game manifest schema (`vgai.game.json`).
 //
-// This is the serialized form of the Game's world list
+// This is the serialized form of the Game's root list
 // (docs/GAME-ROOT-DESIGN.md §1, D6) — see docs/GAME-MANIFEST-DESIGN.md §3 for
 // the adjudicated field list this file implements exactly. `load.ts` is this
 // schema's runtime reader (T4.1 policy): it parses via this schema, then
@@ -11,20 +11,24 @@
 // Naming: this file follows the repo's `XxxSchema` (Zod schema) / `Xxx`
 // (inferred type) convention used throughout `scene/schema/` — the design
 // doc's §3 sketch names the bare consts (`Tier`, `IngestStrategy`,
-// `WorldEntry`) without the `Schema` suffix; that sketch is explicitly a
+// `AdapterRoot`) without the `Schema` suffix; that sketch is explicitly a
 // "Zod sketch" the doc tells implementers to adapt to real code style
 // ("mirror the style in scene/schema/scene-file.ts" per CLAUDE.md), so the
 // schema consts here are suffixed and the bare names are reserved for the
 // inferred types, matching every other schema file in the repo.
 //
-// World `kind` intentionally mirrors `WorldKind` in
+// Adapter surface values mirror `AdapterSurface` in
 // `packages/engine/src/runtime/game.ts` (`'threejs' | 'pixijs' | 'react'`)
-// by value, not by import — this schema module has no runtime dependency
-// beyond `zod` (kept parseable/bundlable in any context), matching the
-// `scene/schema/` precedent.
+// by value, not by import. The adapter remains the sole root discriminator.
 
 import { z } from 'zod';
 
+/**
+ * Current on-disk `vgai.game.json` format. Exported so editor/server
+ * compatibility checks do not duplicate the schema's literal value.
+ */
+export const GAME_MANIFEST_VERSION = 2 as const;
+
 // ---------------------------------------------------------------------------
 // Ingest capture strategy (world2d today; the general vocabulary D6/§4 names)
 // ---------------------------------------------------------------------------
@@ -42,266 +46,274 @@ export type IngestStrategy = z.infer<typeof IngestStrategySchema>;
 // ---------------------------------------------------------------------------
 
 export const TierSchema = z.enum([
-  'first-party', // vgai-native world: full editor, full loop control
+  'first-party', // vgai-native root: full editor, full loop control
   'shared', // = IngestStrategy 'shared' rung
   'deduped', // = IngestStrategy 'deduped' rung
   'iframe-reachable', // = IngestStrategy 'iframe-reachable' rung
   'opaque-embed', // = IngestStrategy 'opaque-embed' rung
-  'unsupported', // this world does not function in this delivery context
+  'unsupported', // this root does not function in this delivery context
 ]);
 export type Tier = z.infer<typeof TierSchema>;
 
 // ---------------------------------------------------------------------------
-// World adapter identity — "make invalid states unrepresentable" (§2): a
-// world names its `kind` once, and its `adapter` is either resolved BY kind
-// (D6's default-*), a custom module, or an ingest strategy. There is no field
-// that lets a world spell out a kind/adapter combination that cannot exist.
+// Root adapter identity. The adapter is the sole discriminator: a root never
+// repeats its rendering substrate in a sibling `kind` field. Module and ingest
+// adapters carry the surface their adapter contract exposes because the host
+// must allocate a layer before the module has mounted.
 // ---------------------------------------------------------------------------
 
-export const WorldAdapterSchema = z
+export const RootAdapterSchema = z
   .union([
-    z.literal('default'),
-    z.object({
-      module: z
-        .string()
-        .describe('Game-folder-relative path to a custom adapter module (trust boundary)'),
-    }),
-    z.object({
-      ingest: z
-        .object({
-          strategy: IngestStrategySchema.describe(
-            'Capture mechanics rung this ingested world uses (§4) — also the world`s natural local capability tier',
-          ),
-          entryHtml: z
-            .string()
-            .optional()
-            .describe(
-              'Entry HTML path, project-relative. WIRED for opaque-embed (D-W2, ' +
-                'docs/WAVE4-FTUE-HARDENING-DESIGN.md): the file`s bytes are read verbatim through ' +
-                'the project-static route and hosted in a sandboxed iframe (embed-only, no scene ' +
-                'introspection), for both pixijs and threejs worlds. Legal but NOT wired to a ' +
-                'mount for iframe-reachable (a named error at resolve names this — use `bundleUrl` ' +
-                'instead, the wired reachable route).',
-            ),
-          assets: z
-            .record(z.string(), z.string())
-            .optional()
-            .describe(
-              'Path-substring -> served-URL rewrites for this ingested game (IngestGame.assets today)',
-            ),
-          domStubs: z
-            .array(z.string())
-            .optional()
-            .describe('DOM API stub ids this ingested game requires to run headlessly/in-realm'),
-          captureTimeoutMs: z
-            .number()
-            .optional()
-            .describe('Max time to wait for in-realm/cross-realm capture before failing loudly'),
-          // Track P (docs/PIXI-INGEST-LANDING-DESIGN.md §2) — the six
-          // iframe-reachable-multi mount fields (`ingest-iframe-2d.ts`'s
-          // `IframeReachableMultiOpts`), legal ONLY when `strategy` is
-          // 'iframe-reachable' (enforced by the `.superRefine` below).
-          bundleUrl: z
-            .string()
-            .optional()
-            .describe(
-              'Absolute URL of the externalized built game bundle — the WIRED iframe-reachable ' +
-                'mount route (iframe-reachable only), for BOTH pixijs (Track P, ' +
-                "ingest-iframe-2d.ts's mountIngestGame2DIframeReachableMulti) and threejs (D-W1, " +
-                'docs/WAVE4-FTUE-HARDENING-DESIGN.md, ' +
-                "ingest-iframe-reachable-adapter.ts's mountIngestGameIframeReachableBundle). " +
-                'PRECONDITION: the bundle must externalize its world`s own runtime as a bare, ' +
-                'un-rewritten import (`pixi.js` for pixijs, `three` for threejs — `vgai bundle` ' +
-                'does this for you) so it resolves through the iframe importmap to the HOST ' +
-                'instance the capture trap is installed on; a bundle with an inlined runtime is ' +
-                'unreachable and degrades to the embed-only floor. Exactly one of bundleUrl/' +
-                'entryHtml is required when strategy is iframe-reachable.',
-            ),
-          baseHref: z
-            .string()
-            .optional()
-            .describe(
-              "Iframe <base href> so the game's relative asset URLs resolve (iframe-reachable only).",
-            ),
-          assetBaseUrl: z
-            .string()
-            .optional()
-            .describe(
-              "Host-side basePath forced onto the trapped runtime's own asset resolution — " +
-                "pixi's `Assets.init` for a pixijs world, three's " +
-                '`DefaultLoadingManager.setURLModifier` for a threejs world (D-W1) — absolute, or ' +
-                "root-relative (resolved against the editor page's own origin at mount time, " +
-                'ingest-mode.ts, so a static manifest never has to know the dev-server port) ' +
-                '(iframe-reachable only — a document.write iframe keeps the parent window.location).',
-            ),
-          extraDeps: z
-            .array(z.string())
-            .optional()
-            .describe(
-              "Bare specifiers of this world's externalized deps beyond its own runtime " +
-                "(pixi.js/three — e.g. '@pixi/sound', 'gsap'). Resolved by the editor's " +
-                'host-namespace registry into module namespaces when known (D-P1 — the manifest ' +
-                'carries data, not code); an unregistered specifier falls back to the open ' +
-                "project's own node_modules (D-Z3, docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md), served " +
-                'as a verbatim iframe importmap URL. Throws a named error if neither resolves it ' +
-                '(iframe-reachable only).',
-            ),
-          pixiModuleUrl: z
-            .string()
-            .optional()
-            .describe(
-              'PIXI-ONLY: standalone matching-major pixi ESM URL to trap instead of the host ' +
-                "pixi, for version-skewed games (e.g. a v6 game on a v8 host); this field's " +
-                'PRESENCE is how the skew is expressed (D-P2 — no separate strategy/tier for ' +
-                'version skew) (iframe-reachable only). Declaring this on a `kind: "threejs"` ' +
-                'world is schema-legal (this field is kind-agnostic here) but throws a NAMED ' +
-                'not-supported error at resolve — three has no version-skew mount this wave (D-W7, ' +
-                'docs/WAVE4-FTUE-HARDENING-DESIGN.md: a hypothetical `threeModuleUrl` is explicitly ' +
-                'parked, no consumer exists).',
-            ),
-          bodyHtml: z
-            .string()
-            .optional()
-            .describe(
-              'HTML injected into the iframe body before the game script boots (e.g. a ' +
-                '`<div id="game-root">` the game expects to find) (iframe-reachable only).',
+    z.enum(['threejs', 'pixijs', 'react']),
+    z
+      .object({
+        module: z
+          .string()
+          .describe('Game-folder-relative path to a custom adapter module (trust boundary)'),
+        surface: z
+          .enum(['threejs', 'pixijs', 'react'])
+          .describe('Native surface exposed by this custom adapter contract'),
+      })
+      .strict(),
+    z
+      .object({
+        surface: z
+          .enum(['threejs', 'pixijs', 'react'])
+          .describe('Native surface captured from the unmodified game'),
+        ingest: z
+          .object({
+            strategy: IngestStrategySchema.describe(
+              'Capture mechanics rung this ingested root uses (§4) — also the root`s natural local capability tier',
             ),
-        })
-        .describe(
-          'Ingest adapter configuration for an unmodified game (a repo-vendored game or your ' +
-            'own external folder)',
-        )
-        .superRefine((ingest, ctx) => {
-          // Track P (docs/PIXI-INGEST-LANDING-DESIGN.md §2/D-P4): the six
-          // iframe-reachable-multi fields only make sense for the
-          // iframe-reachable-multi mount — reject them under any other
-          // strategy (mirrors ui.ts's dead-field-under-wrong-variant pattern).
-          const iframeOnlyFields: ReadonlyArray<
-            readonly [
-              key:
-                | 'bundleUrl'
-                | 'baseHref'
-                | 'assetBaseUrl'
-                | 'extraDeps'
-                | 'pixiModuleUrl'
-                | 'bodyHtml',
-              present: boolean,
-            ]
-          > = [
-            ['bundleUrl', ingest.bundleUrl !== undefined],
-            ['baseHref', ingest.baseHref !== undefined],
-            ['assetBaseUrl', ingest.assetBaseUrl !== undefined],
-            ['extraDeps', ingest.extraDeps !== undefined],
-            ['pixiModuleUrl', ingest.pixiModuleUrl !== undefined],
-            ['bodyHtml', ingest.bodyHtml !== undefined],
-          ];
-          if (ingest.strategy !== 'iframe-reachable') {
-            for (const [key, present] of iframeOnlyFields) {
-              if (present) {
-                ctx.addIssue({
-                  code: z.ZodIssueCode.custom,
-                  message:
-                    `\`${key}\` is only legal when strategy is 'iframe-reachable' (got ` +
-                    `"${ingest.strategy}") — bundleUrl/baseHref/assetBaseUrl/extraDeps/` +
-                    "pixiModuleUrl/bodyHtml are the iframe-reachable-multi mount's options " +
-                    '(pixijs: ingest-iframe-2d.ts IframeReachableMultiOpts; threejs, D-W1: ' +
-                    'ingest-iframe-reachable-adapter.ts IframeReachableBundleOpts) and have no ' +
-                    'meaning under any other strategy.',
-                  path: [key],
-                });
+            entryHtml: z
+              .string()
+              .optional()
+              .describe(
+                'Entry HTML path, project-relative. WIRED for opaque-embed (D-W2, ' +
+                  'docs/WAVE4-FTUE-HARDENING-DESIGN.md): the file`s bytes are read verbatim through ' +
+                  'the project-static route and hosted in a sandboxed iframe (embed-only, no scene ' +
+                  'introspection), for both pixijs and threejs roots. Legal but NOT wired to a ' +
+                  'mount for iframe-reachable (a named error at resolve names this — use `bundleUrl` ' +
+                  'instead, the wired reachable route).',
+              ),
+            assets: z
+              .record(z.string(), z.string())
+              .optional()
+              .describe(
+                'Path-substring -> served-URL rewrites for this ingested game (IngestGame.assets today)',
+              ),
+            domStubs: z
+              .array(z.string())
+              .optional()
+              .describe('DOM API stub ids this ingested game requires to run headlessly/in-realm'),
+            captureTimeoutMs: z
+              .number()
+              .optional()
+              .describe('Max time to wait for in-realm/cross-realm capture before failing loudly'),
+            // Track P (docs/PIXI-INGEST-LANDING-DESIGN.md §2) — the six
+            // iframe-reachable-multi mount fields (`ingest-iframe-2d.ts`'s
+            // `IframeReachableMultiOpts`), legal ONLY when `strategy` is
+            // 'iframe-reachable' (enforced by the `.superRefine` below).
+            bundleUrl: z
+              .string()
+              .optional()
+              .describe(
+                'Absolute URL of the externalized built game bundle — the WIRED iframe-reachable ' +
+                  'mount route (iframe-reachable only), for BOTH pixijs (Track P, ' +
+                  "ingest-iframe-2d.ts's mountIngestGame2DIframeReachableMulti) and threejs (D-W1, " +
+                  'docs/WAVE4-FTUE-HARDENING-DESIGN.md, ' +
+                  "ingest-iframe-reachable-adapter.ts's mountIngestGameIframeReachableBundle). " +
+                  'PRECONDITION: the bundle must externalize its root`s own runtime as a bare, ' +
+                  'un-rewritten import (`pixi.js` for pixijs, `three` for threejs — `vgai bundle` ' +
+                  'does this for you) so it resolves through the iframe importmap to the HOST ' +
+                  'instance the capture trap is installed on; a bundle with an inlined runtime is ' +
+                  'unreachable and degrades to the embed-only floor. Exactly one of bundleUrl/' +
+                  'entryHtml is required when strategy is iframe-reachable.',
+              ),
+            baseHref: z
+              .string()
+              .optional()
+              .describe(
+                "Iframe <base href> so the game's relative asset URLs resolve (iframe-reachable only).",
+              ),
+            assetBaseUrl: z
+              .string()
+              .optional()
+              .describe(
+                "Host-side basePath forced onto the trapped runtime's own asset resolution — " +
+                  "pixi's `Assets.init` for a pixijs root, three's " +
+                  '`DefaultLoadingManager.setURLModifier` for a threejs root (D-W1) — absolute, or ' +
+                  "root-relative (resolved against the editor page's own origin at mount time, " +
+                  'ingest-mode.ts, so a static manifest never has to know the dev-server port) ' +
+                  '(iframe-reachable only — a document.write iframe keeps the parent window.location).',
+              ),
+            extraDeps: z
+              .array(z.string())
+              .optional()
+              .describe(
+                "Bare specifiers of this root's externalized deps beyond its own runtime " +
+                  "(pixi.js/three — e.g. '@pixi/sound', 'gsap'). Resolved by the editor's " +
+                  'host-namespace registry into module namespaces when known (D-P1 — the manifest ' +
+                  'carries data, not code); an unregistered specifier falls back to the open ' +
+                  "project's own node_modules (D-Z3, docs/WAVE3-ADAPTER-PLUMBING-DESIGN.md), served " +
+                  'as a verbatim iframe importmap URL. Throws a named error if neither resolves it ' +
+                  '(iframe-reachable only).',
+              ),
+            pixiModuleUrl: z
+              .string()
+              .optional()
+              .describe(
+                'PIXI-ONLY: standalone matching-major pixi ESM URL to trap instead of the host ' +
+                  "pixi, for version-skewed games (e.g. a v6 game on a v8 host); this field's " +
+                  'PRESENCE is how the skew is expressed (D-P2 — no separate strategy/tier for ' +
+                  'version skew) (iframe-reachable only). Declaring this on a `kind: "threejs"` ' +
+                  'root is schema-legal (this field is kind-agnostic here) but throws a NAMED ' +
+                  'not-supported error at resolve — three has no version-skew mount this wave (D-W7, ' +
+                  'docs/WAVE4-FTUE-HARDENING-DESIGN.md: a hypothetical `threeModuleUrl` is explicitly ' +
+                  'parked, no consumer exists).',
+              ),
+            bodyHtml: z
+              .string()
+              .optional()
+              .describe(
+                'HTML injected into the iframe body before the game script boots (e.g. a ' +
+                  '`<div id="game-root">` the game expects to find) (iframe-reachable only).',
+              ),
+          })
+          .describe(
+            'Ingest adapter configuration for an unmodified game (a repo-vendored game or your ' +
+              'own external folder)',
+          )
+          .superRefine((ingest, ctx) => {
+            // Track P (docs/PIXI-INGEST-LANDING-DESIGN.md §2/D-P4): the six
+            // iframe-reachable-multi fields only make sense for the
+            // iframe-reachable-multi mount — reject them under any other
+            // strategy (mirrors ui.ts's dead-field-under-wrong-variant pattern).
+            const iframeOnlyFields: ReadonlyArray<
+              readonly [
+                key:
+                  | 'bundleUrl'
+                  | 'baseHref'
+                  | 'assetBaseUrl'
+                  | 'extraDeps'
+                  | 'pixiModuleUrl'
+                  | 'bodyHtml',
+                present: boolean,
+              ]
+            > = [
+              ['bundleUrl', ingest.bundleUrl !== undefined],
+              ['baseHref', ingest.baseHref !== undefined],
+              ['assetBaseUrl', ingest.assetBaseUrl !== undefined],
+              ['extraDeps', ingest.extraDeps !== undefined],
+              ['pixiModuleUrl', ingest.pixiModuleUrl !== undefined],
+              ['bodyHtml', ingest.bodyHtml !== undefined],
+            ];
+            if (ingest.strategy !== 'iframe-reachable') {
+              for (const [key, present] of iframeOnlyFields) {
+                if (present) {
+                  ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    message:
+                      `\`${key}\` is only legal when strategy is 'iframe-reachable' (got ` +
+                      `"${ingest.strategy}") — bundleUrl/baseHref/assetBaseUrl/extraDeps/` +
+                      "pixiModuleUrl/bodyHtml are the iframe-reachable-multi mount's options " +
+                      '(pixijs: ingest-iframe-2d.ts IframeReachableMultiOpts; threejs, D-W1: ' +
+                      'ingest-iframe-reachable-adapter.ts IframeReachableBundleOpts) and have no ' +
+                      'meaning under any other strategy.',
+                    path: [key],
+                  });
+                }
               }
+              return;
             }
-            return;
-          }
-          const hasBundleUrl = ingest.bundleUrl !== undefined;
-          const hasEntryHtml = ingest.entryHtml !== undefined;
-          if (hasBundleUrl === hasEntryHtml) {
-            ctx.addIssue({
-              code: z.ZodIssueCode.custom,
-              message:
-                "strategy 'iframe-reachable' requires EXACTLY ONE of `bundleUrl` (externalized " +
-                'multi-file bundle, the iframe-reachable-multi mount) or `entryHtml` (single-' +
-                `file/legacy iframe entry) — ${hasBundleUrl ? 'both are present' : 'neither is present'}.`,
-              path: hasBundleUrl ? ['bundleUrl'] : ['entryHtml'],
-            });
-          }
-        }),
-    }),
+            const hasBundleUrl = ingest.bundleUrl !== undefined;
+            const hasEntryHtml = ingest.entryHtml !== undefined;
+            if (hasBundleUrl === hasEntryHtml) {
+              ctx.addIssue({
+                code: z.ZodIssueCode.custom,
+                message:
+                  "strategy 'iframe-reachable' requires EXACTLY ONE of `bundleUrl` (externalized " +
+                  'multi-file bundle, the iframe-reachable-multi mount) or `entryHtml` (single-' +
+                  `file/legacy iframe entry) — ${hasBundleUrl ? 'both are present' : 'neither is present'}.`,
+                path: hasBundleUrl ? ['bundleUrl'] : ['entryHtml'],
+              });
+            }
+          }),
+      })
+      .strict(),
   ])
   .describe(
-    "World adapter identity: 'default' (resolved by world kind to the built-in default " +
-      'adapter), a custom { module } adapter, or an { ingest } strategy for an unmodified ' +
-      'game (a repo-vendored game or your own external folder)',
+    "Root adapter identity: built-in 'threejs'/'pixijs'/'react', a custom " +
+      '{ module, surface } adapter, or an { ingest, surface } adapter for an unmodified game',
   );
-export type WorldAdapter = z.infer<typeof WorldAdapterSchema>;
+export type RootAdapter = z.infer<typeof RootAdapterSchema>;
 
 // ---------------------------------------------------------------------------
-// World entry
+// Root entry
 // ---------------------------------------------------------------------------
 
-export const WorldEntrySchema = z.object({
-  id: z
-    .string()
-    .describe(
-      'Unique id for this world within the manifest (enforced-unique, D-V6 — GameManifestSchema.worlds rejects duplicates)',
-    ),
-  kind: z
-    .enum(['threejs', 'pixijs', 'react'])
-    .describe('World render substrate kind (mirrors runtime/game.ts WorldKind)'),
-  description: z
-    .string()
-    .optional()
-    .describe(
-      "Optional one-line description of this world's game/content (e.g. an ingested game's " +
-        "blurb — the manifest-native replacement for a registry entry's description field)",
-    ),
-  adapter: WorldAdapterSchema.default('default').describe(
-    "This world's adapter — see WorldAdapterSchema; defaults to 'default' (resolved by kind)",
-  ),
-  scene: z
-    .string()
-    .optional()
-    .describe(
-      '.vscn.json / .scn2d.json scene path (default adapters only — ingest adapters keep their own formats)',
-    ),
-  entry: z
-    .string()
-    .optional()
-    .describe(
-      "Module exporting setup()/adapter (default adapters' code-authored alternative to `scene`)",
-    ),
-  zOrder: z
-    .number()
-    .int()
-    .default(0)
-    .describe('Canvas stacking order (COMPOSITION-DESIGN); ties broken by array order'),
-  pausable: z
-    .boolean()
-    .default(true)
-    .describe('Whether play-mode pause/step applies to this world'),
-  loop: z
-    .enum(['gated', 'self-driven'])
-    .default('gated')
-    .describe(
-      'gated: host-driven loop (default). self-driven: this world drives its own loop ' +
-        '(the "composited, unsynchronized" tier) — an axis independent of capability tier',
-    ),
-  capabilities: z
-    .object({
-      local: TierSchema.optional().describe(
-        'Declared capability tier when served via the local CLI (Vite pipeline); omitted -> derived (§4)',
+export const AdapterRootSchema = z
+  .object({
+    id: z
+      .string()
+      .describe(
+        'Unique id for this root within the manifest (enforced-unique, D-V6 — GameManifestSchema.roots rejects duplicates)',
       ),
-      hosted: TierSchema.optional().describe(
-        'Declared capability tier when served hosted (no bundler: esbuild-wasm + externals only); omitted -> derived (§4)',
+    description: z
+      .string()
+      .optional()
+      .describe(
+        "Optional one-line description of this root's game/content (e.g. an ingested game's " +
+          "blurb — the manifest-native replacement for a registry entry's description field)",
       ),
-    })
-    .optional()
-    .describe(
-      "Per-delivery-context capability tier declarations (§4). Declaring above the adapter's " +
-        'ceiling for that context is an error; declaring at or below it (including `unsupported`) is legal.',
+    adapter: RootAdapterSchema.describe(
+      "This root's adapter and sole rendering/lifecycle discriminator",
     ),
-});
-export type WorldEntry = z.infer<typeof WorldEntrySchema>;
+    scene: z
+      .string()
+      .optional()
+      .describe(
+        '.vscn.json / .scn2d.json scene path (default adapters only — ingest adapters keep their own formats)',
+      ),
+    entry: z
+      .string()
+      .optional()
+      .describe(
+        "Module exporting setup()/adapter (default adapters' code-authored alternative to `scene`)",
+      ),
+    zOrder: z
+      .number()
+      .int()
+      .default(0)
+      .describe('Canvas stacking order (COMPOSITION-DESIGN); ties broken by array order'),
+    pausable: z
+      .boolean()
+      .default(true)
+      .describe('Whether play-mode pause/step applies to this root'),
+    loop: z
+      .enum(['gated', 'self-driven'])
+      .default('gated')
+      .describe(
+        'gated: host-driven loop (default). self-driven: this root drives its own loop ' +
+          '(the "composited, unsynchronized" tier) — an axis independent of capability tier',
+      ),
+    capabilities: z
+      .object({
+        local: TierSchema.optional().describe(
+          'Declared capability tier when served via the local CLI (Vite pipeline); omitted -> derived (§4)',
+        ),
+        hosted: TierSchema.optional().describe(
+          'Declared capability tier when served hosted (no bundler: esbuild-wasm + externals only); omitted -> derived (§4)',
+        ),
+      })
+      .optional()
+      .describe(
+        "Per-delivery-context capability tier declarations (§4). Declaring above the adapter's " +
+          'ceiling for that context is an error; declaring at or below it (including `unsupported`) is legal.',
+      ),
+  })
+  .strict();
+export type AdapterRoot = z.infer<typeof AdapterRootSchema>;
 
 // ---------------------------------------------------------------------------
 // Game manifest (vgai.game.json)
@@ -309,8 +321,25 @@ export type WorldEntry = z.infer<typeof WorldEntrySchema>;
 
 export const GameManifestSchema = z
   .object({
-    manifestVersion: z.literal(1).describe('Manifest file format version (currently always 1)'),
+    $schema: z
+      .string()
+      .optional()
+      .describe('Optional JSON Schema URI for editor autocomplete and validation'),
+    manifestVersion: z
+      .literal(GAME_MANIFEST_VERSION)
+      .describe('Manifest file format version (v2 clean roots)'),
     name: z.string().describe('Game display name'),
+    appId: z
+      .string()
+      .optional()
+      .describe('Stable reverse-domain application id used by packaged targets'),
+    editorPort: z
+      .number()
+      .int()
+      .min(1024)
+      .max(65535)
+      .optional()
+      .describe('Stable preferred local editor port; launchers may fall forward when occupied'),
     version: z.string().describe("The game's own version (used for orphan detection)"),
     engine: z
       .object({
@@ -322,22 +351,22 @@ export const GameManifestSchema = z
           ),
       })
       .describe('Engine version pin'),
-    worlds: z
-      .array(WorldEntrySchema)
+    roots: z
+      .array(AdapterRootSchema)
       .min(1)
-      .superRefine((worlds, ctx) => {
+      .superRefine((roots, ctx) => {
         // D-V6 (docs/WAVE5-MULTIWORLD-INGEST-DESIGN.md §1G debt,
-        // docs/MULTI-WORLD-DESIGN.md §1G): world ids are described as unique
+        // docs/MULTI-WORLD-DESIGN.md §1G): root ids are described as unique
         // above but that was describe-only at the SCHEMA level — only
         // load.ts's loader-level cross-field check caught a collision, so
         // any OTHER consumer of this schema (the generated JSON Schema,
         // editor tooling) saw duplicate ids as legal. Enforced HERE instead,
         // naming every colliding id (not just the first found) — overlay
-        // files are keyed by world id (`.vgai/overlays/<id>.json`), so a
-        // silently-permitted duplicate would have two worlds silently share
+        // files are keyed by root id (`.vgai/overlays/<id>.json`), so a
+        // silently-permitted duplicate would have two roots silently share
         // one overlay.
         const counts = new Map<string, number>();
-        for (const world of worlds) counts.set(world.id, (counts.get(world.id) ?? 0) + 1);
+        for (const root of roots) counts.set(root.id, (counts.get(root.id) ?? 0) + 1);
         const duplicates = [...counts.entries()].filter(([, n]) => n > 1).map(([id]) => id);
         if (duplicates.length === 0) return;
         const idsText = duplicates.map((id) => `"${id}"`).join(', ');
@@ -345,11 +374,40 @@ export const GameManifestSchema = z
           code: z.ZodIssueCode.custom,
           message:
             duplicates.length === 1
-              ? `Game manifest: duplicate world id ${idsText} — world ids must be unique across the manifest (enforced-unique).`
-              : `Game manifest: duplicate world ids: ${idsText} — world ids must be unique across the manifest (enforced-unique).`,
+              ? `Game manifest: duplicate root id ${idsText} — root ids must be unique across the manifest (enforced-unique).`
+              : `Game manifest: duplicate root ids: ${idsText} — root ids must be unique across the manifest (enforced-unique).`,
         });
       })
-      .describe("The Game's world list — this manifest is its serialized form"),
+      .describe(
+        "The Game's explicit, non-empty adapter-root composition. There is no implicit root.",
+      ),
+    authoring: z
+      .object({
+        hierarchy: z
+          .object({
+            rootLabels: z
+              .record(z.string(), z.string())
+              .optional()
+              .describe('Optional editor labels keyed by adapter-root id'),
+            groups: z
+              .array(
+                z.object({
+                  id: z.string().describe('Unique editor-only group id'),
+                  label: z.string().describe('Editor-only group label'),
+                  roots: z
+                    .array(z.string())
+                    .min(1)
+                    .describe('Adapter-root ids shown under this editor-only group'),
+                }),
+              )
+              .optional()
+              .describe('Optional editor-only hierarchy groups'),
+          })
+          .optional()
+          .describe('Editor projection for native adapter roots'),
+      })
+      .optional()
+      .describe('Editor-only authoring metadata; never runtime ownership'),
     server: z
       .object({
         room: z.string().describe('Colyseus room name'),
@@ -368,8 +426,57 @@ export const GameManifestSchema = z
         height: z.number().describe('Canvas height in pixels'),
       })
       .optional()
-      .describe("Canvas resolution (subsumed from today's project.json)"),
+      .describe('Canvas resolution'),
+    debug: z
+      .object({
+        allowInProduction: z
+          .boolean()
+          .describe(
+            'Allow the ?vgai-debug=1 introspection bridge and debug-command invocation in ' +
+              'production builds. Default false: the bridge only installs in dev builds. The ' +
+              'runtime reader is the debug-bridge installer (D18).',
+          ),
+      })
+      .optional()
+      .describe(
+        'Debug-bridge production gating (D18) — governs whether ?vgai-debug=1 installs ' +
+          'window.__vgai outside dev builds.',
+      ),
+    determinism: z
+      .object({
+        seededRandom: z
+          .boolean()
+          .describe(
+            'Declares that ALL gameplay RNG in this project flows through ctx.random (the ' +
+              'named-stream seeded PRNG, docs/D15-DETERMINISM-DESIGN.md) rather than raw ' +
+              'Math.random/Date.now/performance.now. Three runtime enforcers key off this flag: ' +
+              'the boot-time seeding reader (mount-manifest.ts seeds ctx.random from ' +
+              'defaultSeed/?vgai-seed=/explicit config, in that precedence, only when true), the ' +
+              'gameplay-rng-ban burn-down scan (test/gameplay-rng-ban.test.ts — lints this ' +
+              "project's src/ for raw RNG/wall-clock calls), and the dev-mode Math.random phase " +
+              'trap (runtime/gameplay-rng-trap.ts — warns once per call site during a gameplay ' +
+              'frame, never throws). Default false: an undeclared project gets no determinism ' +
+              'contract at all (that IS the opt-out — no dead field, per the T4.1 policy).',
+          ),
+        defaultSeed: z
+          .number()
+          .int()
+          .optional()
+          .describe(
+            'The seed ctx.random boots from when seededRandom is true, unless overridden by ' +
+              '?vgai-seed=<int> (the query param always wins over this manifest default) or an ' +
+              'even higher-precedence explicit config value a host passes directly. Optional — ' +
+              "omit to fall back to the runtime's own fixed default seed.",
+          ),
+      })
+      .optional()
+      .describe(
+        'Seeded-RNG determinism contract (D15, docs/D15-DETERMINISM-DESIGN.md) — governs ' +
+          'whether ctx.random is boot-seeded from a reproducible seed and whether the ' +
+          'gameplay-rng-ban scan / dev-mode Math.random phase trap are active for this project.',
+      ),
   })
-  .describe('Game manifest (vgai.game.json) — the serialized form of the Game world list');
+  .strict()
+  .describe('Game manifest (vgai.game.json) — the complete v2 project configuration');
 
 export type GameManifest = z.infer<typeof GameManifestSchema>;