@forgeax/engine-assets-runtime 0.1.3 → 0.1.6

package/dist/registry/instantiate.d.ts

@@ -0,0 +1,153 @@
+import type { EcsError, EntityHandle, World } from '@forgeax/engine-ecs';
+import type { PackError } from '@forgeax/engine-pack/errors';
+import { type Result } from '@forgeax/engine-rhi';
+import { type Asset, AssetError, type Handle, type SceneAsset, type SceneInstanceMount, type SkinAsset, type TagOf } from '@forgeax/engine-types';
+import type { AssetRegistry } from '../asset-registry';
+import { type ScenePublicationFence, type ScenePublicationFenceError } from './scene-publication-fence';
+/**
+ * Resolver contract consumed by {@link postSpawnResolveJoints} (D-1: relocated
+ * here from scene-instances/post-spawn-resolve-joints.ts so the hook contract
+ * travels with the instantiate cluster into @forgeax/engine-assets-runtime).
+ */
+export interface SkinJointResolver {
+    resolveSkinAsset(skeletonHandleRaw: number): SkinAsset | undefined;
+}
+/**
+ * Post-spawn hook contract (D-1). A hook runs after instantiate spawns the
+ * scene subtree; the shipped implementation is runtime's `postSpawnResolveJoints`
+ * (auto-wire Skin.joints). Injected at the sole production assembly point
+ * (createRenderer) in w9/w10; when absent, instantiate skips joint wiring.
+ */
+export type PostSpawnHook = (world: World, resolver: SkinJointResolver, root: EntityHandle) => {
+    ok: true;
+} | {
+    ok: false;
+    error: unknown;
+};
+/**
+ * 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
+ *   }
+ * }
+ * ```
+ */
+export declare function instantiate<T extends SceneAsset>(registry: AssetRegistry, handle: Handle<TagOf<T>, 'shared'>, world: World, parent?: EntityHandle, expectedPublication?: ScenePublicationFence): Result<EntityHandle, AssetError | PackError | EcsError | ScenePublicationFenceError>;
+/**
+ * Materialise a `SceneAsset` FLAT into an existing `World` — the "edit the
+ * scene itself" registry entry (#655). Shares the GUID-resolution + shared-ref +
+ * SceneAssetResolver prelude with {@link instantiate}, but calls
+ * `worldInstantiateSceneFlat` instead of `worldInstantiateScene`: NO synthetic
+ * SceneInstance root, NO forced `ChildOf` on top-level members. The scene's own
+ * entities become plain top-level world entities; nested prefabs (`mounts[]`)
+ * still become their own SceneInstance anchors. Returns the set of top-level
+ * entity handles.
+ *
+ * Use this to OPEN a scene for authoring; use {@link instantiate} (anchor) at
+ * runtime / Play and for nested prefabs.
+ *
+ * The post-spawn Skin.joints hook (when wired via `registry.postSpawnHook`)
+ * runs once per top-level root: each GLB root keeps its own `ChildOf` subtree,
+ * so joint resolution is scoped to each subtree exactly as the anchor path
+ * scopes it to the single synthetic root.
+ */
+export declare function instantiateFlat<T extends SceneAsset>(registry: AssetRegistry, handle: Handle<TagOf<T>, 'shared'>, world: World, expectedPublication?: ScenePublicationFence): Result<EntityHandle[], AssetError | PackError | EcsError | ScenePublicationFenceError>;
+/**
+ * m3-i2: Recursively resolve mounts[].source GUID strings.
+ * Returns a PackError-shaped object on cycle (R-9) or AssetError
+ * on child resolution failure.
+ *
+ * feat-20260713 M3 / w13: also down-drills `mounts[].overrides[].value`,
+ * resolving any GUID string bound to a `shared<...>` / `array<shared<...>>`
+ * schema field to a live handle (D-2). `guidToHandle` is the caller's per-scene
+ * dedup map (shared with the entity-field resolution in `_resolveSceneGuids`) so
+ * the same catalogued GUID mints exactly one user-tier handle across entity
+ * fields and override values (D-15/D-17 dedup contract); it defaults to a fresh
+ * map so standalone callers keep working. Override resolution runs for every
+ * mount regardless of `source` branch — an unresolvable GUID fail-fasts here,
+ * before any spawn (P3: no half-initialized member).
+ */
+export declare function resolveMountsRec(registry: AssetRegistry, mounts: readonly SceneInstanceMount[], world: World, visited: Set<string>, guidToHandle?: Map<string, number>, resolvedSceneHandles?: Map<string, number>): Result<SceneInstanceMount[], AssetError | {
+    readonly code: 'pack-cyclic-reference';
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: {
+        readonly code: 'pack-cyclic-reference';
+        readonly kind: 'mount-asset';
+        readonly cycle: readonly string[];
+    };
+} | ScenePublicationFenceError>;
+/**
+ * Resolve one GUID string to a live user-tier handle (feat-20260713 M3 / w13
+ * SSOT). Parses the GUID, uses `guidToHandle` as the per-resolution fast path,
+ * and on a miss looks the envelope up in the catalog + interns its shared ref
+ * by `(target, payload identity)` in the World. An unparseable / uncatalogued
+ * GUID returns `AssetError(code='asset-not-found')` with a breadcrumb hint
+ * (`fieldPath` + `location`) for AI-user debuggability (P3). Shared by the
+ * entity-field fallback in `_resolveSceneGuids` and the override-value down-drill
+ * in {@link resolveMountOverrides} so the parse/dedup/lookup/mint idiom has one
+ * home (architecture-principles §1 SSOT).
+ */
+export declare function resolveHandleGuid(registry: AssetRegistry, world: World, guidString: string, guidToHandle: Map<string, number>, fieldPath: string, location: string): Result<number, AssetError>;
+/**
+ * tweak-20260609 M1 helper: build the per-sub-ref parent context for a
+ * SceneAsset child. feat-20260622 M3 / w9: re-sourced to lookup in the
+ * scene envelope's ``refs[]`` edges instead of walking entity components
+ * via extractSceneEntityHandleGuids (D-7). When the scene envelope is not
+ * found in the catalog, falls back to the entity-walk path (backward compat
+ * for call sites that lack a catalogued envelope).
+ *
+ * Texture edges (sourceField=undefined) produce ``componentField:
+ * undefined`` — the breadcrumb will show GUID+kind only, no per-entity
+ * detail (D-2: texture has no per-entity origin).
+ */
+export declare function buildSceneChildContext(registry: AssetRegistry, scene: Asset & {
+    kind: 'scene';
+}, subGuidKey: string, sceneGuidKey?: string): {
+    sceneEntityId?: number;
+    componentField?: string;
+    sourceField?: {
+        componentName?: string;
+        fieldName: string;
+        arrayIndex?: number;
+    };
+} | undefined;
+/**
+ * tweak-20260609 M1 helper: build the error-hint breadcrumb string
+ * containing the parent asset's GUID + kind, enriched with the
+ * caller-provided `parentContext` (entity localId + component.field).
+ *
+ * Per D-7 / B-8: the breadcrumb appears before the sub-asset's own hint,
+ * separated by " / ".
+ */
+export declare function buildBreadcrumbHint(parentGuidKey: string, parentKind: string, subGuidKey: string, parentContext?: {
+    sceneEntityId?: number;
+    componentField?: string;
+}): string;
+//# sourceMappingURL=instantiate.d.ts.map

package/dist/registry/instantiate.d.ts.map

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

package/dist/registry/load-by-guid.d.ts

@@ -0,0 +1,247 @@
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { type Result, type RhiError } from '@forgeax/engine-rhi';
+import { type Asset, type AssetCompression, AssetError, type AssetErrorCode, type AssetRef, type CatalogSubject, type ImageError, type ImageMetadata, type LoadContext, type ParseErrorDetail } from '@forgeax/engine-types';
+import type { AssetRegistry } from '../asset-registry';
+import { type MaterialLoadError, type MaterialLoadRequest, type MaterialReady } from '../material/loader';
+/**
+ * Load an asset and all its transitively referenced sub-assets by GUID;
+ * returns `ok(handle)` only when the asset and every sub-asset are in the
+ * registry.
+ *
+ * **Post-condition:** `ok(payload)` is returned ONLY when the asset AND every
+ * transitively referenced sub-asset (per the asset envelope's `refs[]`) are
+ * present in this registry. The implementation walks `envelope.refs` and
+ * recursively calls `loadByGuid` on each ref before cataloguing the top-level
+ * asset. The resolved value is the PAYLOAD `T`
+ * (D-17), never a handle -- mint a column handle with
+ * `world.allocSharedRef('Kind', payload)` when one is needed (e.g. before
+ * `instantiate`).
+ *
+ * Two paths:
+ * - **Dev / fallback** (no `configurePackIndex` call): synchronous catalogue
+ *   lookup wrapped in `Promise.resolve`. Returns `Err(asset-not-found)` if not
+ *   catalogued.
+ * - **Prod** (after `configurePackIndex(url)`): fetches `pack-index.json`
+ *   on the first call (cached as a `Map<guid, {packageUrl, kind}>`), then
+ *   fetches the individual resource URL and parses the asset payload, then
+ *   catalogues it (GUID -> payload) and returns the payload.
+ *
+ * Error union: `AssetError | PackError | ImageError | RhiError` (closed -- no
+ * new codes were introduced by the recursive walk; every code is pre-existing).
+ *
+ * An in-flight `Map` (D-5) deduplicates concurrent calls for the same GUID and
+ * prevents stack overflow on cycles (A->B->A).
+ *
+ * **Breaking-change classification:** this is a semantic strengthening, not a
+ * shape change. Sub-assets catalogued by a prior `catalog(guid, payload)` /
+ * `loadByGuid` call are protected by the catalogue fast-path: the recursive
+ * walk hits cache on every node and incurs zero additional fetch.
+ *
+ * @example
+ * ```ts
+ * const res = await engine.assets.loadByGuid<SceneAsset>(sceneGuid);
+ * if (!res.ok) {
+ *   switch (res.error.code) {
+ *     case 'asset-not-found':
+ *       // top GUID or any sub-asset GUID is missing from the catalog
+ *       break;
+ *     case 'asset-fetch-failed':
+ *       // network / CORS
+ *       break;
+ *     case 'asset-parse-failed':
+ *       // payload malformed
+ *       break;
+ *     // ... AssetErrorCode | PackErrorCode | ImageErrorCode | RhiErrorCode exhaustive
+ *   }
+ *   return;
+ * }
+ * ```
+ */
+export declare function loadByGuid<T = Asset>(registry: AssetRegistry, guid: AssetGuid, parentContext?: {
+    sceneEntityId?: number;
+    componentField?: string;
+}): Promise<Result<T, AssetError | ImageError | RhiError>>;
+export declare function loadMaterialReadyByGuid(registry: AssetRegistry, request: MaterialLoadRequest): Promise<MaterialReady | MaterialLoadError>;
+/**
+ * feat-20260603-asset-import-loader-injection M1 / w6: load an
+ * upstream-branch kind (texture / font) straight from its catalog entry
+ * through the injected async loader, then register the produced POD. Replaces
+ * the bespoke `loadTextureFromEntry` / `loadFontFromEntry` methods; the decode
+ * / glyph-parse logic moved verbatim into the loader bodies (D-2 — loader is
+ * pure of `registerWithGuid`, which stays here).
+ */
+export declare function loadFromUpstreamEntry<T = Asset>(registry: AssetRegistry, guidKey: string, entry: {
+    packageUrl: string;
+    kind: string;
+    name?: string;
+    metadata?: ImageMetadata | undefined;
+}): Promise<Result<T, AssetError | ImageError | RhiError>>;
+/**
+ * Internal: prod fetch path for `loadByGuid`.
+ * Fetches pack-index.json (cached), then fetches the pack file, parses the
+ * asset payload, and registers it.
+ */
+export declare function loadByGuidProd<T = Asset>(registry: AssetRegistry, guid: AssetGuid, guidKey: string, parentContext?: {
+    sceneEntityId?: number;
+    componentField?: string;
+}, ancestry?: ReadonlySet<string>): Promise<Result<T, AssetError | ImageError | RhiError>>;
+/**
+ * Resolve the catalog entry for a GUID, lazily fetching the pack-index on
+ * first call. Returns `undefined` when the GUID is absent from the catalog.
+ */
+export declare function resolveCatalogEntry(registry: AssetRegistry, guidKey: string): Promise<{
+    packageUrl: string;
+    kind: string;
+    name?: string;
+    metadata?: ImageMetadata | undefined;
+    compression?: AssetCompression;
+} | undefined>;
+/**
+ * feat-20260618 M3 (D-2): once the pack-index is parsed, group every row by
+ * its `packageUrl` and register each package fully -- all of its GUIDs and
+ * their entry display names in one `registerPackage` call. Registering the
+ * whole package at once (rather than one GUID per load) means the package
+ * cardinality is known up front, so `resolveName` returns the basename for a
+ * genuinely single-asset package and the entry name for a multi-asset one,
+ * with no incremental 1->N promotion needed on the prod path. The name travels
+ * entry -> Package, never through the payload (Risk-3 JSON-roundtrip safety),
+ * and covers both the sync (parseAssetPayload) and async (texture/font) loads.
+ */
+export declare function registerPackagesFromIndex(registry: AssetRegistry, catalog: Map<string, {
+    packageUrl: string;
+    name?: string;
+    sourcePath?: string;
+    subject?: CatalogSubject;
+}>): void;
+/**
+ * Load an asset through the DDC (catalog entry -> fetch pack -> loader.load
+ * -> register). Returns `Err(asset-not-found)` or `Err(asset-fetch-failed)`
+ * on DDC miss (the caller then decides whether to route through the
+ * import transport).
+ *
+ * This path is IDENTICAL in studio and shipped forms -- the only difference
+ * between the two is whether `registry.importTransport` exists when the caller
+ * falls back to `transportOrFail` (AC-23 key invariant).
+ */
+export declare function ddcLoad<T = Asset>(registry: AssetRegistry, guid: AssetGuid, guidKey: string, entry: {
+    packageUrl: string;
+    kind: string;
+    name?: string;
+    metadata?: ImageMetadata | undefined;
+    compression?: AssetCompression;
+}, parentContext?: {
+    sceneEntityId?: number;
+    componentField?: string;
+}, ancestry?: ReadonlySet<string>): Promise<Result<T, AssetError | ImageError | RhiError>>;
+/**
+ * M4 transport fallback: try the injected {@link ImportTransport} to lazily
+ * import a missing DDC, then re-enter the DDC load path. When no transport
+ * is wired (shipped form), fail fast with `asset-not-imported` (AC-22).
+ */
+export declare function transportOrFail<T = Asset>(registry: AssetRegistry, guid: AssetGuid, guidKey: string, _missReason: AssetErrorCode): Promise<Result<T, AssetError | ImageError | RhiError>>;
+/**
+ * Register a parsed asset POD (the synchronous tail of the DDC load path:
+ * `registerWithGuid`). Material parent preload is handled asynchronously
+ * inside `ddcLoad` before calling this method; the registered asset is
+ * always fully resolved by the time it reaches here.
+ *
+ * Extracted from the old `loadByGuidProd` body so `ddcLoad` and
+ * `transportOrFail` share an identical load path (AC-23 key invariant).
+ */
+export declare function registerParsedAsset<T = Asset>(registry: AssetRegistry, guid: AssetGuid, asset: Asset, _guidKey: string, refs?: readonly AssetRef[]): Result<T, AssetError | ImageError | RhiError>;
+/**
+ * Fetch a .pack.json file, find the asset entry matching guidKey, and
+ * reconstruct the Asset from its payload.
+ */
+/**
+ * bug-20260610: fetch one pack file and return the raw asset entry without
+ * parsing. Used by `loadByGuidProd` for material kinds so the caller can
+ * recursively preload `refs[]` (texture sub-assets) BEFORE the synchronous
+ * materialLoader runs and rewrites values handle fields to their refs[]
+ * GUID strings (feat-20260614 M8 / D-19: GUID verbatim, no handle minting).
+ */
+export declare function fetchPackEntry(_registry: AssetRegistry, packageUrl: string, guidKey: string): Promise<Result<{
+    kind: string;
+    payload: Record<string, unknown>;
+    refs?: string[];
+}, AssetError>>;
+/**
+ * Fetch one pack file, locate the requested asset entry, and either parse it
+ * inline or expose the entry to the caller (for kinds that need to preload
+ * `refs[]` BEFORE running the loader — currently 'material', whose
+ * values handle fields are rewritten to their refs[] GUID strings
+ * (feat-20260614 M8 / D-19: GUID verbatim, no handle minting at load time)).
+ *
+ * bug-20260610 Fix B (M3 / D-4): the fetch+parse result is cached per
+ * `packageUrl` in `packFileCache`; concurrent calls for the same URL share
+ * a single in-flight promise via `packFileInFlight`. Only the raw parsed
+ * body is cached — `parseAssetPayload` still runs per-call (CON-2).
+ */
+export declare function fetchPackFile(registry: AssetRegistry, packageUrl: string, guidKey: string, _kind: string): Promise<Result<{
+    asset: Asset;
+    refs: readonly string[];
+}, AssetError>>;
+/**
+ * Parse the asset payload from a pack-file entry and return the result.
+ * Extracted so cache-hit and in-flight-dedup paths share the same
+ * parseAssetPayload + error-wrapping logic.
+ */
+export declare function parseAndReturnAsset(registry: AssetRegistry, assetEntry: {
+    kind: string;
+    payload: Record<string, unknown>;
+    refs?: string[];
+}): Result<{
+    asset: Asset;
+    refs: readonly string[];
+}, AssetError>;
+/**
+ * Fetch a pack file from the network, parse the JSON body, store the
+ * result in the cache, and return the requested asset entry.
+ *
+ * Registers the in-flight promise in `packFileInFlight` so concurrent
+ * callers share a single fetch. On success the body moves to
+ * `packFileCache`; on failure the in-flight entry is removed so
+ * subsequent retries re-fetch (D-7).
+ */
+export declare function fetchAndCachePackFile(registry: AssetRegistry, packageUrl: string, guidKey: string): Promise<Result<{
+    asset: Asset;
+    refs: readonly string[];
+}, AssetError>>;
+/**
+ * Reconstruct a typed `Asset` from a raw payload object.
+ *
+ * @param kind The asset kind discriminant (matches the pack entry or
+ *   dev-register dispatch).
+ * @param payload The serialised asset payload (keys mirror the asset
+ *   interface field names).
+ * @param refs Pack-file refs array for Handle fields — when a field
+ *   value is `number` it resolves to `refs[N]` (glTF-style index).
+ *   Optional to preserve compatibility with callers outside the pack
+ *   ingestion path (e.g., direct `registerWithGuid`).
+ */
+export declare function parseAssetPayload(registry: AssetRegistry, kind: string, payload: Record<string, unknown>, refs?: string[]): Asset | Record<string, unknown> | undefined | {
+    readonly ok: false;
+    readonly error: ParseErrorDetail;
+};
+/**
+ * Build the {@link LoadContext} passed to a loader's `load`.
+ * `fetchBinary` / `resolveRef` / `device` are wired for the async texture /
+ * font loaders (w6).
+ */
+export declare function makeLoadContext(registry: AssetRegistry): LoadContext;
+/**
+ * Return a runtime snapshot of every catalogued asset. Each entry exposes
+ * `{ guid, kind, name }` where `kind` is the asset discriminant string
+ * from `payload.kind`. feat-20260614 M8 (D-15): the registry holds no
+ * handles -- entries are keyed by GUID (the catalogue key).
+ *
+ * AI-user narrowing flow (AC-11 + plan-strategy §7.4):
+ * ```ts
+ * for (const e of registry.inspect().assets) {
+ *   if (e.kind === 'texture') {
+ *     // re-query via registry.lookup(e.guid) to get the typed Asset value.
+ *   }
+ * }
+ * ```
+ */
+//# sourceMappingURL=load-by-guid.d.ts.map

package/dist/registry/load-by-guid.d.ts.map

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

package/dist/registry/load-state.d.ts

@@ -0,0 +1,26 @@
+export type LoadStatus = 'unloaded' | 'provisional' | 'ready' | 'failed';
+export interface LoadRecord {
+    readonly status: LoadStatus;
+    readonly refs: readonly string[];
+    readonly value?: unknown;
+    readonly error?: unknown;
+}
+export declare class LoadStateStore {
+    private readonly records;
+    get(guid: string): LoadRecord | undefined;
+    getReady<T = unknown>(guid: string): T | undefined;
+    /**
+     * Return a provisional value only for the internal SCC back-edge bridge.
+     * Public callers must use getReady so promotion remains the visibility gate.
+     */
+    getProvisional<T = unknown>(guid: string): T | undefined;
+    begin(guid: string, refs: readonly string[]): LoadRecord;
+    resolveAsset(guid: string, value: unknown): void;
+    registerReady(guid: string, value: unknown): void;
+    promoteReady(guid: string): void;
+    fail(guid: string, error: unknown): readonly string[];
+    remove(guid: string): void;
+    clear(): void;
+    private provisionalGroup;
+}
+//# sourceMappingURL=load-state.d.ts.map

package/dist/registry/load-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-state.d.ts","sourceRoot":"","sources":["../../src/registry/load-state.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,aAAa,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEzE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AASD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwC;IAEhE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAIzC,QAAQ,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAKlD;;;OAGG;IACH,cAAc,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAKxD,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,UAAU;IAYxD,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAUhD,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAMjD,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAkBhC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE;IAWrD,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI1B,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,gBAAgB;CAYzB"}

package/dist/registry/runtime-projection.d.ts

@@ -0,0 +1,16 @@
+import { type Result } from '@forgeax/engine-rhi';
+import { AssetError, type CatalogProjection } from '@forgeax/engine-types';
+import type { CatalogRecord } from './catalog';
+export interface RuntimeProjection {
+    readonly subject: CatalogProjection['subject'];
+    readonly execution: CatalogProjection['execution'];
+    readonly lifecycle: CatalogProjection['lifecycle'];
+    readonly packageUrl: string;
+}
+/**
+ * Resolve the producer-declared runtime projection. Legacy rows return
+ * undefined so inline/dev assets retain their existing registration path;
+ * rows that publish any projection axis must publish all three axes.
+ */
+export declare function resolveRuntimeProjection(guid: string, record: CatalogRecord): Result<RuntimeProjection | undefined, AssetError>;
+//# sourceMappingURL=runtime-projection.d.ts.map

package/dist/registry/runtime-projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-projection.d.ts","sourceRoot":"","sources":["../../src/registry/runtime-projection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAqB,UAAU,EAAE,KAAK,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC9F,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC;IAC/C,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC,WAAW,CAAC,CAAC;IACnD,QAAQ,CAAC,SAAS,EAAE,iBAAiB,CAAC,WAAW,CAAC,CAAC;IACnD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAUD;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,GACpB,MAAM,CAAC,iBAAiB,GAAG,SAAS,EAAE,UAAU,CAAC,CAmCnD"}

package/dist/registry/scene-publication-fence.d.ts

@@ -0,0 +1,38 @@
+import { type Result } from '@forgeax/engine-rhi';
+import type { AssetPublicationEnvelope, CatalogEntry, ScenePublicationFence as EngineScenePublicationFence } from '@forgeax/engine-types';
+export declare const SCENE_PUBLICATION_FENCE_SCHEMA: "scene-publication-fence/1";
+export declare const SCENE_PUBLICATION_RECOVERY_ACTIONS: readonly ["continue-last-known-good", "retry-rebuild", "fresh-reopen"];
+export type ScenePublicationFence = EngineScenePublicationFence;
+export type ScenePublicationFencePhase = 'publication' | 'catalog' | 'observation' | 'instantiate';
+export interface ScenePublicationFenceError {
+    readonly code: 'asset-generation-fence-mismatch';
+    readonly phase: ScenePublicationFencePhase;
+    readonly hint: string;
+    readonly sourcePath?: string;
+    readonly sourceRevision?: string;
+    readonly expected?: ScenePublicationFence;
+    readonly actual?: ScenePublicationFence;
+    readonly currentGeneration?: number;
+    readonly lastKnownGood?: ScenePublicationFence;
+    readonly retryable: boolean;
+    readonly recoveryActions: readonly string[];
+}
+export interface ScenePublicationObservation {
+    readonly fence: ScenePublicationFence;
+    readonly outputs: readonly string[];
+}
+/** Convert one complete Engine publication into the serializable Scene fence. */
+export declare function createScenePublicationFence(publication: AssetPublicationEnvelope): Result<ScenePublicationFence, ScenePublicationFenceError>;
+/** Parse the persisted fence without guessing legacy generation or identity. */
+export declare function parseScenePublicationFence(value: unknown): Result<ScenePublicationFence, ScenePublicationFenceError>;
+/** Compare all fence fields; no single generation or GUID may stand in for it. */
+export declare function compareScenePublicationFences(expected: ScenePublicationFence, actual: ScenePublicationFence, lastKnownGood?: ScenePublicationFence): Result<ScenePublicationFence, ScenePublicationFenceError>;
+/** Derive a fence only when every Catalog row for the source publication is present and aligned. */
+export declare function scenePublicationFenceFromCatalog(entries: readonly CatalogEntry[], outputGuid: string): Result<ScenePublicationFence, ScenePublicationFenceError>;
+export declare function observeScenePublication(input: {
+    readonly publication: AssetPublicationEnvelope;
+    readonly waitForOutput: (guid: string) => Promise<void>;
+    readonly timeoutMs?: number;
+    readonly lastKnownGood?: ScenePublicationFence;
+}): Promise<Result<ScenePublicationObservation, ScenePublicationFenceError>>;
+//# sourceMappingURL=scene-publication-fence.d.ts.map

package/dist/registry/scene-publication-fence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-publication-fence.d.ts","sourceRoot":"","sources":["../../src/registry/scene-publication-fence.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EACV,wBAAwB,EACxB,YAAY,EACZ,qBAAqB,IAAI,2BAA2B,EACrD,MAAM,uBAAuB,CAAC;AAE/B,eAAO,MAAM,8BAA8B,EAAG,2BAAoC,CAAC;AACnF,eAAO,MAAM,kCAAkC,wEAIpC,CAAC;AAEZ,MAAM,MAAM,qBAAqB,GAAG,2BAA2B,CAAC;AAEhE,MAAM,MAAM,0BAA0B,GAAG,aAAa,GAAG,SAAS,GAAG,aAAa,GAAG,aAAa,CAAC;AAEnG,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC;IACjD,QAAQ,CAAC,KAAK,EAAE,0BAA0B,CAAC;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,qBAAqB,CAAC;IACxC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,aAAa,CAAC,EAAE,qBAAqB,CAAC;IAC/C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAkDD,iFAAiF;AACjF,wBAAgB,2BAA2B,CACzC,WAAW,EAAE,wBAAwB,GACpC,MAAM,CAAC,qBAAqB,EAAE,0BAA0B,CAAC,CA4C3D;AAED,gFAAgF;AAChF,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,GACb,MAAM,CAAC,qBAAqB,EAAE,0BAA0B,CAAC,CA0B3D;AAED,kFAAkF;AAClF,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,qBAAqB,EAC/B,MAAM,EAAE,qBAAqB,EAC7B,aAAa,CAAC,EAAE,qBAAqB,GACpC,MAAM,CAAC,qBAAqB,EAAE,0BAA0B,CAAC,CAW3D;AAED,oGAAoG;AACpG,wBAAgB,gCAAgC,CAC9C,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,UAAU,EAAE,MAAM,GACjB,MAAM,CAAC,qBAAqB,EAAE,0BAA0B,CAAC,CAyB3D;AAED,wBAAsB,uBAAuB,CAAC,KAAK,EAAE;IACnD,QAAQ,CAAC,WAAW,EAAE,wBAAwB,CAAC;IAC/C,QAAQ,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,qBAAqB,CAAC;CAChD,GAAG,OAAO,CAAC,MAAM,CAAC,2BAA2B,EAAE,0BAA0B,CAAC,CAAC,CAoC3E"}

package/dist/registry/validate-material.d.ts

@@ -0,0 +1,77 @@
+import type { CookedMaterialRecord } from '@forgeax/engine-pack';
+import { AssetError, type MaterialAsset, type MaterialError } from '@forgeax/engine-types';
+import type { AssetRegistry } from '../asset-registry';
+/**
+ * Validate a MaterialAsset's passes[] against the ShaderRegistry's
+ * paramSchema (union semantics: all declared params across all passes
+ * must be satisfiable from values).
+ *
+ * - Empty / undefined passes[] → error
+ * - Each pass's shader must exist in ShaderRegistry
+ * - Union of all pass paramSchemas: params without `default` must
+ *   appear in values with matching type
+ * - Extra keys in values are silently ignored (D-5)
+ *
+ * @returns AssetError on failure, null on success
+ */
+export declare function validateMaterialPasses(registry: AssetRegistry, asset: MaterialAsset): AssetError | null;
+export interface MaterialEffectiveRootIdentity {
+    readonly guid: string;
+    readonly layoutIdentity: string;
+}
+export declare function validateMaterialCookIdentity(record: Pick<CookedMaterialRecord, 'guid' | 'receipt'>, root: MaterialEffectiveRootIdentity): MaterialError | null;
+/**
+ * Sprite 9-slice values fail-fast validation
+ * (feat-20260527-sprite-nineslice M2 / w8, plan-strategy §D-1 + AC-08).
+ *
+ * Fires when:
+ *  - asset.kind === 'material'
+ *  - first pass shader === 'forgeax::sprite'
+ *  - values.slices is present
+ *
+ * Six fail-fast branches (1:1 with w4 test):
+ *   (1) any component is negative
+ *   (2) slices.x + slices.z >= region.zw[0]   (X-axis overlap)
+ *   (3) slices.y + slices.w >= region.zw[1]   (Y-axis overlap)
+ *   (4) any component is NaN
+ *   (5) any component is Infinity
+ *   (6) length !== 4
+ *
+ * Reuses the existing 'asset-invalid-value' member of the closed
+ * `AssetErrorCode` 13-member union (no new code added per
+ * AGENTS.md §Error model). The `.expected` literal mirrors the AI-User
+ * Charter §3 string; `.hint` inlines the offending sum + the relevant
+ * `region.zw` numeral so AI users can copy-paste the prompt straight
+ * back into the IDE for self-recovery (plan-strategy §R-4).
+ *
+ * @returns AssetError on failure, null on success.
+ */
+export declare function validateSpriteSlices(_registry: AssetRegistry, asset: MaterialAsset): AssetError | null;
+export declare function validateParamType(_registry: AssetRegistry, _name: string, type: string, value: unknown): boolean;
+/**
+ * feat-20260527-sprite-nineslice M4 / w18 (D-9): register-time soft-warn
+ * for sliceMode=1 (tile) bound to a sampler whose addressMode is not
+ * 'repeat'. Bumps `nineslice.tile-needs-repeat-sampler` once per offending
+ * catalogue call. Never throws -- the counter is the sole AI-user-facing
+ * signal (charter P3 machine-readable; AC-08 closed, never extends
+ * AssetErrorCode).
+ *
+ * feat-20260614 M8 (D-19): `values.sampler` is now an embedded GUID
+ * string (dash-form), resolved against the catalogue rather than a handle.
+ */
+export declare function detectTileNeedsRepeatSampler(registry: AssetRegistry, asset: MaterialAsset): void;
+/**
+ * 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`.
+ */
+export declare function materialShaderTextureFieldNames(registry: AssetRegistry, shaderId: string): ReadonlySet<string> | undefined;
+//# sourceMappingURL=validate-material.d.ts.map

package/dist/registry/validate-material.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-material.d.ts","sourceRoot":"","sources":["../../src/registry/validate-material.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EACL,UAAU,EAEV,KAAK,aAAa,EAClB,KAAK,aAAa,EAEnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,aAAa,EACvB,KAAK,EAAE,aAAa,GACnB,UAAU,GAAG,IAAI,CAoFnB;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,MAAM,GAAG,SAAS,CAAC,EACtD,IAAI,EAAE,6BAA6B,GAClC,aAAa,GAAG,IAAI,CAkBtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,aAAa,EACxB,KAAK,EAAE,aAAa,GACnB,UAAU,GAAG,IAAI,CA8GnB;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,aAAa,EACxB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GACb,OAAO,CAgCT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CA8BhG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,MAAM,GACf,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,CAIjC"}

package/dist/resolve-asset-handle.d.ts

@@ -0,0 +1,43 @@
+import type { SharedRefStaleError, UniqueRefStaleError, World } from '@forgeax/engine-ecs';
+import type { AssetGuid } from '@forgeax/engine-pack/guid';
+import { type Result } from '@forgeax/engine-rhi';
+import type { Asset, AssetError as AssetErrorType, Handle, MaterialAsset, MaterialError, MaterialPass } from '@forgeax/engine-types';
+/**
+ * Resolve a handle to its asset payload with two-tier slot-range dispatch.
+ *
+ *   slot <  BUILTIN_BASE -> BuiltinAssetRegistry.resolve(handle) (process-static)
+ *   slot >= BUILTIN_BASE -> world.sharedRefs.resolve(handle)     (user-tier RC)
+ *
+ * Callers must specify the expected asset type explicitly:
+ * `resolveAssetHandle<MeshAsset>(world, handle)`. The type parameter is an
+ * assertion -- the runtime dispatch returns the correct payload based on slot
+ * range; the type parameter mirrors the caller's expectation.
+ *
+ * @param world - The World owning the per-World SharedRefStore (user-tier).
+ * @param handle - The branded handle to resolve.
+ * @returns `Result.ok(payload)` on hit, `Result.err(AssetError)` on miss.
+ */
+export declare function resolveAssetHandle<T extends Asset>(world: World, handle: Handle<string, 'shared'>): Result<T, AssetErrorType | SharedRefStaleError | UniqueRefStaleError>;
+/**
+ * Walk a MaterialAsset parent chain to produce the inherited passes +
+ * shallow-merged values (W-1..W-7 semantics). feat-20260614 M8 (D-19):
+ * the starting material is resolved from a column `handle` via
+ * {@link resolveAssetHandle} (builtin / user-tier world.sharedRefs); each
+ * ancestor `material.parent` is an embedded GUID (AssetGuid) resolved through
+ * the AssetRegistry catalogue ({@link AssetRegistry.lookup}). The registry
+ * holds no handles -- it is the GUID->payload SSOT for parent resolution.
+ *
+ * Zero-cache (AC-04): every call builds the same table-shaped input and delegates
+ * inheritance semantics to the MaterialAsset resolver in `@forgeax/engine-types`.
+ * Compiler and runtime therefore share root-contract ownership and child-value
+ * override semantics instead of maintaining two subtly different walks.
+ */
+export declare function walkMaterialPassesOverSharedRefs(world: World, handle: Handle<'MaterialAsset', 'shared'>, registry: {
+    lookup(guid: AssetGuid | string): Asset | undefined;
+}): Result<{
+    passes: MaterialPass[];
+    parameters: MaterialAsset['parameters'];
+    values: NonNullable<MaterialAsset['values']>;
+    colorSpace: MaterialAsset['colorSpace'];
+}, AssetErrorType | MaterialError | SharedRefStaleError | UniqueRefStaleError>;
+//# sourceMappingURL=resolve-asset-handle.d.ts.map

package/dist/resolve-asset-handle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-asset-handle.d.ts","sourceRoot":"","sources":["../src/resolve-asset-handle.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC3F,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAW,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EACV,KAAK,EACL,UAAU,IAAI,cAAc,EAC5B,MAAM,EACN,aAAa,EACb,aAAa,EACb,YAAY,EACb,MAAM,uBAAuB,CAAC;AAW/B;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,KAAK,EAChD,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,GAC/B,MAAM,CAAC,CAAC,EAAE,cAAc,GAAG,mBAAmB,GAAG,mBAAmB,CAAC,CAiCvE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gCAAgC,CAC9C,KAAK,EAAE,KAAK,EACZ,MAAM,EAAE,MAAM,CAAC,eAAe,EAAE,QAAQ,CAAC,EACzC,QAAQ,EAAE;IAAE,MAAM,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,CAAA;CAAE,GAChE,MAAM,CACP;IACE,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,UAAU,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;IACxC,MAAM,EAAE,WAAW,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC7C,UAAU,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC;CACzC,EACD,cAAc,GAAG,aAAa,GAAG,mBAAmB,GAAG,mBAAmB,CAC3E,CA+BA"}