@forgeax/engine-runtime 0.1.2

package/src/__tests__/post-process-register-roundtrip.dawn.test.ts

@@ -0,0 +1,230 @@
+// post-process-register-roundtrip.dawn.test.ts - feat-20260604-resource-owning
+// -render-graph-and-fullscreen-postpr M3 / F-2 fix-up.
+//
+// PIPE-NEUTRAL: this file exercises fullscreen post-process passes via
+// addFullscreenPass, which bypasses material-pass selection. The URP
+// tag convention (tags: { LightMode: 'Forward' }) is not applicable
+// here — no passes:[] material literal exists in this file.
+//
+// Round-trip dawn integration test for the postProcess.register channel +
+// addFullscreenPass dispatcher (F-2 / F-7 wiring):
+//   (a) register(id, entry) is callable through the public renderer.postProcess
+//       surface (re-runs through createRenderer to a real Renderer instance).
+//   (b) registering the SAME id twice throws PostProcessError with code
+//       'post-process-already-registered' (programmer-error fail-fast).
+//   (c) addFullscreenPass referencing an unregistered id throws PostProcessError
+//       with code 'post-process-not-found' through the dispatcher's lookup +
+//       throw branch (the load-bearing AC-08 path: F-2 verified by exercising
+//       the runtime.lookupPostProcess plumbing on a real Renderer).
+//
+// Distinct from fullscreen-post-process-pass.dawn.test.ts (which exercises the
+// FXAA built-in path via antialias='fxaa' + camera) — this test exercises the
+// AI-user register/lookup channel directly, ensuring an unregistered id never
+// silently no-ops (charter P3) and ensuring the registry survives a real
+// renderer.draw cycle.
+
+import type { RenderPipelineContext } from '@forgeax/engine-render/internal';
+import { addFullscreenPass } from '@forgeax/engine-render/internal';
+import { RenderGraph } from '@forgeax/engine-render-graph';
+import { describe, expect, it } from 'vitest';
+import { createRenderer } from '../createRenderer';
+
+const WIDTH = 256;
+const HEIGHT = 256;
+
+const ENGINE_MANIFEST = await (async () => {
+  const { buildEngineShaderManifest } = await import('@forgeax/engine-vite-plugin-shader');
+  return buildEngineShaderManifest();
+})();
+const ENGINE_MANIFEST_URL = `data:application/json,${encodeURIComponent(
+  JSON.stringify(ENGINE_MANIFEST),
+)}`;
+
+async function setupRenderer(): Promise<Awaited<ReturnType<typeof createRenderer>>> {
+  if (typeof globalThis.navigator?.gpu?.requestAdapter !== 'function') {
+    throw new Error('dawn-node navigator.gpu not injected; vitest.setup-webgpu.ts regressed');
+  }
+  let renderTarget: GPUTexture | undefined;
+  let sharedDevice: GPUDevice | undefined;
+  const original = globalThis.navigator.gpu.requestAdapter.bind(globalThis.navigator.gpu);
+  globalThis.navigator.gpu.requestAdapter = async (opts) => {
+    const a = await original(opts);
+    if (a === null) return a;
+    const od = a.requestDevice.bind(a);
+    a.requestDevice = async (desc) => {
+      const d = await od(desc);
+      if (sharedDevice === undefined) sharedDevice = d;
+      return d;
+    };
+    return a;
+  };
+  const mockCanvas = {
+    width: WIDTH,
+    height: HEIGHT,
+    getContext(kind: string) {
+      if (kind !== 'webgpu') return null;
+      return {
+        configure() {},
+        unconfigure() {},
+        getCurrentTexture(): GPUTexture {
+          if (sharedDevice === undefined)
+            throw new Error('render target requested before device captured');
+          if (renderTarget === undefined) {
+            renderTarget = sharedDevice.createTexture({
+              size: { width: WIDTH, height: HEIGHT, depthOrArrayLayers: 1 },
+              format: 'rgba8unorm',
+              usage: 0x10 | 0x01,
+              viewFormats: ['rgba8unorm-srgb'],
+            });
+          }
+          return renderTarget;
+        },
+      };
+    },
+    addEventListener() {},
+    removeEventListener() {},
+  } as unknown as HTMLCanvasElement;
+  try {
+    const r = await createRenderer(mockCanvas, undefined, {
+      shaderManifestUrl: ENGINE_MANIFEST_URL,
+    });
+    const ready = await r.ready;
+    if (!ready.ok) throw new Error('renderer.ready failed');
+    return r;
+  } finally {
+    globalThis.navigator.gpu.requestAdapter = original;
+  }
+}
+
+describe('feat-20260604 M3 F-2 fix-up: postProcess.register + addFullscreenPass dispatcher', () => {
+  it('renderer.postProcess.register accepts a new id (round-trip success)', async () => {
+    const r = await setupRenderer();
+    // The first register MUST succeed (no throw). entry.source is a placeholder
+    // WGSL string — the dispatcher does not compile it on this path; only the
+    // BGL/sampler/bind-group helpers run on the AI-user execute closure.
+    expect(() =>
+      r.postProcess.register('test::roundtrip-A', {
+        source: 'fn main() {}',
+      }),
+    ).not.toThrow();
+  });
+
+  it('renderer.postProcess.register throws on same-id duplicate (programmer-error fail-fast)', async () => {
+    const r = await setupRenderer();
+    r.postProcess.register('test::roundtrip-B', { source: 'fn main() {}' });
+    let caught: unknown = null;
+    try {
+      r.postProcess.register('test::roundtrip-B', { source: 'fn main() {}' });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught).not.toBeNull();
+    const err = caught as { code?: string; detail?: { id?: string } };
+    expect(err.code).toBe('post-process-already-registered');
+    expect(err.detail?.id).toBe('test::roundtrip-B');
+  });
+
+  it('unregisters a realm-owned entry so a later realm can reuse the id', async () => {
+    const r = await setupRenderer();
+    const unregister = r.postProcess.register('test::realm-owned', { source: 'fn main() {}' });
+    unregister();
+    expect(() =>
+      r.postProcess.register('test::realm-owned', { source: 'fn main() {}' }),
+    ).not.toThrow();
+  });
+
+  it('renderer.postProcess.register throws params-size-mismatch when params.byteSize < 16 (live fail-fast)', async () => {
+    // feat-20260621 AC-A3: the eager params-UBO guard must fire on the REAL
+    // register() path (not just on a hand-constructed PostProcessError). byteSize
+    // below the 16B std140 minimum is a programmer error caught at register time,
+    // before any frame draws.
+    const r = await setupRenderer();
+    let caught: unknown = null;
+    try {
+      r.postProcess.register('test::roundtrip-params-too-small', {
+        source: 'fn main() {}',
+        params: { byteSize: 8, defaultValue: new Uint8Array(8) },
+      });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught, 'register with byteSize < 16 must throw').not.toBeNull();
+    const err = caught as { code?: string; detail?: { byteSize?: number; actualLength?: number } };
+    expect(err.code).toBe('params-size-mismatch');
+    expect(err.detail?.byteSize).toBe(8);
+  });
+
+  it('renderer.postProcess.register throws params-size-mismatch when defaultValue.length !== byteSize (live fail-fast)', async () => {
+    // Same guard, second branch: declared byteSize and the seed defaultValue
+    // disagree — the eager UBO write would corrupt; register() must reject.
+    const r = await setupRenderer();
+    let caught: unknown = null;
+    try {
+      r.postProcess.register('test::roundtrip-params-length-mismatch', {
+        source: 'fn main() {}',
+        params: { byteSize: 16, defaultValue: new Uint8Array(12) },
+      });
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught, 'register with mismatched defaultValue length must throw').not.toBeNull();
+    const err = caught as { code?: string; detail?: { byteSize?: number; actualLength?: number } };
+    expect(err.code).toBe('params-size-mismatch');
+    expect(err.detail?.byteSize).toBe(16);
+    expect(err.detail?.actualLength).toBe(12);
+  });
+
+  it('addFullscreenPass referencing unregistered id throws post-process-not-found via dispatcher', async () => {
+    // The dispatcher's lookup-and-throw branch is the load-bearing AC-08 path.
+    // Build a minimal RenderGraph with a single fullscreen pass referencing an
+    // id that was never registered; running its execute closure must throw a
+    // PostProcessError with code 'post-process-not-found'.
+    //
+    // We synthesise a stub ctx that satisfies the closure's read paths
+    // (runtime.lookupPostProcess returns undefined, ctx.view is non-null).
+    // The dispatcher's only consumed surface on this path is
+    // ctx.runtime.lookupPostProcess; the throw fires before any device call.
+    const r = await setupRenderer();
+    void r;
+
+    const stubCtx = {
+      runtime: {
+        lookupPostProcess: (_id: string) => undefined,
+      },
+      view: {} as unknown,
+    } as unknown as RenderPipelineContext;
+
+    const graph = new RenderGraph<RenderPipelineContext>();
+    graph.addColorTarget('rt', {
+      format: 'rgba8unorm',
+      size: { w: WIDTH, h: HEIGHT },
+    });
+    addFullscreenPass(graph, 'pp', { shader: 'never::registered', color: 'rt' });
+
+    // Reach into the registry to recover the descriptor.execute. listPasses
+    // surfaces only name/reads/writes; the executor lives on the PassEntry
+    // accessible via the private passes registry. The cast is test-internal
+    // (mirrors how render-system-record reaches into the registry to invoke
+    // pass.descriptor.execute on the per-frame topology).
+    const passes = (
+      graph as unknown as {
+        passes: {
+          list(): readonly { name: string; descriptor: { execute?: (c: unknown) => void } }[];
+        };
+      }
+    ).passes.list();
+    const pp = passes.find((p) => p.name === 'pp');
+    expect(pp, 'pass "pp" must be registered').toBeDefined();
+    if (!pp || pp.descriptor.execute === undefined) return;
+    let caught: unknown = null;
+    try {
+      pp.descriptor.execute(stubCtx);
+    } catch (e) {
+      caught = e;
+    }
+    expect(caught, 'addFullscreenPass with unregistered id must throw').not.toBeNull();
+    const err = caught as { code?: string; detail?: { id?: string } };
+    expect(err.code).toBe('post-process-not-found');
+    expect(err.detail?.id).toBe('never::registered');
+  });
+});

package/src/__tests__/postprocess-camera-consistency.test.ts

@@ -0,0 +1,378 @@
+// m2-t4: postProcessParams <-> cameras same-origin constraint test (TDD red).
+//
+// Test R-6 risk mitigation: the merged frame's postProcessParams and cameras
+// must come from the same (owner) world, because the built-in tonemap provider
+// reads cameras[0] (render-system-extract.ts:3341-3351) and the two must be
+// atomically consistent.
+//
+// Construct dual-world scenario:
+//   - owner world A has postProcessParams + camera
+//   - world B has different postProcessParams + camera
+// Assert after merge: postProcessParams and cameras both come from owner A.
+// Non-owner B's postProcessParams are discarded.
+//
+// Anchors:
+//   plan-tasks.json m2-t4
+//   plan-strategy D-3 (owner snapshot holistic selection)
+//   research Finding 3 / R-6
+//   requirements AC-05/06
+
+import { World } from '@forgeax/engine-ecs';
+import type { CameraSnapshot, ExtractedFrame } from '@forgeax/engine-render/internal';
+import {
+  Camera,
+  extractFrame,
+  PostProcessParams,
+  prepareExtractContext,
+} from '@forgeax/engine-render/internal';
+import { Transform } from '@forgeax/engine-scene';
+import { describe, expect, it } from 'vitest';
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function identityTransform(): {
+  pos: [number, number, number];
+  quat: [number, number, number, number];
+  scale: [number, number, number];
+} {
+  return {
+    pos: [0, 0, 0],
+    quat: [0, 0, 0, 1],
+    scale: [1, 1, 1],
+  };
+}
+
+/**
+ * Simulate the D-3 merge that extractFrames will implement, specifically
+ * for postProcessParams and cameras same-origin verification.
+ *
+ * Per D-3: cameras + postProcessParams are taken from the owner world's
+ * frame holistically. Non-owner's same-type items are discarded.
+ */
+function simulateMergeWithOwnerSelection(
+  frames: ExtractedFrame[],
+  ownerIndex: number,
+): {
+  cameras: CameraSnapshot[];
+  postProcessParams: ReadonlyMap<string, Uint8Array>;
+  singleWorldCameras: CameraSnapshot[][];
+  singleWorldPostProcess: ReadonlyMap<string, Uint8Array>[];
+} {
+  // biome-ignore lint/style/noNonNullAssertion: ownerIndex is validated, frames is dense
+  const ownerFrame = frames[ownerIndex]!;
+
+  // D-3: cameras only from owner world
+  const cameras = [...ownerFrame.cameras];
+
+  // D-3: postProcessParams only from owner world
+  const postProcessParams = new Map(ownerFrame.postProcessParams);
+
+  return {
+    cameras,
+    postProcessParams,
+    singleWorldCameras: frames.map((f) => f.cameras),
+    singleWorldPostProcess: frames.map((f) => f.postProcessParams),
+  };
+}
+
+// ── Tests ───────────────────────────────────────────────────────────────────
+
+describe('postProcessParams <-> cameras same-origin constraint (m2-t4, R-6)', () => {
+  // ── R-6: postProcessParams and cameras from same world ─────────────────────
+
+  it('R-6: merged postProcessParams and cameras both come from owner world', () => {
+    const worldA = new World();
+    worldA
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: Camera,
+          data: {
+            fov: Math.PI / 4,
+            near: 0.1,
+            far: 100,
+            aspect: 1,
+            clearColor: [0.1, 0.2, 0.3, 1],
+          },
+        },
+      )
+      .unwrap();
+    worldA
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: PostProcessParams,
+          data: {
+            shader: 'forgeax::owner-effect',
+            data: new Uint8Array([1, 2, 3]),
+          },
+        },
+      )
+      .unwrap();
+
+    const worldB = new World();
+    worldB
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: Camera,
+          data: {
+            fov: Math.PI / 3,
+            near: 0.5,
+            far: 50,
+            aspect: 2,
+            clearColor: [0.9, 0.8, 0.7, 1],
+          },
+        },
+      )
+      .unwrap();
+    worldB
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: PostProcessParams,
+          data: {
+            shader: 'forgeax::non-owner-effect',
+            data: new Uint8Array([9, 9, 9]),
+          },
+        },
+      )
+      .unwrap();
+
+    const frameA = extractFrame(worldA as World, prepareExtractContext(worldA as World));
+    const frameB = extractFrame(worldB as World, prepareExtractContext(worldB as World));
+
+    // Verify both worlds have their own cameras and postProcessParams
+    expect(frameA.cameras.length).toBeGreaterThanOrEqual(1);
+    expect(frameB.cameras.length).toBeGreaterThanOrEqual(1);
+    expect(frameA.postProcessParams.has('forgeax::owner-effect')).toBe(true);
+    expect(frameB.postProcessParams.has('forgeax::non-owner-effect')).toBe(true);
+
+    // owner=0 (worldA)
+    const merged = simulateMergeWithOwnerSelection([frameA, frameB], 0);
+
+    // Cameras come from owner world A
+    expect(merged.cameras.length).toBe(frameA.cameras.length);
+    // postProcessParams come from owner world A
+    expect(merged.postProcessParams.has('forgeax::owner-effect')).toBe(true);
+    // Non-owner's postProcessParams are discarded
+    expect(merged.postProcessParams.has('forgeax::non-owner-effect')).toBe(false);
+
+    // owner=1 (worldB)
+    const merged2 = simulateMergeWithOwnerSelection([frameA, frameB], 1);
+
+    // Cameras come from owner world B
+    expect(merged2.cameras.length).toBe(frameB.cameras.length);
+    // postProcessParams come from owner world B
+    expect(merged2.postProcessParams.has('forgeax::non-owner-effect')).toBe(true);
+    expect(merged2.postProcessParams.has('forgeax::owner-effect')).toBe(false);
+  });
+
+  // ── Non-owner postProcessParams discarded ──────────────────────────────────
+
+  it('R-6: non-owner postProcessParams are discarded, not merged', () => {
+    const worldA = new World();
+    worldA
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        { component: Camera, data: { fov: Math.PI / 4, near: 0.1, far: 100, aspect: 1 } },
+      )
+      .unwrap();
+    worldA
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: PostProcessParams,
+          data: {
+            shader: 'forgeax::effect-a',
+            data: new Uint8Array([1]),
+          },
+        },
+      )
+      .unwrap();
+    worldA
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: PostProcessParams,
+          data: {
+            shader: 'forgeax::effect-b',
+            data: new Uint8Array([2]),
+          },
+        },
+      )
+      .unwrap();
+
+    const worldB = new World();
+    worldB
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: PostProcessParams,
+          data: {
+            shader: 'forgeax::effect-c',
+            data: new Uint8Array([3]),
+          },
+        },
+      )
+      .unwrap();
+
+    const frameA = extractFrame(worldA as World, prepareExtractContext(worldA as World));
+    const frameB = extractFrame(worldB as World, prepareExtractContext(worldB as World));
+
+    const merged = simulateMergeWithOwnerSelection([frameA, frameB], 0);
+
+    // Owner's params are present
+    expect(merged.postProcessParams.has('forgeax::effect-a')).toBe(true);
+    expect(merged.postProcessParams.has('forgeax::effect-b')).toBe(true);
+    // Non-owner's params are discarded
+    expect(merged.postProcessParams.has('forgeax::effect-c')).toBe(false);
+  });
+
+  // ── Empty world postProcessParams ──────────────────────────────────────────
+
+  it('R-6: when owner world has no user PostProcessParams, only engine-injected tonemap is present', () => {
+    const worldA = new World();
+    worldA
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        { component: Camera, data: { fov: Math.PI / 4, near: 0.1, far: 100, aspect: 1 } },
+      )
+      .unwrap();
+
+    const worldB = new World();
+    worldB
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: PostProcessParams,
+          data: {
+            shader: 'forgeax::effect-b',
+            data: new Uint8Array([2]),
+          },
+        },
+      )
+      .unwrap();
+
+    const frameA = extractFrame(worldA as World, prepareExtractContext(worldA as World));
+    const frameB = extractFrame(worldB as World, prepareExtractContext(worldB as World));
+
+    // owner=0: worldA has no user PostProcessParams, but has a camera
+    // so engine injects forgeax::tonemap
+    const merged = simulateMergeWithOwnerSelection([frameA, frameB], 0);
+
+    // Non-owner's user-defined postProcessParams are NOT carried over
+    expect(merged.postProcessParams.has('forgeax::effect-b')).toBe(false);
+    // But owner's engine-injected forgeax::tonemap is present
+    // (camera exists, so engine provides it)
+    const ownerHasTonemap = frameA.postProcessParams.has('forgeax::tonemap');
+    expect(merged.postProcessParams.has('forgeax::tonemap')).toBe(ownerHasTonemap);
+  });
+
+  // ── Same-origin: cameras[0] exists in the same world as postProcessParams ──
+
+  it('R-6: tonemap hidden dependency safety — cameras[0] and postProcessParams from same owner', () => {
+    // The built-in tonemap provider reads cameras[0] (render-system-extract.ts:3341-3351).
+    // If postProcessParams came from owner but cameras came from non-owner,
+    // the tonemap would read the wrong camera's exposure/tonemap/whitePoint.
+    // This test verifies the merge contract guarantees they are same-origin.
+
+    const worldA = new World();
+    worldA
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: Camera,
+          data: {
+            fov: Math.PI / 4,
+            near: 0.1,
+            far: 100,
+            aspect: 1,
+            tonemap: 1, // 'reinhard'
+            exposure: 1.5,
+            whitePoint: 3.0,
+          },
+        },
+      )
+      .unwrap();
+    worldA
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: PostProcessParams,
+          data: {
+            shader: 'forgeax::custom-effect',
+            data: new Uint8Array([1, 2, 3]),
+          },
+        },
+      )
+      .unwrap();
+
+    const worldB = new World();
+    worldB
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: Camera,
+          data: {
+            fov: Math.PI / 3,
+            near: 0.5,
+            far: 50,
+            aspect: 2,
+            tonemap: 0, // 'none'
+            exposure: 0.5,
+            whitePoint: 1.0,
+          },
+        },
+      )
+      .unwrap();
+    worldB
+      .spawn(
+        { component: Transform, data: identityTransform() },
+        {
+          component: PostProcessParams,
+          data: {
+            shader: 'forgeax::other-effect',
+            data: new Uint8Array([9, 9, 9]),
+          },
+        },
+      )
+      .unwrap();
+
+    const frameA = extractFrame(worldA as World, prepareExtractContext(worldA as World));
+    const frameB = extractFrame(worldB as World, prepareExtractContext(worldB as World));
+
+    const merged = simulateMergeWithOwnerSelection([frameA, frameB], 0);
+
+    // postProcessParams and cameras[0] both come from owner worldA
+    expect(merged.cameras.length).toBeGreaterThanOrEqual(1);
+    expect(merged.cameras[0]?.exposure).toBe(1.5);
+    expect(merged.cameras[0]?.whitePoint).toBe(3.0);
+
+    // Owner's user-defined postProcessParams are carried over
+    expect(merged.postProcessParams.has('forgeax::custom-effect')).toBe(true);
+    // Non-owner's user-defined postProcessParams are discarded
+    expect(merged.postProcessParams.has('forgeax::other-effect')).toBe(false);
+
+    // When owner=1 (worldB), cameras[0] has different values
+    const merged2 = simulateMergeWithOwnerSelection([frameA, frameB], 1);
+    expect(merged2.cameras[0]?.exposure).toBe(0.5);
+    expect(merged2.cameras[0]?.whitePoint).toBe(1.0);
+
+    // Owner=1's user-defined postProcessParams are carried over
+    expect(merged2.postProcessParams.has('forgeax::other-effect')).toBe(true);
+    // Non-owner's user-defined postProcessParams are discarded
+    expect(merged2.postProcessParams.has('forgeax::custom-effect')).toBe(false);
+
+    // Both frames have engine-injected forgeax::tonemap (because both have cameras).
+    // When owner=0, the forgeax::tonemap comes from worldA's camera context.
+    // When owner=1, it comes from worldB's camera context.
+    // Both are present because each owner has a camera.
+    expect(merged.postProcessParams.has('forgeax::tonemap')).toBe(
+      frameA.postProcessParams.has('forgeax::tonemap'),
+    );
+    expect(merged2.postProcessParams.has('forgeax::tonemap')).toBe(
+      frameB.postProcessParams.has('forgeax::tonemap'),
+    );
+  });
+});

package/src/__tests__/profiler-assembly.integration.test.ts

@@ -0,0 +1,74 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { createProfiler } from '@forgeax/engine-profiler';
+import type { RendererOptions } from '@forgeax/engine-render/internal';
+import { describe, expect, it } from 'vitest';
+
+describe('runtime profiler assembly', () => {
+  it('accepts the host profiler capability without creating a second owner', () => {
+    const profiler = createProfiler();
+    const options = { profiler } satisfies RendererOptions;
+
+    expect(options.profiler).toBe(profiler);
+    expect(profiler.activeSession()).toBeUndefined();
+  });
+
+  it('forwards the explicit capability and keeps runtime free of Remote and CLI ownership', () => {
+    const source = readFileSync(
+      fileURLToPath(new URL('../createRenderer.ts', import.meta.url)),
+      'utf8',
+    );
+
+    expect(source).toContain('profiler');
+    expect(source).not.toContain('@forgeax/engine-remote');
+    expect(source).not.toContain('phaseCatalog');
+    expect(source).not.toContain('createProfiler');
+  });
+
+  it('preserves capture completeness across stop and overflow boundaries', () => {
+    const stopped = createProfiler();
+    const stoppedSession = stopped.startCapture({ frameLimit: 2, eventLimit: 8 });
+    expect(stoppedSession.ok).toBe(true);
+    if (!stoppedSession.ok) return;
+    expect(stoppedSession.value.beginFrame(1).ok).toBe(true);
+    expect(stoppedSession.value.endFrame().ok).toBe(true);
+    const partial = stoppedSession.value.finish();
+    expect(partial.ok).toBe(true);
+    if (partial.ok) expect(partial.value.completeness.status).toBe('partial');
+
+    const overflow = createProfiler({ phaseCatalog: { app: [], render: ['record'] } });
+    const overflowSession = overflow.startCapture({ frameLimit: 2, eventLimit: 1 });
+    expect(overflowSession.ok).toBe(true);
+    if (!overflowSession.ok) return;
+    for (const frameId of [1, 2]) {
+      expect(overflowSession.value.beginFrame(frameId).ok).toBe(true);
+      expect(
+        overflowSession.value.recordSkip({ source: 'render', phase: 'record', reason: 'no-render' })
+          .ok,
+      ).toBe(true);
+      expect(overflowSession.value.endFrame().ok).toBe(true);
+    }
+    const artifact = overflowSession.value.finish();
+    expect(artifact.ok).toBe(true);
+    if (artifact.ok) expect(artifact.value.completeness.status).toBe('overflow');
+  });
+
+  it('isolates sink Result.err and thrown failures without losing latest capture', () => {
+    for (const sink of [
+      { write: () => ({ ok: false as const, error: { code: 'sink-rejected' } }) },
+      {
+        write: () => {
+          throw new Error('sink-threw');
+        },
+      },
+    ]) {
+      const profiler = createProfiler({ sink });
+      const session = profiler.startCapture({ frameLimit: 1, eventLimit: 4 });
+      expect(session.ok).toBe(true);
+      if (!session.ok) continue;
+      const result = session.value.finish();
+      expect(result.ok).toBe(false);
+      expect(profiler.latestCapture()).toBeDefined();
+    }
+  });
+});