@forgeax/engine-assets-runtime 0.0.0-dev.8d955ade1c79

package/dist/asset-registry.d.ts

@@ -0,0 +1,554 @@
+import type { Component, EcsError, EntityHandle, World } from '@forgeax/engine-ecs';
+import type { PackError } from '@forgeax/engine-pack/errors';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { type Result, type RhiError } from '@forgeax/engine-rhi';
+import type { ShaderRegistry } from '@forgeax/engine-shader';
+import { type Asset, type AssetEnvelope, AssetError, type AssetEvidence, type AssetEvidenceError, type AssetRef, type CatalogEntry, type EngineMetrics, type Handle, type ImageError, type ImportTransport, type InspectSnapshot, type Loader, type Package, type ParseErrorDetail, type RuntimeAssetBinding, type SceneAsset, type TagOf, type TranscodeCaps, type MeshAsset as TypesMeshAsset } from '@forgeax/engine-types';
+import type { LoaderRegistry } from './loader-registry';
+import type { CatalogListener, CatalogSource } from './catalog-source';
+import type { MaterialLoadError, MaterialReady } from './material/loader';
+import { ArtifactReadCache } from './registry/artifact-io';
+import { type RuntimeEvidenceSource } from './registry/asset-evidence';
+import { type CatalogRecord } from './registry/catalog';
+import { type CatalogReplicaSnapshot } from './registry/catalog-state';
+import { type PostSpawnHook } from './registry/instantiate';
+import { LoadStateStore } from './registry/load-state';
+import type { ScenePublicationFence, ScenePublicationFenceError } from './registry/scene-publication-fence';
+export { HANDLE_CUBE, HANDLE_CYLINDER, HANDLE_NINESLICE_QUAD, HANDLE_QUAD, HANDLE_SPHERE, HANDLE_TRIANGLE, } from './handles';
+export { animationClipLoader, animationGraphLoader, INLINE_PACK_LOADERS, materialLoader, meshLoader, sceneLoader, skeletonLoader, skinLoader, } from './loaders/inline-pack';
+export { equirectLoader, fontLoader, PACK_ARTIFACT_LOADERS, textureLoader, } from './loaders/pack-artifact';
+export { type TilesetValidateOptions, validateTilesetPayload } from './payload-validate';
+export type { Asset, TypesMeshAsset as MeshAsset };
+/**
+ * Asset registry (instance-per-engine; `engine.assets: AssetRegistry | null`).
+ *
+ * The builtin meshes (`HANDLE_CUBE` / `HANDLE_TRIANGLE` / ...) are served by
+ * the process-static `BuiltinAssetRegistry`, so AI users see usable handles in
+ * the very first frame without registration ceremony (charter proposition 1).
+ *
+ * @example Catalogue a texture by GUID, load its payload, and bind a material:
+ * ```ts
+ * const guid = engine.assets.parseGuid('00000000-0000-7000-8000-000000000001');
+ * engine.assets.catalog(guid, myTexture);                       // GUID -> payload
+ * const res = await engine.assets.loadByGuid(guid);             // payload (D-17)
+ * if (!res.ok) {
+ *   switch (res.error.code) {
+ *     case 'asset-not-found':  // guid not catalogued
+ *   }
+ *   return;
+ * }
+ * const material = world.allocSharedRef('MaterialAsset', {       // mint column handle
+ *   kind: 'material',
+ *   passes: [{ name: 'Forward', program: { module: 'forgeax::default-standard-pbr' }, tags: { LightMode: 'Forward' }, queue: 2000 }],
+ *   values: { baseColorTexture: res.value },
+ * });
+ * world.spawn({ component: MeshRenderer, data: { materials: [material] } });
+ * ```
+ */
+export interface ParsedPackFile {
+    schemaVersion?: string;
+    kind?: string;
+    assets: Array<{
+        guid: string;
+        kind: string;
+        payload: Record<string, unknown>;
+        refs?: string[];
+        artifacts?: Record<string, import('@forgeax/engine-types').ArtifactDescriptor>;
+    }>;
+}
+export type CatalogReconcileError = AssetError;
+export type CatalogReconcileResult = Result<CatalogReplicaSnapshot, CatalogReconcileError>;
+export declare class AssetRegistry {
+    readonly shaderRegistry: ShaderRegistry;
+    private catalogSource;
+    private catalogEnumerating;
+    private readonly catalogListeners;
+    private catalogSourceDispose;
+    private catalogReplica;
+    readonly assetCatalog: Map<string, AssetEnvelope<Asset>>;
+    /** Owner-injected component catalog used for scene breadcrumb projection. */
+    readonly componentCatalog: ReadonlyMap<string, Component>;
+    private readonly packages;
+    private readonly packageByPath;
+    private readonly pendingNames;
+    packIndexUrl: string | undefined;
+    packIndexCache: Map<string, CatalogRecord> | undefined;
+    /** Current browser-facing asset realm; absent for inline/shipped legacy use. */
+    runtimeBinding: RuntimeAssetBinding | undefined;
+    readonly inFlight: Map<string, Promise<Result<unknown, AssetError | ImageError | RhiError>>>;
+    readonly packFileCache: Map<string, ParsedPackFile>;
+    readonly packFileInFlight: Map<string, Promise<ParsedPackFile>>;
+    readonly artifactCache: ArtifactReadCache;
+    readonly loadState: LoadStateStore;
+    /**
+     * Render-facing material readiness owned by the production GUID loader.
+     * The map stores the complete tuple result, including structured failures,
+     * so record code cannot silently fall back to a generic MaterialAsset.
+     */
+    readonly materialReadiness: Map<string, MaterialReady | MaterialLoadError>;
+    private assetEvidenceAdapter;
+    readonly generations: Map<string, number>;
+    globalGeneration: number;
+    /**
+     * Monotonic payload-cache epoch. Render-side derived snapshots use this
+     * single stamp to skip re-walking an unchanged material parent chain on
+     * every frame; catalog/invalidation mutations advance it conservatively.
+     */
+    catalogEpoch: number;
+    packIndexCachePatchQueue: Promise<void>;
+    metrics: EngineMetrics | null;
+    transcodeCaps: TranscodeCaps;
+    /** @internal */
+    _originIndex: WeakMap<object, string>;
+    /**
+     * Construct a fresh registry pre-populated with the builtin cube + triangle
+     * mesh handles (`HANDLE_CUBE` / `HANDLE_TRIANGLE`).
+     *
+     * feat-20260514 M3 / w15: the previous optional `RhiDevice` constructor
+     * argument (consumed by the now-deleted `createInstancedBuffer` triplet)
+     * is removed; the registry surface is engine-agnostic again. Per-entity
+     * instance transforms now live inside the ECS `Instances { transforms:
+     * 'array<f32>' }` component; the RenderSystem record stage owns GPU
+     * storage buffer allocation + cap-gate.
+     */
+    readonly loaders: LoaderRegistry;
+    readonly importTransport: ImportTransport | undefined;
+    readonly postSpawnHook: PostSpawnHook | undefined;
+    /** @internal Stored for M2 validation; TS suppressor reference */
+    constructor(shaderRegistry: ShaderRegistry, importTransport?: ImportTransport | undefined, extraLoaders?: readonly Loader[] | undefined, postSpawnHook?: PostSpawnHook | undefined, runtimeBinding?: RuntimeAssetBinding | undefined, componentCatalog?: ReadonlyMap<string, Component>);
+    /**
+     * Restore the engine-owned GUID catalogue after a runtime-realm transition.
+     *
+     * Builtin meshes are process-static engine assets, not game-owned catalog
+     * rows. A realm transition clears the user catalog and load caches, but must
+     * leave these assets addressable so a scene in the newly bound game can keep
+     * resolving its builtin mesh references.
+     */
+    private registerBuiltins;
+    /**
+     * feat-20260527-sprite-nineslice M4 / w16 prep + w18 (D-5 + D-9): inject the
+     * per-Renderer `EngineMetrics` so register-time soft-warns can bump the same
+     * counter map the runtime reads through `renderer.metrics.snapshot()`. Called
+     * by `createRenderer` after constructing both the registry and the metrics
+     * instance; safe to skip in standalone tests (the soft-warn arms simply do
+     * not record).
+     */
+    setMetrics(metrics: EngineMetrics): void;
+    /**
+     * feat-20260707 M5 / w33 (D-11): wire the device compression caps used by the
+     * Basis texture / equirect transcode arms. `createRenderer` calls this right
+     * after construction with `RhiCaps` projected to `TranscodeCaps` (D-8). Left
+     * at the all-false default, the loaders transcode to the uncompressed
+     * `rgba8unorm` / `rgba16float` fallback (AC-04, section 8 P3).
+     */
+    setTranscodeCaps(caps: TranscodeCaps): void;
+    /**
+     * Inject authoritative runtime evidence without importing CLI or Node policy.
+     * `inspect(guid)` and `verifyByGuid(guid)` return the shared state model; an
+     * omitted capability remains an explicit structured error, never a pass.
+     */
+    configureAssetEvidence(source: RuntimeEvidenceSource): void;
+    /**
+     * @internal — read the metrics handle for register-time soft-warn paths.
+     * Returns `null` when no `createRenderer` wired the registry to a renderer
+     * (the standalone-test path; the structured fail-fast branches still fire).
+     */
+    _getMetrics(): EngineMetrics | null;
+    /**
+     * @internal — reverse-lookup: find the GUID key for a catalogued asset
+     * payload by identity comparison (===). Returns the GUID string if found,
+     * `undefined` otherwise. This is the SSOT for the inline identity scan
+     * idiom that previously existed in two places (instantiate sceneGuidKey
+     * lookup and resolveSkinAsset skeleton match).
+     *
+     * Linear scan of the assetCatalog (Map<string, AssetEnvelope>). The O(n)
+     * cost is acceptable for save-path frequencies (OOS-2).
+     */
+    _guidForAsset(asset: Asset): string | undefined;
+    /** Public identity projection consumed by scene collection boundaries. */
+    guidOf(asset: Asset): string | undefined;
+    /** Return the production MaterialReady/Error result for one material GUID. */
+    getMaterialReadiness(guid: string): MaterialReady | MaterialLoadError | undefined;
+    /** Record the canonical result produced by the production material loader. */
+    recordMaterialReadiness(guid: string, readiness: MaterialReady | MaterialLoadError): void;
+    /**
+     * Configure a catalog URL for `loadByGuid`.
+     *
+     * Call this once during engine initialization with the URL where
+     * `pack-index.json` is served (emitted by `@forgeax/engine-vite-plugin-pack`
+     * during `vite build`). In a Vite dev host, use `configureRuntimeBinding`
+     * instead so the catalog remains bound to its scope and generation. The
+     * index is also the canonical base URL for every
+     * catalog entry: relative, root-relative, and absolute entry URLs are resolved
+     * against it before the registry fetches a pack body. After configuration,
+     * `loadByGuid` will fetch the catalog on its first invocation and cache it for
+     * subsequent calls.
+     *
+     * @example
+     * ```ts
+     * engine.assets.configurePackIndex('/pack-index.json');
+     * const payloadRes = await engine.assets.loadByGuid(guid); // payload, not a handle (D-17)
+     * ```
+     */
+    configurePackIndex(url: string): void;
+    /**
+     * Atomically replace the browser-side asset realm. The binding owns the
+     * catalog URL and generation; no cache from the previous game survives the
+     * transition.
+     */
+    configureRuntimeBinding(binding: RuntimeAssetBinding): void;
+    /**
+     * feat-20260621 F17c: invalidate a single cached asset by GUID so the next
+     * `loadByGuid` performs a genuinely fresh fetch. Clears, for this GUID only:
+     * the catalogue entry, the in-flight dedup entry, the cached pack-file body
+     * (keyed by the index entry's packageUrl), and the pack-index entry. Then
+     * increments the per-GUID generation counter so any still in-flight Promise
+     * for this GUID discards its result (returns `asset-invalidated`). The body +
+     * index clears are targeted (other GUIDs' cached bodies and index entries
+     * survive); deleting the index entry forces `resolveCatalogEntry` to re-fetch
+     * the pack-index on the next load, re-resolving the packageUrl whose body
+     * cache was just dropped. No-op when the GUID is not catalogued.
+     *
+     * Does NOT touch `packages` (a re-load's registerPackage overwrites them; D-8)
+     * and does NOT trigger GPU resource release (OOS-1,
+     * q1 boundary: the asset is CPU-only; GPU resources follow the ECS).
+     *
+     * @param guid - Case-insensitive GUID string or AssetGuid.
+     */
+    invalidate(guid: string): void;
+    /**
+     * Adopt freshly loaded Mesh material slots into an object that is already
+     * pinned by live World shared refs. Geometry and GPU-backed fields deliberately
+     * remain untouched: this primitive is only for a default-material source
+     * override, never a general Mesh reimport. This is the atomic cutover: Catalog,
+     * Ready load state, and payload-to-GUID provenance must all name the same
+     * object after the call. Call only after invalidate(guid) + loadByGuid(guid)
+     * has completed successfully.
+     */
+    adoptReloadedMeshMaterialSlots(guid: string, livePayload: Asset): Result<Asset, AssetError>;
+    /**
+     * feat-20260621 F17c: invalidate ALL cached assets so the next `loadByGuid`
+     * re-fetches both the pack-index and the asset body. Clears assetCatalog,
+     * inFlight, and packFileCache (wholesale), and resets packIndexCache to
+     * `undefined` (NOT `.clear()` -- an empty Map would short-circuit
+     * `resolveCatalogEntry`'s `=== undefined` re-fetch guard and serve
+     * asset-not-imported for every later load; undefined forces a fresh
+     * fetchPackIndex). Then increments a single globalGeneration counter so every
+     * in-flight Promise (regardless of GUID) discards its result. Returns the
+     * number of assets that were catalogued before the call.
+     *
+     * Idempotent: second call on an already-empty catalogue returns clearedCount 0
+     * (AC-06). Does NOT trigger GPU resource release (OOS-1).
+     */
+    invalidateAll(): {
+        clearedCount: number;
+    };
+    /**
+     * Force a re-fetch of the configured pack-index NOW and repopulate the cache,
+     * so a synchronous `listCatalog()` immediately reflects assets added on disk
+     * since boot (a freshly imported GLB's sub-assets). `loadByGuid`'s lazy
+     * re-fetch only fires on a per-GUID miss and `invalidateAll()` merely clears
+     * the cache (leaving `listCatalog()` empty until the next load), so neither
+     * makes a Content Browser or `loadByGuid`-driven "Add to Scene" see a new
+     * asset without a page reload. This does.
+     *
+     * No-op (returns false) when no pack-index URL is configured (dev inline
+     * catalogue path) or the fetch fails — callers keep the stale cache rather
+     * than blanking it. Returns true when the cache was repopulated.
+     */
+    refreshCatalog(): Promise<boolean>;
+    setCatalogSource(source: CatalogSource): void;
+    /** Stop the catalog transport and remove its replica without clearing payload caches. */
+    clearCatalogSource(): void;
+    enumerateCatalog(): Promise<Result<readonly CatalogEntry[], AssetError>>;
+    /** Read the immutable catalog projection folded by this registry. */
+    catalogSnapshot(): CatalogReplicaSnapshot | undefined;
+    /** Explicitly recover the registry's single catalog replica from its configured source. */
+    reconcileCatalog(): Promise<CatalogReconcileResult>;
+    subscribeCatalog(listener: CatalogListener): () => void;
+    /**
+     * Materialise a `SceneAsset` into an existing `World` and return the
+     * synthetic root `Entity` (feat-20260514 w31 sugar wrapper; AC-03 +
+     * requirements §IN-3; M3: returns Entity not SceneInstanceId).
+     *
+     * Before spawning, handle-type component fields (e.g. `assetHandle`,
+     * `material`, `skeleton`) containing GUID strings are resolved to fresh
+     * user-tier `Handle` numbers via `world.allocSharedRef` (feat-20260614 M8
+     * D-19 instantiate-time GUID->handle mint; supersedes the pre-D-17
+     * `resolveGuid` map). GUIDs that fail to parse or are not catalogued return
+     * `AssetError(code='asset-not-found')` with a hint containing the GUID,
+     * node localId, and field name.
+     *
+     * Errors propagate verbatim through the closed
+     * `AssetError | PackError | EcsError` union so AI users that already
+     * narrow `loadByGuid<SceneAsset>` results reuse the same `switch
+     * (err.code)` exhaustively (charter proposition 3 machine-readable
+     * union; plan-strategy §3.3 closed-union transparency).
+     *
+     * @example
+     * ```ts
+     * const sceneRes = await engine.assets.loadByGuid<SceneAsset>(roomGuid); // payload (D-17)
+     * if (!sceneRes.ok) return;
+     * const handle = world.allocSharedRef('SceneAsset', sceneRes.value);     // mint column handle
+     * const r = engine.assets.instantiate(handle, world);
+     * if (!r.ok) {
+     *   switch (r.error.code) {
+     *     case 'asset-not-found':
+     *     case 'pack-cyclic-reference':
+     *     // ... AssetErrorCode | PackErrorCode | EcsErrorCode exhaustive
+     *   }
+     * }
+     * ```
+     */
+    instantiate<T extends SceneAsset>(handle: Handle<TagOf<T>, 'shared'>, world: World, parent?: EntityHandle): Result<EntityHandle, AssetError | PackError | EcsError>;
+    instantiateWithPublicationFence<T extends SceneAsset>(handle: Handle<TagOf<T>, 'shared'>, world: World, parent: EntityHandle | undefined, expectedPublication: ScenePublicationFence): Result<EntityHandle, AssetError | PackError | EcsError | ScenePublicationFenceError>;
+    /**
+     * Materialise a `SceneAsset` FLAT into an existing `World` — the "open a scene
+     * for authoring" registry entry (#655): NO synthetic SceneInstance root, NO
+     * forced `ChildOf` on top-level members. Returns the top-level entity handles.
+     * Nested prefabs (`mounts[]`) still materialise as their own SceneInstance
+     * anchors. Use {@link instantiate} (anchor) at runtime / Play and for nested
+     * prefabs.
+     */
+    instantiateFlat<T extends SceneAsset>(handle: Handle<TagOf<T>, 'shared'>, world: World): Result<EntityHandle[], AssetError | PackError | EcsError>;
+    instantiateFlatWithPublicationFence<T extends SceneAsset>(handle: Handle<TagOf<T>, 'shared'>, world: World, expectedPublication: ScenePublicationFence): Result<EntityHandle[], AssetError | PackError | EcsError | ScenePublicationFenceError>;
+    private sceneMeshGuidBySlot;
+    private migrateLegacySceneMaterialOverrides;
+    private preflightSceneMaterialGraph;
+    /**
+     * @internal
+     * Transform a SceneAsset whose handle-type component fields hold GUID
+     * strings (post-parseScenePayload intermediate state) into a copy whose
+     * handle fields hold resolved Handle numbers.
+     *
+     * Schema-driven field detection (plan-strategy D-4): for each component
+     * field whose Component.schema fieldType starts with `shared\<`, the
+     * value is treated as a GUID string and resolved via `AssetGuid.parse` +
+     * catalogue lookup + `world.internSharedRef` (feat-20260614 M8 D-15/D-17;
+     * the registry mints nothing). Unknown component names are silently passed
+     * through (the ecs layer's additionalProperties check will catch unknowns at
+     * spawn if appropriate).
+     *
+     * Stop-on-first-error (AC-08): the first unresolvable GUID aborts
+     * iteration and returns `AssetError(code='asset-not-found')` with a hint
+     * containing the GUID string, node localId, and field name for AI-user
+     * debuggability (P3).
+     */
+    _resolveSceneGuids(scene: SceneAsset, world: World, sceneGuidKey?: string, _visitedMountGuids?: Set<string>, _guidToHandle?: Map<string, number>, _resolvedSceneHandles?: Map<string, number>, _materialGraphPreflighted?: boolean): Result<SceneAsset, AssetError>;
+    /**
+     * Register an asset and return a fresh
+     * `Result<Handle<TagOf<T>, 'shared'>, AssetError>`. The brand `target`
+     * tag is derived from the Asset's `kind` discriminator via `AssetTagMap`
+     * (charter F1 single-entry indexability). The runtime representation is
+     * an auto-incrementing u32 starting at 1024 (builtins reserve 1-2).
+     *
+     * feat-20260526 M4: `shadingModel` field is retired in favour of
+     * pass-based MaterialAsset. This generic surface covers the full
+     * `Asset` closed union (mesh / texture / sampler / scene / equirect
+     * / material).
+     */
+    /**
+     * feat-20260614 M8 (D-15 / D-17): catalogue a payload under its GUID.
+     * Replaces the old `register` / `registerWithGuid` mint pair -- the registry
+     * stores the PAYLOAD and never produces a handle (it owns no World).
+     * Column minting is the caller's job via `world.allocSharedRef`.
+     *
+     * Validates mesh stride + material passes / sprite slices at catalogue entry
+     * (same fail-fast surface as the old register path). Returns
+     * `Result.err(AssetError)` on validation failure; `Result.ok(payload)` with
+     * the stored payload (mesh payloads gain an `aabb`) on success.
+     */
+    catalog<T = Asset>(guid: AssetGuid | string, asset: T, refs?: readonly AssetRef[]): Result<T, AssetError>;
+    /**
+     * @internal feat-20260618-asset-and-pack-name-fields M3 (D-1): the single
+     * package-mapping write primitive. All three registration entry points funnel
+     * here so the XOR name invariant is implemented once (#1 SSOT):
+     *   - catalog() inline path -> registerPackage(null, [guid])          (no package)
+     *   - loadByGuid disk path  -> registerPackage(packageUrl, [g1,g2,...], names)
+     *   - constructor builtin    -> registerPackage(null, [...guids])      (D-5 null)
+     *
+     * `path === null` registers the GUIDs with no package (resolveName reads their
+     * storedName or returns ''). A non-null `path` finds-or-creates the shared
+     * MutablePackage for that path and adds the GUIDs to it; per-GUID entry names
+     * (D-2: name flows entry -> Package, never the payload) are taken from
+     * `names`. The 1->N promotion branch (D-3) is added by w11. Never throws --
+     * it only writes maps; resolution + validation happen in resolveName / rename.
+     */
+    _registerPackage(path: string | null, guids: readonly string[], names?: Map<string, string>): void;
+    /**
+     * Read the per-GUID stored display name (D-6 home: the envelope's `name`
+     * field, with `pendingNames` covering the prod-disk ordering where the name is
+     * known before the body is catalogued). Single read point for resolveName /
+     * the 1->N promotion XOR check.
+     */
+    private storedNameFor;
+    private hasStoredName;
+    /**
+     * Write the per-GUID stored display name. When the envelope exists, replace it
+     * with one carrying the new `name` (the envelope is immutable; D-6 keeps the
+     * payload free of the name). Before the envelope is catalogued (prod disk
+     * path), stash on `pendingNames` so catalog() can drain it into the new
+     * envelope. `name === undefined` clears the name in both homes.
+     */
+    private setStoredName;
+    /**
+     * Return the `Package` this GUID belongs to, or `null` when the asset has no
+     * package (catalog() inline + builtin, D-5), or `undefined` when the GUID was
+     * never registered. The returned `Package` is a readonly snapshot whose
+     * `assetCount` is derived from the live member set (#2 Derive).
+     */
+    packageOf(guid: AssetGuid | string): Package | null | undefined;
+    /**
+     * Resolve an asset's human-readable display name -- the single source of truth
+     * for the two-segment identity's `name` segment (D-6). Every name consumer
+     * (inspect / catalog builder / CLI) reads this or the same `deriveAssetName`
+     * pure function it delegates to (AC-04); no consumer re-implements the XOR
+     * rule. Returns a deterministic fallback rather than throwing on a missing
+     * name (AC-15): `basename(path)` for a multi-asset entry that lacks a stored
+     * name, or `''` for a no-package asset with no self name (the detectable
+     * "genuinely no name" signal, charter P3). An unregistered GUID is treated as
+     * the no-package branch.
+     */
+    resolveName(guid: AssetGuid | string): string;
+    /**
+     * Rename an asset's display name in memory (D-4). Three classes by package
+     * shape:
+     *   - no-package asset      -> set the stored self name
+     *   - multi-asset package   -> set the entry stored name
+     *   - single-asset package  -> rewrite the package path's leaf segment so the
+     *                              derived basename becomes `newName` (the package
+     *                              stays single-asset; the leaf IS the name)
+     *
+     * In-memory only (OOS-1: no disk write-back). Returns structured failures via
+     * the closed `AssetErrorCode` union with no new members (D-4): a name that
+     * collides with another member of the same package -> `asset-invalid-value`;
+     * an unregistered GUID -> `asset-not-found`. AI users consume `.code` through
+     * a `switch`, not by parsing `.message` (charter P3).
+     */
+    rename(guid: AssetGuid | string, newName: string): Result<void, AssetError>;
+    /**
+     * Return an `asset-invalid-value` AssetError if another member of `pkg`
+     * already resolves to `newName`, else null. Extracted from `rename` to keep
+     * the collision-detection control flow flat (D-4 reuses the closed error code;
+     * the detail narrows via the `{ field, value, reason }` union variant).
+     */
+    private nameCollisionIn;
+    /**
+     * Parse a dash-form GUID string into an `AssetGuid`. Thin convenience over
+     * `AssetGuid.parse` for the `loadByGuid` / `catalog` call sites; throws
+     * `AssetError` on a malformed GUID (caller-error, mirrors `parseInt`-style
+     * eager validation -- the GUID literal is author-supplied, not user data).
+     */
+    parseGuid(guidStr: string): AssetGuid;
+    /**
+     * Look up a catalogued payload by GUID, or `undefined` on miss. Used by the
+     * ECS/render side (e.g. `walkMaterialParents` in `resolve-asset-handle.ts`)
+     * to resolve a payload's embedded sub-asset GUIDs (D-19) without minting.
+     */
+    lookup<T = Asset>(guid: AssetGuid | string): T | undefined;
+    /**
+     * feat-20260613-material-paramschema-driven-binding M4 / w23 (D-5 graceful):
+     * Return the texture-field name set for the given material-shader id,
+     * derived from the registered shader's paramSchema via `derive(paramSchema)
+     * .textureFieldNames`. Returns `undefined` when the shader is not yet
+     * registered (cross-worktree shader-late-register, plan R-4).
+     *
+     * Used by `extractFrame` to know which values fields the shader
+     * declares as texture handles; the extract layer validates handle-vs-
+     * scalar typing and drops misclassified slots so the record stage's
+     * MISSING_TEXTURE_HANDLE fallback can take over (white default texture)
+     * rather than letting a stray handle reach `device.createBindGroup`.
+     *
+     * feat-20260705-runtime-tier2-decomposition M1 / w5 (D-4): delegates to the
+     * extracted `./registry/validate-material` free function (signature stable).
+     */
+    materialShaderTextureFieldNames(shaderId: string): ReadonlySet<string> | undefined;
+    /**
+     * Load an asset and all its transitively referenced sub-assets by GUID.
+     * The result is a durable Asset payload. Consumer owners may narrow the
+     * success type, then call their own World/Host projection; this registry does
+     * not create a generic GUID-to-handle materializer.
+     * Delegates to the load-by-guid collaboration module (w7 / D-4); see
+     * registry/load-by-guid.ts for the full DDC / pack-fetch pipeline.
+     */
+    loadByGuid<T = Asset>(guid: AssetGuid, parentContext?: {
+        sceneEntityId?: number;
+        componentField?: string;
+    }): Promise<Result<T, AssetError | ImageError | RhiError>>;
+    /**
+     * Dispatch a pack payload through the injected LoaderRegistry. Delegates to
+     * the load-by-guid collaboration module (w7 / D-4). Kept as a class method so
+     * existing structural-cast test access keeps resolving.
+     */
+    parseAssetPayload(kind: string, payload: Record<string, unknown>, refs?: string[]): Asset | Record<string, unknown> | undefined | {
+        readonly ok: false;
+        readonly error: ParseErrorDetail;
+    };
+    /**
+     * Parse a pack asset entry and return the payload + refs. Delegates to the
+     * load-by-guid collaboration module (w7 / D-4). Kept as a class method so
+     * existing structural-cast test access keeps resolving.
+     */
+    parseAndReturnAsset(assetEntry: {
+        kind: string;
+        payload: Record<string, unknown>;
+        refs?: string[];
+    }): Result<{
+        asset: Asset;
+        refs: readonly string[];
+    }, AssetError>;
+    /** Return the legacy catalog snapshot when no GUID is supplied. */
+    inspect(): InspectSnapshot;
+    /** Return joined source/cook/package/runtime evidence for one GUID. */
+    inspect(guid: string): Promise<Result<AssetEvidence, AssetEvidenceError>>;
+    /** Verify the same GUID evidence chain through the injected SDK capability. */
+    verifyByGuid(guid: string): Promise<Result<AssetEvidence, AssetEvidenceError>>;
+    /**
+     * Return a readonly snapshot of all catalogued assets (inlined + pack-index)
+     * for enumeration by asset panels (AC-03 single source of truth).
+     *
+     * Merges entries from the private `packIndexCache` (prod path, carries
+     * `packageUrl`) and `assetCatalog` (inlined / dev path, no URL). Each
+     * GUID appears exactly once. Returns a fresh array on every call — the
+     * internal Maps are never exposed (charter P4 consistent abstraction).
+     *
+     * plan-strategy section 2 D1; requirements AC-03; research Finding 5.
+     *
+     * @example
+     * ```ts
+     * for (const e of registry.listCatalog()) {
+     *   console.log(e.guid, e.kind, e.name, e.packageUrl);
+     * }
+     * ```
+     */
+    listCatalog(): readonly {
+        guid: string;
+        kind: string;
+        name?: string;
+        packageUrl: string;
+        packageId?: CatalogEntry['packageId'];
+        provenance?: CatalogEntry['provenance'];
+        revision?: CatalogEntry['revision'];
+        sourceKey?: CatalogEntry['sourceKey'];
+        sourceIndex?: CatalogEntry['sourceIndex'];
+        sourceOverrides?: CatalogEntry['sourceOverrides'];
+        sourceOverrideDescriptors?: CatalogEntry['sourceOverrideDescriptors'];
+        authoring?: CatalogEntry['authoring'];
+        relations?: CatalogEntry['relations'];
+        diagnostics?: CatalogEntry['diagnostics'];
+        refs?: readonly string[];
+        subject?: import('@forgeax/engine-types').CatalogSubject;
+        execution?: import('@forgeax/engine-types').CookExecution;
+        lifecycle?: import('@forgeax/engine-types').CatalogLifecycle;
+        projection?: import('@forgeax/engine-types').CatalogProjection;
+        /**
+         * On-disk source-file path for external imported assets (FBX / GLB / HDR /
+         * audio / font), relative to the game root. Editors locate the
+         * `.meta.json` sidecar via `sourcePath + '.meta.json'` for CRUD; unlike
+         * `packageUrl` (the runtime load artefact) it is stable across DDC cook
+         * state. `undefined` for inline / dev-path assets (no sidecar, no CRUD).
+         */
+        sourcePath?: string;
+    }[];
+}
+//# sourceMappingURL=asset-registry.d.ts.map

package/dist/asset-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asset-registry.d.ts","sourceRoot":"","sources":["../src/asset-registry.ts"],"names":[],"mappings":"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"}

package/dist/builtin-asset-registry.d.ts

@@ -0,0 +1,22 @@
+import type { Handle, MeshAsset as TypesMeshAsset } from '@forgeax/engine-types';
+import { BUILTIN_BASE } from '@forgeax/engine-types';
+export { BUILTIN_BASE };
+export declare const BUILTIN_CUBE: TypesMeshAsset;
+export declare const BUILTIN_TRIANGLE: TypesMeshAsset;
+export declare const BUILTIN_QUAD: TypesMeshAsset;
+export declare const BUILTIN_SPHERE: TypesMeshAsset;
+export declare const BUILTIN_CYLINDER: TypesMeshAsset;
+export declare const BUILTIN_NINESLICE_QUAD: TypesMeshAsset;
+/**
+ * Process-static builtin asset resolver (D-15). `resolve(handle)` returns the
+ * frozen builtin payload when `slot < BUILTIN_BASE`, else `null` (the slot
+ * belongs to the user tier — resolve it through `world.sharedRefs.resolve`).
+ *
+ * Read-only: there is no register / mint surface. The five builtin payloads
+ * are fixed at module load. AI users `import { BuiltinAssetRegistry } from
+ * '@forgeax/engine-runtime'` and resolve a builtin handle without a World.
+ */
+export declare const BuiltinAssetRegistry: Readonly<{
+    resolve<T extends TypesMeshAsset>(handle: Handle<string, "shared">): T | null;
+}>;
+//# sourceMappingURL=builtin-asset-registry.d.ts.map

package/dist/builtin-asset-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-asset-registry.d.ts","sourceRoot":"","sources":["../src/builtin-asset-registry.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,IAAI,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACjF,OAAO,EAAE,YAAY,EAAc,MAAM,uBAAuB,CAAC;AAMjE,OAAO,EAAE,YAAY,EAAE,CAAC;AAmBxB,eAAO,MAAM,YAAY,EAAE,cAAoD,CAAC;AAmBhF,eAAO,MAAM,gBAAgB,EAAE,cAAwD,CAAC;AAiBxF,eAAO,MAAM,YAAY,EAAE,cAAoD,CAAC;AAchF,eAAO,MAAM,cAAc,EAAE,cAAsD,CAAC;AAgBpF,eAAO,MAAM,gBAAgB,EAAE,cAAwD,CAAC;AAexF,eAAO,MAAM,sBAAsB,EAAE,cAA6D,CAAC;AAanG;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB;YACvB,CAAC,SAAS,cAAc,UAAU,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAAG,CAAC,GAAG,IAAI;EAM7E,CAAC"}

package/dist/catalog-source.d.ts

@@ -0,0 +1,24 @@
+import { type Result } from '@forgeax/engine-rhi';
+import { AssetError, type CatalogDelta, type CatalogEntry, type ResourceRevision, type RuntimeAssetBinding } from '@forgeax/engine-types';
+export type CatalogListener = (delta: CatalogDelta) => void;
+/** Read-only catalog source backed by static entries or a canonical URL. */
+export interface CatalogSource {
+    enumerate(): Promise<Result<readonly CatalogEntry[], AssetError>>;
+    subscribe(listener: CatalogListener): () => void;
+    readonly expectedScope?: Pick<RuntimeAssetBinding, 'scopeId' | 'generation'>;
+}
+/**
+ * Create a read-only catalog source while preserving the schema SSOT.
+ *
+ * Static and fetched sources use the same `CatalogEntry` and revision fields;
+ * an expected revision rejects unverified data before it reaches consumers.
+ */
+export declare function createCatalogSource(options: {
+    readonly url?: string;
+    readonly entries?: readonly CatalogEntry[];
+    readonly fetch?: typeof globalThis.fetch;
+    readonly expectedRevision?: ResourceRevision;
+    readonly expectedScope?: Pick<RuntimeAssetBinding, 'scopeId' | 'generation'>;
+    readonly subscribe?: (listener: CatalogListener) => () => void;
+}): CatalogSource;
+//# sourceMappingURL=catalog-source.d.ts.map

package/dist/catalog-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-source.d.ts","sourceRoot":"","sources":["../src/catalog-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAEL,UAAU,EACV,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACzB,MAAM,uBAAuB,CAAC;AAG/B,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;AAE5D,4EAA4E;AAC5E,MAAM,WAAW,aAAa;IAC5B,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,SAAS,YAAY,EAAE,EAAE,UAAU,CAAC,CAAC,CAAC;IAClE,SAAS,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,IAAI,CAAC;IACjD,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,SAAS,GAAG,YAAY,CAAC,CAAC;CAC9E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE;IAC3C,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IACzC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,SAAS,GAAG,YAAY,CAAC,CAAC;IAC7E,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,eAAe,KAAK,MAAM,IAAI,CAAC;CAChE,GAAG,aAAa,CAuDhB"}