@forgeax/engine-render 0.1.4 → 0.1.6

package/src/device/resource-types.ts

@@ -0,0 +1,20 @@
+export const DEVICE_RESOURCE_KINDS = [
+  'listener',
+  'surface',
+  'shader',
+  'pipeline',
+  'buffer',
+  'texture',
+  'binding',
+  'scene-table',
+  'feature',
+  'post-effect',
+] as const;
+
+export type DeviceResourceKind = (typeof DEVICE_RESOURCE_KINDS)[number];
+
+export interface DeviceScopeReceipt {
+  readonly owner: string;
+  readonly generation: number;
+  readonly resourceCount: number;
+}

package/src/engine-metrics.ts

@@ -1,11 +1,10 @@
 import type { EngineMetrics } from '@forgeax/engine-types';
 
-// @forgeax/engine-runtime — EngineMetrics public API (feat-20260527-sprite-nineslice
-// M4 / w16). A per-Renderer counter Map exposed through `renderer.metrics` so AI
-// users observe runtime-time soft signals (e.g. nineslice scale too small,
-// nineslice tile mode without sampler repeat) without parsing console.warn text
-// or reaching into engine internals (charter F1 minimum surface, P3 machine-
-// readable signals over text logs).
+// @forgeax/engine-runtime — owner-scoped EngineMetrics implementation
+// (feat-20260527-sprite-nineslice M4 / w16). The counter map is injected into
+// owning services such as AssetRegistry and the record stage; the Renderer
+// facade does not expose it. AI-facing renderer observation stays on inspect()
+// and observe().
 //
 // Surface — three methods:
 //
@@ -28,21 +27,15 @@ import type { EngineMetrics } from '@forgeax/engine-types';
 //     calls the fold operator emits this frame; one increment per non-
 //     singleton head bucket retained after the M2 / w11 cap-fallback
 //     filter. NOT entity count, NOT pre-filter bucket count. AI users
-//     read it via `renderer.metrics.snapshot()['render.instancing.foldedDraws']`
+//     read it via `ownerMetrics.snapshot()['render.instancing.foldedDraws']`
 //     to verify fold actually reduced draw count under mode-0 (LAYER_Z)
 //     transparent sort. The key is exported as `FOLDED_DRAWS_METRIC_KEY`
-//     from `render-system-fold.ts` (single source of truth — engine
+//     from the record mesh owner (single source of truth — engine
 //     calls increment via the helper, never the literal string).
-//   - `shadow.csm.*`                         — debug-only semantic census for
-//     directional shadow token construction and atlas cache hit/miss reasons.
-//     These counters are emitted only when RHI semantic observation is enabled;
-//     they are not a production performance or rendering contract.
 //
-// Multi-Renderer isolation (D-5 candidate 1): each Renderer instance owns its
-// own EngineMetrics; counters from one renderer never bleed into another.
-// `createRenderer.ts` constructs a fresh instance per call; tests that spin
-// up multiple renderers can read each `renderer.metrics.snapshot()` in
-// isolation.
+// Assembly isolation (D-5 candidate 1): each renderer assembly injects a fresh
+// EngineMetrics instance; counters from one host never bleed into another.
+// `createRenderer.ts` constructs a fresh instance per call.
 
 // The EngineMetrics interface (3-method contract, zero type dependencies) sank
 // into @forgeax/engine-types (feat-20260705-runtime-tier2-decomposition M1 / w2,
@@ -56,8 +49,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 class EngineMetricsImpl implements EngineMetrics {
   private readonly counters = new Map<string, number>();

package/src/errors/recover.ts

@@ -3,8 +3,10 @@
 // feat-20260704-runtime-tier1-decomposition M2 / w8 (D-3): the recover()
 // failure cluster. RecoverErrorCode (closed 4-member union) + RecoverError
 // class migrated as-is (OOS-4). RecoverError is surfaced through
-// `recover(): Promise<Result<void, RecoverError>>`, NOT the onError fanout
-// channel (see renderer.ts RendererError composition).
+// `recover(): Promise<Result<void, RecoverFailure>>`, NOT the onError fanout
+// channel (see render-contract.ts RendererError composition).
+
+import type { DeviceScopeReceipt } from '../device/resource-types';
 
 // ── RecoverError (feat-20260621-renderer-health-recover-skeleton M1) ─────────
 
@@ -17,7 +19,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
@@ -93,6 +95,46 @@ export class RecoverError extends Error {
   }
 }
 
+const RENDER_RECOVERY_ERROR_POLICY = {
+  'recover-lifecycle-failed': {
+    expected: 'the replacement DeviceScope must publish only after lifecycle cleanup succeeds',
+    hint: 'inspect detail and cleanupFailures, then recover or rebuild the DeviceScope',
+  },
+  'recover-disposed-during-rebuild': {
+    expected: 'dispose wins over an in-flight recovery rebuild',
+    hint: 'stop using the disposed renderer and create a new Renderer',
+  },
+} as const;
+
+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 class RenderRecoveryError extends Error {
+  readonly code: RenderRecoveryErrorCode;
+  readonly expected: string;
+  readonly hint: string;
+  readonly detail: RenderRecoveryFailureDetail;
+
+  constructor(code: RenderRecoveryErrorCode, detail: RenderRecoveryFailureDetail) {
+    const policy = RENDER_RECOVERY_ERROR_POLICY[code];
+    super(`${code}: ${policy.expected}`);
+    this.name = 'RenderRecoveryError';
+    this.code = code;
+    this.expected = policy.expected;
+    this.hint = policy.hint;
+    this.detail = detail;
+  }
+}
+
+export type RecoverFailure = RecoverError | RenderRecoveryError;
+
 export type IblCapabilityLossCode = 'ibl-hdr-capability-loss';
 
 export interface IblCapabilityLossDetail {