@forgeax/engine-vite-plugin-rhi-debug 0.0.0-dev.8d955ade1c79

package/dist/index.mjs

@@ -0,0 +1,170 @@
+import { createHash, randomUUID } from 'crypto';
+import { writeFile, mkdir, rename, rm, access } from 'fs/promises';
+import { resolve, join } from 'path';
+import { decodeTape } from '@forgeax/engine-rhi-debug';
+
+// src/index.ts
+var RAW_TAPE_ROUTE = "/__forgeax-debug/tape";
+var RHITAPE_MIME = "application/x-forgeax-rhitape";
+var DEFINE_KEY = "import.meta.env.FORGEAX_ENGINE_RHI_DEBUG";
+var RUN_ID_PATTERN = /^[A-Za-z0-9_-]+$/;
+function selectCaptureProvider(providers) {
+  const providerIds = providers.map((provider2) => provider2.id);
+  if (providers.length === 0) {
+    return { ok: false, error: { code: "capture-target-unavailable", providerIds } };
+  }
+  if (providers.length > 1) {
+    return { ok: false, error: { code: "capture-target-ambiguous", providerIds } };
+  }
+  const provider = providers[0];
+  if (provider === void 0) {
+    return { ok: false, error: { code: "capture-target-unavailable", providerIds } };
+  }
+  return { ok: true, value: provider };
+}
+function createRawTapeProvider(options) {
+  const rootDir = resolve(options.rootDir);
+  const write = options.writeFile ?? (async (path, bytes) => {
+    await writeFile(path, bytes);
+  });
+  return {
+    async accept(upload) {
+      if (!RUN_ID_PATTERN.test(upload.runId)) {
+        return {
+          ok: false,
+          error: {
+            code: "capture-run-id-invalid",
+            hint: "runId must contain only ASCII letters, numbers, underscore, or hyphen"
+          }
+        };
+      }
+      if (upload.contentType !== RHITAPE_MIME) {
+        return {
+          ok: false,
+          error: {
+            code: "capture-mime-invalid",
+            hint: `content-type must be exactly ${RHITAPE_MIME}`
+          }
+        };
+      }
+      const decoded = decodeTape(upload.bytes);
+      if (!decoded.ok) {
+        return {
+          ok: false,
+          error: {
+            code: "capture-tape-invalid",
+            hint: decoded.error.hint
+          }
+        };
+      }
+      const digest = `sha256:${createHash("sha256").update(upload.bytes).digest("hex")}`;
+      const debugDir = join(rootDir, ".forgeax-debug");
+      const outDir = join(debugDir, upload.runId);
+      const finalPath = join(outDir, "frame.rhitape");
+      const tempDir = join(debugDir, `.rhitape-${upload.runId}-${randomUUID()}`);
+      const debugDirExisted = await pathExists(debugDir);
+      const outDirExisted = await pathExists(outDir);
+      try {
+        await mkdir(tempDir, { recursive: true });
+        await write(join(tempDir, "frame.rhitape"), upload.bytes);
+        await mkdir(outDir, { recursive: true });
+        await rename(join(tempDir, "frame.rhitape"), finalPath);
+        await rm(tempDir, { recursive: true, force: true });
+      } catch {
+        await rm(tempDir, { recursive: true, force: true });
+        if (!outDirExisted) await rm(outDir, { recursive: true, force: true });
+        if (!debugDirExisted) await rm(debugDir, { recursive: true, force: true });
+        return {
+          ok: false,
+          error: {
+            code: "capture-artifact-write-failed",
+            hint: "the raw tape could not be written atomically; inspect the dev-server filesystem and retry"
+          }
+        };
+      }
+      return { ok: true, value: { kind: "rhi-tape", digest, path: finalPath } };
+    }
+  };
+}
+function sendJson(res, status, payload) {
+  res.statusCode = status;
+  res.setHeader("Content-Type", "application/json");
+  res.end(JSON.stringify(payload));
+}
+async function readRawBody(req) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    const bytes = chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk);
+    chunks.push(bytes);
+    size += bytes.byteLength;
+  }
+  const output = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    output.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return output;
+}
+function contentType(req) {
+  const value = req.headers?.["content-type"];
+  return Array.isArray(value) ? value[0] ?? "" : value ?? "";
+}
+async function pathExists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function vitePluginRhiDebug(options = {}) {
+  return {
+    name: "forgeax:rhi-debug",
+    config(_config, env) {
+      return {
+        define: { [DEFINE_KEY]: JSON.stringify(env.command === "serve" ? "1" : "0") }
+      };
+    },
+    configureServer(server) {
+      const provider = createRawTapeProvider({ rootDir: options.rootDir ?? process.cwd() });
+      server.middlewares.use(async (request, response, next) => {
+        const req = request;
+        const res = response;
+        const url = new URL(req.url ?? "", "http://localhost");
+        if (url.pathname !== RAW_TAPE_ROUTE) {
+          next();
+          return;
+        }
+        if (req.method !== "POST") {
+          res.setHeader("Allow", "POST");
+          sendJson(res, 405, {
+            error: "method-not-allowed",
+            hint: `use POST ${RAW_TAPE_ROUTE}?runId=<id> with raw ${RHITAPE_MIME} bytes`
+          });
+          return;
+        }
+        const runId = url.searchParams.get("runId") ?? "";
+        const bytes = await readRawBody(req);
+        const result = await provider.accept({ runId, contentType: contentType(req), bytes });
+        if (!result.ok) {
+          sendJson(
+            res,
+            result.error.code === "capture-artifact-write-failed" ? 500 : 400,
+            result.error
+          );
+          return;
+        }
+        res.statusCode = 200;
+        res.setHeader("Content-Type", "application/json");
+        res.end(JSON.stringify(result.value));
+      });
+    }
+  };
+}
+var index_default = vitePluginRhiDebug;
+
+export { RAW_TAPE_ROUTE, RHITAPE_MIME, createRawTapeProvider, index_default as default, selectCaptureProvider, vitePluginRhiDebug };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["provider"],"mappings":"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","file":"index.mjs","sourcesContent":["// @forgeax/engine-vite-plugin-rhi-debug -- serve-only raw tape transport.\n//\n// The plugin is a leaf: it validates one encoded v7 tape with the core decoder,\n// persists one `.rhitape` file, and exposes no replay or report owner.\n\nimport { createHash, randomUUID } from 'node:crypto';\nimport { access, mkdir, rename, rm, writeFile } from 'node:fs/promises';\nimport { join, resolve } from 'node:path';\nimport { decodeTape } from '@forgeax/engine-rhi-debug';\nimport type { Plugin, ViteDevServer } from 'vite';\n\nexport const RAW_TAPE_ROUTE = '/__forgeax-debug/tape' as const;\nexport const RHITAPE_MIME = 'application/x-forgeax-rhitape' as const;\n\nconst DEFINE_KEY = 'import.meta.env.FORGEAX_ENGINE_RHI_DEBUG';\nconst RUN_ID_PATTERN = /^[A-Za-z0-9_-]+$/;\n\nexport interface CaptureProvider {\n  readonly id: string;\n}\n\nexport type CaptureProviderError =\n  | { readonly code: 'capture-target-unavailable'; readonly providerIds: readonly string[] }\n  | { readonly code: 'capture-target-ambiguous'; readonly providerIds: readonly string[] };\n\nexport type ViteProviderError =\n  | CaptureProviderError\n  | {\n      readonly code:\n        | 'capture-run-id-invalid'\n        | 'capture-mime-invalid'\n        | 'capture-tape-invalid'\n        | 'capture-artifact-write-failed';\n      readonly hint: string;\n    };\n\nexport interface RawTapeUpload {\n  readonly runId: string;\n  readonly contentType: string;\n  readonly bytes: Uint8Array;\n}\n\nexport interface RawTapeArtifactRef {\n  readonly kind: 'rhi-tape';\n  readonly digest: string;\n  readonly path: string;\n}\n\nexport interface RawTapeProviderOptions {\n  readonly rootDir: string;\n  readonly writeFile?: (path: string, bytes: Uint8Array) => Promise<void>;\n}\n\nexport interface RawTapeProvider {\n  accept(upload: RawTapeUpload): Promise<ProviderResult<RawTapeArtifactRef, ViteProviderError>>;\n}\n\ntype ProviderResult<T, E> =\n  | { readonly ok: true; readonly value: T }\n  | { readonly ok: false; readonly error: E };\n\nexport function selectCaptureProvider(\n  providers: readonly CaptureProvider[],\n): ProviderResult<CaptureProvider, CaptureProviderError> {\n  const providerIds = providers.map((provider) => provider.id);\n  if (providers.length === 0) {\n    return { ok: false, error: { code: 'capture-target-unavailable', providerIds } };\n  }\n  if (providers.length > 1) {\n    return { ok: false, error: { code: 'capture-target-ambiguous', providerIds } };\n  }\n  const provider = providers[0];\n  if (provider === undefined) {\n    return { ok: false, error: { code: 'capture-target-unavailable', providerIds } };\n  }\n  return { ok: true, value: provider };\n}\n\nexport function createRawTapeProvider(options: RawTapeProviderOptions): RawTapeProvider {\n  const rootDir = resolve(options.rootDir);\n  const write =\n    options.writeFile ??\n    (async (path: string, bytes: Uint8Array) => {\n      await writeFile(path, bytes);\n    });\n\n  return {\n    async accept(upload) {\n      if (!RUN_ID_PATTERN.test(upload.runId)) {\n        return {\n          ok: false,\n          error: {\n            code: 'capture-run-id-invalid',\n            hint: 'runId must contain only ASCII letters, numbers, underscore, or hyphen',\n          },\n        };\n      }\n      if (upload.contentType !== RHITAPE_MIME) {\n        return {\n          ok: false,\n          error: {\n            code: 'capture-mime-invalid',\n            hint: `content-type must be exactly ${RHITAPE_MIME}`,\n          },\n        };\n      }\n\n      const decoded = decodeTape(upload.bytes);\n      if (!decoded.ok) {\n        return {\n          ok: false,\n          error: {\n            code: 'capture-tape-invalid',\n            hint: decoded.error.hint,\n          },\n        };\n      }\n\n      const digest = `sha256:${createHash('sha256').update(upload.bytes).digest('hex')}`;\n      const debugDir = join(rootDir, '.forgeax-debug');\n      const outDir = join(debugDir, upload.runId);\n      const finalPath = join(outDir, 'frame.rhitape');\n      const tempDir = join(debugDir, `.rhitape-${upload.runId}-${randomUUID()}`);\n      const debugDirExisted = await pathExists(debugDir);\n      const outDirExisted = await pathExists(outDir);\n\n      try {\n        await mkdir(tempDir, { recursive: true });\n        await write(join(tempDir, 'frame.rhitape'), upload.bytes);\n        await mkdir(outDir, { recursive: true });\n        await rename(join(tempDir, 'frame.rhitape'), finalPath);\n        await rm(tempDir, { recursive: true, force: true });\n      } catch {\n        await rm(tempDir, { recursive: true, force: true });\n        if (!outDirExisted) await rm(outDir, { recursive: true, force: true });\n        if (!debugDirExisted) await rm(debugDir, { recursive: true, force: true });\n        return {\n          ok: false,\n          error: {\n            code: 'capture-artifact-write-failed',\n            hint: 'the raw tape could not be written atomically; inspect the dev-server filesystem and retry',\n          },\n        };\n      }\n\n      return { ok: true, value: { kind: 'rhi-tape', digest, path: finalPath } };\n    },\n  };\n}\n\nexport interface RhiDebugPluginOptions {\n  readonly rootDir?: string;\n}\n\ninterface MiddlewareRequest extends AsyncIterable<Uint8Array> {\n  readonly method?: string;\n  readonly url?: string;\n  readonly headers?: Readonly<Record<string, string | string[] | undefined>>;\n}\n\ninterface MiddlewareResponse {\n  statusCode: number;\n  setHeader(name: string, value: string): void;\n  end(chunk?: string | Uint8Array): void;\n}\n\nfunction sendJson(res: MiddlewareResponse, status: number, payload: unknown): void {\n  res.statusCode = status;\n  res.setHeader('Content-Type', 'application/json');\n  res.end(JSON.stringify(payload));\n}\n\nasync function readRawBody(req: AsyncIterable<Uint8Array>): Promise<Uint8Array> {\n  const chunks: Uint8Array[] = [];\n  let size = 0;\n  for await (const chunk of req) {\n    const bytes = chunk instanceof Uint8Array ? chunk : new Uint8Array(chunk);\n    chunks.push(bytes);\n    size += bytes.byteLength;\n  }\n  const output = new Uint8Array(size);\n  let offset = 0;\n  for (const chunk of chunks) {\n    output.set(chunk, offset);\n    offset += chunk.byteLength;\n  }\n  return output;\n}\n\nfunction contentType(req: MiddlewareRequest): string {\n  const value = req.headers?.['content-type'];\n  return Array.isArray(value) ? (value[0] ?? '') : (value ?? '');\n}\n\nasync function pathExists(path: string): Promise<boolean> {\n  try {\n    await access(path);\n    return true;\n  } catch {\n    return false;\n  }\n}\n\nexport function vitePluginRhiDebug(options: RhiDebugPluginOptions = {}): Plugin {\n  return {\n    name: 'forgeax:rhi-debug',\n\n    config(_config, env) {\n      return {\n        define: { [DEFINE_KEY]: JSON.stringify(env.command === 'serve' ? '1' : '0') },\n      };\n    },\n\n    configureServer(server: ViteDevServer) {\n      const provider = createRawTapeProvider({ rootDir: options.rootDir ?? process.cwd() });\n      server.middlewares.use(async (request, response, next) => {\n        const req = request as MiddlewareRequest;\n        const res = response as unknown as MiddlewareResponse;\n        const url = new URL(req.url ?? '', 'http://localhost');\n        if (url.pathname !== RAW_TAPE_ROUTE) {\n          next();\n          return;\n        }\n        if (req.method !== 'POST') {\n          res.setHeader('Allow', 'POST');\n          sendJson(res, 405, {\n            error: 'method-not-allowed',\n            hint: `use POST ${RAW_TAPE_ROUTE}?runId=<id> with raw ${RHITAPE_MIME} bytes`,\n          });\n          return;\n        }\n\n        const runId = url.searchParams.get('runId') ?? '';\n        const bytes = await readRawBody(req);\n        const result = await provider.accept({ runId, contentType: contentType(req), bytes });\n        if (!result.ok) {\n          sendJson(\n            res,\n            result.error.code === 'capture-artifact-write-failed' ? 500 : 400,\n            result.error,\n          );\n          return;\n        }\n        res.statusCode = 200;\n        res.setHeader('Content-Type', 'application/json');\n        res.end(JSON.stringify(result.value));\n      });\n    },\n  };\n}\n\nexport default vitePluginRhiDebug;\n"]}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@forgeax/engine-vite-plugin-rhi-debug",
+  "version": "0.0.0-dev.8d955ade1c79",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "Vite serve-only raw .rhitape capture provider with strict validation and atomic persistence.",
+  "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"
+  ],
+  "peerDependencies": {
+    "@forgeax/engine-rhi-debug": "0.0.0-dev.8d955ade1c79",
+    "vite": "^7 || ^8"
+  },
+  "devDependencies": {
+    "@forgeax/engine-rhi-debug": "0.0.0-dev.8d955ade1c79",
+    "@forgeax/engine-types": "0.0.0-dev.8d955ade1c79",
+    "@types/node": "^20.14.0",
+    "vite": "8.0.10"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "dev-server-only vite plugin; no runtime canvas or frame loop"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "thin middleware shell validates and persists raw tape bytes; no perf-critical hot path"
+      },
+      "gate": {
+        "enabled": false,
+        "reason": "no standalone binary gate for this package; CI gates are repo-root scripts"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc -b",
+    "test": "vitest run"
+  }
+}

package/src/__tests__/atomic-tape-write.unit.test.ts

@@ -0,0 +1,57 @@
+import { mkdtemp, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { encodeTape } from '@forgeax/engine-rhi-debug';
+import { describe, expect, it } from 'vitest';
+import { createRawTapeProvider, RHITAPE_MIME } from '../index';
+
+async function validTapeBytes(): Promise<Uint8Array> {
+  const encoded = encodeTape({
+    header: { formatVersion: 7, rhiCaps: {}, eventCount: 0, blobCount: 0 },
+    bootstrap: [],
+    events: [],
+    blobs: [],
+  });
+  if (!encoded.ok) throw new Error(encoded.error.hint);
+  return encoded.value;
+}
+
+describe('atomic .rhitape persistence', () => {
+  it('leaves exactly one final artifact and no temporary sibling', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'forgeax-rhitape-atomic-'));
+    try {
+      const provider = createRawTapeProvider({ rootDir });
+      const result = await provider.accept({
+        runId: 'atomic',
+        contentType: RHITAPE_MIME,
+        bytes: await validTapeBytes(),
+      });
+      expect(result.ok).toBe(true);
+      const files = await readdir(join(rootDir, '.forgeax-debug', 'atomic'));
+      expect(files).toEqual(['frame.rhitape']);
+    } finally {
+      await rm(rootDir, { recursive: true, force: true });
+    }
+  });
+
+  it('reports disk failure without leaving final or temporary output', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'forgeax-rhitape-disk-'));
+    try {
+      const provider = createRawTapeProvider({
+        rootDir,
+        writeFile: async () => {
+          throw new Error('injected disk failure');
+        },
+      });
+      const result = await provider.accept({
+        runId: 'disk-failure',
+        contentType: RHITAPE_MIME,
+        bytes: await validTapeBytes(),
+      });
+      expect(result.ok).toBe(false);
+      await expect(readdir(join(rootDir, '.forgeax-debug'))).rejects.toThrow();
+    } finally {
+      await rm(rootDir, { recursive: true, force: true });
+    }
+  });
+});

package/src/__tests__/define.test.ts

@@ -0,0 +1,107 @@
+// config.define injection + prod constant-fold tests (w12).
+//
+// AC-07 / C6: config(cfg) injects "1" for dev serve and "0" for production
+// build. The production literal lets Vite tree-shake the dev-only endpoint and
+// avoids leaving a bare @forgeax/engine-rhi-debug import in preview bundles.
+
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { build, type Plugin } from 'vite';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
+import { vitePluginRhiDebug } from '../index';
+
+// The factory returns a Vite plugin; view it through the Plugin type so the
+// optional config / configureServer hooks are statically known to the test.
+const asPlugin = (): Plugin => vitePluginRhiDebug() as unknown as Plugin;
+
+// ─── config(cfg) hook unit assertion ─────────────────────────────────────────
+
+describe('config(cfg) define injection', () => {
+  it('injects import.meta.env.FORGEAX_ENGINE_RHI_DEBUG = "1" for serve', () => {
+    const plugin = asPlugin();
+    const cfg: { define?: Record<string, string> } = {};
+    // Vite calls config(userConfig, env); the hook mutates/returns define.
+    const hook = typeof plugin.config === 'function' ? plugin.config : plugin.config?.handler;
+    const ret = hook?.call(
+      undefined as never,
+      cfg as never,
+      {
+        command: 'serve',
+        mode: 'development',
+      } as never,
+    );
+    const define = (ret as { define?: Record<string, string> } | undefined)?.define ?? cfg.define;
+    expect(define).toBeDefined();
+    expect(define?.['import.meta.env.FORGEAX_ENGINE_RHI_DEBUG']).toBe(JSON.stringify('1'));
+  });
+
+  it('injects import.meta.env.FORGEAX_ENGINE_RHI_DEBUG = "0" for build', () => {
+    const plugin = asPlugin();
+    const hook = typeof plugin.config === 'function' ? plugin.config : plugin.config?.handler;
+    const ret = hook?.call(
+      undefined as never,
+      {} as never,
+      {
+        command: 'build',
+        mode: 'production',
+      } as never,
+    );
+    const define = (ret as { define?: Record<string, string> } | undefined)?.define;
+    expect(define?.['import.meta.env.FORGEAX_ENGINE_RHI_DEBUG']).toBe(JSON.stringify('0'));
+  });
+});
+
+// ─── vite build constant-fold (enabled vs not) ───────────────────────────────
+
+describe('vite build constant-fold (w12)', () => {
+  let tmpRoot: string;
+
+  beforeEach(async () => {
+    tmpRoot = await mkdtemp(join(tmpdir(), 'forgeax-vprd-define-'));
+    // Entry reads the guard flag and exports it, so the bundler cannot dead-strip
+    // the reference; whether it folds to "1" depends on define injection.
+    await writeFile(
+      join(tmpRoot, 'entry.js'),
+      'export const flag = import.meta.env.FORGEAX_ENGINE_RHI_DEBUG;\n',
+    );
+  });
+
+  afterEach(async () => {
+    await rm(tmpRoot, { recursive: true, force: true });
+  });
+
+  async function buildCode(withPlugin: boolean): Promise<string> {
+    const output = await build({
+      root: tmpRoot,
+      logLevel: 'silent',
+      plugins: withPlugin ? [asPlugin()] : [],
+      build: {
+        write: false,
+        minify: false,
+        lib: {
+          entry: join(tmpRoot, 'entry.js'),
+          formats: ['es'],
+          fileName: 'out',
+        },
+      },
+    });
+    const arr = Array.isArray(output) ? output : [output];
+    const chunks = arr.flatMap((o) => ('output' in o ? o.output : []));
+    return chunks.map((c) => ('code' in c ? c.code : '')).join('\n');
+  }
+
+  it('with plugin: production bundle folds the flag to the literal "0"', async () => {
+    const code = await buildCode(true);
+    // define replaces `import.meta.env.FORGEAX_ENGINE_RHI_DEBUG` with "0".
+    expect(code).toContain('"0"');
+    expect(code).not.toContain('FORGEAX_ENGINE_RHI_DEBUG');
+  });
+
+  it('without plugin: bundle retains no FORGEAX_ENGINE_RHI_DEBUG literal residue', async () => {
+    const code = await buildCode(false);
+    expect(code).not.toContain('FORGEAX_ENGINE_RHI_DEBUG');
+  });
+});

package/src/__tests__/provider-cardinality.unit.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest';
+import { type CaptureProvider, selectCaptureProvider } from '../index';
+
+const provider = (id: string): CaptureProvider => ({ id });
+
+describe('capture provider cardinality', () => {
+  it('fails closed when no provider is available', () => {
+    const result = selectCaptureProvider([]);
+    expect(result).toEqual({
+      ok: false,
+      error: { code: 'capture-target-unavailable', providerIds: [] },
+    });
+  });
+
+  it('returns the only provider without creating a second route', () => {
+    const only = provider('tab-a');
+    expect(selectCaptureProvider([only])).toEqual({ ok: true, value: only });
+  });
+
+  it('fails closed when multiple providers race for one artifact', () => {
+    const result = selectCaptureProvider([provider('tab-a'), provider('tab-b')]);
+    expect(result).toEqual({
+      ok: false,
+      error: { code: 'capture-target-ambiguous', providerIds: ['tab-a', 'tab-b'] },
+    });
+  });
+});

package/src/__tests__/raw-tape-provider.integration.test.ts

@@ -0,0 +1,86 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { decodeTape, encodeTape } from '@forgeax/engine-rhi-debug';
+import { describe, expect, it } from 'vitest';
+import { createRawTapeProvider, RHITAPE_MIME, vitePluginRhiDebug } from '../index';
+
+async function validTapeBytes(): Promise<Uint8Array> {
+  const encoded = encodeTape({
+    header: { formatVersion: 7, rhiCaps: {}, eventCount: 0, blobCount: 0 },
+    bootstrap: [],
+    events: [],
+    blobs: [],
+  });
+  if (!encoded.ok) throw new Error(encoded.error.hint);
+  return encoded.value;
+}
+
+describe('raw .rhitape provider', () => {
+  it('accepts one raw v7 body, validates it, and returns one digest-bearing artifact', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'forgeax-rhitape-provider-'));
+    try {
+      const bytes = await validTapeBytes();
+      const provider = createRawTapeProvider({ rootDir });
+      const result = await provider.accept({
+        runId: 'raw-provider',
+        contentType: RHITAPE_MIME,
+        bytes,
+      });
+
+      expect(result.ok).toBe(true);
+      if (!result.ok) return;
+      expect(result.value).toMatchObject({
+        kind: 'rhi-tape',
+        path: join(rootDir, '.forgeax-debug', 'raw-provider', 'frame.rhitape'),
+      });
+      expect(decodeTape(await readFile(result.value.path))).toMatchObject({ ok: true });
+    } finally {
+      await rm(rootDir, { recursive: true, force: true });
+    }
+  });
+
+  it('rejects non-raw MIME and invalid bytes before writing', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'forgeax-rhitape-invalid-'));
+    try {
+      const provider = createRawTapeProvider({ rootDir });
+      const wrongMime = await provider.accept({
+        runId: 'wrong-mime',
+        contentType: 'application/json',
+        bytes: await validTapeBytes(),
+      });
+      const invalidBytes = await provider.accept({
+        runId: 'invalid-bytes',
+        contentType: RHITAPE_MIME,
+        bytes: new Uint8Array([1, 2, 3]),
+      });
+
+      expect(wrongMime.ok).toBe(false);
+      expect(invalidBytes.ok).toBe(false);
+      await expect(
+        readFile(join(rootDir, '.forgeax-debug', 'wrong-mime', 'frame.rhitape')),
+      ).rejects.toThrow();
+      await expect(
+        readFile(join(rootDir, '.forgeax-debug', 'invalid-bytes', 'frame.rhitape')),
+      ).rejects.toThrow();
+    } finally {
+      await rm(rootDir, { recursive: true, force: true });
+    }
+  });
+
+  it('keeps debug flag enabled only for serve', () => {
+    const plugin = vitePluginRhiDebug();
+    expect(plugin.config).toBeTypeOf('function');
+    if (typeof plugin.config !== 'function') return;
+    expect(
+      plugin.config?.call(undefined as never, {}, { command: 'serve', mode: 'development' }),
+    ).toMatchObject({
+      define: { 'import.meta.env.FORGEAX_ENGINE_RHI_DEBUG': '"1"' },
+    });
+    expect(
+      plugin.config?.call(undefined as never, {}, { command: 'build', mode: 'production' }),
+    ).toMatchObject({
+      define: { 'import.meta.env.FORGEAX_ENGINE_RHI_DEBUG': '"0"' },
+    });
+  });
+});