@forgeax/engine-assets-runtime 0.1.4 → 0.1.7

package/src/errors/asset.ts

@@ -0,0 +1,347 @@
+// @forgeax/engine-assets-runtime -- asset cluster error classes.
+//
+// feat-20260704-runtime-tier1-decomposition M2 / w8 (D-3): asset-resolution
+// cluster -- material parent-chain resolve, mesh-SSBO grow ceiling, and
+// scene-collect GUID / forest-closure fail-fast errors. Class names, .code
+// literals, and .detail shapes preserved byte-for-byte (OOS-4).
+//
+// The cluster union type is named AssetRuntimeError / AssetRuntimeErrorCode
+// (not AssetError / AssetErrorCode) because @forgeax/engine-types already owns
+// the AssetError class + AssetErrorCode union (asset-system-v1); D-8 grep
+// uniqueness forbids the collision.
+
+import type { MeshBinHeaderV4 } from '@forgeax/engine-pack';
+import {
+  AssetError,
+  type AssetErrorDetail,
+  type AssetMeshBinContractFacts,
+  type AssetMeshBinContractViolationReason,
+} from '@forgeax/engine-types';
+
+export class MeshBinAssetError extends AssetError {
+  readonly subject = 'mesh-bin' as const;
+  readonly sourceKey: string;
+  readonly actual: string;
+  readonly recovery = 're-cook the source with its Meta sidecar through the build-time importer';
+
+  constructor(args: {
+    readonly sourceKey: string;
+    readonly expected: string;
+    readonly actual: string;
+    readonly header?: Partial<MeshBinHeaderV4> & { readonly byteLength?: number };
+    readonly reason?: AssetMeshBinContractViolationReason;
+    readonly expectedFacts?: AssetMeshBinContractFacts;
+    readonly actualFacts?: AssetMeshBinContractFacts;
+  }) {
+    const expectedFacts: AssetMeshBinContractFacts = args.expectedFacts ?? {
+      version: 4,
+      projectionVersion: 1,
+    };
+    const actualFacts: AssetMeshBinContractFacts = {
+      ...(args.header ?? {}),
+      ...(args.actualFacts ?? {}),
+    };
+    const detail: AssetErrorDetail = {
+      code: 'mesh-bin-contract-violation',
+      sourceKey: args.sourceKey,
+      reason: args.reason ?? 'header-invalid',
+      expected: expectedFacts,
+      actual: actualFacts,
+    };
+    super({
+      code: 'mesh-bin-contract-violation',
+      expected: args.expected,
+      hint: 're-cook the source with its Meta sidecar through the build-time importer',
+      detail,
+    });
+    this.sourceKey = args.sourceKey;
+    this.actual = args.actual;
+  }
+}
+
+// ── MaterialResolvedEmptyPassesError ──────────────────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'material-resolved-empty-passes'`.
+ *
+ * Emitted at material parent chain walk time when the resolved passes list
+ * is empty. Two reasons: `'missing-parent'` (a parent handle is not
+ * registered) and `'no-pass-in-chain'` (the entire parent chain has no
+ * pass declarations). AI users switch on `.detail.reason` to surface the
+ * right recovery guidance.
+ *
+ * plan-strategy D-2/D-3: empty-passes is a runtime-layer error
+ * (RuntimeErrorCode, not AssetErrorCode).
+ */
+export interface MaterialResolvedEmptyPassesDetail {
+  /** GUID of the material whose resolve produced empty passes. */
+  readonly materialGuid: string;
+  /** Root cause of the empty passes: missing parent vs entire chain has no passes. */
+  readonly reason: 'missing-parent' | 'no-pass-in-chain';
+  /** The raw numeric handle id of the unregistered parent. Only populated when reason='missing-parent'. */
+  readonly missingParentHandle?: number;
+}
+
+/**
+ * Structured error for material parent chain resolve yielding zero passes.
+ *
+ * Emitted by `AssetRegistry.passesOf` when the parent chain walk produces
+ * an empty passes list (AC-09, D-3 two-reason). Four-field surface:
+ *   - `.code = 'material-resolved-empty-passes'` (closed RuntimeErrorCode)
+ *   - `.expected` — expected-state description
+ *   - `.hint` — actionable recovery guidance (differs per reason)
+ *   - `.detail = { materialGuid, reason, missingParentHandle? }`
+ */
+export class MaterialResolvedEmptyPassesError extends Error {
+  readonly code = 'material-resolved-empty-passes' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: MaterialResolvedEmptyPassesDetail;
+
+  constructor(
+    materialGuid: string,
+    reason: 'missing-parent' | 'no-pass-in-chain',
+    missingParentHandle?: number,
+  ) {
+    const expected =
+      reason === 'missing-parent'
+        ? `parent handle ${missingParentHandle} present in AssetRegistry`
+        : 'at least one material in the parent chain declares passes';
+    const hint =
+      reason === 'missing-parent'
+        ? `material ${materialGuid} references parent handle ${missingParentHandle} which is not registered; inspect AssetRegistry, register the parent first, or rebuild the material chain`
+        : `material ${materialGuid} has no passes and its entire parent chain also has no pass declarations; inspect the chain, add pass declarations to one member, then rebuild`;
+    const message =
+      reason === 'missing-parent'
+        ? `material ${materialGuid} parent handle ${missingParentHandle} not registered`
+        : `material ${materialGuid} parent chain resolves to zero passes`;
+
+    super(message);
+    this.name = 'MaterialResolvedEmptyPassesError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = {
+      materialGuid,
+      reason,
+      ...(reason === 'missing-parent' && missingParentHandle !== undefined
+        ? { missingParentHandle }
+        : {}),
+    };
+  }
+}
+
+// ── MeshSsboCapacityExceededError ────────────────────────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'mesh-ssbo-capacity-exceeded'`.
+ *
+ * Fired by `growMeshSsbo` (createRenderer.ts grow factory) when, after
+ * attempting pow2 doubling, the resulting `slotCount` still cannot
+ * accommodate the requested `requested` slot count under the device's
+ * `maxStorageBufferBindingSize` ceiling. This is a defensive fallback —
+ * the primary path for "request past device limit" is
+ * `mesh-ssbo-ceiling-reached`. The two codes share the same detail shape so
+ * AI users handle both arms identically; the discriminant identifies which
+ * branch fired so diagnostics can distinguish the primary vs defensive
+ * surface (research §F6.c).
+ *
+ *   - `requested` — slot count requested by the caller (entity count for the frame)
+ *   - `capacity`  — current `slotCount` in the grow controller's state
+ *   - `ceiling`   — `device.limits.maxStorageBufferBindingSize` in BYTES (not slots)
+ */
+export interface MeshSsboCapacityExceededDetail {
+  readonly requested: number;
+  readonly capacity: number;
+  readonly ceiling: number;
+}
+
+/**
+ * Structured error for the post-grow defensive fallback when mesh-SSBO
+ * capacity cannot accommodate the requested slot count.
+ *
+ * Emitted by `growMeshSsbo` in `createRenderer.ts` (D-5: fire, never
+ * throw). Four-field surface aligned with `SkinPaletteOverflowError`:
+ *   - `.code = 'mesh-ssbo-capacity-exceeded'`
+ *   - `.expected` — capacity >= requested
+ *   - `.hint` — reduce per-frame entity count or split work across frames
+ *   - `.detail = { requested, capacity, ceiling }`
+ */
+export class MeshSsboCapacityExceededError extends Error {
+  readonly code = 'mesh-ssbo-capacity-exceeded' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: MeshSsboCapacityExceededDetail;
+
+  constructor(requested: number, capacity: number, ceiling: number) {
+    const expected = `mesh SSBO slotCount >= ${requested} (currently ${capacity}; device ceiling ${ceiling} B)`;
+    const hint =
+      `mesh SSBO grow could not satisfy needed=${requested} slots (capacity=${capacity}, ceiling=${ceiling} B); ` +
+      'reduce per-frame entity count or split work across frames (defensive fallback path)';
+    super(
+      `mesh SSBO capacity exceeded: needed ${requested} slots, capacity ${capacity}, ceiling ${ceiling} B`,
+    );
+    this.name = 'MeshSsboCapacityExceededError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { requested, capacity, ceiling };
+  }
+}
+
+// ── MeshSsboCeilingReachedError ──────────────────────────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'mesh-ssbo-ceiling-reached'`.
+ *
+ * Fired by `growMeshSsbo` when the requested slot count would exceed the
+ * device's `maxStorageBufferBindingSize` (the only ceiling per D-1; engine
+ * carries no private capacity constant). Same detail shape as
+ * `MeshSsboCapacityExceededDetail`.
+ *
+ *   - `requested` — slot count requested by the caller
+ *   - `capacity`  — current `slotCount` in the grow controller's state
+ *   - `ceiling`   — `device.limits.maxStorageBufferBindingSize` in BYTES
+ */
+export interface MeshSsboCeilingReachedDetail {
+  readonly requested: number;
+  readonly capacity: number;
+  readonly ceiling: number;
+}
+
+/**
+ * Structured error for mesh-SSBO grow refused because the request exceeds
+ * `device.limits.maxStorageBufferBindingSize`.
+ *
+ * Emitted by `growMeshSsbo` (D-5: fire, never throw). The frame renders a
+ * degraded subset (truncated to pre-grow capacity) per plan-strategy D-2 —
+ * no black frame. Four-field surface aligned with `SkinPaletteOverflowError`:
+ *   - `.code = 'mesh-ssbo-ceiling-reached'`
+ *   - `.expected` — requested * stride <= device.limits.maxStorageBufferBindingSize
+ *   - `.hint` — reduce per-frame entity count or pick a higher-tier adapter
+ *   - `.detail = { requested, capacity, ceiling }`
+ */
+export class MeshSsboCeilingReachedError extends Error {
+  readonly code = 'mesh-ssbo-ceiling-reached' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: MeshSsboCeilingReachedDetail;
+
+  constructor(requested: number, capacity: number, ceiling: number) {
+    const expected = `mesh SSBO slot byte size <= device.limits.maxStorageBufferBindingSize (${ceiling} B)`;
+    const hint =
+      `requested ${requested} mesh SSBO slots would exceed device.limits.maxStorageBufferBindingSize (${ceiling} B); ` +
+      'reduce per-frame entity count or run on an adapter with a larger storage buffer binding size';
+    super(
+      `mesh SSBO ceiling reached: needed ${requested} slots; capacity ${capacity}; ceiling ${ceiling} B`,
+    );
+    this.name = 'MeshSsboCeilingReachedError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { requested, capacity, ceiling };
+  }
+}
+
+// ── SceneCollectEntityRefOutOfClosureError ──────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'scene-collect-entity-ref-out-of-closure'`.
+ *
+ * Emitted during rootsToSceneAsset when an entity field references a target
+ * outside the collected forest closure.
+ */
+export interface SceneCollectEntityRefOutOfClosureDetail {
+  readonly entity: number;
+  readonly field: string;
+  readonly target: number;
+}
+
+/**
+ * Structured error for entity ref pointing outside the forest closure.
+ *
+ * Emitted during rootsToSceneAsset collect; fail-fast per charter P3.
+ *   - `.code = 'scene-collect-entity-ref-out-of-closure'`
+ *   - `.expected` — all entity refs resolve within the closure
+ *   - `.hint` — Expand roots to include the target entity, or remove the reference.
+ *   - `.detail = { entity, field, target }`
+ */
+export class SceneCollectEntityRefOutOfClosureError extends Error {
+  readonly code = 'scene-collect-entity-ref-out-of-closure' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: SceneCollectEntityRefOutOfClosureDetail;
+
+  constructor(entity: number, field: string, target: number) {
+    const expected = `entity ${entity}.${field} references entity ${target} which is inside the forest closure`;
+    const hint = 'Expand roots to include the target entity, or remove the reference.';
+    super(`${expected} — ${hint}`);
+    this.name = 'SceneCollectEntityRefOutOfClosureError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = { entity, field, target };
+  }
+}
+
+// ── SceneCollectAssetGuidUnresolvedError ────────────────────────────
+
+/**
+ * Detail for `RuntimeErrorCode 'scene-collect-asset-guid-unresolved'`.
+ *
+ * Emitted at two points with different context on hand:
+ *   - collect (handle→GUID): the shared handle is known → `.handle` is set.
+ *   - serialize (GUID→refs): the GUID string is known but absent from the
+ *     refs index → `.guid` is set. (`.handle` is meaningless there.)
+ * Exactly one of `handle` / `guid` is present per instance.
+ */
+export interface SceneCollectAssetGuidUnresolvedDetail {
+  readonly field: string;
+  readonly handle?: number;
+  readonly guid?: string;
+}
+
+/**
+ * Structured error for a shared asset reference whose GUID cannot be resolved.
+ *
+ * Emitted during rootsToSceneAsset collect (handle) or
+ * serializeSceneAssetToPack (guid); fail-fast per charter P3.
+ *   - `.code = 'scene-collect-asset-guid-unresolved'`
+ *   - `.expected` — every shared asset reference has a catalogued GUID
+ *   - `.hint` — Register the asset in AssetRegistry before collecting.
+ *   - `.detail = { field, handle }` (collect) or `{ field, guid }` (serialize)
+ */
+export class SceneCollectAssetGuidUnresolvedError extends Error {
+  readonly code = 'scene-collect-asset-guid-unresolved' as const;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: SceneCollectAssetGuidUnresolvedDetail;
+
+  constructor(field: string, ref: number | string) {
+    const where = typeof ref === 'number' ? `handle ${ref}` : `guid '${ref}'`;
+    const expected = `shared field '${field}' (${where}) resolves to an asset whose GUID is catalogued`;
+    const hint =
+      'source SceneAsset is not catalogued: call registry.catalog(guid, payload) first, ' +
+      'or load through loadByGuid() which auto-catalogs GUID-scoped assets';
+    super(`${expected} — ${hint}`);
+    this.name = 'SceneCollectAssetGuidUnresolvedError';
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = typeof ref === 'number' ? { field, handle: ref } : { field, guid: ref };
+  }
+}
+
+// -- AssetRuntimeErrorCode / AssetRuntimeError closed unions --------------------
+
+/**
+ * Closed union of asset-cluster error codes. AI users perform exhaustive
+ * `switch (err.code)` without default; TS guards completeness.
+ */
+export type AssetRuntimeErrorCode = AssetRuntimeError['code'];
+
+/**
+ * Closed union of the asset-cluster structured error classes, each carrying
+ * an `AssetRuntimeErrorCode` discriminant on `.code`.
+ */
+export type AssetRuntimeError =
+  | MaterialResolvedEmptyPassesError
+  | MeshSsboCapacityExceededError
+  | MeshSsboCeilingReachedError
+  | SceneCollectEntityRefOutOfClosureError
+  | SceneCollectAssetGuidUnresolvedError;

package/src/handles.ts

@@ -0,0 +1,186 @@
+// @forgeax/engine-assets-runtime -- builtin mesh handles + scene-parse handle field
+// name sets (feat-20260705-runtime-tier2-decomposition M1 / w4, D-4 F1
+// straight-cut). Pure move from asset-registry.ts; zero identifier changes.
+
+import type { Handle } from '@forgeax/engine-types';
+import { handleSlot, toShared } from '@forgeax/engine-types';
+
+// ─── Builtin handles (D-S9 / backward compat with hello-triangle + hello-cube) ─
+
+/**
+ * Builtin unit-cube mesh handle (8 vertices + 36 indices, pos+normal
+ * interleaved). Pair with `MeshFilter` to spawn a cube entity.
+ *
+ * @remarks Typed as `Handle<'MeshAsset', 'shared'>` — feat-20260517
+ * unifies the engine-types and engine-ecs Handle brand SSOT into a single
+ * `Handle<T extends string, M extends 'unique'|'shared'>` declaration
+ * (research Finding 4 import-path-decoupled identity), and constructs the
+ * value via the brand-creation factory `toShared<'MeshAsset'>(N)` so
+ * the caller-side `as unknown as` cast is eliminated (AC-05). The
+ * `'shared'` mode signals the AssetRegistry owns the lifecycle — the
+ * ECS does not release the slot on despawn / removeComponent / set.
+ * Runtime value is a small u32 (1).
+ */
+export const HANDLE_CUBE: Handle<'MeshAsset', 'shared'> = toShared<'MeshAsset'>(1);
+
+/**
+ * Builtin triangle mesh handle (3 vertices). Pair with `MeshFilter`.
+ *
+ * @remarks Typed as `Handle<'MeshAsset', 'shared'>` (same narrow brand
+ * as HANDLE_CUBE; constructed via the `toShared<'MeshAsset'>(N)`
+ * factory per AC-05).
+ */
+export const HANDLE_TRIANGLE: Handle<'MeshAsset', 'shared'> = toShared<'MeshAsset'>(2);
+
+/**
+ * Builtin unit-quad mesh handle — 4 vertices, 6 indices, 2 triangles on
+ * the XY plane facing +Z. Pair with `MeshFilter` to spawn a sprite quad
+ * (feat-20260520-2d-sprite-layer-mvp / M-1 / w06).
+ *
+ * @derives Same-shape sibling of {@link HANDLE_CUBE} / {@link HANDLE_TRIANGLE}
+ *   per requirements §2.1.C: built via the `toShared<'MeshAsset'>(N)`
+ *   brand-creation factory; reserved-id 3 fills the namespace hole between
+ *   HANDLE_TRIANGLE=2 and FIRST_USER_HANDLE=1024 (no `BUILTIN_HANDLE_`
+ *   prefix per Q2 naming decision — discoverable next to existing
+ *   builtins in IDE autocomplete; charter F1 single-entry indexability).
+ *
+ * @reuses {@link createPlaneGeometry}(1, 1) — the procedural plane factory
+ *   already produces 8-floats-per-vertex interleaved (position + normal +
+ *   uv) and is then expanded to the runtime 12-floats layout (adds
+ *   tangent vec4) by {@link meshFromInterleaved}. This funnels HANDLE_QUAD
+ *   onto the exact same vertex pipeline branch as BUILTIN_CUBE /
+ *   BUILTIN_TRIANGLE and the procedural geometry factories — zero new
+ *   layout discriminator (plan-strategy §3 RT4 + D-9 + charter P4
+ *   consistent abstraction).
+ *
+ * @reuses `PROCEDURAL_FLOATS_PER_VERTEX` = 12 from
+ *   `@forgeax/engine-geometry` (the single layout SSOT; the procedural
+ *   `createPlaneGeometry` factory already returns 12F via
+ *   `meshFromInterleaved`).
+ */
+export const HANDLE_QUAD: Handle<'MeshAsset', 'shared'> = toShared<'MeshAsset'>(3);
+
+/**
+ * Id=4 reserved builtin; occupies the next available slot under
+ * FIRST_USER_HANDLE=1024. BUILTIN_SPHERE is synthesised from
+ * `createSphereGeometry(1, 16, 12)` through the same
+ * `meshFromInterleaved` path as BUILTIN_QUAD, so the runtime
+ * 12-float stride is byte-identical to procedural output — zero
+ * new layout discriminator (charter P4 consistent abstraction).
+ */
+export const HANDLE_SPHERE: Handle<'MeshAsset', 'shared'> = toShared<'MeshAsset'>(4);
+
+/**
+ * Builtin cylinder mesh handle — procedural open cylinder (unit-height,
+ * radius=0.5, 16 radial segments, no caps). Pair with `MeshFilter`.
+ *
+ * @derives Same-shape sibling of {@link HANDLE_SPHERE}: synthesised from
+ *   `createCylinderGeometry(0.5, 0.5, 1, 16, 1)` through the same
+ *   `meshFromInterleaved` path as BUILTIN_SPHERE, so the runtime
+ *   12-float stride is byte-identical to all other built-in meshes —
+ *   zero new layout discriminator (charter P4 consistent abstraction).
+ *
+ * @remarks Id=6 follows {@link HANDLE_NINESLICE_QUAD}=5 in the builtin slot
+ *   sequence (FIRST_USER_HANDLE=1024 untouched).
+ *   feat-20260701-editor-world-container-doc-ecs-collapse M0 / AC-16:
+ *   GUID = deriveBuiltin('HANDLE_CYLINDER') UUIDv5
+ *   (plan-strategy §2 D-6 + §5.6 builtin-guid-ssot gate)
+ */
+export const HANDLE_CYLINDER: Handle<'MeshAsset', 'shared'> = toShared<'MeshAsset'>(6);
+
+/**
+ * Builtin 9-slice quad mesh handle — 4×4 grid (16 vertices, 9 sub-quads,
+ * 54 indices) on the XY plane facing +Z. Pair with `MeshFilter` and a
+ * `MaterialAsset` whose first pass shader is `'forgeax::sprite'` and whose
+ * `values.slices` is non-zero to render a 9-sliced UI panel
+ * (feat-20260527-sprite-nineslice / M2 / w9).
+ *
+ * @derives Same-shape sibling of {@link HANDLE_QUAD}: synthesised from
+ *   `createPlaneGeometry(1, 1, 3, 3)` which subdivides the unit quad into
+ *   3×3 sub-quads (9 cells). The 16 grid points and 54 indices feed
+ *   {@link meshFromInterleaved} so the runtime 12-float vertex stride is
+ *   byte-identical to all other built-in / procedural meshes — zero new
+ *   layout discriminator (charter P4 consistent abstraction).
+ *
+ * @remarks Id=5 follows {@link HANDLE_SPHERE}=4 in the builtin slot
+ *   sequence (FIRST_USER_HANDLE=1024 untouched). The vertex shader uses
+ *   `vertex_index % 4` / `vertex_index / 4` to recover (i, j) grid
+ *   coordinates and four anchor vec4s to map each grid cell to the right
+ *   region of the source texture; only required when the sprite material
+ *   declares non-zero `slices`. For the legacy zero-slice sprite path use
+ *   {@link HANDLE_QUAD}.
+ *
+ * @reuses `PROCEDURAL_FLOATS_PER_VERTEX` = 12 from
+ *   `@forgeax/engine-geometry` (sprite-pipeline binding table / vertex layout
+ *   untouched). plan-strategy §D-2 NOTE clarifies
+ *   the id=5 vs original-plan id=4 drift: HANDLE_SPHERE took id=4 in
+ *   feat-20260529-fxaa-sphere-builtin before this feat landed.
+ */
+export const HANDLE_NINESLICE_QUAD: Handle<'MeshAsset', 'shared'> = toShared<'MeshAsset'>(5);
+
+/**
+ * Stable GUIDs for the builtin meshes — the dash-form of
+ * `deriveBuiltin('HANDLE_<NAME>')` (UUIDv5, ForgeaX namespace) in
+ * `@forgeax/engine-pack`. They are inlined here (not imported) because the
+ * pack derivation runs under top-level `await` (async SubtleCrypto) and
+ * dragging that into the AssetRegistry constructor — a synchronous hot path
+ * consumed engine-wide — would make the whole runtime module graph async.
+ *
+ * The single source of truth remains `deriveBuiltin`: a cross-package
+ * guard test (`builtin-guid-ssot.test.ts`) asserts each literal equals the
+ * derived value, so any drift in the derivation reds the suite. This pairs
+ * the previously-disconnected dual truths (the u32 `HANDLE_*` constants and
+ * the pack GUID strings) into one bidirectionally-resolvable table, so
+ * `guidOf(HANDLE_CUBE)` no longer returns `undefined`
+ * (docs/feedbacks/2026-06-03 §6.2 Tier 0).
+ */
+export const BUILTIN_MESH_GUIDS: ReadonlyArray<readonly [Handle<'MeshAsset', 'shared'>, string]> = [
+  [HANDLE_CUBE, 'cbe42beb-8975-5096-b3a1-3dda4cb4c077'],
+  [HANDLE_TRIANGLE, '22592f07-d967-5116-b29c-fa9781929ba8'],
+  [HANDLE_QUAD, '339338aa-a338-581c-9fc5-744267ef8a51'],
+  [HANDLE_SPHERE, '95730fd2-9846-5f84-8658-0b3c971eb263'],
+  [HANDLE_NINESLICE_QUAD, '692d38b4-8cac-5fb2-9dcf-f389e076d6bf'],
+  // feat-20260701-editor-world-container-doc-ecs-collapse M0 / AC-16:
+  // cylinder builtin handle=6, GUID = deriveBuiltin('HANDLE_CYLINDER') UUIDv5
+  // (plan-strategy §5.6 builtin-guid-ssot gate)
+  [HANDLE_CYLINDER, 'ab20af21-0764-55be-a7f2-b80ab3d46a0a'],
+];
+
+/** Resolve the stable producer GUID for one process-static builtin mesh handle. */
+export function builtinMeshGuid(handle: Handle<string, 'shared'>): string | undefined {
+  const slot = handleSlot(handle);
+  return BUILTIN_MESH_GUIDS.find(([candidate]) => handleSlot(candidate) === slot)?.[1];
+}
+
+/**
+ * Field names known to carry handle<> schema-vocab references (plan-strategy
+ * D-4).  parseScenePayload uses this allowlist to replace integer values
+ * with GUID strings from refs[] only for handle fields — a Transform.pos lane of 0,
+ * ChildOf.parent=0 and similar non-handle integers are left untouched.
+ *
+ * When a new handle<> field is added to a runtime component, its field name
+ * MUST be added here so parseScenePayload correctly resolves it.
+ */
+export const HANDLE_FIELD_NAMES: ReadonlySet<string> = new Set([
+  'assetHandle',
+  'material',
+  'skeleton',
+  'clip',
+  // ParticleEffectPlayer.effect (shared<ParticleEffectAsset>) uses the same
+  // scene-pack refs[] index contract as every other scalar shared field.
+  'effect',
+  // feat-20260630-equirect-kind-internalized-ibl-declarative-skyligh M3 / w27:
+  // Skylight.equirect + SkyboxBackground.equirect (shared<EquirectAsset>). The
+  // generic extractSceneEntityHandleGuids path already covers shared< fields by
+  // schema; this allowlist is the second scene-parse path (parseScenePayload),
+  // so the new handle field name is registered here too (R-1).
+  'equirect',
+]);
+
+/**
+ * Field names known to carry `array<handle<X>>` schema-vocab references
+ * (feat-20260608 M2 / w7: MeshRenderer.materials). Each element is a refs
+ * index that resolves to a GUID string. Coexists with HANDLE_FIELD_NAMES;
+ * a field name lives in exactly one set.
+ */
+export const HANDLE_ARRAY_FIELD_NAMES: ReadonlySet<string> = new Set(['materials']);

package/src/image-error.ts

@@ -0,0 +1,45 @@
+// @forgeax/engine-assets-runtime -- runtime-local ImageError constructor
+// (feat-20260705-runtime-tier2-decomposition M1 / w4, D-4 F1 straight-cut).
+// Pure move from asset-registry.ts; zero identifier changes.
+
+import type { ImageErrorDetailFor, ImageErrorFor } from '@forgeax/engine-types';
+import { IMAGE_ERROR_HINTS } from '@forgeax/engine-types';
+
+// Local minimal `ImageError` constructor (charter P5 producer / consumer
+// split: the runtime AssetRegistry should not import @forgeax/engine-image
+// errors module because the image package is the disk-side decoder; the
+// runtime is the GPU consumer. Both packages share the `ImageError`
+// interface SSOT in @forgeax/engine-types so runtime constructs the
+// 4-field surface (.code / .expected / .hint / .detail) directly without
+// duplicating the @forgeax/engine-image errors.ts class).
+type UnsupportedMimeImageError = ImageErrorFor<'image-format-unsupported'>;
+type UnsupportedMimeImageErrorDetail = ImageErrorDetailFor<'image-format-unsupported'>;
+
+const IMAGE_ERROR_EXPECTED_LOCAL: Readonly<
+  Record<UnsupportedMimeImageErrorDetail['code'], string>
+> = {
+  'image-format-unsupported':
+    "mime is one of ['image/png', 'image/jpeg', 'image/x-tga']; texture format <-> colorSpace family agrees",
+};
+
+class RuntimeImageError extends Error implements UnsupportedMimeImageError {
+  readonly code: UnsupportedMimeImageError['code'];
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: UnsupportedMimeImageErrorDetail;
+  constructor(detail: UnsupportedMimeImageErrorDetail) {
+    const code = detail.code;
+    const expected = IMAGE_ERROR_EXPECTED_LOCAL[code];
+    const hint = IMAGE_ERROR_HINTS[code];
+    super(`[ImageError ${code}] expected: ${expected}; hint: ${hint}`);
+    this.name = 'ImageError';
+    this.code = code;
+    this.expected = expected;
+    this.hint = hint;
+    this.detail = detail;
+  }
+}
+
+export function makeImageError(detail: UnsupportedMimeImageErrorDetail): UnsupportedMimeImageError {
+  return new RuntimeImageError(detail);
+}