@forgeax/engine-render-graph 0.1.2

package/dist/observation.d.ts

@@ -0,0 +1,38 @@
+import type { Texture } from '@forgeax/engine-rhi';
+import { RenderGraphError, type Result } from './errors.js';
+export { RenderGraphError } from './errors.js';
+export interface ObservationSize {
+    readonly width: number;
+    readonly height: number;
+}
+/** Generic producer-owned metadata for one current-frame texture. */
+export interface CurrentFrameObservationDescriptor {
+    readonly texture: Texture;
+    readonly format: string;
+    readonly size: ObservationSize;
+    readonly usage: number;
+    readonly frameId: number;
+}
+export interface CurrentFrameObservationLifetime {
+    readonly frameId: number;
+    readonly state: 'active' | 'retired';
+}
+/** The only resource information a downstream copy consumer receives. */
+export interface CurrentFrameObservationSource {
+    readonly texture: Texture;
+    readonly descriptor: CurrentFrameObservationDescriptor;
+    readonly lifetime: CurrentFrameObservationLifetime;
+}
+export interface CurrentFrameObservationLease {
+    readonly descriptor: CurrentFrameObservationDescriptor;
+    readonly lifetime: CurrentFrameObservationLifetime;
+    readonly state: CurrentFrameObservationLifetime['state'];
+    beginReadback(): Result<CurrentFrameObservationSource, RenderGraphError>;
+    retire(): void;
+}
+/**
+ * Validate and lease a producer's current-frame texture without naming any
+ * semantic, pipeline, backend policy, or graph resource key.
+ */
+export declare function createCurrentFrameObservationLease(descriptor: CurrentFrameObservationDescriptor, currentFrameId: number): Result<CurrentFrameObservationLease, RenderGraphError>;
+//# sourceMappingURL=observation.d.ts.map

package/dist/observation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation.d.ts","sourceRoot":"","sources":["../src/observation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAW,gBAAgB,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC;AAErE,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAI/C,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,qEAAqE;AACrE,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,SAAS,CAAC;CACtC;AAED,yEAAyE;AACzE,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,iCAAiC,CAAC;IACvD,QAAQ,CAAC,QAAQ,EAAE,+BAA+B,CAAC;CACpD;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,UAAU,EAAE,iCAAiC,CAAC;IACvD,QAAQ,CAAC,QAAQ,EAAE,+BAA+B,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,+BAA+B,CAAC,OAAO,CAAC,CAAC;IACzD,aAAa,IAAI,MAAM,CAAC,6BAA6B,EAAE,gBAAgB,CAAC,CAAC;IACzE,MAAM,IAAI,IAAI,CAAC;CAChB;AAeD;;;GAGG;AACH,wBAAgB,kCAAkC,CAChD,UAAU,EAAE,iCAAiC,EAC7C,cAAc,EAAE,MAAM,GACrB,MAAM,CAAC,4BAA4B,EAAE,gBAAgB,CAAC,CAwExD"}

package/dist/pass-registry.d.ts

@@ -0,0 +1,12 @@
+import type { PassDescriptor } from './graph.js';
+export interface PassEntry<Ctx = unknown> {
+    readonly name: string;
+    readonly descriptor: PassDescriptor<Ctx>;
+}
+export declare class PassRegistry<Ctx = unknown> {
+    private readonly passes;
+    add(name: string, descriptor: PassDescriptor<Ctx>, before?: string): PassEntry<Ctx>;
+    list(): readonly PassEntry<Ctx>[];
+    count(): number;
+}
+//# sourceMappingURL=pass-registry.d.ts.map

package/dist/pass-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pass-registry.d.ts","sourceRoot":"","sources":["../src/pass-registry.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,WAAW,SAAS,CAAC,GAAG,GAAG,OAAO;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC;CAC1C;AAED,qBAAa,YAAY,CAAC,GAAG,GAAG,OAAO;IACrC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwB;IAE/C,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,cAAc,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC;IAiBnF,IAAI,IAAI,SAAS,SAAS,CAAC,GAAG,CAAC,EAAE;IAIjC,KAAK,IAAI,MAAM;CAGhB"}

package/dist/pipeline/__tests__/color-value-domain.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=color-value-domain.test.d.ts.map

package/dist/pipeline/__tests__/color-value-domain.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color-value-domain.test.d.ts","sourceRoot":"","sources":["../../../src/pipeline/__tests__/color-value-domain.test.ts"],"names":[],"mappings":""}

package/dist/pipeline/color-value-domain.d.ts

@@ -0,0 +1,35 @@
+import { RenderGraphError, type Result } from '../errors.js';
+export declare const COLOR_VALUE_DOMAINS: readonly ["linear-hdr", "linear-ldr", "display-encoded"];
+export type ColorValueDomain = (typeof COLOR_VALUE_DOMAINS)[number];
+export type ColorDomainConversion = {
+    readonly kind: 'encode-srgb';
+} | {
+    readonly kind: 'decode-srgb';
+} | {
+    readonly kind: 'tone-map';
+};
+export interface ColorResourceDescriptor {
+    readonly domain: ColorValueDomain;
+    readonly format: string;
+}
+export interface ColorDomainConnection {
+    readonly source: string;
+    readonly destination: string;
+    readonly conversion?: ColorDomainConversion | undefined;
+}
+export type ColorDomainValidation = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly error: RenderGraphError;
+};
+export declare function isColorValueDomain(value: unknown): value is ColorValueDomain;
+declare function invalidDomain(value: unknown): RenderGraphError;
+declare function missingDomain(resourceKey?: string): RenderGraphError;
+export declare function serializeColorValueDomain(domain: ColorValueDomain): string;
+export declare function deserializeColorValueDomain(value: unknown): Result<ColorValueDomain, RenderGraphError>;
+export declare function serializeColorResourceDescriptor(descriptor: ColorResourceDescriptor): string;
+export declare function deserializeColorResourceDescriptor(value: unknown): Result<ColorResourceDescriptor, RenderGraphError>;
+export declare function validateColorDomainConnection(source: unknown, destination: unknown, conversion?: ColorDomainConversion): ColorDomainValidation;
+export { invalidDomain, missingDomain };
+//# sourceMappingURL=color-value-domain.d.ts.map

package/dist/pipeline/color-value-domain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"color-value-domain.d.ts","sourceRoot":"","sources":["../../src/pipeline/color-value-domain.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,gBAAgB,EAAE,KAAK,MAAM,EAAE,MAAM,cAAc,CAAC;AAEtE,eAAO,MAAM,mBAAmB,0DAA2D,CAAC;AAE5F,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEpE,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE,GAChC;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;CAAE,GAChC;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,CAAC;AAElC,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;CACzD;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GACrB;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAE7D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAE5E;AAED,iBAAS,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,gBAAgB,CAOvD;AAED,iBAAS,aAAa,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAO7D;AAED,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAG1E;AAED,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,GACb,MAAM,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAU5C;AAED,wBAAgB,gCAAgC,CAAC,UAAU,EAAE,uBAAuB,GAAG,MAAM,CAG5F;AAED,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,OAAO,GACb,MAAM,CAAC,uBAAuB,EAAE,gBAAgB,CAAC,CAgBnD;AAsBD,wBAAgB,6BAA6B,CAC3C,MAAM,EAAE,OAAO,EACf,WAAW,EAAE,OAAO,EACpB,UAAU,CAAC,EAAE,qBAAqB,GACjC,qBAAqB,CAoBvB;AAED,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,CAAC"}

package/dist/resource-registry.d.ts

@@ -0,0 +1,61 @@
+import { type CapMissingDetail, type DanglingReadDetail, type DuplicateResourceDetail, RenderGraphError, type Result } from './errors.js';
+import type { ColorTargetDescriptor, ColorTargetSize, ResourceDescriptor, ResourceLifetime } from './graph.js';
+import type { ColorValueDomain } from './pipeline/color-value-domain.js';
+/**
+ * Per-resource GPU allocation metadata carried through compile.
+ * When the resource was registered via addColorTarget, colorTarget
+ * carries the format/size/sample/usage fields (w5); when via
+ * addResource it is undefined.
+ */
+export interface ColorTargetResourceMeta {
+    readonly format: string;
+    readonly size: ColorTargetSize;
+    readonly sample: number;
+    readonly usage: number;
+    /** Explicit semantic color domain; never derived from format. */
+    readonly domain?: ColorValueDomain | undefined;
+    /**
+     * Extra texture view formats pre-declared at GPU texture creation. Mirrors
+     * GPUTextureDescriptor.viewFormats. Used by the LDR MSAA path which needs a
+     * `bgra8unorm` storage texture plus a `bgra8unorm-srgb` view of the same
+     * texture for hardware sRGB encoding on store.
+     */
+    readonly viewFormats?: readonly string[] | undefined;
+    /**
+     * When set, this resource is an alias of the given source resource.
+     * The compile allocation phase folds the alias into the source's
+     * physical texture (KB-1 MoveNode pattern, D-2).
+     */
+    readonly aliasedFrom?: string | undefined;
+}
+export interface ResourceEntry {
+    readonly key: string;
+    readonly descriptor: ResourceDescriptor;
+    readonly lifetime: ResourceLifetime;
+    /** Present when the resource was registered via addColorTarget (w5). */
+    readonly colorTarget?: ColorTargetResourceMeta | undefined;
+}
+export declare class ResourceRegistry {
+    private readonly resources;
+    add(key: string, descriptor: ResourceDescriptor): Result<ResourceEntry, RenderGraphError>;
+    /**
+     * Register a color target resource (D-8).
+     * Same semantics as addResource with kind:'texture' plus GPU texture
+     * allocation metadata. Existing callers default to a transient target.
+     */
+    addColorTarget(name: string, desc: ColorTargetDescriptor): Result<ResourceEntry, RenderGraphError>;
+    /**
+     * Register a color target alias that folds into the source's physical
+     * texture at compile time (KB-1 MoveNode pattern, D-2).
+     * The source must already be registered via addColorTarget.
+     */
+    addColorTargetAlias(name: string, source: string): Result<ResourceEntry, RenderGraphError>;
+    private duplicateResource;
+    private register;
+    get(key: string): ResourceEntry | undefined;
+    getColorTargetMeta(key: string): ColorTargetResourceMeta | undefined;
+    has(key: string): boolean;
+    entries(): IterableIterator<ResourceEntry>;
+}
+export type { CapMissingDetail, DanglingReadDetail, DuplicateResourceDetail };
+//# sourceMappingURL=resource-registry.d.ts.map

package/dist/resource-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-registry.d.ts","sourceRoot":"","sources":["../src/resource-registry.ts"],"names":[],"mappings":"AASA,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,EAG5B,gBAAgB,EAChB,KAAK,MAAM,EACZ,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACV,qBAAqB,EACrB,eAAe,EACf,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAEzE;;;;;GAKG;AACH,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,iEAAiE;IACjE,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,GAAG,SAAS,CAAC;IAC/C;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IACrD;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3C;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC,wEAAwE;IACxE,QAAQ,CAAC,WAAW,CAAC,EAAE,uBAAuB,GAAG,SAAS,CAAC;CAC5D;AAED,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoC;IAE9D,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,kBAAkB,GAAG,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC;IASzF;;;;OAIG;IACH,cAAc,CACZ,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,qBAAqB,GAC1B,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC;IAmB1C;;;;OAIG;IACH,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,aAAa,EAAE,gBAAgB,CAAC;IA8B1F,OAAO,CAAC,iBAAiB;IAWzB,OAAO,CAAC,QAAQ;IAMhB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAI3C,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS;IAIpE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIzB,OAAO,IAAI,gBAAgB,CAAC,aAAa,CAAC;CAG3C;AAGD,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,171 @@
+import type { Buffer, ComputePassDescriptor, RhiCommandEncoder, RhiComputePassEncoder, RhiDevice, RhiRenderPassEncoder, Texture, TextureFormat, TextureView } from '@forgeax/engine-rhi';
+import type { RenderGraphError, Result } from './errors.js';
+declare const graphTextureBrand: unique symbol;
+declare const graphTextureViewBrand: unique symbol;
+declare const graphBufferBrand: unique symbol;
+export interface GraphTexture {
+    readonly [graphTextureBrand]: true;
+}
+export interface GraphTextureView {
+    readonly [graphTextureViewBrand]: true;
+}
+export interface GraphBuffer {
+    readonly [graphBufferBrand]: true;
+}
+export type GraphResource = GraphTexture | GraphTextureView | GraphBuffer;
+export type GraphResourceOrigin = 'created' | 'imported';
+export type GraphResourceKind = 'texture' | 'buffer';
+export type GraphExtent = 'surface' | 'half-surface' | {
+    readonly width: number;
+    readonly height: number;
+    readonly depthOrArrayLayers?: number | undefined;
+};
+export interface GraphTextureDescriptor {
+    readonly format: TextureFormat;
+    readonly size: GraphExtent;
+    readonly mipLevelCount?: number | undefined;
+    readonly sampleCount?: number | undefined;
+    readonly dimension?: GPUTextureDimension | undefined;
+    readonly viewFormats?: readonly TextureFormat[] | undefined;
+}
+export interface ImportedTextureDescriptor extends GraphTextureDescriptor {
+    readonly usage: number;
+}
+export interface GraphTextureViewDescriptor {
+    readonly label?: string | undefined;
+    readonly format?: TextureFormat | undefined;
+    readonly dimension?: GPUTextureViewDimension | undefined;
+    readonly aspect?: GPUTextureAspect | undefined;
+    readonly baseMipLevel?: number | undefined;
+    readonly mipLevelCount?: number | undefined;
+    readonly baseArrayLayer?: number | undefined;
+    readonly arrayLayerCount?: number | undefined;
+}
+export type ImportedTextureViewResolver<FrameCtx> = (frame: FrameCtx) => TextureView;
+export interface GraphBufferDescriptor {
+    readonly size: number;
+    readonly mappedAtCreation?: boolean | undefined;
+}
+export interface ImportedBufferDescriptor extends GraphBufferDescriptor {
+    readonly usage: number;
+}
+export type GraphBufferAccess = 'uniform-read' | 'storage-read' | 'storage-write' | 'storage-read-write' | 'indirect-read' | 'vertex-read' | 'index-read' | 'copy-src' | 'copy-dst';
+export type GraphTextureAccess = 'sampled-read' | 'storage-read' | 'storage-write' | 'storage-read-write' | 'color-attachment' | 'depth-stencil-read' | 'depth-stencil-write' | 'copy-src' | 'copy-dst';
+export type GraphAccess = {
+    readonly resource: GraphBuffer;
+    readonly usage: GraphBufferAccess;
+} | {
+    readonly resource: GraphTextureView;
+    readonly usage: GraphTextureAccess;
+};
+export interface GraphResourceResolver {
+    buffer(resource: GraphBuffer): Result<Buffer, RenderGraphError>;
+    texture(resource: GraphTexture): Result<Texture, RenderGraphError>;
+    textureView(resource: GraphTextureView): Result<TextureView, RenderGraphError>;
+}
+export interface RasterColorAttachment<FrameCtx> {
+    readonly view: GraphTextureView;
+    readonly resolveTarget?: GraphTextureView | undefined;
+    readonly clearValue?: GPUColor | ((frame: FrameCtx) => GPUColor) | undefined;
+    readonly loadOp: GPULoadOp;
+    readonly storeOp: GPUStoreOp;
+    readonly depthSlice?: number | undefined;
+}
+export interface RasterDepthStencilAttachment {
+    readonly view: GraphTextureView;
+    readonly depthClearValue?: number | undefined;
+    readonly depthLoadOp?: GPULoadOp | undefined;
+    readonly depthStoreOp?: GPUStoreOp | undefined;
+    readonly depthReadOnly?: boolean | undefined;
+    readonly stencilClearValue?: number | undefined;
+    readonly stencilLoadOp?: GPULoadOp | undefined;
+    readonly stencilStoreOp?: GPUStoreOp | undefined;
+    readonly stencilReadOnly?: boolean | undefined;
+}
+export interface RasterGraphPass<FrameCtx> {
+    readonly accesses: readonly GraphAccess[];
+    readonly colorAttachments: readonly RasterColorAttachment<FrameCtx>[];
+    readonly depthStencilAttachment?: RasterDepthStencilAttachment | undefined;
+    readonly executeIf?: ((frame: FrameCtx) => boolean) | undefined;
+    encode(context: {
+        readonly pass: RhiRenderPassEncoder;
+        readonly frame: FrameCtx;
+        readonly resources: GraphResourceResolver;
+    }): void;
+}
+export interface ComputeGraphPass<FrameCtx> {
+    readonly accesses: readonly GraphAccess[];
+    readonly executeIf?: ((frame: FrameCtx) => boolean) | undefined;
+    readonly begin?: ((frame: FrameCtx) => ComputePassDescriptor) | undefined;
+    readonly onBeginError?: ((frame: FrameCtx, cause: unknown) => void) | undefined;
+    encode(context: {
+        readonly pass: RhiComputePassEncoder;
+        readonly frame: FrameCtx;
+        readonly resources: GraphResourceResolver;
+    }): void;
+    readonly after?: ((frame: FrameCtx) => void) | undefined;
+}
+export interface CopyGraphPass<FrameCtx> {
+    readonly accesses: readonly GraphAccess[];
+    readonly executeIf?: ((frame: FrameCtx) => boolean) | undefined;
+    encode(context: {
+        readonly encoder: RhiCommandEncoder;
+        readonly frame: FrameCtx;
+        readonly resources: GraphResourceResolver;
+    }): void;
+}
+export type GraphPass<FrameCtx> = {
+    readonly kind: 'raster';
+    readonly descriptor: RasterGraphPass<FrameCtx>;
+} | {
+    readonly kind: 'compute';
+    readonly descriptor: ComputeGraphPass<FrameCtx>;
+} | {
+    readonly kind: 'copy';
+    readonly descriptor: CopyGraphPass<FrameCtx>;
+};
+export type GraphPassKind = GraphPass<unknown>['kind'];
+export interface GraphAccessInfo {
+    readonly resource: string;
+    readonly usage: GraphBufferAccess | GraphTextureAccess;
+}
+export interface CompiledRenderGraphInfo {
+    readonly passes: readonly {
+        readonly name: string;
+        readonly kind: GraphPassKind;
+        readonly executionIndex: number;
+        readonly accesses: readonly GraphAccessInfo[];
+        readonly dependencies: readonly string[];
+    }[];
+    readonly resources: readonly {
+        readonly label: string;
+        readonly kind: GraphResourceKind;
+        readonly origin: GraphResourceOrigin;
+        readonly firstUse: number | null;
+        readonly lastUse: number | null;
+        readonly derivedUsage: number;
+    }[];
+}
+export interface RenderGraphFrame {
+    readonly encoder: RhiCommandEncoder;
+}
+export interface RenderGraphPassExecution {
+    readonly name: string;
+    readonly kind: GraphPassKind;
+    readonly executionIndex: number;
+}
+export type RenderGraphPassRunner = (pass: RenderGraphPassExecution, encode: () => void) => void;
+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>;
+    inspect(): CompiledRenderGraphInfo;
+    retire(): Promise<Result<void, RenderGraphError>>;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@forgeax/engine-render-graph",
+  "version": "0.1.2",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "RHI-pure typed GPU work graph: resource access declaration, immutable compilation, execution, and retirement.",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@forgeax/engine-rhi": "0.1.2",
+    "@forgeax/engine-types": "0.1.2",
+    "@webgpu/types": "^0.1.71"
+  },
+  "devDependencies": {
+    "@forgeax/engine-rhi-null": "0.1.2"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "render-graph is a compile-time / orchestration layer without canvas; fps reported by consuming runtime apps"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "compile path is not perf-critical; bench focus stays on @forgeax/engine-math and runtime render loop"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "physical-isolation grep gate (check-render-graph-no-runtime-import) is a repo-root script wired into ci.yml lint job, not a per-package gate"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/graph-pass-kind-owner.test-d.ts

@@ -0,0 +1,35 @@
+import { describe, expectTypeOf, it } from 'vitest';
+import type {
+  CompiledRenderGraphInfo,
+  GraphPass,
+  GraphPassKind,
+  RenderGraphPassExecution,
+} from '../index.js';
+
+type GraphPassKindOwner = GraphPass<unknown>['kind'];
+type ExpectedGraphPassKind = 'raster' | 'compute' | 'copy';
+type CompiledPassKind = CompiledRenderGraphInfo['passes'][number]['kind'];
+type ExecutionPassKind = RenderGraphPassExecution['kind'];
+
+describe('render-graph pass kind owner', () => {
+  it('keeps the exact raster, compute, and copy membership', () => {
+    expectTypeOf<GraphPassKindOwner>().toEqualTypeOf<ExpectedGraphPassKind>();
+    expectTypeOf<ExpectedGraphPassKind>().toEqualTypeOf<GraphPassKindOwner>();
+    expectTypeOf<GraphPassKind>().toEqualTypeOf<GraphPassKindOwner>();
+    expectTypeOf<GraphPassKindOwner>().toEqualTypeOf<GraphPassKind>();
+
+    const acceptsPassKind = (kind: GraphPassKindOwner): GraphPassKindOwner => kind;
+    acceptsPassKind('raster');
+    acceptsPassKind('compute');
+    acceptsPassKind('copy');
+    // @ts-expect-error unknown pass kinds remain outside the closed union.
+    acceptsPassKind('pass-kind-not-real');
+  });
+
+  it('keeps compiled and execution views equal to the owner', () => {
+    expectTypeOf<CompiledPassKind>().toEqualTypeOf<GraphPassKindOwner>();
+    expectTypeOf<GraphPassKindOwner>().toEqualTypeOf<CompiledPassKind>();
+    expectTypeOf<ExecutionPassKind>().toEqualTypeOf<GraphPassKindOwner>();
+    expectTypeOf<GraphPassKindOwner>().toEqualTypeOf<ExecutionPassKind>();
+  });
+});

package/src/__tests__/observation-lifetime-state-owner.test-d.ts

@@ -0,0 +1,39 @@
+/// <reference types="node" />
+
+import { readFileSync } from 'node:fs';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { CurrentFrameObservationLease, CurrentFrameObservationLifetime } from '../index.js';
+
+const observationSource = readFileSync(new URL('../observation.ts', import.meta.url), 'utf8');
+
+describe('current-frame observation lifetime state owner', () => {
+  it('keeps lease state bilaterally equal to the lifetime owner', () => {
+    type LifetimeState = CurrentFrameObservationLifetime['state'];
+    type LeaseState = CurrentFrameObservationLease['state'];
+
+    expectTypeOf<LeaseState>().toEqualTypeOf<LifetimeState>();
+    expectTypeOf<LifetimeState>().toEqualTypeOf<LeaseState>();
+
+    const acceptsLifetimeState = (state: LifetimeState): LifetimeState => state;
+    const acceptsLeaseState = (state: LeaseState): LeaseState => state;
+    acceptsLifetimeState('active');
+    acceptsLifetimeState('retired');
+    acceptsLeaseState('active');
+    acceptsLeaseState('retired');
+    // @ts-expect-error unknown observation lifetime states remain outside the closed union.
+    acceptsLifetimeState('pending');
+    // @ts-expect-error unknown lease states remain outside the closed union.
+    acceptsLeaseState('pending');
+  });
+
+  it('keeps the source annotations derived from the lifetime owner', () => {
+    expect(observationSource).toContain(
+      "readonly state: CurrentFrameObservationLifetime['state'];",
+    );
+    expect(observationSource).toContain(
+      "let state: CurrentFrameObservationLifetime['state'] = 'active';",
+    );
+    expect(observationSource.match(/readonly state: 'active' \| 'retired';/g)).toHaveLength(1);
+    expect(observationSource).not.toContain("let state: 'active' | 'retired' = 'active';");
+  });
+});

package/src/__tests__/observation.unit.test.ts

@@ -0,0 +1,103 @@
+import type { Texture } from '@forgeax/engine-rhi';
+import { describe, expect, it } from 'vitest';
+import {
+  type CurrentFrameObservationDescriptor,
+  type CurrentFrameObservationLease,
+  createCurrentFrameObservationLease,
+  RenderGraphError,
+} from '../observation.js';
+
+const COPY_SRC = 0x01;
+const RENDER_ATTACHMENT = 0x10;
+const TEXTURE_BINDING = 0x04;
+
+const texture = {} as Texture;
+
+function descriptor(
+  overrides: Partial<CurrentFrameObservationDescriptor> = {},
+): CurrentFrameObservationDescriptor {
+  return {
+    texture,
+    format: 'rgba16float',
+    size: { width: 32, height: 16 },
+    usage: RENDER_ATTACHMENT | TEXTURE_BINDING | COPY_SRC,
+    frameId: 7,
+    ...overrides,
+  };
+}
+
+function expectError(
+  result: { readonly ok: true } | { readonly ok: false; readonly error: { readonly code: string } },
+  code: string,
+): void {
+  expect(result.ok).toBe(false);
+  if (!result.ok) expect(result.error.code).toBe(code);
+}
+
+describe('current-frame observation lease', () => {
+  it('accepts an opaque texture descriptor with a fresh frame lifetime', () => {
+    const result = createCurrentFrameObservationLease(descriptor(), 7);
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.value.descriptor).toEqual(descriptor());
+    expect(result.value.state).toBe('active');
+    expect(result.value.beginReadback().ok).toBe(true);
+  });
+
+  it('rejects missing or incompatible observation descriptors', () => {
+    expectError(
+      createCurrentFrameObservationLease(descriptor({ format: 'bgra8unorm' }), 7),
+      'observation-invalid-format',
+    );
+    expectError(
+      createCurrentFrameObservationLease(descriptor({ size: { width: 0, height: 16 } }), 7),
+      'observation-invalid-size',
+    );
+    expectError(
+      createCurrentFrameObservationLease(descriptor({ usage: RENDER_ATTACHMENT }), 7),
+      'observation-missing-copy-src',
+    );
+    expectError(
+      createCurrentFrameObservationLease(descriptor({ texture: undefined as never }), 7),
+      'observation-absent',
+    );
+  });
+
+  it('rejects stale frame descriptors before a lease is created', () => {
+    expectError(
+      createCurrentFrameObservationLease(descriptor({ frameId: 6 }), 7),
+      'observation-stale',
+    );
+  });
+
+  it('fails closed after retirement and exposes no graph key or policy', () => {
+    const result = createCurrentFrameObservationLease(descriptor(), 7);
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+
+    const lease: CurrentFrameObservationLease = result.value;
+    lease.retire();
+    expect(lease.state).toBe('retired');
+    expectError(lease.beginReadback(), 'observation-retired');
+    expect('graphKey' in lease).toBe(false);
+    expect('pipelineId' in lease).toBe(false);
+    expect('backendHandle' in lease).toBe(false);
+  });
+
+  it('keeps the graph package isolated from semantic owners', async () => {
+    const source = await import('../observation.js');
+    const sourceText = Object.keys(source).join(' ');
+    expect(sourceText).not.toMatch(/linear-hdr|URP|HDRP|parity/i);
+  });
+
+  it('uses the structured RenderGraphError surface', () => {
+    expect(
+      new RenderGraphError({
+        code: 'observation-stale',
+        expected: 'current frame observation',
+        hint: 'capture the current frame before the producer retires it',
+      }),
+    ).toBeInstanceOf(Error);
+  });
+});