@forgeax/engine-assets-runtime 0.1.3 → 0.1.6

package/src/__tests__/catalog-replica.unit.test.ts

@@ -0,0 +1,196 @@
+import type { CatalogDelta, CatalogEntry } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { CatalogReplica } from '../registry/catalog-state.js';
+
+type EnumerationResult = { readonly ok: true; readonly value: readonly CatalogEntry[] };
+
+const base = {
+  guid: '11111111-1111-4111-8111-111111111111',
+  packageUrl: '/preview/base',
+  packageId: 'fixture-package',
+  kind: 'mesh',
+  sourcePath: 'model.source',
+  sourceKey: 'mesh/main',
+  sourceIndex: 0,
+  provenance: { provider: 'fixture', version: '1' },
+  revision: { digest: 'digest-1', observedAt: 1, rootId: 'fixture-root' },
+  relations: [],
+  lifecycle: 'current' as const,
+  diagnostics: [{ code: 'fixture-note', severity: 'info' as const, hint: 'none' }],
+};
+
+const other = {
+  ...base,
+  guid: '22222222-2222-4222-8222-222222222222',
+  sourceKey: 'mesh/other',
+  sourceIndex: 1,
+  packageUrl: '/preview/other',
+};
+
+function source() {
+  let listener: ((delta: CatalogDelta) => void) | undefined;
+  let enumerate: (() => Promise<EnumerationResult>) | undefined;
+  const source = {
+    subscribe(next: (delta: CatalogDelta) => void) {
+      listener = next;
+      return () => {
+        listener = undefined;
+      };
+    },
+    enumerate() {
+      return enumerate?.() ?? Promise.resolve({ ok: true as const, value: [base] });
+    },
+  };
+  return {
+    source,
+    emit(delta: CatalogDelta) {
+      listener?.(delta);
+    },
+    deferEnumeration() {
+      let resolve!: (result: EnumerationResult) => void;
+      enumerate = () => new Promise((next) => (resolve = next));
+      return (result: EnumerationResult) => resolve(result);
+    },
+  };
+}
+
+describe('CatalogReplica', () => {
+  it('subscribes before enumerate and folds an early delta after the baseline', async () => {
+    const fixture = source();
+    const release = fixture.deferEnumeration();
+    const replica = new CatalogReplica(fixture.source as never);
+    const started = replica.start();
+
+    fixture.emit({ added: [other], changed: [], removed: [] });
+    release({ ok: true, value: [base] });
+    await expect(started).resolves.toMatchObject({ ok: true });
+    expect(replica.snapshot().entries.map((entry) => entry.guid)).toEqual([base.guid, other.guid]);
+  });
+
+  it('is idempotent, rejects older revisions, and preserves complete producer facts', async () => {
+    const fixture = source();
+    const replica = new CatalogReplica(fixture.source as never);
+    await replica.start();
+    const delta = {
+      added: [],
+      changed: [
+        { ...base, packageUrl: '/preview/new', revision: { ...base.revision, observedAt: 2 } },
+      ],
+      removed: [],
+      revisions: {
+        baseline: [{ rootId: 'fixture-root', revision: 1 }],
+        current: [{ rootId: 'fixture-root', revision: 2 }],
+      },
+    };
+
+    fixture.emit(delta);
+    fixture.emit(delta);
+    fixture.emit({
+      ...delta,
+      changed: [
+        { ...base, packageUrl: '/preview/old', revision: { ...base.revision, observedAt: 1 } },
+      ],
+      revisions: {
+        baseline: [{ rootId: 'fixture-root', revision: 2 }],
+        current: [{ rootId: 'fixture-root', revision: 1 }],
+      },
+    });
+
+    const row = replica.snapshot().entries.find((entry) => entry.guid === base.guid);
+    expect(row).toMatchObject({
+      packageUrl: '/preview/new',
+      sourceKey: 'mesh/main',
+      provenance: base.provenance,
+      relations: base.relations,
+      diagnostics: base.diagnostics,
+    });
+    expect(replica.snapshot().version).toBe(1);
+  });
+
+  it('marks degraded gaps stale and reconcile restores the authoritative set', async () => {
+    const fixture = source();
+    const release = fixture.deferEnumeration();
+    const replica = new CatalogReplica(fixture.source as never);
+    const started = replica.start();
+    release({ ok: true, value: [base] });
+    await started;
+
+    fixture.emit({
+      added: [],
+      changed: [],
+      removed: [],
+      authority: 'degraded',
+      diagnostics: [{ code: 'catalog-gap', severity: 'blocking', hint: 'reconcile' }],
+    });
+    expect(replica.snapshot()).toMatchObject({ stale: true });
+
+    const reconciling = replica.reconcile();
+    release({ ok: true, value: [other] });
+    await expect(reconciling).resolves.toMatchObject({ ok: true });
+    expect(replica.snapshot()).toMatchObject({ stale: false, entries: [other] });
+  });
+
+  it('does not publish or apply a changed row whose revision window is stale', async () => {
+    const fixture = source();
+    const replica = new CatalogReplica(fixture.source as never);
+    await replica.start();
+    const received: CatalogDelta[] = [];
+    replica.subscribe((delta) => received.push(delta));
+    const staleEntry = {
+      ...base,
+      packageUrl: '/preview/stale',
+      revision: { ...base.revision, observedAt: 3 },
+    };
+
+    fixture.emit({
+      added: [],
+      changed: [staleEntry],
+      removed: [],
+      revisions: {
+        baseline: [{ rootId: 'fixture-root', revision: 2 }],
+        current: [{ rootId: 'fixture-root', revision: 1 }],
+      },
+    });
+
+    expect(replica.snapshot()).toMatchObject({
+      stale: true,
+      entries: [{ guid: base.guid, packageUrl: base.packageUrl }],
+      diagnostics: [{ code: 'catalog-revision-stale', severity: 'blocking' }],
+    });
+    expect(received).toHaveLength(1);
+    expect(received[0]).toMatchObject({
+      added: [],
+      changed: [],
+      removed: [],
+      authority: 'degraded',
+      diagnostics: [{ code: 'catalog-revision-stale', severity: 'blocking' }],
+    });
+  });
+
+  it('rejects a changed payload that reuses the verified row revision', async () => {
+    const fixture = source();
+    const replica = new CatalogReplica(fixture.source as never);
+    await replica.start();
+    const received: CatalogDelta[] = [];
+    replica.subscribe((delta) => received.push(delta));
+
+    fixture.emit({
+      added: [],
+      changed: [{ ...base, packageUrl: '/preview/unchanged-revision' }],
+      removed: [],
+    });
+
+    expect(replica.snapshot()).toMatchObject({
+      stale: true,
+      entries: [{ guid: base.guid, packageUrl: base.packageUrl }],
+      diagnostics: [{ code: 'catalog-revision-conflict', severity: 'blocking' }],
+    });
+    expect(received[0]).toMatchObject({
+      added: [],
+      changed: [],
+      removed: [],
+      authority: 'degraded',
+      diagnostics: [{ code: 'catalog-revision-conflict', severity: 'blocking' }],
+    });
+  });
+});

package/src/__tests__/catalog-source-v2.unit.test.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it, vi } from 'vitest';
+import { createCatalogSource } from '../catalog-source.js';
+import { parseCatalog } from '../registry/catalog.js';
+
+const packageRow = {
+  guid: '11111111-1111-4111-8111-111111111111',
+  kind: 'mesh',
+  sourcePath: 'model.glb',
+  packageUrl: '/preview/packages/model',
+};
+
+describe('catalog source v2', () => {
+  it('parses packageUrl navigation without reading artifact bytes', () => {
+    const resolveUrl = vi.fn((url: string) => `https://example.test${url}`);
+    const result = parseCatalog([packageRow], resolveUrl);
+
+    expect(result).toEqual({
+      ok: true,
+      value: new Map([
+        [
+          packageRow.guid,
+          {
+            packageUrl: 'https://example.test/preview/packages/model',
+            kind: 'mesh',
+            sourcePath: 'model.glb',
+          },
+        ],
+      ]),
+    });
+    expect(resolveUrl).toHaveBeenCalledWith('/preview/packages/model');
+  });
+
+  it.each([
+    ['missing packageUrl', { ...packageRow, packageUrl: undefined }],
+    ['legacy relativeUrl', { ...packageRow, packageUrl: undefined, relativeUrl: '/asset.bin' }],
+    ['legacy compression', { ...packageRow, compression: 'zstd' }],
+    ['raw source package', { ...packageRow, packageUrl: '/assets/model.glb' }],
+    [
+      'raw particle effect source',
+      { ...packageRow, packageUrl: '/assets/effects/boss.particle-effect.json' },
+    ],
+  ])('rejects %s as a structured catalog failure', (_label, row) => {
+    const result = parseCatalog([row]);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('asset-parse-failed');
+  });
+
+  it('does not fetch an artifact while parsing catalog rows', () => {
+    const fetchArtifact = vi.fn();
+    const result = parseCatalog([packageRow]);
+
+    expect(result.ok).toBe(true);
+    expect(fetchArtifact).not.toHaveBeenCalled();
+  });
+
+  it('preserves producer-owned source override authoring facts', () => {
+    const sourceOverrides = {
+      'mesh/main': {
+        materialSlots: [
+          {
+            slotName: 'Body',
+            sourceKey: 'material/body',
+          },
+        ],
+        materialSlotDefaultOverrides: {
+          'material/body': '22222222-2222-4222-8222-222222222222',
+        },
+      },
+    } as const;
+    const sourceOverrideDescriptors = [
+      { sourceKey: 'mesh/main', payloadSchema: { type: 'object' } },
+    ] as const;
+    const result = parseCatalog([
+      { ...packageRow, sourceKey: 'mesh/main', sourceOverrides, sourceOverrideDescriptors },
+    ]);
+
+    expect(result).toEqual({
+      ok: true,
+      value: new Map([
+        [
+          packageRow.guid,
+          {
+            packageUrl: packageRow.packageUrl,
+            kind: packageRow.kind,
+            sourcePath: packageRow.sourcePath,
+            sourceKey: 'mesh/main',
+            sourceOverrides,
+            sourceOverrideDescriptors,
+          },
+        ],
+      ]),
+    });
+  });
+
+  it('preserves the complete source publication tuple for runtime fence consumers', () => {
+    const publication = {
+      schemaVersion: 'asset-publication/1' as const,
+      sourcePath: 'assets/showcase.pack.ts',
+      sourceRevision: 'sha256:source',
+      generation: 3,
+      digest: 'sha256:output',
+      outputSetDigest: 'sha256:output-set',
+      outputs: [
+        {
+          guid: packageRow.guid,
+          sourceKey: 'mesh/main',
+          kind: 'mesh',
+          digest: 'sha256:mesh',
+          refs: [],
+        },
+      ],
+      receipt: {
+        schemaVersion: 'asset-publication-receipt/1' as const,
+        sourcePath: 'assets/showcase.pack.ts',
+        sourceRevision: 'sha256:source',
+        inputFingerprint: 'sha256:source',
+        outputDigest: 'sha256:output',
+        outputSetDigest: 'sha256:output-set',
+        externalEvidence: [],
+      },
+      externalEvidence: [],
+      current: {
+        generation: 3,
+        digest: 'sha256:output',
+        outputSetDigest: 'sha256:output-set',
+        packageUrl: packageRow.packageUrl,
+        receiptKey: 'sha256:source',
+      },
+    };
+    const result = parseCatalog([{ ...packageRow, publication }]);
+
+    expect(result).toEqual({
+      ok: true,
+      value: new Map([
+        [
+          packageRow.guid,
+          {
+            kind: packageRow.kind,
+            packageUrl: packageRow.packageUrl,
+            sourcePath: packageRow.sourcePath,
+            publication,
+          },
+        ],
+      ]),
+    });
+  });
+
+  it('fetches only the catalog source and preserves package navigation', async () => {
+    const fetch = vi.fn().mockResolvedValue({ ok: true, json: async () => [packageRow] });
+    const source = createCatalogSource({ url: '/preview/pack-index.json', fetch });
+
+    const result = await source.enumerate();
+
+    expect(result).toEqual({ ok: true, value: [packageRow] });
+    expect(fetch).toHaveBeenCalledWith('/preview/pack-index.json');
+  });
+});

package/src/__tests__/catalog-source.unit.test.ts

@@ -0,0 +1,126 @@
+import type { CatalogEntry } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { createCatalogSource } from '../catalog-source';
+import { parseCatalog } from '../registry/catalog';
+
+const entry: CatalogEntry = {
+  guid: '11111111-1111-4111-8111-111111111111',
+  kind: 'mesh',
+  name: 'unloaded',
+  packageUrl: '/assets/unloaded.pack.json',
+  sourcePath: 'assets/unloaded.glb',
+};
+
+const richEntry: CatalogEntry = {
+  ...entry,
+  packageId: 'pkg/runtime',
+  provenance: { provider: 'runtime-fixture', version: '1.0.0' },
+  revision: { digest: 'sha256:runtime', observedAt: 3, rootId: 'root-runtime' },
+  sourceKey: 'runtime/main',
+  sourceIndex: 0,
+  relations: [
+    {
+      from: { type: 'asset', id: '11111111-1111-4111-8111-111111111111' },
+      to: { type: 'asset', id: '22222222-2222-4222-8222-222222222222' },
+      type: 'references',
+      provenance: { provider: 'runtime-fixture', version: '1.0.0' },
+    },
+  ],
+  diagnostics: [{ code: 'runtime-warning', severity: 'warning', hint: 'refresh catalog' }],
+};
+
+describe('CatalogSource', () => {
+  it('enumerates every development or build row without loading its payload', async () => {
+    for (const url of ['/__pack/index', '/pack-index.json']) {
+      const fetch = vi.fn().mockResolvedValue({ ok: true, json: async () => [entry] });
+      const source = createCatalogSource({ url, fetch });
+      const result = await source.enumerate();
+
+      expect(result).toEqual({ ok: true, value: [entry] });
+      expect(fetch).toHaveBeenCalledWith(url);
+    }
+  });
+
+  it('reports an unconfigured source instead of an empty catalog', async () => {
+    const result = await createCatalogSource({}).enumerate();
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('catalog-source-unconfigured');
+  });
+
+  it('uses the shared parser to distinguish malformed JSON from a fetch failure', async () => {
+    const fetch = vi.fn().mockResolvedValue({ ok: true, json: async () => ({ entries: [] }) });
+
+    const result = await createCatalogSource({ url: '/pack-index.json', fetch }).enumerate();
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('asset-parse-failed');
+  });
+
+  it('keeps static and URL catalog rows in the same producer-fact shape', async () => {
+    const fetch = vi.fn().mockResolvedValue({ ok: true, json: async () => [richEntry] });
+    const source = createCatalogSource({ url: '/pack-index.json', fetch });
+    const urlResult = await source.enumerate();
+    const staticResult = await createCatalogSource({ entries: [richEntry] }).enumerate();
+
+    expect(urlResult).toEqual(staticResult);
+    expect(urlResult).toEqual({ ok: true, value: [richEntry] });
+  });
+
+  it('rejects a catalog row without a locator instead of returning an empty catalog', () => {
+    const result = parseCatalog([
+      {
+        guid: richEntry.guid,
+        kind: richEntry.kind,
+        packageId: richEntry.packageId,
+      },
+    ]);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('asset-parse-failed');
+      expect(result.error.expected).toContain('packageUrl');
+      expect(result.error.hint).toBeTruthy();
+    }
+  });
+
+  it('reports a stale revision through structured fields', async () => {
+    const fetch = vi.fn().mockResolvedValue({ ok: true, json: async () => [richEntry] });
+    const result = await createCatalogSource({
+      url: '/pack-index.json',
+      fetch,
+      expectedRevision: { digest: 'sha256:expected', observedAt: 4, rootId: 'root-runtime' },
+    }).enumerate();
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('asset-parse-failed');
+      expect(result.error.expected).toContain('revision');
+      expect(result.error.hint).toContain('verified');
+      expect(result.error.detail).toMatchObject({
+        expectedRevision: { digest: 'sha256:expected' },
+        actualRevisions: [{ digest: 'sha256:runtime' }],
+      });
+    }
+  });
+
+  it('uses an idempotent no-op subscription for static catalogs', () => {
+    const source = createCatalogSource({ entries: [entry] });
+    const listener = vi.fn();
+    const dispose = source.subscribe(listener);
+
+    dispose();
+    dispose();
+    expect(listener).not.toHaveBeenCalled();
+  });
+
+  it('forwards an optional catalog subscription', () => {
+    const listener = vi.fn();
+    const unsubscribe = vi.fn();
+    const subscribe = vi.fn(() => unsubscribe);
+    const source = createCatalogSource({ subscribe });
+
+    expect(source.subscribe(listener)).toBe(unsubscribe);
+    expect(subscribe).toHaveBeenCalledWith(listener);
+  });
+});

package/src/__tests__/catalog-subscription-order.unit.test.ts

@@ -0,0 +1,65 @@
+import type { CatalogDelta, CatalogEntry } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { CatalogReplica } from '../registry/catalog-state.js';
+
+const entry: CatalogEntry = {
+  guid: '11111111-1111-4111-8111-111111111111',
+  packageUrl: '/preview/fixture',
+  kind: 'mesh',
+  sourcePath: 'fixture.source',
+};
+
+describe('CatalogReplica subscription order', () => {
+  it('does not lose an early delta and does not double-deliver a listener', async () => {
+    const listeners = new Set<(delta: CatalogDelta) => void>();
+    const source = {
+      enumerate: async () => ({ ok: true as const, value: [entry] }),
+      subscribe: vi.fn((listener: (delta: CatalogDelta) => void) => {
+        listeners.add(listener);
+        return () => listeners.delete(listener);
+      }),
+    };
+    const replica = new CatalogReplica(source as never);
+    const received: CatalogDelta[] = [];
+    const dispose = replica.subscribe((delta) => received.push(delta));
+    await replica.start();
+
+    const delta: CatalogDelta = { added: [], changed: [entry], removed: [] };
+    for (const listener of listeners) listener(delta);
+    expect(received).toHaveLength(1);
+    dispose();
+    dispose();
+    for (const listener of listeners) listener(delta);
+    expect(received).toHaveLength(1);
+    expect(source.subscribe).toHaveBeenCalledTimes(1);
+  });
+
+  it('returns structured enumerate failure and can recover through reconcile', async () => {
+    const enumerate = vi
+      .fn()
+      .mockResolvedValueOnce({
+        ok: false as const,
+        error: {
+          code: 'catalog-enumerate-failed',
+          expected: 'a readable producer catalog',
+          hint: 'call reconcile after restoring the source',
+        },
+      })
+      .mockResolvedValueOnce({ ok: true as const, value: [entry] });
+    const replica = new CatalogReplica({ enumerate, subscribe: () => () => {} } as never);
+
+    const first = await replica.start();
+    expect(first).toMatchObject({
+      ok: false,
+      error: {
+        code: 'catalog-enumerate-failed',
+        expected: 'a readable producer catalog',
+        hint: expect.any(String),
+      },
+    });
+    expect(replica.snapshot().stale).toBe(true);
+    await expect(replica.reconcile()).resolves.toMatchObject({ ok: true });
+    expect(replica.snapshot()).toMatchObject({ stale: false, entries: [entry] });
+    expect(enumerate).toHaveBeenCalledTimes(2);
+  });
+});

package/src/__tests__/catalog-subscription.unit.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it, vi } from 'vitest';
+import { AssetRegistry } from '../asset-registry';
+
+describe('AssetRegistry.subscribeCatalog', () => {
+  it('isolates throwing listeners and makes unsubscribe idempotent', () => {
+    let emit: ((delta: { added: []; changed: []; removed: [] }) => void) | undefined;
+    const source = {
+      enumerate: async () => ({ ok: true as const, value: [] }),
+      subscribe: (listener: typeof emit) => {
+        emit = listener;
+        return () => {};
+      },
+    };
+    const assets = new AssetRegistry({} as never);
+    assets.setCatalogSource(source as never);
+    const broken = vi.fn(() => {
+      throw new Error('listener failed');
+    });
+    const received = vi.fn();
+    const dispose = assets.subscribeCatalog(broken);
+    assets.subscribeCatalog(received);
+
+    emit?.({ added: [], changed: [], removed: [] });
+    expect(received).toHaveBeenCalledTimes(1);
+    dispose();
+    dispose();
+  });
+});

package/src/__tests__/decode-image-bytes-pass-through.test.ts

@@ -0,0 +1,34 @@
+// @forgeax/engine-assets-runtime -- decoder error pass-through regression
+
+import type { ImageError } from '@forgeax/engine-types';
+import { err } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { decodeImageBytes } from '../decode-image-bytes';
+
+vi.mock('@forgeax/engine-image', () => ({
+  decodeImageInBrowser: vi.fn(),
+}));
+
+describe('decodeImageBytes decoder error pass-through', () => {
+  it('returns the decoder ImageError object unchanged', async () => {
+    const { decodeImageInBrowser } = await import('@forgeax/engine-image');
+    const decoderError = {
+      name: 'ImageError',
+      message: 'decoder failure',
+      code: 'image-decode-failed',
+      expected: 'decoder expected',
+      hint: 'decoder hint',
+      detail: {
+        code: 'image-decode-failed',
+        reason: 'decoder failure',
+      },
+    } as ImageError;
+    vi.mocked(decodeImageInBrowser).mockResolvedValue(err(decoderError));
+
+    const result = await decodeImageBytes(new Uint8Array([1]), 'image/png');
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error).toBe(decoderError);
+  });
+});