@forgeax/engine-assets-runtime 0.1.2

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@forgeax/engine-assets-runtime",
+  "version": "0.1.2",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Single-scope Catalog, Pack, typed decoder, dependency graph, and terminal lifecycle for forgeax-engine.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-types": "0.1.2"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "asset registry / loader library, no runtime canvas; fps reported by hello-* apps that consume it"
+      },
+      "bench": {
+        "enabled": true,
+        "reportSchema": "asset-runtime-core",
+        "reportPath": "report/assets-runtime-core.json"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "no package-level binary gate; smoke gate covered by hello-* / learn-render apps that load assets by GUID"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package; asset cluster extracted from runtime in feat-20260705-runtime-tier2-decomposition"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "bench:asset-runtime-baseline": "node ../../scripts/metrics/asset-runtime-baseline.mjs",
+    "bench:asset-runtime-core": "node ../../scripts/metrics/asset-runtime-bench.mjs"
+  }
+}

package/src/__tests__/asset-graph-red.integration.test.ts

@@ -0,0 +1,113 @@
+import type { AssetLoadError } from '@forgeax/engine-types';
+import { err, ok } from '@forgeax/engine-types';
+import { describe, expect, it, vi } from 'vitest';
+import { AssetGraph } from '../internal/asset-graph.js';
+
+type Value = { readonly refs: readonly string[]; readonly value: string };
+
+const failure = (guid: string): AssetLoadError => ({
+  code: 'asset-dependency-failed',
+  expected: 'a readable dependency',
+  hint: 'repair the dependency publication and retry',
+  detail: { guid, dependencyGuid: guid },
+});
+
+describe('AssetGraph', () => {
+  it('deduplicates shared reads, bounds concurrency, and promotes a closure atomically', async () => {
+    let active = 0;
+    let peak = 0;
+    const reads = vi.fn(async (guid: string) => {
+      active += 1;
+      peak = Math.max(peak, active);
+      await new Promise((resolve) => setTimeout(resolve, 1));
+      active -= 1;
+      if (guid === 'root') return ok({ value: guid, refs: ['shared', 'left'] });
+      if (guid === 'left') return ok({ value: guid, refs: ['shared'] });
+      return ok({ value: guid, refs: [] });
+    });
+    const graph = new AssetGraph<Value>({ read: reads, maxConcurrentReads: 2 });
+
+    const [first, second] = await Promise.all([graph.load('root'), graph.load('root')]);
+    expect(first).toEqual(second);
+    expect(reads.mock.calls.filter(([guid]) => guid === 'shared')).toHaveLength(1);
+    expect(peak).toBeLessThanOrEqual(2);
+    expect(graph.snapshot().ready).toEqual(['left', 'root', 'shared']);
+    expect(graph.snapshot().pending).toBe(0);
+  });
+
+  it('terminates cycles as one SCC and does not deadlock', async () => {
+    const reads = vi.fn(async (guid: string) =>
+      ok<Value>({ value: guid, refs: [guid === 'a' ? 'b' : 'a'] }),
+    );
+    const graph = new AssetGraph<Value>({ read: reads, maxConcurrentReads: 1 });
+
+    expect((await graph.load('a')).ok).toBe(true);
+    expect(reads).toHaveBeenCalledTimes(2);
+    expect(graph.snapshot().sccs).toContainEqual(['a', 'b']);
+  });
+
+  it('clears failed pending work so a repaired publication can retry', async () => {
+    let repaired = false;
+    const reads = vi.fn(async (guid: string) => {
+      if (guid === 'child' && !repaired) return err(failure(guid));
+      return ok<Value>({ value: guid, refs: [] });
+    });
+    const graph = new AssetGraph<Value>({ read: reads });
+
+    expect((await graph.load('child')).ok).toBe(false);
+    expect(graph.snapshot().pending).toBe(0);
+    repaired = true;
+    expect((await graph.load('child')).ok).toBe(true);
+    expect(reads).toHaveBeenCalledTimes(2);
+  });
+
+  it('fences an in-flight read after publication invalidation', async () => {
+    let release: (() => void) | undefined;
+    let reads = 0;
+    const graph = new AssetGraph<Value>({
+      read: async (guid) => {
+        reads += 1;
+        await new Promise<void>((resolve) => {
+          release = resolve;
+        });
+        return ok<Value>({ value: guid, refs: [] });
+      },
+    });
+
+    const first = graph.load('asset');
+    graph.invalidate('asset');
+    release?.();
+    expect(await first).toEqual({
+      ok: false,
+      error: expect.objectContaining({ code: 'asset-superseded' }),
+    });
+    expect(reads).toBe(1);
+  });
+
+  it('resolves a queued permit with the terminal dispose result', async () => {
+    let release: (() => void) | undefined;
+    const graph = new AssetGraph<Value>({
+      maxConcurrentReads: 1,
+      read: async (guid) => {
+        await new Promise<void>((resolve) => {
+          release = resolve;
+        });
+        return ok<Value>({ value: guid, refs: [] });
+      },
+    });
+
+    const first = graph.load('first');
+    await Promise.resolve();
+    const second = graph.load('second');
+    graph.dispose();
+    expect(await second).toEqual({
+      ok: false,
+      error: expect.objectContaining({ code: 'asset-runtime-disposed' }),
+    });
+    release?.();
+    expect(await first).toEqual({
+      ok: false,
+      error: expect.objectContaining({ code: 'asset-runtime-disposed' }),
+    });
+  });
+});

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

@@ -0,0 +1,14 @@
+import type { AssetKindPayload } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { defineAssetKind } from '../asset-kind.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-core.integration.test.ts

@@ -0,0 +1,161 @@
+import type { AssetDecoder, CatalogDelta, CatalogEntry } from '@forgeax/engine-types';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { defineAssetKind } from '../asset-kind.js';
+import { createCatalogSource } from '../catalog-source.js';
+import { createAssetRegistry } from '../internal/load-asset.js';
+
+const ROOT = '00000000-0000-7000-8000-000000000021';
+const CHILD = '00000000-0000-7000-8000-000000000022';
+const PACKAGE_URL = 'https://assets.test/runtime.pack.json';
+const kind = defineAssetKind<unknown, 'host-blob'>('host-blob');
+
+function row(guid: string, refs: readonly string[] = [], revision = 1): CatalogEntry {
+  return {
+    guid,
+    packageUrl: PACKAGE_URL,
+    kind: kind.kind,
+    sourcePath: `fixtures/${guid}`,
+    revision: { rootId: 'root', digest: `sha256:catalog-${revision}`, observedAt: revision },
+    publication: {
+      schemaVersion: 'asset-publication/1',
+      sourcePath: `fixtures/${guid}`,
+      sourceRevision: 'source-1',
+      generation: 1,
+      digest: 'sha256:pack',
+      outputSetDigest: 'sha256:outputs',
+      outputs: [{ guid, sourceKey: guid, kind: kind.kind, digest: `sha256:${guid}`, refs }],
+      receipt: {
+        schemaVersion: 'asset-publication-receipt/1',
+        sourcePath: `fixtures/${guid}`,
+        sourceRevision: 'source-1',
+        inputFingerprint: 'input-1',
+        outputDigest: 'sha256:outputs',
+        outputSetDigest: 'sha256:outputs',
+        externalEvidence: [],
+      },
+      externalEvidence: [],
+    },
+  };
+}
+
+describe('AssetRegistry integration', () => {
+  it('loads a real Pack closure through the owner decoder and reuses one Pack read', async () => {
+    let packReads = 0;
+    let artifactReads = 0;
+    let publishCatalog: ((delta: CatalogDelta) => void) | undefined;
+    const fetcher: typeof globalThis.fetch = async (input) => {
+      const url = String(input);
+      if (url === PACKAGE_URL) {
+        packReads += 1;
+        return new Response(
+          JSON.stringify({
+            schemaVersion: '2.0.0',
+            kind: 'internal-text-package',
+            scopeId: 'scope',
+            generation: 1,
+            digest: 'sha256:pack',
+            outputSetDigest: 'sha256:outputs',
+            assets: [
+              {
+                guid: ROOT,
+                kind: kind.kind,
+                payload: { label: 'root' },
+                refs: [CHILD],
+                artifacts: {
+                  preview: {
+                    path: 'preview.bin',
+                    mediaType: 'application/octet-stream',
+                    contentEncoding: 'identity',
+                    byteLength: 3,
+                    integrity: {
+                      algorithm: 'sha256',
+                      digest:
+                        'sha256:039058c6f2c0cb492c533b0a4d14ef77cc0f78abccced5287d84a1a2011cfb81',
+                    },
+                  },
+                },
+              },
+              {
+                guid: CHILD,
+                kind: kind.kind,
+                payload: { label: 'child' },
+                refs: [],
+                artifacts: {},
+              },
+            ],
+          }),
+        );
+      }
+      if (url === 'https://assets.test/preview.bin') {
+        artifactReads += 1;
+        return new Response(new Uint8Array([1, 2, 3]));
+      }
+      return new Response('not found', { status: 404 });
+    };
+    const decoder: AssetDecoder<unknown> = {
+      decode: async ({ envelope, artifacts }) => {
+        if (envelope.guid === ROOT) {
+          const preview = await artifacts.read(
+            envelope.artifacts.preview as NonNullable<typeof envelope.artifacts.preview>,
+          );
+          if (!preview.ok) return preview;
+          return ok({
+            child: envelope.refs[0],
+            inline: (envelope.payload as { label: string }).label,
+            preview: [...preview.value],
+          });
+        }
+        return ok({ inline: (envelope.payload as { label: string }).label });
+      },
+    };
+    const core = createAssetRegistry({
+      catalog: createCatalogSource({
+        entries: [row(ROOT, [CHILD]), row(CHILD)],
+        expectedScope: { scopeId: 'scope', generation: 1 },
+        subscribe(listener) {
+          publishCatalog = listener;
+          return () => {};
+        },
+      }),
+      fetcher,
+      maxConcurrentReads: 2,
+    });
+    core.installDecoder(kind, decoder);
+
+    const result = await core.load(ROOT, kind);
+
+    expect(result).toEqual({
+      ok: true,
+      value: { child: CHILD, inline: 'root', preview: [1, 2, 3] },
+    });
+    expect(result.ok && Object.isFrozen(result.value)).toBe(true);
+    expect(packReads).toBe(1);
+    expect(artifactReads).toBe(1);
+    expect(core.snapshot().ready).toHaveLength(2);
+    expect(core.snapshot().resources).toBe(2);
+    publishCatalog?.({
+      added: [],
+      changed: [row(ROOT, [CHILD], 2)],
+      removed: [],
+    });
+    expect(core.snapshot().resources).toBe(1);
+    expect(core.snapshot().ready).toEqual([CHILD]);
+
+    publishCatalog?.({
+      added: [],
+      changed: [row(ROOT, [CHILD], 3)],
+      removed: [],
+      revisions: {
+        baseline: [{ rootId: 'root', revision: 1 }],
+        current: [{ rootId: 'root', revision: 3 }],
+      },
+    });
+    expect(core.snapshot().resources).toBe(0);
+    const recovered = await core.load(ROOT, kind);
+    expect(recovered.ok).toBe(true);
+    expect(core.snapshot().resources).toBe(2);
+    expect(packReads).toBe(1);
+    core.dispose();
+  });
+});

package/src/__tests__/asset-registry-public-api.test-d.ts

@@ -0,0 +1,31 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import type { CatalogSource } from '../catalog-source.js';
+import {
+  type AssetRegistry,
+  type AssetRegistryOptions,
+  type AssetRegistrySnapshot,
+  createAssetRegistry,
+} from '../index.js';
+
+describe('AssetRegistry public API', () => {
+  it('binds the factory and options to the root registry interface', () => {
+    const options = { catalog: null as unknown as CatalogSource } satisfies AssetRegistryOptions;
+    expectTypeOf(createAssetRegistry(options)).toEqualTypeOf<AssetRegistry>();
+  });
+
+  it('exposes the graph observation through registry snapshot types', () => {
+    const registry = null as unknown as AssetRegistry;
+    expectTypeOf(registry.snapshot()).toEqualTypeOf<AssetRegistrySnapshot>();
+    expectTypeOf(registry.snapshot().ready).toEqualTypeOf<readonly string[]>();
+    expectTypeOf(registry.snapshot().counters.loads).toEqualTypeOf<number>();
+  });
+
+  it('keeps renderer payload projection out of the five-action root surface', () => {
+    const registry = null as unknown as AssetRegistry;
+    expectTypeOf(registry.installDecoder).toBeFunction();
+    expectTypeOf(registry.load).toBeFunction();
+    expectTypeOf(registry.snapshot).toBeFunction();
+    expectTypeOf(registry.subscribe).toBeFunction();
+    expectTypeOf(registry.dispose).toBeFunction();
+  });
+});

package/src/__tests__/asset-runtime-core-lifecycle.integration.test.ts

@@ -0,0 +1,79 @@
+import type { CatalogEntry } from '@forgeax/engine-types';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { defineAssetKind } from '../asset-kind.js';
+import { createCatalogSource } from '../catalog-source.js';
+import { createAssetRegistry } from '../internal/load-asset.js';
+
+const GUID = '00000000-0000-7000-8000-000000000011';
+const kind = defineAssetKind<string, 'host-blob'>('host-blob');
+
+function row(): CatalogEntry {
+  return {
+    guid: GUID,
+    packageUrl: '/asset.pack.json',
+    kind: kind.kind,
+    sourcePath: 'test',
+    publication: {
+      schemaVersion: 'asset-publication/1',
+      sourcePath: 'test',
+      sourceRevision: 'source-1',
+      generation: 1,
+      digest: 'sha256:pack',
+      outputSetDigest: 'sha256:outputs',
+      outputs: [
+        { guid: GUID, sourceKey: 'test', kind: kind.kind, digest: 'sha256:asset', refs: [] },
+      ],
+      receipt: {
+        schemaVersion: 'asset-publication-receipt/1',
+        sourcePath: 'test',
+        sourceRevision: 'source-1',
+        inputFingerprint: 'input-1',
+        outputDigest: 'sha256:outputs',
+        outputSetDigest: 'sha256:outputs',
+        externalEvidence: [],
+      },
+      externalEvidence: [],
+    },
+  };
+}
+
+describe('AssetRegistry lifecycle', () => {
+  it('does not promote a late Pack result after dispose', async () => {
+    let resolveFetch: ((response: Response) => void) | undefined;
+    const fetcher = () =>
+      new Promise<Response>((resolve) => {
+        resolveFetch = resolve;
+      });
+    const core = createAssetRegistry({
+      catalog: createCatalogSource({ entries: [row()] }),
+      fetcher,
+      scopeId: 'scope',
+      generation: 1,
+    });
+    core.installDecoder(kind, {
+      decode: async ({ envelope }) => ok(envelope.payload as string),
+    });
+    const request = core.load(GUID, kind);
+    core.dispose();
+    resolveFetch?.(
+      new Response(
+        JSON.stringify({
+          schemaVersion: '2.0.0',
+          kind: 'internal-text-package',
+          scopeId: 'scope',
+          generation: 1,
+          digest: 'sha256:pack',
+          outputSetDigest: 'sha256:outputs',
+          assets: [{ guid: GUID, kind: kind.kind, payload: 'value', refs: [], artifacts: {} }],
+        }),
+      ),
+    );
+    expect(await request).toEqual({
+      ok: false,
+      error: expect.objectContaining({ code: 'asset-runtime-disposed' }),
+    });
+    expect(core.snapshot().pending).toBe(0);
+    expect(core.snapshot().resources).toBe(0);
+  });
+});

package/src/__tests__/asset-runtime-snapshot.unit.test.ts

@@ -0,0 +1,23 @@
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { AssetGraph } from '../internal/asset-graph.js';
+
+describe('asset runtime snapshot counters', () => {
+  it('reports no-change loads without new reads and keeps bounded counters', async () => {
+    let reads = 0;
+    const graph = new AssetGraph<{ readonly refs: readonly string[]; readonly value: string }>({
+      read: async (guid) => {
+        reads += 1;
+        return ok({ value: guid, refs: [] });
+      },
+    });
+    await graph.load('same');
+    const before = graph.snapshot();
+    await graph.load('same');
+    const after = graph.snapshot();
+    expect(reads).toBe(1);
+    expect(after.counters.noChange).toBe(before.counters.noChange + 1);
+    expect(after.resources).toBe(1);
+    expect(after.pending).toBe(0);
+  });
+});