@forgeax/engine-assets-runtime 0.0.0-dev.8d955ade1c79

package/src/__tests__/scene-publication-fence.test.ts

@@ -0,0 +1,129 @@
+import type { AssetPublicationEnvelope } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import {
+  compareScenePublicationFences,
+  createScenePublicationFence,
+  observeScenePublication,
+  parseScenePublicationFence,
+  type ScenePublicationFence,
+  scenePublicationFenceFromCatalog,
+} from '../registry/scene-publication-fence.js';
+
+function publication(generation: number): AssetPublicationEnvelope {
+  return {
+    schemaVersion: 'asset-publication/1',
+    sourcePath: 'assets/showcase.pack.ts',
+    sourceRevision: `source-${generation}`,
+    generation,
+    digest: `sha256:publication-${generation}`,
+    outputSetDigest: `sha256:outputs-${generation}`,
+    outputs: [
+      {
+        guid: '01890000-0000-7000-8000-111111111111',
+        sourceKey: 'scene/main',
+        kind: 'scene',
+        digest: `sha256:scene-${generation}`,
+        refs: [],
+      },
+    ],
+    receipt: {
+      schemaVersion: 'asset-publication-receipt/1',
+      sourcePath: 'assets/showcase.pack.ts',
+      sourceRevision: `source-${generation}`,
+      inputFingerprint: `sha256:receipt-${generation}`,
+      outputDigest: `sha256:publication-${generation}`,
+      outputSetDigest: `sha256:outputs-${generation}`,
+      externalEvidence: [],
+    },
+    externalEvidence: [],
+  };
+}
+
+describe('Scene publication fence', () => {
+  it('serializes one complete source publication tuple', () => {
+    const created = createScenePublicationFence(publication(4));
+    expect(created.ok).toBe(true);
+    if (!created.ok) return;
+    const parsed = parseScenePublicationFence(JSON.parse(JSON.stringify(created.value)));
+    expect(parsed).toEqual(created);
+    expect(created.value).toMatchObject<ScenePublicationFence>({
+      schemaVersion: 'scene-publication-fence/1',
+      sourcePath: 'assets/showcase.pack.ts',
+      sourceRevision: 'source-4',
+      publicationGeneration: 4,
+      outputDigest: 'sha256:publication-4',
+      outputSetDigest: 'sha256:outputs-4',
+      receiptIdentity: 'sha256:receipt-4',
+    });
+  });
+
+  it('rejects missing output and receipt or digest mismatches before observation', () => {
+    expect(createScenePublicationFence({ ...publication(1), outputs: [] })).toMatchObject({
+      ok: false,
+      error: { code: 'asset-generation-fence-mismatch', phase: 'publication' },
+    });
+    expect(
+      createScenePublicationFence({
+        ...publication(1),
+        receipt: { ...publication(1).receipt, outputDigest: 'sha256:wrong' },
+      }),
+    ).toMatchObject({
+      ok: false,
+      error: { code: 'asset-generation-fence-mismatch', phase: 'publication' },
+    });
+  });
+
+  it('fails closed for mixed generations and observation timeout while preserving LKG', async () => {
+    const first = createScenePublicationFence(publication(1));
+    const second = createScenePublicationFence(publication(2));
+    expect(first.ok && second.ok).toBe(true);
+    if (!first.ok || !second.ok) return;
+    expect(compareScenePublicationFences(first.value, second.value)).toMatchObject({
+      ok: false,
+      error: {
+        code: 'asset-generation-fence-mismatch',
+        phase: 'observation',
+        currentGeneration: 2,
+      },
+    });
+
+    const observed = await observeScenePublication({
+      publication: publication(2),
+      waitForOutput: async () => {
+        await new Promise((resolve) => setTimeout(resolve, 20));
+      },
+      timeoutMs: 1,
+      lastKnownGood: first.value,
+    });
+    expect(observed).toMatchObject({
+      ok: false,
+      error: {
+        code: 'asset-generation-fence-mismatch',
+        phase: 'observation',
+        lastKnownGood: { publicationGeneration: 1 },
+        recoveryActions: ['continue-last-known-good', 'retry-rebuild', 'fresh-reopen'],
+      },
+    });
+  });
+
+  it('requires every Catalog output row to carry the same publication tuple', () => {
+    const source = publication(7);
+    const entries = source.outputs.map((output) => ({
+      guid: output.guid,
+      kind: output.kind,
+      packageUrl: '/assets/showcase.pack.json',
+      sourcePath: source.sourcePath,
+      publication: source,
+    }));
+    const outputGuid = source.outputs[0]?.guid;
+    if (outputGuid === undefined) return;
+    expect(scenePublicationFenceFromCatalog(entries, outputGuid)).toMatchObject({
+      ok: true,
+      value: { publicationGeneration: 7 },
+    });
+    expect(scenePublicationFenceFromCatalog(entries.slice(0, 0), outputGuid)).toMatchObject({
+      ok: false,
+      error: { code: 'asset-generation-fence-mismatch', phase: 'catalog' },
+    });
+  });
+});

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

@@ -0,0 +1,27 @@
+import type {
+  AnimationGraph,
+  AssetRegistry,
+  AssetRegistryResolver,
+  AudioClipAsset,
+  ParticleEffectAsset,
+  RuntimeAssetRegistry,
+  TilesetAsset,
+} from '@forgeax/engine-assets-runtime';
+import { expectTypeOf, it } from 'vitest';
+
+it('exports concrete loadByGuid payload types from the runtime entry point', () => {
+  expectTypeOf<AssetRegistry>().toHaveProperty('loadByGuid');
+  expectTypeOf<AnimationGraph['kind']>().toEqualTypeOf<'animation-graph'>();
+  expectTypeOf<TilesetAsset['kind']>().toEqualTypeOf<'tileset'>();
+  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__/static-rig.integration.test.ts

@@ -0,0 +1,8 @@
+import { Skin } from '@forgeax/engine-skinning';
+import { describe, expect, it } from 'vitest';
+
+describe('static rig asset consumer', () => {
+  it('does not require animation to describe Skin', () => {
+    expect(Skin.name).toBe('Skin');
+  });
+});

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

@@ -0,0 +1,359 @@
+// @forgeax/engine-assets-runtime -- material-validation free-function coverage
+// (fix issue #709). validateMaterialPasses / validateSpriteSlices /
+// validateParamType / detectTileNeedsRepeatSampler / materialShaderTextureFieldNames.
+//
+// The free functions read only `registry.shaderRegistry` / `.metrics` /
+// `.assetCatalog`, so a duck-typed stub standing in for AssetRegistry suffices
+// (charter F2: test against the surface the code touches, not the whole class).
+
+import {
+  type MaterialAsset,
+  type ParamSchemaEntry,
+  ParamSchemaProjectionOwner,
+} from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import type { AssetRegistry } from '../asset-registry';
+import {
+  detectTileNeedsRepeatSampler,
+  materialShaderTextureFieldNames,
+  validateMaterialCookIdentity,
+  validateMaterialPasses,
+  validateParamType,
+  validateSpriteSlices,
+} from '../registry/validate-material';
+
+interface StubShaders {
+  [shaderId: string]: readonly ParamSchemaEntry[];
+}
+
+function makeRegistry(
+  shaders: StubShaders,
+  opts: { metrics?: { increment(k: string): void }; catalog?: Map<string, unknown> } = {},
+): AssetRegistry {
+  const projectionOwner = new ParamSchemaProjectionOwner();
+  return {
+    shaderRegistry: {
+      findMaterialArtifact(id: string) {
+        const paramSchema = shaders[id];
+        const paramSchemaProjection =
+          paramSchema === undefined
+            ? undefined
+            : projectionOwner.admit({ ownerId: id, revision: 1, schema: paramSchema });
+        return paramSchemaProjection !== undefined
+          ? {
+              ok: true as const,
+              value: {
+                source: '',
+                paramSchema: paramSchemaProjection.schema,
+                paramSchemaProjection,
+              },
+            }
+          : { ok: false as const, error: new Error('not found') };
+      },
+    },
+    metrics: opts.metrics ?? null,
+    assetCatalog: opts.catalog ?? new Map(),
+  } as unknown as AssetRegistry;
+}
+
+function mat(over: Record<string, unknown>): MaterialAsset {
+  return { kind: 'material', ...over } as unknown as MaterialAsset;
+}
+
+describe('validateMaterialCookIdentity', () => {
+  const record = {
+    guid: 'mat-child',
+    receipt: {
+      identity: { layoutIdentity: 'sha256:root-layout' },
+      derivedInterface: { layoutIdentity: 'sha256:root-layout' },
+    },
+  } as never;
+
+  it('accepts an effective root identity and rejects a stale one', () => {
+    expect(
+      validateMaterialCookIdentity(record, {
+        guid: 'mat-parent',
+        layoutIdentity: 'sha256:root-layout',
+      }),
+    ).toBeNull();
+    expect(
+      validateMaterialCookIdentity(record, {
+        guid: 'mat-parent',
+        layoutIdentity: 'sha256:changed-layout',
+      }),
+    ).toMatchObject({
+      code: 'material-derived-interface-mismatch',
+      detail: { stage: 'extract', action: 'recook' },
+    });
+  });
+});
+
+describe('validateMaterialPasses', () => {
+  it('returns null when passes is undefined (inherits from parent)', () => {
+    expect(validateMaterialPasses(makeRegistry({}), mat({}))).toBeNull();
+  });
+
+  it('errors when passes is an explicit empty array', () => {
+    const e = validateMaterialPasses(makeRegistry({}), mat({ passes: [] }));
+    expect(e?.code).toBe('asset-invalid-value');
+    expect((e?.detail as { passCount: number }).passCount).toBe(0);
+  });
+
+  it('errors when a pass has no program module', () => {
+    const e = validateMaterialPasses(
+      makeRegistry({}),
+      mat({ passes: [{ name: 'main', program: { module: '' } }] }),
+    );
+    expect(e?.code).toBe('asset-invalid-value');
+  });
+
+  it('errors when a required (no-default) param is missing from values', () => {
+    const e = validateMaterialPasses(
+      makeRegistry({}),
+      mat({
+        passes: [{ name: 'm', program: { module: 'forgeax_material::standard' } }],
+        parameters: [{ name: 'roughness', type: 'f32' }],
+      }),
+    );
+    expect(e?.code).toBe('asset-invalid-value');
+    expect((e?.detail as { missingParams: string[] }).missingParams).toContain('roughness');
+  });
+
+  it('accepts when a required param is supplied with the right type', () => {
+    expect(
+      validateMaterialPasses(
+        makeRegistry({}),
+        mat({
+          passes: [{ name: 'm', program: { module: 'forgeax_material::standard' } }],
+          parameters: [{ name: 'roughness', type: 'f32' }],
+          values: { roughness: 0.5 },
+        }),
+      ),
+    ).toBeNull();
+  });
+
+  it('errors on a supplied param with a mismatched type', () => {
+    const e = validateMaterialPasses(
+      makeRegistry({}),
+      mat({
+        passes: [{ name: 'm', program: { module: 'forgeax_material::standard' } }],
+        parameters: [{ name: 'roughness', type: 'f32' }],
+        values: { roughness: 'no' },
+      }),
+    );
+    expect((e?.detail as { paramName: string }).paramName).toBe('roughness');
+  });
+
+  it('skips params that carry a default', () => {
+    expect(
+      validateMaterialPasses(
+        makeRegistry({}),
+        mat({
+          passes: [{ name: 'm', program: { module: 'forgeax_material::standard' } }],
+          parameters: [{ name: 'roughness', type: 'f32', default: 0.5 }],
+        }),
+      ),
+    ).toBeNull();
+  });
+
+  it('accepts absent and explicitly cleared optional params', () => {
+    const material = {
+      passes: [{ name: 'm', program: { module: 'forgeax_material::standard' } }],
+      parameters: [{ name: 'alphaCutoff', type: 'f32', optional: true }],
+    };
+    expect(validateMaterialPasses(makeRegistry({}), mat(material))).toBeNull();
+    expect(
+      validateMaterialPasses(makeRegistry({}), mat({ ...material, values: { alphaCutoff: null } })),
+    ).toBeNull();
+  });
+
+  it('still validates a supplied optional param', () => {
+    const e = validateMaterialPasses(
+      makeRegistry({}),
+      mat({
+        passes: [{ name: 'm', program: { module: 'forgeax_material::standard' } }],
+        parameters: [{ name: 'alphaCutoff', type: 'f32', optional: true }],
+        values: { alphaCutoff: 'no' },
+      }),
+    );
+    expect((e?.detail as { paramName: string }).paramName).toBe('alphaCutoff');
+  });
+});
+
+describe('validateParamType', () => {
+  const reg = makeRegistry({});
+  it('numeric scalars', () => {
+    expect(validateParamType(reg, 'x', 'f32', 1)).toBe(true);
+    expect(validateParamType(reg, 'x', 'u32', 'no')).toBe(false);
+  });
+  it('vector arities', () => {
+    expect(validateParamType(reg, 'x', 'vec2', [1, 2])).toBe(true);
+    expect(validateParamType(reg, 'x', 'vec3', [1, 2])).toBe(false);
+    expect(validateParamType(reg, 'x', 'vec4', [1, 2, 3, 4])).toBe(true);
+  });
+  it('color accepts length 3 or 4', () => {
+    expect(validateParamType(reg, 'x', 'color', [1, 2, 3])).toBe(true);
+    expect(validateParamType(reg, 'x', 'color', [1, 2, 3, 4])).toBe(true);
+    expect(validateParamType(reg, 'x', 'color', [1, 2])).toBe(false);
+  });
+  it('texture values accept compact GUIDs and structured records', () => {
+    expect(validateParamType(reg, 'x', 'texture', 'guid')).toBe(true);
+    expect(validateParamType(reg, 'x', 'texture', { texture: 'guid' })).toBe(true);
+    expect(validateParamType(reg, 'x', 'texture', 123)).toBe(false);
+  });
+  it('unknown type -> false', () => {
+    expect(validateParamType(reg, 'x', 'mat4', {})).toBe(false);
+  });
+});
+
+describe('validateSpriteSlices', () => {
+  const reg = makeRegistry({});
+  const spritePass = { name: 'main', program: { module: 'forgeax_material::sprite' } };
+
+  it('returns null for non-sprite shaders', () => {
+    expect(
+      validateSpriteSlices(
+        reg,
+        mat({ passes: [{ name: 'm', program: { module: 'forgeax::standard' } }] }),
+      ),
+    ).toBeNull();
+  });
+
+  it('returns null when slices is absent', () => {
+    expect(validateSpriteSlices(reg, mat({ passes: [spritePass], values: {} }))).toBeNull();
+  });
+
+  it('accepts a well-formed slices tuple', () => {
+    expect(
+      validateSpriteSlices(
+        reg,
+        mat({ passes: [spritePass], values: { slices: [0.1, 0.1, 0.1, 0.1] } }),
+      ),
+    ).toBeNull();
+  });
+
+  it('rejects a non-array / wrong-length / non-number slices', () => {
+    expect(
+      validateSpriteSlices(reg, mat({ passes: [spritePass], values: { slices: 'x' } }))?.code,
+    ).toBe('asset-invalid-value');
+    expect(
+      validateSpriteSlices(reg, mat({ passes: [spritePass], values: { slices: [0, 0, 0] } }))?.code,
+    ).toBe('asset-invalid-value');
+    expect(
+      validateSpriteSlices(reg, mat({ passes: [spritePass], values: { slices: [0, 0, 0, 'x'] } }))
+        ?.code,
+    ).toBe('asset-invalid-value');
+  });
+
+  it('rejects NaN, Infinity, and negative components', () => {
+    expect(
+      validateSpriteSlices(
+        reg,
+        mat({ passes: [spritePass], values: { slices: [Number.NaN, 0, 0, 0] } }),
+      ),
+    ).not.toBeNull();
+    expect(
+      validateSpriteSlices(
+        reg,
+        mat({ passes: [spritePass], values: { slices: [Number.POSITIVE_INFINITY, 0, 0, 0] } }),
+      ),
+    ).not.toBeNull();
+    expect(
+      validateSpriteSlices(reg, mat({ passes: [spritePass], values: { slices: [-0.1, 0, 0, 0] } })),
+    ).not.toBeNull();
+  });
+
+  it('rejects X-axis / Y-axis overlap against region', () => {
+    // default region z/w = 1; left+right = 1.2 >= 1
+    expect(
+      validateSpriteSlices(
+        reg,
+        mat({ passes: [spritePass], values: { slices: [0.6, 0, 0.6, 0] } }),
+      ),
+    ).not.toBeNull();
+    expect(
+      validateSpriteSlices(
+        reg,
+        mat({ passes: [spritePass], values: { slices: [0, 0.6, 0, 0.6] } }),
+      ),
+    ).not.toBeNull();
+  });
+});
+
+describe('detectTileNeedsRepeatSampler', () => {
+  const spritePass = { name: 'main', program: { module: 'forgeax_material::sprite' } };
+
+  it('no-ops when metrics is null', () => {
+    // makeRegistry defaults metrics to null; call must not throw.
+    expect(() =>
+      detectTileNeedsRepeatSampler(
+        makeRegistry({}),
+        mat({ passes: [spritePass], values: { sliceMode: 1, sampler: 'g' } }),
+      ),
+    ).not.toThrow();
+  });
+
+  it('increments the metric when a tile sampler is not repeat/repeat', () => {
+    const counts: string[] = [];
+    const catalog = new Map<string, unknown>([
+      [
+        's-guid',
+        {
+          kind: 'sampler',
+          payload: { kind: 'sampler', addressModeU: 'clamp', addressModeV: 'repeat' },
+        },
+      ],
+    ]);
+    const reg = makeRegistry({}, { metrics: { increment: (k) => counts.push(k) }, catalog });
+    detectTileNeedsRepeatSampler(
+      reg,
+      mat({ passes: [spritePass], values: { sliceMode: 1, sampler: 'S-GUID' } }),
+    );
+    expect(counts).toContain('nineslice.tile-needs-repeat-sampler');
+  });
+
+  it('does not increment when the sampler is repeat/repeat', () => {
+    const counts: string[] = [];
+    const catalog = new Map<string, unknown>([
+      [
+        's-guid',
+        {
+          kind: 'sampler',
+          payload: { kind: 'sampler', addressModeU: 'repeat', addressModeV: 'repeat' },
+        },
+      ],
+    ]);
+    const reg = makeRegistry({}, { metrics: { increment: (k) => counts.push(k) }, catalog });
+    detectTileNeedsRepeatSampler(
+      reg,
+      mat({ passes: [spritePass], values: { sliceMode: 1, sampler: 's-guid' } }),
+    );
+    expect(counts).toEqual([]);
+  });
+
+  it('no-ops for sliceMode !== 1', () => {
+    const counts: string[] = [];
+    const reg = makeRegistry({}, { metrics: { increment: (k) => counts.push(k) } });
+    detectTileNeedsRepeatSampler(reg, mat({ passes: [spritePass], values: { sliceMode: 0 } }));
+    expect(counts).toEqual([]);
+  });
+});
+
+describe('materialShaderTextureFieldNames', () => {
+  it('returns the texture field-name set derived from paramSchema', () => {
+    const reg = makeRegistry({
+      'forgeax::x': [
+        { name: 'roughness', type: 'f32' },
+        { name: 'baseColorTexture', type: 'texture2d' },
+      ],
+    });
+    const names = materialShaderTextureFieldNames(reg, 'forgeax::x');
+    expect(names).toBeDefined();
+    expect(names?.has('baseColorTexture')).toBe(true);
+    expect(names?.has('roughness')).toBe(false);
+  });
+
+  it('returns undefined for an unregistered shader', () => {
+    expect(materialShaderTextureFieldNames(makeRegistry({}), 'forgeax::nope')).toBeUndefined();
+  });
+});

package/src/__tests__/video-pack-loader.integration.test.ts

@@ -0,0 +1,83 @@
+// M59: exercise the Pack v2 video loader through AssetRegistry's default
+// registry, including failure cleanup and same-GUID invalidate/reload.
+
+import { describe, expect, it, vi } from 'vitest';
+import { AssetRegistry } from '../asset-registry';
+
+const GUID = 'f1b3d000-1111-4aaa-9eee-aa1111112222';
+
+describe('Pack v2 video loader recovery', () => {
+  it('fails before publication, then retries the same GUID with a repaired descriptor', async () => {
+    const registry = new AssetRegistry({} as never);
+    expect(registry.loaders.get('video')).toBeDefined();
+    registry.configurePackIndex('/pack-index.json');
+
+    let repaired = false;
+    const fetchCalls: string[] = [];
+    const originalFetch = globalThis.fetch;
+    vi.stubGlobal('fetch', async (input: RequestInfo | URL) => {
+      const url = String(input);
+      fetchCalls.push(url);
+      if (url.endsWith('/pack-index.json')) {
+        return new Response(
+          JSON.stringify([
+            {
+              guid: GUID,
+              packageUrl: '/video.pack.json',
+              kind: 'video',
+              sourcePath: 'cutscene.webm',
+            },
+          ]),
+        );
+      }
+      if (!url.endsWith('/video.pack.json')) {
+        throw new Error(`unexpected media fetch: ${url}`);
+      }
+      return new Response(
+        JSON.stringify({
+          schemaVersion: '2.0.0',
+          kind: 'internal-text-package',
+          assets: [
+            {
+              guid: GUID,
+              kind: 'video',
+              payload: {
+                url: repaired ? '/cutscene.webm' : 'javascript:alert(1)',
+              },
+              refs: [],
+              artifacts: {},
+            },
+          ],
+        }),
+      );
+    });
+
+    try {
+      const first = await registry.loadByGuid(registry.parseGuid(GUID));
+      expect(first.ok).toBe(false);
+      if (first.ok) return;
+      expect(first.error.code).toBe('asset-parse-failed');
+      expect(registry.lookup(GUID)).toBeUndefined();
+      expect(registry.assetCatalog.has(GUID)).toBe(false);
+      expect(fetchCalls).toEqual(['/pack-index.json', '/video.pack.json']);
+
+      repaired = true;
+      registry.invalidate(GUID);
+      const retried = await registry.loadByGuid(registry.parseGuid(GUID));
+      expect(retried).toEqual({ ok: true, value: { kind: 'video', url: '/cutscene.webm' } });
+      expect(registry.lookup(GUID)).toEqual({ kind: 'video', url: '/cutscene.webm' });
+      expect(registry.assetCatalog.get(GUID)?.payload).toEqual({
+        kind: 'video',
+        url: '/cutscene.webm',
+      });
+      expect(fetchCalls).toEqual([
+        '/pack-index.json',
+        '/video.pack.json',
+        '/pack-index.json',
+        '/video.pack.json',
+      ]);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+});