@plasius/gpu-model-runtime 0.1.1 → 0.2.1

package/dist/index.d.ts

@@ -1,3 +1,7 @@
+import { ModelAssetRef, ModelLodLevel } from '@plasius/asset-contracts';
+
+/** Default ceiling per entrypoint or related resource: 64 MiB. */
+declare const DEFAULT_MODEL_MAX_BYTES: number;
 type ModelSourceKind = "file-path" | "url" | "blob-storage-url" | "blob" | "array-buffer" | "uint8-array" | "stream";
 type ModelProvenance = Readonly<{
     sourceId?: string;
@@ -82,6 +86,8 @@ interface ResourceResolver {
     resolve(reference: string | ResourceReference, options?: ResolveResourceOptions): Promise<ResolvedResource>;
 }
 type ResolveResourceOptions = Readonly<{
+    /** Tightens the inherited acquisition ceiling for this resource. */
+    maxBytes?: number;
     signal?: AbortSignal;
     range?: Readonly<{
         start: number;
@@ -89,13 +95,18 @@ type ResolveResourceOptions = Readonly<{
     }>;
 }>;
 type FetchPolicy = Readonly<{
+    /** Maximum bytes per entrypoint/resource, including non-HTTP sources. Default 64 MiB. */
+    maxBytes?: number;
     maxAttempts?: number;
     baseDelayMs?: number;
     maxDelayMs?: number;
     timeoutMs?: number;
 }>;
 type RuntimeFetch = (input: string | URL, init?: RequestInit) => Promise<Response>;
-type ReadFile = (path: string, signal?: AbortSignal) => Promise<Uint8Array>;
+/** Providers must enforce maxBytes during I/O; runtime also checks returned bytes. */
+type ReadFile = (path: string, signal?: AbortSignal, options?: Readonly<{
+    maxBytes: number;
+}>) => Promise<Uint8Array>;
 type HashBytes = (bytes: Uint8Array) => Promise<string>;
 type Sleep = (milliseconds: number, signal?: AbortSignal) => Promise<void>;
 type BlobStorageUrlResolver = (baseUrl: string, reference: string) => string | Promise<string>;
@@ -218,6 +229,7 @@ declare class AdapterRegistry {
     resolve<TCanonicalModel = unknown, TRendererReady = unknown>(input: SniffInput, formatId?: string): Promise<ModelAdapter<TCanonicalModel, TRendererReady>>;
 }
 declare class PackageResourceResolver implements ResourceResolver {
+    private readonly parentSignal?;
     private readonly memoryResources;
     private readonly baseUrl?;
     private readonly sourceKind;
@@ -229,6 +241,7 @@ declare class PackageResourceResolver implements ResourceResolver {
     private readonly blobStorageUrlResolver?;
     constructor(options: Readonly<{
         sourceKind: ModelSourceKind;
+        signal?: AbortSignal;
         baseUrl?: string;
         package?: ModelPackage;
         fetch: RuntimeFetch;
@@ -264,6 +277,127 @@ declare class ModelRuntime {
     private resolveSource;
 }
 
+/** Hard CPU, GPU, and concurrent-load limits for one residency manager. */
+interface ModelResidencyBudget {
+    readonly maxCpuBytes: number;
+    readonly maxGpuBytes: number;
+    readonly maxInFlightLoads: number;
+}
+/** Adapter request for one immutable model LOD or partition. */
+interface ModelLoadRequest {
+    readonly assetRef: ModelAssetRef;
+    readonly lod: ModelLodLevel;
+    readonly partitionId?: string;
+    readonly priority: number;
+    readonly signal: AbortSignal;
+}
+/** Resource returned by a format-specific loader/upload adapter. */
+interface ModelLoadedResource<Resource> {
+    readonly resource: Resource;
+    readonly contentHash: string;
+    readonly cpuBytes: number;
+    readonly gpuBytes: number;
+    readonly dispose: () => void | Promise<void>;
+}
+/** Options for acquiring a shared model resource. */
+interface AcquireModelOptions {
+    readonly assetRef: ModelAssetRef;
+    readonly lod: ModelLodLevel;
+    readonly partitionId?: string;
+    readonly priority: number;
+    readonly estimatedCpuBytes: number;
+    readonly estimatedGpuBytes: number;
+    readonly signal?: AbortSignal;
+    readonly pinned?: boolean;
+}
+/** Idempotent reference to one shared resident model resource. */
+interface ModelResidencyLease<Resource> {
+    readonly key: string;
+    readonly assetRef: ModelAssetRef;
+    readonly lod: ModelLodLevel;
+    readonly partitionId?: string;
+    readonly resource: Resource;
+    release(): void;
+    setPriority(priority: number): void;
+    setPinned(pinned: boolean): void;
+}
+/** Construction boundary for adapter-driven model loading. */
+interface ModelResidencyManagerOptions<Resource> {
+    readonly budget: ModelResidencyBudget;
+    readonly load: (request: ModelLoadRequest) => Promise<ModelLoadedResource<Resource>>;
+    readonly loadTimeoutMs?: number;
+}
+type ModelResidencyErrorCode = "acquire-aborted" | "budget-exceeded" | "content-hash-mismatch" | "invalid-load-result" | "load-timeout" | "manager-closed";
+/** Stable operational error returned by residency-specific failure paths. */
+declare class ModelResidencyError extends Error {
+    readonly code: ModelResidencyErrorCode;
+    constructor(code: ModelResidencyErrorCode, message: string);
+}
+interface ModelResidencyEntrySnapshot {
+    readonly key: string;
+    readonly state: "queued" | "loading" | "resident";
+    readonly priority: number;
+    readonly references: number;
+    readonly pinned: boolean;
+    readonly cpuBytes: number;
+    readonly gpuBytes: number;
+}
+/** Immutable accounting and lifetime metrics for diagnostics. */
+interface ModelResidencySnapshot {
+    readonly maxCpuBytes: number;
+    readonly maxGpuBytes: number;
+    readonly maxInFlightLoads: number;
+    readonly cpuBytes: number;
+    readonly gpuBytes: number;
+    readonly reservedCpuBytes: number;
+    readonly reservedGpuBytes: number;
+    readonly residentCount: number;
+    readonly pendingCount: number;
+    readonly referenceCount: number;
+    readonly pinnedCount: number;
+    readonly inFlightLoads: number;
+    readonly queuedLoads: number;
+    readonly acquireCount: number;
+    readonly cacheHits: number;
+    readonly deduplicatedAcquires: number;
+    readonly loadsStarted: number;
+    readonly loadsCompleted: number;
+    readonly loadsFailed: number;
+    readonly loadsAborted: number;
+    readonly loadsTimedOut: number;
+    readonly evictions: number;
+    readonly disposals: number;
+    readonly disposalFailures: number;
+    readonly residentKeys: readonly string[];
+    readonly entries: readonly ModelResidencyEntrySnapshot[];
+}
+/** Build the canonical content-hash, LOD, and optional partition cache key. */
+declare function createModelResidencyKey(assetRef: ModelAssetRef, lod: ModelLodLevel, partitionId?: string): string;
+/**
+ * Content-addressed model cache with bounded work, reference-counted leases,
+ * deterministic eviction, and exact-once adapter disposal.
+ */
+declare class ModelResidencyManager<Resource = unknown> {
+    #private;
+    constructor(options: ModelResidencyManagerOptions<Resource>);
+    /** Acquire one shared resource lease, loading it at most once per cache key. */
+    acquire(options: AcquireModelOptions): Promise<ModelResidencyLease<Resource>>;
+    /** Dispose every currently unreferenced, unpinned resident cache entry. */
+    evictUnused(): Promise<void>;
+    /** Wait until queued/loading work and its resulting disposal have settled. */
+    waitForIdle(): Promise<void>;
+    /** Abort pending work and dispose every resident or late-completing resource. */
+    shutdown(): Promise<void>;
+    /** Return immutable byte, queue, cache, and lifetime metrics. */
+    snapshot(): ModelResidencySnapshot;
+}
+
+/** Non-retryable acquisition failure; never contains a source URI or provider error. */
+declare class ModelResourceTooLargeError extends Error {
+    readonly code = "MODEL_RESOURCE_TOO_LARGE";
+    constructor();
+}
+
 /** Package identity and rollout metadata for the runtime boundary. */
 declare const packageName: "@plasius/gpu-model-runtime";
 declare const packageBootstrap: Readonly<{
@@ -272,4 +406,4 @@ declare const packageBootstrap: Readonly<{
     readonly status: "runtime";
 }>;
 
-export { type AdapterLoadContext, type AdapterLoadResult, type AdapterModule, type AdapterRegistration, AdapterRegistry, type BlobStorageUrlResolver, type FetchPolicy, type FetchedResource, type HashBytes, type LoadModelOptions, MemoryModelCache, type ModelAdapter, type ModelCache, type ModelLoadResult, type ModelPackage, type ModelProvenance, type ModelResourceInput, ModelRuntime, type ModelSource, type ModelSourceKind, PackageResourceResolver, type ReadFile, type ResolveResourceOptions, type ResolvedModelSource, type ResolvedResource, type ResourceReference, type ResourceResolver, type RuntimeDependencies, type RuntimeFetch, type Sleep, type SniffInput, type WorkerDispatcher, type WorkerLoadRequest, createModelCacheKey, defaultSleep, fetchResource, packageBootstrap, packageName, sha256Hex, verifyIntegrity };
+export { type AcquireModelOptions, type AdapterLoadContext, type AdapterLoadResult, type AdapterModule, type AdapterRegistration, AdapterRegistry, type BlobStorageUrlResolver, DEFAULT_MODEL_MAX_BYTES, type FetchPolicy, type FetchedResource, type HashBytes, type LoadModelOptions, MemoryModelCache, type ModelAdapter, type ModelCache, type ModelLoadRequest, type ModelLoadResult, type ModelLoadedResource, type ModelPackage, type ModelProvenance, type ModelResidencyBudget, type ModelResidencyEntrySnapshot, ModelResidencyError, type ModelResidencyErrorCode, type ModelResidencyLease, ModelResidencyManager, type ModelResidencyManagerOptions, type ModelResidencySnapshot, type ModelResourceInput, ModelResourceTooLargeError, ModelRuntime, type ModelSource, type ModelSourceKind, PackageResourceResolver, type ReadFile, type ResolveResourceOptions, type ResolvedModelSource, type ResolvedResource, type ResourceReference, type ResourceResolver, type RuntimeDependencies, type RuntimeFetch, type Sleep, type SniffInput, type WorkerDispatcher, type WorkerLoadRequest, createModelCacheKey, createModelResidencyKey, defaultSleep, fetchResource, packageBootstrap, packageName, sha256Hex, verifyIntegrity };