@forgeax/engine-assets-runtime 0.1.6 → 0.1.7

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-assets-runtime",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -26,22 +26,22 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-codec": "0.1.6",
-    "@forgeax/engine-ecs": "0.1.6",
-    "@forgeax/engine-geometry": "0.1.6",
-    "@forgeax/engine-graphics-extras": "0.1.6",
-    "@forgeax/engine-image": "0.1.6",
-    "@forgeax/engine-pack": "0.1.6",
-    "@forgeax/engine-plugin": "0.1.6",
-    "@forgeax/engine-rhi": "0.1.6",
-    "@forgeax/engine-scene": "0.1.6",
-    "@forgeax/engine-shader": "0.1.6",
-    "@forgeax/engine-types": "0.1.6",
-    "@forgeax/engine-ui": "0.1.6",
+    "@forgeax/engine-codec": "0.1.7",
+    "@forgeax/engine-ecs": "0.1.7",
+    "@forgeax/engine-geometry": "0.1.7",
+    "@forgeax/engine-graphics-extras": "0.1.7",
+    "@forgeax/engine-image": "0.1.7",
+    "@forgeax/engine-pack": "0.1.7",
+    "@forgeax/engine-plugin": "0.1.7",
+    "@forgeax/engine-rhi": "0.1.7",
+    "@forgeax/engine-scene": "0.1.7",
+    "@forgeax/engine-shader": "0.1.7",
+    "@forgeax/engine-types": "0.1.7",
+    "@forgeax/engine-ui": "0.1.7",
     "@webgpu/types": "^0.1.71"
   },
   "devDependencies": {
-    "@forgeax/engine-skinning": "0.1.6",
+    "@forgeax/engine-skinning": "0.1.7",
     "@webgpu/types": "^0.1.71"
   },
   "forgeax": {

package/src/__tests__/material-ready.integration.test.ts

@@ -19,7 +19,7 @@ const PRODUCTION_GUID = '019f0000-0000-7000-8000-000000000701';
 function cookedRecord(guid = MATERIAL_GUID): CookedMaterialRecord {
   const artifactDigest = createMaterialArtifactDigest(ARTIFACT_BYTES);
   return {
-    schemaVersion: 'material-cook/2',
+    schemaVersion: 'material-cook/3',
     guid,
     materialGuid: guid,
     publicationGeneration: 7,
@@ -36,15 +36,31 @@ function cookedRecord(guid = MATERIAL_GUID): CookedMaterialRecord {
       bytes: ARTIFACT_BYTES,
     },
     receipt: {
-      schemaVersion: 'material-cook/2',
+      schemaVersion: 'material-cook/3',
       sourceClosure: ['materials/ready.material.json', 'shaders/ready.wgsl'],
       profile: 'webgpu/v1',
       compilerVersion: 'compiler/1',
-      inputDigest: 'input-digest',
-      outputDigest: artifactDigest,
-      layoutIdentity: 'sha256:ready-layout',
+      identity: {
+        materialContractDigest: 'sha256:ready-contract',
+        sourceRevision: 'sha256:ready-source',
+        sourceClosureDigest: 'sha256:ready-closure',
+        layoutIdentity: 'sha256:ready-layout',
+        programIdentity: 'sha256:ready-program',
+        pipelineIdentity: 'sha256:ready-pipeline',
+        materialPublicationIdentity: 'sha256:ready-publication',
+        cookIdentity: 'sha256:ready-cook',
+        compilerFingerprint: 'sha256:ready-compiler',
+        wasm: {
+          sourceContentKey: 'unavailable',
+          artifactSha256: 'unavailable',
+          glueSha256: 'unavailable',
+        },
+        artifactDigest,
+        valueGeneration: 7,
+        dependencyGeneration: 7,
+        cookGeneration: 7,
+      },
       derivedInterface: { layoutIdentity: 'sha256:ready-layout' },
-      publicationGeneration: 7,
     },
   };
 }

package/src/__tests__/material-stale-generation.unit.test.ts

@@ -30,7 +30,6 @@ function createCookedMaterialLoader() {
         guid,
         record: {
           ...raw,
-          schemaVersion: 'material-cook/2',
           materialGuid: raw.guid,
           publicationGeneration: 1,
           specializationKey: SPECIALIZATION_KEY,
@@ -40,11 +39,7 @@ function createCookedMaterialLoader() {
           artifact: { ...raw.artifact, digest, bytes },
           receipt: {
             ...raw.receipt,
-            schemaVersion: 'material-cook/2',
-            layoutIdentity: 'sha256:pulse-layout',
-            derivedInterface: { layoutIdentity: 'sha256:pulse-layout' },
-            publicationGeneration: 1,
-            outputDigest: digest,
+            identity: { ...raw.receipt.identity, artifactDigest: digest, cookGeneration: 1 },
           },
         },
         artifact: { bytes },

package/src/__tests__/resolve-asset-handle.unit.test.ts

@@ -167,7 +167,7 @@ describe('walkMaterialPassesOverSharedRefs', () => {
     const child = mat({
       parent: 'p-guid' as never,
       parameters: [
-        { name: 'roughness', type: 'f32', static: true },
+        { name: 'roughness', type: 'f32' },
         { name: 'normalTexture', type: 'texture' },
       ],
     });

package/src/__tests__/scriptable-pack-public-surface.test-d.ts

@@ -1,8 +1,10 @@
 import type {
   AnimationGraph,
   AssetRegistry,
+  AssetRegistryResolver,
   AudioClipAsset,
   ParticleEffectAsset,
+  RuntimeAssetRegistry,
   TilesetAsset,
 } from '@forgeax/engine-assets-runtime';
 import { expectTypeOf, it } from 'vitest';
@@ -14,3 +16,12 @@ it('exports concrete loadByGuid payload types from the runtime entry point', ()
   expectTypeOf<AudioClipAsset['mediaType']>().toMatchTypeOf<`audio/${string}`>();
   expectTypeOf<ParticleEffectAsset['program']>().toMatchTypeOf<ParticleEffectAsset['program']>();
 });
+
+it('exports the five-action runtime registry and its resolver from the root entry point', () => {
+  expectTypeOf<RuntimeAssetRegistry>().toHaveProperty('installDecoder');
+  expectTypeOf<RuntimeAssetRegistry>().toHaveProperty('load');
+  expectTypeOf<RuntimeAssetRegistry>().toHaveProperty('snapshot');
+  expectTypeOf<RuntimeAssetRegistry>().toHaveProperty('subscribe');
+  expectTypeOf<AssetRegistryResolver>().toHaveProperty('lookup');
+  expectTypeOf<AssetRegistryResolver>().toHaveProperty('guidOf');
+});

package/src/__tests__/validate-material.unit.test.ts

@@ -64,7 +64,7 @@ describe('validateMaterialCookIdentity', () => {
   const record = {
     guid: 'mat-child',
     receipt: {
-      layoutIdentity: 'sha256:root-layout',
+      identity: { layoutIdentity: 'sha256:root-layout' },
       derivedInterface: { layoutIdentity: 'sha256:root-layout' },
     },
   } as never;

package/src/asset-registry.ts

@@ -611,6 +611,11 @@ export class AssetRegistry {
     return this._originIndex.get(asset as object);
   }
 
+  /** Public identity projection consumed by scene collection boundaries. */
+  guidOf(asset: Asset): string | undefined {
+    return this._guidForAsset(asset);
+  }
+
   /** Return the production MaterialReady/Error result for one material GUID. */
   getMaterialReadiness(guid: string): MaterialReady | MaterialLoadError | undefined {
     return this.materialReadiness.get(guid.toLowerCase());

package/src/handles.ts

@@ -3,7 +3,7 @@
 // straight-cut). Pure move from asset-registry.ts; zero identifier changes.
 
 import type { Handle } from '@forgeax/engine-types';
-import { toShared } from '@forgeax/engine-types';
+import { handleSlot, toShared } from '@forgeax/engine-types';
 
 // ─── Builtin handles (D-S9 / backward compat with hello-triangle + hello-cube) ─
 
@@ -146,6 +146,12 @@ export const BUILTIN_MESH_GUIDS: ReadonlyArray<readonly [Handle<'MeshAsset', 'sh
   [HANDLE_CYLINDER, 'ab20af21-0764-55be-a7f2-b80ab3d46a0a'],
 ];
 
+/** Resolve the stable producer GUID for one process-static builtin mesh handle. */
+export function builtinMeshGuid(handle: Handle<string, 'shared'>): string | undefined {
+  const slot = handleSlot(handle);
+  return BUILTIN_MESH_GUIDS.find(([candidate]) => handleSlot(candidate) === slot)?.[1];
+}
+
 /**
  * Field names known to carry handle<> schema-vocab references (plan-strategy
  * D-4).  parseScenePayload uses this allowlist to replace integer values

package/src/index.ts

@@ -76,6 +76,7 @@ export {
 } from './errors/asset';
 // ─── Builtin mesh handles (re-exported by asset-registry from ./handles) ─────
 export {
+  builtinMeshGuid,
   HANDLE_CUBE,
   HANDLE_CYLINDER,
   HANDLE_NINESLICE_QUAD,
@@ -83,7 +84,15 @@ export {
   HANDLE_SPHERE,
   HANDLE_TRIANGLE,
 } from './handles';
-export { createAssetRegistry } from './internal/load-asset.js';
+// The five-action runtime registry is distinct from the legacy authoring
+// AssetRegistry class above. Keep its resolver on the public package boundary
+// so render/VFX hosts never reach through `/internal` to inspect loaded assets.
+export {
+  type AssetRegistry as RuntimeAssetRegistry,
+  type AssetRegistryResolver,
+  createAssetRegistry,
+  getAssetRegistryResolver,
+} from './internal/load-asset.js';
 // ─── Loader-injection surface ───────────────────────────────────────────────
 export { LoaderRegistry } from './loader-registry';
 // ─── Default loader tables + individual loaders (pre-w14 consumer face) ──────

package/src/material/inspection.ts

@@ -29,7 +29,7 @@ export function inspectMaterialRuntime(ready: MaterialReady): MaterialRuntimeInf
     publicationGeneration: ready.publicationGeneration,
     specializationKey: ready.specializationKey,
     artifactDigest: ready.artifactDigest,
-    layoutIdentity: ready.record.receipt.layoutIdentity,
+    layoutIdentity: ready.record.receipt.identity.layoutIdentity,
     dependencies: [
       ...ready.record.refs.parent,
       ...ready.record.refs.textures,

package/src/material/loader.ts

@@ -108,7 +108,7 @@ function missingCook(request: MaterialLoadRequest): MaterialLoadError {
 function recordError(
   request: MaterialLoadRequest,
   field: string,
-  expected = 'a complete material-cook/2 publication record',
+  expected = 'a complete material-cook/3 publication record',
 ): MaterialLoadError {
   return materialError(
     request,
@@ -174,18 +174,18 @@ function completeTupleField(record: CookedMaterialRecord): string | undefined {
     receipt.profile.length === 0 ||
     typeof receipt.compilerVersion !== 'string' ||
     receipt.compilerVersion.length === 0 ||
-    typeof receipt.inputDigest !== 'string' ||
-    receipt.inputDigest.length === 0 ||
-    receipt.outputDigest !== record.artifactDigest ||
-    receipt.publicationGeneration !== record.publicationGeneration
+    typeof receipt.identity.cookIdentity !== 'string' ||
+    receipt.identity.cookIdentity.length === 0 ||
+    receipt.identity.artifactDigest !== record.artifactDigest ||
+    receipt.identity.cookGeneration !== record.publicationGeneration
   )
     return 'receipt';
   if (
-    typeof receipt.layoutIdentity !== 'string' ||
-    receipt.layoutIdentity.length === 0 ||
-    receipt.derivedInterface?.layoutIdentity !== receipt.layoutIdentity
+    typeof receipt.identity.layoutIdentity !== 'string' ||
+    receipt.identity.layoutIdentity.length === 0 ||
+    receipt.derivedInterface?.layoutIdentity !== receipt.identity.layoutIdentity
   )
-    return 'receipt.layoutIdentity';
+    return 'receipt.identity.layoutIdentity';
   if (
     typeof record.artifact.mediaType !== 'string' ||
     record.artifact.mediaType.length === 0 ||

package/src/material/runtime-shader.ts

@@ -22,7 +22,7 @@ export function materialParametersToParamSchema(
       ? ENGINE_INJECTED_TEXTURE_FIELDS
       : undefined;
   return parameters.flatMap((parameter): ParamSchemaEntry[] => {
-    if (parameter.static || parameter.type === 'bool') return [];
+    if (parameter.type === 'bool') return [];
     if (parameter.type === 'texture') {
       if (engineInjectedTextureFields?.has(parameter.name) === true) return [];
       return [{ name: parameter.name, type: 'texture2d' }];

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

@@ -104,7 +104,7 @@ export async function loadByGuid<T = Asset>(
 }
 
 function cookedRecordFromPayload(payload: Record<string, unknown>): unknown {
-  if (payload.schemaVersion === 'material-cook/2') return payload;
+  if (payload.schemaVersion === 'material-cook/3') 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;

package/src/registry/validate-material.ts

@@ -121,11 +121,10 @@ export function validateMaterialCookIdentity(
   record: Pick<CookedMaterialRecord, 'guid' | 'receipt'>,
   root: MaterialEffectiveRootIdentity,
 ): MaterialError | null {
-  const actual = record.receipt.layoutIdentity;
+  const actual = record.receipt.identity.layoutIdentity;
   if (
     actual !== root.layoutIdentity ||
-    (record.receipt as { readonly derivedInterface?: { readonly layoutIdentity?: string } })
-      .derivedInterface?.layoutIdentity !== root.layoutIdentity
+    record.receipt.derivedInterface.layoutIdentity !== root.layoutIdentity
   ) {
     return createMaterialError('material-derived-interface-mismatch', {
       code: 'material-derived-interface-mismatch',