@forgeax/engine-assets-runtime 0.1.4 → 0.1.6

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

@@ -0,0 +1,492 @@
+import {
+  type CookedMaterialRecord,
+  createMaterialArtifactDigest,
+  serializeCookedMaterialRecord,
+} from '@forgeax/engine-pack';
+import { AssetGuid } from '@forgeax/engine-pack/guid';
+import { ShaderRegistry } from '@forgeax/engine-shader';
+import { describe, expect, it, vi } from 'vitest';
+import { AssetRegistry } from '../asset-registry';
+import { MaterialGenerationCache } from '../material/generation-cache';
+import { inspectMaterialRuntime } from '../material/inspection.js';
+import { createMaterialLoader, type MaterialPublication } from '../material/loader.js';
+import { materialParametersToParamSchema } from '../material/runtime-shader.js';
+
+const MATERIAL_GUID = 'mat-ready';
+const ARTIFACT_BYTES = new TextEncoder().encode('published material artifact');
+const PRODUCTION_GUID = '019f0000-0000-7000-8000-000000000701';
+
+function cookedRecord(guid = MATERIAL_GUID): CookedMaterialRecord {
+  const artifactDigest = createMaterialArtifactDigest(ARTIFACT_BYTES);
+  return {
+    schemaVersion: 'material-cook/2',
+    guid,
+    materialGuid: guid,
+    publicationGeneration: 7,
+    specializationKey: 'material-specialization/7/ready',
+    artifactDigest,
+    sourceClosure: ['materials/ready.material.json', 'shaders/ready.wgsl'],
+    parameterContract: { parameters: [], values: {} },
+    resolved: { passes: [], parameters: [], values: {} },
+    refs: { parent: [], textures: [], samplers: [], modules: [] },
+    artifact: {
+      mediaType: 'text/wgsl',
+      path: `materials/${guid}/shader.wgsl`,
+      digest: artifactDigest,
+      bytes: ARTIFACT_BYTES,
+    },
+    receipt: {
+      schemaVersion: 'material-cook/2',
+      sourceClosure: ['materials/ready.material.json', 'shaders/ready.wgsl'],
+      profile: 'webgpu/v1',
+      compilerVersion: 'compiler/1',
+      inputDigest: 'input-digest',
+      outputDigest: artifactDigest,
+      layoutIdentity: 'sha256:ready-layout',
+      derivedInterface: { layoutIdentity: 'sha256:ready-layout' },
+      publicationGeneration: 7,
+    },
+  };
+}
+
+function publication(
+  overrides: {
+    readonly record?: unknown;
+    readonly artifact?: MaterialPublication['artifact'] | null;
+  } = {},
+): MaterialPublication {
+  const record = cookedRecord();
+  return {
+    guid: MATERIAL_GUID,
+    record: overrides.record ?? record,
+    ...(overrides.artifact === null
+      ? {}
+      : { artifact: overrides.artifact ?? { bytes: ARTIFACT_BYTES } }),
+  };
+}
+
+function createLoader(loadPublication: () => Promise<MaterialPublication | undefined>) {
+  return createMaterialLoader({ loadPublication, loadReference: async () => true });
+}
+
+describe('material runtime readiness', () => {
+  it('preserves authored numeric defaults in the runtime parameter contract', () => {
+    expect(
+      materialParametersToParamSchema(
+        [
+          { name: 'baseColor', type: 'color', default: [1, 1, 1, 1] },
+          { name: 'roughness', type: 'f32', default: 0.5 },
+          { name: 'baseColorTexture', type: 'texture' },
+        ],
+        'published::custom',
+      ),
+    ).toEqual([
+      { name: 'baseColor', type: 'color', default: [1, 1, 1, 1] },
+      { name: 'roughness', type: 'f32', default: 0.5 },
+      { name: 'baseColorTexture', type: 'texture2d' },
+    ]);
+  });
+
+  it('loads only a cooked record with its artifact and complete references', async () => {
+    const loader = createLoader(async () => publication());
+
+    const result = await loader.load({
+      guid: MATERIAL_GUID,
+      specializationKey: 'material-specialization/7/ready',
+    });
+
+    expect(result.status).toBe('Ready');
+    if (result.status !== 'Ready') return;
+    expect(result).toMatchObject({
+      materialGuid: MATERIAL_GUID,
+      publicationGeneration: 7,
+      specializationKey: 'material-specialization/7/ready',
+      artifactDigest: expect.stringMatching(/^sha256:/),
+      sourceClosure: ['materials/ready.material.json', 'shaders/ready.wgsl'],
+      parameterContract: { parameters: [], values: {} },
+    });
+    expect(inspectMaterialRuntime(result)).toMatchObject({
+      materialGuid: MATERIAL_GUID,
+      readiness: 'ready',
+      publicationGeneration: 7,
+      specializationKey: 'material-specialization/7/ready',
+      artifactDigest: expect.stringMatching(/^sha256:/),
+      sourceClosure: ['materials/ready.material.json', 'shaders/ready.wgsl'],
+      parameterContract: { parameters: [], values: {} },
+      status: 'Ready',
+    });
+  });
+
+  it('returns a structured missing-cook failure without compiling at runtime', async () => {
+    const loader = createLoader(async () => undefined);
+    const result = await loader.load({ guid: 'mat-missing', specializationKey: 'key-a' });
+
+    expect(result).toMatchObject({
+      status: 'Error',
+      error: { code: 'material-specialization-not-cooked' },
+    });
+  });
+
+  it.each([
+    ['artifact missing', () => ({ artifact: null }), 'asset-artifact-missing'],
+    [
+      'artifact bytes tampered',
+      () => ({ artifact: { bytes: new TextEncoder().encode('tampered artifact') } }),
+      'asset-artifact-integrity-mismatch',
+    ],
+    [
+      'record field tampered',
+      () => ({ record: { ...cookedRecord(), publicationGeneration: undefined } }),
+      'material-cook-record-invalid',
+    ],
+  ] as const)('rejects %s on the published tuple', async (_label, mutate, code) => {
+    const loader = createLoader(async () => publication(mutate()));
+    const result = await loader.load({
+      guid: MATERIAL_GUID,
+      specializationKey: 'material-specialization/7/ready',
+    });
+
+    expect(result).toMatchObject({ status: 'Error', error: { code } });
+  });
+
+  it('keeps publication generations distinct in the material cache', async () => {
+    const cache = new MaterialGenerationCache();
+    let calls = 0;
+    const load = async () => {
+      calls += 1;
+      return calls;
+    };
+
+    const first = await cache.resolve(MATERIAL_GUID, 'material-specialization/7/ready', load, 7);
+    const second = await cache.resolve(MATERIAL_GUID, 'material-specialization/7/ready', load, 8);
+
+    expect(first).toBe(1);
+    expect(second).toBe(2);
+    expect(calls).toBe(2);
+  });
+
+  it('loads the published record sidecar through the production GUID route', async () => {
+    const record = cookedRecord(PRODUCTION_GUID);
+    const packageUrl = `/materials/${PRODUCTION_GUID}.pack.json`;
+    const descriptor = {
+      path: record.artifact.path,
+      mediaType: record.artifact.mediaType,
+      byteLength: ARTIFACT_BYTES.byteLength,
+      integrity: { algorithm: 'sha256' as const, digest: record.artifactDigest },
+    };
+    const pack = {
+      schemaVersion: '2.0.0',
+      kind: 'internal-text-package',
+      assets: [
+        {
+          guid: PRODUCTION_GUID,
+          kind: 'material',
+          payload: {
+            kind: 'material',
+            passes: [{ name: 'Forward', program: { module: 'core/pbr' } }],
+            parameters: [],
+            values: {},
+          },
+          refs: [],
+          artifacts: { [record.artifact.path]: descriptor },
+        },
+      ],
+    };
+    const fetcher = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.endsWith('/pack-index.json')) {
+        return new Response(
+          JSON.stringify([{ guid: PRODUCTION_GUID, packageUrl, kind: 'material' }]),
+        );
+      }
+      if (url.endsWith('.record.json')) {
+        return new Response(serializeCookedMaterialRecord(record), {
+          headers: { 'content-type': 'application/json' },
+        });
+      }
+      if (url.endsWith('.pack.json')) return new Response(JSON.stringify(pack));
+      if (url.endsWith('.wgsl')) return new Response(ARTIFACT_BYTES);
+      return new Response('not found', { status: 404 });
+    });
+    vi.stubGlobal('fetch', fetcher);
+
+    try {
+      const registry = new AssetRegistry({} as never);
+      registry.configurePackIndex('/pack-index.json');
+      const parsedGuid = AssetGuid.parse(PRODUCTION_GUID);
+      expect(parsedGuid.ok).toBe(true);
+      if (!parsedGuid.ok) return;
+      const payloadResult = await registry.loadByGuid(parsedGuid.value);
+
+      expect(payloadResult).toMatchObject({ ok: true });
+      expect(registry.getMaterialReadiness(PRODUCTION_GUID)).toMatchObject({
+        status: 'Ready',
+        materialGuid: PRODUCTION_GUID,
+        publicationGeneration: 7,
+        artifactDigest: record.artifactDigest,
+      });
+      expect(fetcher).toHaveBeenCalled();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it('does not require a cooked artifact for an Engine-owned material module', async () => {
+    const packageUrl = `/materials/${PRODUCTION_GUID}.pack.json`;
+    const pack = {
+      schemaVersion: '2.0.0',
+      kind: 'internal-text-package',
+      assets: [
+        {
+          guid: PRODUCTION_GUID,
+          kind: 'material',
+          payload: {
+            kind: 'material',
+            passes: [{ name: 'Forward', program: { module: 'forgeax::default-standard-pbr' } }],
+            values: { baseColor: [1, 0.2, 0.05, 1] },
+          },
+          refs: [],
+          artifacts: {},
+        },
+      ],
+    };
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async (input: RequestInfo | URL) => {
+        const url = String(input);
+        if (url.endsWith('/pack-index.json')) {
+          return new Response(
+            JSON.stringify([{ guid: PRODUCTION_GUID, packageUrl, kind: 'material' }]),
+          );
+        }
+        return new Response(JSON.stringify(pack));
+      }),
+    );
+
+    try {
+      const registry = new AssetRegistry({} as never);
+      registry.configurePackIndex('/pack-index.json');
+      const parsedGuid = AssetGuid.parse(PRODUCTION_GUID);
+      expect(parsedGuid.ok).toBe(true);
+      if (!parsedGuid.ok) return;
+
+      const result = await registry.loadByGuid(parsedGuid.value);
+
+      expect(result).toMatchObject({ ok: true, value: { kind: 'material' } });
+      expect(registry.getMaterialReadiness(PRODUCTION_GUID)).toBeUndefined();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it('installs authored pass modules from MaterialReady without a host registration step', async () => {
+    const customShaderId = 'published::custom';
+    const baseRecord = cookedRecord(PRODUCTION_GUID);
+    const record: CookedMaterialRecord = {
+      ...baseRecord,
+      resolved: {
+        ...baseRecord.resolved,
+        passes: [{ name: 'Forward', program: { module: customShaderId } }],
+      },
+      refs: { ...baseRecord.refs, modules: [customShaderId] },
+    };
+    const packageUrl = `/materials/${PRODUCTION_GUID}.pack.json`;
+    const descriptor = {
+      path: record.artifact.path,
+      mediaType: record.artifact.mediaType,
+      byteLength: ARTIFACT_BYTES.byteLength,
+      integrity: { algorithm: 'sha256' as const, digest: record.artifactDigest },
+    };
+    const pack = {
+      schemaVersion: '2.0.0',
+      kind: 'internal-text-package',
+      assets: [
+        {
+          guid: PRODUCTION_GUID,
+          kind: 'material',
+          payload: {
+            kind: 'material',
+            passes: [{ name: 'Forward', program: { module: customShaderId } }],
+            parameters: [],
+            values: {},
+          },
+          refs: [],
+          artifacts: { [record.artifact.path]: descriptor },
+        },
+      ],
+    };
+    const fetcher = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.endsWith('/pack-index.json')) {
+        return new Response(
+          JSON.stringify([{ guid: PRODUCTION_GUID, packageUrl, kind: 'material' }]),
+        );
+      }
+      if (url.endsWith('.record.json')) {
+        return new Response(serializeCookedMaterialRecord(record), {
+          headers: { 'content-type': 'application/json' },
+        });
+      }
+      if (url.endsWith('.pack.json')) return new Response(JSON.stringify(pack));
+      if (url.endsWith('.wgsl')) return new Response(ARTIFACT_BYTES);
+      return new Response('not found', { status: 404 });
+    });
+    vi.stubGlobal('fetch', fetcher);
+
+    const shaderRegistry = new ShaderRegistry({
+      device: {
+        createShaderModule: () => {
+          throw new Error('not used');
+        },
+      } as never,
+      manifestUrl: undefined,
+    });
+    try {
+      const registry = new AssetRegistry(shaderRegistry);
+      registry.configurePackIndex('/pack-index.json');
+      const parsedGuid = AssetGuid.parse(PRODUCTION_GUID);
+      expect(parsedGuid.ok).toBe(true);
+      if (!parsedGuid.ok) return;
+
+      const result = await registry.loadByGuid(parsedGuid.value);
+
+      expect(result).toMatchObject({ ok: true });
+      const lookup = shaderRegistry.findMaterialArtifact(customShaderId);
+      expect(lookup).toMatchObject({
+        ok: true,
+        value: { source: new TextDecoder().decode(ARTIFACT_BYTES), paramSchema: [] },
+      });
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it('installs authored pass modules from an inline cooked artifact', async () => {
+    const customShaderId = 'published::inline-custom';
+    const baseRecord = cookedRecord(PRODUCTION_GUID);
+    const record: CookedMaterialRecord = {
+      ...baseRecord,
+      resolved: {
+        ...baseRecord.resolved,
+        passes: [{ name: 'Forward', program: { module: customShaderId } }],
+      },
+      refs: { ...baseRecord.refs, modules: [customShaderId] },
+    };
+    const packageUrl = `/materials/${PRODUCTION_GUID}.inline.pack.json`;
+    const pack = {
+      schemaVersion: '2.0.0',
+      kind: 'internal-text-package',
+      assets: [
+        {
+          guid: PRODUCTION_GUID,
+          kind: 'material',
+          payload: {
+            kind: 'material',
+            passes: [{ name: 'Forward', program: { module: customShaderId } }],
+            parameters: [],
+            values: {},
+            cooked: JSON.parse(serializeCookedMaterialRecord(record)),
+          },
+          refs: [],
+          artifacts: {},
+        },
+      ],
+    };
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async (input: RequestInfo | URL) => {
+        const url = String(input);
+        if (url.endsWith('/pack-index.json')) {
+          return new Response(
+            JSON.stringify([{ guid: PRODUCTION_GUID, packageUrl, kind: 'material' }]),
+          );
+        }
+        if (url.endsWith('.inline.pack.json')) return new Response(JSON.stringify(pack));
+        return new Response('not found', { status: 404 });
+      }),
+    );
+
+    const shaderRegistry = new ShaderRegistry({
+      device: {
+        createShaderModule: () => {
+          throw new Error('not used');
+        },
+      } as never,
+      manifestUrl: undefined,
+    });
+    try {
+      const registry = new AssetRegistry(shaderRegistry);
+      registry.configurePackIndex('/pack-index.json');
+      const parsedGuid = AssetGuid.parse(PRODUCTION_GUID);
+      expect(parsedGuid.ok).toBe(true);
+      if (!parsedGuid.ok) return;
+
+      const result = await registry.loadByGuid(parsedGuid.value);
+
+      expect(result).toMatchObject({ ok: true });
+      expect(shaderRegistry.findMaterialArtifact(customShaderId)).toMatchObject({
+        ok: true,
+        value: { source: new TextDecoder().decode(ARTIFACT_BYTES), paramSchema: [] },
+      });
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
+  it('does not reinterpret the Pack descriptor base64 digest as a material digest', async () => {
+    const record = cookedRecord(PRODUCTION_GUID);
+    const packageUrl = `/materials/${PRODUCTION_GUID}.pack.json`;
+    const descriptor = {
+      path: record.artifact.path,
+      mediaType: record.artifact.mediaType,
+      byteLength: ARTIFACT_BYTES.byteLength,
+      integrity: {
+        algorithm: 'sha256' as const,
+        digest: 'xEjSZ79vI9pvhM0qf+ot+tnK32nBxZHXVAn4OYdaJ3M=',
+      },
+    };
+    const pack = {
+      schemaVersion: '2.0.0',
+      kind: 'internal-text-package',
+      assets: [
+        {
+          guid: PRODUCTION_GUID,
+          kind: 'material',
+          payload: {
+            kind: 'material',
+            passes: [{ name: 'Forward', program: { module: 'core/pbr' } }],
+            parameters: [],
+            values: {},
+          },
+          refs: [],
+          artifacts: { [record.artifact.path]: descriptor },
+        },
+      ],
+    };
+    const fetcher = vi.fn(async (input: RequestInfo | URL) => {
+      const url = String(input);
+      if (url.endsWith('/pack-index.json')) {
+        return new Response(
+          JSON.stringify([{ guid: PRODUCTION_GUID, packageUrl, kind: 'material' }]),
+        );
+      }
+      if (url.endsWith('.record.json')) return new Response(serializeCookedMaterialRecord(record));
+      if (url.endsWith('.pack.json')) return new Response(JSON.stringify(pack));
+      if (url.endsWith('.wgsl')) return new Response(ARTIFACT_BYTES);
+      return new Response('not found', { status: 404 });
+    });
+    vi.stubGlobal('fetch', fetcher);
+    try {
+      const registry = new AssetRegistry({} as never);
+      registry.configurePackIndex('/pack-index.json');
+      const parsedGuid = AssetGuid.parse(PRODUCTION_GUID);
+      expect(parsedGuid.ok).toBe(true);
+      if (!parsedGuid.ok) return;
+      const result = await registry.loadByGuid(parsedGuid.value);
+      expect(result).toMatchObject({ ok: true });
+      expect(registry.getMaterialReadiness(PRODUCTION_GUID)).toMatchObject({ status: 'Ready' });
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+});

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

@@ -0,0 +1,152 @@
+import { readFileSync } from 'node:fs';
+import { type CookedMaterialRecord, createMaterialArtifactDigest } from '@forgeax/engine-pack';
+import { describe, expect, it } from 'vitest';
+import { MaterialGenerationCache } from '../material/generation-cache.js';
+import { createMaterialLoader } from '../material/loader.js';
+
+const CUSTOM_SHADER_FIXTURE = new URL(
+  '../../../../apps/hello/custom-shader/assets/pulse-material.pack.json',
+  import.meta.url,
+);
+
+const DERIVED_MATERIAL_GUID = '01935b00-7d8c-7c4e-9f12-345678abcd03';
+const SPECIALIZATION_KEY = 'my-game::pulse-material';
+const SPECIALIZATION_DEPENDENCIES = ['my-game::pulse-material', 'pack:pulse-material'] as const;
+
+function createCookedMaterialLoader() {
+  const fixture = JSON.parse(readFileSync(CUSTOM_SHADER_FIXTURE, 'utf8')) as {
+    assets: readonly { guid: string; payload?: { cooked?: unknown } }[];
+  };
+  const cookedByGuid = new Map(
+    fixture.assets.map((entry) => [entry.guid.toLowerCase(), entry.payload?.cooked]),
+  );
+  return createMaterialLoader({
+    loadPublication: async (guid) => {
+      const raw = cookedByGuid.get(guid.toLowerCase()) as CookedMaterialRecord | undefined;
+      if (raw === undefined) return undefined;
+      const bytes = new TextEncoder().encode('published pulse artifact');
+      const digest = createMaterialArtifactDigest(bytes);
+      return {
+        guid,
+        record: {
+          ...raw,
+          schemaVersion: 'material-cook/2',
+          materialGuid: raw.guid,
+          publicationGeneration: 1,
+          specializationKey: SPECIALIZATION_KEY,
+          artifactDigest: digest,
+          sourceClosure: raw.receipt.sourceClosure,
+          parameterContract: { parameters: raw.resolved.parameters, values: raw.resolved.values },
+          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,
+          },
+        },
+        artifact: { bytes },
+      };
+    },
+    loadReference: async () => true,
+  });
+}
+
+describe('material stale generation publication', () => {
+  it('retries once and reports the generation vector when dependencies change', async () => {
+    const cache = new MaterialGenerationCache();
+    let calls = 0;
+    const result = await cache.loadWithGeneration('mat-a', ['texture/a'], async (generation) => {
+      calls += 1;
+      if (calls === 1) cache.bump('texture/a');
+      return { generation, value: calls };
+    });
+
+    expect(result.ok).toBe(true);
+    expect(calls).toBe(2);
+    expect(cache.generationError('mat-a')).toBeUndefined();
+  });
+
+  it('exposes stale-generation details after the retry budget is exhausted', async () => {
+    const cache = new MaterialGenerationCache();
+    const result = await cache.loadWithGeneration('mat-a', ['texture/a'], async (generation) => {
+      cache.bump('texture/a');
+      return { generation, value: 1 };
+    });
+
+    expect(result).toMatchObject({
+      ok: false,
+      error: { code: 'material-specialization-stale-generation' },
+    });
+  });
+
+  it('retries a cooked material after the stale promise is rejected', async () => {
+    const cache = new MaterialGenerationCache();
+    const loader = createCookedMaterialLoader();
+    const dependencies: string[] = [...SPECIALIZATION_DEPENDENCIES];
+    const shaderDependency = SPECIALIZATION_DEPENDENCIES[0];
+    let unstable = true;
+    let loadCalls = 0;
+
+    const loadSpecialization = () =>
+      cache.loadWithGeneration(DERIVED_MATERIAL_GUID, dependencies, async (generation) => {
+        loadCalls += 1;
+        const loaded = await loader.load({
+          guid: DERIVED_MATERIAL_GUID,
+          specializationKey: SPECIALIZATION_KEY,
+        });
+        expect(loaded.status).toBe('Ready');
+        if (loaded.status !== 'Ready') throw new Error('fixture material did not load');
+        if (unstable) cache.bump(shaderDependency);
+        return { generation, value: loaded.record };
+      });
+
+    const stale = await cache.resolve(
+      DERIVED_MATERIAL_GUID,
+      SPECIALIZATION_KEY,
+      loadSpecialization,
+    );
+    expect(stale).toMatchObject({
+      ok: false,
+      error: { code: 'material-specialization-stale-generation' },
+    });
+    expect(loadCalls).toBe(2);
+    expect(cache.generationError(DERIVED_MATERIAL_GUID)?.detail).toMatchObject({
+      material: DERIVED_MATERIAL_GUID,
+      dependencies: [...SPECIALIZATION_DEPENDENCIES],
+      observed: {
+        dependencies: { [SPECIALIZATION_DEPENDENCIES[0]]: 1, [SPECIALIZATION_DEPENDENCIES[1]]: 0 },
+      },
+      current: {
+        dependencies: { [SPECIALIZATION_DEPENDENCIES[0]]: 2, [SPECIALIZATION_DEPENDENCIES[1]]: 0 },
+      },
+    });
+    const staleError = cache.generationError(DERIVED_MATERIAL_GUID);
+    expect(staleError?.code).toBe('material-specialization-stale-generation');
+    expect(staleError?.detail.code).toBe('material-specialization-stale-generation');
+    expect(Object.isFrozen(staleError?.detail)).toBe(true);
+    expect(Object.isFrozen(staleError?.detail.dependencies)).toBe(true);
+    expect(Object.isFrozen(staleError?.detail.observed.dependencies)).toBe(true);
+    expect(Object.isFrozen(staleError?.detail.current.dependencies)).toBe(true);
+    dependencies.push('mutated-after-publication');
+    expect(staleError?.detail.dependencies).toEqual([...SPECIALIZATION_DEPENDENCIES]);
+
+    const published: unknown[] = [];
+    if (stale.ok) published.push(stale.value);
+    expect(published).toHaveLength(0);
+
+    unstable = false;
+    const fresh = await cache.resolve(
+      DERIVED_MATERIAL_GUID,
+      SPECIALIZATION_KEY,
+      loadSpecialization,
+    );
+    expect(fresh.ok).toBe(true);
+    expect(loadCalls).toBe(3);
+    if (fresh.ok) published.push(fresh.value);
+    expect(published).toHaveLength(1);
+    expect(cache.generationError(DERIVED_MATERIAL_GUID)).toBeUndefined();
+  });
+});

package/src/__tests__/mesh-bin-morph-v3.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest';
+import { unpackMeshBinV4 } from '../loaders/mesh-bin';
+
+describe('mesh-bin v4 morph validation', () => {
+  it('rejects trailing bytes instead of silently accepting a malformed artifact', () => {
+    const bytes = new Uint8Array(80 + 1);
+    const view = new DataView(bytes.buffer);
+    view.setUint32(0, 4, true);
+    expect(unpackMeshBinV4(bytes, 'gltf://morph-trailing').ok).toBe(false);
+  });
+
+  it('rejects malformed metadata with a structured recovery error', () => {
+    const bytes = new Uint8Array(80);
+    const view = new DataView(bytes.buffer);
+    view.setUint32(0, 4, true);
+    const result = unpackMeshBinV4(bytes, 'gltf://morph-invalid');
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error.sourceKey).toBe('gltf://morph-invalid');
+    expect(result.error.recovery).toContain('re-cook');
+  });
+});