@forgeax/engine-assets-runtime 0.1.4 → 0.1.6

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

@@ -0,0 +1,13 @@
+import { type AssetEvidence, type AssetEvidenceError, type AssetEvidenceInputs, type Result } from '@forgeax/engine-types';
+/** Host-injected runtime bridge; the adapter never imports CLI, Vite, or Node policy. */
+export interface RuntimeEvidenceSource {
+    readonly evidence: (guid: string) => Promise<AssetEvidenceInputs | Result<AssetEvidenceInputs, AssetEvidenceError>>;
+}
+/** Runtime SDK view over the shared AssetEvidence projector. */
+export interface RuntimeAssetEvidenceAdapter {
+    readonly inspect: (guid: string) => Promise<Result<AssetEvidence, AssetEvidenceError>>;
+    readonly verifyByGuid: (guid: string) => Promise<Result<AssetEvidence, AssetEvidenceError>>;
+}
+/** Create an adapter; omitted source intentionally returns capability-missing errors. */
+export declare function createRuntimeAssetEvidenceAdapter(source?: RuntimeEvidenceSource): RuntimeAssetEvidenceAdapter;
+//# sourceMappingURL=asset-evidence.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"asset-evidence.d.ts","sourceRoot":"","sources":["../../src/registry/asset-evidence.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,EAGxB,KAAK,MAAM,EACZ,MAAM,uBAAuB,CAAC;AAE/B,yFAAyF;AACzF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,CACjB,IAAI,EAAE,MAAM,KACT,OAAO,CAAC,mBAAmB,GAAG,MAAM,CAAC,mBAAmB,EAAE,kBAAkB,CAAC,CAAC,CAAC;CACrF;AAED,gEAAgE;AAChE,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC,CAAC;IACvF,QAAQ,CAAC,YAAY,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,kBAAkB,CAAC,CAAC,CAAC;CAC7F;AAuBD,yFAAyF;AACzF,wBAAgB,iCAAiC,CAC/C,MAAM,CAAC,EAAE,qBAAqB,GAC7B,2BAA2B,CAI7B"}

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

@@ -0,0 +1,47 @@
+import { type Result } from '@forgeax/engine-rhi';
+import type { AssetError, CatalogDelta, CatalogDiagnostic, CatalogEntry } from '@forgeax/engine-types';
+import type { CatalogSource } from '../catalog-source';
+export interface CatalogReplicaSnapshot {
+    readonly version: number;
+    readonly entries: readonly CatalogEntry[];
+    readonly stale: boolean;
+    readonly diagnostics: readonly CatalogDiagnostic[];
+}
+type SnapshotResult = Result<CatalogReplicaSnapshot, AssetError>;
+type CatalogDeltaListener = (delta: CatalogDelta) => void;
+/**
+ * One authoritative catalog read model owned by AssetRegistry.
+ *
+ * The source subscription is installed before the first enumeration. Deltas
+ * observed during that baseline read are buffered and folded afterwards, so
+ * an early publication cannot disappear between the two operations.
+ */
+export declare class CatalogReplica {
+    private readonly source;
+    private readonly listeners;
+    private readonly entries;
+    private pendingBeforeBaseline;
+    private pendingDuringReconcile;
+    private unsubscribe;
+    private startPromise;
+    private baselineReady;
+    private version;
+    private stale;
+    private diagnostics;
+    private currentSnapshot;
+    private readonly expectedScope;
+    constructor(source: CatalogSource);
+    subscribe(listener: CatalogDeltaListener): () => void;
+    snapshot(): CatalogReplicaSnapshot;
+    dispose(): void;
+    start(): Promise<SnapshotResult>;
+    reconcile(): Promise<SnapshotResult>;
+    private loadBaseline;
+    private receive;
+    private fold;
+    private safeDelta;
+    private publish;
+    private makeSnapshot;
+}
+export {};
+//# sourceMappingURL=catalog-state.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"catalog-state.d.ts","sourceRoot":"","sources":["../../src/registry/catalog-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAM,KAAK,MAAM,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EACV,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,YAAY,EAIb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,SAAS,iBAAiB,EAAE,CAAC;CACpD;AAED,KAAK,cAAc,GAAG,MAAM,CAAC,sBAAsB,EAAE,UAAU,CAAC,CAAC;AACjE,KAAK,oBAAoB,GAAG,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;AAmM1D;;;;;;GAMG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAgB;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAmC;IAC7D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmC;IAC3D,OAAO,CAAC,qBAAqB,CAAsB;IACnD,OAAO,CAAC,sBAAsB,CAA6B;IAC3D,OAAO,CAAC,WAAW,CAA2B;IAC9C,OAAO,CAAC,YAAY,CAAsC;IAC1D,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,eAAe,CAAyB;IAChD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkE;gBAEpF,MAAM,EAAE,aAAa;IAWjC,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,IAAI;IAKrD,QAAQ,IAAI,sBAAsB;IAIlC,OAAO,IAAI,IAAI;IAST,KAAK,IAAI,OAAO,CAAC,cAAc,CAAC;IAahC,SAAS,IAAI,OAAO,CAAC,cAAc,CAAC;YAQ5B,YAAY;IAuB1B,OAAO,CAAC,OAAO;IAef,OAAO,CAAC,IAAI;IAiCZ,OAAO,CAAC,SAAS;IA4BjB,OAAO,CAAC,OAAO;IAUf,OAAO,CAAC,YAAY;CAYrB"}

package/dist/registry/catalog.d.ts

@@ -0,0 +1,48 @@
+import { type Result } from '@forgeax/engine-rhi';
+import { type Asset, type AssetEnvelope, AssetError, type AssetPublicationEnvelope, type AssetRelation, type CatalogDiagnostic, type CatalogLifecycle, type CatalogProjection, type CatalogSubject, type CookExecution, type ProviderProvenance, type ResourceRevision, type RuntimeAssetBinding, type SourceOverrideDescriptor, type SourceOverrideMap } from '@forgeax/engine-types';
+import type { AssetRegistry } from '../asset-registry';
+/** Runtime catalog row parsed from the shared pack-index POD shape. */
+export interface CatalogRecord {
+    readonly packageUrl: string;
+    readonly kind: string;
+    readonly authoring?: import('@forgeax/engine-types').AssetAuthoringCapability;
+    readonly name?: string;
+    readonly refs?: readonly string[];
+    readonly sourcePath?: string;
+    readonly cookReceiptUrl?: string;
+    readonly packageId?: string;
+    readonly provenance?: ProviderProvenance;
+    readonly revision?: ResourceRevision;
+    readonly sourceKey?: string;
+    readonly sourceIndex?: number;
+    readonly sourceOverrides?: SourceOverrideMap;
+    readonly sourceOverrideDescriptors?: readonly SourceOverrideDescriptor[];
+    readonly relations?: readonly AssetRelation[];
+    readonly diagnostics?: readonly CatalogDiagnostic[];
+    /** Producer-owned projection axes; never infer these from locators. */
+    readonly subject?: CatalogSubject;
+    readonly execution?: CookExecution;
+    readonly lifecycle?: CatalogLifecycle;
+    readonly projection?: CatalogProjection;
+    /** Complete producer publication tuple used by Scene publication fences. */
+    readonly publication?: AssetPublicationEnvelope;
+}
+/** Build the canonical row for an inline asset without inventing producer facts. */
+export declare function createInlineCatalogRecord(envelope: AssetEnvelope<Asset>, name: string): CatalogRecord;
+type CatalogFetch = (input: string, init?: {
+    readonly cache?: 'no-store';
+}) => PromiseLike<{
+    readonly ok: boolean;
+    json(): Promise<unknown>;
+}>;
+/** Resolve a catalog entry URL against the configured pack-index URL. */
+export declare function resolveCatalogAssetUrl(registry: AssetRegistry, packageUrl: string): string;
+/** Parse the shared pack-index/catalog wire shape without loading payloads. */
+export declare function parseCatalog(raw: unknown, resolveUrl?: (packageUrl: string) => string, expectedRevision?: ResourceRevision, expectedScope?: Pick<RuntimeAssetBinding, 'scopeId' | 'generation'>): Result<Map<string, CatalogRecord>, AssetError>;
+/** Fetch and parse a catalog using the shared JSON/error boundary. */
+export declare function fetchCatalog(url: string, fetch: CatalogFetch, resolveUrl?: (packageUrl: string) => string, expectedRevision?: ResourceRevision, expectedScope?: Pick<RuntimeAssetBinding, 'scopeId' | 'generation'>, requestInit?: {
+    readonly cache?: 'no-store';
+}): Promise<Result<Map<string, CatalogRecord>, AssetError>>;
+export declare function fetchPackIndex(registry: AssetRegistry): Promise<Result<Map<string, CatalogRecord>, AssetError>>;
+export {};
+//# sourceMappingURL=catalog.d.ts.map

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

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

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"}