@forgeax/engine-assets-runtime 0.1.2

package/src/__tests__/catalog-session-red.unit.test.ts

@@ -0,0 +1,276 @@
+import type { CatalogDelta, CatalogEntry } from '@forgeax/engine-types';
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { createCatalogSource } from '../catalog-source.js';
+import { ArtifactCache } from '../internal/artifact-cache.js';
+import { CatalogSession } from '../internal/catalog-session.js';
+import { PackReader } from '../internal/pack-reader.js';
+
+const GUID = '00000000-0000-7000-8000-000000000001';
+
+function entry(guid = GUID, revision = 1): CatalogEntry {
+  return {
+    guid,
+    packageUrl: '/runtime.pack.json',
+    kind: 'host-blob',
+    sourcePath: 'test',
+    revision: { rootId: 'root', digest: `sha256:revision-${revision}`, observedAt: revision },
+    publication: {
+      schemaVersion: 'asset-publication/1',
+      sourcePath: 'test',
+      sourceRevision: `source-${revision}`,
+      generation: 1,
+      digest: 'sha256:pack',
+      outputSetDigest: 'sha256:outputs',
+      outputs: [{ guid, sourceKey: guid, kind: 'host-blob', digest: 'sha256:asset', refs: [] }],
+      receipt: {
+        schemaVersion: 'asset-publication-receipt/1',
+        sourcePath: 'test',
+        sourceRevision: `source-${revision}`,
+        inputFingerprint: 'input',
+        outputDigest: 'sha256:outputs',
+        outputSetDigest: 'sha256:outputs',
+        externalEvidence: [],
+      },
+      externalEvidence: [],
+    },
+  };
+}
+
+describe('CatalogSession', () => {
+  it('rejects a Catalog row without a complete publication at the runtime boundary', async () => {
+    const invalidRow = { ...entry() };
+    delete (invalidRow as { publication?: CatalogEntry['publication'] }).publication;
+    const session = new CatalogSession(createCatalogSource({ entries: [invalidRow] }));
+
+    expect(await session.start()).toEqual({
+      ok: false,
+      error: expect.objectContaining({ code: 'asset-package-invalid' }),
+    });
+  });
+
+  it('turns a thrown Catalog enumeration into a structured runtime failure', async () => {
+    const session = new CatalogSession({
+      enumerate: async () => {
+        throw new Error('catalog transport unavailable');
+      },
+      subscribe: () => () => {},
+    });
+
+    await expect(session.start()).resolves.toMatchObject({
+      ok: false,
+      error: { code: 'asset-package-invalid' },
+    });
+    expect(session.snapshot().stale).toBe(true);
+  });
+
+  it('binds one scope and rejects a delta from another scope', async () => {
+    let publish: ((delta: CatalogDelta) => void) | undefined;
+    const source = createCatalogSource({
+      entries: [entry()],
+      expectedScope: { scopeId: 'scope-a', generation: 4 },
+      subscribe(listener) {
+        publish = listener;
+        return () => {};
+      },
+    });
+    const session = new CatalogSession(source);
+
+    expect((await session.start()).ok).toBe(true);
+    expect(session.snapshot().scopeId).toBe('scope-a');
+    expect(session.snapshot().generation).toBe(4);
+    publish?.({
+      scopeId: 'scope-b',
+      generation: 4,
+      added: [entry('00000000-0000-7000-8000-000000000002', 2)],
+      changed: [],
+      removed: [],
+    });
+
+    expect(session.snapshot().entries).toHaveLength(1);
+    expect(session.snapshot().diagnostics.map((item) => item.code)).toContain(
+      'catalog-scope-mismatch',
+    );
+  });
+
+  it('serializes reconcile and preserves continuity across ordered deltas', async () => {
+    const deltas: CatalogDelta[] = [];
+    const source = createCatalogSource({
+      entries: [entry()],
+      subscribe(listener) {
+        deltas.push({
+          added: [],
+          changed: [entry(GUID, 2)],
+          removed: [],
+          revisions: {
+            baseline: [{ rootId: 'root', revision: 1 }],
+            current: [{ rootId: 'root', revision: 2 }],
+          },
+        });
+        listener(deltas[0] as CatalogDelta);
+        return () => {};
+      },
+    });
+    const session = new CatalogSession(source, { scopeId: 'scope', generation: 1 });
+
+    await session.start();
+    expect(session.current(GUID)?.revision?.observedAt).toBe(2);
+    expect((await session.reconcile()).ok).toBe(true);
+    expect(session.snapshot().epoch).toBeGreaterThan(0);
+  });
+
+  it('marks a discontinuous delta and clears the terminal observation on reconcile', async () => {
+    let publish: ((delta: CatalogDelta) => void) | undefined;
+    const source = createCatalogSource({
+      entries: [entry()],
+      subscribe(listener) {
+        publish = listener;
+        return () => {};
+      },
+    });
+    const session = new CatalogSession(source, { scopeId: 'scope', generation: 1 });
+
+    await session.start();
+    publish?.({
+      added: [],
+      changed: [entry(GUID, 3)],
+      removed: [],
+      revisions: {
+        baseline: [{ rootId: 'root', revision: 1 }],
+        current: [{ rootId: 'root', revision: 3 }],
+      },
+    });
+
+    expect(session.snapshot().stale).toBe(true);
+    expect(session.snapshot().epoch).toBeGreaterThan(0);
+    expect(session.discontinuity()).toMatchObject({ code: 'catalog-discontinuous' });
+
+    expect((await session.reconcile()).ok).toBe(true);
+    expect(session.snapshot().stale).toBe(false);
+    expect(session.snapshot().diagnostics).toEqual([]);
+    expect(session.discontinuity()).toBeUndefined();
+  });
+
+  it('does not expose mutable session state', async () => {
+    const session = new CatalogSession(createCatalogSource({ entries: [entry()] }), {
+      scopeId: 'scope',
+      generation: 1,
+    });
+    await session.start();
+    const snapshot = session.snapshot();
+    expect(Object.isFrozen(snapshot)).toBe(true);
+    expect(Object.isFrozen(snapshot.entries)).toBe(true);
+    expect(ok(snapshot.entries[0])).toEqual(ok(snapshot.entries[0]));
+  });
+
+  it('records observer failures without starving later observers', async () => {
+    const session = new CatalogSession(createCatalogSource({ entries: [entry()] }));
+    const seen: number[] = [];
+    session.subscribe(() => {
+      throw new Error('observer failure');
+    });
+    session.subscribe((snapshot) => seen.push(snapshot.entries.length));
+
+    await session.start();
+
+    expect(seen).toContain(1);
+    expect(session.snapshot().listenerFailures).toBe(1);
+  });
+
+  it('accepts only the current Pack v2 tuple and complete artifact descriptors', async () => {
+    const tuple = {
+      scopeId: 'scope',
+      generation: 1,
+      digest: 'sha256:pack',
+      outputSetDigest: 'sha256:outputs',
+    };
+    const reader = new PackReader();
+    const result = reader.verify(
+      {
+        schemaVersion: '2.0.0',
+        kind: 'internal-text-package',
+        ...tuple,
+        assets: [
+          {
+            guid: GUID,
+            kind: 'host-blob',
+            payload: { value: 'ok' },
+            refs: [],
+            artifacts: {
+              body: {
+                path: 'body.bin',
+                mediaType: 'application/octet-stream',
+                contentEncoding: 'identity',
+                byteLength: 2,
+                integrity: {
+                  algorithm: 'sha256',
+                  digest: 'sha256:230d8358dc8e8890b4c58deeb62912ee2f20357ae92a5cc861b98e68fe31acb5',
+                },
+              },
+            },
+          },
+        ],
+      },
+      tuple,
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok) expect(Object.isFrozen(result.value.assets[0])).toBe(true);
+    expect(reader.verify({ schemaVersion: '1.0.0' }, tuple).ok).toBe(false);
+  });
+
+  it('resolves a late-installed host fetch when no transport was injected', async () => {
+    const tuple = {
+      scopeId: 'scope',
+      generation: 1,
+      digest: 'sha256:pack',
+      outputSetDigest: 'sha256:outputs',
+    };
+    const pack = {
+      schemaVersion: '2.0.0',
+      kind: 'internal-text-package',
+      ...tuple,
+      assets: [
+        {
+          guid: GUID,
+          kind: 'host-blob',
+          payload: { value: 'late-fetch' },
+          refs: [],
+          artifacts: {},
+        },
+      ],
+    };
+    const originalFetch = globalThis.fetch;
+    try {
+      const reader = new PackReader();
+      globalThis.fetch = (async () => new Response(JSON.stringify(pack))) as typeof fetch;
+      const result = await reader.read('/late.pack.json', tuple, new AbortController().signal);
+      expect(result.ok).toBe(true);
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  it('deduplicates content-addressed artifact reads and removes rejected entries', async () => {
+    const cache = new ArtifactCache();
+    let reads = 0;
+    const read = () => {
+      reads += 1;
+      return Promise.resolve(ok(new Uint8Array([1, 2, 3])));
+    };
+    await Promise.all([cache.read('sha256:body', read), cache.read('sha256:body', read)]);
+    expect(reads).toBe(1);
+    expect(cache.snapshot().hits).toBe(1);
+    await cache.read('sha256:failed', () =>
+      Promise.resolve({
+        ok: false as const,
+        error: {
+          code: 'asset-fetch-failed' as const,
+          expected: 'bytes',
+          hint: 'retry',
+          detail: { guid: GUID, packageUrl: '/body.bin' },
+        },
+      } as never),
+    );
+    expect(cache.snapshot().pending).toBe(0);
+  });
+});

package/src/__tests__/decode-image-mime-owner.test.ts

@@ -0,0 +1,41 @@
+/// <reference types="node" />
+
+import { readFileSync } from 'node:fs';
+import type { decodeImageBytes } from '@forgeax/engine-image';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+
+type ExpectedSupportedMime = 'image/png' | 'image/jpeg';
+type PublicMime = Parameters<typeof decodeImageBytes>[1];
+
+const decoderSource = readFileSync(
+  new URL('../../../image/src/runtime/decode-image-bytes.ts', import.meta.url),
+  'utf8',
+);
+
+describe('decodeImageBytes supported MIME owner', () => {
+  it('keeps the supported MIME vocabulary and public boundary exact', () => {
+    expectTypeOf<ExpectedSupportedMime>().toEqualTypeOf<'image/png' | 'image/jpeg'>();
+    expectTypeOf<PublicMime>().toEqualTypeOf<string>();
+    expectTypeOf<string>().toEqualTypeOf<PublicMime>();
+
+    const acceptsSupportedMime = (mime: ExpectedSupportedMime): ExpectedSupportedMime => mime;
+    acceptsSupportedMime('image/png');
+    acceptsSupportedMime('image/jpeg');
+    // @ts-expect-error Unsupported MIME values remain outside the private vocabulary.
+    acceptsSupportedMime('image/gif');
+  });
+
+  it('derives the private type guard from one readonly MIME owner', () => {
+    expect(decoderSource).toContain(
+      "const SUPPORTED_MIMES = ['image/png', 'image/jpeg'] as const;",
+    );
+    expect(decoderSource).toContain('type SupportedMime = (typeof SUPPORTED_MIMES)[number];');
+    expect(decoderSource).toContain(
+      'function isSupportedMime(mime: string): mime is SupportedMime',
+    );
+    expect(decoderSource).toContain(
+      'return SUPPORTED_MIMES.some((supportedMime) => supportedMime === mime);',
+    );
+    expect(decoderSource).not.toContain("return mime === 'image/png' || mime === 'image/jpeg';");
+  });
+});

package/src/__tests__/registry-lifecycle-red.integration.test.ts

@@ -0,0 +1,80 @@
+import { ok } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { defineAssetKind } from '../asset-kind.js';
+import { AssetGraph } from '../internal/asset-graph.js';
+import { DecoderRegistry } from '../internal/decoder-registry.js';
+
+const kind = defineAssetKind<string, 'host-blob'>('host-blob');
+
+describe('asset runtime terminal lifecycle', () => {
+  it('shares leases for one decoder identity and rejects a different owner', () => {
+    const decoders = new DecoderRegistry({ scopeId: 'scope' });
+    const decoder = { decode: async () => ok('value') };
+    const first = decoders.install(kind, decoder);
+    const second = decoders.install(kind, decoder);
+
+    expect(decoders.has(kind)).toBe(true);
+    expect(() => decoders.install(kind, { decode: async () => ok('other') })).toThrow(
+      'duplicate decoder kind "host-blob"',
+    );
+    first.dispose();
+    expect(decoders.has(kind)).toBe(true);
+    second.dispose();
+    expect(decoders.has(kind)).toBe(false);
+  });
+
+  it('normalizes decoder throws and preserves the terminal error shape', async () => {
+    const decoders = new DecoderRegistry({ scopeId: 'scope' });
+    const lease = decoders.install(kind, {
+      async decode() {
+        throw new Error('boom');
+      },
+    });
+    const result = await decoders.decode(kind, {
+      envelope: { guid: 'guid', kind: kind.kind, payload: 'raw', refs: [], artifacts: {} },
+      artifacts: { read: async () => ok(new Uint8Array()) },
+      signal: new AbortController().signal,
+    });
+    lease.dispose();
+    expect(result.ok).toBe(false);
+    if (!result.ok) expect(result.error.code).toBe('asset-decode-failed');
+  });
+
+  it('drops a late non-cancellable result after dispose and zeroes resources', async () => {
+    let resolve: ((value: { ok: true; value: string }) => void) | undefined;
+    const pending = new Promise<{ ok: true; value: string }>((done) => {
+      resolve = done;
+    });
+    const graph = new AssetGraph<{ readonly refs: readonly string[]; readonly value: string }>({
+      read: async (guid) => {
+        await pending;
+        return ok({ value: guid, refs: [] });
+      },
+    });
+    const request = graph.load('late');
+    graph.dispose();
+    resolve?.({ ok: true, value: 'late' });
+    expect(await request).toEqual({
+      ok: false,
+      error: expect.objectContaining({ code: 'asset-runtime-disposed' }),
+    });
+    expect(graph.snapshot().resources).toBe(0);
+    expect(graph.snapshot().pending).toBe(0);
+  });
+
+  it('returns detached frozen observations and isolates listener failure', async () => {
+    const graph = new AssetGraph<{ readonly refs: readonly string[]; readonly value: string }>({
+      read: async (guid) => ok({ value: guid, refs: [] }),
+    });
+    const seen: string[] = [];
+    graph.subscribe(() => {
+      throw new Error('observer failure');
+    });
+    graph.subscribe((snapshot) => seen.push(snapshot.ready.join(',')));
+    await graph.load('asset');
+    const snapshot = graph.snapshot();
+    expect(Object.isFrozen(snapshot)).toBe(true);
+    expect(seen).toContain('asset');
+    expect(snapshot.counters.listenerFailures).toBeGreaterThan(0);
+  });
+});

package/src/asset-kind.ts

@@ -0,0 +1,6 @@
+import type { AssetKind } from '@forgeax/engine-types';
+
+/** Create the type witness shared by one custom decoder lease and its loads. */
+export function defineAssetKind<P, K extends string = string>(kind: K): AssetKind<P, K> {
+  return Object.freeze({ kind }) as AssetKind<P, K>;
+}

package/src/catalog-source.ts

@@ -0,0 +1,145 @@
+import {
+  ASSET_ERROR_HINTS,
+  AssetError,
+  type CatalogDelta,
+  type CatalogEntry,
+  err,
+  ok,
+  type ResourceRevision,
+  type Result,
+  type RuntimeAssetBinding,
+} from '@forgeax/engine-types';
+export type CatalogListener = (delta: CatalogDelta) => void;
+
+/** Read-only catalog source backed by static entries or a canonical URL. */
+export interface CatalogSource {
+  enumerate(): Promise<Result<readonly CatalogEntry[], AssetError>>;
+  subscribe(listener: CatalogListener): () => void;
+  readonly expectedScope?: Pick<RuntimeAssetBinding, 'scopeId' | 'generation'>;
+}
+
+/**
+ * Create a read-only catalog source while preserving the schema SSOT.
+ *
+ * Static and fetched sources use the same `CatalogEntry` and revision fields;
+ * an expected revision rejects unverified data before it reaches consumers.
+ */
+export function createCatalogSource(options: {
+  readonly url?: string;
+  readonly entries?: readonly CatalogEntry[];
+  readonly fetch?: typeof globalThis.fetch;
+  readonly expectedRevision?: ResourceRevision;
+  readonly expectedScope?: Pick<RuntimeAssetBinding, 'scopeId' | 'generation'>;
+  readonly subscribe?: (listener: CatalogListener) => () => void;
+}): CatalogSource {
+  const entries = options.entries;
+  return {
+    async enumerate() {
+      if (entries !== undefined) {
+        if (options.expectedRevision === undefined) return ok(entries);
+        const actualRevisions = entries.flatMap((entry) =>
+          entry.revision === undefined ? [] : [entry.revision],
+        );
+        const matches =
+          actualRevisions.length > 0 &&
+          actualRevisions.every(
+            (revision) =>
+              revision.digest === options.expectedRevision?.digest &&
+              revision.observedAt === options.expectedRevision?.observedAt &&
+              revision.rootId === options.expectedRevision?.rootId,
+          );
+        if (!matches) {
+          return err(
+            new AssetError({
+              code: 'asset-parse-failed',
+              expected: 'static catalog entries to carry the expected producer revision',
+              hint: 'restore a verified catalog revision before applying the source',
+              detail: { expectedRevision: options.expectedRevision, actualRevisions } as never,
+            }),
+          );
+        }
+        return ok(entries);
+      }
+      if (options.url === undefined) {
+        return err(
+          new AssetError({
+            code: 'catalog-source-unconfigured',
+            expected: 'a configured catalog source',
+            hint: ASSET_ERROR_HINTS['catalog-source-unconfigured'],
+          }),
+        );
+      }
+      const response = await (options.fetch ?? globalThis.fetch)(options.url);
+      if (!response.ok) {
+        return err(
+          new AssetError({
+            code: 'asset-fetch-failed',
+            expected: 'the configured Catalog URL to return HTTP 200',
+            hint: 'verify the producer Catalog URL and republish the current snapshot',
+            detail: { sourcePath: options.url },
+          }),
+        );
+      }
+      let raw: unknown;
+      try {
+        raw = await response.json();
+      } catch {
+        return err(
+          new AssetError({
+            code: 'asset-parse-failed',
+            expected: 'the configured Catalog URL to return JSON',
+            hint: 'repair the producer Catalog before loading the current publication',
+          }),
+        );
+      }
+      const rows = scopedRows(raw, options.expectedScope);
+      if (!rows.ok) return rows;
+      const result = rows.value.map((row) => ({ ...row }));
+      return ok(result);
+    },
+    subscribe(listener) {
+      return options.subscribe?.(listener) ?? (() => {});
+    },
+    ...(options.expectedScope === undefined ? {} : { expectedScope: options.expectedScope }),
+  };
+}
+
+function scopedRows(
+  raw: unknown,
+  expectedScope: Pick<RuntimeAssetBinding, 'scopeId' | 'generation'> | undefined,
+): Result<readonly CatalogEntry[], AssetError> {
+  if (Array.isArray(raw)) return ok(raw as readonly CatalogEntry[]);
+  if (raw === null || typeof raw !== 'object') return parseRowsError('Catalog JSON rows');
+  const snapshot = raw as Record<string, unknown>;
+  if (!Array.isArray(snapshot.entries)) return parseRowsError('Catalog JSON entries');
+  if (expectedScope !== undefined) {
+    if (
+      snapshot.scopeId !== expectedScope.scopeId ||
+      snapshot.generation !== expectedScope.generation ||
+      snapshot.authority !== 'authoritative'
+    ) {
+      return err(
+        new AssetError({
+          code: 'asset-parse-failed',
+          expected: 'the Catalog snapshot to match the active scope and generation',
+          hint: 'restore the authoritative producer Catalog for the active runtime scope',
+          detail: {
+            expectedScope,
+            actualScope: { scopeId: snapshot.scopeId, generation: snapshot.generation },
+          } as never,
+        }),
+      );
+    }
+  }
+  return ok(snapshot.entries as readonly CatalogEntry[]);
+}
+
+function parseRowsError(expected: string): Result<never, AssetError> {
+  return err(
+    new AssetError({
+      code: 'asset-parse-failed',
+      expected,
+      hint: 'repair the producer Catalog before loading the current publication',
+    }),
+  );
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+export type {
+  AssetDecoder,
+  AssetDecoderInput,
+  AssetDecoderLease,
+  AssetKind,
+  AssetLoadError,
+  AssetPublicationTuple,
+  CatalogEntry,
+  PackV2,
+  Result,
+} from '@forgeax/engine-types';
+
+export { defineAssetKind } from './asset-kind.js';
+export { type CatalogListener, type CatalogSource, createCatalogSource } from './catalog-source.js';
+export {
+  type AssetLoadOptions,
+  type AssetRegistry,
+  type AssetRegistryOptions,
+  type AssetRegistrySnapshot,
+  type AssetRegistrySnapshotCounters,
+  createAssetRegistry,
+} from './internal/load-asset.js';

package/src/internal/artifact-cache.ts

@@ -0,0 +1,65 @@
+import type { AssetLoadError, Result } from '@forgeax/engine-types';
+
+export interface ArtifactCacheSnapshot {
+  readonly entries: number;
+  readonly pending: number;
+  readonly hits: number;
+  readonly misses: number;
+}
+
+export class ArtifactCache {
+  private readonly values = new Map<string, Uint8Array>();
+  private readonly pending = new Map<string, Promise<Result<Uint8Array, AssetLoadError>>>();
+  private hits = 0;
+  private misses = 0;
+
+  read(
+    contentAddress: string,
+    reader: () => Promise<Result<Uint8Array, AssetLoadError>>,
+  ): Promise<Result<Uint8Array, AssetLoadError>> {
+    const value = this.values.get(contentAddress);
+    if (value !== undefined) {
+      this.hits += 1;
+      return Promise.resolve({ ok: true, value: new Uint8Array(value) } as Result<
+        Uint8Array,
+        AssetLoadError
+      >);
+    }
+    const pending = this.pending.get(contentAddress);
+    if (pending !== undefined) {
+      this.hits += 1;
+      return pending;
+    }
+    this.misses += 1;
+    const request = Promise.resolve()
+      .then(reader)
+      .then((result) => {
+        if (result.ok) this.values.set(contentAddress, new Uint8Array(result.value));
+        return result;
+      })
+      .finally(() => {
+        if (this.pending.get(contentAddress) === request) this.pending.delete(contentAddress);
+      });
+    this.pending.set(contentAddress, request);
+    return request;
+  }
+
+  clear(contentAddress?: string): void {
+    if (contentAddress === undefined) {
+      this.values.clear();
+      this.pending.clear();
+      return;
+    }
+    this.values.delete(contentAddress);
+    this.pending.delete(contentAddress);
+  }
+
+  snapshot(): ArtifactCacheSnapshot {
+    return Object.freeze({
+      entries: this.values.size,
+      pending: this.pending.size,
+      hits: this.hits,
+      misses: this.misses,
+    });
+  }
+}