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

package/src/__tests__/artifact-integrity.unit.test.ts

@@ -0,0 +1,99 @@
+import type { ArtifactDescriptor } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { readArtifact } from '../registry/artifact-io';
+
+const GUID = '22222222-2222-4222-8222-222222222222';
+
+describe('artifact integrity and outer encoding', () => {
+  it('rejects an artifact without a durable media type', async () => {
+    const fetcher = vi.fn().mockResolvedValue(new Response(Uint8Array.of(1)));
+    const result = await readArtifact(
+      {
+        packageUrl: 'https://example.test/pkg.pack.json',
+        guid: GUID,
+        artifactKey: 'payload',
+        descriptor: {
+          path: 'payload.bin',
+          mediaType: '',
+        },
+      },
+      fetcher,
+    );
+
+    expect(result.ok).toBe(false);
+    expect(fetcher).not.toHaveBeenCalled();
+    if (!result.ok) expect(result.error.code).toBe('asset-artifact-media-unsupported');
+  });
+
+  it('checks byte length and integrity after outer decoding', async () => {
+    const descriptor: ArtifactDescriptor = {
+      path: 'payload.bin',
+      mediaType: 'application/octet-stream',
+      contentEncoding: 'identity',
+      byteLength: 3,
+      integrity: {
+        algorithm: 'sha256',
+        digest: 'sha256-of-decoded-bytes',
+      },
+    };
+    const result = await readArtifact(
+      {
+        packageUrl: 'https://example.test/pkg.pack.json',
+        guid: GUID,
+        artifactKey: 'payload',
+        descriptor,
+      },
+      vi.fn().mockResolvedValue(new Response(Uint8Array.of(1, 2, 3))),
+    );
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('asset-artifact-integrity-mismatch');
+      expect(result.error.expected).toContain('sha256');
+      expect(result.error.detail.observed).toBeTruthy();
+    }
+  });
+
+  it('reports a same-sized published artifact with the wrong digest as an integrity mismatch', async () => {
+    const result = await readArtifact(
+      {
+        packageUrl: 'https://example.test/pkg.pack.json',
+        guid: GUID,
+        artifactKey: 'shader',
+        descriptor: {
+          path: 'shader.wgsl',
+          mediaType: 'text/wgsl',
+          byteLength: 4,
+          integrity: { algorithm: 'sha256', digest: 'sha256:published-digest' },
+        },
+      },
+      vi.fn().mockResolvedValue(new Response(Uint8Array.of(1, 2, 3, 4))),
+    );
+
+    expect(result).toMatchObject({
+      ok: false,
+      error: { code: 'asset-artifact-integrity-mismatch' },
+    });
+  });
+
+  it('does not pass asset codec names to the outer decoder', async () => {
+    const fetcher = vi.fn().mockResolvedValue(new Response(Uint8Array.of(7, 8)));
+    const result = await readArtifact(
+      {
+        packageUrl: 'https://example.test/pkg.pack.json',
+        guid: GUID,
+        artifactKey: 'texture',
+        descriptor: {
+          path: 'texture.data',
+          mediaType: 'image/ktx2',
+          assetCodec: { name: 'basis', profile: 'etc1s' },
+          contentEncoding: 'identity',
+        },
+      },
+      fetcher,
+    );
+
+    expect(result).toEqual({ ok: true, value: Uint8Array.of(7, 8) });
+    expect(fetcher).toHaveBeenCalledTimes(1);
+  });
+});

package/src/__tests__/artifact-io.unit.test.ts

@@ -0,0 +1,127 @@
+import type { ArtifactDescriptor } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { readArtifact } from '../registry/artifact-io';
+
+const GUID = '11111111-1111-4111-8111-111111111111';
+
+function descriptor(path: string, changes: Partial<ArtifactDescriptor> = {}): ArtifactDescriptor {
+  return { path, mediaType: 'application/octet-stream', ...changes };
+}
+
+function response(bytes: Uint8Array, ok = true): Response {
+  const body = new ArrayBuffer(bytes.byteLength);
+  new Uint8Array(body).set(bytes);
+  return new Response(body, { status: ok ? 200 : 404 });
+}
+
+describe('artifact I/O', () => {
+  it('rejects an empty media type before fetching artifact bytes', async () => {
+    const fetcher = vi.fn();
+    const result = await readArtifact(
+      {
+        packageUrl: 'https://example.test/packages/main.pack.json',
+        guid: GUID,
+        artifactKey: 'source',
+        descriptor: descriptor('payload.bin', { mediaType: '' }),
+      },
+      fetcher,
+    );
+
+    expect(result.ok).toBe(false);
+    expect(fetcher).not.toHaveBeenCalled();
+    if (!result.ok) expect(result.error.code).toBe('asset-artifact-media-unsupported');
+  });
+
+  it.each([
+    '../outside.bin',
+    '%2e%2e/outside.bin',
+    '%252e%252e/outside.bin',
+    '/absolute.bin',
+    'https://evil.example/outside.bin',
+    '..\\outside.bin',
+  ])('rejects unsafe locator %s before reading', async (path) => {
+    const fetcher = vi.fn();
+    const result = await readArtifact(
+      {
+        packageUrl: 'https://example.test/packages/main.pack.json',
+        guid: GUID,
+        artifactKey: 'source',
+        descriptor: descriptor(path),
+      },
+      fetcher,
+    );
+
+    expect(result.ok).toBe(false);
+    expect(fetcher).not.toHaveBeenCalled();
+    if (!result.ok) {
+      expect(result.error.code).toBe('asset-artifact-path-invalid');
+      expect(result.error.detail.guid).toBe(GUID);
+      expect(result.error.detail.artifactKey).toBe('source');
+      expect(result.error.hint).toContain('package-relative');
+    }
+  });
+
+  it('reads a normalized package-relative artifact and preserves asset codec metadata as data', async () => {
+    const fetcher = vi.fn().mockResolvedValue(response(Uint8Array.of(1, 2, 3)));
+    const result = await readArtifact(
+      {
+        packageUrl: 'https://example.test/packages/main.pack.json',
+        guid: GUID,
+        artifactKey: 'source',
+        descriptor: descriptor('./payload.bin', {
+          mediaType: 'image/ktx2',
+          assetCodec: { name: 'basis', profile: 'uastc' },
+          contentEncoding: 'identity',
+        }),
+      },
+      fetcher,
+    );
+
+    expect(result).toEqual({ ok: true, value: Uint8Array.of(1, 2, 3) });
+    expect(fetcher).toHaveBeenCalledWith('https://example.test/packages/payload.bin');
+  });
+
+  it('returns structured missing, encoding, and integrity failures', async () => {
+    const missing = await readArtifact(
+      {
+        packageUrl: 'https://example.test/main.pack.json',
+        guid: GUID,
+        artifactKey: 'source',
+        descriptor: descriptor('missing.bin'),
+      },
+      vi.fn().mockResolvedValue(response(new Uint8Array(), false)),
+    );
+    expect(missing.ok).toBe(false);
+    if (!missing.ok) expect(missing.error.code).toBe('asset-artifact-missing');
+
+    const unsupported = await readArtifact(
+      {
+        packageUrl: 'https://example.test/main.pack.json',
+        guid: GUID,
+        artifactKey: 'source',
+        descriptor: descriptor('payload.bin', { contentEncoding: 'brotli' as never }),
+      },
+      vi.fn(),
+    );
+    expect(unsupported.ok).toBe(false);
+    if (!unsupported.ok) expect(unsupported.error.code).toBe('asset-artifact-encoding-unsupported');
+
+    const integrity = await readArtifact(
+      {
+        packageUrl: 'https://example.test/main.pack.json',
+        guid: GUID,
+        artifactKey: 'source',
+        descriptor: descriptor('payload.bin', {
+          integrity: { algorithm: 'sha256', digest: 'not-the-digest' },
+        }),
+      },
+      vi.fn().mockResolvedValue(response(Uint8Array.of(1, 2, 3))),
+    );
+    expect(integrity.ok).toBe(false);
+    if (!integrity.ok) {
+      expect(integrity.error.code).toBe('asset-artifact-integrity-mismatch');
+      expect(integrity.error.detail.guid).toBe(GUID);
+      expect(integrity.error.detail.artifactKey).toBe('source');
+    }
+  });
+});

package/src/__tests__/asset-evidence-sdk.integration.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { createRuntimeAssetEvidenceAdapter } from '../registry/asset-evidence.js';
+
+const guid = '11111111-1111-4111-8111-111111111111';
+
+describe('AssetEvidence SDK integration', () => {
+  it('uses the same projector shape for inspect and verifyByGuid', async () => {
+    const adapter = createRuntimeAssetEvidenceAdapter({
+      evidence: async () => ({
+        guid,
+        source: { origin: 'sourceMeta', inputFingerprint: 'fp-1' },
+        locator: { packageUrl: '/assets/config.pack.json' },
+        receipt: {
+          guid,
+          origin: 'sourceMeta',
+          status: 'succeeded',
+          inputFingerprint: 'fp-1',
+          outputDigest: 'digest-1',
+        },
+        packageVerification: { status: 'passed', digest: 'digest-1' },
+        artifacts: {},
+        runtime: { status: 'ready' },
+      }),
+    });
+
+    const inspected = await adapter.inspect(guid);
+    const verified = await adapter.verifyByGuid(guid);
+    expect(inspected.ok).toBe(true);
+    expect(verified.ok).toBe(true);
+    expect(inspected).toEqual(verified);
+  });
+});

package/src/__tests__/asset-evidence.unit.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from 'vitest';
+import { createRuntimeAssetEvidenceAdapter } from '../registry/asset-evidence.js';
+
+const guid = '11111111-1111-4111-8111-111111111111';
+
+describe('runtime AssetEvidence adapter', () => {
+  it('uses injected runtime state and leaves missing capability explicit', async () => {
+    const adapter = createRuntimeAssetEvidenceAdapter({
+      evidence: async (requestedGuid) => ({
+        guid: requestedGuid,
+        source: { origin: 'sourceMeta', inputFingerprint: 'fp-1' },
+        locator: { packageUrl: '/assets/data.pack.json' },
+        receipt: {
+          guid: requestedGuid,
+          origin: 'sourceMeta',
+          status: 'succeeded',
+          inputFingerprint: 'fp-1',
+          outputDigest: 'digest-1',
+        },
+        packageVerification: { status: 'passed', digest: 'digest-1' },
+        artifacts: {},
+      }),
+    });
+
+    const result = await adapter.verifyByGuid(guid);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.guid).toBe(guid);
+    expect(result.value.runtime.status).toBe('unknown');
+    expect(result.value.cook.freshness).toBe('current');
+  });
+});

package/src/__tests__/asset-kind.unit.test.ts

@@ -0,0 +1,14 @@
+import type { AssetKindPayload } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { defineAssetKind } from '../index.js';
+
+describe('defineAssetKind', () => {
+  it('freezes the runtime kind witness while preserving its payload type', () => {
+    const kind = defineAssetKind<{ readonly lines: readonly string[] }, 'dialogue'>('dialogue');
+    const payload: AssetKindPayload<typeof kind> = { lines: ['hello'] };
+
+    expect(kind).toEqual({ kind: 'dialogue' });
+    expect(Object.isFrozen(kind)).toBe(true);
+    expect(payload.lines).toEqual(['hello']);
+  });
+});

package/src/__tests__/asset-registry-catalog-reconcile.integration.test.ts

@@ -0,0 +1,74 @@
+import { err, ok } from '@forgeax/engine-rhi';
+import { AssetError, type CatalogDelta, type CatalogEntry } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { AssetRegistry, type CatalogReconcileResult } from '../index.js';
+
+const baselineEntry = {
+  guid: '22222222-2222-4222-8222-222222222222',
+  kind: 'mesh',
+  sourcePath: 'failed.glb',
+  packageUrl: '/preview/packages/failed',
+  revision: { digest: 'sha256:baseline', observedAt: 3, rootId: 'root-failed' },
+} as const satisfies CatalogEntry;
+
+function registry(): AssetRegistry {
+  return new AssetRegistry({} as never);
+}
+
+describe('AssetRegistry.reconcileCatalog recovery integration', () => {
+  it('preserves stale gap diagnostics and the source error without silent refresh', async () => {
+    let listener: ((delta: CatalogDelta) => void) | undefined;
+    const failure = new AssetError({
+      code: 'asset-fetch-failed',
+      expected: 'an authoritative catalog enumeration',
+      hint: 'restore the catalog source and reconcile again',
+    });
+    const enumerate = vi
+      .fn()
+      .mockResolvedValueOnce(ok([baselineEntry]))
+      .mockResolvedValueOnce(err(failure));
+    const writeMeta = vi.fn();
+    const writeSourceBytes = vi.fn();
+    const assets = registry();
+    const source = {
+      enumerate,
+      subscribe(next: (delta: CatalogDelta) => void) {
+        listener = next;
+        return () => {
+          listener = undefined;
+        };
+      },
+      writeMeta,
+      writeSourceBytes,
+    };
+    assets.setCatalogSource(source);
+    await assets.enumerateCatalog();
+    listener?.({
+      added: [],
+      changed: [],
+      removed: [],
+      authority: 'degraded',
+      diagnostics: [
+        {
+          code: 'catalog-gap',
+          severity: 'blocking',
+          expected: 'contiguous producer revisions',
+          hint: 'reconcile',
+        },
+      ],
+    });
+    const refreshCatalog = vi.spyOn(assets, 'refreshCatalog');
+
+    const result: CatalogReconcileResult = await assets.reconcileCatalog();
+
+    expect(result).toEqual({ ok: false, error: failure });
+    expect(assets.catalogSnapshot()).toMatchObject({
+      stale: true,
+      diagnostics: [{ code: 'catalog-gap', severity: 'blocking' }],
+      entries: [{ guid: baselineEntry.guid, revision: baselineEntry.revision }],
+    });
+    expect(refreshCatalog).not.toHaveBeenCalled();
+    expect(writeMeta).not.toHaveBeenCalled();
+    expect(writeSourceBytes).not.toHaveBeenCalled();
+  });
+});

package/src/__tests__/asset-registry-catalog-reconcile.unit.test.ts

@@ -0,0 +1,89 @@
+import { ok } from '@forgeax/engine-rhi';
+import { ASSET_ERROR_HINTS, type CatalogDelta, type CatalogEntry } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  AssetRegistry,
+  type CatalogReconcileResult,
+  type CatalogReplicaSnapshot,
+} from '../index.js';
+
+const currentEntry = {
+  guid: '11111111-1111-4111-8111-111111111111',
+  kind: 'mesh',
+  sourcePath: 'model.glb',
+  packageUrl: '/preview/packages/model',
+  revision: { digest: 'sha256:current', observedAt: 7, rootId: 'root-model' },
+  diagnostics: [{ code: 'catalog-current', severity: 'info', hint: 'current revision' }],
+} as const satisfies CatalogEntry;
+
+function registry(): AssetRegistry {
+  return new AssetRegistry({} as never);
+}
+
+describe('AssetRegistry.reconcileCatalog public contract', () => {
+  it('returns the structured unconfigured Result through the package surface', async () => {
+    const assets = registry();
+
+    const result: CatalogReconcileResult = await assets.reconcileCatalog();
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error).toMatchObject({
+      code: 'catalog-source-unconfigured',
+      expected: 'a configured catalog source',
+    });
+    expect(result.error.hint).toBe(ASSET_ERROR_HINTS['catalog-source-unconfigured']);
+  });
+
+  it('returns the same immutable revision snapshot without authoring writes', async () => {
+    let listener: ((delta: CatalogDelta) => void) | undefined;
+    const writeMeta = vi.fn();
+    const writeSourceBytes = vi.fn();
+    const sourceBytes = new Uint8Array([1, 2, 3, 4]);
+    const originalSourceBytes = sourceBytes.slice();
+    const source = {
+      enumerate: vi.fn(async () => ok([currentEntry])),
+      subscribe(next: (delta: CatalogDelta) => void) {
+        listener = next;
+        return () => {
+          listener = undefined;
+        };
+      },
+      writeMeta,
+      writeSourceBytes,
+    };
+    const assets = registry();
+    assets.setCatalogSource(source);
+    await assets.enumerateCatalog();
+    listener?.({
+      added: [],
+      changed: [],
+      removed: [],
+      authority: 'degraded',
+      diagnostics: [{ code: 'catalog-gap', severity: 'blocking', hint: 'reconcile' }],
+    });
+
+    const result: CatalogReconcileResult = await assets.reconcileCatalog();
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const snapshot: CatalogReplicaSnapshot = result.value;
+    expect(snapshot).toBe(assets.catalogSnapshot());
+    expect(snapshot).toMatchObject({
+      stale: false,
+      diagnostics: [],
+      entries: [
+        {
+          guid: currentEntry.guid,
+          revision: currentEntry.revision,
+          diagnostics: currentEntry.diagnostics,
+        },
+      ],
+    });
+    expect(Object.isFrozen(snapshot)).toBe(true);
+    expect(Object.isFrozen(snapshot.entries)).toBe(true);
+    expect(writeMeta).not.toHaveBeenCalled();
+    expect(writeSourceBytes).not.toHaveBeenCalled();
+    expect(sourceBytes).toEqual(originalSourceBytes);
+  });
+});

package/src/__tests__/asset-registry-catalog.unit.test.ts

@@ -0,0 +1,170 @@
+import { ok } from '@forgeax/engine-rhi';
+import type { CatalogDelta } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { AssetRegistry } from '../asset-registry';
+import { createCatalogSource } from '../catalog-source';
+import { parseCatalog } from '../registry/catalog';
+
+function registry(): AssetRegistry {
+  return new AssetRegistry({} as never);
+}
+
+const packageRow = {
+  guid: '11111111-1111-4111-8111-111111111111',
+  kind: 'mesh',
+  sourcePath: 'model.glb',
+  packageUrl: '/preview/packages/model',
+};
+
+describe('AssetRegistry.enumerateCatalog', () => {
+  it('exposes packageUrl navigation from the configured catalog source', async () => {
+    const assets = registry();
+    assets.setCatalogSource({
+      enumerate: async () => ok([packageRow]),
+      subscribe: () => () => {},
+    });
+
+    const result = await assets.enumerateCatalog();
+
+    expect(result).toEqual({ ok: true, value: [packageRow] });
+  });
+
+  it('shares concurrent reads and retries after a failed source read', async () => {
+    const enumerate = vi
+      .fn()
+      .mockResolvedValueOnce({ ok: false, error: { code: 'asset-fetch-failed' } })
+      .mockResolvedValueOnce(ok([]));
+    const source = { enumerate, subscribe: () => () => {} };
+    const assets = registry();
+    assets.setCatalogSource(source);
+
+    const [first, second] = await Promise.all([
+      assets.enumerateCatalog(),
+      assets.enumerateCatalog(),
+    ]);
+    expect(first.ok).toBe(false);
+    expect(second.ok).toBe(false);
+    expect(enumerate).toHaveBeenCalledTimes(1);
+    expect((await assets.enumerateCatalog()).ok).toBe(true);
+    expect(enumerate).toHaveBeenCalledTimes(2);
+  });
+
+  it('returns the complete neutral entry from a catalog source', async () => {
+    const entry = {
+      guid: '11111111-1111-4111-8111-111111111111',
+      kind: 'host/blob',
+      packageUrl: '/assets/blob.bin',
+      sourcePath: 'assets/blob.source',
+      packageId: 'pkg/registry',
+      provenance: { provider: 'registry-fixture', version: '1.0.0' },
+      revision: { digest: 'sha256:registry', observedAt: 5, rootId: 'root-registry' },
+      sourceKey: 'blob/main',
+      sourceIndex: 0,
+      relations: [],
+      diagnostics: [{ code: 'registry-note', severity: 'info', hint: 'no action' }],
+    } as const;
+    const assets = registry();
+    assets.setCatalogSource(createCatalogSource({ entries: [entry] }));
+
+    const result = await assets.enumerateCatalog();
+
+    expect(result).toEqual({ ok: true, value: [entry] });
+  });
+
+  it('clears a catalog source and unsubscribes its producer transport', async () => {
+    const listeners = new Set<(delta: CatalogDelta) => void>();
+    const unsubscribe = vi.fn(() => listeners.clear());
+    const source = {
+      enumerate: async () => ok([packageRow]),
+      subscribe: (listener: (delta: CatalogDelta) => void) => {
+        listeners.add(listener);
+        return unsubscribe;
+      },
+    };
+    const assets = registry();
+    const received = vi.fn();
+    assets.setCatalogSource(source);
+    assets.subscribeCatalog(received);
+    await assets.enumerateCatalog();
+
+    assets.clearCatalogSource();
+    assets.clearCatalogSource();
+
+    expect(unsubscribe).toHaveBeenCalledTimes(1);
+    expect((await assets.enumerateCatalog()).ok).toBe(false);
+    for (const listener of listeners) listener({ added: [], changed: [], removed: [] });
+    expect(received).not.toHaveBeenCalled();
+  });
+
+  it('preserves the explicit runtime projection instead of inferring it from locators', () => {
+    const guid = '33333333-3333-4333-8333-333333333333';
+    const raw = [
+      {
+        guid,
+        packageUrl: '/opaque/runtime/asset.ddc',
+        kind: 'particle-effect',
+        sourcePath: 'authoring/boss.pack.json',
+        subject: 'internal-asset',
+        execution: 'cooked',
+        lifecycle: 'current',
+        projection: {
+          subject: 'internal-asset',
+          execution: 'cooked',
+          lifecycle: 'current',
+          operations: {
+            preview: { operation: 'preview', enabled: true },
+            save: { operation: 'save', enabled: false, reason: 'cooked projection' },
+            rebuild: { operation: 'rebuild', enabled: true },
+            sourceOverride: { operation: 'sourceOverride', enabled: false },
+            instanceOverride: { operation: 'instanceOverride', enabled: false },
+            promote: { operation: 'promote', enabled: false },
+          },
+        },
+      },
+    ];
+
+    const result = parseCatalog(raw);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.get(guid)?.subject).toBe('internal-asset');
+    expect(result.value.get(guid)?.execution).toBe('cooked');
+    expect(result.value.get(guid)?.lifecycle).toBe('current');
+    expect(result.value.get(guid)?.projection).toEqual(raw[0]?.projection);
+  });
+
+  it('keeps non-current cooked states explicit even when the locator looks runnable', () => {
+    const guid = '44444444-4444-4444-8444-444444444444';
+    const result = parseCatalog([
+      {
+        guid,
+        packageUrl: '/opaque/runtime/asset.pack.json',
+        kind: 'scene',
+        sourcePath: 'authoring/scene.pack.json',
+        subject: 'internal-asset',
+        execution: 'cooked',
+        lifecycle: 'stale',
+        projection: {
+          subject: 'internal-asset',
+          execution: 'cooked',
+          lifecycle: 'stale',
+          operations: {
+            preview: { operation: 'preview', enabled: true },
+            save: { operation: 'save', enabled: false },
+            rebuild: { operation: 'rebuild', enabled: true },
+            sourceOverride: { operation: 'sourceOverride', enabled: false },
+            instanceOverride: { operation: 'instanceOverride', enabled: false },
+            promote: { operation: 'promote', enabled: false },
+          },
+          lastKnownGood: { packageUrl: '/opaque/runtime/old.pack.json' },
+        },
+      },
+    ]);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    const row = result.value.get(guid);
+    expect(row?.lifecycle).toBe('stale');
+    expect(row?.projection?.lastKnownGood?.packageUrl).toBe('/opaque/runtime/old.pack.json');
+  });
+});