@plasius/gpu-model-runtime 0.2.5 → 0.3.1

package/README.md

@@ -7,8 +7,21 @@ This repository is the dedicated package boundary defined by ADR 0094.
 
 The runtime owns orchestration only. Canonical model documents, diagnostics, and
 renderer-specific data remain owned by the corresponding `@plasius/gpu-model-*`
-packages and are carried through generic type parameters until the core package
-is released.
+packages. Published `@plasius/gpu-model-core@0.6.0` supplies source, provenance,
+diagnostic-mode and canonical document types; runtime `ModelSource` adds the
+optional package-resource descriptor. Existing explicit generic model types
+remain supported. `ModelAdapter`, `AdapterLoadResult` and `ModelLoadResult` now
+have `GpuModelDocument` as their optional type default. `loadModel<T>()` remains
+explicitly generic; an unannotated call still returns an unknown model.
+
+Core imports in runtime source are type-only, so importing this runtime does not
+execute core validators or eagerly load concrete adapters. Adapters own canonical
+validation and strict/tolerant/forensic policy through the core factories and
+evaluator. Runtime returns the resulting document and diagnostic ledger without
+rewriting them. Its `ModelAdapter` is an acquisition/worker port, distinct from
+core's inspect/load/export/validate conversion interface: bind a format adapter's
+factory to the provided resource resolver and map its result in that port;
+do not cast a format module directly to a runtime adapter.
 
 ## Runtime behavior
 
@@ -25,23 +38,28 @@ is released.
   statuses, abort signals, optional byte ranges, response content types, and
   SHA-256 integrity checks.
 - `MemoryModelCache` keys loaded output by content hash, adapter format, and
-  stable adapter options and acquisition byte ceiling. Call `runtime.invalidate()` to clear all entries or
-  entries for one content hash.
+  stable adapter options, acquisition byte ceiling, diagnostic mode and actual
+  execution path. Call `runtime.invalidate()` to clear all entries or entries
+  for one content hash.
 - Worker execution is opt-in through a `WorkerDispatcher`; consumers that do
   not provide one stay on the main execution path.
 
 Example:
 
 ```ts
+import { AdapterRegistry, ModelRuntime, type GpuModelDocument } from "@plasius/gpu-model-runtime";
+
 const registry = new AdapterRegistry().register({
   formatId: "gltf",
   extensions: ["gltf", "glb"],
   sniff: ({ bytes }) => bytes[0] === 0x67,
-  load: () => import("@plasius/gpu-model-gltf"),
+  // A consumer-owned bridge implementing this runtime's ModelAdapter port.
+  // Its factory binds the format adapter to input.resourceResolver.
+  load: () => import("./model-adapters/gltf.js"),
 });
 
 const runtime = new ModelRuntime({ registry });
-const result = await runtime.loadModel({
+const result = await runtime.loadModel<GpuModelDocument>({
   kind: "blob-storage-url",
   url: "https://storage.example.invalid/models/scene.glb?<signed-url>",
 });
@@ -50,6 +68,22 @@ result.canonicalModel;
 result.rendererReady;
 ```
 
+A tolerant or forensic cache entry cannot satisfy a strict request. Mandatory
+worker support is checked before cache lookup; main and worker results have
+separate keys, while `auto` and `always` can share a result when both select the
+worker. Adapters and dispatchers injected by the consumer are trusted execution
+ports; they must honor signals, enforce their own parsing/decoding budgets, and
+return core-validated documents. This package does not supply a Worker script or
+serialize resolver functions across threads. A dispatcher binds its own RPC and
+resource-resolution transport.
+
+New cache keys intentionally cold-start existing external caches. This is a
+patch-compatible policy fix with additive canonical type defaults and one exact
+published dependency (core 0.6.0, previously absent); no concrete adapter is added.
+The new dependency has no runtime dependencies and requires the already-supported
+Node 24. Installed package and strict ESM/CJS declaration checks verify the
+published boundary. Do not use local workspace links.
+
 ## Bounded source acquisition
 
 Every entrypoint and related resource has a default ceiling of 64 MiB
@@ -77,6 +111,13 @@ underestimate never disables actual-byte checks. Hashes still cover the admitted
 bytes, including a returned range. Limits apply to decoded Fetch body bytes;
 compressed Content-Length is only an additional early check.
 
+Integrity accepts a 64-character SHA-256 hex digest (case-insensitive) or its
+standard padded base64 encoding (case-sensitive), with an optional `sha256-`
+prefix. The same verifier applies to fetched and in-memory package resources;
+malformed or mismatched digests fail without retry. Cross-realm `Uint8Array`
+stream chunks are accepted with the same limits and copy ownership, while other
+typed-array kinds, DataViews and spoofed byte-array tags are rejected.
+
 Oversize throws `ModelResourceTooLargeError` with code
 `MODEL_RESOURCE_TOO_LARGE` and a fixed message containing no source identifiers.
 It is not retried. Cancellation and acquisition deadlines stop pending reads,

package/dist/index.cjs

@@ -74,6 +74,10 @@ function createModelCacheKey(contentHash, formatId, adapterOptions) {
 var DEFAULT_MODEL_MAX_BYTES = 64 * 1024 * 1024;
 
 // src/bytes.ts
+var typedArrayKind = Object.getOwnPropertyDescriptor(
+  Object.getPrototypeOf(Uint8Array.prototype),
+  Symbol.toStringTag
+)?.get;
 var ModelResourceTooLargeError = class extends Error {
   code = "MODEL_RESOURCE_TOO_LARGE";
   constructor() {
@@ -150,7 +154,7 @@ async function readBoundedStream(source, maxBytes, signal) {
       const next = await abortable(reader ? reader.read() : iterator.next(), signal);
       checkAbort(signal);
       if (next.done) break;
-      if (!(next.value instanceof Uint8Array)) throw new TypeError("Model stream chunks must be Uint8Array");
+      if (!ArrayBuffer.isView(next.value) || typedArrayKind?.call(next.value) !== "Uint8Array") throw new TypeError("Model stream chunks must be Uint8Array");
       const chunk = next.value;
       if (chunk.byteLength > maxBytes - length) throw new ModelResourceTooLargeError();
       const required = length + chunk.byteLength;
@@ -282,12 +286,15 @@ async function verifyIntegrity(bytes, integrity, hashBytes) {
   if (!integrity) {
     return;
   }
-  const expected = integrity.replace(/^sha256-/iu, "").toLowerCase();
-  const actualHex = (await hashBytes(bytes)).toLowerCase();
-  const actualBase64 = bytesToBase64(await digestBytes(bytes, hashBytes));
-  if (expected !== actualHex && expected !== actualBase64) {
-    throw new NonRetryableResourceError("Model resource integrity check failed");
+  const expected = integrity.replace(/^sha256-/iu, "");
+  if (/^[0-9a-f]{64}$/iu.test(expected)) {
+    const actualHex = await hashBytes(bytes);
+    if (expected.toLowerCase() === actualHex.toLowerCase()) return;
+  } else if (/^[A-Za-z0-9+/]{43}=$/u.test(expected)) {
+    const actualBase64 = bytesToBase64(await digestBytes(bytes, hashBytes));
+    if (expected === actualBase64) return;
   }
+  throw new NonRetryableResourceError("Model resource integrity check failed");
 }
 async function digestBytes(bytes, hashBytes) {
   if (globalThis.crypto?.subtle) {
@@ -377,7 +384,7 @@ var PackageResourceResolver = class {
       const memoryResource = this.memoryResources[memoryKey] ?? this.memoryResources[`./${memoryKey}`];
       if (memoryResource) {
         const bytes = await boundedBytes(memoryResource.bytes, maxBytes, controller.signal);
-        await abortable(verifyResourceIntegrity(bytes, requested.integrity ?? memoryResource.integrity, this.hashBytes), controller.signal);
+        await abortable(verifyIntegrity(bytes, requested.integrity ?? memoryResource.integrity, this.hashBytes), controller.signal);
         return {
           path: memoryKey,
           bytes,
@@ -465,7 +472,23 @@ var ModelRuntime = class {
       fileName: input.fileName,
       sourceKind: source.kind
     }, options.formatId);
-    const cacheKey = createModelCacheKey(input.contentHash, adapter.formatId, { adapterOptions: options.adapterOptions ?? null, maxBytes: byteLimit(options.fetchPolicy?.maxBytes) });
+    const workerMode = options.worker?.mode ?? "auto";
+    const canUseWorker = workerMode !== "never" && Boolean(this.workerDispatcher) && Boolean(adapter.supportsWorker);
+    if (workerMode === "always" && !canUseWorker) {
+      throw new Error(`Adapter ${adapter.formatId} does not support the requested worker execution`);
+    }
+    const context = {
+      signal: options.signal ?? new AbortController().signal,
+      mode: options.mode ?? "strict",
+      execution: canUseWorker ? "worker" : "main",
+      adapterOptions: options.adapterOptions ?? null
+    };
+    const cacheKey = createModelCacheKey(input.contentHash, adapter.formatId, {
+      adapterOptions: context.adapterOptions,
+      maxBytes: byteLimit(options.fetchPolicy?.maxBytes),
+      mode: context.mode,
+      execution: context.execution
+    });
     const useCache = options.useCache ?? true;
     if (useCache) {
       const cached = await this.cache.get(cacheKey);
@@ -473,13 +496,7 @@ var ModelRuntime = class {
         return { ...cached, fromCache: true };
       }
     }
-    const context = {
-      signal: options.signal ?? new AbortController().signal,
-      mode: options.mode ?? "strict",
-      execution: "main",
-      adapterOptions: options.adapterOptions ?? null
-    };
-    const adapterResult = await this.loadWithExecution(adapter, input, context, options);
+    const adapterResult = await this.loadWithExecution(adapter, input, context);
     const result = {
       ...adapterResult,
       contentHash: input.contentHash,
@@ -494,13 +511,8 @@ var ModelRuntime = class {
     }
     return result;
   }
-  async loadWithExecution(adapter, input, context, options) {
-    const workerMode = options.worker?.mode ?? "auto";
-    const canUseWorker = workerMode !== "never" && Boolean(this.workerDispatcher) && Boolean(adapter.supportsWorker);
-    if (workerMode === "always" && !canUseWorker) {
-      throw new Error(`Adapter ${adapter.formatId} does not support the requested worker execution`);
-    }
-    if (canUseWorker && this.workerDispatcher) {
+  async loadWithExecution(adapter, input, context) {
+    if (context.execution === "worker" && this.workerDispatcher) {
       const workerRequest = {
         formatId: adapter.formatId,
         input,
@@ -606,14 +618,6 @@ async function sourceToBytes(source, maxBytes, signal) {
   if (source.byteLengthHint !== void 0) checkSize(source.byteLengthHint, maxBytes);
   return readBoundedStream(source.stream, maxBytes, signal);
 }
-async function verifyResourceIntegrity(bytes, integrity, hashBytes) {
-  if (!integrity) return;
-  const expected = integrity.replace(/^sha256-/iu, "").toLowerCase();
-  const actual = (await hashBytes(bytes)).toLowerCase();
-  if (actual !== expected) {
-    throw new Error("Model resource integrity check failed");
-  }
-}
 var defaultFetch = (input, init) => {
   if (!globalThis.fetch) {
     throw new Error("URL sources require fetch or an injected fetch dependency");