@alwaysmeticulous/backend-recorder-workerd 2.327.0 → 2.329.0

package/README.md

@@ -155,8 +155,44 @@ Replay is **hermetic**: a call the recording does not cover fails with a `[backe
 await fetch(url, { headers: { "meticulous-passthrough": "true" } });
 ```
 
+While serving a replay, the shim prefixes request-scoped `console.debug`, `console.log`,
+`console.info`, `console.warn`, `console.error`, and `console.trace` output with the active replay
+ID. Each request reads its own ID from `AsyncLocalStorage`, so logs stay correctly attributed when
+one Worker isolate serves concurrent replays. Startup and other work outside a replay request stays
+untagged.
+
 Calls through bindings and KV namespaces are not served from the recording (see Limitations) and are never failed — they always reach the real binding.
 
+## Code coverage
+
+Meticulous can report which of your server lines each replayed session executed. Workerd exposes no usable V8 coverage — its inspector never dispatches `Profiler.enable`, so `Profiler.startPreciseCoverage` is unreachable, and the one coverage call it does forward reports binary counts that never reset, which cannot be split per request. So the lines are marked at build time instead.
+
+Add the plugin to the build you **upload for testing**, not the one you deploy:
+
+```ts
+import { defineConfig } from "vite";
+import { meticulousCoverage } from "@alwaysmeticulous/backend-recorder-workerd/vite";
+
+export default defineConfig({
+  plugins: [meticulousCoverage()],
+});
+```
+
+Then replays report coverage automatically — the wrapper posts the lines each request ran to the Meticulous replay sidecar, which attributes them to that session.
+
+- Only **server** modules are instrumented; the client build is untouched unless you pass `includeClient: true`.
+- `node_modules` and virtual modules are always skipped. `exclude: [/pattern/]` skips more.
+- The instrumented bundle is safe to run with coverage off: every marker is a no-op when nothing is collecting, so the same image still works for ordinary replays and for local development.
+- A module the plugin cannot parse is passed through unchanged. Coverage is never worth failing your build for.
+- Some lines are deliberately not marked, because marking them would mean rewriting code rather than adding to it: statements at module top level (they run at isolate startup, outside any request), class `static` blocks, the body of a braceless single statement such as `if (x) return;`, and the condition of an `else if` (only the first `if` of a chain gets a marker, though every branch body still gets its own). Those lines therefore read as uncovered even in a run that executed them.
+
+Reported line numbers are lines in your source, not in the bundle. The plugin runs after your build's TypeScript/JSX pass, which re-prints each module and drops comments and blank lines — so it resolves every line back through that pass's source map. Two consequences worth knowing:
+
+- A module whose source map your build does not produce is still instrumented, but its lines are reported as the build printed them. The plugin says how many modules this affected at the end of the build.
+- A module whose source map covers some other file is skipped entirely rather than reported against the wrong lines.
+
+Because each function re-reads the current request's sink, a callback that outlives the request that created it is credited to the request that actually runs it, not the one that built it.
+
 ## Limitations
 
 - Streamed responses are captured truncated: the inbound request is reported once the handler returns, which for a streamed response is before the stream ends, and outbound bodies cap at 256 KB. An app whose main endpoints are SSE will not record them faithfully.

package/dist/context.js

@@ -1,5 +1,5 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="da83b02f-d7b4-508b-997d-3fc67e266c80")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="fd65e097-c18e-51ca-8f2b-59427a88d125")}catch(e){}}();
 import { transportOrigin } from "./sidecar-transport.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/context.ts
@@ -10,4 +10,4 @@ const sidecarOriginOf = (ctx) => ctx.mode === "replay" ? ctx.sidecarUrl : transp
 export { requestCaptureContext, sidecarOriginOf };
 
 //# sourceMappingURL=context.js.map
-//# debugId=da83b02f-d7b4-508b-997d-3fc67e266c80
+//# debugId=fd65e097-c18e-51ca-8f2b-59427a88d125

package/dist/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sources":["../src/context.ts"],"sourcesContent":["import { AsyncLocalStorage } from \"node:async_hooks\";\nimport type { CaptureBuffer } from \"./capture-buffer\";\nimport { type SidecarTransport, transportOrigin } from \"./sidecar-transport\";\n\n/**\n * Per-inbound-request context, entered by the withMeticulous wrapper and read by the fetch\n * patch. Requires the `nodejs_als` (or `nodejs_compat`) compatibility flag in the worker's\n * wrangler configuration.\n */\ninterface BaseRequestContext {\n  requestId: string;\n  /** The inbound request's ctx.waitUntil, for post-response capture work. */\n  waitUntil: (promise: Promise<unknown>) => void;\n}\n\n/** Recording: capture events are reported to the sidecar, which stays out of the request path. */\nexport interface RequestCaptureContext extends BaseRequestContext {\n  mode: \"record\";\n  frontendSessionId: string | undefined;\n  /**\n   * Set only when we minted {@link frontendSessionId} ourselves for a document navigation the\n   * browser could not tag, rather than reading it off the request. Recorded on the inbound\n   * event so ingestion can tell an id the page may never have adopted from one it sent us.\n   * See provisional-session-id.ts.\n   */\n  sessionIdOrigin?: \"backend\";\n  transport: SidecarTransport;\n  /** Batches this request's events into one report. */\n  buffer: CaptureBuffer;\n  /**\n   * Trace this request's spans belong to, and the id of its SERVER span. Minted here rather than\n   * by the sidecar so span assembly needs no cross-batch memory — see `CorrelatedEvent`.\n   */\n  traceId: string;\n  serverSpanId: string;\n}\n\n/**\n * Replaying: outbound calls are looked up against the sidecar's mock store before they leave the\n * worker.\n *\n * Both ids are required here, unlike recording. Mocks are indexed by session and their\n * consume-once state is isolated by replay, so omitting either would make deterministic\n * lookup impossible. Making both non-optional keeps that state unrepresentable.\n *\n * Replay is URL-only, deliberately: the sidecar URL arrives on a request header the replay runner\n * injects, validated down to a loopback / docker-gateway / private-network origin. There is no\n * binding transport here because a replay sidecar is a Node process holding the mock store, never\n * a Worker.\n */\nexport interface RequestReplayContext extends BaseRequestContext {\n  mode: \"replay\";\n  frontendSessionId: string;\n  replayId: string;\n  /** Normalized origin of the sidecar, e.g. \"http://127.0.0.1:9670\". No trailing slash. */\n  sidecarUrl: string;\n  /**\n   * Instant to freeze the worker's clock at while serving this session, or undefined to leave the\n   * real clock alone.\n   */\n  clockAnchorMs: number | undefined;\n}\n\nexport type RequestContext = RequestCaptureContext | RequestReplayContext;\n\nexport const requestCaptureContext = new AsyncLocalStorage<RequestContext>();\n\n/** The origin the shim's own sidecar traffic goes to, for the self-capture guards. */\nexport const sidecarOriginOf = (ctx: RequestContext): string =>\n  ctx.mode === \"replay\" ? ctx.sidecarUrl : transportOrigin(ctx.transport);\n"],"names":[],"mappings":";;;;;AAiEA,MAAa,wBAAwB,IAAI,mBAAmC;;AAG5E,MAAa,mBAAmB,QAC9B,IAAI,SAAS,WAAW,IAAI,aAAa,gBAAgB,IAAI,UAAU","debugId":"da83b02f-d7b4-508b-997d-3fc67e266c80"}
+{"version":3,"file":"context.js","sources":["../src/context.ts"],"sourcesContent":["import { AsyncLocalStorage } from \"node:async_hooks\";\nimport type { CaptureBuffer } from \"./capture-buffer\";\nimport { type SidecarTransport, transportOrigin } from \"./sidecar-transport\";\n\n/**\n * Per-inbound-request context, entered by the withMeticulous wrapper and read by the fetch\n * patch. Requires the `nodejs_als` (or `nodejs_compat`) compatibility flag in the worker's\n * wrangler configuration.\n */\ninterface BaseRequestContext {\n  requestId: string;\n  /** The inbound request's ctx.waitUntil, for post-response capture work. */\n  waitUntil: (promise: Promise<unknown>) => void;\n  /**\n   * Per-request line-coverage sink, indexed by the global line id the build\n   * plugin assigned. Present only when the bundle is instrumented and the\n   * request is being replayed.\n   *\n   * Lives here rather than in a module-scope global because workerd interleaves\n   * concurrent requests in one isolate — a shared sink would merge sessions'\n   * coverage together.\n   */\n  coverage?: Uint8Array;\n}\n\n/** Recording: capture events are reported to the sidecar, which stays out of the request path. */\nexport interface RequestCaptureContext extends BaseRequestContext {\n  mode: \"record\";\n  frontendSessionId: string | undefined;\n  /**\n   * Set only when we minted {@link frontendSessionId} ourselves for a document navigation the\n   * browser could not tag, rather than reading it off the request. Recorded on the inbound\n   * event so ingestion can tell an id the page may never have adopted from one it sent us.\n   * See provisional-session-id.ts.\n   */\n  sessionIdOrigin?: \"backend\";\n  transport: SidecarTransport;\n  /** Batches this request's events into one report. */\n  buffer: CaptureBuffer;\n  /**\n   * Trace this request's spans belong to, and the id of its SERVER span. Minted here rather than\n   * by the sidecar so span assembly needs no cross-batch memory — see `CorrelatedEvent`.\n   */\n  traceId: string;\n  serverSpanId: string;\n}\n\n/**\n * Replaying: outbound calls are looked up against the sidecar's mock store before they leave the\n * worker.\n *\n * Both ids are required here, unlike recording. Mocks are indexed by session and their\n * consume-once state is isolated by replay, so omitting either would make deterministic\n * lookup impossible. Making both non-optional keeps that state unrepresentable.\n *\n * Replay is URL-only, deliberately: the sidecar URL arrives on a request header the replay runner\n * injects, validated down to a loopback / docker-gateway / private-network origin. There is no\n * binding transport here because a replay sidecar is a Node process holding the mock store, never\n * a Worker.\n */\nexport interface RequestReplayContext extends BaseRequestContext {\n  mode: \"replay\";\n  frontendSessionId: string;\n  replayId: string;\n  /** Normalized origin of the sidecar, e.g. \"http://127.0.0.1:9670\". No trailing slash. */\n  sidecarUrl: string;\n  /**\n   * Instant to freeze the worker's clock at while serving this session, or undefined to leave the\n   * real clock alone.\n   */\n  clockAnchorMs: number | undefined;\n}\n\nexport type RequestContext = RequestCaptureContext | RequestReplayContext;\n\nexport const requestCaptureContext = new AsyncLocalStorage<RequestContext>();\n\n/** The origin the shim's own sidecar traffic goes to, for the self-capture guards. */\nexport const sidecarOriginOf = (ctx: RequestContext): string =>\n  ctx.mode === \"replay\" ? ctx.sidecarUrl : transportOrigin(ctx.transport);\n"],"names":[],"mappings":";;;;;AA2EA,MAAa,wBAAwB,IAAI,mBAAmC;;AAG5E,MAAa,mBAAmB,QAC9B,IAAI,SAAS,WAAW,IAAI,aAAa,gBAAgB,IAAI,UAAU","debugId":"fd65e097-c18e-51ca-8f2b-59427a88d125"}

package/dist/coverage/coverage.types.d.ts

@@ -0,0 +1,32 @@
+//#region src/coverage/coverage.types.d.ts
+/**
+ * Build-time line coverage contract, shared by the Vite plugin (which produces
+ * the ids), the in-worker runtime (which reports hits against them) and the
+ * sidecar (which turns hits back into file/line ranges).
+ */
+/** One instrumented source file's slice of the global id space. */
+interface CoverageMapFile {
+  /** Source path as the build saw it, project-root-relative where possible. */
+  path: string;
+  /** First global id assigned to this file. */
+  firstId: number;
+  /**
+   * Inclusive 1-based line ranges, flattened as `[s1, e1, s2, e2, ...]` — the
+   * range at pair index `i` belongs to global id `firstId + i`. Flat rather
+   * than nested because this ships inside the customer's bundle, and it matches
+   * the `[start, end]` flattening the V8 chunk format already uses.
+   *
+   * A range covers only the lines the marked statement occupies itself: nested
+   * statements and function bodies carry their own ids, so an enclosing `if`
+   * never credits its untaken branch.
+   */
+  lineRanges: number[];
+}
+interface CoverageMap {
+  /** Size of the global id space, and therefore of a request's sink. */
+  totalIds: number;
+  files: CoverageMapFile[];
+}
+//#endregion
+export { CoverageMap, CoverageMapFile };
+//# sourceMappingURL=coverage.types.d.ts.map

package/dist/coverage/replay-coverage.js

@@ -0,0 +1,84 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="7dccd8d2-bdd2-5af1-ab64-d5b05a22f58e")}catch(e){}}();
+import { requestCaptureContext } from "../context.js";
+import { warnOnce } from "../log.js";
+import { getOriginalFetch } from "../original-fetch.js";
+import { postCoverageReport } from "../sidecar-client.js";
+import { collectHitIds, createCoverageSink, getUnreportedCoverageFiles, markCoverageFilesReported } from "./runtime.js";
+//#region src/coverage/replay-coverage.ts
+/**
+* The replay-mode half of line coverage: giving a request a sink, and reporting
+* what it marked. The marking itself is `runtime.ts`, which the instrumented
+* bundle calls directly.
+*/
+/**
+* Whether the sidecar has told us it will never take coverage (404 on the route: an older
+* sidecar, or one started without coverage enabled). Latched per isolate so a replay against
+* such a sidecar stops allocating sinks and serialising hits after the first report.
+*/
+let coverageDisabled = false;
+/**
+* Runs the handler with a per-request coverage sink, reporting what it marked once the response
+* exists.
+*
+* The sink is per-request rather than per-isolate because workerd interleaves concurrent
+* requests, and every replayed request belongs to a different session — a shared sink would
+* merge their coverage. Reporting goes through `waitUntil` so serialising the hits never delays
+* the response, and every failure path leaves the response untouched: coverage is strictly
+* best-effort.
+*/
+const runReplayWithCoverage = async (replayContext, invokeHandler) => {
+	if (coverageDisabled) return requestCaptureContext.run(replayContext, invokeHandler);
+	let sink;
+	try {
+		sink = createCoverageSink();
+	} catch (error) {
+		warnOnce("coverage-sink", "Could not allocate a coverage sink.", error);
+	}
+	if (sink === void 0) return requestCaptureContext.run(replayContext, invokeHandler);
+	const contextWithCoverage = {
+		...replayContext,
+		coverage: sink
+	};
+	try {
+		return await requestCaptureContext.run(contextWithCoverage, invokeHandler);
+	} finally {
+		reportCoverage(contextWithCoverage);
+	}
+};
+/**
+* Sends the hits, plus any id→line map the sidecar has not acknowledged yet.
+*
+* The map goes out incrementally rather than once per isolate because a
+* code-split app registers a module only when its chunk is first imported: a
+* route's server module usually registers on the request that first calls it,
+* after earlier requests have already reported. Without the delta its hits would
+* arrive against ids no file describes, and be dropped by the post-process.
+*/
+const reportCoverage = (context) => {
+	try {
+		const sink = context.coverage;
+		if (sink === void 0) return;
+		const hitIds = collectHitIds(sink);
+		const files = getUnreportedCoverageFiles();
+		if (hitIds.length === 0 && files.length === 0) return;
+		context.waitUntil(postCoverageReport(getOriginalFetch(), context.sidecarUrl, {
+			frontendSessionId: context.frontendSessionId,
+			hitIds,
+			...files.length > 0 ? { files } : {}
+		}).then((outcome) => {
+			if (outcome === "unsupported") {
+				coverageDisabled = true;
+				return;
+			}
+			if (outcome === "accepted") markCoverageFilesReported(files);
+		}));
+	} catch (error) {
+		warnOnce("coverage-report", "Failed to report line coverage.", error);
+	}
+};
+//#endregion
+export { runReplayWithCoverage };
+
+//# sourceMappingURL=replay-coverage.js.map
+//# debugId=7dccd8d2-bdd2-5af1-ab64-d5b05a22f58e

package/dist/coverage/replay-coverage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-coverage.js","sources":["../../src/coverage/replay-coverage.ts"],"sourcesContent":["import { type RequestReplayContext, requestCaptureContext } from \"../context\";\nimport { warnOnce } from \"../log\";\nimport { getOriginalFetch } from \"../original-fetch\";\nimport { postCoverageReport } from \"../sidecar-client\";\nimport {\n  collectHitIds,\n  createCoverageSink,\n  getUnreportedCoverageFiles,\n  markCoverageFilesReported,\n} from \"./runtime\";\n\n/**\n * The replay-mode half of line coverage: giving a request a sink, and reporting\n * what it marked. The marking itself is `runtime.ts`, which the instrumented\n * bundle calls directly.\n */\n\n/**\n * Whether the sidecar has told us it will never take coverage (404 on the route: an older\n * sidecar, or one started without coverage enabled). Latched per isolate so a replay against\n * such a sidecar stops allocating sinks and serialising hits after the first report.\n */\nlet coverageDisabled = false;\n\n/**\n * Runs the handler with a per-request coverage sink, reporting what it marked once the response\n * exists.\n *\n * The sink is per-request rather than per-isolate because workerd interleaves concurrent\n * requests, and every replayed request belongs to a different session — a shared sink would\n * merge their coverage. Reporting goes through `waitUntil` so serialising the hits never delays\n * the response, and every failure path leaves the response untouched: coverage is strictly\n * best-effort.\n */\nexport const runReplayWithCoverage = async (\n  replayContext: RequestReplayContext,\n  invokeHandler: () => Response | Promise<Response>,\n): Promise<Response> => {\n  if (coverageDisabled) {\n    return requestCaptureContext.run(replayContext, invokeHandler);\n  }\n\n  let sink: Uint8Array | undefined;\n  try {\n    sink = createCoverageSink();\n  } catch (error) {\n    warnOnce(\"coverage-sink\", \"Could not allocate a coverage sink.\", error);\n  }\n  if (sink === undefined) {\n    // Allocation threw — run the request uncovered rather than failing it.\n    return requestCaptureContext.run(replayContext, invokeHandler);\n  }\n\n  const contextWithCoverage: RequestReplayContext = {\n    ...replayContext,\n    coverage: sink,\n  };\n  try {\n    return await requestCaptureContext.run(contextWithCoverage, invokeHandler);\n  } finally {\n    reportCoverage(contextWithCoverage);\n  }\n};\n\n/**\n * Sends the hits, plus any id→line map the sidecar has not acknowledged yet.\n *\n * The map goes out incrementally rather than once per isolate because a\n * code-split app registers a module only when its chunk is first imported: a\n * route's server module usually registers on the request that first calls it,\n * after earlier requests have already reported. Without the delta its hits would\n * arrive against ids no file describes, and be dropped by the post-process.\n */\nconst reportCoverage = (context: RequestReplayContext): void => {\n  try {\n    // Read the sink off the context rather than closing over the one allocated at\n    // request start: a module imported while the request ran will have grown it.\n    const sink = context.coverage;\n    if (sink === undefined) {\n      return;\n    }\n    const hitIds = collectHitIds(sink);\n    const files = getUnreportedCoverageFiles();\n    if (hitIds.length === 0 && files.length === 0) {\n      return;\n    }\n    context.waitUntil(\n      postCoverageReport(getOriginalFetch(), context.sidecarUrl, {\n        frontendSessionId: context.frontendSessionId,\n        hitIds,\n        ...(files.length > 0 ? { files } : {}),\n      }).then((outcome) => {\n        if (outcome === \"unsupported\") {\n          coverageDisabled = true;\n          return;\n        }\n        if (outcome === \"accepted\") {\n          markCoverageFilesReported(files);\n        }\n      }),\n    );\n  } catch (error) {\n    warnOnce(\"coverage-report\", \"Failed to report line coverage.\", error);\n  }\n};\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;AAsBA,IAAI,mBAAmB;;;;;;;;;;;AAYvB,MAAa,wBAAwB,OACnC,eACA,kBACsB;AACtB,KAAI,iBACF,QAAO,sBAAsB,IAAI,eAAe,cAAc;CAGhE,IAAI;AACJ,KAAI;AACF,SAAO,oBAAoB;UACpB,OAAO;AACd,WAAS,iBAAiB,uCAAuC,MAAM;;AAEzE,KAAI,SAAS,KAAA,EAEX,QAAO,sBAAsB,IAAI,eAAe,cAAc;CAGhE,MAAM,sBAA4C;EAChD,GAAG;EACH,UAAU;EACX;AACD,KAAI;AACF,SAAO,MAAM,sBAAsB,IAAI,qBAAqB,cAAc;WAClE;AACR,iBAAe,oBAAoB;;;;;;;;;;;;AAavC,MAAM,kBAAkB,YAAwC;AAC9D,KAAI;EAGF,MAAM,OAAO,QAAQ;AACrB,MAAI,SAAS,KAAA,EACX;EAEF,MAAM,SAAS,cAAc,KAAK;EAClC,MAAM,QAAQ,4BAA4B;AAC1C,MAAI,OAAO,WAAW,KAAK,MAAM,WAAW,EAC1C;AAEF,UAAQ,UACN,mBAAmB,kBAAkB,EAAE,QAAQ,YAAY;GACzD,mBAAmB,QAAQ;GAC3B;GACA,GAAI,MAAM,SAAS,IAAI,EAAE,OAAO,GAAG,EAAE;GACtC,CAAC,CAAC,MAAM,YAAY;AACnB,OAAI,YAAY,eAAe;AAC7B,uBAAmB;AACnB;;AAEF,OAAI,YAAY,WACd,2BAA0B,MAAM;IAElC,CACH;UACM,OAAO;AACd,WAAS,mBAAmB,mCAAmC,MAAM","debugId":"7dccd8d2-bdd2-5af1-ab64-d5b05a22f58e"}

package/dist/coverage/runtime.d.ts

@@ -0,0 +1,70 @@
+import { CoverageMap, CoverageMapFile } from "./coverage.types.js";
+
+//#region src/coverage/runtime.d.ts
+/**
+ * Registers one module's slice of the id space, as a side effect of that module
+ * being evaluated.
+ *
+ * Per-module rather than one generated manifest because the full map is not
+ * known until every module has been transformed, and a manifest module would be
+ * loaded by the bundler as soon as the *first* instrumented module imported it.
+ * Self-registration sidesteps that ordering entirely.
+ *
+ * Deduplicated by path+id so a bundler that evaluates a module twice cannot
+ * inflate the id space.
+ */
+declare const registerCoverageFile: (file: CoverageMapFile) => void;
+/** The whole registered id space. Exposed for debugging an instrumented build. */
+declare const getCoverageMap: () => CoverageMap;
+/**
+ * The registered files the sidecar has not acknowledged yet.
+ *
+ * Reported per request rather than once per isolate because a code-split app
+ * registers modules as their chunks are first imported — a route's server module
+ * typically registers on the request that first calls into it, long after the
+ * isolate's first report. Sending the map only once would leave every one of
+ * that module's hits unresolvable, which is coverage silently lost rather than
+ * coverage reported as missing.
+ */
+declare const getUnreportedCoverageFiles: () => CoverageMapFile[];
+/**
+ * Marks files as delivered. Called only once the sidecar has accepted them, so a
+ * report lost to a timeout or a 5xx goes out again with the next one — the
+ * sidecar keeps the first map it sees for an id block, so a dropped map is
+ * permanent otherwise.
+ */
+declare const markCoverageFilesReported: (reported: readonly CoverageMapFile[]) => void;
+/**
+ * Resolves the current request's sink. Called once per function invocation by
+ * instrumented code, which then stores into the returned array directly.
+ */
+declare const __mcEnter: () => Uint8Array | undefined;
+/**
+ * Marks one line hit. Used only for concise arrow bodies (`() => expr`), which
+ * have no block in which to hoist the sink lookup.
+ */
+declare const __mcHit: (id: number) => void;
+/**
+ * Allocates a request's sink, sized to the id space registered so far — which on
+ * a cold isolate is empty, since a code-split app registers nothing until its
+ * chunks are imported. An empty sink is deliberately not the same as "no
+ * instrumentation": {@link registerCoverageFile} grows it as modules arrive, so a
+ * request that starts with nothing registered still collects what it loads.
+ *
+ * Never undefined, so an uninstrumented bundle costs one zero-length allocation
+ * per request and reports nothing, rather than needing a per-isolate latch that
+ * cannot tell "no instrumentation" from "not loaded yet".
+ */
+declare const createCoverageSink: () => Uint8Array;
+/**
+ * The ids marked during a request.
+ *
+ * Scanning the whole sink costs one pass over the id space per request — for a
+ * large app a few hundred thousand array reads, well under a millisecond, and
+ * paid once rather than on every line hit. The alternative (a push-list beside
+ * the bitmap) would add a branch to the hot path to save that single pass.
+ */
+declare const collectHitIds: (sink: Uint8Array) => number[];
+//#endregion
+export { __mcEnter, __mcHit, collectHitIds, createCoverageSink, getCoverageMap, getUnreportedCoverageFiles, markCoverageFilesReported, registerCoverageFile };
+//# sourceMappingURL=runtime.d.ts.map

package/dist/coverage/runtime.js

@@ -0,0 +1,138 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="a559d75e-b978-551b-aaf6-c1a5a06e7cfd")}catch(e){}}();
+import { requestCaptureContext } from "../context.js";
+//#region src/coverage/runtime.ts
+/**
+* The in-worker half of build-time line coverage.
+*
+* The Meticulous Vite plugin rewrites the app's modules so each line marks
+* itself against a sink, and injects a manifest module that calls
+* {@link registerCoverageMap} once per isolate. Everything else here exists to
+* keep the hot path to a single array store.
+*
+* The sink lives on the per-request AsyncLocalStorage store rather than in a
+* module-scope global, which is the whole reason this can attribute coverage at
+* all: workerd interleaves concurrent requests in one isolate, so a shared
+* global would mix sessions together — the same over-attribution that makes
+* workerd's `getBestEffortCoverage` useless for this.
+*
+* Both entry points are no-ops when no sink is present (recording, an
+* uninstrumented request, module-level code running at isolate init), so an
+* instrumented bundle is safe to run with coverage off.
+*/
+const files = [];
+const registeredKeys = /* @__PURE__ */ new Set();
+const reportedKeys = /* @__PURE__ */ new Set();
+let totalIds = 0;
+const fileKey = (file) => `${file.path}#${file.firstId}`;
+/**
+* Registers one module's slice of the id space, as a side effect of that module
+* being evaluated.
+*
+* Per-module rather than one generated manifest because the full map is not
+* known until every module has been transformed, and a manifest module would be
+* loaded by the bundler as soon as the *first* instrumented module imported it.
+* Self-registration sidesteps that ordering entirely.
+*
+* Deduplicated by path+id so a bundler that evaluates a module twice cannot
+* inflate the id space.
+*/
+const registerCoverageFile = (file) => {
+	const key = fileKey(file);
+	if (registeredKeys.has(key)) return;
+	registeredKeys.add(key);
+	files.push(file);
+	const idsInFile = file.lineRanges.length / 2;
+	totalIds = Math.max(totalIds, file.firstId + idsInFile);
+	growCurrentRequestSink();
+};
+/**
+* Extends the in-flight request's sink to cover the ids just registered.
+*
+* Registration happens as a module is evaluated, which for a code-split app is
+* inside whichever request first imported its chunk — usually the one about to
+* execute it. The sink was sized before that, so without this the request that
+* brings a module in is the one request whose coverage of it is lost, and on a
+* cold isolate that is the session's very first render.
+*
+* Replacing the array is safe because instrumented code re-reads the sink at
+* every function entry: only a function already executing keeps the old one, and
+* module evaluation itself carries no markers.
+*/
+const growCurrentRequestSink = () => {
+	const store = requestCaptureContext.getStore();
+	if (store === void 0) return;
+	const sink = store.coverage;
+	if (sink === void 0 || sink.length >= totalIds) return;
+	const grown = new Uint8Array(totalIds);
+	grown.set(sink);
+	store.coverage = grown;
+};
+/** The whole registered id space. Exposed for debugging an instrumented build. */
+const getCoverageMap = () => ({
+	totalIds,
+	files
+});
+/**
+* The registered files the sidecar has not acknowledged yet.
+*
+* Reported per request rather than once per isolate because a code-split app
+* registers modules as their chunks are first imported — a route's server module
+* typically registers on the request that first calls into it, long after the
+* isolate's first report. Sending the map only once would leave every one of
+* that module's hits unresolvable, which is coverage silently lost rather than
+* coverage reported as missing.
+*/
+const getUnreportedCoverageFiles = () => files.filter((file) => !reportedKeys.has(fileKey(file)));
+/**
+* Marks files as delivered. Called only once the sidecar has accepted them, so a
+* report lost to a timeout or a 5xx goes out again with the next one — the
+* sidecar keeps the first map it sees for an id block, so a dropped map is
+* permanent otherwise.
+*/
+const markCoverageFilesReported = (reported) => {
+	for (const file of reported) reportedKeys.add(fileKey(file));
+};
+/**
+* Resolves the current request's sink. Called once per function invocation by
+* instrumented code, which then stores into the returned array directly.
+*/
+const __mcEnter = () => requestCaptureContext.getStore()?.coverage;
+/**
+* Marks one line hit. Used only for concise arrow bodies (`() => expr`), which
+* have no block in which to hoist the sink lookup.
+*/
+const __mcHit = (id) => {
+	const sink = requestCaptureContext.getStore()?.coverage;
+	if (sink !== void 0 && id < sink.length) sink[id] = 1;
+};
+/**
+* Allocates a request's sink, sized to the id space registered so far — which on
+* a cold isolate is empty, since a code-split app registers nothing until its
+* chunks are imported. An empty sink is deliberately not the same as "no
+* instrumentation": {@link registerCoverageFile} grows it as modules arrive, so a
+* request that starts with nothing registered still collects what it loads.
+*
+* Never undefined, so an uninstrumented bundle costs one zero-length allocation
+* per request and reports nothing, rather than needing a per-isolate latch that
+* cannot tell "no instrumentation" from "not loaded yet".
+*/
+const createCoverageSink = () => new Uint8Array(totalIds);
+/**
+* The ids marked during a request.
+*
+* Scanning the whole sink costs one pass over the id space per request — for a
+* large app a few hundred thousand array reads, well under a millisecond, and
+* paid once rather than on every line hit. The alternative (a push-list beside
+* the bitmap) would add a branch to the hot path to save that single pass.
+*/
+const collectHitIds = (sink) => {
+	const hits = [];
+	for (let id = 0; id < sink.length; id++) if (sink[id] !== 0) hits.push(id);
+	return hits;
+};
+//#endregion
+export { __mcEnter, __mcHit, collectHitIds, createCoverageSink, getCoverageMap, getUnreportedCoverageFiles, markCoverageFilesReported, registerCoverageFile };
+
+//# sourceMappingURL=runtime.js.map
+//# debugId=a559d75e-b978-551b-aaf6-c1a5a06e7cfd

package/dist/coverage/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sources":["../../src/coverage/runtime.ts"],"sourcesContent":["import { requestCaptureContext } from \"../context\";\nimport type { CoverageMap, CoverageMapFile } from \"./coverage.types\";\n\n/**\n * The in-worker half of build-time line coverage.\n *\n * The Meticulous Vite plugin rewrites the app's modules so each line marks\n * itself against a sink, and injects a manifest module that calls\n * {@link registerCoverageMap} once per isolate. Everything else here exists to\n * keep the hot path to a single array store.\n *\n * The sink lives on the per-request AsyncLocalStorage store rather than in a\n * module-scope global, which is the whole reason this can attribute coverage at\n * all: workerd interleaves concurrent requests in one isolate, so a shared\n * global would mix sessions together — the same over-attribution that makes\n * workerd's `getBestEffortCoverage` useless for this.\n *\n * Both entry points are no-ops when no sink is present (recording, an\n * uninstrumented request, module-level code running at isolate init), so an\n * instrumented bundle is safe to run with coverage off.\n */\n\nconst files: CoverageMapFile[] = [];\nconst registeredKeys = new Set<string>();\nconst reportedKeys = new Set<string>();\nlet totalIds = 0;\n\nconst fileKey = (file: CoverageMapFile): string =>\n  `${file.path}#${file.firstId}`;\n\n/**\n * Registers one module's slice of the id space, as a side effect of that module\n * being evaluated.\n *\n * Per-module rather than one generated manifest because the full map is not\n * known until every module has been transformed, and a manifest module would be\n * loaded by the bundler as soon as the *first* instrumented module imported it.\n * Self-registration sidesteps that ordering entirely.\n *\n * Deduplicated by path+id so a bundler that evaluates a module twice cannot\n * inflate the id space.\n */\nexport const registerCoverageFile = (file: CoverageMapFile): void => {\n  const key = fileKey(file);\n  if (registeredKeys.has(key)) {\n    return;\n  }\n  registeredKeys.add(key);\n  files.push(file);\n  const idsInFile = file.lineRanges.length / 2;\n  totalIds = Math.max(totalIds, file.firstId + idsInFile);\n  growCurrentRequestSink();\n};\n\n/**\n * Extends the in-flight request's sink to cover the ids just registered.\n *\n * Registration happens as a module is evaluated, which for a code-split app is\n * inside whichever request first imported its chunk — usually the one about to\n * execute it. The sink was sized before that, so without this the request that\n * brings a module in is the one request whose coverage of it is lost, and on a\n * cold isolate that is the session's very first render.\n *\n * Replacing the array is safe because instrumented code re-reads the sink at\n * every function entry: only a function already executing keeps the old one, and\n * module evaluation itself carries no markers.\n */\nconst growCurrentRequestSink = (): void => {\n  const store = requestCaptureContext.getStore();\n  if (store === undefined) {\n    return;\n  }\n  const sink = store.coverage;\n  if (sink === undefined || sink.length >= totalIds) {\n    return;\n  }\n  const grown = new Uint8Array(totalIds);\n  grown.set(sink);\n  store.coverage = grown;\n};\n\n/** The whole registered id space. Exposed for debugging an instrumented build. */\nexport const getCoverageMap = (): CoverageMap => ({ totalIds, files });\n\n/**\n * The registered files the sidecar has not acknowledged yet.\n *\n * Reported per request rather than once per isolate because a code-split app\n * registers modules as their chunks are first imported — a route's server module\n * typically registers on the request that first calls into it, long after the\n * isolate's first report. Sending the map only once would leave every one of\n * that module's hits unresolvable, which is coverage silently lost rather than\n * coverage reported as missing.\n */\nexport const getUnreportedCoverageFiles = (): CoverageMapFile[] =>\n  files.filter((file) => !reportedKeys.has(fileKey(file)));\n\n/**\n * Marks files as delivered. Called only once the sidecar has accepted them, so a\n * report lost to a timeout or a 5xx goes out again with the next one — the\n * sidecar keeps the first map it sees for an id block, so a dropped map is\n * permanent otherwise.\n */\nexport const markCoverageFilesReported = (\n  reported: readonly CoverageMapFile[],\n): void => {\n  for (const file of reported) {\n    reportedKeys.add(fileKey(file));\n  }\n};\n\n/**\n * Resolves the current request's sink. Called once per function invocation by\n * instrumented code, which then stores into the returned array directly.\n */\nexport const __mcEnter = (): Uint8Array | undefined =>\n  requestCaptureContext.getStore()?.coverage;\n\n/**\n * Marks one line hit. Used only for concise arrow bodies (`() => expr`), which\n * have no block in which to hoist the sink lookup.\n */\nexport const __mcHit = (id: number): void => {\n  const sink = requestCaptureContext.getStore()?.coverage;\n  if (sink !== undefined && id < sink.length) {\n    sink[id] = 1;\n  }\n};\n\n/**\n * Allocates a request's sink, sized to the id space registered so far — which on\n * a cold isolate is empty, since a code-split app registers nothing until its\n * chunks are imported. An empty sink is deliberately not the same as \"no\n * instrumentation\": {@link registerCoverageFile} grows it as modules arrive, so a\n * request that starts with nothing registered still collects what it loads.\n *\n * Never undefined, so an uninstrumented bundle costs one zero-length allocation\n * per request and reports nothing, rather than needing a per-isolate latch that\n * cannot tell \"no instrumentation\" from \"not loaded yet\".\n */\nexport const createCoverageSink = (): Uint8Array => new Uint8Array(totalIds);\n\n/**\n * The ids marked during a request.\n *\n * Scanning the whole sink costs one pass over the id space per request — for a\n * large app a few hundred thousand array reads, well under a millisecond, and\n * paid once rather than on every line hit. The alternative (a push-list beside\n * the bitmap) would add a branch to the hot path to save that single pass.\n */\nexport const collectHitIds = (sink: Uint8Array): number[] => {\n  const hits: number[] = [];\n  for (let id = 0; id < sink.length; id++) {\n    if (sink[id] !== 0) {\n      hits.push(id);\n    }\n  }\n  return hits;\n};\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAsBA,MAAM,QAA2B,EAAE;AACnC,MAAM,iCAAiB,IAAI,KAAa;AACxC,MAAM,+BAAe,IAAI,KAAa;AACtC,IAAI,WAAW;AAEf,MAAM,WAAW,SACf,GAAG,KAAK,KAAK,GAAG,KAAK;;;;;;;;;;;;;AAcvB,MAAa,wBAAwB,SAAgC;CACnE,MAAM,MAAM,QAAQ,KAAK;AACzB,KAAI,eAAe,IAAI,IAAI,CACzB;AAEF,gBAAe,IAAI,IAAI;AACvB,OAAM,KAAK,KAAK;CAChB,MAAM,YAAY,KAAK,WAAW,SAAS;AAC3C,YAAW,KAAK,IAAI,UAAU,KAAK,UAAU,UAAU;AACvD,yBAAwB;;;;;;;;;;;;;;;AAgB1B,MAAM,+BAAqC;CACzC,MAAM,QAAQ,sBAAsB,UAAU;AAC9C,KAAI,UAAU,KAAA,EACZ;CAEF,MAAM,OAAO,MAAM;AACnB,KAAI,SAAS,KAAA,KAAa,KAAK,UAAU,SACvC;CAEF,MAAM,QAAQ,IAAI,WAAW,SAAS;AACtC,OAAM,IAAI,KAAK;AACf,OAAM,WAAW;;;AAInB,MAAa,wBAAqC;CAAE;CAAU;CAAO;;;;;;;;;;;AAYrE,MAAa,mCACX,MAAM,QAAQ,SAAS,CAAC,aAAa,IAAI,QAAQ,KAAK,CAAC,CAAC;;;;;;;AAQ1D,MAAa,6BACX,aACS;AACT,MAAK,MAAM,QAAQ,SACjB,cAAa,IAAI,QAAQ,KAAK,CAAC;;;;;;AAQnC,MAAa,kBACX,sBAAsB,UAAU,EAAE;;;;;AAMpC,MAAa,WAAW,OAAqB;CAC3C,MAAM,OAAO,sBAAsB,UAAU,EAAE;AAC/C,KAAI,SAAS,KAAA,KAAa,KAAK,KAAK,OAClC,MAAK,MAAM;;;;;;;;;;;;;AAef,MAAa,2BAAuC,IAAI,WAAW,SAAS;;;;;;;;;AAU5E,MAAa,iBAAiB,SAA+B;CAC3D,MAAM,OAAiB,EAAE;AACzB,MAAK,IAAI,KAAK,GAAG,KAAK,KAAK,QAAQ,KACjC,KAAI,KAAK,QAAQ,EACf,MAAK,KAAK,GAAG;AAGjB,QAAO","debugId":"a559d75e-b978-551b-aaf6-c1a5a06e7cfd"}

package/dist/index.d.ts

@@ -1,9 +1,12 @@
 import { SIDECAR_BINDING_ENV_KEY, SIDECAR_BINDING_ORIGIN, SIDECAR_URL_ENV_KEY, SidecarFetcher, SidecarTransport } from "./sidecar-transport.js";
 import { MeticulousExecutionContext, WithMeticulousOptions } from "./with-meticulous.js";
-import { BindingRequestEvent, CAPTURED_HEADERS, CaptureEvent, CaptureEventsPayload, CapturedBody, FRONTEND_SESSION_ID_HEADER, InboundRequestEvent, KvOmittedReason, KvOperation, KvOperationEvent, METICULOUS_PASSTHROUGH_HEADER, OutboundFetchLookupRequest, OutboundFetchLookupResponse, OutboundRequestEvent, PostgresQueryEvent, REPLAY_ID_HEADER, REPLAY_SIDECAR_URL_HEADER, ReplaySessionInfoResponse, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH } from "./protocol.js";
+import { BindingRequestEvent, CAPTURED_HEADERS, CaptureEvent, CaptureEventsPayload, CapturedBody, CoverageReportRequest, FRONTEND_SESSION_ID_HEADER, InboundRequestEvent, KvOmittedReason, KvOperation, KvOperationEvent, METICULOUS_PASSTHROUGH_HEADER, OutboundFetchLookupRequest, OutboundFetchLookupResponse, OutboundRequestEvent, PostgresQueryEvent, REPLAY_ID_HEADER, REPLAY_SIDECAR_URL_HEADER, ReplaySessionInfoResponse, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_COVERAGE_PATH, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH, WORKERD_SHIM_VERSION_HEADER } from "./protocol.js";
+import { WORKERD_SHIM_VERSION } from "./version.js";
 import { MAX_BODY_CAPTURE_SIZE, readBodyWithCap, readRequestBodyWithCap } from "./body-capture.js";
 import { headersToRecord } from "./outbound-capture.js";
 import { STR_REDACTED, redactRequestBody } from "./redact-body.js";
+import { CoverageMap, CoverageMapFile } from "./coverage/coverage.types.js";
+import { __mcEnter, __mcHit, collectHitIds, createCoverageSink, getCoverageMap, getUnreportedCoverageFiles, markCoverageFilesReported, registerCoverageFile } from "./coverage/runtime.js";
 import { MeticulousPagesFunction, MeticulousPagesFunctionContext, withMeticulousPagesFunction } from "./pages-function.js";
 import { KvCaptureFields, KvCaptureOutcome, serializeKvArgs, serializeKvCaptureFields } from "./kv-capture.js";
 import { deserializeCapturedError, serializeCapturedError } from "./error-capture.js";
@@ -82,5 +85,5 @@ declare const withMeticulous: <H extends MeticulousWorkerHandler<never>>(handler
  */
 declare const getMeticulousSessionId: () => string | undefined;
 //#endregion
-export { type BindingRequestEvent, CAPTURED_HEADERS, CLIENT_TECHNOLOGY_ATTR, CLIENT_TECHNOLOGY_POSTGRES_JS, CLIENT_TECHNOLOGY_WORKERD_BINDING, CLIENT_TECHNOLOGY_WORKERD_FETCH, CLIENT_TECHNOLOGY_WORKERD_KV, type CaptureEvent, type CaptureEventsPayload, type CapturedBody, FRONTEND_SESSION_ID_ATTR, FRONTEND_SESSION_ID_HEADER, type HeaderReader, type HrTime, type InboundRequestEvent, type KvCaptureFields, type KvCaptureOutcome, type KvOmittedReason, type KvOperation, type KvOperationEvent, MAX_BODY_CAPTURE_SIZE, MAX_POSTGRES_JS_RESULT_SIZE, METICULOUS_PASSTHROUGH_HEADER, type MeticulousExecutionContext, type MeticulousPagesFunction, type MeticulousPagesFunctionContext, MeticulousWorkerHandler, type OutboundFetchLookupRequest, type OutboundFetchLookupResponse, type OutboundRequestEvent, POSTGRES_JS_ERROR_ATTR, POSTGRES_JS_QUERY_PARAMS_ATTR, POSTGRES_JS_QUERY_TEXT_ATTR, POSTGRES_JS_RESULT_ATTR, POSTGRES_JS_RESULT_TRUNCATED_ATTR, POSTGRES_JS_ROW_MODE_ATTR, type PostgresJsQueryLike, type PostgresJsRowMode, type PostgresQueryEvent, REPLAY_ID_HEADER, REPLAY_SIDECAR_URL_HEADER, type ReadableSpan, type ReplaySessionInfoResponse, SERVER_TIMING_HEADER, SERVER_TIMING_SESSION_METRIC, SESSION_ID_ORIGIN_ATTR, SESSION_ID_ORIGIN_BACKEND, SIDECAR_BINDING_ENV_KEY, SIDECAR_BINDING_ORIGIN, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH, SIDECAR_URL_ENV_KEY, SPAN_KIND_CLIENT, SPAN_KIND_INTERNAL, SPAN_KIND_SERVER, SPAN_STATUS_ERROR, SPAN_STATUS_OK, SPAN_STATUS_UNSET, STR_REDACTED, type SerializedSpanBase, type SidecarFetcher, type SidecarTransport, SpanBuilder, type SpanStatus, WORKERD_BINDING_NAME_ATTR, WORKERD_KV_ARGS_ATTR, WORKERD_KV_ARGS_TRUNCATED_ATTR, WORKERD_KV_KEY_ATTR, WORKERD_KV_OMITTED_ATTR, WORKERD_KV_OPERATION_ATTR, WORKERD_KV_RESULT_ATTR, WORKERD_KV_RESULT_TRUNCATED_ATTR, WORKERD_KV_VALUE_ATTR, WORKERD_KV_VALUE_TRUNCATED_ATTR, type WithMeticulousOptions, buildServerTimingSessionEntry, deserializeCapturedError, getMeticulousSessionId, headersToRecord, hrTimeToMs, isProvisionalSessionIdCandidate, isSupportedPostgresJsQuery, mintProvisionalSessionId, msToHrTime, postgresJsCommandOf, randomHex, readBodyWithCap, readRequestBodyWithCap, reconstructQueryText, redactRequestBody, redactUrlCredentials, resolveRowMode, serializeCapturedError, serializeKvArgs, serializeKvCaptureFields, serializePostgresJsArgs, serializePostgresJsError, serializePostgresJsResult, serializeSpan, withMeticulous, withMeticulousPagesFunction, withMeticulousPostgres };
+export { type BindingRequestEvent, CAPTURED_HEADERS, CLIENT_TECHNOLOGY_ATTR, CLIENT_TECHNOLOGY_POSTGRES_JS, CLIENT_TECHNOLOGY_WORKERD_BINDING, CLIENT_TECHNOLOGY_WORKERD_FETCH, CLIENT_TECHNOLOGY_WORKERD_KV, type CaptureEvent, type CaptureEventsPayload, type CapturedBody, type CoverageMap, type CoverageMapFile, type CoverageReportRequest, FRONTEND_SESSION_ID_ATTR, FRONTEND_SESSION_ID_HEADER, type HeaderReader, type HrTime, type InboundRequestEvent, type KvCaptureFields, type KvCaptureOutcome, type KvOmittedReason, type KvOperation, type KvOperationEvent, MAX_BODY_CAPTURE_SIZE, MAX_POSTGRES_JS_RESULT_SIZE, METICULOUS_PASSTHROUGH_HEADER, type MeticulousExecutionContext, type MeticulousPagesFunction, type MeticulousPagesFunctionContext, MeticulousWorkerHandler, type OutboundFetchLookupRequest, type OutboundFetchLookupResponse, type OutboundRequestEvent, POSTGRES_JS_ERROR_ATTR, POSTGRES_JS_QUERY_PARAMS_ATTR, POSTGRES_JS_QUERY_TEXT_ATTR, POSTGRES_JS_RESULT_ATTR, POSTGRES_JS_RESULT_TRUNCATED_ATTR, POSTGRES_JS_ROW_MODE_ATTR, type PostgresJsQueryLike, type PostgresJsRowMode, type PostgresQueryEvent, REPLAY_ID_HEADER, REPLAY_SIDECAR_URL_HEADER, type ReadableSpan, type ReplaySessionInfoResponse, SERVER_TIMING_HEADER, SERVER_TIMING_SESSION_METRIC, SESSION_ID_ORIGIN_ATTR, SESSION_ID_ORIGIN_BACKEND, SIDECAR_BINDING_ENV_KEY, SIDECAR_BINDING_ORIGIN, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_COVERAGE_PATH, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH, SIDECAR_URL_ENV_KEY, SPAN_KIND_CLIENT, SPAN_KIND_INTERNAL, SPAN_KIND_SERVER, SPAN_STATUS_ERROR, SPAN_STATUS_OK, SPAN_STATUS_UNSET, STR_REDACTED, type SerializedSpanBase, type SidecarFetcher, type SidecarTransport, SpanBuilder, type SpanStatus, WORKERD_BINDING_NAME_ATTR, WORKERD_KV_ARGS_ATTR, WORKERD_KV_ARGS_TRUNCATED_ATTR, WORKERD_KV_KEY_ATTR, WORKERD_KV_OMITTED_ATTR, WORKERD_KV_OPERATION_ATTR, WORKERD_KV_RESULT_ATTR, WORKERD_KV_RESULT_TRUNCATED_ATTR, WORKERD_KV_VALUE_ATTR, WORKERD_KV_VALUE_TRUNCATED_ATTR, WORKERD_SHIM_VERSION, WORKERD_SHIM_VERSION_HEADER, type WithMeticulousOptions, __mcEnter, __mcHit, buildServerTimingSessionEntry, collectHitIds, createCoverageSink, deserializeCapturedError, getCoverageMap, getMeticulousSessionId, getUnreportedCoverageFiles, headersToRecord, hrTimeToMs, isProvisionalSessionIdCandidate, isSupportedPostgresJsQuery, markCoverageFilesReported, mintProvisionalSessionId, msToHrTime, postgresJsCommandOf, randomHex, readBodyWithCap, readRequestBodyWithCap, reconstructQueryText, redactRequestBody, redactUrlCredentials, registerCoverageFile, resolveRowMode, serializeCapturedError, serializeKvArgs, serializeKvCaptureFields, serializePostgresJsArgs, serializePostgresJsError, serializePostgresJsResult, serializeSpan, withMeticulous, withMeticulousPagesFunction, withMeticulousPostgres };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,13 +1,15 @@
 
-!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="0c547b1c-16e2-5039-8501-124231fbde95")}catch(e){}}();
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="22e3bcf8-6298-5815-a54c-39716473b677")}catch(e){}}();
 import { SIDECAR_BINDING_ENV_KEY, SIDECAR_BINDING_ORIGIN, SIDECAR_URL_ENV_KEY } from "./sidecar-transport.js";
 import { requestCaptureContext } from "./context.js";
 import { STR_REDACTED, redactRequestBody } from "./redact-body.js";
 import { MAX_BODY_CAPTURE_SIZE, readBodyWithCap, readRequestBodyWithCap } from "./body-capture.js";
-import { CAPTURED_HEADERS, FRONTEND_SESSION_ID_HEADER, METICULOUS_PASSTHROUGH_HEADER, REPLAY_ID_HEADER, REPLAY_SIDECAR_URL_HEADER, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH } from "./protocol.js";
+import { CAPTURED_HEADERS, FRONTEND_SESSION_ID_HEADER, METICULOUS_PASSTHROUGH_HEADER, REPLAY_ID_HEADER, REPLAY_SIDECAR_URL_HEADER, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_COVERAGE_PATH, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH, WORKERD_SHIM_VERSION_HEADER } from "./protocol.js";
 import { headersToRecord } from "./outbound-capture.js";
+import { __mcEnter, __mcHit, collectHitIds, createCoverageSink, getCoverageMap, getUnreportedCoverageFiles, markCoverageFilesReported, registerCoverageFile } from "./coverage/runtime.js";
 import { serializeKvArgs, serializeKvCaptureFields } from "./kv-capture.js";
 import { SERVER_TIMING_HEADER, SERVER_TIMING_SESSION_METRIC, buildServerTimingSessionEntry, isProvisionalSessionIdCandidate, mintProvisionalSessionId } from "./provisional-session-id.js";
+import { WORKERD_SHIM_VERSION } from "./version.js";
 import { deserializeCapturedError, serializeCapturedError } from "./error-capture.js";
 import { MAX_POSTGRES_JS_RESULT_SIZE, POSTGRES_JS_ERROR_ATTR, POSTGRES_JS_QUERY_PARAMS_ATTR, POSTGRES_JS_QUERY_TEXT_ATTR, POSTGRES_JS_RESULT_ATTR, POSTGRES_JS_RESULT_TRUNCATED_ATTR, POSTGRES_JS_ROW_MODE_ATTR, isSupportedPostgresJsQuery, postgresJsCommandOf, reconstructQueryText, resolveRowMode, serializePostgresJsArgs, serializePostgresJsError, serializePostgresJsResult } from "./postgres/capture.js";
 import { CLIENT_TECHNOLOGY_ATTR, CLIENT_TECHNOLOGY_POSTGRES_JS, CLIENT_TECHNOLOGY_WORKERD_BINDING, CLIENT_TECHNOLOGY_WORKERD_FETCH, CLIENT_TECHNOLOGY_WORKERD_KV, FRONTEND_SESSION_ID_ATTR, SESSION_ID_ORIGIN_ATTR, SESSION_ID_ORIGIN_BACKEND, WORKERD_BINDING_NAME_ATTR, WORKERD_KV_ARGS_ATTR, WORKERD_KV_ARGS_TRUNCATED_ATTR, WORKERD_KV_KEY_ATTR, WORKERD_KV_OMITTED_ATTR, WORKERD_KV_OPERATION_ATTR, WORKERD_KV_RESULT_ATTR, WORKERD_KV_RESULT_TRUNCATED_ATTR, WORKERD_KV_VALUE_ATTR, WORKERD_KV_VALUE_TRUNCATED_ATTR } from "./spans/attributes.js";
@@ -91,7 +93,7 @@ const withMeticulous = (handler, options) => {
 */
 const getMeticulousSessionId = () => requestCaptureContext.getStore()?.frontendSessionId;
 //#endregion
-export { CAPTURED_HEADERS, CLIENT_TECHNOLOGY_ATTR, CLIENT_TECHNOLOGY_POSTGRES_JS, CLIENT_TECHNOLOGY_WORKERD_BINDING, CLIENT_TECHNOLOGY_WORKERD_FETCH, CLIENT_TECHNOLOGY_WORKERD_KV, FRONTEND_SESSION_ID_ATTR, FRONTEND_SESSION_ID_HEADER, MAX_BODY_CAPTURE_SIZE, MAX_POSTGRES_JS_RESULT_SIZE, METICULOUS_PASSTHROUGH_HEADER, POSTGRES_JS_ERROR_ATTR, POSTGRES_JS_QUERY_PARAMS_ATTR, POSTGRES_JS_QUERY_TEXT_ATTR, POSTGRES_JS_RESULT_ATTR, POSTGRES_JS_RESULT_TRUNCATED_ATTR, POSTGRES_JS_ROW_MODE_ATTR, REPLAY_ID_HEADER, REPLAY_SIDECAR_URL_HEADER, SERVER_TIMING_HEADER, SERVER_TIMING_SESSION_METRIC, SESSION_ID_ORIGIN_ATTR, SESSION_ID_ORIGIN_BACKEND, SIDECAR_BINDING_ENV_KEY, SIDECAR_BINDING_ORIGIN, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH, SIDECAR_URL_ENV_KEY, SPAN_KIND_CLIENT, SPAN_KIND_INTERNAL, SPAN_KIND_SERVER, SPAN_STATUS_ERROR, SPAN_STATUS_OK, SPAN_STATUS_UNSET, STR_REDACTED, SpanBuilder, WORKERD_BINDING_NAME_ATTR, WORKERD_KV_ARGS_ATTR, WORKERD_KV_ARGS_TRUNCATED_ATTR, WORKERD_KV_KEY_ATTR, WORKERD_KV_OMITTED_ATTR, WORKERD_KV_OPERATION_ATTR, WORKERD_KV_RESULT_ATTR, WORKERD_KV_RESULT_TRUNCATED_ATTR, WORKERD_KV_VALUE_ATTR, WORKERD_KV_VALUE_TRUNCATED_ATTR, buildServerTimingSessionEntry, deserializeCapturedError, getMeticulousSessionId, headersToRecord, hrTimeToMs, isProvisionalSessionIdCandidate, isSupportedPostgresJsQuery, mintProvisionalSessionId, msToHrTime, postgresJsCommandOf, randomHex, readBodyWithCap, readRequestBodyWithCap, reconstructQueryText, redactRequestBody, redactUrlCredentials, resolveRowMode, serializeCapturedError, serializeKvArgs, serializeKvCaptureFields, serializePostgresJsArgs, serializePostgresJsError, serializePostgresJsResult, serializeSpan, withMeticulous, withMeticulousPagesFunction, withMeticulousPostgres };
+export { CAPTURED_HEADERS, CLIENT_TECHNOLOGY_ATTR, CLIENT_TECHNOLOGY_POSTGRES_JS, CLIENT_TECHNOLOGY_WORKERD_BINDING, CLIENT_TECHNOLOGY_WORKERD_FETCH, CLIENT_TECHNOLOGY_WORKERD_KV, FRONTEND_SESSION_ID_ATTR, FRONTEND_SESSION_ID_HEADER, MAX_BODY_CAPTURE_SIZE, MAX_POSTGRES_JS_RESULT_SIZE, METICULOUS_PASSTHROUGH_HEADER, POSTGRES_JS_ERROR_ATTR, POSTGRES_JS_QUERY_PARAMS_ATTR, POSTGRES_JS_QUERY_TEXT_ATTR, POSTGRES_JS_RESULT_ATTR, POSTGRES_JS_RESULT_TRUNCATED_ATTR, POSTGRES_JS_ROW_MODE_ATTR, REPLAY_ID_HEADER, REPLAY_SIDECAR_URL_HEADER, SERVER_TIMING_HEADER, SERVER_TIMING_SESSION_METRIC, SESSION_ID_ORIGIN_ATTR, SESSION_ID_ORIGIN_BACKEND, SIDECAR_BINDING_ENV_KEY, SIDECAR_BINDING_ORIGIN, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_COVERAGE_PATH, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH, SIDECAR_URL_ENV_KEY, SPAN_KIND_CLIENT, SPAN_KIND_INTERNAL, SPAN_KIND_SERVER, SPAN_STATUS_ERROR, SPAN_STATUS_OK, SPAN_STATUS_UNSET, STR_REDACTED, SpanBuilder, WORKERD_BINDING_NAME_ATTR, WORKERD_KV_ARGS_ATTR, WORKERD_KV_ARGS_TRUNCATED_ATTR, WORKERD_KV_KEY_ATTR, WORKERD_KV_OMITTED_ATTR, WORKERD_KV_OPERATION_ATTR, WORKERD_KV_RESULT_ATTR, WORKERD_KV_RESULT_TRUNCATED_ATTR, WORKERD_KV_VALUE_ATTR, WORKERD_KV_VALUE_TRUNCATED_ATTR, WORKERD_SHIM_VERSION, WORKERD_SHIM_VERSION_HEADER, __mcEnter, __mcHit, buildServerTimingSessionEntry, collectHitIds, createCoverageSink, deserializeCapturedError, getCoverageMap, getMeticulousSessionId, getUnreportedCoverageFiles, headersToRecord, hrTimeToMs, isProvisionalSessionIdCandidate, isSupportedPostgresJsQuery, markCoverageFilesReported, mintProvisionalSessionId, msToHrTime, postgresJsCommandOf, randomHex, readBodyWithCap, readRequestBodyWithCap, reconstructQueryText, redactRequestBody, redactUrlCredentials, registerCoverageFile, resolveRowMode, serializeCapturedError, serializeKvArgs, serializeKvCaptureFields, serializePostgresJsArgs, serializePostgresJsError, serializePostgresJsResult, serializeSpan, withMeticulous, withMeticulousPagesFunction, withMeticulousPostgres };
 
 //# sourceMappingURL=index.js.map
-//# debugId=0c547b1c-16e2-5039-8501-124231fbde95
+//# debugId=22e3bcf8-6298-5815-a54c-39716473b677

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":["import { requestCaptureContext } from \"./context\";\nimport {\n  type MeticulousExecutionContext,\n  runWithMeticulous,\n  type WithMeticulousOptions,\n} from \"./with-meticulous\";\n\nexport type {\n  BindingRequestEvent,\n  CaptureEvent,\n  CapturedBody,\n  CaptureEventsPayload,\n  InboundRequestEvent,\n  KvOmittedReason,\n  KvOperation,\n  KvOperationEvent,\n  OutboundFetchLookupRequest,\n  OutboundFetchLookupResponse,\n  OutboundRequestEvent,\n  PostgresQueryEvent,\n  ReplaySessionInfoResponse,\n} from \"./protocol\";\nexport {\n  CAPTURED_HEADERS,\n  FRONTEND_SESSION_ID_HEADER,\n  METICULOUS_PASSTHROUGH_HEADER,\n  REPLAY_ID_HEADER,\n  REPLAY_SIDECAR_URL_HEADER,\n  SIDECAR_EVENTS_PATH,\n  SIDECAR_PROTOCOL_VERSION,\n  SIDECAR_PROTOCOL_VERSION_HEADER,\n  SIDECAR_REPLAY_OUTBOUND_FETCH_PATH,\n  SIDECAR_REPLAY_SESSION_PATH,\n} from \"./protocol\";\nexport {\n  MAX_BODY_CAPTURE_SIZE,\n  readBodyWithCap,\n  readRequestBodyWithCap,\n} from \"./body-capture\";\nexport { headersToRecord } from \"./outbound-capture\";\nexport { redactRequestBody, STR_REDACTED } from \"./redact-body\";\nexport type { MeticulousExecutionContext, WithMeticulousOptions };\nexport {\n  type MeticulousPagesFunction,\n  type MeticulousPagesFunctionContext,\n  withMeticulousPagesFunction,\n} from \"./pages-function\";\nexport {\n  SIDECAR_BINDING_ENV_KEY,\n  SIDECAR_BINDING_ORIGIN,\n  SIDECAR_URL_ENV_KEY,\n  type SidecarFetcher,\n  type SidecarTransport,\n} from \"./sidecar-transport\";\n/**\n * Exported for the Node recorder's `withMeticulousCloudflareEnv`, which records the same KV\n * operations from a process whose bindings come from wrangler's `getPlatformProxy`. Both surfaces\n * must produce identical fields, so the contract has exactly one implementation.\n */\nexport {\n  type KvCaptureFields,\n  type KvCaptureOutcome,\n  serializeKvArgs,\n  serializeKvCaptureFields,\n} from \"./kv-capture\";\n/**\n * Exported for the same reason: the Node recorder re-exports these so a postgres.js query, a\n * captured error and a built span are byte-identical whichever surface produced them. A\n * Worker-hosted sidecar needs them too, and cannot load the Node bundle.\n */\nexport {\n  deserializeCapturedError,\n  serializeCapturedError,\n} from \"./error-capture\";\nexport {\n  isSupportedPostgresJsQuery,\n  MAX_POSTGRES_JS_RESULT_SIZE,\n  POSTGRES_JS_ERROR_ATTR,\n  POSTGRES_JS_QUERY_PARAMS_ATTR,\n  POSTGRES_JS_QUERY_TEXT_ATTR,\n  POSTGRES_JS_RESULT_ATTR,\n  POSTGRES_JS_RESULT_TRUNCATED_ATTR,\n  POSTGRES_JS_ROW_MODE_ATTR,\n  postgresJsCommandOf,\n  type PostgresJsQueryLike,\n  type PostgresJsRowMode,\n  reconstructQueryText,\n  resolveRowMode,\n  serializePostgresJsArgs,\n  serializePostgresJsError,\n  serializePostgresJsResult,\n} from \"./postgres/capture\";\nexport { withMeticulousPostgres } from \"./postgres/with-meticulous-postgres\";\nexport * from \"./spans/attributes\";\nexport {\n  hrTimeToMs,\n  msToHrTime,\n  type HrTime,\n  type ReadableSpan,\n  type SerializedSpanBase,\n  SPAN_KIND_CLIENT,\n  SPAN_KIND_INTERNAL,\n  SPAN_KIND_SERVER,\n  SPAN_STATUS_ERROR,\n  SPAN_STATUS_OK,\n  SPAN_STATUS_UNSET,\n  type SpanStatus,\n} from \"./spans/readable-span\";\nexport { serializeSpan } from \"./spans/serialize-span\";\nexport { randomHex, SpanBuilder } from \"./spans/span-builder\";\nexport { redactUrlCredentials } from \"./spans/url-redaction\";\n/**\n * Exported for the Node recorder, whose own `provisional-session-id.ts` adapts these to\n * `http.IncomingMessage` / `http.ServerResponse`. The mint format, the rule for which requests\n * get an id and the `Server-Timing` metric are all wire contracts with the page, so — as with\n * the KV capture fields above — they have exactly one implementation.\n */\nexport {\n  type HeaderReader,\n  SERVER_TIMING_HEADER,\n  SERVER_TIMING_SESSION_METRIC,\n  buildServerTimingSessionEntry,\n  isProvisionalSessionIdCandidate,\n  mintProvisionalSessionId,\n} from \"./provisional-session-id\";\n\n/** Structural subset of an ES-module Worker handler (`export default {...}`). */\nexport interface MeticulousWorkerHandler<Env = never> {\n  fetch(\n    request: Request,\n    env: Env,\n    ctx: MeticulousExecutionContext,\n  ): Response | Promise<Response>;\n}\n\n/**\n * Wraps an ES-module Worker handler so Meticulous can record, or replay, the app's HTTP\n * behaviour:\n *\n *   export default withMeticulous({\n *     async fetch(request, env, ctx) { ... },\n *   });\n *\n * For a Cloudflare Pages project, whose worker exports `onRequest` instead, use\n * {@link withMeticulousPagesFunction} — same behaviour, different handler shape.\n *\n * **Recording** activates on either a `METICULOUS_SIDECAR` service binding (how a **deployed**\n * Worker records: the binding points at a Meticulous recorder sidecar Worker in the same account)\n * or a `METICULOUS_SIDECAR_URL` var (how `wrangler dev` records against a local sidecar process),\n * or the matching `options`. Inbound requests, outgoing `fetch` calls, calls through\n * `fetch`-shaped bindings, KV namespace operations and — with `withMeticulousPostgres` — postgres.js\n * queries are reported to the sidecar, batched into one report per request, without affecting the\n * app. A binding beats a var if both are configured: only the binding can have been added to\n * *this* deployment's wrangler configuration deliberately, whereas a stale `.dev.vars` travels\n * with an image.\n *\n * **Replay** activates on the `x-meticulous-backend-replay-sidecar-url` header, injected by the\n * Meticulous replay runner on requests to the app under test. Outgoing `fetch` calls are then\n * served from the recording instead of reaching the real service — and a call the recording does\n * not cover fails, rather than quietly becoming live traffic; put a `meticulous-passthrough: true`\n * header on a request that must stay real. The clock is frozen at the recorded session's end so\n * recorded credentials are still valid, and `Math.random` / `crypto.randomUUID` /\n * `crypto.getRandomValues` are seeded so ids the app mints are the same in every replay of that\n * session. Workerd cannot read container environment variables, which is why per-replay config\n * arrives as a request header; the shim validates it and only honours a loopback /\n * docker-gateway / private-network `http:` origin.\n *\n * Replay takes precedence over recording when both are configured. A stale sidecar var baked into\n * an image is far more likely than a spurious replay header (nothing but the replay runner emits\n * one), and letting the env win would silently record a replay instead of mocking it.\n *\n * With neither configured the wrapper is a complete pass-through, so it is safe to keep in\n * deployed code. Requires the `nodejs_als` (or `nodejs_compat`) compatibility flag. A capture\n * failure or unreachable sidecar never affects the app.\n */\nexport const withMeticulous = <H extends MeticulousWorkerHandler<never>>(\n  handler: H,\n  options?: WithMeticulousOptions,\n): H => {\n  const wrappedFetch = (\n    request: Request,\n    env: unknown,\n    ctx: MeticulousExecutionContext,\n  ): Promise<Response> =>\n    runWithMeticulous(\n      {\n        request,\n        env,\n        ctx,\n        invokeHandler: () => handler.fetch(request, env as never, ctx),\n      },\n      options,\n    );\n\n  // The wrapper only replaces `fetch` (same call signature), but TypeScript cannot verify a\n  // spread against the bare generic H.\n  return { ...handler, fetch: wrappedFetch } as H;\n};\n\n/**\n * The Meticulous session id of the request currently being served, or `undefined` if this\n * call cannot be tied to one — including whenever the wrapper is a pass-through.\n *\n * Exposed so a server-rendering worker can put the id into the HTML it is about to return,\n * typically as `data-session-id` on the recorder's own `<script>` tag. That is the exact,\n * cache-proof alternative to the `Server-Timing` header the shim publishes automatically;\n * doing both is fine, since the recorder prefers the rendered value. It is also how the id\n * reaches another process — a document navigation has no inbound header for the app to\n * forward, so a worker that fans out to its own services has to pass this on as\n * `x-meticulous-session-id` itself.\n *\n * During a replay this returns the replayed session's id, which is the same value the render\n * being replayed was given when it was recorded (the page adopted the minted id, so that is\n * what the recording is stored under, and it is what the replay runner injects back). An app\n * that renders the id therefore renders the same bytes both times, rather than the id turning\n * every server-rendered page into a diff.\n */\nexport const getMeticulousSessionId = (): string | undefined =>\n  requestCaptureContext.getStore()?.frontendSessionId;\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+KA,MAAa,kBACX,SACA,YACM;CACN,MAAM,gBACJ,SACA,KACA,QAEA,kBACE;EACE;EACA;EACA;EACA,qBAAqB,QAAQ,MAAM,SAAS,KAAc,IAAI;EAC/D,EACD,QACD;AAIH,QAAO;EAAE,GAAG;EAAS,OAAO;EAAc;;;;;;;;;;;;;;;;;;;;AAqB5C,MAAa,+BACX,sBAAsB,UAAU,EAAE","debugId":"0c547b1c-16e2-5039-8501-124231fbde95"}
+{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":["import { requestCaptureContext } from \"./context\";\nimport {\n  type MeticulousExecutionContext,\n  runWithMeticulous,\n  type WithMeticulousOptions,\n} from \"./with-meticulous\";\n\nexport type {\n  BindingRequestEvent,\n  CaptureEvent,\n  CapturedBody,\n  CaptureEventsPayload,\n  CoverageReportRequest,\n  InboundRequestEvent,\n  KvOmittedReason,\n  KvOperation,\n  KvOperationEvent,\n  OutboundFetchLookupRequest,\n  OutboundFetchLookupResponse,\n  OutboundRequestEvent,\n  PostgresQueryEvent,\n  ReplaySessionInfoResponse,\n} from \"./protocol\";\nexport {\n  CAPTURED_HEADERS,\n  FRONTEND_SESSION_ID_HEADER,\n  METICULOUS_PASSTHROUGH_HEADER,\n  REPLAY_ID_HEADER,\n  REPLAY_SIDECAR_URL_HEADER,\n  SIDECAR_EVENTS_PATH,\n  SIDECAR_PROTOCOL_VERSION,\n  SIDECAR_PROTOCOL_VERSION_HEADER,\n  SIDECAR_REPLAY_COVERAGE_PATH,\n  SIDECAR_REPLAY_OUTBOUND_FETCH_PATH,\n  SIDECAR_REPLAY_SESSION_PATH,\n  WORKERD_SHIM_VERSION_HEADER,\n} from \"./protocol\";\nexport { WORKERD_SHIM_VERSION } from \"./version\";\nexport {\n  MAX_BODY_CAPTURE_SIZE,\n  readBodyWithCap,\n  readRequestBodyWithCap,\n} from \"./body-capture\";\nexport { headersToRecord } from \"./outbound-capture\";\nexport { redactRequestBody, STR_REDACTED } from \"./redact-body\";\nexport type { CoverageMap, CoverageMapFile } from \"./coverage/coverage.types\";\n// __mcEnter / __mcHit are the entry points the Vite plugin's injected imports\n// bind to, so they are part of the package's public surface even though no\n// human writes a call to them.\nexport {\n  __mcEnter,\n  __mcHit,\n  collectHitIds,\n  createCoverageSink,\n  getCoverageMap,\n  getUnreportedCoverageFiles,\n  markCoverageFilesReported,\n  registerCoverageFile,\n} from \"./coverage/runtime\";\nexport type { MeticulousExecutionContext, WithMeticulousOptions };\nexport {\n  type MeticulousPagesFunction,\n  type MeticulousPagesFunctionContext,\n  withMeticulousPagesFunction,\n} from \"./pages-function\";\nexport {\n  SIDECAR_BINDING_ENV_KEY,\n  SIDECAR_BINDING_ORIGIN,\n  SIDECAR_URL_ENV_KEY,\n  type SidecarFetcher,\n  type SidecarTransport,\n} from \"./sidecar-transport\";\n/**\n * Exported for the Node recorder's `withMeticulousCloudflareEnv`, which records the same KV\n * operations from a process whose bindings come from wrangler's `getPlatformProxy`. Both surfaces\n * must produce identical fields, so the contract has exactly one implementation.\n */\nexport {\n  type KvCaptureFields,\n  type KvCaptureOutcome,\n  serializeKvArgs,\n  serializeKvCaptureFields,\n} from \"./kv-capture\";\n/**\n * Exported for the same reason: the Node recorder re-exports these so a postgres.js query, a\n * captured error and a built span are byte-identical whichever surface produced them. A\n * Worker-hosted sidecar needs them too, and cannot load the Node bundle.\n */\nexport {\n  deserializeCapturedError,\n  serializeCapturedError,\n} from \"./error-capture\";\nexport {\n  isSupportedPostgresJsQuery,\n  MAX_POSTGRES_JS_RESULT_SIZE,\n  POSTGRES_JS_ERROR_ATTR,\n  POSTGRES_JS_QUERY_PARAMS_ATTR,\n  POSTGRES_JS_QUERY_TEXT_ATTR,\n  POSTGRES_JS_RESULT_ATTR,\n  POSTGRES_JS_RESULT_TRUNCATED_ATTR,\n  POSTGRES_JS_ROW_MODE_ATTR,\n  postgresJsCommandOf,\n  type PostgresJsQueryLike,\n  type PostgresJsRowMode,\n  reconstructQueryText,\n  resolveRowMode,\n  serializePostgresJsArgs,\n  serializePostgresJsError,\n  serializePostgresJsResult,\n} from \"./postgres/capture\";\nexport { withMeticulousPostgres } from \"./postgres/with-meticulous-postgres\";\nexport * from \"./spans/attributes\";\nexport {\n  hrTimeToMs,\n  msToHrTime,\n  type HrTime,\n  type ReadableSpan,\n  type SerializedSpanBase,\n  SPAN_KIND_CLIENT,\n  SPAN_KIND_INTERNAL,\n  SPAN_KIND_SERVER,\n  SPAN_STATUS_ERROR,\n  SPAN_STATUS_OK,\n  SPAN_STATUS_UNSET,\n  type SpanStatus,\n} from \"./spans/readable-span\";\nexport { serializeSpan } from \"./spans/serialize-span\";\nexport { randomHex, SpanBuilder } from \"./spans/span-builder\";\nexport { redactUrlCredentials } from \"./spans/url-redaction\";\n/**\n * Exported for the Node recorder, whose own `provisional-session-id.ts` adapts these to\n * `http.IncomingMessage` / `http.ServerResponse`. The mint format, the rule for which requests\n * get an id and the `Server-Timing` metric are all wire contracts with the page, so — as with\n * the KV capture fields above — they have exactly one implementation.\n */\nexport {\n  type HeaderReader,\n  SERVER_TIMING_HEADER,\n  SERVER_TIMING_SESSION_METRIC,\n  buildServerTimingSessionEntry,\n  isProvisionalSessionIdCandidate,\n  mintProvisionalSessionId,\n} from \"./provisional-session-id\";\n\n/** Structural subset of an ES-module Worker handler (`export default {...}`). */\nexport interface MeticulousWorkerHandler<Env = never> {\n  fetch(\n    request: Request,\n    env: Env,\n    ctx: MeticulousExecutionContext,\n  ): Response | Promise<Response>;\n}\n\n/**\n * Wraps an ES-module Worker handler so Meticulous can record, or replay, the app's HTTP\n * behaviour:\n *\n *   export default withMeticulous({\n *     async fetch(request, env, ctx) { ... },\n *   });\n *\n * For a Cloudflare Pages project, whose worker exports `onRequest` instead, use\n * {@link withMeticulousPagesFunction} — same behaviour, different handler shape.\n *\n * **Recording** activates on either a `METICULOUS_SIDECAR` service binding (how a **deployed**\n * Worker records: the binding points at a Meticulous recorder sidecar Worker in the same account)\n * or a `METICULOUS_SIDECAR_URL` var (how `wrangler dev` records against a local sidecar process),\n * or the matching `options`. Inbound requests, outgoing `fetch` calls, calls through\n * `fetch`-shaped bindings, KV namespace operations and — with `withMeticulousPostgres` — postgres.js\n * queries are reported to the sidecar, batched into one report per request, without affecting the\n * app. A binding beats a var if both are configured: only the binding can have been added to\n * *this* deployment's wrangler configuration deliberately, whereas a stale `.dev.vars` travels\n * with an image.\n *\n * **Replay** activates on the `x-meticulous-backend-replay-sidecar-url` header, injected by the\n * Meticulous replay runner on requests to the app under test. Outgoing `fetch` calls are then\n * served from the recording instead of reaching the real service — and a call the recording does\n * not cover fails, rather than quietly becoming live traffic; put a `meticulous-passthrough: true`\n * header on a request that must stay real. The clock is frozen at the recorded session's end so\n * recorded credentials are still valid, and `Math.random` / `crypto.randomUUID` /\n * `crypto.getRandomValues` are seeded so ids the app mints are the same in every replay of that\n * session. Workerd cannot read container environment variables, which is why per-replay config\n * arrives as a request header; the shim validates it and only honours a loopback /\n * docker-gateway / private-network `http:` origin.\n *\n * Replay takes precedence over recording when both are configured. A stale sidecar var baked into\n * an image is far more likely than a spurious replay header (nothing but the replay runner emits\n * one), and letting the env win would silently record a replay instead of mocking it.\n *\n * With neither configured the wrapper is a complete pass-through, so it is safe to keep in\n * deployed code. Requires the `nodejs_als` (or `nodejs_compat`) compatibility flag. A capture\n * failure or unreachable sidecar never affects the app.\n */\nexport const withMeticulous = <H extends MeticulousWorkerHandler<never>>(\n  handler: H,\n  options?: WithMeticulousOptions,\n): H => {\n  const wrappedFetch = (\n    request: Request,\n    env: unknown,\n    ctx: MeticulousExecutionContext,\n  ): Promise<Response> =>\n    runWithMeticulous(\n      {\n        request,\n        env,\n        ctx,\n        invokeHandler: () => handler.fetch(request, env as never, ctx),\n      },\n      options,\n    );\n\n  // The wrapper only replaces `fetch` (same call signature), but TypeScript cannot verify a\n  // spread against the bare generic H.\n  return { ...handler, fetch: wrappedFetch } as H;\n};\n\n/**\n * The Meticulous session id of the request currently being served, or `undefined` if this\n * call cannot be tied to one — including whenever the wrapper is a pass-through.\n *\n * Exposed so a server-rendering worker can put the id into the HTML it is about to return,\n * typically as `data-session-id` on the recorder's own `<script>` tag. That is the exact,\n * cache-proof alternative to the `Server-Timing` header the shim publishes automatically;\n * doing both is fine, since the recorder prefers the rendered value. It is also how the id\n * reaches another process — a document navigation has no inbound header for the app to\n * forward, so a worker that fans out to its own services has to pass this on as\n * `x-meticulous-session-id` itself.\n *\n * During a replay this returns the replayed session's id, which is the same value the render\n * being replayed was given when it was recorded (the page adopted the minted id, so that is\n * what the recording is stored under, and it is what the replay runner injects back). An app\n * that renders the id therefore renders the same bytes both times, rather than the id turning\n * every server-rendered page into a diff.\n */\nexport const getMeticulousSessionId = (): string | undefined =>\n  requestCaptureContext.getStore()?.frontendSessionId;\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiMA,MAAa,kBACX,SACA,YACM;CACN,MAAM,gBACJ,SACA,KACA,QAEA,kBACE;EACE;EACA;EACA;EACA,qBAAqB,QAAQ,MAAM,SAAS,KAAc,IAAI;EAC/D,EACD,QACD;AAIH,QAAO;EAAE,GAAG;EAAS,OAAO;EAAc;;;;;;;;;;;;;;;;;;;;AAqB5C,MAAa,+BACX,sBAAsB,UAAU,EAAE","debugId":"22e3bcf8-6298-5815-a54c-39716473b677"}

package/dist/protocol.d.ts

@@ -32,6 +32,14 @@ declare const SIDECAR_EVENTS_PATH = "/v1/events";
  */
 declare const SIDECAR_REPLAY_SESSION_PATH = "/v1/replay/session";
 declare const SIDECAR_REPLAY_OUTBOUND_FETCH_PATH = "/v1/replay/outbound-fetch";
+/**
+ * Line-coverage reporting. Additive: an older sidecar answers 404, which the
+ * shim treats as "coverage not collected here" and stops reporting for the life
+ * of the isolate. Deliberately NOT guarded by a
+ * {@link SIDECAR_PROTOCOL_VERSION} bump — that check is exact equality, so a
+ * bump would stop every already-built customer image from mocking at all.
+ */
+declare const SIDECAR_REPLAY_COVERAGE_PATH = "/v1/replay/coverage";
 /**
  * Header carrying the replay sidecar's origin, injected by the Meticulous replay runner
  * on requests to the app under test. Workerd cannot see container environment variables,
@@ -41,6 +49,14 @@ declare const SIDECAR_REPLAY_OUTBOUND_FETCH_PATH = "/v1/replay/outbound-fetch";
  * `host.docker.internal` / private-network `http:` origin — see `replay-sidecar-url.ts`.
  */
 declare const REPLAY_SIDECAR_URL_HEADER = "x-meticulous-backend-replay-sidecar-url";
+/**
+ * Header the in-worker shim stamps on every app response (record and replay)
+ * carrying the shim's npm package version. The replay runner reads this from
+ * Puppeteer — workerd cannot see container env, and the execute pod cannot
+ * reach the in-pod sidecar, so a response header is the only channel that
+ * reports which bundled shim produced a replay's After screenshots.
+ */
+declare const WORKERD_SHIM_VERSION_HEADER = "x-meticulous-workerd-shim-version";
 /**
  * The only headers persisted on capture events. Everything else — notably
  * authorization, cookie/set-cookie, and API-key headers — is dropped at
@@ -244,6 +260,25 @@ interface ReplaySessionInfoResponse {
    */
   clockAnchorMs?: number;
 }
+/**
+ * One request's line coverage, sent to {@link SIDECAR_REPLAY_COVERAGE_PATH}
+ * after the response has been produced.
+ *
+ * `files` carries the build-time id→line map and is sent only on the first
+ * report of an isolate: it is the same for every request the isolate serves and
+ * is far larger than the hits themselves.
+ */
+interface CoverageReportRequest {
+  frontendSessionId: string;
+  /** Global line ids marked during this request, ascending. */
+  hitIds: number[];
+  /** Present on an isolate's first report only. */
+  files?: Array<{
+    path: string;
+    firstId: number; /** Inclusive 1-based line ranges, flattened as `[s1, e1, s2, e2, ...]`. */
+    lineRanges: number[];
+  }>;
+}
 /** Lookup for a single outbound `fetch`, sent to {@link SIDECAR_REPLAY_OUTBOUND_FETCH_PATH}. */
 interface OutboundFetchLookupRequest {
   frontendSessionId: string;
@@ -281,5 +316,5 @@ type OutboundFetchLookupResponse = {
   outcome: "no-mock";
 };
 //#endregion
-export { BindingRequestEvent, CAPTURED_HEADERS, CaptureEvent, CaptureEventsPayload, CapturedBody, FRONTEND_SESSION_ID_HEADER, InboundRequestEvent, KvOmittedReason, KvOperation, KvOperationEvent, METICULOUS_PASSTHROUGH_HEADER, OutboundFetchLookupRequest, OutboundFetchLookupResponse, OutboundRequestEvent, PostgresQueryEvent, REPLAY_ID_HEADER, REPLAY_SIDECAR_URL_HEADER, ReplaySessionInfoResponse, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH };
+export { BindingRequestEvent, CAPTURED_HEADERS, CaptureEvent, CaptureEventsPayload, CapturedBody, CoverageReportRequest, FRONTEND_SESSION_ID_HEADER, InboundRequestEvent, KvOmittedReason, KvOperation, KvOperationEvent, METICULOUS_PASSTHROUGH_HEADER, OutboundFetchLookupRequest, OutboundFetchLookupResponse, OutboundRequestEvent, PostgresQueryEvent, REPLAY_ID_HEADER, REPLAY_SIDECAR_URL_HEADER, ReplaySessionInfoResponse, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_COVERAGE_PATH, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH, WORKERD_SHIM_VERSION_HEADER };
 //# sourceMappingURL=protocol.d.ts.map