@forgeax/engine-scene 0.1.28 → 0.1.30

package/src/instances/scene-instances.ts

@@ -17,12 +17,11 @@ import { fillComponentDefaults, StaleEntityError } from '@forgeax/engine-ecs/pro
 import type {
   Handle,
   LocalEntityId,
-  MountOverride,
   PackErrorCode,
   PackErrorDetail,
   SceneAsset,
+  SceneEntityAddress,
   SceneEntityRef,
-  SceneInstanceMount,
 } from '@forgeax/engine-types';
 import {
   err,
@@ -33,7 +32,13 @@ import {
   unwrapHandle,
 } from '@forgeax/engine-types';
 import { ComponentNotDefinedError } from '../errors';
-import { resolveSceneEntity, validateSceneBindings } from './binding.js';
+import { resolveSceneEntity, sceneEntityAddressKey } from './binding.js';
+import {
+  type CompiledSceneAsset,
+  type CompiledSceneEntity,
+  compileKeyedSceneAsset,
+} from './keyed.js';
+import type { MountOverride, SceneInstanceMount } from './runtime-types.js';
 import {
   isPrimitiveScalarFieldType,
   mountOverrideStateKey,
@@ -48,39 +53,32 @@ const entityIndex = (entity: EntityHandle): number => (entity as number) & 0x00f
 const entityGeneration = (entity: EntityHandle): number => ((entity as number) >>> 24) & 0xff;
 
 /**
- * C-R2 (feat-20260622-s5 / studio-issues): one structured, non-fatal record of
- * a SceneAsset payload field that did NOT match the target component's schema.
- *
- * Scene data is loader-fed and may carry a stale / deprecated / typo'd field
- * (an editor renames a field, an old `.pack.json` lags). `worldInstantiateScene`
- * does NOT blank the whole scene over one such field (#478 lesson: a
- * prod-silent strip re-introduced an invisible-entity class) and does NOT abort
- * fatally. Instead it skips the unknown key (no write, no input mutation) and
- * surfaces this record on the success value's `diagnostics[]` — observable in
- * production (NOT NODE_ENV-gated), consumed by property access (no string parse):
+ * Legacy diagnostic shape retained on the scene-instantiation result for
+ * non-blocking runtime observations. SceneAsset schema violations are
+ * rejected by the keyed compiler before this result is produced; no authored
+ * unknown-field record is emitted by the current path.
  *
  *   const r = worldInstantiateScene(world, handle);
  *   if (r.ok) for (const d of r.value.diagnostics)
- *     console.warn(`unknown field ${d.component}.${d.field} on localId ${d.localId}`);
+ *     console.warn('scene diagnostic', d);
  *
- * Direct `world.spawn` / `world.addComponent` / `Commands.spawn` stay fail-fast
- * with `SpawnDataUnknownFieldError` — those are explicit API calls where a typo
- * is a programming error, not loader-fed data.
+ * Direct `world.spawn` / `world.addComponent` / `Commands.spawn` remain
+ * fail-fast with `SpawnDataUnknownFieldError`.
  */
 export type SceneInstantiateDiagnostic = {
-  /** Component name (schema key) the unknown field appeared under. */
+  /** Component name associated with the observation. */
   readonly component: string;
-  /** The offending field name not declared in the component schema. */
+  /** Field associated with the observation. */
   readonly field: string;
-  /** LocalEntityId (within its owning SceneAsset) of the carrying entity. */
+  /** LocalEntityId within the owning SceneAsset, when applicable. */
   readonly localId: number;
 };
 
 /**
  * Success value of `worldInstantiateScene`. `root` is the synthetic scene-root
- * EntityHandle (carries `SceneInstance`); `diagnostics` is the (possibly empty)
- * list of non-fatal unknown-field records aggregated across this scene and every
- * recursively mounted sub-scene (C-R2). Empty array = no diagnostics.
+ * EntityHandle (carries `SceneInstance`); `diagnostics` contains only
+ * non-blocking runtime observations. Schema-invalid authored fields fail before
+ * an entity is created.
  */
 export type SceneInstantiateOk = {
   readonly root: EntityHandle;
@@ -137,11 +135,50 @@ export interface SceneMembersSpawn {
     readonly mount: SceneInstanceMount;
     readonly root: EntityHandle;
     readonly mapping: Uint32Array;
+    readonly key?: string;
   }[];
   /** `entities.length + mounts + Σ memberCount`, captured at instantiate-time. */
   readonly totalSlots: number;
 }
 
+/**
+ * Populate the instance binding projection from the private numeric mapping.
+ * The authored key remains the only lookup identity: nested instance paths are
+ * represented as the same string/tuple key accepted by `SceneEntityRef`, while
+ * the numeric mapping stays local to the Scene owner.
+ */
+function collectSceneEntityBindings(
+  world: World,
+  root: EntityHandle,
+  prefix: readonly string[],
+  bindings: Map<string, EntityHandle>,
+  visited = new Set<number>(),
+): void {
+  const rootRaw = root as unknown as number;
+  if (visited.has(rootRaw)) return;
+  visited.add(rootRaw);
+  const state = worldResolveSceneInstanceStatePayload(world, root);
+  if (!state.ok) return;
+  const sceneInstance = world.components.resolve('SceneInstance');
+  if (sceneInstance === undefined) return;
+  const component = world.get(root, sceneInstance);
+  if (!component.ok) return;
+  const mapping = (component.value as unknown as { mapping: ArrayLike<number> }).mapping;
+  for (const [slot, key] of state.value.keyByLocalId) {
+    const raw = mapping[slot];
+    if (raw === undefined || raw === ENTITY_NULL_RAW) continue;
+    const address: SceneEntityAddress =
+      prefix.length === 0 ? key : ([...prefix, key] as unknown as [string, ...string[]]);
+    bindings.set(sceneEntityAddressKey(address), raw as unknown as EntityHandle);
+  }
+  for (const childRoot of state.value.mountRoots) {
+    const childState = worldResolveSceneInstanceStatePayload(world, childRoot);
+    const childKey = childState.ok ? childState.value.instanceKey : undefined;
+    if (childKey === undefined) continue;
+    collectSceneEntityBindings(world, childRoot, [...prefix, childKey], bindings, visited);
+  }
+}
+
 export type SceneAssetResolver = (
   source: number | string,
   parentHandle: Handle<'SceneAsset', 'shared'>,
@@ -173,8 +210,8 @@ export function worldGetSceneAssetResolver(world: World): SceneAssetResolver | n
  *   const r = worldInstantiateScene(world, handle);
  *   if (!r.ok) return r;
  *   const { root, diagnostics } = r.value;
- *   for (const d of diagnostics) // C-R2: unknown-field records, non-fatal
- *     console.warn(`unknown field ${d.component}.${d.field} on localId ${d.localId}`);
+ *   for (const d of diagnostics) // non-blocking runtime observations
+ *     console.warn('scene diagnostic', d);
  *   const inst = world.get(root, SceneInstance).value;
  *   const member = inst.mapping[0]; // first member entity
  */
@@ -182,13 +219,21 @@ export function worldInstantiateScene(
   world: World,
   handle: Handle<'SceneAsset', 'shared'>,
   parent?: EntityHandle,
+  sceneSourceKey?: string,
 ): Result<SceneInstantiateOk, EcsError> {
   const stack = new Set<number>();
-  // C-R2: collect non-fatal unknown-field diagnostics across this scene and
-  // every recursively mounted sub-scene. The internal recursion writes into
-  // this accumulator; only the public entry packages it onto the success value.
+  // Keep the existing result shape for non-blocking runtime observations. The
+  // keyed compiler rejects schema-invalid authoring data before spawning.
   const diagnostics: SceneInstantiateDiagnostic[] = [];
-  const r = worldInstantiateSceneRec(world, handle, parent, stack, diagnostics);
+  const r = worldInstantiateSceneRec(
+    world,
+    handle,
+    parent,
+    stack,
+    diagnostics,
+    undefined,
+    sceneSourceKey,
+  );
   if (!r.ok) return r;
   return ok({ root: r.value, diagnostics });
 }
@@ -264,6 +309,8 @@ export function worldInstantiateSceneRec(
   parent: EntityHandle | undefined,
   stack: Set<number>,
   diagnostics: SceneInstantiateDiagnostic[],
+  instanceKey?: string,
+  sceneSourceKey?: string,
 ): Result<EntityHandle, EcsError> {
   const handleKey = unwrapHandle(handle);
   if (stack.has(handleKey)) {
@@ -287,7 +334,16 @@ export function worldInstantiateSceneRec(
   const asset = resolved.value;
   stack.add(handleKey);
   try {
-    return worldInstantiateSceneAsset(world, handle, asset, parent, stack, diagnostics);
+    return worldInstantiateSceneAsset(
+      world,
+      handle,
+      asset,
+      parent,
+      stack,
+      diagnostics,
+      instanceKey,
+      sceneSourceKey,
+    );
   } finally {
     stack.delete(handleKey);
   }
@@ -320,9 +376,10 @@ export function worldResolveSceneAsset(
 export function worldSpawnSceneMembers(
   world: World,
   handle: Handle<'SceneAsset', 'shared'>,
-  asset: SceneAsset,
+  asset: CompiledSceneAsset,
   stack: Set<number>,
   diagnostics: SceneInstantiateDiagnostic[],
+  mountKeys?: ReadonlyMap<number, string>,
 ): Result<SceneMembersSpawn, EcsError> {
   const sceneInstanceToken = world.components.resolve('SceneInstance');
   if (sceneInstanceToken === undefined) {
@@ -335,15 +392,6 @@ export function worldSpawnSceneMembers(
 
   const ownEntities = asset.entities;
   const ownMounts = asset.mounts ?? [];
-  const bindingKeys = ownEntities.flatMap((entity) =>
-    entity.bindingKey === undefined ? [] : [entity.bindingKey],
-  );
-  if (bindingKeys.length > 0) {
-    const bindingCheck = validateSceneBindings(asset.sourceKey ?? '', bindingKeys);
-    if (!bindingCheck.ok) {
-      return err(bindingCheck.error as unknown as EcsError);
-    }
-  }
   const memberSum = ownMounts.reduce((s, m) => s + m.memberCount, 0);
   const countBaseline = ownEntities.length + ownMounts.length + memberSum;
   // C-R1 (studio-issues #6): mapping table must be sized to maxLocalId+1,
@@ -469,10 +517,16 @@ export function worldSpawnSceneMembers(
     const childHandle = childHandleRes.value;
 
     // Recursively instantiate the child. Its synthetic root attaches as a
-    // child of the mount entity. The child writes its own unknown-field
-    // diagnostics into the SAME accumulator, so they bubble to the top-level
-    // instantiateScene result (C-R2 recursive aggregation).
-    const childRes = worldInstantiateSceneRec(world, childHandle, mountEntity, stack, diagnostics);
+    // child of the mount entity; runtime observations share the same result
+    // accumulator and bubble to the top-level instance.
+    const childRes = worldInstantiateSceneRec(
+      world,
+      childHandle,
+      mountEntity,
+      stack,
+      diagnostics,
+      mountKeys?.get(mountLid),
+    );
     if (!childRes.ok) return childRes;
 
     // R2/B-2: cross-check mount.memberCount === child.totalSlots BEFORE
@@ -482,7 +536,12 @@ export function worldSpawnSceneMembers(
     const childInstRes = world.get(childRes.value, sceneInstanceToken);
     if (!childInstRes.ok) return childInstRes;
     const childMapping = (childInstRes.value as unknown as { mapping: Uint32Array }).mapping;
-    mountInstances.push({ mount, root: childRes.value, mapping: childMapping });
+    mountInstances.push({
+      mount,
+      root: childRes.value,
+      mapping: childMapping,
+      ...(mountKeys?.get(mountLid) === undefined ? {} : { key: mountKeys.get(mountLid) }),
+    });
     if (childMapping.length !== mount.memberCount) {
       return err({
         code: 'pack-mount-count-mismatch' as PackErrorCode,
@@ -614,6 +673,8 @@ export function worldInstantiateSceneAsset(
   parent: EntityHandle | undefined,
   stack: Set<number>,
   diagnostics: SceneInstantiateDiagnostic[],
+  instanceKey?: string,
+  sceneSourceKey?: string,
 ): Result<EntityHandle, EcsError> {
   const sceneInstanceToken = world.components.resolve('SceneInstance');
   if (sceneInstanceToken === undefined) {
@@ -621,12 +682,26 @@ export function worldInstantiateSceneAsset(
   }
   const childOfToken = world.components.resolve('ChildOf');
 
-  const membersRes = worldSpawnSceneMembers(world, handle, asset, stack, diagnostics);
+  const compiled = compileKeyedSceneAsset(world, handle, asset, {
+    resolveSource: (source, parentHandle) => worldResolveMountSource(world, source, parentHandle),
+    resolveAsset: (childHandle) => worldResolveSceneAsset(world, childHandle),
+    stack,
+  });
+  if (!compiled.ok) return err(compiled.error as EcsError);
+  const compiledAsset = compiled.value.asset;
+  const membersRes = worldSpawnSceneMembers(
+    world,
+    handle,
+    compiledAsset,
+    stack,
+    diagnostics,
+    compiled.value.mountKeyByLocalId,
+  );
   if (!membersRes.ok) return membersRes;
   const { mapping, entityToLocalId, rootEntities, mountEntitiesNeedingRootParent, totalSlots } =
     membersRes.value;
   const { mountInstances } = membersRes.value;
-  const ownMounts = asset.mounts ?? [];
+  const ownMounts = compiledAsset.mounts ?? [];
 
   // 3. Spawn the synthetic root entity carrying SceneInstance.
   //    First alloc the state ref so the SceneInstance.state column has a
@@ -697,7 +772,11 @@ export function worldInstantiateSceneAsset(
       const memberEntityRaw = mapping[lid as unknown as number];
       if (memberEntityRaw !== undefined && memberEntityRaw !== ENTITY_NULL_RAW) {
         const memberEntity = memberEntityRaw as unknown as EntityHandle;
-        const applyRes = worldApplyMountOverride(world, memberEntity, ov);
+        const applyRes = worldApplyMountOverride(
+          world,
+          memberEntity,
+          worldRemapMountOverride(world, ov, mapping),
+        );
         if (!applyRes.ok) {
           return applyRes as Result<EntityHandle, EcsError>;
         }
@@ -707,16 +786,11 @@ export function worldInstantiateSceneAsset(
 
   const detached = new Set<LocalEntityId>();
   const bindings = new Map<string, EntityHandle>();
-  for (const entity of asset.entities) {
-    if (entity.bindingKey === undefined) continue;
-    const live = mapping[entity.localId as unknown as number];
-    if (live !== undefined && live !== ENTITY_NULL_RAW) {
-      bindings.set(entity.bindingKey, live as unknown as EntityHandle);
-    }
-  }
   const state: Record<string, unknown> = {
     source: handle,
-    sceneSourceKey: asset.sourceKey,
+    ...(sceneSourceKey === undefined ? {} : { sceneSourceKey }),
+    keyByLocalId: new Map(compiled.value.keyByLocalId),
+    ...(instanceKey === undefined ? {} : { instanceKey }),
     bindings,
     entityToLocalId,
     detachedLocalIds: detached,
@@ -732,6 +806,10 @@ export function worldInstantiateSceneAsset(
   // re-use the slot we allocated above by writing directly into the
   // payloads map via a `_setUniqueRefPayload` shim.
   worldSetUniqueRefPayload(world, stateRef, state);
+  // Populate direct and nested keyed addresses only after this root state is
+  // visible. Child SceneInstance states were published by the recursive spawn
+  // above, so the same walk can project the complete address closure.
+  collectSceneEntityBindings(world, rootEntity, [], bindings);
 
   // 5. Wire ChildOf for every owned root entity (no ChildOf at layer-1)
   //    to the synthetic root.
@@ -792,7 +870,20 @@ export function worldInstantiateSceneAssetFlat(
   stack: Set<number>,
   diagnostics: SceneInstantiateDiagnostic[],
 ): Result<{ roots: EntityHandle[]; mountEntities: EntityHandle[] }, EcsError> {
-  const membersRes = worldSpawnSceneMembers(world, handle, asset, stack, diagnostics);
+  const compiled = compileKeyedSceneAsset(world, handle, asset, {
+    resolveSource: (source, parentHandle) => worldResolveMountSource(world, source, parentHandle),
+    resolveAsset: (childHandle) => worldResolveSceneAsset(world, childHandle),
+    stack,
+  });
+  if (!compiled.ok) return err(compiled.error as EcsError);
+  const membersRes = worldSpawnSceneMembers(
+    world,
+    handle,
+    compiled.value.asset,
+    stack,
+    diagnostics,
+    compiled.value.mountKeyByLocalId,
+  );
   if (!membersRes.ok) return membersRes;
   const { rootEntities, mountEntitiesNeedingRootParent, mountEntities, mountInstances } =
     membersRes.value;
@@ -811,7 +902,11 @@ export function worldInstantiateSceneAssetFlat(
       const memberEntityRaw = childMapping[childLocalId];
       if (memberEntityRaw === undefined || memberEntityRaw === ENTITY_NULL_RAW) continue;
       const memberEntity = memberEntityRaw as unknown as EntityHandle;
-      const applyRes = worldApplyMountOverride(world, memberEntity, ov);
+      const applyRes = worldApplyMountOverride(
+        world,
+        memberEntity,
+        worldRemapMountOverride(world, ov, childMapping),
+      );
       if (!applyRes.ok) {
         return applyRes as Result<
           { roots: EntityHandle[]; mountEntities: EntityHandle[] },
@@ -849,21 +944,15 @@ export function worldInstantiateSceneAssetFlat(
 }
 /** @internal Build ComponentData[] for one SceneEntity, remapping localIds.
  *
- * C-R2 (feat-20260622-s5 M6): unknown fields on a SceneAsset payload are NOT
- * fatal. Unlike `world.spawn` (an explicit API call where a typo is a
- * programming error -> `SpawnDataUnknownFieldError`), scene data is loader-fed
- * and may carry a stale / deprecated / typo'd field. The remap below builds a
- * fresh `remappedRaw` and simply SKIPS keys absent from the schema (no input
- * mutation — the source `raw` is never deleted-from), recording each skipped
- * key as a non-fatal `SceneInstantiateDiagnostic` into the passed accumulator.
- * All known fields still write through, so one bad field cannot blank the
- * entity or the scene (C-AC-02/03/04).
+ * SceneAsset payloads use the same schema contract as explicit ECS writes.
+ * Unknown fields fail before the first entity is spawned, with the component
+ * schema's structured error. The source object is never mutated.
  */
 export function worldBuildSceneEntityComponentDatas(
   world: World,
-  node: import('@forgeax/engine-types').SceneEntity,
+  node: CompiledSceneEntity,
   mapping: Uint32Array,
-  diagnostics: SceneInstantiateDiagnostic[],
+  _diagnostics: SceneInstantiateDiagnostic[],
 ): Result<ComponentData[], EcsError> {
   const out: ComponentData[] = [];
   const nodeLocalId = node.localId as unknown as number;
@@ -877,13 +966,21 @@ export function worldBuildSceneEntityComponentDatas(
     const remappedRaw: Record<string, unknown> = {};
     for (const fieldName of Object.keys(raw)) {
       const fieldType = schema[fieldName];
-      // C-R2: unknown key -> skip (do not copy into remappedRaw, do not
-      // mutate the source `raw`) and record a structured diagnostic. The
-      // downstream `spawn` only sees schema-valid keys, so its own
-      // validateComponentDataKeys gate stays green.
+      // Do not mutate the source `raw`. SceneAsset compilation normally catches
+      // this earlier; this guard keeps the private numeric projection fail-fast
+      // for callers that provide a precompiled asset.
       if (fieldType === undefined) {
-        diagnostics.push({ component: compName, field: fieldName, localId: nodeLocalId });
-        continue;
+        return err({
+          code: 'spawn-data-unknown-field',
+          expected: `field name in {${Object.keys(schema).sort().join(', ')}}`,
+          hint: `unknown field '${fieldName}' on component '${compName}' at scene localId ${nodeLocalId}`,
+          detail: {
+            component: compName,
+            field: fieldName,
+            entity: nodeLocalId,
+            knownFields: Object.keys(schema).sort(),
+          },
+        } as unknown as EcsError);
       }
       const value = (raw as Record<string, unknown>)[fieldName];
       const kind = classifyEntityField(token, fieldName);
@@ -905,6 +1002,46 @@ export function worldBuildSceneEntityComponentDatas(
   }
   return ok(out);
 }
+
+/**
+ * Resolve the private local-slot values produced by keyed SceneAsset
+ * compilation before an instance override is written to a live ECS row.
+ * Override references are authored in the declaring parent namespace, while
+ * `worldApplyMountOverride` deliberately accepts ordinary live component data.
+ */
+function worldRemapMountOverride(
+  world: World,
+  override: MountOverride,
+  mapping: Uint32Array,
+): MountOverride {
+  const token = world.components.resolve(override.comp);
+  if (token === undefined) return override;
+  const remapField = (field: string, value: unknown): unknown => {
+    const kind = classifyEntityField(token as Component, field);
+    if (kind === null) return value;
+    const toLive = (slot: number): number => {
+      if (slot < 0 || slot >= mapping.length) return ENTITY_NULL_RAW;
+      return mapping[slot] ?? ENTITY_NULL_RAW;
+    };
+    return remapEntityFieldValue(value, kind, toLive);
+  };
+  if (override.field !== undefined) {
+    return { ...override, value: remapField(override.field, override.value) };
+  }
+  if (
+    typeof override.value !== 'object' ||
+    override.value === null ||
+    Array.isArray(override.value)
+  ) {
+    return override;
+  }
+  const value: Record<string, unknown> = {};
+  for (const [field, fieldValue] of Object.entries(override.value as Record<string, unknown>)) {
+    value[field] = remapField(field, fieldValue);
+  }
+  return { ...override, value };
+}
+
 /**
  * @internal feat-20260713 M2 / w8: apply one MountOverride to a live member
  * entity column. The `field?` shape is the add-or-patch discriminant:
@@ -1058,7 +1195,7 @@ export function worldSpawnMountEntity(
   mapping: Uint32Array,
   diagnostics: SceneInstantiateDiagnostic[],
 ): Result<EntityHandle, EcsError> {
-  const fakeNode: import('@forgeax/engine-types').SceneEntity = {
+  const fakeNode: CompiledSceneEntity = {
     localId: mount.localId,
     components: mount.components ?? {},
   };
@@ -1203,8 +1340,11 @@ export function worldResolveSceneEntity(
 ): Result<EntityHandle, EcsError> {
   const state = worldResolveSceneInstanceStatePayload(world, root);
   if (!state.ok) return state;
+  // Anonymous POD scenes remain addressable with an explicit empty source key.
+  // Never let the caller supply the identity used for the comparison: that
+  // would make an anonymous instance accept a fabricated persistent ref.
   const resolved = resolveSceneEntity(ref, {
-    sceneSourceKey: state.value.sceneSourceKey ?? ref.sceneSourceKey,
+    sceneSourceKey: state.value.sceneSourceKey ?? '',
     bindings: state.value.bindings,
   });
   if (!resolved.ok) return err(resolved.error as unknown as EcsError);
@@ -1428,9 +1568,8 @@ export function worldRemoveSceneOverride<S extends ComponentSchema>(
   // Look up the source SceneAsset layer-1 value.
   const assetRes = worldResolveSceneAsset(world, state.source);
   if (!assetRes.ok) return assetRes;
-  const node = assetRes.value.entities.find(
-    (n) => (n.localId as unknown as number) === (lid as unknown as number),
-  );
+  const key = state.keyByLocalId.get(lid as unknown as number);
+  const node = key === undefined ? undefined : assetRes.value.entities[key];
   const layer1 = node?.components[component.name] as Record<string, unknown> | undefined;
   if (layer1 !== undefined && field in layer1) {
     const r = world.set(member, component, { [field]: layer1[field] } as Partial<InputShapeOf<S>>);
@@ -1489,9 +1628,7 @@ export function worldGetSceneAssetForInstance(
  * reachable from indegree-0 (the fallback caller handles cycle reporting via
  * `pack-cyclic-reference` at the upstream scanner / runtime path).
  */
-function sceneTopoSort(
-  nodes: readonly import('@forgeax/engine-types').SceneEntity[],
-): readonly number[] {
+function sceneTopoSort(nodes: readonly CompiledSceneEntity[]): readonly number[] {
   const n = nodes.length;
   const childrenOf: number[][] = Array.from({ length: n }, () => []);
   const indeg = new Uint32Array(n);

package/src/instances/state.ts

@@ -1,10 +1,15 @@
 import type { EntityHandle, World } from '@forgeax/engine-ecs';
-import type { Handle, LocalEntityId, MountOverride } from '@forgeax/engine-types';
+import type { Handle, LocalEntityId } from '@forgeax/engine-types';
+import type { MountOverride } from './runtime-types.js';
 
 /** Internal state retained by a SceneInstance root. */
 export interface SceneInstanceStatePayload {
   readonly source: Handle<'SceneAsset', 'shared'>;
   readonly sceneSourceKey?: string;
+  /** Authored key for each private numeric slot, retained for collection. */
+  readonly keyByLocalId: Map<number, string>;
+  /** Authored key of this instance when it is nested in a parent scene. */
+  readonly instanceKey?: string;
   readonly bindings: Map<string, EntityHandle>;
   readonly entityToLocalId: Map<EntityHandle, LocalEntityId>;
   readonly detachedLocalIds: Set<LocalEntityId>;