@forgeax/engine-render 0.1.4 → 0.1.6

package/dist/debug-draw-glue.d.ts

@@ -1,56 +1,5 @@
-import type { DebugDraw } from '@forgeax/engine-debug-draw';
-import { type Mat4 } from '@forgeax/engine-math';
-import type { RenderGraph, RenderGraphBuilder, RenderGraphError } from '@forgeax/engine-render-graph';
-import type { TextureFormat } from '@forgeax/engine-rhi';
+import type { RenderGraphBuilder, RenderGraphError } from '@forgeax/engine-render-graph';
 import type { Result } from '@forgeax/engine-types';
-import type { RenderPipelineFrame } from './render-pipeline';
-import type { RenderPipelineContext } from './render-pipeline-context';
-import type { RenderPipelineTarget } from './render-pipeline-target';
-import type { Renderer } from './renderer';
-/**
- * Create a DebugDraw instance once `renderer.ready` settles.
- *
- * Waits for the GPU device + shader manifest + builtin asset upload to
- * complete before creating the DebugDraw PSO. Stores the instance in the
- * package-internal registry so graph pass closures can reach it.
- *
- * Bug A fix (feat-20260626 m6-4): the PSO color format MUST equal the swap-chain
- * LDR view the overlay pass draws into (`attachDebugOverlayPass` flushes to
- * `ctx.view`), or the backend rejects the render pass with an attachment-state
- * mismatch every frame. The view format is the SSOT
- * `selectSwapChainFormat(caps.storageBuffer).view` -- `bgra8unorm-srgb` on
- * native WebGPU (follows getPreferredCanvasFormat + the srgb-via-viewFormats
- * route) and `rgba8unorm-srgb` on wgpu-wasm GLES -- the same derivation
- * `PipelineState.colorAttachmentFormat` uses (memory
- * offscreen-rt-format-must-follow-swapchain-not-hardcode-rgba). The hardcoded
- * `'bgra8unorm'` default was latent until the overlay pass actually flushed
- * (before the glue merge the pass was a no-op stub that never validated). A
- * caller may still pass an explicit `format` to target a custom surface.
- */
-export declare function createDebugDrawOnReady(renderer: Renderer, format?: TextureFormat): Promise<DebugDraw>;
-/** Release one app-owned DebugDraw and remove it from render-pass lookup. */
-export declare function releaseDebugDraw(debugDraw: DebugDraw): void;
-/**
- * Attach a DebugOverlay pass to a render graph at the tonemap suffix.
- *
- * The pass is added with empty reads/writes (the swap-chain is not a
- * graph-declared target). The execute closure reads `ctx.view` (the
- * swap-chain TextureView) + `ctx.encoder` (the shared frame command
- * encoder) and calls `dd.flush(encoder, view, viewProj)` using the
- * registered DebugDraw instance.
- *
- * When no DebugDraw is registered (createDebugDrawOnReady not called,
- * or tree-shaken), the pass is a silent no-op.
- *
- * Per plan D-8: URP and HDRP both call this helper with their respective
- * tonemap-suffix graphs, keeping the wiring single-source.
- *
- * @param graph - The per-frame RenderGraph (URP forward-graph or HDRP tonemap-graph).
- * @param getViewProj - Thunk that returns camera.viewProj from the pass context
- *   at execute time (not at graph-build time).
- */
-export declare function attachDebugOverlayPass(graph: RenderGraph<RenderPipelineContext>, getViewProj: (ctx: RenderPipelineContext) => Mat4, options?: {
-    readonly reads?: readonly string[];
-}): void;
+import type { RenderPipelineFrame, RenderPipelineTarget } from './render-pipeline';
 export declare function addTypedDebugOverlayPass(graph: RenderGraphBuilder<RenderPipelineFrame>, output: RenderPipelineTarget): Result<void, RenderGraphError>;
 //# sourceMappingURL=debug-draw-glue.d.ts.map

package/dist/debug-draw-glue.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"debug-draw-glue.d.ts","sourceRoot":"","sources":["../src/debug-draw-glue.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE5D,OAAO,EAAE,KAAK,IAAI,EAAQ,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,qBAAqB,CAAC;AACtE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAU3C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,sBAAsB,CAC1C,QAAQ,EAAE,QAAQ,EAClB,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,SAAS,CAAC,CAkBpB;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAG3D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,WAAW,CAAC,qBAAqB,CAAC,EACzC,WAAW,EAAE,CAAC,GAAG,EAAE,qBAAqB,KAAK,IAAI,EACjD,OAAO,GAAE;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAO,GACnD,IAAI,CAcN;AAED,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,kBAAkB,CAAC,mBAAmB,CAAC,EAC9C,MAAM,EAAE,oBAAoB,GAC3B,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAuChC"}
+{"version":3,"file":"debug-draw-glue.d.ts","sourceRoot":"","sources":["../src/debug-draw-glue.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACzF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAEnF,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,kBAAkB,CAAC,mBAAmB,CAAC,EAC9C,MAAM,EAAE,oBAAoB,GAC3B,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAiChC"}

package/dist/device/device-scope.d.ts

@@ -0,0 +1,83 @@
+import { type Result } from '@forgeax/engine-types';
+import { LifecycleConstructionError } from '../errors/render';
+import type { DeviceResourceKind, DeviceScopeReceipt } from './resource-types';
+export { DEVICE_RESOURCE_KINDS, type DeviceResourceKind, type DeviceScopeReceipt, } from './resource-types';
+export type DeviceScopeState = 'active' | 'retiring' | 'retired' | 'abandoned' | 'disposed';
+export interface ResourceRef<T> {
+    readonly kind: DeviceResourceKind;
+    readonly owner: string;
+    readonly generation: number;
+    readonly value: T;
+    isCurrent(scope: DeviceScope): boolean;
+    isStale(scope: DeviceScope): boolean;
+}
+export declare class DeviceResourceRef<T> implements ResourceRef<T> {
+    readonly kind: DeviceResourceKind;
+    readonly owner: string;
+    readonly generation: number;
+    readonly value: T;
+    constructor(kind: DeviceResourceKind, owner: string, generation: number, value: T);
+    isCurrent(scope: DeviceScope): boolean;
+    isStale(scope: DeviceScope): boolean;
+}
+interface OwnedResource {
+    readonly ref: DeviceResourceRef<unknown>;
+    readonly cleanup: (value: unknown) => void | Promise<void>;
+}
+export declare class DeviceScope {
+    readonly generation: number;
+    readonly owner: string;
+    readonly parent: DeviceScope | undefined;
+    private lifecycleState;
+    private readonly resources;
+    private readonly children;
+    private constructor();
+    static create(generation: number, owner: string): DeviceScope;
+    get state(): DeviceScopeState;
+    get childrenSnapshot(): readonly DeviceScope[];
+    ref<T>(kind: DeviceResourceKind, value: T): ResourceRef<T>;
+    accepts(ref: ResourceRef<unknown>): boolean;
+    isAlive(): boolean;
+    resourceDelta(): number;
+    /** @internal */
+    _adopt<T>(kind: DeviceResourceKind, value: T, cleanup: (value: T) => void | Promise<void>): ResourceRef<T>;
+    /** @internal */
+    _clearResources(): OwnedResource[];
+    retire(): void;
+    abandon(): void;
+    dispose(): void;
+    replace(generation: number, resources: readonly LifecycleResourceSpec<unknown>[]): Promise<LifecycleResult>;
+    /** @internal */
+    _receipt(): DeviceScopeReceipt;
+}
+export interface LifecycleResourceSpec<T> {
+    readonly kind: DeviceResourceKind;
+    readonly create: () => T | Promise<T>;
+    readonly cleanup: (value: T) => void | Promise<void>;
+}
+export interface LifecycleCleanupFailure {
+    readonly resourceKind: DeviceResourceKind;
+    readonly cause: unknown;
+}
+export interface LifecycleFailure {
+    readonly primary: LifecycleConstructionError;
+    readonly cleanupFailures: readonly LifecycleCleanupFailure[];
+    readonly receipt: DeviceScopeReceipt;
+}
+export type LifecycleResult = Result<DeviceScope, LifecycleFailure>;
+export interface LifecycleTransactionOptions {
+    readonly failureAt?: number;
+}
+export declare class LifecycleTransaction {
+    private readonly scope;
+    private readonly resources;
+    private readonly options;
+    private committed;
+    constructor(scope: DeviceScope, options?: LifecycleTransactionOptions);
+    add<T>(spec: LifecycleResourceSpec<T>): this;
+    commit(): Promise<LifecycleResult>;
+    failure(operation: 'create' | 'dispose', resourceKind?: DeviceResourceKind, cleanupFailures?: readonly LifecycleCleanupFailure[], cause?: unknown): LifecycleResult;
+    private cleanupCreated;
+    private cleanupOne;
+}
+//# sourceMappingURL=device-scope.d.ts.map

package/dist/device/device-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-scope.d.ts","sourceRoot":"","sources":["../../src/device/device-scope.ts"],"names":[],"mappings":"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"}

package/dist/{gpu-resource-store.d.ts → device/gpu-residency.d.ts}

@@ -1,14 +1,29 @@
+import { type MipmapShaderModuleFactory } from '@forgeax/engine-assets-runtime';
 import type { World } from '@forgeax/engine-ecs';
-import type { VertexLayoutProjection } from '@forgeax/engine-geometry';
-import { type Result, type RhiCaps, RhiError, type Sampler, type TextureView } from '@forgeax/engine-rhi';
+import { type VertexLayoutProjection } from '@forgeax/engine-geometry';
+import { type Buffer, type Result, type RhiCaps, type RhiDevice, RhiError, type RhiQueue, type Sampler, type TextureFormat, type TextureView } from '@forgeax/engine-rhi';
 import { type AssetError, type DecodedImage, type EquirectAsset, type Handle, type ImageError, type PrimitiveTopology, type SamplerAsset, type Submesh, type TextureAsset, type MeshAsset as TypesMeshAsset } from '@forgeax/engine-types';
-import { GpuBuffer, GpuTexture } from './gpu-resource';
-import type { RhiErrorListenerRegistry } from './lifecycle';
-import { type MeshUpdateError as MeshUpdateErrorType } from './mesh-update-errors';
-import { type MipmapBlitDevice, type MipmapShaderModuleFactory } from './mipmap-generator';
+import { GpuBuffer, GpuTexture } from '../gpu-resource';
+import { type IblShaderModuleFactory } from '../ibl/IblPipelineCache';
+import type { RhiErrorListenerRegistry } from '../lifecycle';
+import type { DeviceScope } from './device-scope';
+export type FaceUniformsDevice = Pick<RhiDevice, 'createBuffer'> & {
+    readonly queue: Pick<RhiQueue, 'writeBuffer'>;
+};
+export declare function createFaceUniformsBuffer(device: FaceUniformsDevice): Result<Buffer, RhiError>;
+export declare function createPrefilterUniformsBuffer(device: FaceUniformsDevice): Result<Buffer, RhiError>;
+export declare function writeFaceUniforms(device: FaceUniformsDevice, buffer: Buffer, faceIdx: number, viewProj: Float32Array): Result<void, RhiError>;
+export declare function writeAllFaceUniforms(device: FaceUniformsDevice, buffer: Buffer): Result<void, RhiError>;
+export declare function writePrefilterUniforms(device: FaceUniformsDevice, buffer: Buffer, subPassIdx: number, roughness: number, mipFaceSize: number): Result<void, RhiError>;
+export declare function writeAllPrefilterUniforms(device: FaceUniformsDevice, buffer: Buffer): Result<void, RhiError>;
 /** Cube-POD register-relay injected by the wire layer (D-3). */
 type RegisterCube = (world: World, pod: EquirectAsset) => Result<Handle<'EquirectAsset', 'shared'>, AssetError>;
-interface MeshGpuEntry {
+interface TextureGpuEntry {
+    readonly texture: GpuTexture;
+    /** Opaque RHI view handle; lifetime is bound to the parent texture. */
+    readonly view: TextureView;
+}
+export interface MeshGpuHandles {
     readonly vertexBuffer: GpuBuffer;
     /**
      * Index buffer wrapper, or `null` for a vertex-only mesh
@@ -26,15 +41,31 @@ interface MeshGpuEntry {
     readonly vboBytes: number;
     /** Allocation byte size for the ibo, or 0 when indexBuffer is null. */
     readonly iboBytes: number;
-    /** Immutable geometry-owned layout projection used for all resident stride checks. */
-    readonly layoutProjection: VertexLayoutProjection;
     readonly indexCount: number;
     readonly indexFormat: 'uint16' | 'uint32';
-    /** Vertex count is derived from the geometry-owned projection stride. */
+    /**
+     * Vertex stride discriminator (feat-20260611). `'12F'` = 48 B
+     * (position+normal+uv+tangent); `'18F'` = 72 B (12F + skinIndex(uint16x4) +
+     * skinWeight(float32x4)). Mirrors `MeshRenderData.layout` in render-data.ts
+     * and `MeshRenderData.layout` -- the residency and render-data layout
+     * fields are the same union and move together.
+     */
+    readonly layout: '12F' | '18F';
+    /** Geometry-owned vertex layout projection used by every GPU consumer. */
+    readonly layoutProjection: VertexLayoutProjection;
+    /**
+     * Number of UV sets the interleaved buffer carries (1 = single `uv`, +1 per
+     * `uv1..uv7`). feat-20260629-multi-uv-set-support: threaded to the record
+     * stage so the forward PSO's vertex layout stride matches the buffer for
+     * meshes with a real extra UV set. Mirrors MeshRenderData.uvSetCount /
+     * MeshRenderData.uvSetCount.
+     */
+    readonly uvSetCount: number;
+    /** Vertex count uses 18F for skin or the geometry-owned canonical base stride. */
     readonly vertexCount: number;
     /** True when `MeshAsset.indices` is present (indexed draw path). */
     readonly indexed: boolean;
-    /** Primitive topology (default 'triangle-list'). Mirrors MeshGpuHandles. */
+    /** Primitive topology (default 'triangle-list'). */
     readonly topology: PrimitiveTopology;
     /**
      * Submeshes from MeshAsset.submeshes, carried through to the record stage
@@ -46,14 +77,19 @@ interface MeshGpuEntry {
 /**
  * GPU residency store. Owns the per-handle GPU caches and the upload
  * primitives that build them. Constructed once per renderer; wired with the
- * GPU device via `configureGpuDevice` after `Renderer.ready` resolves.
+ * GPU device via `configureGpuDevice` after `Renderer.initialization` resolves.
  */
-export declare class GpuResourceStore {
+export declare class GpuResidencyCache {
     /** Monotonic token for mesh GPU residency or contents changes. */
     meshResidencyEpoch: number;
     /** Monotonic token for texture/sampler identities used by material bind groups. */
     materialResourceEpoch: number;
     private gpuDevice;
+    /** RHI-only owner for IBL projection; never populated with a raw GPUDevice. */
+    private iblDevice;
+    /** RHI Result-returning shader factory paired with `iblDevice`. */
+    private iblShaderModuleFactory;
+    private deviceScope;
     private asyncCreateShaderModule;
     private registerCube;
     private errorRegistry;
@@ -64,19 +100,31 @@ export declare class GpuResourceStore {
     private readonly cubemapIdempotentMap;
     private readonly meshGpuHandles;
     /**
-     * feat-20260723-cross-world-gpu-cache-collision: compose a cache key from
-     * the raw handle slot and the worldId so two worlds that independently
-     * allocate assets at the same slot number never collide in the GPU store.
-     * worldId=0 produces the bare slot (backward compat with single-world path).
+     * Compose a cache key from the raw handle slot and its owning World. The
+     * draw-time world index is only a position in one frame's `worlds[]`; it is
+     * not an asset identity and can be reused by a later World. World objects
+     * therefore receive a renderer-local namespace, while numeric callers keep
+     * the legacy namespace for low-level tests and built-in upload paths.
      */
+    private readonly worldNamespaces;
+    private nextWorldNamespace;
     private worldKey;
     /**
      * Wire the GPU device, shader-module factory, and cube-POD register relay.
-     * Called once by createRenderer after `Renderer.ready` resolves. This
-     * performs NO replay of CPU asset state:
+     * Called once by createRenderer after `Renderer.initialization` resolves. Unlike the
+     * pre-extraction AssetRegistry.configureGpuDevice, this performs NO replay:
      * the pull model builds resources lazily at first `ensureResident` access.
      */
-    configureGpuDevice(device: MipmapBlitDevice, asyncCreateShaderModule: MipmapShaderModuleFactory | undefined, registerCube: RegisterCube, caps: RhiCaps): void;
+    configureGpuDevice(device: RhiDevice, asyncCreateShaderModule: MipmapShaderModuleFactory | undefined, registerCube: RegisterCube, caps: RhiCaps): void;
+    /**
+     * Bind the IBL projection to the same opaque RhiDevice used by assembly.
+     * This is deliberately separate from the legacy-compatible mipmap fixture
+     * seam: unit fixtures that only exercise ordinary residency do not need an
+     * IBL device, while a real IBL projection never accepts a raw GPUDevice.
+     */
+    configureIblDevice(device: RhiDevice, shaderModuleFactory: IblShaderModuleFactory | undefined): void;
+    /** Bind residency ownership to the renderer's single DeviceScope tree. */
+    bindDeviceScope(scope: DeviceScope): void;
     /**
      * Wrap a raw RHI Buffer handle into a GpuBuffer. The wrapper holds a
      * reference to the device so `.destroy()` forwards to
@@ -88,7 +136,6 @@ export declare class GpuResourceStore {
      * surfaces as a non-null assertion rather than a structured error.
      */
     private wrapBuf;
-    private destroyMeshBuffer;
     /** Wrap a raw RHI Texture handle into a GpuTexture (mirror of wrapBuf). */
     private wrapTex;
     /**
@@ -122,11 +169,11 @@ export declare class GpuResourceStore {
      * can consume the aggregate result (D-3). Key not present -> no-op
      * returning {freed:0, errors:[]}.
      */
-    evictTexture(handle: Handle<'TextureAsset', 'shared'>, worldId?: number): {
+    evictTexture(handle: Handle<'TextureAsset', 'shared'>, worldId?: World | number): {
         freed: number;
         errors: RhiError[];
     };
-    evictMesh(handle: Handle<'MeshAsset', 'shared'>, worldId?: number): {
+    evictMesh(handle: Handle<'MeshAsset', 'shared'>, worldId?: World | number): {
         freed: number;
         errors: RhiError[];
     };
@@ -149,14 +196,14 @@ export declare class GpuResourceStore {
     };
     /**
      * Prewarm the mipmap pipeline cache for the given texture formats (D-9).
-     * Called from `createRenderer.ready` (already async): builds the one-time
+     * Called from `createRenderer.initialization` (already async): builds the one-time
      * mipmap shader module + per-format render pipeline into the mipmap-generator
      * deviceCache so the per-texture mipmap blit at record-stage `ensureResident`
      * is pure synchronous encoder work. A format absent from this list will make
      * the sync `ensureResident` texture arm return a structured RhiError rather
      * than lazily await a build (which would break the sync draw contract).
      */
-    prewarmMipmapPipeline(device: MipmapBlitDevice, formats: readonly GPUTextureFormat[]): Promise<Result<void, RhiError>>;
+    prewarmMipmapPipeline(device: RhiDevice, formats: readonly TextureFormat[]): Promise<Result<void, RhiError>>;
     /**
      * Return the GpuTexture wrapper for a `Handle<TextureAsset>` if it has been
      * made resident, else `undefined`.
@@ -164,18 +211,18 @@ export declare class GpuResourceStore {
      * @internal — test-only seam for cow-survivor / AC-02 integration tests; not
      * part of the engine's public API surface.
      */
-    _getTextureGpuTexture(handle: Handle<'TextureAsset', 'shared'>, worldId?: number): GpuTexture | undefined;
+    _getTextureGpuTexture(handle: Handle<'TextureAsset', 'shared'>, worldId?: World | number): GpuTexture | undefined;
     /**
      * Return the GPU texture-view for a `Handle<TextureAsset>` if it has been
      * made resident, else `undefined`.
      */
-    getTextureGpuView(handle: Handle<'TextureAsset', 'shared'>, worldId?: number): TextureView | undefined;
+    getTextureGpuView(handle: Handle<'TextureAsset', 'shared'>, worldId?: World | number): TextureView | undefined;
     /**
      * Lazily materialise and cache a sampler descriptor for a material texture.
      * Samplers are opaque, non-destroyable RHI handles, so disposal only drops
      * this store's cache and lets the device own their lifetime.
      */
-    ensureSamplerResident(handle: Handle<'SamplerAsset', 'shared'>, pod: SamplerAsset, worldId?: number): Result<Sampler, RhiError>;
+    ensureSamplerResident(handle: Handle<'SamplerAsset', 'shared'>, pod: SamplerAsset, worldId?: World | number): Result<Sampler, RhiError>;
     /**
      * Return the GpuTexture wrapper for the cubemap, or `undefined` if not
      * uploaded yet. Consumers that need the raw RHI Texture handle (e.g.
@@ -184,9 +231,9 @@ export declare class GpuResourceStore {
      */
     getCubemapGpuTexture(handle: Handle<'EquirectAsset', 'shared'>): GpuTexture | undefined;
     /** Return the full-cube texture view, or `undefined` if not uploaded yet. */
-    getCubemapGpuView(handle: Handle<'EquirectAsset', 'shared'>): any | undefined;
+    getCubemapGpuView(handle: Handle<'EquirectAsset', 'shared'>): TextureView | undefined;
     /** Return per-face 2D views (6 faces), or `undefined` if not uploaded yet. */
-    getCubemapFaceViews(handle: Handle<'EquirectAsset', 'shared'>): readonly any[] | undefined;
+    getCubemapFaceViews(handle: Handle<'EquirectAsset', 'shared'>): readonly TextureView[] | undefined;
     /**
      * Query the projection status for an equirect source handle (D-3 SSOT: the
      * store's CubemapGpuEntry is the single authority). Returns `undefined` when
@@ -203,7 +250,13 @@ export declare class GpuResourceStore {
      * `Handle<MeshAsset>` if resident, else `undefined`. Consumers treat this
      * as the canonical "mesh asset has GPU residency" probe.
      */
-    getMeshGpuHandles(handle: Handle<'MeshAsset', 'shared'>, worldId?: number): MeshGpuEntry | undefined;
+    getMeshGpuHandles(handle: Handle<'MeshAsset', 'shared'>, worldId?: World | number): MeshGpuHandles | undefined;
+    /**
+     * Drop one mutable shared mesh's GPU copy after ECS publishes `markChanged`.
+     * The next record pass resolves the same POD and rebuilds residency through
+     * the normal pull path, so ECS remains the payload authority.
+     */
+    invalidateMesh(handle: number, worldId?: World | number): void;
     /**
      * Pull-model residency: build the GPU resource for `handle` from the
      * caller-provided POD on a miss, return the cached handles on a hit (D-2).
@@ -218,7 +271,8 @@ export declare class GpuResourceStore {
      * (`_uploadCubemapFromEquirect`). Builtin meshes are NOT routed here either
      * (createRenderer step-3 owns them; D-1).
      */
-    ensureResident(handle: Handle<'MeshAsset', 'shared'> | Handle<'TextureAsset', 'shared'>, pod: TypesMeshAsset | TextureAsset, worldId?: number): Result<any, RhiError | AssetError | ImageError>;
+    ensureResident(handle: Handle<'MeshAsset', 'shared'>, pod: TypesMeshAsset, worldId?: World | number): Result<MeshGpuHandles, RhiError | AssetError | ImageError>;
+    ensureResident(handle: Handle<'TextureAsset', 'shared'>, pod: TextureAsset, worldId?: World | number): Result<TextureGpuEntry, RhiError | AssetError | ImageError>;
     /**
      * Eager public surface: upload decoded image bytes into a GPU texture and
      * cache (texture + view) under the handle. The TextureAsset POD supplies the
@@ -227,7 +281,7 @@ export declare class GpuResourceStore {
      * signature so callers that have not prewarmed can drive a mipmap build here
      * (the one async source).
      */
-    uploadTexture(handle: Handle<'TextureAsset', 'shared'>, pod: TextureAsset, decoded: DecodedImage, worldId?: number): Promise<Result<void, AssetError | ImageError | RhiError>>;
+    uploadTexture(handle: Handle<'TextureAsset', 'shared'>, pod: TextureAsset, decoded: DecodedImage, worldId?: World | number): Promise<Result<void, AssetError | ImageError | RhiError>>;
     /**
      * Synchronous texture upload used by `ensureResident` (D-9). Identical to
      * `uploadTexture` except the mipmap pipeline is read from the prewarmed
@@ -269,26 +323,15 @@ export declare class GpuResourceStore {
      */
     private uploadMeshById;
     /**
-     * Update an existing resident mesh without changing its shape or metadata.
-     * A shape change must use a new asset handle; this method never reallocates
-     * or silently changes the draw contract.
+     * Update an existing mesh's GPU buffer data in-place (or expand). The handle
+     * must already be resident. Mirrors the pre-extraction `updateMeshById`.
      */
     private updateMeshById;
-    /**
-     * Internal explicit rebuild path used when an owner has deliberately
-     * replaced a mesh shape. Public callers should register a new MeshAsset
-     * handle so CPU recovery data and GPU residency remain one authority.
-     */
-    private replaceMeshById;
     /**
      * Public surface for updating an existing unmanaged mesh handle's GPU buffer
      * data in-place. The handle must have been made resident.
      */
-    updateMesh(handle: Handle<'MeshAsset', 'shared'>, newVertices: Float32Array, newIndices: Uint16Array | Uint32Array | undefined, worldId?: number, submeshes?: readonly Submesh[]): Result<void, MeshUpdateErrorType | RhiError>;
-    /** Explicit internal rebuild path; public callers should use a new asset handle. */
-    replaceMesh(handle: Handle<'MeshAsset', 'shared'>, newVertices: Float32Array, newIndices: Uint16Array | Uint32Array | undefined, worldId?: number, submeshes?: readonly Submesh[]): Result<void, MeshUpdateErrorType | RhiError>;
-    /** Upload a contiguous vertex range using the resident mesh stride. */
-    updateMeshVertexRange(handle: Handle<'MeshAsset', 'shared'>, vertices: Float32Array, firstVertex: number, vertexCount: number, worldId?: number): Result<void, MeshUpdateErrorType | RhiError>;
+    updateMesh(handle: Handle<'MeshAsset', 'shared'>, newVertices: Float32Array, newIndices: Uint16Array, worldId?: World | number, submeshes?: readonly Submesh[]): void;
 }
 export {};
-//# sourceMappingURL=gpu-resource-store.d.ts.map
+//# sourceMappingURL=gpu-residency.d.ts.map

package/dist/device/gpu-residency.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu-residency.d.ts","sourceRoot":"","sources":["../../src/device/gpu-residency.ts"],"names":[],"mappings":"AA+BA,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,0BAA0B,CAAC;AAElC,OAAO,EACL,KAAK,MAAM,EAIX,KAAK,MAAM,EACX,KAAK,OAAO,EACZ,KAAK,SAAS,EACd,QAAQ,EACR,KAAK,QAAQ,EACb,KAAK,OAAO,EAEZ,KAAK,aAAa,EAClB,KAAK,WAAW,EACjB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,KAAK,UAAU,EAEf,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,MAAM,EAGX,KAAK,UAAU,EAIf,KAAK,iBAAiB,EACtB,KAAK,YAAY,EACjB,KAAK,OAAO,EACZ,KAAK,YAAY,EACjB,KAAK,SAAS,IAAI,cAAc,EAEjC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAWxD,OAAO,EAIL,KAAK,sBAAsB,EAI5B,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAU7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAMlD,MAAM,MAAM,kBAAkB,GAAG,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,GAAG;IACjE,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;CAC/C,CAAC;AAMF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAQ7F;AAED,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,kBAAkB,GACzB,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,CAQ1B;AAED,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,YAAY,GACrB,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAcxB;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,MAAM,GACb,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAQxB;AAED,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAClB,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CASxB;AAED,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,MAAM,GACb,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAgBxB;AA0DD,gEAAgE;AAChE,KAAK,YAAY,GAAG,CAClB,KAAK,EAAE,KAAK,EACZ,GAAG,EAAE,aAAa,KACf,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,QAAQ,CAAC,EAAE,UAAU,CAAC,CAAC;AAQ3D,UAAU,eAAe;IACvB,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;CAC5B;AAuBD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,YAAY,EAAE,SAAS,CAAC;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,GAAG,IAAI,CAAC;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC1C;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,KAAK,GAAG,KAAK,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,gBAAgB,EAAE,sBAAsB,CAAC;IAClD;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,oDAAoD;IACpD,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,OAAO,uBAAuB,EAAE,OAAO,EAAE,CAAC;CACxE;AAED;;;;GAIG;AACH,qBAAa,iBAAiB;IAC5B,kEAAkE;IAClE,kBAAkB,SAAK;IACvB,mFAAmF;IACnF,qBAAqB,SAAK;IAC1B,OAAO,CAAC,SAAS,CAAoC;IACrD,+EAA+E;IAC/E,OAAO,CAAC,SAAS,CAAoC;IACrD,mEAAmE;IACnE,OAAO,CAAC,sBAAsB,CAAiD;IAC/E,OAAO,CAAC,WAAW,CAA0B;IAG7C,OAAO,CAAC,uBAAuB,CAAoD;IAGnF,OAAO,CAAC,YAAY,CAAuC;IAG3D,OAAO,CAAC,aAAa,CAAmD;IAGxE,OAAO,CAAC,IAAI,CAAkC;IAE9C,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAoD;IACtF,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4C;IAC9E,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA2C;IAG7E,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAA6D;IAClG,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAmD;IAElF;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAgC;IAChE,OAAO,CAAC,kBAAkB,CAAK;IAE/B,OAAO,CAAC,QAAQ;IAahB;;;;;OAKG;IACH,kBAAkB,CAChB,MAAM,EAAE,SAAS,EACjB,uBAAuB,EAAE,yBAAyB,GAAG,SAAS,EAC9D,YAAY,EAAE,YAAY,EAC1B,IAAI,EAAE,OAAO,GACZ,IAAI;IAQP;;;;;OAKG;IACH,kBAAkB,CAChB,MAAM,EAAE,SAAS,EACjB,mBAAmB,EAAE,sBAAsB,GAAG,SAAS,GACtD,IAAI;IAKP,0EAA0E;IAC1E,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI;IAIzC;;;;;;;;;OASG;IACH,OAAO,CAAC,OAAO;IAYf,2EAA2E;IAC3E,OAAO,CAAC,OAAO;IAYf;;;;;;;;;;;;;;;OAeG;IACH,UAAU,IAAI,IAAI;IAqClB;;;;OAIG;IACH,gBAAgB,CAAC,QAAQ,EAAE,wBAAwB,GAAG,IAAI;IAI1D;;;;;;;OAOG;IACH,YAAY,CACV,MAAM,EAAE,MAAM,CAAC,cAAc,EAAE,QAAQ,CAAC,EACxC,OAAO,GAAE,KAAK,GAAG,MAAU,GAC1B;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,QAAQ,EAAE,CAAA;KAAE;IAuBxC,SAAS,CACP,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,EACrC,OAAO,GAAE,KAAK,GAAG,MAAU,GAC1B;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,QAAQ,EAAE,CAAA;KAAE;IA4BxC,YAAY,CAAC,EAAE,EAAE,MAAM,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,QAAQ,EAAE,CAAA;KAAE;IAyB/D;;;;;;;;OAQG;IACH,mBAAmB,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,QAAQ,EAAE,CAAA;KAAE;IA2FhF;;;;;;;;OAQG;IACG,qBAAqB,CACzB,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,SAAS,aAAa,EAAE,GAChC,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IA0BlC;;;;;;OAMG;IACH,qBAAqB,CACnB,MAAM,EAAE,MAAM,CAAC,cAAc,EAAE,QAAQ,CAAC,EACxC,OAAO,GAAE,KAAK,GAAG,MAAU,GAC1B,UAAU,GAAG,SAAS;IAIzB;;;OAGG;IACH,iBAAiB,CACf,MAAM,EAAE,MAAM,CAAC,cAAc,EAAE,QAAQ,CAAC,EACxC,OAAO,GAAE,KAAK,GAAG,MAAU,GAC1B,WAAW,GAAG,SAAS;IAI1B;;;;OAIG;IACH,qBAAqB,CACnB,MAAM,EAAE,MAAM,CAAC,cAAc,EAAE,QAAQ,CAAC,EACxC,GAAG,EAAE,YAAY,EACjB,OAAO,GAAE,KAAK,GAAG,MAAU,GAC1B,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC;IAsB5B;;;;;OAKG;IACH,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,eAAe,EAAE,QAAQ,CAAC,GAAG,UAAU,GAAG,SAAS;IAKvF,6EAA6E;IAC7E,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,eAAe,EAAE,QAAQ,CAAC,GAAG,WAAW,GAAG,SAAS;IAIrF,8EAA8E;IAC9E,mBAAmB,CACjB,MAAM,EAAE,MAAM,CAAC,eAAe,EAAE,QAAQ,CAAC,GACxC,SAAS,WAAW,EAAE,GAAG,SAAS;IAIrC;;;;;;;;;OASG;IACH,gBAAgB,CACd,MAAM,EAAE,MAAM,CAAC,eAAe,EAAE,QAAQ,CAAC,GACxC,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS;IAI7C;;;;OAIG;IACH,iBAAiB,CACf,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,EACrC,OAAO,GAAE,KAAK,GAAG,MAAU,GAC1B,cAAc,GAAG,SAAS;IAI7B;;;;OAIG;IACH,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,KAAK,GAAG,MAAU,GAAG,IAAI;IAcjE;;;;;;;;;;;;;OAaG;IACH,cAAc,CACZ,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,EACrC,GAAG,EAAE,cAAc,EACnB,OAAO,CAAC,EAAE,KAAK,GAAG,MAAM,GACvB,MAAM,CAAC,cAAc,EAAE,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;IAC7D,cAAc,CACZ,MAAM,EAAE,MAAM,CAAC,cAAc,EAAE,QAAQ,CAAC,EACxC,GAAG,EAAE,YAAY,EACjB,OAAO,CAAC,EAAE,KAAK,GAAG,MAAM,GACvB,MAAM,CAAC,eAAe,EAAE,QAAQ,GAAG,UAAU,GAAG,UAAU,CAAC;IAyC9D;;;;;;;OAOG;IACG,aAAa,CACjB,MAAM,EAAE,MAAM,CAAC,cAAc,EAAE,QAAQ,CAAC,EACxC,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,YAAY,EACrB,OAAO,GAAE,KAAK,GAAG,MAAU,GAC1B,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,GAAG,QAAQ,CAAC,CAAC;IA+D5D;;;;;OAKG;IACH,OAAO,CAAC,iBAAiB;IAmDzB;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IA8G5B;;;;;;;;;;;;;;;;;;;OAmBG;IACG,0BAA0B,CAC9B,KAAK,EAAE,KAAK,EACZ,YAAY,EAAE,MAAM,CAAC,eAAe,EAAE,QAAQ,CAAC,EAC/C,SAAS,EAAE,aAAa,GACvB,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,eAAe,EAAE,QAAQ,CAAC,EAAE,UAAU,GAAG,QAAQ,CAAC,CAAC;IA8U5E;;;;OAIG;IACH,OAAO,CAAC,cAAc;IAyFtB;;;OAGG;IACH,OAAO,CAAC,cAAc;IA2GtB;;;OAGG;IACH,UAAU,CACR,MAAM,EAAE,MAAM,CAAC,WAAW,EAAE,QAAQ,CAAC,EACrC,WAAW,EAAE,YAAY,EACzB,UAAU,EAAE,WAAW,EACvB,OAAO,GAAE,KAAK,GAAG,MAAU,EAC3B,SAAS,CAAC,EAAE,SAAS,OAAO,EAAE,GAC7B,IAAI;CAIR"}

package/dist/device/resource-types.d.ts

@@ -0,0 +1,8 @@
+export declare const DEVICE_RESOURCE_KINDS: readonly ["listener", "surface", "shader", "pipeline", "buffer", "texture", "binding", "scene-table", "feature", "post-effect"];
+export type DeviceResourceKind = (typeof DEVICE_RESOURCE_KINDS)[number];
+export interface DeviceScopeReceipt {
+    readonly owner: string;
+    readonly generation: number;
+    readonly resourceCount: number;
+}
+//# sourceMappingURL=resource-types.d.ts.map

package/dist/device/resource-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-types.d.ts","sourceRoot":"","sources":["../../src/device/resource-types.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,iIAWxB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC"}

package/dist/engine-metrics.d.ts

@@ -5,8 +5,8 @@ export type { EngineMetrics };
  * the three-method surface bolted on. The map is private; readers consume
  * the snapshot accessor.
  *
- * @internal — instances are constructed by `createRenderer` and surfaced
- * through `Renderer.metrics`; AI users do not import this class directly.
+ * @internal — instances are constructed by `createRenderer` and retained by
+ * owner services; AI users do not import this class directly.
  */
 export declare class EngineMetricsImpl implements EngineMetrics {
     private readonly counters;

package/dist/engine-metrics.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine-metrics.d.ts","sourceRoot":"","sources":["../src/engine-metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAmD3D,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B;;;;;;;GAOG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IAEtD,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI7B,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAQ5C,KAAK,IAAI,IAAI;CAGd;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CAEnD"}
+{"version":3,"file":"engine-metrics.d.ts","sourceRoot":"","sources":["../src/engine-metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AA4C3D,YAAY,EAAE,aAAa,EAAE,CAAC;AAE9B;;;;;;;GAOG;AACH,qBAAa,iBAAkB,YAAW,aAAa;IACrD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IAEtD,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI7B,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAQ5C,KAAK,IAAI,IAAI;CAGd;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CAEnD"}

package/dist/errors/recover.d.ts

@@ -1,3 +1,4 @@
+import type { DeviceScopeReceipt } from '../device/resource-types';
 /**
  * Closed union of recover() error codes.
  *
@@ -7,7 +8,7 @@
  *     (also returned after a successful recover: the renderer is alive again,
  *     so a second recover() is a no-op signal — A-AC-08 idempotency)
  *   - `'recover-not-implemented'` — **reserved**. The S3 skeleton returned this
- *     for any degraded state; M3 implements recover() so this code is no longer
+ *     for each degraded state; M3 implements recover() so this code is no longer
  *     produced. Kept in the union (not deleted) so consumers' exhaustive
  *     switches stay valid — AGENTS.md Change stance: `*ErrorCode` unions evolve
  *     add-only minor, never remove a member
@@ -61,6 +62,32 @@ export declare class RecoverError extends Error {
     readonly hint: string;
     constructor(code: RecoverErrorCode);
 }
+declare const RENDER_RECOVERY_ERROR_POLICY: {
+    readonly 'recover-lifecycle-failed': {
+        readonly expected: "the replacement DeviceScope must publish only after lifecycle cleanup succeeds";
+        readonly hint: "inspect detail and cleanupFailures, then recover or rebuild the DeviceScope";
+    };
+    readonly 'recover-disposed-during-rebuild': {
+        readonly expected: "dispose wins over an in-flight recovery rebuild";
+        readonly hint: "stop using the disposed renderer and create a new Renderer";
+    };
+};
+export type RenderRecoveryErrorCode = keyof typeof RENDER_RECOVERY_ERROR_POLICY;
+export interface RenderRecoveryFailureDetail {
+    readonly owner: string;
+    readonly generation: number;
+    readonly recovery: 'recover' | 'rebuild' | 'stop';
+    readonly receipt: DeviceScopeReceipt;
+    readonly cause: unknown;
+}
+export declare class RenderRecoveryError extends Error {
+    readonly code: RenderRecoveryErrorCode;
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: RenderRecoveryFailureDetail;
+    constructor(code: RenderRecoveryErrorCode, detail: RenderRecoveryFailureDetail);
+}
+export type RecoverFailure = RecoverError | RenderRecoveryError;
 export type IblCapabilityLossCode = 'ibl-hdr-capability-loss';
 export interface IblCapabilityLossDetail {
     readonly fallbackArtifact: 'white-cube';

package/dist/errors/recover.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"recover.d.ts","sourceRoot":"","sources":["../../src/errors/recover.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,oBAAoB,CAAC;AAEjE,QAAA,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;CA+BzB,CAAC;AAEF;;;;;;;;;GASG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,gBAAgB;CAQnC;AAED,MAAM,MAAM,qBAAqB,GAAG,yBAAyB,CAAC;AAE9D,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,gBAAgB,EAAE,YAAY,CAAC;IACxC,QAAQ,CAAC,qBAAqB,EAAE,KAAK,CAAC;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAA6B;IACjE,QAAQ,CAAC,QAAQ,oEAAoE;IACrF,QAAQ,CAAC,IAAI,6EAA6E;IAC1F,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;gBAE7B,aAAa,EAAE,MAAM;CASlC"}
+{"version":3,"file":"recover.d.ts","sourceRoot":"","sources":["../../src/errors/recover.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAInE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,oBAAoB,CAAC;AAEjE,QAAA,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;CA+BzB,CAAC;AAEF;;;;;;;;;GASG;AACH,qBAAa,YAAa,SAAQ,KAAK;IACrC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,gBAAgB;CAQnC;AAED,QAAA,MAAM,4BAA4B;;;;;;;;;CASxB,CAAC;AAEX,MAAM,MAAM,uBAAuB,GAAG,MAAM,OAAO,4BAA4B,CAAC;AAEhF,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAClD,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,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,2BAA2B,CAAC;gBAEjC,IAAI,EAAE,uBAAuB,EAAE,MAAM,EAAE,2BAA2B;CAS/E;AAED,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,mBAAmB,CAAC;AAEhE,MAAM,MAAM,qBAAqB,GAAG,yBAAyB,CAAC;AAE9D,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,gBAAgB,EAAE,YAAY,CAAC;IACxC,QAAQ,CAAC,qBAAqB,EAAE,KAAK,CAAC;IACtC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAA6B;IACjE,QAAQ,CAAC,QAAQ,oEAAoE;IACrF,QAAQ,CAAC,IAAI,6EAA6E;IAC1F,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;gBAE7B,aAAa,EAAE,MAAM;CASlC"}