@plasius/gpu-model-runtime 0.1.1 → 0.2.1

package/dist/index.js

@@ -29,8 +29,117 @@ function createModelCacheKey(contentHash, formatId, adapterOptions) {
   return `${formatId}:${contentHash}:${JSON.stringify(stableValue(adapterOptions ?? null))}`;
 }
 
+// src/types.ts
+var DEFAULT_MODEL_MAX_BYTES = 64 * 1024 * 1024;
+
+// src/bytes.ts
+var ModelResourceTooLargeError = class extends Error {
+  code = "MODEL_RESOURCE_TOO_LARGE";
+  constructor() {
+    super("Model resource exceeds maxBytes");
+    this.name = "ModelResourceTooLargeError";
+  }
+};
+function byteLimit(value = DEFAULT_MODEL_MAX_BYTES) {
+  if (!Number.isSafeInteger(value) || value <= 0) throw new RangeError("maxBytes must be a positive safe integer");
+  return value;
+}
+function checkSize(size, maxBytes) {
+  if (size > maxBytes) throw new ModelResourceTooLargeError();
+}
+function checkAbort(signal) {
+  if (signal?.aborted) throw new DOMException("The model load was aborted", "AbortError");
+}
+function acquisitionController(signal, timeoutMs = 3e4, parent) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2147483647) {
+    throw new RangeError("timeoutMs must be a positive timer-safe integer");
+  }
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  signal?.addEventListener("abort", abort, { once: true });
+  parent?.addEventListener("abort", abort, { once: true });
+  if (signal?.aborted || parent?.aborted) controller.abort();
+  const timer = setTimeout(abort, timeoutMs);
+  return {
+    signal: controller.signal,
+    dispose() {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+      parent?.removeEventListener("abort", abort);
+    }
+  };
+}
+async function abortable(work, signal) {
+  return new Promise((resolve, reject) => {
+    const abort = () => {
+      signal.removeEventListener("abort", abort);
+      reject(new DOMException("The model load was aborted", "AbortError"));
+    };
+    signal.addEventListener("abort", abort, { once: true });
+    if (signal.aborted) abort();
+    work.then(
+      (value) => {
+        signal.removeEventListener("abort", abort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", abort);
+        reject(error);
+      }
+    );
+  });
+}
+function cleanup(work) {
+  try {
+    void Promise.resolve(work()).catch(() => {
+    });
+  } catch {
+  }
+}
+async function readBoundedStream(source, maxBytes, signal) {
+  let bytes = new Uint8Array(0);
+  let length = 0;
+  let chunks = 0;
+  const reader = "getReader" in source ? source.getReader() : void 0;
+  const iterator = reader ? void 0 : source[Symbol.asyncIterator]();
+  try {
+    while (true) {
+      checkAbort(signal);
+      if (++chunks % 256 === 0) await abortable(new Promise((resolve) => setTimeout(resolve, 0)), 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");
+      const chunk = next.value;
+      if (chunk.byteLength > maxBytes - length) throw new ModelResourceTooLargeError();
+      const required = length + chunk.byteLength;
+      if (required > bytes.length) {
+        const grown = new Uint8Array(Math.min(maxBytes, Math.max(required, bytes.length * 2, 4096)));
+        grown.set(bytes.subarray(0, length));
+        bytes = grown;
+      }
+      bytes.set(chunk, length);
+      length = required;
+    }
+    return bytes.length === length ? bytes : bytes.slice(0, length);
+  } catch (error) {
+    if (reader) cleanup(() => reader.cancel());
+    else cleanup(() => iterator?.return?.());
+    throw error;
+  } finally {
+    reader?.releaseLock();
+  }
+}
+async function boundedBytes(input, maxBytes, signal) {
+  checkAbort(signal);
+  checkSize(input instanceof Blob ? input.size : input.byteLength, maxBytes);
+  if (input instanceof Blob) return readBoundedStream(input.stream(), maxBytes, signal);
+  return new Uint8Array(input);
+}
+
 // src/fetch.ts
 var DEFAULT_POLICY = {
+  maxBytes: DEFAULT_MODEL_MAX_BYTES,
   maxAttempts: 3,
   baseDelayMs: 100,
   maxDelayMs: 1e3,
@@ -61,6 +170,7 @@ async function sha256Hex(bytes) {
 }
 async function fetchResource(url, options) {
   const policy = { ...DEFAULT_POLICY, ...options.policy };
+  const maxBytes = Math.min(byteLimit(policy.maxBytes), byteLimit(options.resolveOptions?.maxBytes ?? policy.maxBytes));
   const headers = new Headers(options.headers);
   if (options.resolveOptions?.range) {
     const { start, end } = options.resolveOptions.range;
@@ -68,13 +178,21 @@ async function fetchResource(url, options) {
   }
   let lastError;
   for (let attempt = 1; attempt <= policy.maxAttempts; attempt += 1) {
-    const controller = createRequestController(options.resolveOptions?.signal, policy.timeoutMs);
+    const controller = acquisitionController(options.resolveOptions?.signal, policy.timeoutMs);
     try {
-      const response = await options.fetch(url, {
+      checkAbort(controller.signal);
+      const response = await abortable(options.fetch(url, {
         headers,
         signal: controller.signal
-      });
+      }).then((response2) => {
+        if (controller.signal.aborted) {
+          cleanup(() => response2.body?.cancel());
+          checkAbort(controller.signal);
+        }
+        return response2;
+      }), controller.signal);
       if (!response.ok) {
+        cleanup(() => response.body?.cancel());
         if (!RETRYABLE_STATUSES.has(response.status)) {
           throw new NonRetryableResourceError(`Model resource request failed with HTTP ${response.status}`);
         }
@@ -82,11 +200,20 @@ async function fetchResource(url, options) {
           throw new NonRetryableResourceError(`Model resource request failed with HTTP ${response.status}`);
         }
         lastError = new Error(`Retryable model resource response: HTTP ${response.status}`);
-        await waitForRetry(options.sleep, attempt, policy, options.resolveOptions?.signal);
+        await waitForRetry(options.sleep, attempt, policy, controller.signal);
         continue;
       }
-      const bytes = new Uint8Array(await response.arrayBuffer());
-      await verifyIntegrity(bytes, options.integrity, options.hashBytes);
+      let bytes;
+      try {
+        const declared = response.headers.get("content-length");
+        if (declared !== null && /^\d+$/u.test(declared)) checkSize(Number(declared), maxBytes);
+        bytes = response.body ? await readBoundedStream(response.body, maxBytes, controller.signal) : new Uint8Array(0);
+        checkAbort(controller.signal);
+      } catch (error) {
+        if (!response.body?.locked) cleanup(() => response.body?.cancel());
+        throw error;
+      }
+      await abortable(verifyIntegrity(bytes, options.integrity, options.hashBytes), controller.signal);
       return {
         bytes,
         contentType: response.headers.get("content-type") ?? void 0,
@@ -96,14 +223,14 @@ async function fetchResource(url, options) {
       if (isAbortError(error) || options.resolveOptions?.signal?.aborted) {
         throw createAbortError();
       }
-      if (error instanceof NonRetryableResourceError) {
+      if (error instanceof NonRetryableResourceError || error instanceof ModelResourceTooLargeError) {
         throw error;
       }
       lastError = error;
       if (attempt === policy.maxAttempts) {
         throw error;
       }
-      await waitForRetry(options.sleep, attempt, policy, options.resolveOptions?.signal);
+      await waitForRetry(options.sleep, attempt, policy, controller.signal);
     } finally {
       controller.dispose();
     }
@@ -140,20 +267,7 @@ function bytesToBase64(bytes) {
 }
 async function waitForRetry(sleep, attempt, policy, signal) {
   const delay = Math.min(policy.maxDelayMs, policy.baseDelayMs * 2 ** (attempt - 1));
-  await sleep(delay, signal);
-}
-function createRequestController(signal, timeoutMs) {
-  const controller = new AbortController();
-  const onAbort = () => controller.abort();
-  signal?.addEventListener("abort", onAbort, { once: true });
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  return {
-    signal: controller.signal,
-    dispose: () => {
-      clearTimeout(timer);
-      signal?.removeEventListener("abort", onAbort);
-    }
-  };
+  await abortable(sleep(delay, signal), signal);
 }
 function createAbortError() {
   return new DOMException("The model load was aborted", "AbortError");
@@ -189,6 +303,7 @@ var AdapterRegistry = class {
   }
 };
 var PackageResourceResolver = class {
+  parentSignal;
   memoryResources;
   baseUrl;
   sourceKind;
@@ -199,48 +314,58 @@ var PackageResourceResolver = class {
   headers;
   blobStorageUrlResolver;
   constructor(options) {
+    this.parentSignal = options.signal;
     this.sourceKind = options.sourceKind;
     this.baseUrl = options.package?.baseUrl ?? options.baseUrl;
     this.memoryResources = options.package?.resources ?? {};
     this.fetch = options.fetch;
     this.hashBytes = options.hashBytes;
     this.sleep = options.sleep;
-    this.fetchPolicy = options.fetchPolicy;
+    this.fetchPolicy = { ...options.fetchPolicy };
     this.headers = options.headers;
     this.blobStorageUrlResolver = options.blobStorageUrlResolver;
   }
   async resolve(reference, options = {}) {
-    const requested = typeof reference === "string" ? { path: reference } : reference;
-    const memoryKey = normalizePackagePath(requested.path);
-    const memoryResource = this.memoryResources[memoryKey] ?? this.memoryResources[`./${memoryKey}`];
-    if (memoryResource) {
-      const bytes = await toBytes(memoryResource.bytes);
-      await verifyResourceIntegrity(bytes, requested.integrity ?? memoryResource.integrity, this.hashBytes);
+    const inheritedLimit = byteLimit(this.fetchPolicy?.maxBytes);
+    const maxBytes = Math.min(inheritedLimit, byteLimit(options.maxBytes ?? inheritedLimit));
+    const controller = acquisitionController(options.signal, this.fetchPolicy?.timeoutMs, this.parentSignal);
+    try {
+      checkAbort(controller.signal);
+      const requested = typeof reference === "string" ? { path: reference } : reference;
+      const memoryKey = normalizePackagePath(requested.path);
+      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);
+        return {
+          path: memoryKey,
+          bytes,
+          contentType: requested.contentType ?? memoryResource.contentType,
+          contentHash: await abortable(this.hashBytes(bytes), controller.signal),
+          rangeSupported: false
+        };
+      }
+      const url = await abortable(this.resolveUrl(requested.path), controller.signal);
+      checkAbort(controller.signal);
+      const result = await fetchResource(url, {
+        fetch: this.fetch,
+        hashBytes: this.hashBytes,
+        sleep: this.sleep,
+        headers: this.headers,
+        integrity: requested.integrity,
+        policy: this.fetchPolicy,
+        resolveOptions: { ...options, maxBytes, signal: controller.signal }
+      });
       return {
         path: memoryKey,
-        bytes,
-        contentType: requested.contentType ?? memoryResource.contentType,
-        contentHash: await this.hashBytes(bytes),
-        rangeSupported: false
+        bytes: result.bytes,
+        contentType: requested.contentType ?? result.contentType,
+        contentHash: await abortable(this.hashBytes(result.bytes), controller.signal),
+        rangeSupported: result.rangeSupported
       };
+    } finally {
+      controller.dispose();
     }
-    const url = await this.resolveUrl(requested.path);
-    const result = await fetchResource(url, {
-      fetch: this.fetch,
-      hashBytes: this.hashBytes,
-      sleep: this.sleep,
-      headers: this.headers,
-      integrity: requested.integrity,
-      policy: this.fetchPolicy,
-      resolveOptions: options
-    });
-    return {
-      path: memoryKey,
-      bytes: result.bytes,
-      contentType: requested.contentType ?? result.contentType,
-      contentHash: await this.hashBytes(result.bytes),
-      rangeSupported: result.rangeSupported
-    };
   }
   async resolveUrl(reference) {
     if (/^[a-z][a-z\d+.-]*:/iu.test(reference)) {
@@ -299,7 +424,7 @@ var ModelRuntime = class {
       fileName: input.fileName,
       sourceKind: source.kind
     }, options.formatId);
-    const cacheKey = createModelCacheKey(input.contentHash, adapter.formatId, options.adapterOptions);
+    const cacheKey = createModelCacheKey(input.contentHash, adapter.formatId, { adapterOptions: options.adapterOptions ?? null, maxBytes: byteLimit(options.fetchPolicy?.maxBytes) });
     const useCache = options.useCache ?? true;
     if (useCache) {
       const cached = await this.cache.get(cacheKey);
@@ -345,54 +470,64 @@ var ModelRuntime = class {
     return adapter.load(input, context);
   }
   async resolveSource(source, options) {
-    const fileName = sourceFileName(source);
-    const baseUrl = "url" in source ? source.url : void 0;
-    const headers = "headers" in source ? source.headers : void 0;
-    let bytes;
-    let contentType = "mimeTypeHint" in source ? source.mimeTypeHint : void 0;
-    let rangeSupported = false;
-    if (source.kind === "file-path") {
-      if (!this.readFile) {
-        throw new Error("file-path sources require a readFile dependency");
+    const maxBytes = byteLimit(options.fetchPolicy?.maxBytes);
+    const controller = acquisitionController(options.signal, options.fetchPolicy?.timeoutMs);
+    try {
+      checkAbort(controller.signal);
+      const fileName = sourceFileName(source);
+      const baseUrl = "url" in source ? source.url : void 0;
+      const headers = "headers" in source ? source.headers : void 0;
+      let bytes;
+      let contentType = "mimeTypeHint" in source ? source.mimeTypeHint : void 0;
+      let rangeSupported = false;
+      if (source.kind === "file-path") {
+        if (!this.readFile) {
+          throw new Error("file-path sources require a readFile dependency");
+        }
+        bytes = await abortable(this.readFile(source.path, controller.signal, { maxBytes }), controller.signal);
+        checkSize(bytes.byteLength, maxBytes);
+      } else if (source.kind === "url" || source.kind === "blob-storage-url") {
+        const result = await fetchResource(ensureHttpUrl(source.url), {
+          fetch: this.fetch,
+          hashBytes: this.hashBytes,
+          sleep: this.sleep,
+          headers,
+          integrity: options.integrity,
+          policy: options.fetchPolicy,
+          resolveOptions: { signal: controller.signal }
+        });
+        bytes = result.bytes;
+        contentType ??= result.contentType;
+        rangeSupported = result.rangeSupported;
+      } else {
+        bytes = await sourceToBytes(source, maxBytes, controller.signal);
       }
-      bytes = await this.readFile(source.path, options.signal);
-    } else if (source.kind === "url" || source.kind === "blob-storage-url") {
-      const result = await fetchResource(ensureHttpUrl(source.url), {
+      checkAbort(controller.signal);
+      const contentHash = await abortable(this.hashBytes(bytes), controller.signal);
+      const resourceResolver = new PackageResourceResolver({
+        sourceKind: source.kind,
+        signal: options.signal,
+        baseUrl,
+        package: source.package,
         fetch: this.fetch,
         hashBytes: this.hashBytes,
         sleep: this.sleep,
+        fetchPolicy: options.fetchPolicy,
         headers,
-        integrity: options.integrity,
-        policy: options.fetchPolicy,
-        resolveOptions: { signal: options.signal }
+        blobStorageUrlResolver: this.blobStorageUrlResolver
       });
-      bytes = result.bytes;
-      contentType ??= result.contentType;
-      rangeSupported = result.rangeSupported;
-    } else {
-      bytes = await sourceToBytes(source);
-    }
-    const contentHash = await this.hashBytes(bytes);
-    const resourceResolver = new PackageResourceResolver({
-      sourceKind: source.kind,
-      baseUrl,
-      package: source.package,
-      fetch: this.fetch,
-      hashBytes: this.hashBytes,
-      sleep: this.sleep,
-      fetchPolicy: options.fetchPolicy,
-      headers,
-      blobStorageUrlResolver: this.blobStorageUrlResolver
-    });
-    return {
-      source,
-      bytes,
-      contentType,
-      fileName,
-      contentHash,
-      rangeSupported,
-      resourceResolver
-    };
+      return {
+        source,
+        bytes,
+        contentType,
+        fileName,
+        contentHash,
+        rangeSupported,
+        resourceResolver
+      };
+    } finally {
+      controller.dispose();
+    }
   }
 };
 function scoreRegistration(registration, input) {
@@ -424,50 +559,11 @@ function normalizePackagePath(path) {
   }
   return segments.join("/");
 }
-async function sourceToBytes(source) {
-  if (source.kind === "blob") {
-    return toBytes(source.blob);
-  }
-  if (source.kind === "array-buffer") {
-    return new Uint8Array(source.bytes);
-  }
-  if (source.kind === "uint8-array") {
-    return new Uint8Array(source.bytes);
-  }
-  const chunks = [];
-  if (Symbol.asyncIterator in Object(source.stream)) {
-    for await (const chunk of source.stream) {
-      chunks.push(new Uint8Array(chunk));
-    }
-  } else {
-    const reader = source.stream.getReader();
-    try {
-      while (true) {
-        const next = await reader.read();
-        if (next.done) break;
-        chunks.push(new Uint8Array(next.value));
-      }
-    } finally {
-      reader.releaseLock();
-    }
-  }
-  const length = chunks.reduce((total, chunk) => total + chunk.byteLength, 0);
-  const bytes = new Uint8Array(length);
-  let offset = 0;
-  for (const chunk of chunks) {
-    bytes.set(chunk, offset);
-    offset += chunk.byteLength;
-  }
-  return bytes;
-}
-async function toBytes(input) {
-  if (input instanceof Blob) {
-    return new Uint8Array(await input.arrayBuffer());
-  }
-  if (input instanceof Uint8Array) {
-    return new Uint8Array(input);
-  }
-  return new Uint8Array(input);
+async function sourceToBytes(source, maxBytes, signal) {
+  if (source.kind === "blob") return boundedBytes(source.blob, maxBytes, signal);
+  if (source.kind === "array-buffer" || source.kind === "uint8-array") return boundedBytes(source.bytes, 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;
@@ -507,6 +603,636 @@ function ensureHttpUrl(value) {
   return url.href;
 }
 
+// src/model-residency.ts
+var SHA256_PATTERN = /^[a-f0-9]{64}$/u;
+var PARTITION_ID_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/u;
+var ModelResidencyError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "ModelResidencyError";
+    this.code = code;
+  }
+};
+function requireSafeNonNegativeInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new RangeError(`${name} must be a non-negative safe integer`);
+  }
+}
+function requirePositiveSafeInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new RangeError(`${name} must be a positive safe integer`);
+  }
+}
+function requirePriority(priority) {
+  if (!Number.isFinite(priority) || priority < 0) {
+    throw new RangeError("priority must be a non-negative finite number");
+  }
+}
+function requireLod(lod) {
+  if (!Number.isInteger(lod) || lod < 0 || lod > 3) {
+    throw new RangeError("lod must be an integer from 0 to 3");
+  }
+}
+function createModelResidencyKey(assetRef, lod, partitionId) {
+  if (!SHA256_PATTERN.test(assetRef.contentHash)) {
+    throw new Error("ModelAssetRef.contentHash must be a lowercase SHA-256 value");
+  }
+  requireLod(lod);
+  if (partitionId !== void 0 && !PARTITION_ID_PATTERN.test(partitionId)) {
+    throw new Error("partitionId must be a bounded runtime token");
+  }
+  return `${assetRef.contentHash}:lod${lod}:${partitionId ?? "whole"}`;
+}
+function closedError() {
+  return new ModelResidencyError(
+    "manager-closed",
+    "The model residency manager is closed"
+  );
+}
+function abortedError() {
+  return new ModelResidencyError(
+    "acquire-aborted",
+    "The model residency acquisition was aborted"
+  );
+}
+function signalIsAborted(signal) {
+  return signal?.aborted === true;
+}
+var ModelResidencyManager = class {
+  #budget;
+  #load;
+  #loadTimeoutMs;
+  #entries = /* @__PURE__ */ new Map();
+  #loadTasks = /* @__PURE__ */ new Set();
+  #disposalTasks = /* @__PURE__ */ new Set();
+  #metrics = {
+    acquireCount: 0,
+    cacheHits: 0,
+    deduplicatedAcquires: 0,
+    loadsStarted: 0,
+    loadsCompleted: 0,
+    loadsFailed: 0,
+    loadsAborted: 0,
+    loadsTimedOut: 0,
+    evictions: 0,
+    disposals: 0,
+    disposalFailures: 0
+  };
+  #nextIdentity = 1;
+  #clock = 1;
+  #inFlightLoads = 0;
+  #closed = false;
+  #admissionTail = Promise.resolve();
+  #shutdownPromise;
+  constructor(options) {
+    requirePositiveSafeInteger(
+      options.budget.maxCpuBytes,
+      "budget.maxCpuBytes"
+    );
+    requirePositiveSafeInteger(
+      options.budget.maxGpuBytes,
+      "budget.maxGpuBytes"
+    );
+    requirePositiveSafeInteger(
+      options.budget.maxInFlightLoads,
+      "budget.maxInFlightLoads"
+    );
+    if (options.loadTimeoutMs !== void 0) {
+      requirePositiveSafeInteger(options.loadTimeoutMs, "loadTimeoutMs");
+    }
+    this.#budget = Object.freeze({ ...options.budget });
+    this.#load = options.load;
+    this.#loadTimeoutMs = options.loadTimeoutMs;
+  }
+  /** Acquire one shared resource lease, loading it at most once per cache key. */
+  acquire(options) {
+    try {
+      if (this.#closed) throw closedError();
+      requirePriority(options.priority);
+      requireSafeNonNegativeInteger(
+        options.estimatedCpuBytes,
+        "estimatedCpuBytes"
+      );
+      requireSafeNonNegativeInteger(
+        options.estimatedGpuBytes,
+        "estimatedGpuBytes"
+      );
+      const key = createModelResidencyKey(
+        options.assetRef,
+        options.lod,
+        options.partitionId
+      );
+      if (signalIsAborted(options.signal)) throw abortedError();
+      this.#metrics.acquireCount += 1;
+      const existing = this.#entries.get(key);
+      if (existing !== void 0) return this.#acquireExisting(existing, options);
+      return this.#scheduleAdmission(key, options);
+    } catch (error) {
+      return Promise.reject(error);
+    }
+  }
+  #acquireExisting(entry, options) {
+    this.#metrics.deduplicatedAcquires += 1;
+    if (entry.state === "resident") {
+      this.#metrics.cacheHits += 1;
+      return Promise.resolve(
+        this.#createLease(
+          entry,
+          options.priority,
+          options.pinned ?? false
+        )
+      );
+    }
+    return this.#addWaiter(entry, options);
+  }
+  #scheduleAdmission(key, options) {
+    let resolveAcquisition;
+    let rejectAcquisition;
+    const acquisition = new Promise(
+      (resolve, reject) => {
+        resolveAcquisition = resolve;
+        rejectAcquisition = reject;
+      }
+    );
+    const admission = this.#admissionTail.then(async () => {
+      if (this.#closed) throw closedError();
+      if (signalIsAborted(options.signal)) throw abortedError();
+      const existing = this.#entries.get(key);
+      if (existing !== void 0) {
+        void this.#acquireExisting(existing, options).then(
+          resolveAcquisition,
+          rejectAcquisition
+        );
+        return;
+      }
+      await this.#ensureCapacityForReservation(
+        options.estimatedCpuBytes,
+        options.estimatedGpuBytes
+      );
+      if (this.#closed) throw closedError();
+      if (signalIsAborted(options.signal)) throw abortedError();
+      const entry = {
+        key,
+        assetRef: options.assetRef,
+        lod: options.lod,
+        ...options.partitionId === void 0 ? {} : { partitionId: options.partitionId },
+        estimatedCpuBytes: options.estimatedCpuBytes,
+        estimatedGpuBytes: options.estimatedGpuBytes,
+        queueOrder: this.#nextIdentity++,
+        state: "queued",
+        priority: options.priority,
+        retainedPriority: options.priority,
+        lastUsed: this.#clock++,
+        abandoned: false,
+        loadSlotReleased: true,
+        waiters: /* @__PURE__ */ new Map(),
+        leases: /* @__PURE__ */ new Map()
+      };
+      this.#entries.set(key, entry);
+      void this.#addWaiter(entry, options).then(
+        resolveAcquisition,
+        rejectAcquisition
+      );
+      this.#pumpQueue();
+    });
+    this.#admissionTail = admission.catch(() => void 0);
+    void admission.catch(rejectAcquisition);
+    return acquisition;
+  }
+  /** Dispose every currently unreferenced, unpinned resident cache entry. */
+  async evictUnused() {
+    const tasks = [];
+    for (const entry of this.#evictionCandidates()) {
+      tasks.push(this.#evict(entry));
+    }
+    await Promise.all(tasks);
+  }
+  /** Wait until queued/loading work and its resulting disposal have settled. */
+  async waitForIdle() {
+    await this.#admissionTail;
+    do {
+      this.#pumpQueue();
+      const tasks = [...this.#loadTasks];
+      if (tasks.length > 0) {
+        await Promise.allSettled(tasks);
+      }
+    } while (this.#loadTasks.size > 0 || this.#queuedCount() > 0);
+    await Promise.allSettled([...this.#disposalTasks]);
+  }
+  /** Abort pending work and dispose every resident or late-completing resource. */
+  shutdown() {
+    if (this.#shutdownPromise !== void 0) return this.#shutdownPromise;
+    this.#closed = true;
+    const error = closedError();
+    const disposalTasks = [];
+    for (const entry of [...this.#entries.values()]) {
+      if (entry.state === "resident") {
+        this.#entries.delete(entry.key);
+        disposalTasks.push(this.#disposeEntry(entry));
+        continue;
+      }
+      this.#rejectWaiters(entry, error);
+      if (entry.state === "queued") {
+        this.#entries.delete(entry.key);
+      } else {
+        this.#abandonLoadingEntry(entry, error, false);
+      }
+    }
+    this.#shutdownPromise = (async () => {
+      await Promise.allSettled(disposalTasks);
+      await this.waitForIdle();
+      await Promise.allSettled([...this.#disposalTasks]);
+    })();
+    return this.#shutdownPromise;
+  }
+  /** Return immutable byte, queue, cache, and lifetime metrics. */
+  snapshot() {
+    let cpuBytes = 0;
+    let gpuBytes = 0;
+    let reservedCpuBytes = 0;
+    let reservedGpuBytes = 0;
+    let referenceCount = 0;
+    let pinnedCount = 0;
+    let residentCount = 0;
+    let pendingCount = 0;
+    const entries = [];
+    for (const entry of this.#entries.values()) {
+      const pinned = [...entry.leases.values()].some(
+        (lease) => lease.active && lease.pinned
+      );
+      const references = [...entry.leases.values()].filter(
+        (lease) => lease.active
+      ).length;
+      referenceCount += references;
+      if (pinned) pinnedCount += 1;
+      if (entry.state === "resident") {
+        residentCount += 1;
+        cpuBytes += entry.loaded.cpuBytes;
+        gpuBytes += entry.loaded.gpuBytes;
+      } else {
+        pendingCount += 1;
+        reservedCpuBytes += entry.estimatedCpuBytes;
+        reservedGpuBytes += entry.estimatedGpuBytes;
+      }
+      entries.push(
+        Object.freeze({
+          key: entry.key,
+          state: entry.state,
+          priority: entry.priority,
+          references,
+          pinned,
+          cpuBytes: entry.state === "resident" ? entry.loaded.cpuBytes : entry.estimatedCpuBytes,
+          gpuBytes: entry.state === "resident" ? entry.loaded.gpuBytes : entry.estimatedGpuBytes
+        })
+      );
+    }
+    entries.sort((left, right) => left.key.localeCompare(right.key));
+    return Object.freeze({
+      ...this.#budget,
+      cpuBytes,
+      gpuBytes,
+      reservedCpuBytes,
+      reservedGpuBytes,
+      residentCount,
+      pendingCount,
+      referenceCount,
+      pinnedCount,
+      inFlightLoads: this.#inFlightLoads,
+      queuedLoads: this.#queuedCount(),
+      ...this.#metrics,
+      residentKeys: Object.freeze(
+        entries.filter((entry) => entry.state === "resident").map((entry) => entry.key)
+      ),
+      entries: Object.freeze(entries)
+    });
+  }
+  #addWaiter(entry, options) {
+    const id = this.#nextIdentity++;
+    let resolvePromise;
+    let rejectPromise;
+    const promise = new Promise(
+      (resolve, reject) => {
+        resolvePromise = resolve;
+        rejectPromise = reject;
+      }
+    );
+    const waiter = {
+      id,
+      priority: options.priority,
+      pinned: options.pinned ?? false,
+      ...options.signal === void 0 ? {} : { signal: options.signal },
+      resolve: resolvePromise,
+      reject: rejectPromise
+    };
+    if (options.signal !== void 0) {
+      waiter.onAbort = () => this.#abortWaiter(entry, waiter);
+      options.signal.addEventListener("abort", waiter.onAbort, { once: true });
+    }
+    entry.waiters.set(id, waiter);
+    entry.retainedPriority = Math.max(entry.retainedPriority, options.priority);
+    this.#recalculatePriority(entry);
+    return promise;
+  }
+  #abortWaiter(entry, waiter) {
+    entry.waiters.delete(waiter.id);
+    this.#detachWaiterSignal(waiter);
+    waiter.reject(abortedError());
+    this.#recalculatePriority(entry);
+    if (entry.waiters.size > 0) return;
+    if (entry.state === "queued") {
+      this.#entries.delete(entry.key);
+      this.#pumpQueue();
+      return;
+    }
+    this.#abandonLoadingEntry(entry, abortedError(), true);
+  }
+  #createLease(entry, priority, pinned) {
+    const id = this.#nextIdentity++;
+    const record = {
+      id,
+      active: true,
+      priority,
+      pinned
+    };
+    entry.leases.set(id, record);
+    entry.retainedPriority = priority;
+    entry.lastUsed = this.#clock++;
+    this.#recalculatePriority(entry);
+    const lease = {
+      key: entry.key,
+      assetRef: entry.assetRef,
+      lod: entry.lod,
+      ...entry.partitionId === void 0 ? {} : { partitionId: entry.partitionId },
+      resource: entry.loaded.resource,
+      release: () => {
+        if (!record.active) return;
+        record.active = false;
+        entry.leases.delete(id);
+        entry.lastUsed = this.#clock++;
+        this.#recalculatePriority(entry);
+      },
+      setPriority: (nextPriority) => {
+        if (!record.active || this.#entries.get(entry.key) !== entry) return;
+        requirePriority(nextPriority);
+        record.priority = nextPriority;
+        entry.retainedPriority = nextPriority;
+        entry.lastUsed = this.#clock++;
+        this.#recalculatePriority(entry);
+      },
+      setPinned: (nextPinned) => {
+        if (!record.active || this.#entries.get(entry.key) !== entry) return;
+        record.pinned = nextPinned;
+      }
+    };
+    return Object.freeze(lease);
+  }
+  #recalculatePriority(entry) {
+    let priority = entry.retainedPriority;
+    for (const waiter of entry.waiters.values()) {
+      priority = Math.max(priority, waiter.priority);
+    }
+    for (const lease of entry.leases.values()) {
+      priority = Math.max(priority, lease.priority);
+    }
+    entry.priority = priority;
+  }
+  #pumpQueue() {
+    if (this.#closed) return;
+    while (this.#inFlightLoads < this.#budget.maxInFlightLoads) {
+      const candidate = [...this.#entries.values()].filter(
+        (entry) => entry.state === "queued" && !entry.abandoned && entry.waiters.size > 0
+      ).sort(
+        (left, right) => right.priority - left.priority || left.queueOrder - right.queueOrder
+      )[0];
+      if (candidate === void 0) return;
+      this.#startLoad(candidate);
+    }
+  }
+  #startLoad(entry) {
+    entry.state = "loading";
+    entry.loadSlotReleased = false;
+    entry.controller = new AbortController();
+    this.#inFlightLoads += 1;
+    this.#metrics.loadsStarted += 1;
+    if (this.#loadTimeoutMs !== void 0) {
+      entry.timeout = setTimeout(() => {
+        this.#metrics.loadsTimedOut += 1;
+        this.#abandonLoadingEntry(
+          entry,
+          new ModelResidencyError(
+            "load-timeout",
+            `Model load exceeded ${this.#loadTimeoutMs} ms`
+          ),
+          true
+        );
+      }, this.#loadTimeoutMs);
+    }
+    let adapterPromise;
+    try {
+      adapterPromise = this.#load({
+        assetRef: entry.assetRef,
+        lod: entry.lod,
+        ...entry.partitionId === void 0 ? {} : { partitionId: entry.partitionId },
+        priority: entry.priority,
+        signal: entry.controller.signal
+      });
+    } catch (error) {
+      adapterPromise = Promise.reject(error);
+    }
+    const task = Promise.resolve(adapterPromise).then((result) => this.#completeLoad(entry, result)).catch((error) => this.#failLoad(entry, error)).finally(() => {
+      if (entry.timeout !== void 0) clearTimeout(entry.timeout);
+      entry.timeout = void 0;
+      entry.controller = void 0;
+      this.#releaseLoadSlot(entry);
+      entry.loadTask = void 0;
+    });
+    entry.loadTask = task;
+    this.#loadTasks.add(task);
+  }
+  async #completeLoad(entry, result) {
+    if (entry.abandoned) {
+      await this.#disposeLoaded(result);
+      return;
+    }
+    try {
+      this.#validateLoadedResource(entry, result);
+      const evictions = this.#ensureCapacityForLoadedResult(entry, result);
+      await Promise.all(evictions);
+    } catch (error) {
+      await this.#disposeLoaded(result);
+      this.#entries.delete(entry.key);
+      this.#rejectWaiters(entry, error);
+      this.#metrics.loadsFailed += 1;
+      return;
+    }
+    entry.state = "resident";
+    entry.loaded = result;
+    entry.lastUsed = this.#clock++;
+    this.#metrics.loadsCompleted += 1;
+    const waiters = [...entry.waiters.values()];
+    entry.waiters.clear();
+    for (const waiter of waiters) {
+      this.#detachWaiterSignal(waiter);
+      waiter.resolve(this.#createLease(entry, waiter.priority, waiter.pinned));
+    }
+  }
+  #failLoad(entry, error) {
+    if (entry.abandoned) return;
+    this.#entries.delete(entry.key);
+    this.#metrics.loadsFailed += 1;
+    this.#rejectWaiters(entry, error);
+  }
+  #abandonLoadingEntry(entry, error, rejectWaiters) {
+    entry.abandoned = true;
+    this.#metrics.loadsAborted += 1;
+    if (entry.timeout !== void 0) clearTimeout(entry.timeout);
+    entry.timeout = void 0;
+    this.#entries.delete(entry.key);
+    if (rejectWaiters) this.#rejectWaiters(entry, error);
+    entry.controller?.abort(error);
+    this.#releaseLoadSlot(entry);
+  }
+  #releaseLoadSlot(entry) {
+    if (entry.loadSlotReleased) return;
+    entry.loadSlotReleased = true;
+    this.#inFlightLoads -= 1;
+    this.#loadTasks.delete(entry.loadTask);
+    this.#pumpQueue();
+  }
+  #rejectWaiters(entry, error) {
+    const waiters = [...entry.waiters.values()];
+    entry.waiters.clear();
+    for (const waiter of waiters) {
+      this.#detachWaiterSignal(waiter);
+      waiter.reject(error);
+    }
+    this.#recalculatePriority(entry);
+  }
+  #detachWaiterSignal(waiter) {
+    if (waiter.signal !== void 0 && waiter.onAbort !== void 0) {
+      waiter.signal.removeEventListener("abort", waiter.onAbort);
+    }
+    waiter.onAbort = void 0;
+  }
+  #validateLoadedResource(entry, result) {
+    if (result === null || typeof result !== "object") {
+      throw new ModelResidencyError(
+        "invalid-load-result",
+        "The model loader returned an invalid resource"
+      );
+    }
+    if (typeof result.dispose !== "function") {
+      throw new ModelResidencyError(
+        "invalid-load-result",
+        "The model loader must return a disposer"
+      );
+    }
+    requireSafeNonNegativeInteger(result.cpuBytes, "loaded.cpuBytes");
+    requireSafeNonNegativeInteger(result.gpuBytes, "loaded.gpuBytes");
+    if (result.contentHash !== entry.assetRef.contentHash) {
+      throw new ModelResidencyError(
+        "content-hash-mismatch",
+        "The loaded model content hash does not match its canonical reference"
+      );
+    }
+  }
+  async #ensureCapacityForReservation(cpuBytes, gpuBytes) {
+    if (cpuBytes > this.#budget.maxCpuBytes || gpuBytes > this.#budget.maxGpuBytes) {
+      throw this.#budgetError();
+    }
+    let usage = this.#totalAccountedBytes();
+    for (const candidate of this.#evictionCandidates()) {
+      if (usage.cpu + cpuBytes <= this.#budget.maxCpuBytes && usage.gpu + gpuBytes <= this.#budget.maxGpuBytes) {
+        return;
+      }
+      await this.#evict(candidate);
+      usage = this.#totalAccountedBytes();
+    }
+    if (usage.cpu + cpuBytes > this.#budget.maxCpuBytes || usage.gpu + gpuBytes > this.#budget.maxGpuBytes) {
+      throw this.#budgetError();
+    }
+  }
+  #ensureCapacityForLoadedResult(loadingEntry, result) {
+    const usage = this.#totalAccountedBytes();
+    usage.cpu += result.cpuBytes - loadingEntry.estimatedCpuBytes;
+    usage.gpu += result.gpuBytes - loadingEntry.estimatedGpuBytes;
+    const disposals = [];
+    for (const candidate of this.#evictionCandidates()) {
+      if (usage.cpu <= this.#budget.maxCpuBytes && usage.gpu <= this.#budget.maxGpuBytes) {
+        return disposals;
+      }
+      usage.cpu -= candidate.loaded.cpuBytes;
+      usage.gpu -= candidate.loaded.gpuBytes;
+      disposals.push(this.#evict(candidate));
+    }
+    if (usage.cpu > this.#budget.maxCpuBytes || usage.gpu > this.#budget.maxGpuBytes) {
+      throw this.#budgetError();
+    }
+    return disposals;
+  }
+  #budgetError() {
+    return new ModelResidencyError(
+      "budget-exceeded",
+      "Pinned, referenced, or pending models leave insufficient residency budget"
+    );
+  }
+  #totalAccountedBytes() {
+    let cpu = 0;
+    let gpu = 0;
+    for (const entry of this.#entries.values()) {
+      if (entry.state === "resident") {
+        cpu += entry.loaded.cpuBytes;
+        gpu += entry.loaded.gpuBytes;
+      } else {
+        cpu += entry.estimatedCpuBytes;
+        gpu += entry.estimatedGpuBytes;
+      }
+    }
+    return { cpu, gpu };
+  }
+  #evictionCandidates() {
+    return [...this.#entries.values()].filter(
+      (entry) => entry.state === "resident" && entry.leases.size === 0
+    ).sort(
+      (left, right) => left.priority - right.priority || left.lastUsed - right.lastUsed
+    );
+  }
+  #evict(entry) {
+    this.#entries.delete(entry.key);
+    this.#metrics.evictions += 1;
+    return this.#disposeEntry(entry);
+  }
+  #disposeEntry(entry) {
+    const result = entry.loaded;
+    entry.loaded = void 0;
+    return this.#disposeLoaded(result);
+  }
+  #disposeLoaded(result) {
+    this.#metrics.disposals += 1;
+    let disposal;
+    try {
+      disposal = Promise.resolve(result.dispose());
+    } catch (error) {
+      disposal = Promise.reject(error);
+    }
+    const tracked = disposal.catch(() => {
+      this.#metrics.disposalFailures += 1;
+    }).finally(() => {
+      this.#disposalTasks.delete(tracked);
+    });
+    this.#disposalTasks.add(tracked);
+    return tracked;
+  }
+  #queuedCount() {
+    let count = 0;
+    for (const entry of this.#entries.values()) {
+      if (entry.state === "queued") count += 1;
+    }
+    return count;
+  }
+};
+
 // src/index.ts
 var packageName = "@plasius/gpu-model-runtime";
 var packageBootstrap = Object.freeze({
@@ -516,10 +1242,15 @@ var packageBootstrap = Object.freeze({
 });
 export {
   AdapterRegistry,
+  DEFAULT_MODEL_MAX_BYTES,
   MemoryModelCache,
+  ModelResidencyError,
+  ModelResidencyManager,
+  ModelResourceTooLargeError,
   ModelRuntime,
   PackageResourceResolver,
   createModelCacheKey,
+  createModelResidencyKey,
   defaultSleep,
   fetchResource,
   packageBootstrap,