@forgeax/engine-assets-runtime 0.1.3 → 0.1.6

package/src/registry/load-by-guid.ts

@@ -0,0 +1,1657 @@
+// @forgeax/engine-assets-runtime -- load-by-guid + pack-fetch collaboration module
+// (feat-20260705-runtime-tier2-decomposition M1 / w7, D-4). Free functions
+// taking the AssetRegistry instance as first param; logic byte-preserved from the
+// class body (this. -> registry.). This is the largest method cluster (loadByGuid
+// + the DDC / pack-index / pack-file fetch + parse pipeline).
+
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { err, ok, type Result, type RhiError } from '@forgeax/engine-rhi';
+import { isEngineMaterial } from '@forgeax/engine-shader';
+import {
+  type ArtifactDescriptor,
+  ASSET_ERROR_HINTS,
+  type Asset,
+  type AssetCompression,
+  AssetError,
+  type AssetErrorCode,
+  type AssetErrorDetail,
+  type AssetRef,
+  type CatalogSubject,
+  type ImageError,
+  type ImageMetadata,
+  type LoadContext,
+  type LoaderAsyncResult,
+  type MaterialAsset,
+  type MeshAsset,
+  type ParseErrorDetail,
+} from '@forgeax/engine-types';
+import type { AssetRegistry, ParsedPackFile } from '../asset-registry';
+import {
+  createMaterialLoader,
+  type MaterialLoadError,
+  type MaterialLoadRequest,
+  type MaterialPublication,
+  type MaterialReady,
+} from '../material/loader';
+import { readArtifact } from './artifact-io';
+import { fetchPackIndex, resolveCatalogAssetUrl } from './catalog';
+import { buildBreadcrumbHint, buildSceneChildContext } from './instantiate';
+import { resolveRuntimeProjection } from './runtime-projection';
+
+/**
+ * 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 async function loadByGuid<T = Asset>(
+  registry: AssetRegistry,
+  guid: AssetGuid,
+  parentContext?: {
+    sceneEntityId?: number;
+    componentField?: string;
+  },
+): Promise<Result<T, AssetError | ImageError | RhiError>> {
+  return loadByGuidInternal(registry, guid, parentContext, new Set());
+}
+
+function cookedRecordFromPayload(payload: Record<string, unknown>): unknown {
+  if (payload.schemaVersion === 'material-cook/2') return payload;
+  if (payload.cooked !== null && typeof payload.cooked === 'object') return payload.cooked;
+  if (payload.record !== null && typeof payload.record === 'object') return payload.record;
+  return undefined;
+}
+
+function materialArtifactKey(
+  record: Record<string, unknown> | undefined,
+  descriptors: Readonly<Record<string, ArtifactDescriptor>>,
+): string | undefined {
+  const artifact = record?.artifact;
+  const path =
+    artifact !== null && typeof artifact === 'object' && 'path' in artifact
+      ? (artifact as { readonly path?: unknown }).path
+      : undefined;
+  if (typeof path === 'string') {
+    const match = Object.entries(descriptors).find(([, descriptor]) => descriptor.path === path);
+    if (match !== undefined) return match[0];
+  }
+  const shaderArtifacts = Object.entries(descriptors).filter(
+    ([, descriptor]) => descriptor.mediaType === 'text/wgsl',
+  );
+  return shaderArtifacts.length === 1 ? shaderArtifacts[0]?.[0] : undefined;
+}
+
+function materialRecordPath(descriptor: ArtifactDescriptor): string {
+  return `${descriptor.path}.record.json`;
+}
+
+function inlineMaterialArtifact(
+  record: Record<string, unknown> | undefined,
+): MaterialPublication['artifact'] | undefined {
+  const artifact = record?.artifact;
+  if (artifact === null || typeof artifact !== 'object' || Array.isArray(artifact)) {
+    return undefined;
+  }
+  const bytes = (artifact as { readonly bytes?: unknown }).bytes;
+  const normalizedBytes =
+    bytes instanceof Uint8Array
+      ? new Uint8Array(bytes)
+      : Array.isArray(bytes) &&
+          bytes.every((byte) => Number.isInteger(byte) && byte >= 0 && byte <= 255)
+        ? Uint8Array.from(bytes)
+        : undefined;
+  if (normalizedBytes === undefined) return undefined;
+  const digest = (artifact as { readonly digest?: unknown }).digest;
+  return {
+    bytes: normalizedBytes,
+    ...(typeof digest === 'string' ? { digest } : {}),
+  };
+}
+
+async function loadMaterialPublicationByGuid(
+  registry: AssetRegistry,
+  request: MaterialLoadRequest,
+): Promise<MaterialPublication | undefined> {
+  const parsedGuid = AssetGuid.parse(request.guid);
+  if (!parsedGuid.ok) return undefined;
+  const entry = await resolveCatalogEntry(registry, request.guid.toLowerCase());
+  if (entry === undefined) return undefined;
+  let pack = registry.packFileCache.get(entry.packageUrl);
+  if (pack === undefined) {
+    const fetched = await fetchAndCachePackFile(
+      registry,
+      entry.packageUrl,
+      request.guid.toLowerCase(),
+    );
+    if (!fetched.ok) return undefined;
+    pack = registry.packFileCache.get(entry.packageUrl);
+  }
+  const asset = pack?.assets.find(
+    (candidate) => candidate.guid.toLowerCase() === request.guid.toLowerCase(),
+  );
+  if (asset === undefined || asset.kind !== 'material') return undefined;
+  const record = cookedRecordFromPayload(asset.payload);
+  const recordObject =
+    record !== undefined && typeof record === 'object' && record !== null
+      ? (record as Record<string, unknown>)
+      : undefined;
+  const artifactKey = materialArtifactKey(recordObject, asset.artifacts ?? {});
+  if (artifactKey === undefined) {
+    const inlineArtifact = inlineMaterialArtifact(recordObject);
+    if (inlineArtifact !== undefined) {
+      return {
+        guid: request.guid,
+        record,
+        artifact: inlineArtifact,
+      };
+    }
+    return {
+      guid: request.guid,
+      record,
+      artifactError: {
+        code: 'asset-artifact-missing',
+        expected: 'a published material artifact descriptor',
+      },
+    };
+  }
+  const descriptor = asset.artifacts?.[artifactKey];
+  if (descriptor === undefined) {
+    return {
+      guid: request.guid,
+      record,
+      artifactError: {
+        code: 'asset-artifact-missing',
+        expected: `artifact descriptor '${artifactKey}'`,
+      },
+    };
+  }
+  let publicationRecord = record;
+  if (publicationRecord === undefined) {
+    const recordArtifact = await readArtifact({
+      packageUrl: entry.packageUrl,
+      guid: request.guid,
+      artifactKey: `${artifactKey}.record`,
+      descriptor: {
+        path: materialRecordPath(descriptor),
+        mediaType: 'application/json',
+      },
+    });
+    if (!recordArtifact.ok) return undefined;
+    try {
+      publicationRecord = JSON.parse(new TextDecoder().decode(recordArtifact.value));
+    } catch {
+      publicationRecord = null;
+    }
+  }
+  const artifactCacheKey = `${entry.packageUrl}\0${request.guid.toLowerCase()}\0${artifactKey}`;
+  const artifact = await registry.artifactCache.read(artifactCacheKey, () =>
+    readArtifact({
+      packageUrl: entry.packageUrl,
+      guid: request.guid,
+      artifactKey,
+      descriptor,
+    }),
+  );
+  if (!artifact.ok) {
+    if (artifact.error.code === 'asset-artifact-missing') {
+      return {
+        guid: request.guid,
+        record: publicationRecord,
+        artifactError: {
+          code: artifact.error.code,
+          expected: artifact.error.expected,
+          actual: artifact.error.detail.observed,
+        },
+      };
+    }
+    if (artifact.error.code === 'asset-artifact-integrity-mismatch') {
+      return {
+        guid: request.guid,
+        record: publicationRecord,
+        artifactError: {
+          code: artifact.error.code,
+          expected: artifact.error.expected,
+          actual: artifact.error.detail.observed,
+        },
+      };
+    }
+    return {
+      guid: request.guid,
+      record: publicationRecord,
+      artifactError: {
+        code: 'asset-artifact-missing',
+        expected: artifact.error.expected,
+        actual: artifact.error.detail.observed,
+      },
+    };
+  }
+  return {
+    guid: request.guid,
+    record: publicationRecord,
+    artifact: {
+      bytes: artifact.value,
+    },
+  };
+}
+
+export async function loadMaterialReadyByGuid(
+  registry: AssetRegistry,
+  request: MaterialLoadRequest,
+): Promise<MaterialReady | MaterialLoadError> {
+  const publication = await loadMaterialPublicationByGuid(registry, request);
+  return loadMaterialReadyPublication(registry, request, publication);
+}
+
+function publicationSpecializationKey(publication: MaterialPublication | undefined): string {
+  const record = publication?.record;
+  if (record === null || typeof record !== 'object') return '';
+  const specializationKey = (record as { readonly specializationKey?: unknown }).specializationKey;
+  return typeof specializationKey === 'string' ? specializationKey : '';
+}
+
+async function loadMaterialReadyPublication(
+  registry: AssetRegistry,
+  request: MaterialLoadRequest,
+  publication: MaterialPublication | undefined,
+): Promise<MaterialReady | MaterialLoadError> {
+  const loader = createMaterialLoader({
+    loadPublication: async () => publication,
+    loadReference: async (guid) => {
+      const parsed = AssetGuid.parse(guid);
+      if (!parsed.ok) return true;
+      const result = await loadByGuid(registry, parsed.value);
+      return result.ok;
+    },
+  });
+  const readiness = await loader.load(request);
+  registry.recordMaterialReadiness(request.guid, readiness);
+  return readiness;
+}
+
+async function loadByGuidInternal<T = Asset>(
+  registry: AssetRegistry,
+  guid: AssetGuid,
+  parentContext:
+    | {
+        sceneEntityId?: number;
+        componentField?: string;
+      }
+    | undefined,
+  ancestry: ReadonlySet<string>,
+): Promise<Result<T, AssetError | ImageError | RhiError>> {
+  const guidKey = AssetGuid.format(guid).toLowerCase();
+
+  // feat-20260614 M8 (D-17): the registry catalogues GUID -> payload and
+  // returns the PAYLOAD (never a handle). Fast path: already catalogued
+  // (covers dev catalog() + prod cached repeat calls).
+  const existing = registry.assetCatalog.get(guidKey);
+  if (existing !== undefined) {
+    const state = registry.loadState.get(guidKey);
+    if (state?.status === 'provisional') {
+      // A provisional value is only a legal bridge for a true SCC back-edge.
+      // A sibling or unrelated concurrent load must await its owning promise;
+      // otherwise the parent reaches promoteReady while the dependency is
+      // still provisional and reports a spurious public-readiness failure.
+      if (ancestry.has(guidKey)) {
+        const provisional = registry.loadState.getProvisional<T>(guidKey);
+        if (provisional !== undefined) return ok(provisional);
+      } else {
+        const inFlight = registry.inFlight.get(guidKey);
+        if (inFlight !== undefined) {
+          return inFlight as Promise<Result<T, AssetError | ImageError | RhiError>>;
+        }
+      }
+      return err(
+        new AssetError({
+          code: 'asset-parse-failed',
+          expected: `GUID ${guidKey} to be promoted to Ready before public load`,
+          hint: 'wait for the active load to finish or retry after the referenced assets are ready',
+        }),
+      );
+    }
+    if (state?.status === 'ready' || (state === undefined && registry.packIndexUrl === undefined)) {
+      const ready = registry.loadState.getReady<T>(guidKey);
+      if (ready !== undefined) return ok(ready);
+      if (state === undefined) return ok(existing.payload as T);
+    }
+  }
+
+  // In-flight dedup (D-5 / B-10): if another call is already loading this
+  // GUID, return that same Promise — covers (a) concurrent same-GUID calls
+  // and (b) cycle A→B→A termination (B reaches A's in-flight entry).
+  const inFlightPromise = registry.inFlight.get(guidKey);
+  if (inFlightPromise !== undefined) {
+    return inFlightPromise as Promise<Result<T, AssetError | ImageError | RhiError>>;
+  }
+
+  // Prod fetch path: only enabled when packIndexUrl is configured.
+  if (registry.packIndexUrl !== undefined && typeof globalThis.fetch === 'function') {
+    // F22: capture generation snapshot at Promise creation time so the
+    // resolve path can detect whether invalidate/invalidateAll was called
+    // while the fetch was in flight.
+    const genAtStart = registry.generations.get(guidKey) ?? 0;
+    const globalGenAtStart = registry.globalGeneration;
+
+    const promise = (async () => {
+      const result = await loadByGuidProd<T>(registry, guid, guidKey, parentContext, ancestry);
+      // F22: if the generation counters changed since the Promise was
+      // created, discard the result -- the asset was invalidated.
+      if (
+        genAtStart !== (registry.generations.get(guidKey) ?? 0) ||
+        globalGenAtStart !== registry.globalGeneration
+      ) {
+        registry.assetCatalog.delete(guidKey);
+        registry.loadState.remove(guidKey);
+        return err(
+          new AssetError({
+            code: 'asset-invalidated',
+            expected: `GUID ${guidKey} was invalidated during load`,
+            hint: ASSET_ERROR_HINTS['asset-invalidated'],
+          }),
+        ) as Result<T, AssetError | ImageError | RhiError>;
+      }
+      return result;
+    })();
+    registry.inFlight.set(guidKey, promise);
+    try {
+      return await promise;
+    } finally {
+      if (registry.inFlight.get(guidKey) === promise) registry.inFlight.delete(guidKey);
+    }
+  }
+
+  // Dev / fallback: synchronous catalogue miss (no network).
+  return Promise.resolve(
+    err(
+      new AssetError({
+        code: 'asset-not-found',
+        expected: `GUID ${guidKey} catalogued in AssetRegistry`,
+        hint: ASSET_ERROR_HINTS['asset-not-found'],
+      }),
+    ),
+  );
+}
+
+/**
+ * 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 async function loadFromUpstreamEntry<T = Asset>(
+  registry: AssetRegistry,
+  guidKey: string,
+  entry: {
+    packageUrl: string;
+    kind: string;
+    name?: string;
+    metadata?: ImageMetadata | undefined;
+  },
+): Promise<Result<T, AssetError | ImageError | RhiError>> {
+  const loader = registry.loaders.get(entry.kind);
+  if (loader === undefined) {
+    return err(
+      new AssetError({
+        code: 'loader-not-registered',
+        expected: `a loader registered for kind '${entry.kind}'`,
+        hint: ASSET_ERROR_HINTS['loader-not-registered'],
+        detail: { kind: entry.kind, registeredKinds: registry.loaders.registeredKinds() },
+      }),
+    );
+  }
+  const out = loader.load({ ...entry, guidKey }, undefined, makeLoadContext(registry));
+  // Upstream-branch loaders are async (Promise<LoaderAsyncResult>).
+  const result = (await out) as LoaderAsyncResult;
+  if (!result.ok) {
+    return err(result.error as AssetError | ImageError | RhiError);
+  }
+  const guid = AssetGuid.parse(guidKey);
+  if (!guid.ok) {
+    return err(
+      new AssetError({
+        code: 'asset-parse-failed',
+        expected: `valid GUID ${guidKey}`,
+        hint: ASSET_ERROR_HINTS['asset-parse-failed'],
+      }),
+    );
+  }
+  return registry.catalog(guid.value, result.value) as 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 async function loadByGuidProd<T = Asset>(
+  registry: AssetRegistry,
+  guid: AssetGuid,
+  guidKey: string,
+  parentContext?: {
+    sceneEntityId?: number;
+    componentField?: string;
+  },
+  ancestry: ReadonlySet<string> = new Set(),
+): Promise<Result<T, AssetError | ImageError | RhiError>> {
+  // feat-20260603-asset-import-loader-injection M4 / w31 (AC-19 lazy iron law):
+  // wrap the DDC fetch + load path so a DDC miss can be routed through the
+  // injected ImportTransport (studio form) or fail-fast with
+  // `asset-not-imported` (shipped form, AC-22). The load path after a
+  // successful DDC resolve is identical in both forms -- zero branches on
+  // `registry.importTransport` (AC-23 key invariant).
+  //
+  // A DDC miss is: (a) the GUID is absent from the catalog, OR (b) the
+  // `.pack.json` fetch returns `asset-not-found` / `asset-fetch-failed`.
+  // In case (a) the transport is probed first (the pack-index may have been
+  // built before the asset was imported); in case (b) the transport is the
+  // only fallback (the pack file is genuinely missing).
+
+  const entry = await resolveCatalogEntry(registry, guidKey);
+  if (entry !== undefined) {
+    const projection = resolveRuntimeProjection(guidKey, entry);
+    if (!projection.ok) return projection;
+    if (projection.value?.lifecycle !== undefined && projection.value.lifecycle !== 'current') {
+      return transportOrFail<T>(registry, guid, guidKey, 'asset-not-imported');
+    }
+    // Catalog hit: try the DDC load path.
+    const result = await ddcLoad<T>(registry, guid, guidKey, entry, parentContext, ancestry);
+    if (result.ok) return result;
+    // DDC miss: only route through transport when the error indicates a
+    // missing pack file (not a parse / validation failure inside the pack) or
+    // an unimported texture source (feat-20260604 M2 / D-1: import-on-demand).
+    // `texture-source-not-imported` is an AssetError, so it passes the
+    // `instanceof AssetError` guard naturally. `image-decode-failed` is an
+    // ImageError (a genuinely corrupt imported .bin) -- it fails the guard and
+    // is therefore never transport-eligible (Risk-1), so a real decode
+    // failure is never silently lazy-imported.
+    const ddcError = result.error;
+    const transportEligible =
+      ddcError instanceof AssetError &&
+      (ddcError.code === 'asset-not-found' ||
+        ddcError.code === 'asset-fetch-failed' ||
+        ddcError.code === 'texture-source-not-imported' ||
+        // perf-20260706: the raw-container fail-fast (mesh/material/scene whose
+        // packageUrl is still a .glb/.gltf/.fbx) surfaces source-not-imported;
+        // it is transport-eligible so the import runs once and rewrites the row
+        // to .bin/.pack.json (the shipped form, with no transport, fails fast).
+        // Distinct from the generic asset-not-imported, which must stay
+        // NON-eligible so the parent-missing breadcrumb is never masked.
+        ddcError.code === 'source-not-imported');
+    if (transportEligible) {
+      return transportOrFail<T>(registry, guid, guidKey, ddcError.code);
+    }
+    return result;
+  }
+
+  // Catalog miss: the GUID is not in the pack-index. In the studio form the
+  // import transport can lazily create the missing DDC.
+  return transportOrFail<T>(registry, guid, guidKey, 'asset-not-found');
+}
+
+/**
+ * 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 async function resolveCatalogEntry(
+  registry: AssetRegistry,
+  guidKey: string,
+): Promise<
+  | {
+      packageUrl: string;
+      kind: string;
+      name?: string;
+      metadata?: ImageMetadata | undefined;
+      compression?: AssetCompression;
+    }
+  | undefined
+> {
+  const key = guidKey.toLowerCase();
+  // Re-fetch the pack-index when it has never been fetched (=== undefined) OR
+  // when the cached Map lacks this GUID. The miss case covers invalidate(guid)
+  // round-2 M-A, which deletes the per-GUID index entry (targeted, bystanders
+  // survive) without nuking the whole Map to undefined: the next loadByGuid
+  // must re-consult the source so the GUID re-resolves and its freshly-cleared
+  // body cache re-fetches. A genuinely absent GUID re-fetches once then still
+  // misses, falling through to the transport / asset-not-found path as before.
+  if (registry.packIndexCache === undefined || !registry.packIndexCache.has(key)) {
+    const catalogResult = await fetchPackIndex(registry);
+    if (!catalogResult.ok) {
+      // Keep packIndexCache === undefined so next resolveCatalogEntry re-enters
+      // the fetch path instead of short-circuiting on an empty (polluted) cache.
+      if (registry.packIndexCache === undefined) return undefined;
+    } else {
+      registry.packIndexCache = catalogResult.value;
+      registerPackagesFromIndex(registry, registry.packIndexCache);
+    }
+  }
+  return registry.packIndexCache?.get(key);
+}
+
+/**
+ * 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 function registerPackagesFromIndex(
+  registry: AssetRegistry,
+  catalog: Map<
+    string,
+    {
+      packageUrl: string;
+      name?: string;
+      sourcePath?: string;
+      subject?: CatalogSubject;
+    }
+  >,
+): void {
+  const byPath = new Map<string, { guids: string[]; names: Map<string, string> }>();
+  for (const [guidKey, entry] of catalog) {
+    // Imported outputs are published under generated DDC/package URLs, but
+    // their stable package identity is the authored source. Keeping that
+    // source path here preserves `sky.hdr` (and equivalent source names) for
+    // single-asset lazy imports; authored internal packages retain their
+    // package URL semantics.
+    const packagePath =
+      entry.subject === 'imported-output' && entry.sourcePath !== undefined
+        ? entry.sourcePath
+        : entry.packageUrl;
+    let group = byPath.get(packagePath);
+    if (group === undefined) {
+      group = { guids: [], names: new Map() };
+      byPath.set(packagePath, group);
+    }
+    group.guids.push(guidKey);
+    if (entry.name !== undefined) group.names.set(guidKey, entry.name);
+  }
+  for (const [path, group] of byPath) {
+    registry._registerPackage(path, group.guids, group.names);
+  }
+}
+
+/**
+ * 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 async 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> = new Set(),
+): Promise<Result<T, AssetError | ImageError | RhiError>> {
+  if (typeof entry.packageUrl !== 'string' || entry.packageUrl.length === 0) {
+    return err(
+      new AssetError({
+        code: 'asset-not-imported',
+        expected: `catalog entry for GUID ${guidKey} to contain a packageUrl locator`,
+        hint: ASSET_ERROR_HINTS['asset-not-imported'],
+      }),
+    );
+  }
+  const packResult = await loadPackV2Asset(registry, guidKey, entry.packageUrl);
+  if (packResult === undefined) {
+    return err(
+      new AssetError({
+        code: 'asset-parse-failed',
+        expected: `Pack v2 package for GUID ${guidKey}`,
+        hint: 'legacy top-level asset payloads are not accepted',
+      }),
+    );
+  }
+  if (!packResult.ok) {
+    return packResult as Result<T, AssetError>;
+  }
+
+  const asset = packResult.value.asset;
+  // feat-20260622 M4 / w12: project the pack-entry refs[] (GUID strings) into
+  // AssetRef[] for the envelope. The on-disk pack.json refs[] carries only
+  // GUID strings (sourceField / sceneEntityId are stripped at the
+  // serialization boundary, w7 D-10), so prod-loaded edges have no per-entity
+  // metadata — the scene breadcrumb fallback (buildSceneChildContext) still
+  // walks the payload for entity/field detail. Dev-server register paths that
+  // carry rich AssetRef[] keep their edge metadata end-to-end.
+  const packRefs: readonly AssetRef[] = packResult.value.refs.map((g) => ({ guid: g }));
+
+  // feat-20260622 M5 / w17 (D-8, R5): the former material parent preload
+  // "Path B" (an independent early-return that loaded the parent BEFORE the
+  // unified for-loop and carried the precise breadcrumb hint `loading parent
+  // material X for child Y`) is folded into the unified envelope.refs
+  // for-loop. The parent GUID already rides on the material envelope.refs
+  // (gltf-importer w5 writes it; the on-disk pack refs[] carries it as a
+  // GUID string -> packRefs above projects it), so the unified for-loop
+  // recurses on it like any other edge. Here we only resolve the parent
+  // GUID -> AssetGuid and stamp `parent` onto the asset payload (the
+  // renderer-facing field read by walkMaterialPassesOverSharedRefs); the
+  // parent EDGE load + the `loading parent material X for child Y` breadcrumb
+  // + the not-a-material guard all move into the for-loop's
+  // sourceField.fieldName==='parent' / parent-edge branch below. No early
+  // return: the material registers (register-before-recurse) and its parent
+  // edge loads through the same unified path as texture / scene edges.
+  let assetToRegister: Asset = asset;
+  let parentGuidKey: string | undefined;
+  if (
+    asset.kind === 'material' &&
+    'parentGuid' in (asset as unknown as Record<string, unknown>) &&
+    typeof (asset as unknown as Record<string, unknown>).parentGuid === 'string'
+  ) {
+    const parentGuidStr = (asset as unknown as MaterialAsset & { parentGuid: string }).parentGuid;
+    const parentGuid = AssetGuid.parse(parentGuidStr);
+    if (!parentGuid.ok) {
+      return err(
+        new AssetError({
+          code: 'asset-parse-failed',
+          expected: `valid parent GUID for child ${guidKey}`,
+          hint: `parent GUID '${parentGuidStr}' is not a valid UUID format`,
+        }),
+      );
+    }
+    parentGuidKey = parentGuidStr.toLowerCase();
+    const matAsset = asset as unknown as MaterialAsset & { parentGuid?: string };
+    const passes = matAsset.passes;
+    const values = matAsset.values;
+    assetToRegister = {
+      kind: 'material',
+      ...(passes !== undefined ? { passes } : {}),
+      ...(values !== undefined ? { values } : {}),
+      parent: parentGuid.value,
+    };
+  }
+
+  registry.loadState.begin(
+    guidKey,
+    packRefs.map((ref) => ref.guid),
+  );
+
+  // The provisional record lets cycle back-edges terminate internally while
+  // lookup()/inspect() remain limited to the ready domain.
+  // tweak-20260609 M1: catalogue the asset BEFORE recursing into its
+  // sub-assets. This way, when a cycle (A→B→A) reaches back to A during
+  // B's recursion, A is already catalogued (fast-path hit) and the inFlight
+  // Promise for A can be fulfilled. The inFlight entry in `loadByGuid` is
+  // the second line of defense — it catches concurrent same-GUID calls
+  // before the asset is catalogued.
+  const registerResult = registerParsedAsset<T>(registry, guid, assetToRegister, guidKey, packRefs);
+  if (!registerResult.ok) {
+    purgeFailedLoad(registry, guidKey, entry.packageUrl, registerResult.error);
+    return registerResult;
+  }
+  const registeredPayload = registerResult.value;
+  registry.loadState.resolveAsset(guidKey, registeredPayload);
+
+  // feat-20260622 M4 / w12 (D-5): the recursion source is the just-catalogued
+  // envelope's refs[]. The for-loop is kind-agnostic
+  // — every AssetRef carries the GUID to recurse on; scene/material/skin all
+  // flow through this one loop. Each edge optionally carries sourceField /
+  // sceneEntityId; when present the childContext is built straight from the
+  // edge, otherwise the scene branch falls back to walking the payload
+  // (buildSceneChildContext) so the prod-path breadcrumb keeps its entity /
+  // field detail (on-disk refs[] are GUID-string-only, w7 D-10).
+  const envelope = registry.assetCatalog.get(guidKey);
+  const refs: readonly AssetRef[] = envelope?.refs ?? [];
+  if (refs.length > 0) {
+    const subResults = await Promise.all(
+      refs.map((ref) => {
+        const refGuidKey = ref.guid.toLowerCase();
+        const parsedRef = AssetGuid.parse(ref.guid);
+        if (!parsedRef.ok) {
+          return Promise.resolve({
+            guidKey: refGuidKey,
+            result: err(
+              new AssetError({
+                code: 'asset-parse-failed',
+                expected: `valid sub-asset GUID referenced by ${asset.kind} ${guidKey}`,
+                hint: `refs[] entry '${ref.guid}' is not a valid UUID format`,
+              }),
+            ) as Result<Asset, AssetError | ImageError | RhiError>,
+            childContext: undefined as
+              | {
+                  sceneEntityId?: number;
+                  componentField?: string;
+                  sourceField?: {
+                    componentName?: string;
+                    fieldName: string;
+                    arrayIndex?: number;
+                  };
+                }
+              | undefined,
+            isParentEdge: false,
+            edge: ref,
+          });
+        }
+        let childContext:
+          | {
+              sceneEntityId?: number;
+              componentField?: string;
+              sourceField?: {
+                componentName?: string;
+                fieldName: string;
+                arrayIndex?: number;
+              };
+            }
+          | undefined;
+        if (ref.sceneEntityId !== undefined || ref.sourceField !== undefined) {
+          childContext = {};
+          if (ref.sceneEntityId !== undefined) childContext.sceneEntityId = ref.sceneEntityId;
+          if (ref.sourceField?.fieldName !== undefined) {
+            childContext.componentField =
+              (ref.sourceField.componentName !== undefined
+                ? `${ref.sourceField.componentName}.`
+                : '') +
+              ref.sourceField.fieldName +
+              (ref.sourceField.arrayIndex !== undefined ? `[${ref.sourceField.arrayIndex}]` : '');
+            childContext.sourceField = ref.sourceField;
+          }
+        } else if (asset.kind === 'scene') {
+          childContext = buildSceneChildContext(registry, asset, refGuidKey, guidKey);
+        }
+        // feat-20260622 M5 / w17 (D-8): the material parent edge. Identify it
+        // by either the rich dev-path marker (sourceField.fieldName==='parent')
+        // or the prod-path GUID match against the resolved parent GUID
+        // (on-disk refs[] strip sourceField, w7 D-10, so the GUID is the only
+        // signal). The parent edge carries the distinct `loading parent
+        // material X for child Y` breadcrumb (AC-10) instead of the generic
+        // buildBreadcrumbHint form, and is guarded to be a material.
+        const isParentEdge =
+          asset.kind === 'material' &&
+          (ref.sourceField?.fieldName === 'parent' ||
+            (parentGuidKey !== undefined && refGuidKey === parentGuidKey));
+        const childAncestry = new Set(ancestry);
+        childAncestry.add(guidKey);
+        return loadByGuidInternal(
+          registry,
+          parsedRef.value,
+          childContext ?? parentContext,
+          childAncestry,
+        ).then((r) => ({
+          guidKey: refGuidKey,
+          result: r,
+          childContext,
+          isParentEdge,
+          edge: ref,
+        }));
+      }),
+    );
+
+    // If any sub-asset load failed, propagate the first error enriched with
+    // parent breadcrumb.
+    for (const {
+      guidKey: subGuidKey,
+      result: subResult,
+      childContext: subChildContext,
+      isParentEdge,
+      edge: subEdge,
+    } of subResults) {
+      // feat-20260622 M5 / w17: parent-edge breadcrumb migration (former Path
+      // B). On load failure, carry the distinct `loading parent material X for
+      // child Y: <subErr.hint>` form (AC-10 downstream literal assertion) and
+      // propagate the parent's own error code verbatim.
+      if (isParentEdge && !subResult.ok) {
+        const subErr = subResult.error;
+        const code: AssetErrorCode =
+          subErr instanceof AssetError ? subErr.code : 'asset-parse-failed';
+        purgeFailedLoad(registry, guidKey, entry.packageUrl, subErr);
+        return err(
+          new AssetError({
+            code,
+            expected: subErr.expected,
+            hint: `loading parent material ${subGuidKey} for child ${guidKey}: ${
+              subErr.hint ?? ''
+            }`,
+            ...(subErr instanceof AssetError && subErr.detail !== undefined
+              ? { detail: subErr.detail as Readonly<AssetErrorDetail> }
+              : {}),
+          }),
+        );
+      }
+      // feat-20260622 M5 / w17: parent edge loaded but is not a material —
+      // same guard the former Path B carried, with the matching breadcrumb.
+      if (isParentEdge && subResult.ok && subResult.value?.kind !== 'material') {
+        const error = new AssetError({
+          code: 'asset-parse-failed',
+          expected: `parent GUID ${subGuidKey} to reference a MaterialAsset`,
+          hint: `loading parent material ${subGuidKey} for child ${guidKey}: referenced asset is ${subResult.value?.kind ?? 'unknown'}, not 'material'`,
+        });
+        purgeFailedLoad(registry, guidKey, entry.packageUrl, error);
+        return err(error);
+      }
+      if (!subResult.ok) {
+        const subErr = subResult.error;
+        const breadcrumb = buildBreadcrumbHint(
+          guidKey,
+          asset.kind,
+          subGuidKey,
+          subChildContext ?? parentContext,
+        );
+        const code: AssetErrorCode =
+          subErr instanceof AssetError ? subErr.code : 'asset-fetch-failed';
+        // feat-20260622 verify r1: deliver the breadcrumb provenance in
+        // structured form so AI users locate the broken edge by property
+        // access (charter P3), not by parsing the hint. Preserve the sub
+        // error's own detail when it carries one (more specific); otherwise
+        // expose the edge provenance (entity / source field).
+        // Prefer the rich dev-path edge provenance; on the prod path the
+        // on-disk edge is GUID-only (sourceField stripped, w7 D-10), so fall
+        // back to the entity-walk-recovered provenance carried on the
+        // childContext (verify r1).
+        const provEntityId = subEdge?.sceneEntityId ?? subChildContext?.sceneEntityId;
+        const provSourceField = subEdge?.sourceField ?? subChildContext?.sourceField;
+        const breadcrumbDetail: Readonly<AssetErrorDetail> = {
+          referencedByGuid: guidKey,
+          referencedByKind: asset.kind,
+          subAssetGuid: subGuidKey,
+          ...(provEntityId !== undefined ? { sceneEntityId: provEntityId } : {}),
+          ...(provSourceField !== undefined ? { sourceField: provSourceField } : {}),
+        };
+        const detail: Readonly<AssetErrorDetail> =
+          subErr instanceof AssetError && subErr.detail !== undefined
+            ? subErr.detail
+            : breadcrumbDetail;
+        purgeFailedLoad(registry, guidKey, entry.packageUrl, subErr);
+        return err(
+          new AssetError({
+            code,
+            expected: subErr.expected,
+            hint: `${breadcrumb} / ${subErr.hint ?? ''}`,
+            detail,
+          }),
+        );
+      }
+    }
+  }
+
+  // A Mesh default is a typed dependency, not merely a loadable GUID. This
+  // check deliberately lives outside the `refs.length > 0` branch: a producer
+  // that puts a default GUID in the payload but omits the matching refs[] edge
+  // must fail closed instead of publishing a Mesh whose dependency closure is
+  // incomplete.
+  if (asset.kind === 'mesh') {
+    const directRefGuids = new Set(refs.map((ref) => ref.guid.toLowerCase()));
+    const slots = (asset as MeshAsset).materialSlots;
+    for (let slotIndex = 0; slotIndex < slots.length; slotIndex++) {
+      const slot = slots[slotIndex];
+      if (slot?.defaultMaterial === undefined) continue;
+      const defaultMaterialGuid = AssetGuid.format(slot.defaultMaterial).toLowerCase();
+      const loaded = directRefGuids.has(defaultMaterialGuid)
+        ? registry.assetCatalog.get(defaultMaterialGuid)?.payload
+        : undefined;
+      if (loaded?.kind === 'material') continue;
+      const actualKind = directRefGuids.has(defaultMaterialGuid)
+        ? (loaded?.kind ?? 'missing')
+        : 'missing-ref-edge';
+      const error = new AssetError({
+        code: 'asset-parse-failed',
+        expected: `mesh ${guidKey} materialSlots[${slotIndex}] (${slot.slotName}) default ${defaultMaterialGuid} to reference a MaterialAsset`,
+        hint: `recook mesh ${guidKey}; slot ${slotIndex} '${slot.slotName}' resolves to ${actualKind}, not 'material'`,
+        detail: {
+          meshAssetGuid: guidKey,
+          slotIndex,
+          slotName: slot.slotName,
+          defaultMaterialGuid,
+          actualKind,
+        },
+      });
+      purgeFailedLoad(registry, guidKey, entry.packageUrl, error);
+      return err(error);
+    }
+  }
+
+  registry.loadState.promoteReady(guidKey);
+  if (registry.loadState.getReady(guidKey) === undefined) {
+    const error = new AssetError({
+      code: 'asset-parse-failed',
+      expected: `GUID ${guidKey} and all referenced assets to be public-ready`,
+      hint: 'retry after every referenced GUID has loaded successfully',
+    });
+    purgeFailedLoad(registry, guidKey, entry.packageUrl, error);
+    return err(error);
+  }
+  const registeredAsset = registeredPayload as Asset;
+  if (registeredAsset.kind === 'material' && !isEngineMaterial(registeredAsset)) {
+    const publication = await loadMaterialPublicationByGuid(registry, {
+      guid: guidKey,
+      specializationKey: '',
+    });
+    await loadMaterialReadyPublication(
+      registry,
+      {
+        guid: guidKey,
+        specializationKey: publicationSpecializationKey(publication),
+      },
+      publication,
+    );
+  }
+  return ok(registeredPayload as T);
+}
+
+async function loadPackV2Asset(
+  registry: AssetRegistry,
+  guidKey: string,
+  packageUrl: string,
+): Promise<
+  | Result<
+      {
+        asset: Asset;
+        refs: readonly string[];
+      },
+      AssetError
+    >
+  | undefined
+> {
+  const cached = registry.packFileCache.get(packageUrl);
+  if (cached === undefined) {
+    const inFlight = registry.packFileInFlight.get(packageUrl);
+    if (inFlight !== undefined) await inFlight.catch(() => undefined);
+    const fetched =
+      registry.packFileCache.get(packageUrl) === undefined
+        ? await fetchAndCachePackFile(registry, packageUrl, guidKey)
+        : undefined;
+    if (registry.packFileCache.get(packageUrl) === undefined) {
+      if (fetched === undefined) {
+        return err(
+          new AssetError({
+            code: 'asset-fetch-failed',
+            expected: `pack file ${packageUrl} to be cached after its shared fetch`,
+            hint: ASSET_ERROR_HINTS['asset-fetch-failed'],
+          }),
+        );
+      }
+      return fetched as unknown as Result<{ asset: Asset; refs: readonly string[] }, AssetError>;
+    }
+  }
+  const pack = registry.packFileCache.get(packageUrl);
+  if (pack?.schemaVersion !== '2.0.0') return undefined;
+  const asset = pack.assets.find((candidate) => candidate.guid.toLowerCase() === guidKey);
+  if (asset === undefined) {
+    return err(
+      new AssetError({
+        code: 'asset-not-found',
+        expected: `GUID ${guidKey} present in Pack v2 package ${packageUrl}`,
+        hint: ASSET_ERROR_HINTS['asset-not-found'],
+      }),
+    );
+  }
+  const artifacts: Record<string, { descriptor: ArtifactDescriptor; bytes: Uint8Array }> = {};
+  for (const [artifactKey, descriptor] of Object.entries(asset.artifacts ?? {})) {
+    const cacheKey = `${packageUrl}\0${guidKey}\0${artifactKey}`;
+    const artifact = await registry.artifactCache.read(cacheKey, () =>
+      readArtifact({ packageUrl, guid: guidKey, artifactKey, descriptor }),
+    );
+    if (!artifact.ok)
+      return artifact as unknown as Result<{ asset: Asset; refs: readonly string[] }, AssetError>;
+    artifacts[artifactKey] = { descriptor, bytes: artifact.value };
+  }
+  const loaded = await registry.loaders.loadPack(
+    {
+      guid: guidKey,
+      kind: asset.kind,
+      payload: asset.payload,
+      refs: asset.refs ?? [],
+      artifacts,
+    },
+    makeLoadContext(registry),
+  );
+  if (!loaded.ok) return err(loaded.error as AssetError);
+  if (loaded.value === undefined || typeof loaded.value !== 'object') {
+    return err(
+      new AssetError({
+        code: 'asset-parse-failed',
+        expected: `loader '${asset.kind}' to return an asset payload`,
+        hint: 'register a loader that accepts the Pack v2 asset-local input',
+      }),
+    );
+  }
+  return ok({ asset: loaded.value as Asset, refs: asset.refs ?? [] });
+}
+
+function purgeFailedLoad(
+  registry: AssetRegistry,
+  guidKey: string,
+  packageUrl: string,
+  error: unknown,
+): void {
+  const doomed = registry.loadState.fail(guidKey, error);
+  for (const key of doomed) registry.assetCatalog.delete(key);
+  registry.packFileCache.delete(packageUrl);
+}
+
+/**
+ * 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 async function transportOrFail<T = Asset>(
+  registry: AssetRegistry,
+  guid: AssetGuid,
+  guidKey: string,
+  _missReason: AssetErrorCode,
+): Promise<Result<T, AssetError | ImageError | RhiError>> {
+  if (registry.importTransport === undefined) {
+    // shipped form: no transport wired -> fail fast, never degrade to
+    // runtime import (AC-22, charter P3 explicit failure).
+    return err(
+      new AssetError({
+        code: 'asset-not-imported',
+        expected: `GUID ${guidKey} to have been pre-imported at build time or to have an ImportTransport wired`,
+        hint: ASSET_ERROR_HINTS['asset-not-imported'],
+      }),
+    );
+  }
+
+  // studio form: request the transport to import this GUID on-the-fly.
+  // After a successful transport call the DDC is available; re-enter the
+  // catalog + DDC load path (the transport writes the DDC but does NOT
+  // register the asset — that's the Loader's job).
+  const transportResult = await registry.importTransport.fetchPack(
+    guidKey,
+    registry.runtimeBinding,
+  );
+  if (!transportResult.ok) {
+    return err(
+      new AssetError({
+        code: 'asset-not-imported',
+        expected: `import transport to fetch pack for GUID ${guidKey}`,
+        hint: ASSET_ERROR_HINTS['asset-not-imported'],
+      }),
+    );
+  }
+
+  // Patch ONLY the freshly imported rows into the catalog cache (per-asset
+  // incremental, the four-verb redesign 2026-06-06) instead of nuking the
+  // cache and re-fetching the whole pack-index. The transport returns the one
+  // imported entry (+ sub-asset siblings); each becomes / overwrites a cache
+  // row. This keeps 122 concurrent texture imports O(N) instead of O(N^2)
+  // whole-catalog re-fetches and never resets a sibling's imported row.
+  const importedEntries = 'entries' in transportResult ? transportResult.entries : undefined;
+  if (importedEntries !== undefined && importedEntries.length > 0) {
+    // F20: serialise packIndexCache writes through a per-cache Promise queue.
+    // The "check -> new Map -> set" block is not atomic across concurrent
+    // transportOrFail calls; chaining through the queue ensures each patch
+    // completes before the next starts, preventing new-Map overwrite races.
+    registry.packIndexCachePatchQueue = registry.packIndexCachePatchQueue.then(() => {
+      if (registry.packIndexCache === undefined) registry.packIndexCache = new Map();
+      for (const e of importedEntries) {
+        if (typeof e.packageUrl !== 'string' || e.packageUrl.length === 0) continue;
+        registry.packIndexCache.set(e.guid.toLowerCase(), {
+          packageUrl: resolveCatalogAssetUrl(registry, e.packageUrl),
+          kind: e.kind,
+          // Carry the transport's derived display name into the cache row.
+          // buildCatalog already resolves it (deriveAssetName: basename of the
+          // source for single-/no-storedName sub-assets), so a freshly imported
+          // GLB's 1000+ sub-assets show as "<file>.glb" in the Content Browser
+          // instead of blank. Dropping it here made listCatalog fall back to
+          // `entry.name ?? ''` — the whole-index re-read path (else branch) kept
+          // names, so only the incremental patch path was blank.
+          ...(e.name !== undefined ? { name: e.name } : {}),
+          // Carry refs on the incremental patch path too, else an asset
+          // imported via POST /__import shows missing dependency edges until
+          // the next full pack-index refresh (feat: listCatalog refs).
+          ...(e.refs !== undefined ? { refs: e.refs } : {}),
+          ...(e.packageId !== undefined ? { packageId: e.packageId } : {}),
+          ...(e.provenance !== undefined ? { provenance: e.provenance } : {}),
+          ...(e.revision !== undefined ? { revision: e.revision } : {}),
+          ...(e.authoring !== undefined ? { authoring: e.authoring } : {}),
+          ...(e.sourceKey !== undefined ? { sourceKey: e.sourceKey } : {}),
+          ...(e.sourceIndex !== undefined ? { sourceIndex: e.sourceIndex } : {}),
+          ...(e.relations !== undefined ? { relations: e.relations } : {}),
+          ...(e.diagnostics !== undefined ? { diagnostics: e.diagnostics } : {}),
+          // Carry sourcePath on the incremental patch path too (same red-line
+          // as refs above): an asset imported via POST /__import would
+          // otherwise expose no source-file path in listCatalog until the next
+          // full pack-index refresh, breaking editor CRUD sidecar lookup for
+          // freshly imported assets. `sourcePath` is a required PackIndexEntry
+          // field, so it is always present on the transport row.
+          ...(e.sourcePath !== undefined ? { sourcePath: e.sourcePath } : {}),
+        });
+      }
+    });
+    await registry.packIndexCachePatchQueue;
+  } else {
+    // No inline rows -- fall back to a full pack-index re-read so the freshly
+    // imported DDC entry is visible (legacy / non-row-returning transports).
+    registry.packIndexCache = undefined;
+  }
+  const entry = await resolveCatalogEntry(registry, guidKey);
+  if (entry === undefined) {
+    return err(
+      new AssetError({
+        code: 'asset-not-imported',
+        expected: `import transport to produce a catalog entry for GUID ${guidKey}`,
+        hint: ASSET_ERROR_HINTS['asset-not-imported'],
+      }),
+    );
+  }
+
+  // Re-enter the DDC load path (identical to the catalog-hit path).
+  return ddcLoad<T>(registry, guid, guidKey, entry);
+}
+
+/**
+ * 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 function registerParsedAsset<T = Asset>(
+  registry: AssetRegistry,
+  guid: AssetGuid,
+  asset: Asset,
+  _guidKey: string,
+  refs?: readonly AssetRef[],
+): Result<T, AssetError | ImageError | RhiError> {
+  // feat-20260614 M8 (D-17): catalogue the parsed payload under its GUID and
+  // return the PAYLOAD. `catalog` validates mesh stride + material passes and
+  // returns Result.err on failure (no throw), so the loadByGuid surface stays
+  // a consistent Result (charter P4 consistent abstraction).
+  //
+  // feat-20260622 M4 / w12 (D-9): the pack-entry refs[] ride onto the
+  // catalogued envelope here so the recursive core can read envelope.refs as
+  // its single recursion source.
+  return registry.catalog<T>(guid, asset as T, refs) as 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 async function fetchPackEntry(
+  _registry: AssetRegistry,
+  packageUrl: string,
+  guidKey: string,
+): Promise<
+  Result<{ kind: string; payload: Record<string, unknown>; refs?: string[] }, AssetError>
+> {
+  let raw: unknown;
+  try {
+    const res = await globalThis.fetch(packageUrl);
+    if (!res.ok) {
+      return err(
+        new AssetError({
+          code: 'asset-fetch-failed',
+          expected: `fetch(${packageUrl}) to return ok`,
+          hint: ASSET_ERROR_HINTS['asset-fetch-failed'],
+        }),
+      );
+    }
+    raw = (await res.json()) as unknown;
+  } catch {
+    return err(
+      new AssetError({
+        code: 'asset-fetch-failed',
+        expected: `fetch(${packageUrl}) to succeed`,
+        hint: ASSET_ERROR_HINTS['asset-fetch-failed'],
+      }),
+    );
+  }
+  const packFile = raw as {
+    assets?: Array<{
+      guid: string;
+      kind: string;
+      payload: Record<string, unknown>;
+      refs?: string[];
+    }>;
+  };
+  const assetEntry = (packFile.assets ?? []).find(
+    (a) => a.guid.toLowerCase() === guidKey.toLowerCase(),
+  );
+  if (assetEntry === undefined) {
+    return err(
+      new AssetError({
+        code: 'asset-not-found',
+        expected: `GUID ${guidKey} present in pack file ${packageUrl}`,
+        hint: ASSET_ERROR_HINTS['asset-not-found'],
+      }),
+    );
+  }
+  return ok({
+    kind: assetEntry.kind,
+    payload: assetEntry.payload,
+    ...(assetEntry.refs !== undefined ? { refs: assetEntry.refs } : {}),
+  });
+}
+
+/**
+ * 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 async function fetchPackFile(
+  registry: AssetRegistry,
+  packageUrl: string,
+  guidKey: string,
+  _kind: string,
+): Promise<Result<{ asset: Asset; refs: readonly string[] }, AssetError>> {
+  // ── cache hit ───────────────────────────────────────────────────────
+  const cached = registry.packFileCache.get(packageUrl);
+  if (cached !== undefined) {
+    const assetEntry = cached.assets.find((a) => a.guid.toLowerCase() === guidKey.toLowerCase());
+    if (assetEntry === undefined) {
+      return err(
+        new AssetError({
+          code: 'asset-not-found',
+          expected: `GUID ${guidKey} present in pack file ${packageUrl}`,
+          hint: ASSET_ERROR_HINTS['asset-not-found'],
+        }),
+      );
+    }
+    return parseAndReturnAsset(registry, assetEntry);
+  }
+
+  // ── in-flight dedup ─────────────────────────────────────────────────
+  const inFlight = registry.packFileInFlight.get(packageUrl);
+  if (inFlight !== undefined) {
+    try {
+      const packFile = await inFlight;
+      const assetEntry = packFile.assets.find(
+        (a) => a.guid.toLowerCase() === guidKey.toLowerCase(),
+      );
+      if (assetEntry === undefined) {
+        return err(
+          new AssetError({
+            code: 'asset-not-found',
+            expected: `GUID ${guidKey} present in pack file ${packageUrl}`,
+            hint: ASSET_ERROR_HINTS['asset-not-found'],
+          }),
+        );
+      }
+      return parseAndReturnAsset(registry, assetEntry);
+    } catch {
+      // In-flight promise rejected (network failure) — fall through to
+      // re-fetch. The in-flight entry was already cleaned by the
+      // catch block in the original miss path.
+    }
+  }
+
+  // ── miss: fetch + parse + cache ─────────────────────────────────────
+  return fetchAndCachePackFile(registry, packageUrl, guidKey);
+}
+
+/**
+ * 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 function parseAndReturnAsset(
+  registry: AssetRegistry,
+  assetEntry: {
+    kind: string;
+    payload: Record<string, unknown>;
+    refs?: string[];
+  },
+): Result<{ asset: Asset; refs: readonly string[] }, AssetError> {
+  const parsed = parseAssetPayload(registry, assetEntry.kind, assetEntry.payload, assetEntry.refs);
+  // F21: the scene loader returns its structured ParseErrorDetail inline via
+  // the LoaderOutput `{ ok: false, error }` arm, surfaced here through
+  // parseAssetPayload's return value -- no shared instance slot.
+  if (parsed !== undefined && typeof parsed === 'object' && 'ok' in parsed) {
+    const e = (parsed as { readonly ok: false; readonly error: ParseErrorDetail }).error;
+    return err(
+      new AssetError({
+        code: 'asset-parse-failed',
+        expected: `refs index ${e.index} within [0, ${e.refsLength})`,
+        detail: {
+          localId: e.localId,
+          component: e.component,
+          field: e.field,
+          index: e.index,
+          refsLength: e.refsLength,
+        },
+        hint:
+          `at node localId=${e.localId}, component=${e.component}, ` +
+          `field=${e.field}: index ${e.index} is out of bounds ` +
+          `(refs has ${e.refsLength} entries)`,
+      }),
+    );
+  }
+  if (parsed === undefined) {
+    return err(
+      new AssetError({
+        code: 'asset-parse-failed',
+        expected: `parseable asset payload for kind ${assetEntry.kind}`,
+        hint: ASSET_ERROR_HINTS['asset-parse-failed'],
+      }),
+    );
+  }
+  // feat-20260622 M4 / w12: surface the pack-entry refs[] (GUID-string
+  // projection) alongside the parsed payload so ddcLoad can store them on
+  // the catalogued envelope. The recursive core then reads envelope.refs
+  // as the single recursion source (D-5), never re-deriving them from
+  // the payload.
+  return ok({ asset: parsed as Asset, refs: assetEntry.refs ?? [] });
+}
+
+/**
+ * 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 async function fetchAndCachePackFile(
+  registry: AssetRegistry,
+  packageUrl: string,
+  guidKey: string,
+): Promise<Result<{ asset: Asset; refs: readonly string[] }, AssetError>> {
+  const fetchPromise = (async (): Promise<ParsedPackFile> => {
+    let raw: unknown;
+    try {
+      const res = await globalThis.fetch(packageUrl);
+      if (!res.ok) {
+        throw new AssetError({
+          code: 'asset-fetch-failed',
+          expected: `fetch(${packageUrl}) to return ok`,
+          hint: ASSET_ERROR_HINTS['asset-fetch-failed'],
+        });
+      }
+      raw = (await res.json()) as unknown;
+    } catch (e) {
+      if (e instanceof AssetError) throw e;
+      throw new AssetError({
+        code: 'asset-fetch-failed',
+        expected: `fetch(${packageUrl}) to succeed`,
+        hint: ASSET_ERROR_HINTS['asset-fetch-failed'],
+      });
+    }
+    // Shape guard: the dev-server / preview / 404 fallback can return
+    // index.html or an unrelated JSON body that satisfies res.ok but lacks
+    // the ParsedPackFile contract. Without this guard the downstream
+    // `packFile.assets.find` raises TypeError outside any AssetError
+    // branch, escapes as a process-level Unhandled Rejection, and drives
+    // vitest browser-project exit=1 even when every onerror-gate test
+    // assertion passes (feat-20260611 step-implement F-4).
+    if (
+      raw === null ||
+      typeof raw !== 'object' ||
+      !Array.isArray((raw as { assets?: unknown }).assets)
+    ) {
+      throw new AssetError({
+        code: 'asset-fetch-failed',
+        expected: `pack-file body at ${packageUrl} to be { assets: [...] }`,
+        hint: ASSET_ERROR_HINTS['asset-fetch-failed'],
+      });
+    }
+    return raw as ParsedPackFile;
+  })();
+
+  registry.packFileInFlight.set(packageUrl, fetchPromise);
+
+  try {
+    const packFile = await fetchPromise;
+    registry.packFileCache.set(packageUrl, packFile);
+    registry.packFileInFlight.delete(packageUrl);
+
+    const assetEntry = packFile.assets.find((a) => a.guid.toLowerCase() === guidKey.toLowerCase());
+    if (assetEntry === undefined) {
+      return err(
+        new AssetError({
+          code: 'asset-not-found',
+          expected: `GUID ${guidKey} present in pack file ${packageUrl}`,
+          hint: ASSET_ERROR_HINTS['asset-not-found'],
+        }),
+      );
+    }
+    return parseAndReturnAsset(registry, assetEntry);
+  } catch (e) {
+    registry.packFileInFlight.delete(packageUrl);
+    if (e instanceof AssetError) {
+      return err(e);
+    }
+    throw e;
+  }
+}
+
+/**
+ * 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 function parseAssetPayload(
+  registry: AssetRegistry,
+  kind: string,
+  payload: Record<string, unknown>,
+  refs?: string[],
+):
+  | Asset
+  | Record<string, unknown>
+  | undefined
+  | { readonly ok: false; readonly error: ParseErrorDetail } {
+  // feat-20260603-asset-import-loader-injection M1 / w4: dispatch on
+  // `kind` through the injected LoaderRegistry instead of a hardcoded
+  // `if (kind === ...)` chain (D-1 / AC-01). The seven inline pack-payload
+  // loaders parse synchronously; texture / font live on the upstream
+  // loadByGuidProd branch (w6) and are never reached here.
+  // feat-20260623 M2 / w5: unknown kinds pass through the raw payload so
+  // host-registered loaders can parse their own kind. The engine does not
+  // parse payloads it cannot match; parse responsibility is explicit on the
+  // missing loader (charter P3).
+  const loader = registry.loaders.get(kind);
+  if (loader === undefined) return { ...payload, kind };
+  const out = loader.load(payload, refs, makeLoadContext(registry));
+  // The inline pack-payload loaders are synchronous (`Asset | undefined`);
+  // the async texture / font loaders are dispatched from loadByGuidProd, not
+  // here. A Promise here would mean a misregistered loader -> treat as a
+  // parse miss rather than leaking a thenable into the sync return.
+  if (out !== undefined && typeof (out as { then?: unknown }).then === 'function') {
+    return undefined;
+  }
+  // F21: the scene loader returns { ok: false, error: ParseErrorDetail } for
+  // structured parse errors. Pass the error arm straight through the return
+  // value so the caller constructs a precise AssetError -- no instance slot.
+  if (out !== undefined && out !== null && typeof out === 'object' && 'ok' in out) {
+    return out as { readonly ok: false; readonly error: ParseErrorDetail };
+  }
+  return out as Asset | undefined;
+}
+
+/**
+ * Build the {@link LoadContext} passed to a loader's `load`.
+ * `fetchBinary` / `resolveRef` / `device` are wired for the async texture /
+ * font loaders (w6).
+ */
+export function makeLoadContext(registry: AssetRegistry): LoadContext {
+  return {
+    /**
+     * feat-20260706 M3 / w19: fetchBinary signature extended per D-2.
+     * `opts?.compression` triggers the single decompression gate (AC-02).
+     * 'zstd' → lazy-init codec decompressZstd · 'none' / undefined → pass-through.
+     * On decompression failure, the codec error is nested in asset-fetch-failed
+     * detail (D-8: runtime error union NOT extended).
+     */
+    fetchBinary: async (url: string, opts?: { readonly compression?: AssetCompression }) => {
+      try {
+        const res = await globalThis.fetch(url);
+        if (!res.ok) {
+          return {
+            ok: false as const,
+            error: new AssetError({
+              code: 'asset-fetch-failed',
+              expected: `fetch(${url}) to return ok`,
+              hint: ASSET_ERROR_HINTS['asset-fetch-failed'],
+            }),
+          };
+        }
+        const buf = await res.arrayBuffer();
+        let bytes: Uint8Array = new Uint8Array(buf);
+
+        // --- Decompression gate (AC-02: single gate inside fetchBinary) ---
+        if (opts?.compression === 'zstd') {
+          const { decompressZstd } = await import('@forgeax/engine-codec');
+          const decRes = await decompressZstd(bytes);
+          if (!decRes.ok) {
+            return {
+              ok: false as const,
+              error: new AssetError({
+                code: 'asset-parse-failed',
+                expected: `zstd decompression for ${url}`,
+                hint: `[${decRes.error.code}] ${decRes.error.hint}`,
+                detail: { sourcePath: url },
+              }),
+            };
+          }
+          bytes = new Uint8Array(
+            decRes.value.buffer,
+            decRes.value.byteOffset,
+            decRes.value.byteLength,
+          );
+        }
+        // compression === 'none' / undefined → E1 pass-through
+
+        return { ok: true as const, value: bytes };
+      } catch {
+        return {
+          ok: false as const,
+          error: new AssetError({
+            code: 'asset-fetch-failed',
+            expected: `fetch(${url}) to succeed`,
+            hint: ASSET_ERROR_HINTS['asset-fetch-failed'],
+          }),
+        };
+      }
+    },
+    resolveRef: async (guid: string) => {
+      const parsed = AssetGuid.parse(guid);
+      if (!parsed.ok) {
+        return { ok: false as const, error: parsed.error };
+      }
+      const r = await loadByGuid(registry, parsed.value);
+      if (!r.ok) return { ok: false as const, error: r.error };
+      // feat-20260614 M8 (D-19): resolveRef ensures the sub-asset is
+      // catalogued (recursive load). The numeric value is vestigial -- the
+      // registry mints no handles; callers store the GUID, not this number.
+      return { ok: true as const, value: 0 };
+    },
+    // feat-20260613-material-paramschema-driven-binding M4 / w22 (D-5 graceful):
+    // expose the registered shader's derive(paramSchema).textureFieldNames to
+    // the materialLoader so it can decide which values fields carry
+    // refs[] indices without a hardcoded texture-field allowlist Set
+    // (AC-03). Returns `undefined` when the shader is not registered (cross-
+    // worktree shader-late-register, plan R-4) — the loader then falls back
+    // to a graceful "try every int paramValue" walk.
+    getMaterialShaderTextureFieldNames: (shaderId: string) => {
+      const lookup = registry.shaderRegistry.findMaterialArtifact(shaderId);
+      if (!lookup.ok) return undefined;
+      return lookup.value.paramSchemaProjection.derivedInterface.textureFieldNames;
+    },
+    transcodeCaps: registry.transcodeCaps,
+    device: undefined,
+  };
+}
+
+/**
+ * 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.
+ *   }
+ * }
+ * ```
+ */