@forgeax/engine-assets-runtime 0.1.4 → 0.1.6

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.test.ts → asset-kind.unit.test.ts}

@@ -1,6 +1,6 @@
 import type { AssetKindPayload } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
-import { defineAssetKind } from '../asset-kind.js';
+import { defineAssetKind } from '../index.js';
 
 describe('defineAssetKind', () => {
   it('freezes the runtime kind witness while preserving its payload type', () => {

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');
+  });
+});

package/src/__tests__/asset-registry.pack-cache.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it, vi } from 'vitest';
+import { AssetRegistry } from '../asset-registry';
+
+const GUID = 'cccccccc-cccc-4ccc-8ccc-cccccccccccc';
+
+describe('asset registry cache cleanup', () => {
+  it('clears failed package and in-flight state so a retry can succeed', async () => {
+    const registry = new AssetRegistry({} as never);
+    registry.loaders.register({
+      kind: 'host-blob',
+      load: (payload) => ({ kind: 'host-blob', ...payload }),
+    });
+    registry.configurePackIndex('/pack-index.json');
+    let attempts = 0;
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async (url: string) => {
+        if (url.endsWith('pack-index.json')) {
+          return new Response(
+            JSON.stringify([
+              {
+                guid: GUID,
+                packageUrl: '/asset.pack.json',
+                kind: 'host-blob',
+                sourcePath: 'asset',
+              },
+            ]),
+          );
+        }
+        attempts += 1;
+        if (attempts === 1) return new Response('missing', { status: 404 });
+        return new Response(
+          JSON.stringify({
+            schemaVersion: '2.0.0',
+            kind: 'internal-text-package',
+            assets: [
+              { guid: GUID, kind: 'host-blob', payload: { value: 1 }, refs: [], artifacts: {} },
+            ],
+          }),
+        );
+      }),
+    );
+
+    const first = await registry.loadByGuid(registry.parseGuid(GUID));
+    expect(first.ok).toBe(false);
+    const second = await registry.loadByGuid(registry.parseGuid(GUID));
+    expect(second.ok).toBe(true);
+    expect(attempts).toBe(2);
+    expect(registry.lookup(GUID)).toBeDefined();
+  });
+
+  it('does not expose an unresolved package as a public fast-path hit', async () => {
+    const registry = new AssetRegistry({} as never);
+    registry.loaders.register({
+      kind: 'host-blob',
+      load: (payload) => ({ kind: 'host-blob', ...payload }),
+    });
+    registry.configurePackIndex('/pack-index.json');
+    let release: (() => void) | undefined;
+    const pending = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async (url: string) => {
+        if (url.endsWith('pack-index.json')) {
+          return new Response(
+            JSON.stringify([
+              {
+                guid: GUID,
+                packageUrl: '/asset.pack.json',
+                kind: 'host-blob',
+                sourcePath: 'asset',
+              },
+            ]),
+          );
+        }
+        await pending;
+        return new Response(
+          JSON.stringify({
+            schemaVersion: '2.0.0',
+            kind: 'internal-text-package',
+            assets: [
+              { guid: GUID, kind: 'host-blob', payload: { value: 1 }, refs: [], artifacts: {} },
+            ],
+          }),
+        );
+      }),
+    );
+
+    const loading = registry.loadByGuid(registry.parseGuid(GUID));
+    expect(registry.lookup(GUID)).toBeUndefined();
+    release?.();
+    await loading;
+  });
+});