@forgeax/engine-assets-runtime 0.1.19 → 0.1.20

package/dist/loaders/pack-artifact.d.ts

@@ -1,4 +1,26 @@
-import type { Loader } from '@forgeax/engine-types';
+import type { LoadContext, Loader, TextureAsset } from '@forgeax/engine-types';
+import { AssetError } from '@forgeax/engine-types';
+import { TexturePackVerificationError } from '../errors/asset.js';
+import type { PackLoaderInput } from '../loader-registry';
+export interface TexturePackLoadInput {
+    readonly pack: PackLoaderInput;
+    readonly sourceKey: string;
+    readonly generation: number;
+    readonly expectedDigest: string;
+}
+export type VerifiedTexturePack = {
+    readonly asset: TextureAsset;
+    readonly sourceKey: string;
+    readonly generation: number;
+    readonly digest: string;
+};
+export type VerifiedTexturePackResult = {
+    readonly ok: true;
+    readonly value: VerifiedTexturePack;
+} | {
+    readonly ok: false;
+    readonly error: TexturePackVerificationError | AssetError;
+};
 export type CodecContextFailure = {
     readonly code: 'basis-profile-unsupported';
     readonly detail: {
@@ -11,6 +33,8 @@ export type CodecContextFailure = {
         readonly dfdColorSpace: 'srgb' | 'linear' | 'unknown';
     };
 };
+/** Verify producer facts and then expose one accepted texture projection. */
+export declare function loadVerifiedTexturePack(input: TexturePackLoadInput, ctx: LoadContext): Promise<VerifiedTexturePackResult>;
 export declare const textureLoader: Loader;
 export declare const equirectLoader: Loader;
 export declare const fontLoader: Loader;

package/dist/loaders/pack-artifact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pack-artifact.d.ts","sourceRoot":"","sources":["../../src/loaders/pack-artifact.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAMV,MAAM,EAKP,MAAM,uBAAuB,CAAC;AA+L/B,MAAM,MAAM,mBAAmB,GAC3B;IACE,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,QAAQ,CAAC;QAC/C,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;KACvD,CAAC;CACH,CAAC;AAyXN,eAAO,MAAM,aAAa,EAAE,MAI3B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,MAI5B,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,MAIxB,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,MAkBlC,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,MA0B3B,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAMlD,CAAC"}
+{"version":3,"file":"pack-artifact.d.ts","sourceRoot":"","sources":["../../src/loaders/pack-artifact.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAKV,WAAW,EACX,MAAM,EAGN,YAAY,EAEb,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,UAAU,EAAuB,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAEL,4BAA4B,EAC7B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAI1D,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GACjC;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,4BAA4B,GAAG,UAAU,CAAA;CAAE,CAAC;AAkPtF,MAAM,MAAM,mBAAmB,GAC3B;IACE,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,2BAA2B,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,kBAAkB,EAAE,MAAM,GAAG,QAAQ,CAAC;QAC/C,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;KACvD,CAAC;CACH,CAAC;AAkRN,6EAA6E;AAC7E,wBAAsB,uBAAuB,CAC3C,KAAK,EAAE,oBAAoB,EAC3B,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,yBAAyB,CAAC,CAiHpC;AA8GD,eAAO,MAAM,aAAa,EAAE,MAI3B,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,MAI5B,CAAC;AAEF,eAAO,MAAM,UAAU,EAAE,MAIxB,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,MAkBlC,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,MA0B3B,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAMlD,CAAC"}

package/dist/registry/validate-material.d.ts

@@ -1,6 +1,31 @@
 import type { CookedMaterialRecord } from '@forgeax/engine-pack';
 import { AssetError, type MaterialAsset, type MaterialError } from '@forgeax/engine-types';
 import type { AssetRegistry } from '../asset-registry';
+export interface TexturePublicationStateSnapshot {
+    readonly guid: string;
+    readonly sourceKey: string;
+    readonly acceptedGeneration: number;
+    readonly acceptedDigest: string;
+    readonly candidateGeneration?: number;
+    readonly candidateFailure?: string;
+}
+export interface TexturePublicationState {
+    reject(candidate: {
+        readonly generation: number;
+        readonly reason: string;
+    }): TexturePublicationStateSnapshot;
+    accept(candidate: {
+        readonly generation: number;
+        readonly digest: string;
+    }): TexturePublicationStateSnapshot;
+}
+/** Candidate/accepted state that keeps the last known good publication honest. */
+export declare function createTexturePublicationState(input: {
+    readonly guid: string;
+    readonly sourceKey: string;
+    readonly generation: number;
+    readonly digest: string;
+}): TexturePublicationState;
 /**
  * Validate a MaterialAsset's passes[] against the ShaderRegistry's
  * paramSchema (union semantics: all declared params across all passes

package/dist/registry/validate-material.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate-material.d.ts","sourceRoot":"","sources":["../../src/registry/validate-material.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EACL,UAAU,EAEV,KAAK,aAAa,EAClB,KAAK,aAAa,EAEnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,aAAa,EACvB,KAAK,EAAE,aAAa,GACnB,UAAU,GAAG,IAAI,CAoFnB;AA4CD,wBAAgB,oCAAoC,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,GAAG,IAAI,CAkD/F;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,MAAM,GAAG,SAAS,CAAC,EACtD,IAAI,EAAE,6BAA6B,GAClC,aAAa,GAAG,IAAI,CAiBtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,aAAa,EACxB,KAAK,EAAE,aAAa,GACnB,UAAU,GAAG,IAAI,CA8GnB;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,aAAa,EACxB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GACb,OAAO,CAgCT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CA8BhG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,MAAM,GACf,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,CAIjC"}
+{"version":3,"file":"validate-material.d.ts","sourceRoot":"","sources":["../../src/registry/validate-material.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AACjE,OAAO,EACL,UAAU,EAEV,KAAK,aAAa,EAClB,KAAK,aAAa,EAEnB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,CAAC,SAAS,EAAE;QAChB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,GAAG,+BAA+B,CAAC;IACpC,MAAM,CAAC,SAAS,EAAE;QAChB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;KACzB,GAAG,+BAA+B,CAAC;CACrC;AAED,kFAAkF;AAClF,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,GAAG,uBAAuB,CA0B1B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,aAAa,EACvB,KAAK,EAAE,aAAa,GACnB,UAAU,GAAG,IAAI,CAoFnB;AA4CD,wBAAgB,oCAAoC,CAAC,KAAK,EAAE,aAAa,GAAG,aAAa,GAAG,IAAI,CAkD/F;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,MAAM,GAAG,SAAS,CAAC,EACtD,IAAI,EAAE,6BAA6B,GAClC,aAAa,GAAG,IAAI,CAiBtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,aAAa,EACxB,KAAK,EAAE,aAAa,GACnB,UAAU,GAAG,IAAI,CA8GnB;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,aAAa,EACxB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GACb,OAAO,CAgCT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,4BAA4B,CAAC,QAAQ,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,GAAG,IAAI,CA8BhG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,aAAa,EACvB,QAAQ,EAAE,MAAM,GACf,WAAW,CAAC,MAAM,CAAC,GAAG,SAAS,CAIjC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-assets-runtime",
-  "version": "0.1.19",
+  "version": "0.1.20",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -26,22 +26,22 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-codec": "0.1.19",
-    "@forgeax/engine-ecs": "0.1.19",
-    "@forgeax/engine-geometry": "0.1.19",
-    "@forgeax/engine-graphics-extras": "0.1.19",
-    "@forgeax/engine-image": "0.1.19",
-    "@forgeax/engine-pack": "0.1.19",
-    "@forgeax/engine-plugin": "0.1.19",
-    "@forgeax/engine-rhi": "0.1.19",
-    "@forgeax/engine-scene": "0.1.19",
-    "@forgeax/engine-shader": "0.1.19",
-    "@forgeax/engine-types": "0.1.19",
-    "@forgeax/engine-ui": "0.1.19",
+    "@forgeax/engine-codec": "0.1.20",
+    "@forgeax/engine-ecs": "0.1.20",
+    "@forgeax/engine-geometry": "0.1.20",
+    "@forgeax/engine-graphics-extras": "0.1.20",
+    "@forgeax/engine-image": "0.1.20",
+    "@forgeax/engine-pack": "0.1.20",
+    "@forgeax/engine-plugin": "0.1.20",
+    "@forgeax/engine-rhi": "0.1.20",
+    "@forgeax/engine-scene": "0.1.20",
+    "@forgeax/engine-shader": "0.1.20",
+    "@forgeax/engine-types": "0.1.20",
+    "@forgeax/engine-ui": "0.1.20",
     "@webgpu/types": "^0.1.71"
   },
   "devDependencies": {
-    "@forgeax/engine-skinning": "0.1.19",
+    "@forgeax/engine-skinning": "0.1.20",
     "@webgpu/types": "^0.1.71"
   },
   "forgeax": {

package/src/__tests__/decode-image-bytes.browser.test.ts

@@ -30,7 +30,6 @@ import { World } from '@forgeax/engine-ecs';
 import type { TextureAsset } from '@forgeax/engine-types';
 import { describe, expect, it } from 'vitest';
 import { decodeImageBytes } from '../decode-image-bytes';
-import { numMipLevels } from '../mipmap-generator';
 
 // 1x1 red PNG (RGBA 8-bit). Universally decodable by browser createImageBitmap.
 const PNG_1X1_RED_BASE64 =
@@ -50,14 +49,13 @@ describe('decodeImageBytes browser real-PNG happy path (AC-01)', () => {
     if (!result.ok) return;
     const pod = result.value;
     expect(pod.kind).toBe('texture');
-    expect(pod.width).toBeGreaterThan(0);
-    expect(pod.height).toBeGreaterThan(0);
+    expect(pod.shape.extent.width).toBeGreaterThan(0);
+    expect(pod.shape.extent.height).toBeGreaterThan(0);
     // RGBA8 tight-packed: width * height * 4 bytes.
-    expect(pod.data.length).toBe(pod.width * pod.height * 4);
+    expect(pod.data.length).toBe(pod.shape.extent.width * pod.shape.extent.height * 4);
     expect(pod.format).toBe('rgba8unorm-srgb');
     expect(pod.colorSpace).toBe('srgb');
-    expect(pod.mipmap).toBe(true);
-    expect(pod.mipLevelCount).toBe(numMipLevels({ width: pod.width, height: pod.height }));
+    expect(pod.mips).toEqual({ kind: 'generate' });
   });
 
   it('AC-01: opts.colorSpace="linear" + opts.mipmap=false narrows format + mipLevelCount', async () => {
@@ -70,8 +68,7 @@ describe('decodeImageBytes browser real-PNG happy path (AC-01)', () => {
     const pod = result.value;
     expect(pod.format).toBe('rgba8unorm');
     expect(pod.colorSpace).toBe('linear');
-    expect(pod.mipmap).toBe(false);
-    expect(pod.mipLevelCount).toBe(1);
+    expect(pod.mips).toEqual({ kind: 'none' });
   });
 });
 

package/src/__tests__/pack-basis-load.integration.test.ts

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import type { LoadContext, TextureAsset } from '@forgeax/engine-types';
@@ -7,7 +8,11 @@ import type {
   BasisModuleFactory,
 } from '../../../codec/src/wasm/basis-types.js';
 import type { CodecContextFailure } from '../loaders/pack-artifact.js';
-import { PACK_ARTIFACT_LOADERS, textureLoader } from '../loaders/pack-artifact.js';
+import {
+  loadVerifiedTexturePack,
+  PACK_ARTIFACT_LOADERS,
+  textureLoader,
+} from '../loaders/pack-artifact.js';
 
 const TRANSCODER_GLUE = new URL('../../../codec/pkg/basis_transcoder.mjs', import.meta.url);
 const ENCODER_GLUE = new URL('../../../codec/pkg/encode/basis_encoder.mjs', import.meta.url);
@@ -52,6 +57,10 @@ const context: LoadContext = {
   device: undefined,
 };
 
+function digest(bytes: Uint8Array): string {
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
 describe.skipIf(!pkgBuilt)('Pack runtime raw Basis loader', () => {
   it('keeps context failure code and detail correlated as a closed union', () => {
     type ExpectedContextFailure =
@@ -79,7 +88,11 @@ describe.skipIf(!pkgBuilt)('Pack runtime raw Basis loader', () => {
       {
         guid: '019f0000-0000-7000-8000-000000000304',
         kind: 'texture',
-        payload: { width: 4, height: 4, colorSpace: 'linear' },
+        payload: {
+          shape: { viewDimension: '2d', extent: { width: 4, height: 4 } },
+          colorSpace: 'linear',
+          mips: { kind: 'none' },
+        },
         refs: [],
         artifacts: {
           body: {
@@ -101,12 +114,10 @@ describe.skipIf(!pkgBuilt)('Pack runtime raw Basis loader', () => {
     if (!result.ok) return;
     expect(result.value).toMatchObject({
       kind: 'texture',
-      width: 4,
-      height: 4,
+      shape: { viewDimension: '2d', extent: { width: 4, height: 4 } },
       format: 'rgba8unorm',
       colorSpace: 'linear',
-      mipmap: false,
-      mipLevelCount: 1,
+      mips: { kind: 'packed', levelCount: 1 },
     });
     expect(result.value.data.byteLength).toBeGreaterThan(0);
   });
@@ -119,7 +130,11 @@ describe.skipIf(!pkgBuilt)('Pack runtime raw Basis loader', () => {
       {
         guid: '019f0000-0000-7000-8000-000000000305',
         kind: 'texture',
-        payload: { width: 4, height: 4, colorSpace: 'srgb' },
+        payload: {
+          shape: { viewDimension: '2d', extent: { width: 4, height: 4 } },
+          colorSpace: 'srgb',
+          mips: { kind: 'none' },
+        },
         refs: [],
         artifacts: {
           body: {
@@ -165,4 +180,48 @@ describe('Pack artifact loader matrix', () => {
       ['equirect', 'font', 'render-pipeline', 'texture', 'tileset'].sort(),
     );
   });
+
+  it('preserves array shape and generation provenance through verified loading', async () => {
+    const bytes = new Uint8Array(8 * 4 * 3).fill(91);
+    const artifactDigest = digest(bytes);
+    const result = await loadVerifiedTexturePack(
+      {
+        sourceKey: 'array/layers',
+        generation: 4,
+        expectedDigest: artifactDigest,
+        pack: {
+          guid: '019f0000-0000-7000-8000-000000000306',
+          kind: 'texture',
+          payload: {
+            shape: { viewDimension: '2d-array', extent: { width: 8, height: 4, layers: 3 } },
+            format: 'r8unorm',
+            colorSpace: 'linear',
+            mips: { kind: 'none' },
+          },
+          refs: [],
+          artifacts: {
+            body: {
+              bytes,
+              descriptor: {
+                path: 'array.raw',
+                mediaType: 'application/x-forgeax-r8',
+                byteLength: bytes.byteLength,
+                integrity: { algorithm: 'sha256', digest: artifactDigest },
+              },
+            },
+          },
+        },
+      },
+      context,
+    );
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.asset.shape).toEqual({
+      viewDimension: '2d-array',
+      extent: { width: 8, height: 4, layers: 3 },
+    });
+    expect(result.value.generation).toBe(4);
+    expect(result.value.sourceKey).toBe('array/layers');
+  });
 });

package/src/__tests__/texture-pack-loader.unit.test.ts

@@ -0,0 +1,145 @@
+import { createHash } from 'node:crypto';
+import type { LoadContext } from '@forgeax/engine-types';
+import { describe, expect, it } from 'vitest';
+import { loadVerifiedTexturePack, type TexturePackLoadInput } from '../loaders/pack-artifact.js';
+import {
+  createTexturePublicationState,
+  type TexturePublicationState,
+} from '../registry/validate-material.js';
+
+const GUID = '019ffa97-3000-7000-8000-000000000301';
+const SOURCE_KEY = 'density/volume';
+
+function digest(bytes: Uint8Array): string {
+  return `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+}
+
+const context: LoadContext = {
+  fetchBinary: async () => ({ ok: false as const, error: new Error('not used') }),
+  resolveRef: async () => ({ ok: false as const, error: new Error('not used') }),
+  transcodeCaps: { bc: false, etc2: false, astc: false },
+  device: undefined,
+};
+
+function input(
+  bytes: Uint8Array,
+  overrides: Partial<TexturePackLoadInput> = {},
+): TexturePackLoadInput {
+  const actualDigest = digest(bytes);
+  return {
+    sourceKey: SOURCE_KEY,
+    generation: 2,
+    expectedDigest: actualDigest,
+    pack: {
+      guid: GUID,
+      kind: 'texture',
+      payload: {
+        shape: { viewDimension: '3d', extent: { width: 2, height: 2, depth: 2 } },
+        format: 'r8unorm',
+        colorSpace: 'linear',
+        mips: { kind: 'none' },
+      },
+      refs: [],
+      artifacts: {
+        body: {
+          bytes,
+          descriptor: {
+            path: 'density.raw',
+            mediaType: 'application/x-forgeax-r8',
+            byteLength: 8,
+            integrity: { algorithm: 'sha256', digest: actualDigest },
+          },
+        },
+      },
+    },
+    ...overrides,
+  };
+}
+
+describe('verified texture Pack loader', () => {
+  it('rejects bad byte length with GUID, generation, and loader stage', async () => {
+    const result = await loadVerifiedTexturePack(input(new Uint8Array(7)), context);
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.error.code).toBe('texture-pack-verification-failed');
+      expect(result.error.detail).toMatchObject({
+        guid: GUID,
+        sourceKey: SOURCE_KEY,
+        generation: 2,
+        stage: 'loader',
+        expectedBytes: 8,
+        actualBytes: 7,
+      });
+    }
+  });
+
+  it('rejects digest and canonical order mismatch before exposing an asset', async () => {
+    const digestMismatch = await loadVerifiedTexturePack(
+      input(new Uint8Array(8), { expectedDigest: 'sha256:not-the-artifact' }),
+      context,
+    );
+    expect(digestMismatch.ok).toBe(false);
+    if (!digestMismatch.ok) {
+      expect(digestMismatch.error.code).toBe('texture-pack-verification-failed');
+      expect(digestMismatch.error.detail).toMatchObject({
+        guid: GUID,
+        generation: 2,
+        stage: 'loader',
+        cause: 'digest-mismatch',
+      });
+    }
+
+    const orderMismatch = await loadVerifiedTexturePack(
+      input(new Uint8Array(8), {
+        pack: {
+          ...input(new Uint8Array(8)).pack,
+          payload: {
+            ...input(new Uint8Array(8)).pack.payload,
+            packingOrder: 'row-major,mip-major,image-major',
+          },
+        },
+      }),
+      context,
+    );
+    expect(orderMismatch.ok).toBe(false);
+    if (!orderMismatch.ok) {
+      expect(orderMismatch.error.detail).toMatchObject({
+        guid: GUID,
+        stage: 'loader',
+        cause: 'packing-order-mismatch',
+      });
+    }
+  });
+
+  it('advances accepted generation only after a verified candidate succeeds', async () => {
+    const state: TexturePublicationState = createTexturePublicationState({
+      guid: GUID,
+      sourceKey: SOURCE_KEY,
+      generation: 1,
+      digest: 'sha256:accepted',
+    });
+    const failed = await loadVerifiedTexturePack(input(new Uint8Array(7)), context);
+    expect(failed.ok).toBe(false);
+    const afterFailure = state.reject({
+      generation: 2,
+      reason: 'byte-length',
+    });
+    expect(afterFailure).toEqual({
+      guid: GUID,
+      sourceKey: SOURCE_KEY,
+      acceptedGeneration: 1,
+      acceptedDigest: 'sha256:accepted',
+      candidateGeneration: 2,
+      candidateFailure: 'byte-length',
+    });
+
+    const accepted = state.accept({ generation: 2, digest: 'sha256:repaired' });
+    expect(accepted).toEqual({
+      guid: GUID,
+      sourceKey: SOURCE_KEY,
+      acceptedGeneration: 2,
+      acceptedDigest: 'sha256:repaired',
+    });
+  });
+});

package/src/decode-image-bytes.ts

@@ -10,8 +10,8 @@
 //   3. Map `DecodedImage` -> `TextureAsset` POD; `format` derives from
 //      `opts.colorSpace` (srgb -> 'rgba8unorm-srgb' / linear ->
 //      'rgba8unorm', mirrors `image-importer.ts` colorSpaceToFormat); when
-//      `opts.mipmap !== false`, `mipLevelCount` derives from
-//      `numMipLevels({width,height})` (charter Derive-Don't-Duplicate).
+//      `opts.mipmap !== false`, the mip policy derives from the decoded shape
+//      (charter Derive-Don't-Duplicate).
 //
 // decode-image-bytes.ts is the SINGLE assets-runtime file allowed to
 // statically import @forgeax/engine-image (charter D-2; the
@@ -24,7 +24,6 @@ import { decodeImageInBrowser } from '@forgeax/engine-image';
 import type { ImageError, Result, TextureAsset } from '@forgeax/engine-types';
 import { err, ok } from '@forgeax/engine-types';
 import { makeImageError } from './image-error';
-import { numMipLevels } from './mipmap-generator';
 
 /** v1 mime whitelist -- PNG / JPEG only (charter P1 progressive disclosure). */
 const SUPPORTED_MIMES = ['image/png', 'image/jpeg'] as const;
@@ -60,8 +59,8 @@ function isSupportedMime(mime: string): mime is SupportedMime {
  * @param opts - Optional decode overrides:
  *   - `colorSpace`: `'srgb'` (default) or `'linear'`. Derives POD `format`:
  *     `srgb -> 'rgba8unorm-srgb'`, `linear -> 'rgba8unorm'`.
- *   - `mipmap`: `true` (default) or `false`. When true, `mipLevelCount` is
- *     computed via `numMipLevels({ width, height })`; when false, forced 1.
+ *   - `mipmap`: `true` (default) or `false`. When true, the producer requests
+ *     generated mips; when false, it keeps one authored level.
  * @returns `ok(TextureAsset)` on success; `err(ImageError)` on failure.
  *
  * @example
@@ -110,17 +109,13 @@ export async function decodeImageBytes(
 
   const dec = decoded.value;
   const format: GPUTextureFormat = colorSpace === 'srgb' ? 'rgba8unorm-srgb' : 'rgba8unorm';
-  const mipLevelCount = mipmap ? numMipLevels({ width: dec.width, height: dec.height }) : 1;
-
   const pod: TextureAsset = {
     kind: 'texture',
-    width: dec.width,
-    height: dec.height,
+    shape: { viewDimension: '2d', extent: { width: dec.width, height: dec.height } },
     format,
     data: dec.bytes,
     colorSpace,
-    mipmap,
-    mipLevelCount,
+    mips: mipmap ? { kind: 'generate' } : { kind: 'none' },
   };
   return ok(pod);
 }

package/src/errors/asset.ts

@@ -18,6 +18,39 @@ import {
   type AssetMeshBinContractViolationReason,
 } from '@forgeax/engine-types';
 
+export type TexturePackVerificationCause =
+  | 'byte-length'
+  | 'digest-mismatch'
+  | 'packing-order-mismatch'
+  | 'shape-mismatch';
+
+export interface TexturePackVerificationDetail {
+  readonly guid: string;
+  readonly sourceKey: string;
+  readonly generation: number;
+  readonly stage: 'producer' | 'loader';
+  readonly cause: TexturePackVerificationCause;
+  readonly expectedBytes?: number;
+  readonly actualBytes?: number;
+  readonly expectedDigest?: string;
+  readonly actualDigest?: string;
+}
+
+/** Structured failure for the producer/loader texture contract. */
+export class TexturePackVerificationError extends Error {
+  readonly code = 'texture-pack-verification-failed' as const;
+  readonly expected: string;
+  readonly hint = 'repair the producer output and retry the same texture GUID generation';
+  readonly detail: TexturePackVerificationDetail;
+
+  constructor(detail: TexturePackVerificationDetail, expected: string) {
+    super(`[TexturePackVerificationError] ${detail.cause}: ${expected}`);
+    this.name = 'TexturePackVerificationError';
+    this.expected = expected;
+    this.detail = detail;
+  }
+}
+
 export class MeshBinAssetError extends AssetError {
   readonly subject = 'mesh-bin' as const;
   readonly sourceKey: string;