@forgeax/engine-render-graph 0.1.20 → 0.1.23

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { Buffer, ComputePassDescriptor, RhiCommandEncoder, RhiComputePassEncoder, RhiDevice, RhiRenderPassEncoder, Texture, TextureFormat, TextureView } from '@forgeax/engine-rhi';
+import type { Buffer, ComputePassDescriptor, QuerySet, RenderPassDescriptor, RhiCommandEncoder, RhiComputePassEncoder, RhiDevice, RhiRenderPassEncoder, Texture, TextureFormat, TextureView } from '@forgeax/engine-rhi';
 import type { RenderGraphError, Result } from './errors.js';
 import type { ColorValueDomain } from './pipeline/color-value-domain.js';
 declare const graphTextureBrand: unique symbol;
@@ -25,7 +25,7 @@ export type GraphExtent = 'surface' | 'half-surface' | {
 export interface GraphTextureDescriptor {
     readonly format: TextureFormat;
     readonly size: GraphExtent;
-    /** Additional RHI usage required by an external diagnostic consumer. */
+    /** Additional RHI usage required by an external diagnostic consumer such as readback. */
     readonly usage?: number | undefined;
     readonly mipLevelCount?: number | undefined;
     readonly sampleCount?: number | undefined;
@@ -92,6 +92,8 @@ export interface RasterGraphPass<FrameCtx> {
     readonly accesses: readonly GraphAccess[];
     readonly colorAttachments: readonly RasterColorAttachment<FrameCtx>[];
     readonly depthStencilAttachment?: RasterDepthStencilAttachment | undefined;
+    /** Optional producer-owned occlusion query set for this raster pass. */
+    readonly occlusionQuerySet?: QuerySet | undefined;
     readonly executeIf?: ((frame: FrameCtx) => boolean) | undefined;
     encode(context: {
         readonly pass: RhiRenderPassEncoder;
@@ -193,6 +195,21 @@ export interface RenderGraphPassExecution {
     readonly executionIndex: number;
 }
 export type RenderGraphPassRunner = (pass: RenderGraphPassExecution, encode: () => void) => void;
+/**
+ * The graph-neutral boundary for observing and decorating an actual pass.
+ * Render owns the policy supplied here; the graph only preserves pass
+ * provenance and applies the decorated descriptor at the real pass-open
+ * boundary. Timestamp policy and acceptance remain outside the graph.
+ */
+export interface RenderGraphPassInstrumentationScope {
+    readonly renderPassDescriptor?: (descriptor: RenderPassDescriptor) => RenderPassDescriptor;
+    readonly computePassDescriptor?: (descriptor: ComputePassDescriptor) => ComputePassDescriptor;
+    readonly beforeCopy?: (encoder: RhiCommandEncoder) => void;
+    readonly afterCopy?: (encoder: RhiCommandEncoder) => void;
+}
+export interface RenderGraphPassInstrumentation<FrameCtx extends RenderGraphFrame> {
+    begin(pass: RenderGraphPassExecution, frame: FrameCtx): RenderGraphPassInstrumentationScope | undefined;
+}
 export interface RenderGraphCompileOptions {
     readonly device: RhiDevice;
     readonly surfaceSize: {
@@ -201,7 +218,7 @@ export interface RenderGraphCompileOptions {
     };
 }
 export interface CompiledRenderGraph<FrameCtx extends RenderGraphFrame> {
-    execute(frame: FrameCtx, runPass?: RenderGraphPassRunner): Result<void, RenderGraphError>;
+    execute(frame: FrameCtx, runPass?: RenderGraphPassRunner, instrumentation?: RenderGraphPassInstrumentation<FrameCtx>): Result<void, RenderGraphError>;
     inspect(): CompiledRenderGraphInfo;
     retire(): Promise<Result<void, RenderGraphError>>;
 }

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,MAAM,EACN,qBAAqB,EACrB,iBAAiB,EACjB,qBAAqB,EACrB,SAAS,EACT,oBAAoB,EACpB,OAAO,EACP,aAAa,EACb,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEzE,OAAO,CAAC,MAAM,iBAAiB,EAAE,OAAO,MAAM,CAAC;AAC/C,OAAO,CAAC,MAAM,qBAAqB,EAAE,OAAO,MAAM,CAAC;AACnD,OAAO,CAAC,MAAM,gBAAgB,EAAE,OAAO,MAAM,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,CAAC,iBAAiB,CAAC,EAAE,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,CAAC,qBAAqB,CAAC,EAAE,IAAI,CAAC;CACxC;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,CAAC,gBAAgB,CAAC,EAAE,IAAI,CAAC;CACnC;AAED,MAAM,MAAM,aAAa,GAAG,YAAY,GAAG,gBAAgB,GAAG,WAAW,CAAC;AAC1E,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,UAAU,CAAC;AACzD,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,QAAQ,CAAC;AACrD,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;AAE1D,MAAM,MAAM,WAAW,GACnB,SAAS,GACT,cAAc,GACd;IACE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAClD,CAAC;AAEN,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;IACrD,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,aAAa,EAAE,GAAG,SAAS,CAAC;IAC5D,iFAAiF;IACjF,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;CAChD;AAED,MAAM,WAAW,yBAA0B,SAAQ,sBAAsB;IACvE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,uBAAuB,GAAG,SAAS,CAAC;IACzD,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC/C;AAED,MAAM,MAAM,2BAA2B,CAAC,QAAQ,IAAI,CAAC,KAAK,EAAE,QAAQ,KAAK,WAAW,CAAC;AAErF,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACjD;AAED,MAAM,WAAW,wBAAyB,SAAQ,qBAAqB;IACrE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,MAAM,iBAAiB,GACzB,cAAc,GACd,cAAc,GACd,eAAe,GACf,oBAAoB,GACpB,eAAe,GACf,aAAa,GACb,YAAY,GACZ,UAAU,GACV,UAAU,CAAC;AAEf,MAAM,MAAM,kBAAkB,GAC1B,cAAc,GACd,cAAc,GACd,eAAe,GACf,oBAAoB,GACpB,4BAA4B,GAC5B,kBAAkB,GAClB,oBAAoB,GACpB,qBAAqB,GACrB,UAAU,GACV,UAAU,CAAC;AAEf,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAA;CAAE,GACrE;IAAE,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAEhF,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,QAAQ,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAChE,OAAO,CAAC,QAAQ,EAAE,YAAY,GAAG,MAAM,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAC;IACnE,WAAW,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC;CAChF;AAED,MAAM,WAAW,qBAAqB,CAAC,QAAQ;IAC7C,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,aAAa,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACtD,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,GAAG,CAAC,CAAC,KAAK,EAAE,QAAQ,KAAK,QAAQ,CAAC,GAAG,SAAS,CAAC;IAC7E,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;IAC/C,QAAQ,CAAC,cAAc,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACjD,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAChD;AAED,MAAM,WAAW,eAAe,CAAC,QAAQ;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,QAAQ,CAAC,gBAAgB,EAAE,SAAS,qBAAqB,CAAC,QAAQ,CAAC,EAAE,CAAC;IACtE,QAAQ,CAAC,sBAAsB,CAAC,EAAE,4BAA4B,GAAG,SAAS,CAAC;IAC3E,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;IAChE,MAAM,CAAC,OAAO,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;QACpC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;QACzB,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC;KAC3C,GAAG,IAAI,CAAC;CACV;AAED,MAAM,WAAW,gBAAgB,CAAC,QAAQ;IACxC,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;IAChE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,QAAQ,KAAK,qBAAqB,CAAC,GAAG,SAAS,CAAC;IAC1E,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;IAChF,MAAM,CAAC,OAAO,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;QACrC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;QACzB,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC;KAC3C,GAAG,IAAI,CAAC;IACT,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAC1D;AAED,MAAM,WAAW,aAAa,CAAC,QAAQ;IACrC,QAAQ,CAAC,QAAQ,EAAE,SAAS,WAAW,EAAE,CAAC;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,QAAQ,KAAK,OAAO,CAAC,GAAG,SAAS,CAAC;IAChE,MAAM,CAAC,OAAO,EAAE;QACd,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;QACpC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;QACzB,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC;KAC3C,GAAG,IAAI,CAAC;CACV;AAED,MAAM,MAAM,SAAS,CAAC,QAAQ,IAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAA;CAAE,GAC3E;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAA;CAAE,GAC7E;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAA;CAAE,CAAC;AAE5E,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,iBAAiB,GAAG,kBAAkB,CAAC;CACxD;AAED,0EAA0E;AAC1E,MAAM,MAAM,0BAA0B,GAClC;IACE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC/C,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEN,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,SAAS;QACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;QAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;QAChC,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;QAC9C,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;KAC1C,EAAE,CAAC;IACJ,QAAQ,CAAC,SAAS,EAAE,SAAS;QAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;QACjC,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;QACrC,QAAQ,CAAC,UAAU,EAAE,0BAA0B,CAAC;QAChD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QACjC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,oEAAoE;QACpE,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACpD,8EAA8E;QAC9E,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACvC,sEAAsE;QACtE,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;QAC5C,4EAA4E;QAC5E,QAAQ,CAAC,SAAS,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;QACrD,QAAQ,CAAC,MAAM,CAAC,EACZ;YAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;YAAC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;SAAE,GACxF,SAAS,CAAC;KACf,EAAE,CAAC;IACJ,wEAAwE;IACxE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;CACrC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,wBAAwB,EAAE,MAAM,EAAE,MAAM,IAAI,KAAK,IAAI,CAAC;AAEjG,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3E;AAED,MAAM,WAAW,mBAAmB,CAAC,QAAQ,SAAS,gBAAgB;IACpE,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC;IAC1F,OAAO,IAAI,uBAAuB,CAAC;IACnC,MAAM,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,EAAE,gBAAgB,CAAC,CAAC,CAAC;CACnD"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeax/engine-render-graph",
-  "version": "0.1.20",
+  "version": "0.1.23",
   "private": false,
   "type": "module",
   "license": "Apache-2.0",
@@ -22,12 +22,12 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@forgeax/engine-rhi": "0.1.20",
-    "@forgeax/engine-types": "0.1.20",
+    "@forgeax/engine-rhi": "0.1.23",
+    "@forgeax/engine-types": "0.1.23",
     "@webgpu/types": "^0.1.71"
   },
   "devDependencies": {
-    "@forgeax/engine-rhi-null": "0.1.20"
+    "@forgeax/engine-rhi-null": "0.1.23"
   },
   "forgeax": {
     "metrics": {

package/src/__tests__/render-graph-builder.unit.test.ts

@@ -1,6 +1,7 @@
 import type {
   Buffer,
   ComputePassDescriptor,
+  QuerySet,
   RhiCommandEncoder,
   RhiComputePassEncoder,
   RhiDevice,
@@ -10,7 +11,7 @@ import type {
 import { describe, expect, it } from 'vitest';
 import { RenderGraphBuilder } from '../builder.js';
 import { ok } from '../errors.js';
-import type { RenderGraphFrame } from '../types.js';
+import type { RenderGraphFrame, RenderGraphPassInstrumentation } from '../types.js';
 
 interface Frame extends RenderGraphFrame {
   readonly imported: Buffer;
@@ -448,6 +449,29 @@ describe('RenderGraphBuilder capability, execution, and lifecycle contracts', ()
     );
   });
 
+  it('keeps declared created-texture usage alongside graph-derived usage', () => {
+    const graph = new RenderGraphBuilder<Frame>();
+    const texture = value(
+      graph.createTexture('readback-target', {
+        format: 'rgba8unorm',
+        size: 'surface',
+        usage: 0x01,
+      }),
+    );
+    const view = value(graph.view(texture));
+    graph.addRasterPass('write', {
+      accesses: [{ resource: view, usage: 'color-attachment' }],
+      colorAttachments: [{ view, loadOp: 'clear', storeOp: 'store' }],
+      encode: () => undefined,
+    });
+    const compiled = value(
+      graph.compile({ device: mockDevice(), surfaceSize: { width: 1, height: 1 } }),
+    );
+    expect(compiled.inspect().resources).toContainEqual(
+      expect.objectContaining({ label: 'readback-target', derivedUsage: 0x11 }),
+    );
+  });
+
   it('derives compute and storage capabilities from pass/access declarations', () => {
     const graph = new RenderGraphBuilder<Frame>();
     const buffer = value(
@@ -501,6 +525,96 @@ describe('RenderGraphBuilder capability, execution, and lifecycle contracts', ()
     ]);
   });
 
+  it('applies pass timestamp instrumentation at the real raster and compute boundaries', () => {
+    const graph = new RenderGraphBuilder<Frame>();
+    const texture = value(
+      graph.importTexture(
+        'surface',
+        { format: 'rgba8unorm', size: 'surface', usage: 0x10 },
+        (frame) => frame.importedTexture as Texture,
+      ),
+    );
+    const view = value(
+      graph.importView(
+        texture,
+        { label: 'surface.view' },
+        (frame) => frame.importedView as TextureView,
+      ),
+    );
+    graph.addRasterPass('timed-raster', {
+      accesses: [{ resource: view, usage: 'color-attachment' }],
+      colorAttachments: [{ view, loadOp: 'clear', storeOp: 'store' }],
+      encode: () => undefined,
+    });
+    graph.addComputePass('timed-compute', {
+      accesses: [],
+      encode: () => undefined,
+    });
+    const compiled = value(
+      graph.compile({ device: mockDevice(), surfaceSize: { width: 1, height: 1 } }),
+    );
+    const querySet = {} as QuerySet;
+    const rasterWrites = {
+      querySet,
+      beginningOfPassWriteIndex: 4,
+      endOfPassWriteIndex: 5,
+    } as const;
+    const computeWrites = {
+      querySet,
+      beginningOfPassWriteIndex: 6,
+      endOfPassWriteIndex: 7,
+    } as const;
+    let rasterDescriptor: { readonly timestampWrites?: unknown } | undefined;
+    const computeDescriptors: Array<{ readonly timestampWrites?: unknown }> = [];
+    const encoder = {
+      ...mockEncoder(),
+      beginRenderPass: (descriptor: { readonly timestampWrites?: unknown }) => {
+        rasterDescriptor = descriptor;
+        return { end: () => undefined } as never;
+      },
+      beginComputePass: (descriptor: ComputePassDescriptor = {}) => {
+        computeDescriptors.push(descriptor);
+        return {
+          setPipeline: () => undefined,
+          setBindGroup: () => undefined,
+          dispatchWorkgroups: () => undefined,
+          dispatchWorkgroupsIndirect: () => undefined,
+          end: () => undefined,
+        } as unknown as RhiComputePassEncoder;
+      },
+    } as unknown as RhiCommandEncoder;
+    const instrumentation: RenderGraphPassInstrumentation<Frame> = {
+      begin: (pass) =>
+        pass.kind === 'raster'
+          ? {
+              renderPassDescriptor: (descriptor) => ({
+                ...descriptor,
+                timestampWrites: rasterWrites,
+              }),
+            }
+          : {
+              computePassDescriptor: (descriptor) => ({
+                ...descriptor,
+                timestampWrites: computeWrites,
+              }),
+            },
+    };
+    const executed = compiled.execute(
+      {
+        encoder,
+        imported: {} as Buffer,
+        importedTexture: {} as Texture,
+        importedView: {} as TextureView,
+      },
+      undefined,
+      instrumentation,
+    );
+    expect(executed.ok).toBe(true);
+    expect(rasterDescriptor?.timestampWrites).toBe(rasterWrites);
+    expect(computeDescriptors).toHaveLength(1);
+    expect(computeDescriptors[0]?.timestampWrites).toBe(computeWrites);
+  });
+
   it('reports a graph-owned compute pass begin failure to the pass owner', () => {
     const events: string[] = [];
     const graph = new RenderGraphBuilder<Frame>();

package/src/__tests__/render-graph-gpu-timing-instrumentation.unit.test.ts

@@ -0,0 +1,183 @@
+import type {
+  Buffer,
+  ComputePassDescriptor,
+  RenderPassDescriptor,
+  RhiCommandEncoder,
+  RhiComputePassEncoder,
+  RhiDevice,
+  RhiRenderPassEncoder,
+  Texture,
+  TextureView,
+} from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import { RenderGraphBuilder } from '../builder.js';
+import type { RenderGraphFrame, RenderGraphPassInstrumentation } from '../types.js';
+
+interface Frame extends RenderGraphFrame {
+  readonly source: Buffer;
+}
+
+function mockDevice(): RhiDevice {
+  let nextId = 0;
+  return {
+    caps: {
+      backendKind: 'null',
+      compute: true,
+      storageBuffer: true,
+      storageTexture: true,
+      timestampQuery: false,
+      timestampPeriodNanoseconds: null,
+      indirectDrawing: true,
+      textureCompressionBc: false,
+      textureCompressionEtc2: false,
+      textureCompressionAstc: false,
+      multiDrawIndirect: false,
+      pushConstants: false,
+      textureBindingArray: false,
+      samplerAliasing: true,
+      firstInstanceIndirect: false,
+      rgba16floatRenderable: true,
+      rg11b10ufloatRenderable: true,
+      float32Filterable: true,
+      maxColorAttachments: 8,
+    },
+    limits: {} as never,
+    features: new Set() as never,
+    queue: { onSubmittedWorkDone: async () => undefined } as never,
+    createTexture: () => ({ ok: true, value: { id: nextId++ } as unknown as Texture }),
+    createTextureView: () => ({ ok: true, value: { id: nextId++ } as unknown as TextureView }),
+    createBuffer: () => ({ ok: true, value: { id: nextId++ } as unknown as Buffer }),
+    destroyTexture: () => ({ ok: true, value: undefined }),
+    destroyBuffer: () => ({ ok: true, value: undefined }),
+  } as unknown as RhiDevice;
+}
+
+function buildGraph() {
+  const graph = new RenderGraphBuilder<Frame>();
+  const color = graph.createTexture('color', { format: 'rgba8unorm', size: 'surface' });
+  if (!color.ok) throw color.error;
+  const view = graph.view(color.value);
+  if (!view.ok) throw view.error;
+  graph.addRasterPass('raster', {
+    accesses: [{ resource: view.value, usage: 'color-attachment' }],
+    colorAttachments: [{ view: view.value, loadOp: 'clear', storeOp: 'store' }],
+    encode: () => undefined,
+  });
+  graph.addComputePass('compute', { accesses: [], encode: () => undefined });
+  graph.addCopyPass('copy', { accesses: [], encode: () => undefined });
+  graph.addComputePass('skipped', {
+    accesses: [],
+    executeIf: () => false,
+    encode: () => undefined,
+  });
+  return graph;
+}
+
+function mockEncoder(events: string[]): RhiCommandEncoder {
+  return {
+    beginRenderPass: (descriptor: RenderPassDescriptor) => {
+      events.push(`begin-raster:${descriptor.timestampWrites === undefined ? 'none' : 'timed'}`);
+      return { end: () => events.push('end-raster') } as unknown as RhiRenderPassEncoder;
+    },
+    beginComputePass: (descriptor: ComputePassDescriptor = {}) => {
+      events.push(`begin-compute:${descriptor.timestampWrites === undefined ? 'none' : 'timed'}`);
+      return { end: () => events.push('end-compute') } as unknown as RhiComputePassEncoder;
+    },
+    clearBuffer: () => events.push('clear-buffer'),
+  } as unknown as RhiCommandEncoder;
+}
+
+function value<T>(result: { readonly ok: true; readonly value: T } | { readonly ok: false }): T {
+  if (!result.ok) throw new Error('expected ok result');
+  return result.value;
+}
+
+describe('RenderGraph actual-pass timing instrumentation', () => {
+  it('reports only actual passes with compiled provenance and injects at pass boundaries', () => {
+    const graph = buildGraph();
+    const compiled = graph.compile({
+      device: mockDevice(),
+      surfaceSize: { width: 1, height: 1 },
+    });
+    expect(compiled.ok).toBe(true);
+    if (!compiled.ok) return;
+
+    const events: string[] = [];
+    const actualPasses: string[] = [];
+    const instrumentation: RenderGraphPassInstrumentation<Frame> = {
+      begin(pass) {
+        actualPasses.push(`${pass.executionIndex}:${pass.kind}:${pass.name}`);
+        return {
+          renderPassDescriptor: (descriptor) => ({
+            ...descriptor,
+            timestampWrites: {
+              querySet: {} as never,
+              beginningOfPassWriteIndex: 0,
+              endOfPassWriteIndex: 1,
+            },
+          }),
+          computePassDescriptor: (descriptor) => ({
+            ...descriptor,
+            timestampWrites: {
+              querySet: {} as never,
+              beginningOfPassWriteIndex: 2,
+              endOfPassWriteIndex: 3,
+            },
+          }),
+          beforeCopy: () => events.push('before-copy'),
+          afterCopy: () => events.push('after-copy'),
+        };
+      },
+    };
+
+    const result = value(compiled).execute(
+      { encoder: mockEncoder(events), source: {} as Buffer },
+      undefined,
+      instrumentation,
+    );
+    expect(result.ok).toBe(true);
+    expect(actualPasses).toEqual(['0:raster:raster', '1:compute:compute', '2:copy:copy']);
+    expect(events).toEqual([
+      'begin-raster:timed',
+      'end-raster',
+      'begin-compute:timed',
+      'end-compute',
+      'before-copy',
+      'after-copy',
+    ]);
+  });
+
+  it('keeps the no-hook graph and command ledger equivalent', () => {
+    const graph = buildGraph();
+    const compiled = graph.compile({
+      device: mockDevice(),
+      surfaceSize: { width: 1, height: 1 },
+    });
+    expect(compiled.ok).toBe(true);
+    if (!compiled.ok) return;
+
+    const events: string[] = [];
+    const result = value(compiled).execute({ encoder: mockEncoder(events), source: {} as Buffer });
+    expect(result.ok).toBe(true);
+    expect(events).toEqual([
+      'begin-raster:none',
+      'end-raster',
+      'begin-compute:none',
+      'end-compute',
+    ]);
+    expect(
+      value(compiled)
+        .inspect()
+        .passes.map(({ name, kind, executionIndex }) => ({
+          name,
+          kind,
+          executionIndex,
+        })),
+    ).toEqual([
+      { name: 'raster', kind: 'raster', executionIndex: 0 },
+      { name: 'compute', kind: 'compute', executionIndex: 1 },
+      { name: 'copy', kind: 'copy', executionIndex: 2 },
+      { name: 'skipped', kind: 'compute', executionIndex: 3 },
+    ]);
+  });
+});

package/src/builder.ts

@@ -597,10 +597,14 @@ export class RenderGraphBuilder<FrameCtx extends RenderGraphFrame> {
         const item = this.normalizeAccess(passIndex, pass, access);
         if (!item.ok) return item;
         normalized.push(item.value);
+        const resource = this.resources.get(item.value.resourceId);
         const usage =
-          this.resources.get(item.value.resourceId)?.kind === 'buffer'
+          (resource?.kind === 'texture' && resource.origin === 'created'
+            ? (resource.descriptor.usage ?? 0)
+            : 0) |
+          (resource?.kind === 'buffer'
             ? bufferUsage(access.usage as GraphBufferAccess)
-            : textureUsage(access.usage as GraphTextureAccess);
+            : textureUsage(access.usage as GraphTextureAccess));
         usageByResource.set(
           item.value.resourceId,
           (usageByResource.get(item.value.resourceId) ?? 0) | usage,

package/src/compiled-graph.ts

@@ -24,6 +24,7 @@ import type {
   GraphTexture,
   GraphTextureView,
   RenderGraphFrame,
+  RenderGraphPassInstrumentation,
   RenderGraphPassRunner,
 } from './types.js';
 
@@ -82,7 +83,11 @@ export class CompiledRenderGraphImpl<FrameCtx extends RenderGraphFrame>
     return this.colorTargetDescriptors.get(name);
   }
 
-  execute(frame: FrameCtx, runPass?: RenderGraphPassRunner): Result<void, RenderGraphError> {
+  execute(
+    frame: FrameCtx,
+    runPass?: RenderGraphPassRunner,
+    instrumentation?: RenderGraphPassInstrumentation<FrameCtx>,
+  ): Result<void, RenderGraphError> {
     if (this.retired) {
       return err(
         new RenderGraphError({
@@ -101,8 +106,14 @@ export class CompiledRenderGraphImpl<FrameCtx extends RenderGraphFrame>
       const resolver = this.createPassResolver(pass, resolved.value);
       try {
         if (pass.pass.descriptor.executeIf?.(frame) === false) continue;
+        const execution = { name: pass.name, kind: pass.pass.kind, executionIndex };
         let encodeResult: Result<void, RenderGraphError> = ok(undefined);
         const encode = () => {
+          // Resolve instrumentation only when the runner actually enters the
+          // pass. A runner may inspect or skip a pass without calling encode;
+          // such a pass must not reserve timestamp queries that it never
+          // writes.
+          const scope = instrumentation?.begin(execution, frame);
           switch (pass.pass.kind) {
             case 'raster': {
               const descriptor = pass.pass.descriptor;
@@ -172,11 +183,17 @@ export class CompiledRenderGraphImpl<FrameCtx extends RenderGraphFrame>
                     : { stencilReadOnly: attachment.stencilReadOnly }),
                 };
               }
-              const encoder = frame.encoder.beginRenderPass({
+              const baseDescriptor = {
                 label: pass.name,
                 colorAttachments,
                 ...(depthStencilAttachment === undefined ? {} : { depthStencilAttachment }),
-              });
+                ...(pass.pass.descriptor.occlusionQuerySet === undefined
+                  ? {}
+                  : { occlusionQuerySet: pass.pass.descriptor.occlusionQuerySet }),
+              };
+              const instrumentedDescriptor =
+                scope?.renderPassDescriptor?.(baseDescriptor) ?? baseDescriptor;
+              const encoder = frame.encoder.beginRenderPass(instrumentedDescriptor);
               try {
                 descriptor.encode({ pass: encoder, frame, resources: resolver });
               } finally {
@@ -186,9 +203,13 @@ export class CompiledRenderGraphImpl<FrameCtx extends RenderGraphFrame>
             }
             case 'compute': {
               const begin = pass.pass.descriptor.begin?.(frame);
+              const instrumentedBegin = scope?.computePassDescriptor?.(begin ?? {}) ?? begin;
               let encoder: RhiComputePassEncoder;
               try {
-                encoder = frame.encoder.beginComputePass({ ...(begin ?? {}), label: pass.name });
+                encoder = frame.encoder.beginComputePass({
+                  ...(instrumentedBegin ?? {}),
+                  label: pass.name,
+                });
               } catch (cause) {
                 pass.pass.descriptor.onBeginError?.(frame, cause);
                 throw cause;
@@ -202,14 +223,19 @@ export class CompiledRenderGraphImpl<FrameCtx extends RenderGraphFrame>
               break;
             }
             case 'copy':
-              pass.pass.descriptor.encode({ encoder: frame.encoder, frame, resources: resolver });
+              scope?.beforeCopy?.(frame.encoder);
+              try {
+                pass.pass.descriptor.encode({ encoder: frame.encoder, frame, resources: resolver });
+              } finally {
+                scope?.afterCopy?.(frame.encoder);
+              }
               break;
           }
         };
         if (runPass === undefined) {
           encode();
         } else {
-          runPass({ name: pass.name, kind: pass.pass.kind, executionIndex }, encode);
+          runPass(execution, encode);
         }
         if (!encodeResult.ok) return encodeResult;
       } catch (cause) {

package/src/index.ts

@@ -97,5 +97,7 @@ export type {
   RenderGraphCompileOptions,
   RenderGraphFrame,
   RenderGraphPassExecution,
+  RenderGraphPassInstrumentation,
+  RenderGraphPassInstrumentationScope,
   RenderGraphPassRunner,
 } from './types.js';

package/src/types.ts

@@ -1,6 +1,8 @@
 import type {
   Buffer,
   ComputePassDescriptor,
+  QuerySet,
+  RenderPassDescriptor,
   RhiCommandEncoder,
   RhiComputePassEncoder,
   RhiDevice,
@@ -45,7 +47,7 @@ export type GraphExtent =
 export interface GraphTextureDescriptor {
   readonly format: TextureFormat;
   readonly size: GraphExtent;
-  /** Additional RHI usage required by an external diagnostic consumer. */
+  /** Additional RHI usage required by an external diagnostic consumer such as readback. */
   readonly usage?: number | undefined;
   readonly mipLevelCount?: number | undefined;
   readonly sampleCount?: number | undefined;
@@ -139,6 +141,8 @@ export interface RasterGraphPass<FrameCtx> {
   readonly accesses: readonly GraphAccess[];
   readonly colorAttachments: readonly RasterColorAttachment<FrameCtx>[];
   readonly depthStencilAttachment?: RasterDepthStencilAttachment | undefined;
+  /** Optional producer-owned occlusion query set for this raster pass. */
+  readonly occlusionQuerySet?: QuerySet | undefined;
   readonly executeIf?: ((frame: FrameCtx) => boolean) | undefined;
   encode(context: {
     readonly pass: RhiRenderPassEncoder;
@@ -244,13 +248,37 @@ export interface RenderGraphPassExecution {
 
 export type RenderGraphPassRunner = (pass: RenderGraphPassExecution, encode: () => void) => void;
 
+/**
+ * The graph-neutral boundary for observing and decorating an actual pass.
+ * Render owns the policy supplied here; the graph only preserves pass
+ * provenance and applies the decorated descriptor at the real pass-open
+ * boundary. Timestamp policy and acceptance remain outside the graph.
+ */
+export interface RenderGraphPassInstrumentationScope {
+  readonly renderPassDescriptor?: (descriptor: RenderPassDescriptor) => RenderPassDescriptor;
+  readonly computePassDescriptor?: (descriptor: ComputePassDescriptor) => ComputePassDescriptor;
+  readonly beforeCopy?: (encoder: RhiCommandEncoder) => void;
+  readonly afterCopy?: (encoder: RhiCommandEncoder) => void;
+}
+
+export interface RenderGraphPassInstrumentation<FrameCtx extends RenderGraphFrame> {
+  begin(
+    pass: RenderGraphPassExecution,
+    frame: FrameCtx,
+  ): RenderGraphPassInstrumentationScope | undefined;
+}
+
 export interface RenderGraphCompileOptions {
   readonly device: RhiDevice;
   readonly surfaceSize: { readonly width: number; readonly height: number };
 }
 
 export interface CompiledRenderGraph<FrameCtx extends RenderGraphFrame> {
-  execute(frame: FrameCtx, runPass?: RenderGraphPassRunner): Result<void, RenderGraphError>;
+  execute(
+    frame: FrameCtx,
+    runPass?: RenderGraphPassRunner,
+    instrumentation?: RenderGraphPassInstrumentation<FrameCtx>,
+  ): Result<void, RenderGraphError>;
   inspect(): CompiledRenderGraphInfo;
   retire(): Promise<Result<void, RenderGraphError>>;
 }