@forgeax/engine-assets-runtime 0.1.3 → 0.1.6

package/dist/resolve-tileset-runtime.d.ts

@@ -0,0 +1,23 @@
+import type { World } from '@forgeax/engine-ecs';
+import type { Asset, Handle, Result, TextureAsset } from '@forgeax/engine-types';
+export type TilesetRuntimeErrorCode = 'tileset-atlas-not-found' | 'tileset-atlas-stale' | 'tileset-atlas-kind-mismatch';
+export interface TilesetRuntimeError {
+    readonly code: TilesetRuntimeErrorCode;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: {
+        readonly guid: string;
+        readonly actualKind?: string;
+    };
+}
+export interface ResolvedTilesetRuntime {
+    readonly guid: string;
+    readonly payload: TextureAsset;
+    readonly handle: Handle<'TextureAsset', 'shared'>;
+}
+export type TilesetAtlasLookup = Asset | {
+    readonly code: 'stale';
+} | undefined;
+/** Project one durable atlas GUID into the current World at the tilemap owner. */
+export declare function resolveTilesetRuntime(world: World, guid: string, lookup: (guid: string) => TilesetAtlasLookup): Result<ResolvedTilesetRuntime, TilesetRuntimeError>;
+//# sourceMappingURL=resolve-tileset-runtime.d.ts.map

package/dist/resolve-tileset-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-tileset-runtime.d.ts","sourceRoot":"","sources":["../src/resolve-tileset-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAGjF,MAAM,MAAM,uBAAuB,GAC/B,yBAAyB,GACzB,qBAAqB,GACrB,6BAA6B,CAAC;AAElC,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;KAC9B,CAAC;CACH;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;CACnD;AAED,MAAM,MAAM,kBAAkB,GAAG,KAAK,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAAC;AAEhF,kFAAkF;AAClF,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,kBAAkB,GAC3C,MAAM,CAAC,sBAAsB,EAAE,mBAAmB,CAAC,CAuCrD"}

package/dist/scene-handle-fields.d.ts

@@ -0,0 +1,88 @@
+import type { Component } from '@forgeax/engine-ecs';
+import type { MountOverride } from '@forgeax/engine-types';
+/**
+ * A single handle-field reference extracted from a SceneAsset entity.
+ *
+ * `entityLocalId` is the `node.localId`; `componentName` and `fieldName`
+ * identify the schema field whose `fieldType` starts with `shared\<` or
+ * `array\<shared\<`. `guidString` is the raw GUID string value from the
+ * entity's component data (NOT a parsed `AssetGuid` — callers parse or
+ * resolve as needed).
+ *
+ * `arrayIndex` is `undefined` for plain `handle<T>` fields; for
+ * `array<handle<T>>` fields it is the 0-based index into the array.
+ */
+export interface SceneHandleFieldEntry {
+    readonly entityLocalId: number;
+    readonly componentName: string;
+    readonly fieldName: string;
+    readonly guidString: string;
+    /** 0-based index for `array<handle<T>>` elements; `undefined` for plain `handle<T>` fields. */
+    readonly arrayIndex?: number;
+}
+/**
+ * Shape of a single entity passed to {@link extractSceneEntityHandleGuids}.
+ *
+ * Compatible with both `SceneEntity` (from `@forgeax/engine-types`, where
+ * `components` is `Partial<ComponentValuesMap>`) and test-side plain objects.
+ */
+interface SceneEntityLike {
+    readonly localId: number;
+    readonly components: Record<string, Record<string, unknown>>;
+}
+/**
+ * Walk every `SceneEntityLike` in `entities` and extract all GUID strings
+ * bound to schema fields with `handle<...>` or `array<handle<...>>` fieldType.
+ *
+ * Unknown component names (absent from the supplied World-local catalog) are
+ * silently skipped — the ecs layer's `additionalProperties` check will catch
+ * unknowns at spawn time if appropriate.
+ *
+ * Values that are already numbers (resolved Handles) or non-strings are
+ * skipped (they are not GUID refs).
+ *
+ * @internal Shared by {@link AssetRegistry._resolveSceneGuids} and
+ * `buildSceneChildContext` as the entity-walk fallback used when the structured
+ * `envelope.refs` edges are unavailable or carry no per-entity detail.
+ */
+export declare function extractSceneEntityHandleGuids(components: ReadonlyMap<string, Component>, entities: ReadonlyArray<SceneEntityLike>): SceneHandleFieldEntry[];
+/**
+ * One handle-field GUID reference extracted from a {@link MountOverride}'s value
+ * (feat-20260713 M3 / w12). Mirrors {@link SceneHandleFieldEntry} but keys on the
+ * override's array index (there is no entity `localId` — an override targets a
+ * mount member by its own `localId`, resolved by the ecs apply loop, not here).
+ *
+ * `fieldName` is the schema field the GUID binds to: the override's own `field`
+ * for the patch form, or a key of the component-add value map for the add form.
+ */
+export interface MountOverrideHandleFieldEntry {
+    /** 0-based index into the `overrides[]` array passed to the extractor. */
+    readonly overrideIndex: number;
+    readonly componentName: string;
+    readonly fieldName: string;
+    readonly guidString: string;
+    /** 0-based index for `array<shared<T>>` elements; `undefined` for scalar `shared<T>`. */
+    readonly arrayIndex?: number;
+}
+/**
+ * Walk `overrides` and extract every GUID string bound to a `shared<...>` /
+ * `array<shared<...>>` schema field inside each override's value (feat-20260713
+ * M3 / w12, plan-strategy D-2). This is the apply-side counterpart to
+ * {@link extractSceneEntityHandleGuids}: it feeds `resolveMountsRec`'s
+ * GUID→handle down-drill so a `mounts[].overrides[].value` carrying a raw GUID
+ * (e.g. an `AnimationPlayer.clips` clip GUID) resolves to a live handle before
+ * the ecs apply loop, which only ever sees numeric handles (D-2: the GUID domain
+ * stays sealed in assets-runtime).
+ *
+ * The `{comp, field?, value}` discriminant is normalized to `(fieldName, value)`
+ * pairs: the patch form (`field` present) yields one pair; the component-add form
+ * (`field` absent, `value` is a per-field map) yields one pair per value key.
+ * Field type is judged from the supplied catalog token schema, the same
+ * schema SSOT the entity walk uses. Unknown components / non-shared fields /
+ * non-string (already-resolved number) values are skipped (D-8 number pass-through).
+ *
+ * @internal Shared identification core; resolution lives in `resolveMountsRec`.
+ */
+export declare function extractMountOverrideHandleGuids(components: ReadonlyMap<string, Component>, overrides: ReadonlyArray<MountOverride>): MountOverrideHandleFieldEntry[];
+export {};
+//# sourceMappingURL=scene-handle-fields.d.ts.map

package/dist/scene-handle-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-handle-fields.d.ts","sourceRoot":"","sources":["../src/scene-handle-fields.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,+FAA+F;IAC/F,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;GAKG;AACH,UAAU,eAAe;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CAC9D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,EAC1C,QAAQ,EAAE,aAAa,CAAC,eAAe,CAAC,GACvC,qBAAqB,EAAE,CAmCzB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,6BAA6B;IAC5C,0EAA0E;IAC1E,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yFAAyF;IACzF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,+BAA+B,CAC7C,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,EAC1C,SAAS,EAAE,aAAa,CAAC,aAAa,CAAC,GACtC,6BAA6B,EAAE,CAwBjC"}

package/dist/scene-payload.d.ts

@@ -0,0 +1,15 @@
+import type { SceneAsset } from '@forgeax/engine-types';
+/**
+ * Structured error returned by parseScenePayload when a refs index is
+ * out of bounds (F-2 / AC-02).
+ */
+interface ParseSceneError {
+    readonly localId: number;
+    readonly component: string;
+    readonly field: string;
+    readonly index: number;
+    readonly refsLength: number;
+}
+export declare function parseScenePayload(payload: Record<string, unknown>, refs?: string[]): SceneAsset | ParseSceneError | undefined;
+export {};
+//# sourceMappingURL=scene-payload.d.ts.map

package/dist/scene-payload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-payload.d.ts","sourceRoot":"","sources":["../src/scene-payload.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAEV,UAAU,EAGX,MAAM,uBAAuB,CAAC;AAG/B;;;GAGG;AACH,UAAU,eAAe;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAsBD,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,IAAI,CAAC,EAAE,MAAM,EAAE,GACd,UAAU,GAAG,eAAe,GAAG,SAAS,CAoG1C"}

package/dist/wire-default-loaders.d.ts

@@ -0,0 +1,29 @@
+import type { Loader } from '@forgeax/engine-types';
+import { LoaderRegistry } from './loader-registry';
+/**
+ * Wire the engine's default loader set (16 ordinary kinds plus UI) plus any
+ * `extraLoaders` onto `registry` in
+ * one call. Returns the same `registry` for chaining (so `wireDefaultLoaders(new
+ * LoaderRegistry())` is a one-expression wired registry). The `extraLoaders` are
+ * appended after the defaults and must use kinds outside the ordinary set.
+ *
+ * @example
+ * ```ts
+ * import { LoaderRegistry, wireDefaultLoaders } from '@forgeax/engine-assets-runtime';
+ * const loaders = wireDefaultLoaders(new LoaderRegistry());
+ * // loaders.get('mesh') / .get('texture') / .get('font') / .get('video') are
+ * // non-undefined; all ordinary Asset kinds share this same owner table.
+ * ```
+ */
+export declare function wireDefaultLoaders(registry: LoaderRegistry, extraLoaders?: readonly Loader[]): LoaderRegistry;
+/**
+ * Convenience factory: a fresh `LoaderRegistry` pre-wired with the default
+ * loader set (plus any `extraLoaders`). The production assembly point
+ * (`createRenderer`) and tests pass the result into `new LoaderRegistry()` (D-7
+ * constructor-injection; loaders always wired at construction -- used by
+ * `AssetRegistry` internally via `createDefaultLoaderRegistry(extraLoaders)` and
+ * by host code / tests independently) -- no setter / no illegal intermediate
+ * state).
+ */
+export declare function createDefaultLoaderRegistry(extraLoaders?: readonly Loader[]): LoaderRegistry;
+//# sourceMappingURL=wire-default-loaders.d.ts.map

package/dist/wire-default-loaders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-default-loaders.d.ts","sourceRoot":"","sources":["../src/wire-default-loaders.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAEpD,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAanD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,cAAc,EACxB,YAAY,GAAE,SAAS,MAAM,EAAO,GACnC,cAAc,CAahB;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,YAAY,GAAE,SAAS,MAAM,EAAO,GAAG,cAAc,CAEhG"}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@forgeax/engine-assets-runtime",
-  "version": "0.1.3",
+  "version": "0.1.6",
   "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.",
+  "description": "Asset registry, loader registry, GUID resolution, and default loader wiring for forgeax-engine (Tier 2.1 -- extracted from @forgeax/engine-runtime).",
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -26,7 +26,23 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-types": "0.1.3"
+    "@forgeax/engine-codec": "0.1.6",
+    "@forgeax/engine-ecs": "0.1.6",
+    "@forgeax/engine-geometry": "0.1.6",
+    "@forgeax/engine-graphics-extras": "0.1.6",
+    "@forgeax/engine-image": "0.1.6",
+    "@forgeax/engine-pack": "0.1.6",
+    "@forgeax/engine-plugin": "0.1.6",
+    "@forgeax/engine-rhi": "0.1.6",
+    "@forgeax/engine-scene": "0.1.6",
+    "@forgeax/engine-shader": "0.1.6",
+    "@forgeax/engine-types": "0.1.6",
+    "@forgeax/engine-ui": "0.1.6",
+    "@webgpu/types": "^0.1.71"
+  },
+  "devDependencies": {
+    "@forgeax/engine-skinning": "0.1.6",
+    "@webgpu/types": "^0.1.71"
   },
   "forgeax": {
     "metrics": {
@@ -40,9 +56,8 @@
         "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"
+        "enabled": false,
+        "reason": "asset catalogue + load pipeline run at asset-load time, not per-frame; no CI micro-benchmark warranted"
       },
       "gate": {
         "enabled": false,
@@ -56,8 +71,6 @@
   },
   "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"
+    "test": "vitest run"
   }
 }

package/src/__tests__/aabb.unit.test.ts

@@ -0,0 +1,97 @@
+// @forgeax/engine-assets-runtime -- withMeshAabb / computeAABB coverage
+// (fix issue #709: assets-runtime src entered the coverage pool via the
+// package's own tests importing `../` relative paths -> src; before this the
+// module was only exercised through the compiled dist by runtime-project
+// tests, which are excluded from the coverage denominator).
+
+import type { MeshAsset } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { withMeshAabb } from '../aabb';
+
+const EMPTY_BOX = [Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity];
+
+function meshWith(position: Float32Array | ArrayBuffer | undefined): MeshAsset {
+  return {
+    kind: 'mesh',
+    vertices: new Float32Array(0),
+    attributes: position === undefined ? {} : { position },
+    submeshes: [
+      { indexOffset: 0, indexCount: 0, vertexCount: 0, topology: 'triangle-list', materialSlot: 0 },
+    ],
+    materialSlots: [{ slotName: 'Default' }],
+  } as MeshAsset;
+}
+
+describe('withMeshAabb', () => {
+  it('computes [min, max] over every (x, y, z) triple of the position attribute', () => {
+    const position = Float32Array.of(
+      -1,
+      -2,
+      -3, //
+      4,
+      5,
+      6, //
+      0,
+      0,
+      0,
+    );
+    const out = withMeshAabb(meshWith(position));
+    expect(Array.from(out.aabb as Float32Array)).toEqual([-1, -2, -3, 4, 5, 6]);
+  });
+
+  it('handles a single-vertex mesh (min === max === that vertex)', () => {
+    const out = withMeshAabb(meshWith(Float32Array.of(7, 8, 9)));
+    expect(Array.from(out.aabb as Float32Array)).toEqual([7, 8, 9, 7, 8, 9]);
+  });
+
+  it('re-wraps an ArrayBuffer position buffer as Float32Array', () => {
+    const buf = Float32Array.of(1, 1, 1, 2, 3, 4).buffer;
+    const out = withMeshAabb(meshWith(buf));
+    expect(Array.from(out.aabb as Float32Array)).toEqual([1, 1, 1, 2, 3, 4]);
+  });
+
+  it('returns the inverted-infinity empty box when position is absent', () => {
+    const out = withMeshAabb(meshWith(undefined));
+    expect(Array.from(out.aabb as Float32Array)).toEqual(EMPTY_BOX);
+  });
+
+  it('returns the empty box when position has fewer than 3 floats', () => {
+    const out = withMeshAabb(meshWith(Float32Array.of(1, 2)));
+    expect(Array.from(out.aabb as Float32Array)).toEqual(EMPTY_BOX);
+  });
+
+  it('returns the empty box for a Uint16Array position (treated as absent)', () => {
+    const mesh = {
+      kind: 'mesh',
+      vertices: new Float32Array(0),
+      attributes: { position: Uint16Array.of(1, 2, 3) },
+      submeshes: [{ indexOffset: 0, indexCount: 0, vertexCount: 0, topology: 'triangle-list' }],
+    } as unknown as MeshAsset;
+    const out = withMeshAabb(mesh);
+    expect(Array.from(out.aabb as Float32Array)).toEqual(EMPTY_BOX);
+  });
+
+  it('preserves a packed AABB when the binary path omits position attributes', () => {
+    const mesh = {
+      ...meshWith(undefined),
+      aabb: Float32Array.of(-2, 0, -1, 3, 4, 5),
+    };
+    const out = withMeshAabb(mesh);
+    expect(Array.from(out.aabb as Float32Array)).toEqual([-2, 0, -1, 3, 4, 5]);
+  });
+
+  it('mutates the mesh in place when it is extensible (returns same reference)', () => {
+    const mesh = meshWith(Float32Array.of(0, 0, 0, 1, 1, 1));
+    const out = withMeshAabb(mesh);
+    expect(out).toBe(mesh);
+    expect(mesh.aabb).toBeInstanceOf(Float32Array);
+  });
+
+  it('returns a shallow copy carrying the aabb when the mesh is frozen', () => {
+    const mesh = Object.freeze(meshWith(Float32Array.of(0, 0, 0, 2, 2, 2)));
+    const out = withMeshAabb(mesh);
+    expect(out).not.toBe(mesh);
+    expect(Array.from(out.aabb as Float32Array)).toEqual([0, 0, 0, 2, 2, 2]);
+    expect(mesh.aabb).toBeUndefined();
+  });
+});

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.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', () => {