@alwaysmeticulous/backend-recorder-workerd 2.327.0 → 2.330.0

package/dist/protocol.js

@@ -5,7 +5,7 @@
 * is the single source of truth for the shape of capture events.
 */
 
-!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]="ca4290fa-420e-5b3e-be68-65bc78d7f094")}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]="195758e9-bc4f-5373-96e6-e0aef542ce8c")}catch(e){}}();
 const SIDECAR_PROTOCOL_VERSION = "2";
 /** Header carrying {@link SIDECAR_PROTOCOL_VERSION} on every shim → sidecar request. */
 const SIDECAR_PROTOCOL_VERSION_HEADER = "x-meticulous-sidecar-protocol-version";
@@ -35,6 +35,14 @@ const SIDECAR_EVENTS_PATH = "/v1/events";
 const SIDECAR_REPLAY_SESSION_PATH = "/v1/replay/session";
 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.
+*/
+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,
 * so an inbound header is the only way per-replay config can reach the shim.
@@ -44,6 +52,14 @@ const SIDECAR_REPLAY_OUTBOUND_FETCH_PATH = "/v1/replay/outbound-fetch";
 */
 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.
+*/
+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
 * capture time, before it ever leaves the worker.
@@ -55,7 +71,7 @@ const REPLAY_SIDECAR_URL_HEADER = "x-meticulous-backend-replay-sidecar-url";
 */
 const CAPTURED_HEADERS = ["content-type", FRONTEND_SESSION_ID_HEADER];
 //#endregion
-export { 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 };
+export { 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 };
 
 //# sourceMappingURL=protocol.js.map
-//# debugId=ca4290fa-420e-5b3e-be68-65bc78d7f094
+//# debugId=195758e9-bc4f-5373-96e6-e0aef542ce8c

package/dist/protocol.js.map

@@ -1 +1 @@
-{"version":3,"file":"protocol.js","sources":["../src/protocol.ts"],"sourcesContent":["/**\n * Wire protocol between the in-worker shim and the Meticulous backend\n * recorder sidecar. The sidecar imports these types (type-only), so this file\n * is the single source of truth for the shape of capture events.\n */\n\nexport const SIDECAR_PROTOCOL_VERSION = \"2\";\n\n/** Header carrying {@link SIDECAR_PROTOCOL_VERSION} on every shim → sidecar request. */\nexport const SIDECAR_PROTOCOL_VERSION_HEADER =\n  \"x-meticulous-sidecar-protocol-version\";\n\n/**\n * Header the Meticulous frontend recorder stamps on requests made by the app\n * under recording; its value ties backend spans to the frontend session.\n */\nexport const FRONTEND_SESSION_ID_HEADER = \"x-meticulous-session-id\";\n\n/** Header identifying one replay attempt of a recorded frontend session. */\nexport const REPLAY_ID_HEADER = \"x-meticulous-replay-id\";\n\n/**\n * A request carrying this header set to `\"true\"` is never served from the recording and\n * never fails on a miss — it goes to the real network. Use it for a call that must be live\n * during replay (a health probe, telemetry, a resource the recording cannot cover).\n *\n * Same convention and value as the frontend network stubbing and the Node backend recorder\n * (`METICULOUS_PASSTHROUGH_HEADER` in `@alwaysmeticulous/backend-recorder-js`); the value\n * must stay in step with both.\n */\nexport const METICULOUS_PASSTHROUGH_HEADER = \"meticulous-passthrough\";\n\nexport const SIDECAR_EVENTS_PATH = \"/v1/events\";\n\n/**\n * Replay routes. A sidecar started in record mode answers 404 on both. Replay is hermetic,\n * so an unanswered outbound-fetch lookup fails the app's call rather than letting it reach\n * the real service — the same as any other failure to stub.\n */\nexport const SIDECAR_REPLAY_SESSION_PATH = \"/v1/replay/session\";\nexport const SIDECAR_REPLAY_OUTBOUND_FETCH_PATH = \"/v1/replay/outbound-fetch\";\n\n/**\n * Header carrying the replay sidecar's origin, injected by the Meticulous replay runner\n * on requests to the app under test. Workerd cannot see container environment variables,\n * so an inbound header is the only way per-replay config can reach the shim.\n *\n * The shim validates the value before using it and only honours a loopback /\n * `host.docker.internal` / private-network `http:` origin — see `replay-sidecar-url.ts`.\n */\nexport const REPLAY_SIDECAR_URL_HEADER =\n  \"x-meticulous-backend-replay-sidecar-url\";\n\n/**\n * The only headers persisted on capture events. Everything else — notably\n * authorization, cookie/set-cookie, and API-key headers — is dropped at\n * capture time, before it ever leaves the worker.\n *\n * The Node backend recorder persists the same two, plus the inbound request's\n * `Cookie` header on SERVER spans (`recorded-request-headers.ts`). This list\n * has not followed it there, so a workerd recording of an authenticated server\n * render still carries no session cookie.\n */\nexport const CAPTURED_HEADERS = [\n  \"content-type\",\n  FRONTEND_SESSION_ID_HEADER,\n] as const;\n\nexport interface CapturedBody {\n  /** UTF-8 decoded body, truncated to the capture cap. */\n  body: string;\n  /** True when the body exceeded the capture cap or the read was cut short. */\n  truncated: boolean;\n}\n\n/**\n * The fields every capture event carries to say which request, session and trace it belongs to.\n */\ninterface CorrelatedEvent {\n  /** Correlates outbound events to the inbound request being handled. */\n  requestId: string;\n  /** Value of {@link FRONTEND_SESSION_ID_HEADER} on the inbound request, if any. */\n  frontendSessionId?: string;\n  /**\n   * Trace the request's spans belong to (32 hex chars), minted by the shim.\n   *\n   * The shim mints it, rather than the sidecar deriving it from {@link requestId}, so span\n   * assembly is stateless: a sidecar that had to remember `requestId → traceId` would give a\n   * request's SERVER span and its CLIENT children different traces whenever it lost that memory\n   * between two batches — which, for a Worker-hosted sidecar, an eviction can do at any moment.\n   *\n   * Optional so a sidecar keeps working against a shim that predates this field, in which case\n   * it falls back to its own per-`requestId` map.\n   */\n  traceId?: string;\n  /**\n   * Span id of the request's SERVER span (16 hex chars), also minted by the shim: it is the\n   * parent of every CLIENT span the request produced, and the inbound event's own span id.\n   */\n  serverSpanId?: string;\n}\n\ninterface BaseRequestEvent extends CorrelatedEvent {\n  method: string;\n  /** Full URL including query string. */\n  url: string;\n  /** Lower-cased header name → values. */\n  requestHeaders: Record<string, string[]>;\n  responseHeaders?: Record<string, string[]>;\n  statusCode?: number;\n  startTimeMs: number;\n  endTimeMs: number;\n  /** Set when the request failed before a response was produced. */\n  error?: string;\n}\n\n/**\n * The worker's own inbound request (becomes a SERVER span). Bodies are not\n * captured, matching the Node backend recorder's SERVER-span contract.\n */\nexport interface InboundRequestEvent extends BaseRequestEvent {\n  kind: \"inbound\";\n  /**\n   * Where {@link BaseRequestEvent.frontendSessionId} came from. Absent means the browser\n   * minted it and sent it on the request, which is the normal case. `\"backend\"` means the\n   * shim minted it for a document navigation the browser could not tag, and the page may or\n   * may not have gone on to adopt it — a distinction ingestion needs, because an unadopted\n   * backend-minted id names a session that will never exist and must be treated as unstamped.\n   * The sidecar turns it into `meticulous.session_id_origin`.\n   *\n   * Optional, and therefore compatible with an older sidecar (which ignores it) — which is\n   * why adding it does not bump {@link SIDECAR_PROTOCOL_VERSION}, a strict-equality check\n   * whose bump would instead make this shim unusable against one.\n   */\n  sessionIdOrigin?: \"backend\";\n}\n\n/**\n * An outgoing `fetch` call made while handling an inbound request (becomes a\n * CLIENT span).\n */\nexport interface OutboundRequestEvent extends BaseRequestEvent {\n  kind: \"outbound\";\n  requestBody?: CapturedBody;\n  responseBody?: CapturedBody;\n}\n\n/**\n * A `fetch` through a Cloudflare binding — a service binding, an assets binding, or a\n * Durable Object stub — made while handling an inbound request (becomes a CLIENT span).\n *\n * Request/Response-shaped like {@link OutboundRequestEvent}, but a distinct kind because the\n * call never leaves the isolate and its URL is whatever the caller invented. Keeping the two\n * apart means a binding call and real egress can never be confused for one another when\n * these spans are eventually mocked.\n */\nexport interface BindingRequestEvent extends BaseRequestEvent {\n  kind: \"binding\";\n  /**\n   * The `env` key the binding was found under. Absent when the instance was never seen on\n   * `env` — most commonly a Durable Object stub, which `namespace.get()` produces rather\n   * than being a binding in its own right.\n   */\n  bindingName?: string;\n  requestBody?: CapturedBody;\n  responseBody?: CapturedBody;\n}\n\n/** KV namespace methods the shim records. */\nexport type KvOperation = \"get\" | \"getWithMetadata\" | \"put\" | \"delete\" | \"list\";\n\n/**\n * Why a KV value is absent from an event: workerd handed it over in a form that cannot be\n * persisted as text. A `\"stream\"` value must not even be read — consuming it would take the\n * bytes away from the app — and binary values are skipped deliberately, since KV blobs are\n * large and would both bloat the recording and be mangled by UTF-8 capture.\n */\nexport type KvOmittedReason = \"binary\" | \"stream\";\n\n/**\n * An operation on a Cloudflare KV namespace binding, made while handling an inbound request\n * (becomes a CLIENT span).\n *\n * KV is not HTTP: there is no method, URL or status code, so this event shares nothing with\n * {@link BaseRequestEvent} beyond correlation and timing. Values are JSON so that a single\n * `JSON.parse` reconstructs exactly what the app saw, whichever `type` the read asked for.\n */\nexport interface KvOperationEvent extends CorrelatedEvent {\n  kind: \"kv\";\n  /**\n   * The `env` key the KV namespace was found under. Always present, unlike on a binding\n   * event: a namespace has no factory equivalent to `DurableObjectNamespace.get()`, so one\n   * that was never seen on `env` is not recorded at all.\n   */\n  bindingName: string;\n  operation: KvOperation;\n  /**\n   * The key operated on, when it is a single string. Absent for `list` (which spans keys) and\n   * for a bulk `get` (which takes an array) — both keep their arguments in {@link args}.\n   */\n  key?: string;\n  /**\n   * JSON of the call's arguments: the read `type`, the `put` options, the `list` selector.\n   * A `put` value appears as `null` here — it is captured in {@link value} instead, so that\n   * redaction applies to it.\n   */\n  args?: CapturedBody;\n  /** JSON of the value a `put` wrote, with secret-looking fields redacted. */\n  value?: CapturedBody;\n  /**\n   * JSON of what the operation returned: the value for `get`, `{value, metadata}` for\n   * `getWithMetadata`, the key page for `list`. Absent for `put`/`delete`, which return\n   * nothing, and for a value that could not be captured (see {@link omitted}).\n   */\n  result?: CapturedBody;\n  /**\n   * Why the operation's value is missing. Refers to the written value for `put` and to the\n   * read value otherwise — a `put` has no result, so this is never ambiguous.\n   */\n  omitted?: KvOmittedReason;\n  startTimeMs: number;\n  endTimeMs: number;\n  /** Set when the operation threw. */\n  error?: string;\n}\n\n/**\n * One postgres.js query made while handling an inbound request (becomes a CLIENT span).\n *\n * Deliberately carries the same fields the Node recorder puts on a postgres.js span rather than\n * anything Worker-specific: `PostgresJsMockStore` builds its match key from those attributes at\n * load time, so a query recorded here replays through the existing Node mock path unchanged.\n * See `postgres/capture.ts` for the serialization, which both surfaces share.\n */\nexport interface PostgresQueryEvent extends CorrelatedEvent {\n  kind: \"postgres\";\n  /** SQL rebuilt from the tagged template's chunks, with `$1`, `$2`… placeholders. */\n  queryText: string;\n  /** JSON of the interpolated values, from `serializePostgresJsArgs`. */\n  params: string;\n  /** `\"\"`, `\"raw\"` or `\"values\"` — the row shape the query asked for. */\n  rowMode: string;\n  /** JSON of the resolved `Result`, capped at {@link MAX_POSTGRES_JS_RESULT_SIZE}. */\n  result?: CapturedBody;\n  /**\n   * JSON of the rejection, from `serializePostgresJsError`. Set instead of {@link result}, and\n   * distinct from the transport-level `error` string on the HTTP-shaped events: this one is a\n   * recorded outcome the replay reproduces, not a note that capture failed.\n   */\n  errorJson?: string;\n  startTimeMs: number;\n  endTimeMs: number;\n}\n\nexport type CaptureEvent =\n  | InboundRequestEvent\n  | OutboundRequestEvent\n  | BindingRequestEvent\n  | KvOperationEvent\n  | PostgresQueryEvent;\n\nexport interface CaptureEventsPayload {\n  events: CaptureEvent[];\n}\n\n/**\n * Answer to `GET {SIDECAR_REPLAY_SESSION_PATH}?sessionId=<id>`: whether the sidecar holds\n * mocks for a session, and the virtual clock anchor to freeze `Date` at while serving it.\n */\nexport interface ReplaySessionInfoResponse {\n  found: boolean;\n  /**\n   * Epoch ms of the session's last recorded activity. The worker freezes its clock here so\n   * that credentials minted during the recording are already issued but not yet expired.\n   */\n  clockAnchorMs?: number;\n}\n\n/** Lookup for a single outbound `fetch`, sent to {@link SIDECAR_REPLAY_OUTBOUND_FETCH_PATH}. */\nexport interface OutboundFetchLookupRequest {\n  frontendSessionId: string;\n  replayId: string;\n  method: string;\n  /** Full URL including query string. */\n  url: string;\n  /**\n   * Request body as captured by `readBodyWithCap`. The sidecar hashes this itself, so the\n   * hash it compares against a recording is derived from byte-identical input on both the\n   * record and replay sides.\n   */\n  requestBody?: CapturedBody;\n}\n\n/**\n * A recorded response to serve, or a signal the caller must fail the request. Replay is\n * hermetic, so the shim never turns any of these into a real call — nor an outcome it does\n * not recognise. The only live path is the request-side `meticulous-passthrough` header,\n * handled before the lookup, not any response here.\n */\nexport type OutboundFetchLookupResponse =\n  | {\n      outcome: \"mock\";\n      statusCode: number;\n      body: string;\n      headers: Record<string, string>;\n    }\n  /**\n   * The store holds nothing for this call — a genuine miss, or a call the sidecar could not\n   * look up at all (an unparseable URL). Replay is hermetic, so the shim fails the request\n   * rather than letting it reach the real service — matching the Node backend recorder's\n   * http/undici mocks. There is deliberately no \"let the call through\" outcome: the only\n   * live path is the request-side `meticulous-passthrough` header.\n   */\n  | { outcome: \"no-mock\" };\n"],"names":[],"mappings":";;;;;;;;AAMA,MAAa,2BAA2B;;AAGxC,MAAa,kCACX;;;;;AAMF,MAAa,6BAA6B;;AAG1C,MAAa,mBAAmB;;;;;;;;;;AAWhC,MAAa,gCAAgC;AAE7C,MAAa,sBAAsB;;;;;;AAOnC,MAAa,8BAA8B;AAC3C,MAAa,qCAAqC;;;;;;;;;AAUlD,MAAa,4BACX;;;;;;;;;;;AAYF,MAAa,mBAAmB,CAC9B,gBACA,2BACD","debugId":"ca4290fa-420e-5b3e-be68-65bc78d7f094"}
+{"version":3,"file":"protocol.js","sources":["../src/protocol.ts"],"sourcesContent":["/**\n * Wire protocol between the in-worker shim and the Meticulous backend\n * recorder sidecar. The sidecar imports these types (type-only), so this file\n * is the single source of truth for the shape of capture events.\n */\n\nexport const SIDECAR_PROTOCOL_VERSION = \"2\";\n\n/** Header carrying {@link SIDECAR_PROTOCOL_VERSION} on every shim → sidecar request. */\nexport const SIDECAR_PROTOCOL_VERSION_HEADER =\n  \"x-meticulous-sidecar-protocol-version\";\n\n/**\n * Header the Meticulous frontend recorder stamps on requests made by the app\n * under recording; its value ties backend spans to the frontend session.\n */\nexport const FRONTEND_SESSION_ID_HEADER = \"x-meticulous-session-id\";\n\n/** Header identifying one replay attempt of a recorded frontend session. */\nexport const REPLAY_ID_HEADER = \"x-meticulous-replay-id\";\n\n/**\n * A request carrying this header set to `\"true\"` is never served from the recording and\n * never fails on a miss — it goes to the real network. Use it for a call that must be live\n * during replay (a health probe, telemetry, a resource the recording cannot cover).\n *\n * Same convention and value as the frontend network stubbing and the Node backend recorder\n * (`METICULOUS_PASSTHROUGH_HEADER` in `@alwaysmeticulous/backend-recorder-js`); the value\n * must stay in step with both.\n */\nexport const METICULOUS_PASSTHROUGH_HEADER = \"meticulous-passthrough\";\n\nexport const SIDECAR_EVENTS_PATH = \"/v1/events\";\n\n/**\n * Replay routes. A sidecar started in record mode answers 404 on both. Replay is hermetic,\n * so an unanswered outbound-fetch lookup fails the app's call rather than letting it reach\n * the real service — the same as any other failure to stub.\n */\nexport const SIDECAR_REPLAY_SESSION_PATH = \"/v1/replay/session\";\nexport const SIDECAR_REPLAY_OUTBOUND_FETCH_PATH = \"/v1/replay/outbound-fetch\";\n\n/**\n * Line-coverage reporting. Additive: an older sidecar answers 404, which the\n * shim treats as \"coverage not collected here\" and stops reporting for the life\n * of the isolate. Deliberately NOT guarded by a\n * {@link SIDECAR_PROTOCOL_VERSION} bump — that check is exact equality, so a\n * bump would stop every already-built customer image from mocking at all.\n */\nexport const SIDECAR_REPLAY_COVERAGE_PATH = \"/v1/replay/coverage\";\n\n/**\n * Header carrying the replay sidecar's origin, injected by the Meticulous replay runner\n * on requests to the app under test. Workerd cannot see container environment variables,\n * so an inbound header is the only way per-replay config can reach the shim.\n *\n * The shim validates the value before using it and only honours a loopback /\n * `host.docker.internal` / private-network `http:` origin — see `replay-sidecar-url.ts`.\n */\nexport const REPLAY_SIDECAR_URL_HEADER =\n  \"x-meticulous-backend-replay-sidecar-url\";\n\n/**\n * Header the in-worker shim stamps on every app response (record and replay)\n * carrying the shim's npm package version. The replay runner reads this from\n * Puppeteer — workerd cannot see container env, and the execute pod cannot\n * reach the in-pod sidecar, so a response header is the only channel that\n * reports which bundled shim produced a replay's After screenshots.\n */\nexport const WORKERD_SHIM_VERSION_HEADER = \"x-meticulous-workerd-shim-version\";\n\n/**\n * The only headers persisted on capture events. Everything else — notably\n * authorization, cookie/set-cookie, and API-key headers — is dropped at\n * capture time, before it ever leaves the worker.\n *\n * The Node backend recorder persists the same two, plus the inbound request's\n * `Cookie` header on SERVER spans (`recorded-request-headers.ts`). This list\n * has not followed it there, so a workerd recording of an authenticated server\n * render still carries no session cookie.\n */\nexport const CAPTURED_HEADERS = [\n  \"content-type\",\n  FRONTEND_SESSION_ID_HEADER,\n] as const;\n\nexport interface CapturedBody {\n  /** UTF-8 decoded body, truncated to the capture cap. */\n  body: string;\n  /** True when the body exceeded the capture cap or the read was cut short. */\n  truncated: boolean;\n}\n\n/**\n * The fields every capture event carries to say which request, session and trace it belongs to.\n */\ninterface CorrelatedEvent {\n  /** Correlates outbound events to the inbound request being handled. */\n  requestId: string;\n  /** Value of {@link FRONTEND_SESSION_ID_HEADER} on the inbound request, if any. */\n  frontendSessionId?: string;\n  /**\n   * Trace the request's spans belong to (32 hex chars), minted by the shim.\n   *\n   * The shim mints it, rather than the sidecar deriving it from {@link requestId}, so span\n   * assembly is stateless: a sidecar that had to remember `requestId → traceId` would give a\n   * request's SERVER span and its CLIENT children different traces whenever it lost that memory\n   * between two batches — which, for a Worker-hosted sidecar, an eviction can do at any moment.\n   *\n   * Optional so a sidecar keeps working against a shim that predates this field, in which case\n   * it falls back to its own per-`requestId` map.\n   */\n  traceId?: string;\n  /**\n   * Span id of the request's SERVER span (16 hex chars), also minted by the shim: it is the\n   * parent of every CLIENT span the request produced, and the inbound event's own span id.\n   */\n  serverSpanId?: string;\n}\n\ninterface BaseRequestEvent extends CorrelatedEvent {\n  method: string;\n  /** Full URL including query string. */\n  url: string;\n  /** Lower-cased header name → values. */\n  requestHeaders: Record<string, string[]>;\n  responseHeaders?: Record<string, string[]>;\n  statusCode?: number;\n  startTimeMs: number;\n  endTimeMs: number;\n  /** Set when the request failed before a response was produced. */\n  error?: string;\n}\n\n/**\n * The worker's own inbound request (becomes a SERVER span). Bodies are not\n * captured, matching the Node backend recorder's SERVER-span contract.\n */\nexport interface InboundRequestEvent extends BaseRequestEvent {\n  kind: \"inbound\";\n  /**\n   * Where {@link BaseRequestEvent.frontendSessionId} came from. Absent means the browser\n   * minted it and sent it on the request, which is the normal case. `\"backend\"` means the\n   * shim minted it for a document navigation the browser could not tag, and the page may or\n   * may not have gone on to adopt it — a distinction ingestion needs, because an unadopted\n   * backend-minted id names a session that will never exist and must be treated as unstamped.\n   * The sidecar turns it into `meticulous.session_id_origin`.\n   *\n   * Optional, and therefore compatible with an older sidecar (which ignores it) — which is\n   * why adding it does not bump {@link SIDECAR_PROTOCOL_VERSION}, a strict-equality check\n   * whose bump would instead make this shim unusable against one.\n   */\n  sessionIdOrigin?: \"backend\";\n}\n\n/**\n * An outgoing `fetch` call made while handling an inbound request (becomes a\n * CLIENT span).\n */\nexport interface OutboundRequestEvent extends BaseRequestEvent {\n  kind: \"outbound\";\n  requestBody?: CapturedBody;\n  responseBody?: CapturedBody;\n}\n\n/**\n * A `fetch` through a Cloudflare binding — a service binding, an assets binding, or a\n * Durable Object stub — made while handling an inbound request (becomes a CLIENT span).\n *\n * Request/Response-shaped like {@link OutboundRequestEvent}, but a distinct kind because the\n * call never leaves the isolate and its URL is whatever the caller invented. Keeping the two\n * apart means a binding call and real egress can never be confused for one another when\n * these spans are eventually mocked.\n */\nexport interface BindingRequestEvent extends BaseRequestEvent {\n  kind: \"binding\";\n  /**\n   * The `env` key the binding was found under. Absent when the instance was never seen on\n   * `env` — most commonly a Durable Object stub, which `namespace.get()` produces rather\n   * than being a binding in its own right.\n   */\n  bindingName?: string;\n  requestBody?: CapturedBody;\n  responseBody?: CapturedBody;\n}\n\n/** KV namespace methods the shim records. */\nexport type KvOperation = \"get\" | \"getWithMetadata\" | \"put\" | \"delete\" | \"list\";\n\n/**\n * Why a KV value is absent from an event: workerd handed it over in a form that cannot be\n * persisted as text. A `\"stream\"` value must not even be read — consuming it would take the\n * bytes away from the app — and binary values are skipped deliberately, since KV blobs are\n * large and would both bloat the recording and be mangled by UTF-8 capture.\n */\nexport type KvOmittedReason = \"binary\" | \"stream\";\n\n/**\n * An operation on a Cloudflare KV namespace binding, made while handling an inbound request\n * (becomes a CLIENT span).\n *\n * KV is not HTTP: there is no method, URL or status code, so this event shares nothing with\n * {@link BaseRequestEvent} beyond correlation and timing. Values are JSON so that a single\n * `JSON.parse` reconstructs exactly what the app saw, whichever `type` the read asked for.\n */\nexport interface KvOperationEvent extends CorrelatedEvent {\n  kind: \"kv\";\n  /**\n   * The `env` key the KV namespace was found under. Always present, unlike on a binding\n   * event: a namespace has no factory equivalent to `DurableObjectNamespace.get()`, so one\n   * that was never seen on `env` is not recorded at all.\n   */\n  bindingName: string;\n  operation: KvOperation;\n  /**\n   * The key operated on, when it is a single string. Absent for `list` (which spans keys) and\n   * for a bulk `get` (which takes an array) — both keep their arguments in {@link args}.\n   */\n  key?: string;\n  /**\n   * JSON of the call's arguments: the read `type`, the `put` options, the `list` selector.\n   * A `put` value appears as `null` here — it is captured in {@link value} instead, so that\n   * redaction applies to it.\n   */\n  args?: CapturedBody;\n  /** JSON of the value a `put` wrote, with secret-looking fields redacted. */\n  value?: CapturedBody;\n  /**\n   * JSON of what the operation returned: the value for `get`, `{value, metadata}` for\n   * `getWithMetadata`, the key page for `list`. Absent for `put`/`delete`, which return\n   * nothing, and for a value that could not be captured (see {@link omitted}).\n   */\n  result?: CapturedBody;\n  /**\n   * Why the operation's value is missing. Refers to the written value for `put` and to the\n   * read value otherwise — a `put` has no result, so this is never ambiguous.\n   */\n  omitted?: KvOmittedReason;\n  startTimeMs: number;\n  endTimeMs: number;\n  /** Set when the operation threw. */\n  error?: string;\n}\n\n/**\n * One postgres.js query made while handling an inbound request (becomes a CLIENT span).\n *\n * Deliberately carries the same fields the Node recorder puts on a postgres.js span rather than\n * anything Worker-specific: `PostgresJsMockStore` builds its match key from those attributes at\n * load time, so a query recorded here replays through the existing Node mock path unchanged.\n * See `postgres/capture.ts` for the serialization, which both surfaces share.\n */\nexport interface PostgresQueryEvent extends CorrelatedEvent {\n  kind: \"postgres\";\n  /** SQL rebuilt from the tagged template's chunks, with `$1`, `$2`… placeholders. */\n  queryText: string;\n  /** JSON of the interpolated values, from `serializePostgresJsArgs`. */\n  params: string;\n  /** `\"\"`, `\"raw\"` or `\"values\"` — the row shape the query asked for. */\n  rowMode: string;\n  /** JSON of the resolved `Result`, capped at {@link MAX_POSTGRES_JS_RESULT_SIZE}. */\n  result?: CapturedBody;\n  /**\n   * JSON of the rejection, from `serializePostgresJsError`. Set instead of {@link result}, and\n   * distinct from the transport-level `error` string on the HTTP-shaped events: this one is a\n   * recorded outcome the replay reproduces, not a note that capture failed.\n   */\n  errorJson?: string;\n  startTimeMs: number;\n  endTimeMs: number;\n}\n\nexport type CaptureEvent =\n  | InboundRequestEvent\n  | OutboundRequestEvent\n  | BindingRequestEvent\n  | KvOperationEvent\n  | PostgresQueryEvent;\n\nexport interface CaptureEventsPayload {\n  events: CaptureEvent[];\n}\n\n/**\n * Answer to `GET {SIDECAR_REPLAY_SESSION_PATH}?sessionId=<id>`: whether the sidecar holds\n * mocks for a session, and the virtual clock anchor to freeze `Date` at while serving it.\n */\nexport interface ReplaySessionInfoResponse {\n  found: boolean;\n  /**\n   * Epoch ms of the session's last recorded activity. The worker freezes its clock here so\n   * that credentials minted during the recording are already issued but not yet expired.\n   */\n  clockAnchorMs?: number;\n}\n\n/**\n * One request's line coverage, sent to {@link SIDECAR_REPLAY_COVERAGE_PATH}\n * after the response has been produced.\n *\n * `files` carries the build-time id→line map and is sent only on the first\n * report of an isolate: it is the same for every request the isolate serves and\n * is far larger than the hits themselves.\n */\nexport interface CoverageReportRequest {\n  frontendSessionId: string;\n  /** Global line ids marked during this request, ascending. */\n  hitIds: number[];\n  /** Present on an isolate's first report only. */\n  files?: Array<{\n    path: string;\n    firstId: number;\n    /** Inclusive 1-based line ranges, flattened as `[s1, e1, s2, e2, ...]`. */\n    lineRanges: number[];\n  }>;\n}\n\n/** Lookup for a single outbound `fetch`, sent to {@link SIDECAR_REPLAY_OUTBOUND_FETCH_PATH}. */\nexport interface OutboundFetchLookupRequest {\n  frontendSessionId: string;\n  replayId: string;\n  method: string;\n  /** Full URL including query string. */\n  url: string;\n  /**\n   * Request body as captured by `readBodyWithCap`. The sidecar hashes this itself, so the\n   * hash it compares against a recording is derived from byte-identical input on both the\n   * record and replay sides.\n   */\n  requestBody?: CapturedBody;\n}\n\n/**\n * A recorded response to serve, or a signal the caller must fail the request. Replay is\n * hermetic, so the shim never turns any of these into a real call — nor an outcome it does\n * not recognise. The only live path is the request-side `meticulous-passthrough` header,\n * handled before the lookup, not any response here.\n */\nexport type OutboundFetchLookupResponse =\n  | {\n      outcome: \"mock\";\n      statusCode: number;\n      body: string;\n      headers: Record<string, string>;\n    }\n  /**\n   * The store holds nothing for this call — a genuine miss, or a call the sidecar could not\n   * look up at all (an unparseable URL). Replay is hermetic, so the shim fails the request\n   * rather than letting it reach the real service — matching the Node backend recorder's\n   * http/undici mocks. There is deliberately no \"let the call through\" outcome: the only\n   * live path is the request-side `meticulous-passthrough` header.\n   */\n  | { outcome: \"no-mock\" };\n"],"names":[],"mappings":";;;;;;;;AAMA,MAAa,2BAA2B;;AAGxC,MAAa,kCACX;;;;;AAMF,MAAa,6BAA6B;;AAG1C,MAAa,mBAAmB;;;;;;;;;;AAWhC,MAAa,gCAAgC;AAE7C,MAAa,sBAAsB;;;;;;AAOnC,MAAa,8BAA8B;AAC3C,MAAa,qCAAqC;;;;;;;;AASlD,MAAa,+BAA+B;;;;;;;;;AAU5C,MAAa,4BACX;;;;;;;;AASF,MAAa,8BAA8B;;;;;;;;;;;AAY3C,MAAa,mBAAmB,CAC9B,gBACA,2BACD","debugId":"195758e9-bc4f-5373-96e6-e0aef542ce8c"}

package/dist/publish-shim-version.js

@@ -0,0 +1,37 @@
+
+!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]="1cb92f56-68e8-5791-b6c7-c8bca161b130")}catch(e){}}();
+import { warnOnce } from "./log.js";
+import { WORKERD_SHIM_VERSION_HEADER } from "./protocol.js";
+import { hasWebSocket } from "./outbound-capture.js";
+import { WORKERD_SHIM_VERSION } from "./version.js";
+//#region src/publish-shim-version.ts
+/**
+* Stamps this shim's npm package version on the response the browser is about
+* to receive, so the replay runner can tell which bundled shim produced the
+* After screenshots.
+*
+* Returns the response to send, which is not always the one passed in: a
+* `Response` handed back by `fetch` or by an assets binding has immutable
+* headers, and the only way to add one is to rebuild around the same body.
+* Best-effort throughout — a recorder must never break the customer's app.
+*/
+const publishWorkerdShimVersionOnResponse = (response) => {
+	try {
+		response.headers.set(WORKERD_SHIM_VERSION_HEADER, WORKERD_SHIM_VERSION);
+		return response;
+	} catch {}
+	try {
+		if (hasWebSocket(response) || response.status === 101) return response;
+		const rebuilt = new Response(response.body, response);
+		rebuilt.headers.set(WORKERD_SHIM_VERSION_HEADER, WORKERD_SHIM_VERSION);
+		return rebuilt;
+	} catch (error) {
+		warnOnce("publish-shim-version", "Failed to publish the workerd shim version on the response.", error);
+		return response;
+	}
+};
+//#endregion
+export { publishWorkerdShimVersionOnResponse };
+
+//# sourceMappingURL=publish-shim-version.js.map
+//# debugId=1cb92f56-68e8-5791-b6c7-c8bca161b130

package/dist/publish-shim-version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-shim-version.js","sources":["../src/publish-shim-version.ts"],"sourcesContent":["import { warnOnce } from \"./log\";\nimport { hasWebSocket } from \"./outbound-capture\";\nimport { WORKERD_SHIM_VERSION_HEADER } from \"./protocol\";\nimport { WORKERD_SHIM_VERSION } from \"./version\";\n\n/**\n * Stamps this shim's npm package version on the response the browser is about\n * to receive, so the replay runner can tell which bundled shim produced the\n * After screenshots.\n *\n * Returns the response to send, which is not always the one passed in: a\n * `Response` handed back by `fetch` or by an assets binding has immutable\n * headers, and the only way to add one is to rebuild around the same body.\n * Best-effort throughout — a recorder must never break the customer's app.\n */\nexport const publishWorkerdShimVersionOnResponse = (\n  response: Response,\n): Response => {\n  try {\n    response.headers.set(WORKERD_SHIM_VERSION_HEADER, WORKERD_SHIM_VERSION);\n    return response;\n  } catch {\n    // Immutable headers. Fall through and rebuild.\n  }\n\n  try {\n    // A WebSocket upgrade carries the socket rather than a body and cannot\n    // survive being rebuilt.\n    if (hasWebSocket(response) || response.status === 101) {\n      return response;\n    }\n    const rebuilt = new Response(response.body, response);\n    rebuilt.headers.set(WORKERD_SHIM_VERSION_HEADER, WORKERD_SHIM_VERSION);\n    return rebuilt;\n  } catch (error) {\n    warnOnce(\n      \"publish-shim-version\",\n      \"Failed to publish the workerd shim version on the response.\",\n      error,\n    );\n    return response;\n  }\n};\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAeA,MAAa,uCACX,aACa;AACb,KAAI;AACF,WAAS,QAAQ,IAAI,6BAA6B,qBAAqB;AACvE,SAAO;SACD;AAIR,KAAI;AAGF,MAAI,aAAa,SAAS,IAAI,SAAS,WAAW,IAChD,QAAO;EAET,MAAM,UAAU,IAAI,SAAS,SAAS,MAAM,SAAS;AACrD,UAAQ,QAAQ,IAAI,6BAA6B,qBAAqB;AACtE,SAAO;UACA,OAAO;AACd,WACE,wBACA,+DACA,MACD;AACD,SAAO","debugId":"1cb92f56-68e8-5791-b6c7-c8bca161b130"}

package/dist/replay-log-tagging.js

@@ -0,0 +1,57 @@
+
+!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]="962faa5b-f3e8-548c-be10-1e341f1f56bd")}catch(e){}}();
+import { requestCaptureContext } from "./context.js";
+//#region src/replay-log-tagging.ts
+const CONSOLE_METHODS = [
+	"debug",
+	"error",
+	"info",
+	"log",
+	"trace",
+	"warn"
+];
+const CONSOLE_TAGGING_INSTALLED = Symbol.for("meticulous.workerd.consoleReplayTaggingInstalled");
+const REPLAY_ID_LOG_TAG_NAME = "meticulous-replay-id";
+const formatReplayIdLogTag = (replayId) => `[${REPLAY_ID_LOG_TAG_NAME}:${replayId}] `;
+const tagContinuationLines = (value, prefix) => value.replace(/\n(?=.)/g, `\n${prefix}`);
+const prepareConsoleArgument = (value, prefix) => {
+	if (typeof value === "string") return tagContinuationLines(value, prefix);
+	if (value instanceof Error) return tagContinuationLines(value.stack ?? value.message, prefix);
+	return value;
+};
+/**
+* Adds the active request's replay marker. Keeping a string first argument in
+* place preserves formatting such as `console.log("user=%s", id)`. Embedded
+* newlines in strings and Error stacks are tagged too, since container runtimes
+* may emit their continuation lines as separate log records.
+*/
+const createReplayTaggedConsoleMethod = (original) => (...args) => {
+	let outputArgs = args;
+	try {
+		const ctx = requestCaptureContext.getStore();
+		if (ctx?.mode === "replay") {
+			const prefix = formatReplayIdLogTag(ctx.replayId);
+			const preparedArgs = args.map((arg) => prepareConsoleArgument(arg, prefix));
+			outputArgs = typeof preparedArgs[0] === "string" ? [prefix + preparedArgs[0], ...preparedArgs.slice(1)] : [prefix, ...preparedArgs];
+		}
+	} catch {}
+	original(...outputArgs);
+};
+/**
+* Patches Workerd's output-producing console methods once. Outside a replayed
+* request the wrappers are transparent; inside one they resolve the replay id
+* from Workerd's request-scoped AsyncLocalStorage, so concurrent replays cannot
+* label each other's output.
+*/
+const installReplayLogTagging = (methods = console, holder = globalThis) => {
+	if (holder[CONSOLE_TAGGING_INSTALLED]) return;
+	holder[CONSOLE_TAGGING_INSTALLED] = true;
+	for (const method of CONSOLE_METHODS) try {
+		methods[method] = createReplayTaggedConsoleMethod(methods[method].bind(methods));
+	} catch {}
+};
+//#endregion
+export { installReplayLogTagging };
+
+//# sourceMappingURL=replay-log-tagging.js.map
+//# debugId=962faa5b-f3e8-548c-be10-1e341f1f56bd

package/dist/replay-log-tagging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-log-tagging.js","sources":["../src/replay-log-tagging.ts"],"sourcesContent":["import { requestCaptureContext } from \"./context\";\n\ntype ConsoleLogMethod = (...args: unknown[]) => void;\n\nconst CONSOLE_METHODS = [\n  \"debug\",\n  \"error\",\n  \"info\",\n  \"log\",\n  \"trace\",\n  \"warn\",\n] as const;\n\ntype ConsoleMethodName = (typeof CONSOLE_METHODS)[number];\n\nconst CONSOLE_TAGGING_INSTALLED = Symbol.for(\n  \"meticulous.workerd.consoleReplayTaggingInstalled\",\n);\n\n// This literal is part of the persisted log wire format. Keep it pinned here\n// rather than deriving it from the HTTP header, whose name can change\n// independently of logs that have already been written to S3.\nconst REPLAY_ID_LOG_TAG_NAME = \"meticulous-replay-id\";\n\nconst formatReplayIdLogTag = (replayId: string): string =>\n  `[${REPLAY_ID_LOG_TAG_NAME}:${replayId}] `;\n\nconst tagContinuationLines = (value: string, prefix: string): string =>\n  value.replace(/\\n(?=.)/g, `\\n${prefix}`);\n\nconst prepareConsoleArgument = (value: unknown, prefix: string): unknown => {\n  if (typeof value === \"string\") {\n    return tagContinuationLines(value, prefix);\n  }\n  if (value instanceof Error) {\n    return tagContinuationLines(value.stack ?? value.message, prefix);\n  }\n  return value;\n};\n\n/**\n * Adds the active request's replay marker. Keeping a string first argument in\n * place preserves formatting such as `console.log(\"user=%s\", id)`. Embedded\n * newlines in strings and Error stacks are tagged too, since container runtimes\n * may emit their continuation lines as separate log records.\n */\nexport const createReplayTaggedConsoleMethod =\n  (original: ConsoleLogMethod): ConsoleLogMethod =>\n  (...args: unknown[]): void => {\n    let outputArgs = args;\n    try {\n      const ctx = requestCaptureContext.getStore();\n      if (ctx?.mode === \"replay\") {\n        const prefix = formatReplayIdLogTag(ctx.replayId);\n        const preparedArgs = args.map((arg) =>\n          prepareConsoleArgument(arg, prefix),\n        );\n        outputArgs =\n          typeof preparedArgs[0] === \"string\"\n            ? [prefix + preparedArgs[0], ...preparedArgs.slice(1)]\n            : [prefix, ...preparedArgs];\n      }\n    } catch {\n      // Log tagging must never interfere with the customer's logger. The\n      // original call below still receives its untouched arguments.\n    }\n    original(...outputArgs);\n  };\n\n/**\n * Patches Workerd's output-producing console methods once. Outside a replayed\n * request the wrappers are transparent; inside one they resolve the replay id\n * from Workerd's request-scoped AsyncLocalStorage, so concurrent replays cannot\n * label each other's output.\n */\nexport const installReplayLogTagging = (\n  methods = console as unknown as Record<ConsoleMethodName, ConsoleLogMethod>,\n  holder = globalThis as typeof globalThis & {\n    [CONSOLE_TAGGING_INSTALLED]?: boolean;\n  },\n): void => {\n  if (holder[CONSOLE_TAGGING_INSTALLED]) {\n    return;\n  }\n  holder[CONSOLE_TAGGING_INSTALLED] = true;\n\n  for (const method of CONSOLE_METHODS) {\n    try {\n      methods[method] = createReplayTaggedConsoleMethod(\n        methods[method].bind(methods),\n      );\n    } catch {\n      // A runtime may expose a non-writable console method. Keep the remaining\n      // methods useful rather than making replay initialization fail.\n    }\n  }\n};\n"],"names":[],"mappings":";;;;AAIA,MAAM,kBAAkB;CACtB;CACA;CACA;CACA;CACA;CACA;CACD;AAID,MAAM,4BAA4B,OAAO,IACvC,mDACD;AAKD,MAAM,yBAAyB;AAE/B,MAAM,wBAAwB,aAC5B,IAAI,uBAAuB,GAAG,SAAS;AAEzC,MAAM,wBAAwB,OAAe,WAC3C,MAAM,QAAQ,YAAY,KAAK,SAAS;AAE1C,MAAM,0BAA0B,OAAgB,WAA4B;AAC1E,KAAI,OAAO,UAAU,SACnB,QAAO,qBAAqB,OAAO,OAAO;AAE5C,KAAI,iBAAiB,MACnB,QAAO,qBAAqB,MAAM,SAAS,MAAM,SAAS,OAAO;AAEnE,QAAO;;;;;;;;AAST,MAAa,mCACV,cACA,GAAG,SAA0B;CAC5B,IAAI,aAAa;AACjB,KAAI;EACF,MAAM,MAAM,sBAAsB,UAAU;AAC5C,MAAI,KAAK,SAAS,UAAU;GAC1B,MAAM,SAAS,qBAAqB,IAAI,SAAS;GACjD,MAAM,eAAe,KAAK,KAAK,QAC7B,uBAAuB,KAAK,OAAO,CACpC;AACD,gBACE,OAAO,aAAa,OAAO,WACvB,CAAC,SAAS,aAAa,IAAI,GAAG,aAAa,MAAM,EAAE,CAAC,GACpD,CAAC,QAAQ,GAAG,aAAa;;SAE3B;AAIR,UAAS,GAAG,WAAW;;;;;;;;AAS3B,MAAa,2BACX,UAAU,SACV,SAAS,eAGA;AACT,KAAI,OAAO,2BACT;AAEF,QAAO,6BAA6B;AAEpC,MAAK,MAAM,UAAU,gBACnB,KAAI;AACF,UAAQ,UAAU,gCAChB,QAAQ,QAAQ,KAAK,QAAQ,CAC9B;SACK","debugId":"962faa5b-f3e8-548c-be10-1e341f1f56bd"}

package/dist/sidecar-client.js

@@ -1,8 +1,8 @@
 
-!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]="4dc68be9-c4fd-55b2-bd89-c85b8f37cd8d")}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]="4d6a9c0e-a5a7-52d6-8b38-28342d0f79e3")}catch(e){}}();
 import { sidecarFetch } from "./sidecar-transport.js";
 import { warnOnce } from "./log.js";
-import { SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH } from "./protocol.js";
+import { SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_COVERAGE_PATH, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH } from "./protocol.js";
 import { getOriginalFetch } from "./original-fetch.js";
 //#region src/sidecar-client.ts
 /**
@@ -34,6 +34,13 @@ const CAPTURE_POST_TIMEOUT_MS = 2e3;
 * `waitUntil` allows 30s past the response, so this stays well inside its budget.
 */
 const CAPTURE_POST_BINDING_TIMEOUT_MS = 1e4;
+/**
+* Coverage reports are larger than capture events — the first one of an isolate
+* carries the whole id→line map — so they get more headroom than
+* {@link CAPTURE_POST_TIMEOUT_MS}. Still bounded, and for the same reason: an
+* unreachable sidecar must not hold the request context open.
+*/
+const COVERAGE_POST_TIMEOUT_MS = 5e3;
 /** POSTs capture events to the sidecar. Never rejects — reporting failures only warn (once). */
 const postCaptureEvents = async (transport, events) => {
 	const timeoutMs = transport.kind === "binding" ? CAPTURE_POST_BINDING_TIMEOUT_MS : CAPTURE_POST_TIMEOUT_MS;
@@ -125,6 +132,40 @@ const postOutboundFetchLookup = async (fetchFn, sidecarUrl, payload) => {
 	}
 };
 /**
+* Reports one request's line coverage. Runs under `ctx.waitUntil`, so it is off
+* the response path like record-mode capture reporting.
+*
+* Returns `unsupported` when the sidecar will never accept coverage (404 — an
+* older sidecar, or one started without coverage enabled), which the caller
+* latches so it stops paying to serialise hits for the rest of the isolate's
+* life.
+*/
+const postCoverageReport = async (fetchFn, sidecarUrl, payload) => {
+	try {
+		return await withTimeout(COVERAGE_POST_TIMEOUT_MS, async (signal) => {
+			const response = await fetchFn(`${sidecarUrl}${SIDECAR_REPLAY_COVERAGE_PATH}`, {
+				method: "POST",
+				headers: {
+					"content-type": "application/json",
+					[SIDECAR_PROTOCOL_VERSION_HEADER]: "2"
+				},
+				body: JSON.stringify(payload),
+				signal
+			});
+			await response.arrayBuffer().catch(() => void 0);
+			if (response.status === 404) return "unsupported";
+			if (!response.ok) {
+				warnOnce("coverage-rejected", `Meticulous replay sidecar rejected a coverage report (HTTP ${response.status}).`);
+				return "failed";
+			}
+			return "accepted";
+		});
+	} catch (error) {
+		warnOnce("coverage-unreachable", "Could not report line coverage to the Meticulous replay sidecar.", error);
+		return "failed";
+	}
+};
+/**
 * Runs `send` under an abort signal that fires after `ms`, clearing the timer as soon as the
 * call settles — including the response body read, which an abort must still cut short.
 *
@@ -144,7 +185,7 @@ const withTimeout = async (ms, send) => {
 	}
 };
 //#endregion
-export { getReplaySessionInfo, postCaptureEvents, postOutboundFetchLookup };
+export { getReplaySessionInfo, postCaptureEvents, postCoverageReport, postOutboundFetchLookup };
 
 //# sourceMappingURL=sidecar-client.js.map
-//# debugId=4dc68be9-c4fd-55b2-bd89-c85b8f37cd8d
+//# debugId=4d6a9c0e-a5a7-52d6-8b38-28342d0f79e3

package/dist/sidecar-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"sidecar-client.js","sources":["../src/sidecar-client.ts"],"sourcesContent":["import { warnOnce } from \"./log\";\nimport { getOriginalFetch } from \"./original-fetch\";\nimport {\n  type CaptureEvent,\n  type CaptureEventsPayload,\n  type OutboundFetchLookupRequest,\n  type OutboundFetchLookupResponse,\n  type ReplaySessionInfoResponse,\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\";\nimport { sidecarFetch, type SidecarTransport } from \"./sidecar-transport\";\n\ntype FetchFn = typeof globalThis.fetch;\n\n/**\n * Replay calls sit in the request path, unlike record mode's fire-and-forget reporting, so\n * they must be bounded: without a timeout a wedged sidecar would hang every outbound fetch\n * the app makes, and therefore the whole replay, with nothing to look at.\n */\nconst SESSION_INFO_TIMEOUT_MS = 10_000;\nconst LOOKUP_TIMEOUT_MS = 5_000;\n\n/**\n * Capture reporting is off the response path (it runs under `ctx.waitUntil`), so a timeout here\n * is not about latency the app can see — it is about not holding the request context open on a\n * sidecar that will never answer. A refused connection rejects immediately, but a sidecar URL\n * pointing at a host that drops packets rather than refusing them (a firewalled container or LAN\n * address instead of loopback) would otherwise leave the POST pending until the runtime tears the\n * context down, on every captured call.\n *\n * Generous relative to what it bounds: a local sidecar answers a small batch in single-digit\n * milliseconds, so this only ever fires on one that is wedged or unreachable — never on one that\n * is merely busy. Being generous costs nothing because {@link withTimeout} clears the timer the\n * moment the POST settles.\n */\nconst CAPTURE_POST_TIMEOUT_MS = 2_000;\n\n/**\n * The same bound for a service-binding transport, where the sidecar is a Worker that hands the\n * batch to a Durable Object before answering. That object may live in another region and is\n * single-threaded, so a busy one can legitimately take far longer than a loopback process — and\n * failing the report early would drop spans a slightly longer wait would have recorded.\n * `waitUntil` allows 30s past the response, so this stays well inside its budget.\n */\nconst CAPTURE_POST_BINDING_TIMEOUT_MS = 10_000;\n\n/** POSTs capture events to the sidecar. Never rejects — reporting failures only warn (once). */\nexport const postCaptureEvents = async (\n  transport: SidecarTransport,\n  events: CaptureEvent[],\n): Promise<void> => {\n  const timeoutMs =\n    transport.kind === \"binding\"\n      ? CAPTURE_POST_BINDING_TIMEOUT_MS\n      : CAPTURE_POST_TIMEOUT_MS;\n  try {\n    const payload: CaptureEventsPayload = { events };\n    await withTimeout(timeoutMs, async (signal) => {\n      const response = await sidecarFetch(\n        transport,\n        getOriginalFetch(),\n        SIDECAR_EVENTS_PATH,\n        {\n          method: \"POST\",\n          headers: {\n            \"content-type\": \"application/json\",\n            [SIDECAR_PROTOCOL_VERSION_HEADER]: SIDECAR_PROTOCOL_VERSION,\n          },\n          body: JSON.stringify(payload),\n          signal,\n        },\n      );\n      if (!response.ok) {\n        warnOnce(\n          \"sidecar-rejected\",\n          `Meticulous sidecar rejected capture events (HTTP ${response.status}).`,\n        );\n      }\n      await response.arrayBuffer().catch(() => undefined);\n    });\n  } catch (error) {\n    warnOnce(\n      \"sidecar-unreachable\",\n      \"Could not reach the Meticulous backend recorder sidecar — backend session events are not being recorded.\",\n      error,\n    );\n  }\n};\n\n/**\n * Outcome of the session handshake.\n *\n * `unavailable` and `unreachable` both mean \"do not replay\", but they are kept apart\n * because only the first is a settled answer. The caller caches per isolate, and caching a\n * one-off network blip would disable mocking for the rest of the session — silently sending\n * every later outbound call to the real service.\n */\nexport type ReplaySessionInfoResult =\n  /** The sidecar holds mocks for this session. */\n  | { outcome: \"found\"; clockAnchorMs: number | undefined }\n  /** The sidecar answered and will never serve this session: no mocks, or no such route. */\n  | { outcome: \"unavailable\" }\n  /** Could not get an answer — timeout, transport error, 5xx. May succeed later. */\n  | { outcome: \"unreachable\" };\n\n/**\n * Asks whether the sidecar holds mocks for a session, and at what instant to freeze the\n * clock while serving it.\n *\n * A 404 is how a record-only sidecar answers, so it counts as a settled `unavailable`\n * rather than a retryable blip.\n */\nexport const getReplaySessionInfo = async (\n  fetchFn: FetchFn,\n  sidecarUrl: string,\n  frontendSessionId: string,\n): Promise<ReplaySessionInfoResult> => {\n  const url = `${sidecarUrl}${SIDECAR_REPLAY_SESSION_PATH}?sessionId=${encodeURIComponent(\n    frontendSessionId,\n  )}`;\n  try {\n    return await withTimeout(SESSION_INFO_TIMEOUT_MS, async (signal) => {\n      const response = await fetchFn(url, {\n        headers: {\n          [SIDECAR_PROTOCOL_VERSION_HEADER]: SIDECAR_PROTOCOL_VERSION,\n        },\n        signal,\n      });\n      if (!response.ok) {\n        await response.arrayBuffer().catch(() => undefined);\n        // 4xx is the sidecar telling us something definitive — no such route (a record-only\n        // sidecar), or a protocol version it will not speak. Retrying cannot change either.\n        // 5xx may well be a sidecar still finding its feet, so leave it retryable.\n        if (response.status >= 500) {\n          warnOnce(\n            \"replay-session-unreachable\",\n            `Meticulous replay sidecar failed the replay session handshake (HTTP ${response.status}) — will retry on the next request.`,\n          );\n          return { outcome: \"unreachable\" };\n        }\n        warnOnce(\n          \"replay-session-unavailable\",\n          `Meticulous replay sidecar did not recognise the replay session route (HTTP ${response.status}) — outbound calls will not be mocked.`,\n        );\n        return { outcome: \"unavailable\" };\n      }\n      const info = (await response.json()) as ReplaySessionInfoResponse;\n      if (info.found !== true) {\n        warnOnce(\n          \"replay-session-unknown\",\n          \"Meticulous replay sidecar holds no mocks for this session — outbound calls will not be mocked.\",\n        );\n        return { outcome: \"unavailable\" };\n      }\n      return {\n        outcome: \"found\",\n        clockAnchorMs:\n          typeof info.clockAnchorMs === \"number\"\n            ? info.clockAnchorMs\n            : undefined,\n      };\n    });\n  } catch (error) {\n    warnOnce(\n      \"replay-session-unreachable\",\n      \"Could not reach the Meticulous replay sidecar — will retry on the next request.\",\n      error,\n    );\n    return { outcome: \"unreachable\" };\n  }\n};\n\n/**\n * Looks up a recorded response for one outbound call. Never rejects; returns undefined when\n * the sidecar could not be consulted, which the caller fails the request on — an unanswered\n * lookup is not evidence that a real call is safe.\n */\nexport const postOutboundFetchLookup = async (\n  fetchFn: FetchFn,\n  sidecarUrl: string,\n  payload: OutboundFetchLookupRequest,\n): Promise<OutboundFetchLookupResponse | undefined> => {\n  try {\n    return await withTimeout(LOOKUP_TIMEOUT_MS, async (signal) => {\n      const response = await fetchFn(\n        `${sidecarUrl}${SIDECAR_REPLAY_OUTBOUND_FETCH_PATH}`,\n        {\n          method: \"POST\",\n          headers: {\n            \"content-type\": \"application/json\",\n            [SIDECAR_PROTOCOL_VERSION_HEADER]: SIDECAR_PROTOCOL_VERSION,\n          },\n          body: JSON.stringify(payload),\n          signal,\n        },\n      );\n      if (!response.ok) {\n        warnOnce(\n          \"replay-lookup-rejected\",\n          `Meticulous replay sidecar rejected a mock lookup (HTTP ${response.status}).`,\n        );\n        await response.arrayBuffer().catch(() => undefined);\n        return undefined;\n      }\n      return (await response.json()) as OutboundFetchLookupResponse;\n    });\n  } catch (error) {\n    warnOnce(\n      \"replay-lookup-unreachable\",\n      \"Could not reach the Meticulous replay sidecar for a mock lookup — the call will fail.\",\n      error,\n    );\n    return undefined;\n  }\n};\n\n/**\n * Runs `send` under an abort signal that fires after `ms`, clearing the timer as soon as the\n * call settles — including the response body read, which an abort must still cut short.\n *\n * Deliberately not `AbortSignal.timeout`: its timer cannot be cancelled, and a pending timer\n * keeps workerd's request context alive. Bounding a 5ms POST at 2s would then pin the context\n * for the remaining ~2s on every captured call — worse than the unbounded wait it exists to\n * prevent, and on the healthy path rather than the broken one. `body-capture.ts` uses this\n * same clearable shape, for the same reason.\n */\nconst withTimeout = async <T>(\n  ms: number,\n  send: (signal: AbortSignal) => Promise<T>,\n): Promise<T> => {\n  const controller = new AbortController();\n  const timer = setTimeout(() => controller.abort(), ms);\n  try {\n    return await send(controller.signal);\n  } finally {\n    clearTimeout(timer);\n  }\n};\n"],"names":[],"mappings":";;;;;;;;;;;;AAuBA,MAAM,0BAA0B;AAChC,MAAM,oBAAoB;;;;;;;;;;;;;;AAe1B,MAAM,0BAA0B;;;;;;;;AAShC,MAAM,kCAAkC;;AAGxC,MAAa,oBAAoB,OAC/B,WACA,WACkB;CAClB,MAAM,YACJ,UAAU,SAAS,YACf,kCACA;AACN,KAAI;EACF,MAAM,UAAgC,EAAE,QAAQ;AAChD,QAAM,YAAY,WAAW,OAAO,WAAW;GAC7C,MAAM,WAAW,MAAM,aACrB,WACA,kBAAkB,EAClB,qBACA;IACE,QAAQ;IACR,SAAS;KACP,gBAAgB;MACf,kCAAA;KACF;IACD,MAAM,KAAK,UAAU,QAAQ;IAC7B;IACD,CACF;AACD,OAAI,CAAC,SAAS,GACZ,UACE,oBACA,oDAAoD,SAAS,OAAO,IACrE;AAEH,SAAM,SAAS,aAAa,CAAC,YAAY,KAAA,EAAU;IACnD;UACK,OAAO;AACd,WACE,uBACA,4GACA,MACD;;;;;;;;;;AA2BL,MAAa,uBAAuB,OAClC,SACA,YACA,sBACqC;CACrC,MAAM,MAAM,GAAG,aAAa,4BAA4B,aAAa,mBACnE,kBACD;AACD,KAAI;AACF,SAAO,MAAM,YAAY,yBAAyB,OAAO,WAAW;GAClE,MAAM,WAAW,MAAM,QAAQ,KAAK;IAClC,SAAS,GACN,kCAAA,KACF;IACD;IACD,CAAC;AACF,OAAI,CAAC,SAAS,IAAI;AAChB,UAAM,SAAS,aAAa,CAAC,YAAY,KAAA,EAAU;AAInD,QAAI,SAAS,UAAU,KAAK;AAC1B,cACE,8BACA,uEAAuE,SAAS,OAAO,qCACxF;AACD,YAAO,EAAE,SAAS,eAAe;;AAEnC,aACE,8BACA,8EAA8E,SAAS,OAAO,wCAC/F;AACD,WAAO,EAAE,SAAS,eAAe;;GAEnC,MAAM,OAAQ,MAAM,SAAS,MAAM;AACnC,OAAI,KAAK,UAAU,MAAM;AACvB,aACE,0BACA,iGACD;AACD,WAAO,EAAE,SAAS,eAAe;;AAEnC,UAAO;IACL,SAAS;IACT,eACE,OAAO,KAAK,kBAAkB,WAC1B,KAAK,gBACL,KAAA;IACP;IACD;UACK,OAAO;AACd,WACE,8BACA,mFACA,MACD;AACD,SAAO,EAAE,SAAS,eAAe;;;;;;;;AASrC,MAAa,0BAA0B,OACrC,SACA,YACA,YACqD;AACrD,KAAI;AACF,SAAO,MAAM,YAAY,mBAAmB,OAAO,WAAW;GAC5D,MAAM,WAAW,MAAM,QACrB,GAAG,aAAa,sCAChB;IACE,QAAQ;IACR,SAAS;KACP,gBAAgB;MACf,kCAAA;KACF;IACD,MAAM,KAAK,UAAU,QAAQ;IAC7B;IACD,CACF;AACD,OAAI,CAAC,SAAS,IAAI;AAChB,aACE,0BACA,0DAA0D,SAAS,OAAO,IAC3E;AACD,UAAM,SAAS,aAAa,CAAC,YAAY,KAAA,EAAU;AACnD;;AAEF,UAAQ,MAAM,SAAS,MAAM;IAC7B;UACK,OAAO;AACd,WACE,6BACA,yFACA,MACD;AACD;;;;;;;;;;;;;AAcJ,MAAM,cAAc,OAClB,IACA,SACe;CACf,MAAM,aAAa,IAAI,iBAAiB;CACxC,MAAM,QAAQ,iBAAiB,WAAW,OAAO,EAAE,GAAG;AACtD,KAAI;AACF,SAAO,MAAM,KAAK,WAAW,OAAO;WAC5B;AACR,eAAa,MAAM","debugId":"4dc68be9-c4fd-55b2-bd89-c85b8f37cd8d"}
+{"version":3,"file":"sidecar-client.js","sources":["../src/sidecar-client.ts"],"sourcesContent":["import { warnOnce } from \"./log\";\nimport { getOriginalFetch } from \"./original-fetch\";\nimport {\n  type CaptureEvent,\n  type CaptureEventsPayload,\n  type CoverageReportRequest,\n  type OutboundFetchLookupRequest,\n  type OutboundFetchLookupResponse,\n  type ReplaySessionInfoResponse,\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} from \"./protocol\";\nimport { sidecarFetch, type SidecarTransport } from \"./sidecar-transport\";\n\ntype FetchFn = typeof globalThis.fetch;\n\n/**\n * Replay calls sit in the request path, unlike record mode's fire-and-forget reporting, so\n * they must be bounded: without a timeout a wedged sidecar would hang every outbound fetch\n * the app makes, and therefore the whole replay, with nothing to look at.\n */\nconst SESSION_INFO_TIMEOUT_MS = 10_000;\nconst LOOKUP_TIMEOUT_MS = 5_000;\n\n/**\n * Capture reporting is off the response path (it runs under `ctx.waitUntil`), so a timeout here\n * is not about latency the app can see — it is about not holding the request context open on a\n * sidecar that will never answer. A refused connection rejects immediately, but a sidecar URL\n * pointing at a host that drops packets rather than refusing them (a firewalled container or LAN\n * address instead of loopback) would otherwise leave the POST pending until the runtime tears the\n * context down, on every captured call.\n *\n * Generous relative to what it bounds: a local sidecar answers a small batch in single-digit\n * milliseconds, so this only ever fires on one that is wedged or unreachable — never on one that\n * is merely busy. Being generous costs nothing because {@link withTimeout} clears the timer the\n * moment the POST settles.\n */\nconst CAPTURE_POST_TIMEOUT_MS = 2_000;\n\n/**\n * The same bound for a service-binding transport, where the sidecar is a Worker that hands the\n * batch to a Durable Object before answering. That object may live in another region and is\n * single-threaded, so a busy one can legitimately take far longer than a loopback process — and\n * failing the report early would drop spans a slightly longer wait would have recorded.\n * `waitUntil` allows 30s past the response, so this stays well inside its budget.\n */\nconst CAPTURE_POST_BINDING_TIMEOUT_MS = 10_000;\n\n/**\n * Coverage reports are larger than capture events — the first one of an isolate\n * carries the whole id→line map — so they get more headroom than\n * {@link CAPTURE_POST_TIMEOUT_MS}. Still bounded, and for the same reason: an\n * unreachable sidecar must not hold the request context open.\n */\nconst COVERAGE_POST_TIMEOUT_MS = 5_000;\n\n/** POSTs capture events to the sidecar. Never rejects — reporting failures only warn (once). */\nexport const postCaptureEvents = async (\n  transport: SidecarTransport,\n  events: CaptureEvent[],\n): Promise<void> => {\n  const timeoutMs =\n    transport.kind === \"binding\"\n      ? CAPTURE_POST_BINDING_TIMEOUT_MS\n      : CAPTURE_POST_TIMEOUT_MS;\n  try {\n    const payload: CaptureEventsPayload = { events };\n    await withTimeout(timeoutMs, async (signal) => {\n      const response = await sidecarFetch(\n        transport,\n        getOriginalFetch(),\n        SIDECAR_EVENTS_PATH,\n        {\n          method: \"POST\",\n          headers: {\n            \"content-type\": \"application/json\",\n            [SIDECAR_PROTOCOL_VERSION_HEADER]: SIDECAR_PROTOCOL_VERSION,\n          },\n          body: JSON.stringify(payload),\n          signal,\n        },\n      );\n      if (!response.ok) {\n        warnOnce(\n          \"sidecar-rejected\",\n          `Meticulous sidecar rejected capture events (HTTP ${response.status}).`,\n        );\n      }\n      await response.arrayBuffer().catch(() => undefined);\n    });\n  } catch (error) {\n    warnOnce(\n      \"sidecar-unreachable\",\n      \"Could not reach the Meticulous backend recorder sidecar — backend session events are not being recorded.\",\n      error,\n    );\n  }\n};\n\n/**\n * Outcome of the session handshake.\n *\n * `unavailable` and `unreachable` both mean \"do not replay\", but they are kept apart\n * because only the first is a settled answer. The caller caches per isolate, and caching a\n * one-off network blip would disable mocking for the rest of the session — silently sending\n * every later outbound call to the real service.\n */\nexport type ReplaySessionInfoResult =\n  /** The sidecar holds mocks for this session. */\n  | { outcome: \"found\"; clockAnchorMs: number | undefined }\n  /** The sidecar answered and will never serve this session: no mocks, or no such route. */\n  | { outcome: \"unavailable\" }\n  /** Could not get an answer — timeout, transport error, 5xx. May succeed later. */\n  | { outcome: \"unreachable\" };\n\n/**\n * Asks whether the sidecar holds mocks for a session, and at what instant to freeze the\n * clock while serving it.\n *\n * A 404 is how a record-only sidecar answers, so it counts as a settled `unavailable`\n * rather than a retryable blip.\n */\nexport const getReplaySessionInfo = async (\n  fetchFn: FetchFn,\n  sidecarUrl: string,\n  frontendSessionId: string,\n): Promise<ReplaySessionInfoResult> => {\n  const url = `${sidecarUrl}${SIDECAR_REPLAY_SESSION_PATH}?sessionId=${encodeURIComponent(\n    frontendSessionId,\n  )}`;\n  try {\n    return await withTimeout(SESSION_INFO_TIMEOUT_MS, async (signal) => {\n      const response = await fetchFn(url, {\n        headers: {\n          [SIDECAR_PROTOCOL_VERSION_HEADER]: SIDECAR_PROTOCOL_VERSION,\n        },\n        signal,\n      });\n      if (!response.ok) {\n        await response.arrayBuffer().catch(() => undefined);\n        // 4xx is the sidecar telling us something definitive — no such route (a record-only\n        // sidecar), or a protocol version it will not speak. Retrying cannot change either.\n        // 5xx may well be a sidecar still finding its feet, so leave it retryable.\n        if (response.status >= 500) {\n          warnOnce(\n            \"replay-session-unreachable\",\n            `Meticulous replay sidecar failed the replay session handshake (HTTP ${response.status}) — will retry on the next request.`,\n          );\n          return { outcome: \"unreachable\" };\n        }\n        warnOnce(\n          \"replay-session-unavailable\",\n          `Meticulous replay sidecar did not recognise the replay session route (HTTP ${response.status}) — outbound calls will not be mocked.`,\n        );\n        return { outcome: \"unavailable\" };\n      }\n      const info = (await response.json()) as ReplaySessionInfoResponse;\n      if (info.found !== true) {\n        warnOnce(\n          \"replay-session-unknown\",\n          \"Meticulous replay sidecar holds no mocks for this session — outbound calls will not be mocked.\",\n        );\n        return { outcome: \"unavailable\" };\n      }\n      return {\n        outcome: \"found\",\n        clockAnchorMs:\n          typeof info.clockAnchorMs === \"number\"\n            ? info.clockAnchorMs\n            : undefined,\n      };\n    });\n  } catch (error) {\n    warnOnce(\n      \"replay-session-unreachable\",\n      \"Could not reach the Meticulous replay sidecar — will retry on the next request.\",\n      error,\n    );\n    return { outcome: \"unreachable\" };\n  }\n};\n\n/**\n * Looks up a recorded response for one outbound call. Never rejects; returns undefined when\n * the sidecar could not be consulted, which the caller fails the request on — an unanswered\n * lookup is not evidence that a real call is safe.\n */\nexport const postOutboundFetchLookup = async (\n  fetchFn: FetchFn,\n  sidecarUrl: string,\n  payload: OutboundFetchLookupRequest,\n): Promise<OutboundFetchLookupResponse | undefined> => {\n  try {\n    return await withTimeout(LOOKUP_TIMEOUT_MS, async (signal) => {\n      const response = await fetchFn(\n        `${sidecarUrl}${SIDECAR_REPLAY_OUTBOUND_FETCH_PATH}`,\n        {\n          method: \"POST\",\n          headers: {\n            \"content-type\": \"application/json\",\n            [SIDECAR_PROTOCOL_VERSION_HEADER]: SIDECAR_PROTOCOL_VERSION,\n          },\n          body: JSON.stringify(payload),\n          signal,\n        },\n      );\n      if (!response.ok) {\n        warnOnce(\n          \"replay-lookup-rejected\",\n          `Meticulous replay sidecar rejected a mock lookup (HTTP ${response.status}).`,\n        );\n        await response.arrayBuffer().catch(() => undefined);\n        return undefined;\n      }\n      return (await response.json()) as OutboundFetchLookupResponse;\n    });\n  } catch (error) {\n    warnOnce(\n      \"replay-lookup-unreachable\",\n      \"Could not reach the Meticulous replay sidecar for a mock lookup — the call will fail.\",\n      error,\n    );\n    return undefined;\n  }\n};\n\n/**\n * Outcome of a coverage report.\n *\n * `unsupported` and `failed` both mean the report did not land, but only the\n * first is settled: the caller latches `unsupported` and stops collecting, while\n * `failed` leaves the id→line map queued for the next report. Conflating them\n * would either disable coverage on one blip or lose a map permanently.\n */\nexport type CoverageReportOutcome = \"accepted\" | \"unsupported\" | \"failed\";\n\n/**\n * Reports one request's line coverage. Runs under `ctx.waitUntil`, so it is off\n * the response path like record-mode capture reporting.\n *\n * Returns `unsupported` when the sidecar will never accept coverage (404 — an\n * older sidecar, or one started without coverage enabled), which the caller\n * latches so it stops paying to serialise hits for the rest of the isolate's\n * life.\n */\nexport const postCoverageReport = async (\n  fetchFn: FetchFn,\n  sidecarUrl: string,\n  payload: CoverageReportRequest,\n): Promise<CoverageReportOutcome> => {\n  try {\n    return await withTimeout(COVERAGE_POST_TIMEOUT_MS, async (signal) => {\n      const response = await fetchFn(\n        `${sidecarUrl}${SIDECAR_REPLAY_COVERAGE_PATH}`,\n        {\n          method: \"POST\",\n          headers: {\n            \"content-type\": \"application/json\",\n            [SIDECAR_PROTOCOL_VERSION_HEADER]: SIDECAR_PROTOCOL_VERSION,\n          },\n          body: JSON.stringify(payload),\n          signal,\n        },\n      );\n      await response.arrayBuffer().catch(() => undefined);\n      if (response.status === 404) {\n        return \"unsupported\";\n      }\n      if (!response.ok) {\n        warnOnce(\n          \"coverage-rejected\",\n          `Meticulous replay sidecar rejected a coverage report (HTTP ${response.status}).`,\n        );\n        return \"failed\";\n      }\n      return \"accepted\";\n    });\n  } catch (error) {\n    warnOnce(\n      \"coverage-unreachable\",\n      \"Could not report line coverage to the Meticulous replay sidecar.\",\n      error,\n    );\n    return \"failed\";\n  }\n};\n\n/**\n * Runs `send` under an abort signal that fires after `ms`, clearing the timer as soon as the\n * call settles — including the response body read, which an abort must still cut short.\n *\n * Deliberately not `AbortSignal.timeout`: its timer cannot be cancelled, and a pending timer\n * keeps workerd's request context alive. Bounding a 5ms POST at 2s would then pin the context\n * for the remaining ~2s on every captured call — worse than the unbounded wait it exists to\n * prevent, and on the healthy path rather than the broken one. `body-capture.ts` uses this\n * same clearable shape, for the same reason.\n */\nconst withTimeout = async <T>(\n  ms: number,\n  send: (signal: AbortSignal) => Promise<T>,\n): Promise<T> => {\n  const controller = new AbortController();\n  const timer = setTimeout(() => controller.abort(), ms);\n  try {\n    return await send(controller.signal);\n  } finally {\n    clearTimeout(timer);\n  }\n};\n"],"names":[],"mappings":"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","debugId":"4d6a9c0e-a5a7-52d6-8b38-28342d0f79e3"}

package/dist/version.d.ts

@@ -0,0 +1,14 @@
+//#region src/version.d.ts
+/**
+ * npm package version of this shim, baked in at build time. Customers bump
+ * `@alwaysmeticulous/backend-recorder-workerd` independently of our cloud
+ * deploy, so this is the only way a replay can tell which bundled shim
+ * produced its After screenshots.
+ *
+ * Replaced by tsdown's `define`. The guard keeps a direct source import
+ * (vitest, typecheck) working, where no bundler has substituted the value.
+ */
+declare const WORKERD_SHIM_VERSION: string;
+//#endregion
+export { WORKERD_SHIM_VERSION };
+//# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -0,0 +1,18 @@
+//#region src/version.ts
+/**
+* npm package version of this shim, baked in at build time. Customers bump
+* `@alwaysmeticulous/backend-recorder-workerd` independently of our cloud
+* deploy, so this is the only way a replay can tell which bundled shim
+* produced its After screenshots.
+*
+* Replaced by tsdown's `define`. The guard keeps a direct source import
+* (vitest, typecheck) working, where no bundler has substituted the value.
+*/
+
+!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]="90d63f09-8235-55d7-bcd6-ad69626771bc")}catch(e){}}();
+const WORKERD_SHIM_VERSION = "2.330.0";
+//#endregion
+export { WORKERD_SHIM_VERSION };
+
+//# sourceMappingURL=version.js.map
+//# debugId=90d63f09-8235-55d7-bcd6-ad69626771bc

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sources":["../src/version.ts"],"sourcesContent":["declare const TSDOWN_WORKERD_SHIM_VERSION: string;\n\n/**\n * npm package version of this shim, baked in at build time. Customers bump\n * `@alwaysmeticulous/backend-recorder-workerd` independently of our cloud\n * deploy, so this is the only way a replay can tell which bundled shim\n * produced its After screenshots.\n *\n * Replaced by tsdown's `define`. The guard keeps a direct source import\n * (vitest, typecheck) working, where no bundler has substituted the value.\n */\nexport const WORKERD_SHIM_VERSION: string =\n  typeof TSDOWN_WORKERD_SHIM_VERSION !== \"undefined\"\n    ? TSDOWN_WORKERD_SHIM_VERSION\n    : \"0.0.0-dev\";\n"],"names":[],"mappings":";;;;;;;;;;;;AAWA,MAAa,uBAAA","debugId":"90d63f09-8235-55d7-bcd6-ad69626771bc"}

package/dist/virtual-random.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]="0b356a44-c057-5a04-b105-f150b4aab2af")}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]="bae5b317-9875-525c-b298-245193a2eca5")}catch(e){}}();
 import { requestCaptureContext } from "./context.js";
 import { warnOnce } from "./log.js";
 //#region src/virtual-random.ts
@@ -25,10 +25,15 @@ import { warnOnce } from "./log.js";
 * to the inbound request, not the whole replay: two concurrent requests of the same session
 * that race to the same call site would otherwise consume one shared stream in arrival
 * order, and a Fisher-Yates shuffle (or any other draw) would then differ between replays.
-* Each request starts its sequences over from the same session-scoped seed. Each call site
-* on a request returns {@link UNATTRIBUTED_DRAW} for the first {@link FIXED_DRAWS_BEFORE_PRNG}
-* draws and only then starts the PRNG, so a shuffle is identical across concurrent requests
-* and a `while (Math.random() < 0.5)` loop still terminates.
+* Each request starts its sequences over from the same session-scoped seed, and every draw
+* inside a replayed request comes from the seeded PRNG.
+*
+* A call site's first draws used to return one repeated constant before the PRNG started, to
+* damp the seed's positional fragility (see {@link openSequence}). That is gone: returning the
+* same number to consecutive draws is not determinism, it is a collision, and randomness is far
+* more often consumed for uniqueness than for its value. Anything minting an id from
+* consecutive draws — `nanoid`, a hand-rolled uuid, a cache-buster — got one repeated value and
+* broke. The damping was not worth what it cost.
 *
 * Two differences from the Node version, both forced by the runtime:
 *
@@ -59,18 +64,6 @@ const STACK_FRAMES = 10;
 const MAX_STACK_CAPTURES = 1e4;
 const UNKNOWN_CALL_SITE = "unknown";
 /**
-* What a draw returns before its call site's PRNG starts, and what unattributed draws
-* return. Leading digits of pi, so the value is recognisably ours in a diff or a log.
-*/
-const UNATTRIBUTED_DRAW = .3142;
-/**
-* Draws at one call site on one request that return {@link UNATTRIBUTED_DRAW} before the
-* seeded PRNG starts. Large enough that a shuffle stays constant, small enough that
-* `while (Math.random() < 0.5)` still exits.
-*/
-const FIXED_DRAWS_BEFORE_PRNG = 1e3;
-const drawUnattributed = () => UNATTRIBUTED_DRAW;
-/**
 * Held on the inbound request object, so two concurrent requests of one replay cannot share
 * a generator. The seed below stays session-scoped: base and head are different replays of
 * the same recording and must draw identical numbers, and two requests of that recording
@@ -139,11 +132,6 @@ const getCallStack = (frameCount = STACK_FRAMES) => {
 		Error.stackTraceLimit = originalLimit;
 	}
 };
-const stillInFixedDrawPhase = (state, callSite) => {
-	const n = (state.drawsByCallSite.get(callSite) ?? 0) + 1;
-	state.drawsByCallSite.set(callSite, n);
-	return n <= FIXED_DRAWS_BEFORE_PRNG;
-};
 const getRequestState = () => {
 	const ctx = requestCaptureContext.getStore();
 	if (ctx === void 0 || ctx.mode !== "replay") return;
@@ -153,7 +141,6 @@ const getRequestState = () => {
 		frontendSessionId: ctx.frontendSessionId,
 		generatorBySequenceKey: /* @__PURE__ */ new Map(),
 		nextCallerIdByCallSite: /* @__PURE__ */ new Map(),
-		drawsByCallSite: /* @__PURE__ */ new Map(),
 		stackCaptures: 0
 	};
 	stateByRequest.set(ctx, created);
@@ -177,11 +164,16 @@ const getRequestState = () => {
 * separated them (say, an ordinal per call site) would shift every later site's values as soon
 * as a PR added one randomness call, which is the butterfly effect this whole scheme exists to
 * avoid.
+*
+* Because callerIds are handed out in order of first arrival, every draw now depends on that
+* order — there is no longer a fixed-draw phase in front of the PRNG to absorb it, so a PR
+* that routes a new path through a shared helper can shift the values another path draws.
+* That fragility was the reason for the phase; a phase that returned one repeated constant
+* was not a workable way to pay for it.
 */
 const openSequence = () => {
 	const state = getRequestState();
 	if (state === void 0) return;
-	if (stillInFixedDrawPhase(state, getCallStack(1).site)) return drawUnattributed;
 	let sequenceKey = UNKNOWN_CALL_SITE;
 	let callSite = UNKNOWN_CALL_SITE;
 	if (state.stackCaptures < MAX_STACK_CAPTURES) {
@@ -262,4 +254,4 @@ const installVirtualRandom = () => {
 export { installVirtualRandom };
 
 //# sourceMappingURL=virtual-random.js.map
-//# debugId=0b356a44-c057-5a04-b105-f150b4aab2af
+//# debugId=bae5b317-9875-525c-b298-245193a2eca5

package/dist/virtual-random.js.map

@@ -1 +1 @@
-{"version":3,"file":"virtual-random.js","sources":["../src/virtual-random.ts"],"sourcesContent":["import { requestCaptureContext, type RequestReplayContext } from \"./context\";\nimport { warnOnce } from \"./log\";\n\n/**\n * Per-request randomness virtualization for replay mode.\n *\n * Mocking every outbound `fetch` is not enough to make a replay deterministic: a Worker that\n * mints an id (`crypto.randomUUID()` for a guest id, `getRandomValues` for a token) produces\n * a different value in the base replay than in the head replay, so the rendered HTML differs\n * and any screenshot showing that value diffs forever. This replaces the worker's sources of\n * randomness with seeded generators while serving a replayed request, so two replays of the\n * same recorded session render identically.\n *\n * Deliberately a *generator*, not a recording: like the browser replayer we do not capture\n * the numbers the original session produced, we produce fresh ones from a fixed seed. The\n * app still sees plausible random values, and two replays see the same ones.\n *\n * Ported from the Node backend recorder's `replay/virtual-random.ts`, which in turn mirrors\n * the browser replayer's `mockOutRandomNumberGeneration`, including its butterfly-effect\n * containment: a separate sequence per call stack, seeded from a per-call-site counter, so a\n * change in one part of the app does not shift the numbers another part gets, and a shared\n * helper called from two places does not return the same value twice. Sequences are scoped\n * to the inbound request, not the whole replay: two concurrent requests of the same session\n * that race to the same call site would otherwise consume one shared stream in arrival\n * order, and a Fisher-Yates shuffle (or any other draw) would then differ between replays.\n * Each request starts its sequences over from the same session-scoped seed. Each call site\n * on a request returns {@link UNATTRIBUTED_DRAW} for the first {@link FIXED_DRAWS_BEFORE_PRNG}\n * draws and only then starts the PRNG, so a shuffle is identical across concurrent requests\n * and a `while (Math.random() < 0.5)` loop still terminates.\n *\n * Two differences from the Node version, both forced by the runtime:\n *\n *   - the session comes from the request context rather than a session resolver with a\n *     process-wide fallback, because workerd's AsyncLocalStorage propagates reliably from the\n *     inbound handler;\n *   - only the globals workerd actually has are patched — there is no `node:crypto` module to\n *     mutate.\n *\n * Reads outside a replayed request — module evaluation, a recording, a deployed production\n * worker — fall through to the native generators untouched.\n */\n\nconst nativeMathRandom = Math.random.bind(Math);\nconst nativeRandomUUID = globalThis.crypto?.randomUUID?.bind(globalThis.crypto);\nconst nativeGetRandomValues = globalThis.crypto?.getRandomValues?.bind(\n  globalThis.crypto,\n);\n\n/**\n * Frames of the stack that belong to this module and must be skipped to reach the app's call\n * site, counted from the `new Error()` inside {@link getCallStack}.\n *\n * Getting this wrong degrades gracefully rather than breaking: a call site that resolves to\n * one of our own frames merges sequences that should have been separate, which costs\n * butterfly-effect isolation but is still perfectly deterministic.\n */\nconst FRAMES_TO_APP = 3; // getCallStack ← openSequence ← patched global ← app\n\n/** How much of the stack identifies a sequence. Ten frames tells call paths apart cheaply. */\nconst STACK_FRAMES = 10;\n\n/** Stack captures per request, after which sequences are keyed by call site alone. */\nconst MAX_STACK_CAPTURES = 10_000;\n\nconst UNKNOWN_CALL_SITE = \"unknown\";\n\n/**\n * What a draw returns before its call site's PRNG starts, and what unattributed draws\n * return. Leading digits of pi, so the value is recognisably ours in a diff or a log.\n */\nexport const UNATTRIBUTED_DRAW = 0.3142;\n\n/**\n * Draws at one call site on one request that return {@link UNATTRIBUTED_DRAW} before the\n * seeded PRNG starts. Large enough that a shuffle stays constant, small enough that\n * `while (Math.random() < 0.5)` still exits.\n */\nexport const FIXED_DRAWS_BEFORE_PRNG = 1_000;\n\nconst drawUnattributed = (): number => UNATTRIBUTED_DRAW;\n\ninterface RequestRandomState {\n  frontendSessionId: string;\n  generatorBySequenceKey: Map<string, () => number>;\n  nextCallerIdByCallSite: Map<string, number>;\n  drawsByCallSite: Map<string, number>;\n  stackCaptures: number;\n}\n\n/**\n * Held on the inbound request object, so two concurrent requests of one replay cannot share\n * a generator. The seed below stays session-scoped: base and head are different replays of\n * the same recording and must draw identical numbers, and two requests of that recording\n * must draw the same first values rather than racing to consume one stream.\n */\nconst stateByRequest = new WeakMap<RequestReplayContext, RequestRandomState>();\n\n// ---------------------------------------------------------------------------\n// Seeded PRNG (Alea)\n// ---------------------------------------------------------------------------\n\n/**\n * Alea, the same algorithm the browser replayer gets from `seedrandom`. Inlined because this\n * package is published to npm and ships no runtime dependencies — a customer's Worker bundle\n * should not grow for this.\n */\nexport const createSeededRandom = (seed: string): (() => number) => {\n  let n = 0xefc8249d;\n  const mash = (data: string): number => {\n    for (let i = 0; i < data.length; i++) {\n      n += data.charCodeAt(i);\n      let h = 0.02519603282416938 * n;\n      n = h >>> 0;\n      h -= n;\n      h *= n;\n      n = h >>> 0;\n      h -= n;\n      n += h * 0x100000000;\n    }\n    return (n >>> 0) * 2.3283064365386963e-10;\n  };\n\n  let s0 = mash(\" \");\n  let s1 = mash(\" \");\n  let s2 = mash(\" \");\n  let c = 1;\n  s0 -= mash(seed);\n  if (s0 < 0) {\n    s0 += 1;\n  }\n  s1 -= mash(seed);\n  if (s1 < 0) {\n    s1 += 1;\n  }\n  s2 -= mash(seed);\n  if (s2 < 0) {\n    s2 += 1;\n  }\n\n  return () => {\n    const t = 2091639 * s0 + c * 2.3283064365386963e-10;\n    s0 = s1;\n    s1 = s2;\n    c = t | 0;\n    s2 = t - c;\n    return s2;\n  };\n};\n\n// ---------------------------------------------------------------------------\n// Sequence resolution\n// ---------------------------------------------------------------------------\n\nconst getCallStack = (\n  frameCount: number = STACK_FRAMES,\n): { stack: string; site: string } => {\n  const originalLimit = Error.stackTraceLimit;\n  try {\n    Error.stackTraceLimit = FRAMES_TO_APP + frameCount;\n    const stack = new Error().stack;\n    if (stack == null) {\n      return { stack: UNKNOWN_CALL_SITE, site: UNKNOWN_CALL_SITE };\n    }\n    // Line 0 is the \"Error\" header; frame lines follow, innermost first, and the first\n    // FRAMES_TO_APP of them are ours.\n    const lines = stack.split(\"\\n\").slice(FRAMES_TO_APP + 1);\n    return {\n      stack: lines.join(\"\\n\") || UNKNOWN_CALL_SITE,\n      site: lines[0] ?? UNKNOWN_CALL_SITE,\n    };\n  } catch {\n    return { stack: UNKNOWN_CALL_SITE, site: UNKNOWN_CALL_SITE };\n  } finally {\n    Error.stackTraceLimit = originalLimit;\n  }\n};\n\nconst stillInFixedDrawPhase = (\n  state: RequestRandomState,\n  callSite: string,\n): boolean => {\n  const n = (state.drawsByCallSite.get(callSite) ?? 0) + 1;\n  state.drawsByCallSite.set(callSite, n);\n  return n <= FIXED_DRAWS_BEFORE_PRNG;\n};\n\nconst getRequestState = (): RequestRandomState | undefined => {\n  const ctx = requestCaptureContext.getStore();\n  if (ctx === undefined || ctx.mode !== \"replay\") {\n    return undefined;\n  }\n  const existing = stateByRequest.get(ctx);\n  if (existing !== undefined) {\n    return existing;\n  }\n  const created: RequestRandomState = {\n    frontendSessionId: ctx.frontendSessionId,\n    generatorBySequenceKey: new Map(),\n    nextCallerIdByCallSite: new Map(),\n    drawsByCallSite: new Map(),\n    stackCaptures: 0,\n  };\n  stateByRequest.set(ctx, created);\n  return created;\n};\n\n/**\n * The generator for the sequence the current call belongs to, or undefined outside a\n * replayed request.\n *\n * Sequences are keyed by the whole call stack, so a second call down the same path continues\n * the same sequence and gets a different value. The *seed* comes from a counter kept per\n * immediate call site, which is what keeps a shared id helper honest: two call paths through\n * the same `generateId()` share a call site, so they are seeded 0 and 1 and return different\n * ids.\n *\n * Note what the seed deliberately does NOT contain: any part of the stack. Base and head are\n * different builds of the app, so the same logical call site has a different string in each —\n * a seed built from it would change on every rebuild. The consequence, which the browser\n * replayer shares, is that two *distinct* call sites each seen for the first time both seed at\n * 0 and hand out the same first value. That is the accepted trade: an alternative that\n * separated them (say, an ordinal per call site) would shift every later site's values as soon\n * as a PR added one randomness call, which is the butterfly effect this whole scheme exists to\n * avoid.\n */\nconst openSequence = (): (() => number) | undefined => {\n  const state = getRequestState();\n  if (state === undefined) {\n    return undefined;\n  }\n\n  // Called directly so FRAMES_TO_APP still lands on the app. A wrapper here would make\n  // every Math.random share one call site and one fixed-draw budget.\n  if (stillInFixedDrawPhase(state, getCallStack(1).site)) {\n    return drawUnattributed;\n  }\n\n  let sequenceKey = UNKNOWN_CALL_SITE;\n  let callSite = UNKNOWN_CALL_SITE;\n  if (state.stackCaptures < MAX_STACK_CAPTURES) {\n    state.stackCaptures++;\n    const captured = getCallStack();\n    sequenceKey = captured.stack;\n    callSite = captured.site;\n  }\n\n  const existing = state.generatorBySequenceKey.get(sequenceKey);\n  if (existing !== undefined) {\n    return existing;\n  }\n  const callerId = state.nextCallerIdByCallSite.get(callSite) ?? 0;\n  // Seeded from the counter only — never from the call-site or stack string itself. Those embed\n  // bundle filenames and line numbers, which differ between the base build and the head build\n  // of the very same code, so putting one in the seed would reseed every sequence on any\n  // rebuild and bring back exactly the diffs this exists to remove. The strings are grouping\n  // keys, nothing more.\n  const generator = createSeededRandom(\n    `meticulous-random-${state.frontendSessionId}-${callerId}`,\n  );\n  state.generatorBySequenceKey.set(sequenceKey, generator);\n  state.nextCallerIdByCallSite.set(callSite, callerId + 1);\n  return generator;\n};\n\n// ---------------------------------------------------------------------------\n// Derived primitives\n// ---------------------------------------------------------------------------\n\nconst HEX = \"0123456789abcdef\";\n/** The two bits of a v4 UUID's variant field are fixed, leaving these four values. */\nconst VARIANT = \"89ab\";\n\nconst buildUuid = (draw: () => number): string => {\n  let uuid = \"\";\n  for (let i = 0; i < 36; i++) {\n    if (i === 8 || i === 13 || i === 18 || i === 23) {\n      uuid += \"-\";\n    } else if (i === 14) {\n      uuid += \"4\";\n    } else if (i === 19) {\n      uuid += VARIANT[Math.floor(draw() * VARIANT.length)];\n    } else {\n      uuid += HEX[Math.floor(draw() * HEX.length)];\n    }\n  }\n  return uuid;\n};\n\n/**\n * Fills the view's bytes rather than its elements, so every typed array — including the\n * BigInt ones, whose elements cannot be assigned a number — is handled by one path.\n */\nconst fillBytes = (view: ArrayBufferView, draw: () => number): void => {\n  const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);\n  for (let i = 0; i < bytes.length; i++) {\n    bytes[i] = Math.floor(draw() * 256);\n  }\n};\n\n// ---------------------------------------------------------------------------\n// Install\n// ---------------------------------------------------------------------------\n\nlet installed = false;\n\n/**\n * Replaces the worker's sources of randomness with per-request seeded generators. Idempotent,\n * and a no-op failure: a worker that will not let them be replaced still replays, just\n * without randomness virtualisation.\n *\n * Called lazily from the replay branch of the request wrapper rather than at module scope,\n * for the same reasons as the virtual clock: record mode and deployed production workers then\n * pay nothing, and the package declares no `sideEffects`, so a module-scope side effect could\n * legitimately be tree-shaken away by a customer's bundler.\n */\nexport const installVirtualRandom = (): void => {\n  if (installed) {\n    return;\n  }\n  installed = true;\n  try {\n    Math.random = () => openSequence()?.() ?? nativeMathRandom();\n\n    if (globalThis.crypto != null) {\n      Object.defineProperty(globalThis.crypto, \"randomUUID\", {\n        value: (): string => {\n          const draw = openSequence();\n          if (draw !== undefined) {\n            return buildUuid(draw);\n          }\n          return nativeRandomUUID?.() ?? buildUuid(nativeMathRandom);\n        },\n        configurable: true,\n        writable: true,\n      });\n\n      Object.defineProperty(globalThis.crypto, \"getRandomValues\", {\n        value: <T extends ArrayBufferView>(array: T): T => {\n          const draw = openSequence();\n          if (draw === undefined) {\n            return nativeGetRandomValues?.(array) ?? array;\n          }\n          fillBytes(array, draw);\n          return array;\n        },\n        configurable: true,\n        writable: true,\n      });\n    }\n  } catch (error) {\n    warnOnce(\n      \"virtual-random\",\n      \"Could not install the Meticulous replay random-number generators — ids minted by the app will differ between replays.\",\n      error,\n    );\n  }\n};\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,MAAM,mBAAmB,KAAK,OAAO,KAAK,KAAK;AAC/C,MAAM,mBAAmB,WAAW,QAAQ,YAAY,KAAK,WAAW,OAAO;AAC/E,MAAM,wBAAwB,WAAW,QAAQ,iBAAiB,KAChE,WAAW,OACZ;;;;;;;;;AAUD,MAAM,gBAAgB;;AAGtB,MAAM,eAAe;;AAGrB,MAAM,qBAAqB;AAE3B,MAAM,oBAAoB;;;;;AAM1B,MAAa,oBAAoB;;;;;;AAOjC,MAAa,0BAA0B;AAEvC,MAAM,yBAAiC;;;;;;;AAgBvC,MAAM,iCAAiB,IAAI,SAAmD;;;;;;AAW9E,MAAa,sBAAsB,SAAiC;CAClE,IAAI,IAAI;CACR,MAAM,QAAQ,SAAyB;AACrC,OAAK,IAAI,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;AACpC,QAAK,KAAK,WAAW,EAAE;GACvB,IAAI,IAAI,qBAAsB;AAC9B,OAAI,MAAM;AACV,QAAK;AACL,QAAK;AACL,OAAI,MAAM;AACV,QAAK;AACL,QAAK,IAAI;;AAEX,UAAQ,MAAM,KAAK;;CAGrB,IAAI,KAAK,KAAK,IAAI;CAClB,IAAI,KAAK,KAAK,IAAI;CAClB,IAAI,KAAK,KAAK,IAAI;CAClB,IAAI,IAAI;AACR,OAAM,KAAK,KAAK;AAChB,KAAI,KAAK,EACP,OAAM;AAER,OAAM,KAAK,KAAK;AAChB,KAAI,KAAK,EACP,OAAM;AAER,OAAM,KAAK,KAAK;AAChB,KAAI,KAAK,EACP,OAAM;AAGR,cAAa;EACX,MAAM,IAAI,UAAU,KAAK,IAAI;AAC7B,OAAK;AACL,OAAK;AACL,MAAI,IAAI;AACR,OAAK,IAAI;AACT,SAAO;;;AAQX,MAAM,gBACJ,aAAqB,iBACe;CACpC,MAAM,gBAAgB,MAAM;AAC5B,KAAI;AACF,QAAM,kBAAkB,gBAAgB;EACxC,MAAM,yBAAQ,IAAI,OAAO,EAAC;AAC1B,MAAI,SAAS,KACX,QAAO;GAAE,OAAO;GAAmB,MAAM;GAAmB;EAI9D,MAAM,QAAQ,MAAM,MAAM,KAAK,CAAC,MAAM,gBAAgB,EAAE;AACxD,SAAO;GACL,OAAO,MAAM,KAAK,KAAK,IAAI;GAC3B,MAAM,MAAM,MAAM;GACnB;SACK;AACN,SAAO;GAAE,OAAO;GAAmB,MAAM;GAAmB;WACpD;AACR,QAAM,kBAAkB;;;AAI5B,MAAM,yBACJ,OACA,aACY;CACZ,MAAM,KAAK,MAAM,gBAAgB,IAAI,SAAS,IAAI,KAAK;AACvD,OAAM,gBAAgB,IAAI,UAAU,EAAE;AACtC,QAAO,KAAK;;AAGd,MAAM,wBAAwD;CAC5D,MAAM,MAAM,sBAAsB,UAAU;AAC5C,KAAI,QAAQ,KAAA,KAAa,IAAI,SAAS,SACpC;CAEF,MAAM,WAAW,eAAe,IAAI,IAAI;AACxC,KAAI,aAAa,KAAA,EACf,QAAO;CAET,MAAM,UAA8B;EAClC,mBAAmB,IAAI;EACvB,wCAAwB,IAAI,KAAK;EACjC,wCAAwB,IAAI,KAAK;EACjC,iCAAiB,IAAI,KAAK;EAC1B,eAAe;EAChB;AACD,gBAAe,IAAI,KAAK,QAAQ;AAChC,QAAO;;;;;;;;;;;;;;;;;;;;;AAsBT,MAAM,qBAAiD;CACrD,MAAM,QAAQ,iBAAiB;AAC/B,KAAI,UAAU,KAAA,EACZ;AAKF,KAAI,sBAAsB,OAAO,aAAa,EAAE,CAAC,KAAK,CACpD,QAAO;CAGT,IAAI,cAAc;CAClB,IAAI,WAAW;AACf,KAAI,MAAM,gBAAgB,oBAAoB;AAC5C,QAAM;EACN,MAAM,WAAW,cAAc;AAC/B,gBAAc,SAAS;AACvB,aAAW,SAAS;;CAGtB,MAAM,WAAW,MAAM,uBAAuB,IAAI,YAAY;AAC9D,KAAI,aAAa,KAAA,EACf,QAAO;CAET,MAAM,WAAW,MAAM,uBAAuB,IAAI,SAAS,IAAI;CAM/D,MAAM,YAAY,mBAChB,qBAAqB,MAAM,kBAAkB,GAAG,WACjD;AACD,OAAM,uBAAuB,IAAI,aAAa,UAAU;AACxD,OAAM,uBAAuB,IAAI,UAAU,WAAW,EAAE;AACxD,QAAO;;AAOT,MAAM,MAAM;;AAEZ,MAAM,UAAU;AAEhB,MAAM,aAAa,SAA+B;CAChD,IAAI,OAAO;AACX,MAAK,IAAI,IAAI,GAAG,IAAI,IAAI,IACtB,KAAI,MAAM,KAAK,MAAM,MAAM,MAAM,MAAM,MAAM,GAC3C,SAAQ;UACC,MAAM,GACf,SAAQ;UACC,MAAM,GACf,SAAQ,QAAQ,KAAK,MAAM,MAAM,GAAG,EAAe;KAEnD,SAAQ,IAAI,KAAK,MAAM,MAAM,GAAG,GAAW;AAG/C,QAAO;;;;;;AAOT,MAAM,aAAa,MAAuB,SAA6B;CACrE,MAAM,QAAQ,IAAI,WAAW,KAAK,QAAQ,KAAK,YAAY,KAAK,WAAW;AAC3E,MAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,IAChC,OAAM,KAAK,KAAK,MAAM,MAAM,GAAG,IAAI;;AAQvC,IAAI,YAAY;;;;;;;;;;;AAYhB,MAAa,6BAAmC;AAC9C,KAAI,UACF;AAEF,aAAY;AACZ,KAAI;AACF,OAAK,eAAe,cAAc,IAAI,IAAI,kBAAkB;AAE5D,MAAI,WAAW,UAAU,MAAM;AAC7B,UAAO,eAAe,WAAW,QAAQ,cAAc;IACrD,aAAqB;KACnB,MAAM,OAAO,cAAc;AAC3B,SAAI,SAAS,KAAA,EACX,QAAO,UAAU,KAAK;AAExB,YAAO,oBAAoB,IAAI,UAAU,iBAAiB;;IAE5D,cAAc;IACd,UAAU;IACX,CAAC;AAEF,UAAO,eAAe,WAAW,QAAQ,mBAAmB;IAC1D,QAAmC,UAAgB;KACjD,MAAM,OAAO,cAAc;AAC3B,SAAI,SAAS,KAAA,EACX,QAAO,wBAAwB,MAAM,IAAI;AAE3C,eAAU,OAAO,KAAK;AACtB,YAAO;;IAET,cAAc;IACd,UAAU;IACX,CAAC;;UAEG,OAAO;AACd,WACE,kBACA,yHACA,MACD","debugId":"0b356a44-c057-5a04-b105-f150b4aab2af"}
+{"version":3,"file":"virtual-random.js","sources":["../src/virtual-random.ts"],"sourcesContent":["import { requestCaptureContext, type RequestReplayContext } from \"./context\";\nimport { warnOnce } from \"./log\";\n\n/**\n * Per-request randomness virtualization for replay mode.\n *\n * Mocking every outbound `fetch` is not enough to make a replay deterministic: a Worker that\n * mints an id (`crypto.randomUUID()` for a guest id, `getRandomValues` for a token) produces\n * a different value in the base replay than in the head replay, so the rendered HTML differs\n * and any screenshot showing that value diffs forever. This replaces the worker's sources of\n * randomness with seeded generators while serving a replayed request, so two replays of the\n * same recorded session render identically.\n *\n * Deliberately a *generator*, not a recording: like the browser replayer we do not capture\n * the numbers the original session produced, we produce fresh ones from a fixed seed. The\n * app still sees plausible random values, and two replays see the same ones.\n *\n * Ported from the Node backend recorder's `replay/virtual-random.ts`, which in turn mirrors\n * the browser replayer's `mockOutRandomNumberGeneration`, including its butterfly-effect\n * containment: a separate sequence per call stack, seeded from a per-call-site counter, so a\n * change in one part of the app does not shift the numbers another part gets, and a shared\n * helper called from two places does not return the same value twice. Sequences are scoped\n * to the inbound request, not the whole replay: two concurrent requests of the same session\n * that race to the same call site would otherwise consume one shared stream in arrival\n * order, and a Fisher-Yates shuffle (or any other draw) would then differ between replays.\n * Each request starts its sequences over from the same session-scoped seed, and every draw\n * inside a replayed request comes from the seeded PRNG.\n *\n * A call site's first draws used to return one repeated constant before the PRNG started, to\n * damp the seed's positional fragility (see {@link openSequence}). That is gone: returning the\n * same number to consecutive draws is not determinism, it is a collision, and randomness is far\n * more often consumed for uniqueness than for its value. Anything minting an id from\n * consecutive draws — `nanoid`, a hand-rolled uuid, a cache-buster — got one repeated value and\n * broke. The damping was not worth what it cost.\n *\n * Two differences from the Node version, both forced by the runtime:\n *\n *   - the session comes from the request context rather than a session resolver with a\n *     process-wide fallback, because workerd's AsyncLocalStorage propagates reliably from the\n *     inbound handler;\n *   - only the globals workerd actually has are patched — there is no `node:crypto` module to\n *     mutate.\n *\n * Reads outside a replayed request — module evaluation, a recording, a deployed production\n * worker — fall through to the native generators untouched.\n */\n\nconst nativeMathRandom = Math.random.bind(Math);\nconst nativeRandomUUID = globalThis.crypto?.randomUUID?.bind(globalThis.crypto);\nconst nativeGetRandomValues = globalThis.crypto?.getRandomValues?.bind(\n  globalThis.crypto,\n);\n\n/**\n * Frames of the stack that belong to this module and must be skipped to reach the app's call\n * site, counted from the `new Error()` inside {@link getCallStack}.\n *\n * Getting this wrong degrades gracefully rather than breaking: a call site that resolves to\n * one of our own frames merges sequences that should have been separate, which costs\n * butterfly-effect isolation but is still perfectly deterministic.\n */\nconst FRAMES_TO_APP = 3; // getCallStack ← openSequence ← patched global ← app\n\n/** How much of the stack identifies a sequence. Ten frames tells call paths apart cheaply. */\nconst STACK_FRAMES = 10;\n\n/** Stack captures per request, after which sequences are keyed by call site alone. */\nconst MAX_STACK_CAPTURES = 10_000;\n\nconst UNKNOWN_CALL_SITE = \"unknown\";\n\ninterface RequestRandomState {\n  frontendSessionId: string;\n  generatorBySequenceKey: Map<string, () => number>;\n  nextCallerIdByCallSite: Map<string, number>;\n  stackCaptures: number;\n}\n\n/**\n * Held on the inbound request object, so two concurrent requests of one replay cannot share\n * a generator. The seed below stays session-scoped: base and head are different replays of\n * the same recording and must draw identical numbers, and two requests of that recording\n * must draw the same first values rather than racing to consume one stream.\n */\nconst stateByRequest = new WeakMap<RequestReplayContext, RequestRandomState>();\n\n// ---------------------------------------------------------------------------\n// Seeded PRNG (Alea)\n// ---------------------------------------------------------------------------\n\n/**\n * Alea, the same algorithm the browser replayer gets from `seedrandom`. Inlined because this\n * package is published to npm and ships no runtime dependencies — a customer's Worker bundle\n * should not grow for this.\n */\nexport const createSeededRandom = (seed: string): (() => number) => {\n  let n = 0xefc8249d;\n  const mash = (data: string): number => {\n    for (let i = 0; i < data.length; i++) {\n      n += data.charCodeAt(i);\n      let h = 0.02519603282416938 * n;\n      n = h >>> 0;\n      h -= n;\n      h *= n;\n      n = h >>> 0;\n      h -= n;\n      n += h * 0x100000000;\n    }\n    return (n >>> 0) * 2.3283064365386963e-10;\n  };\n\n  let s0 = mash(\" \");\n  let s1 = mash(\" \");\n  let s2 = mash(\" \");\n  let c = 1;\n  s0 -= mash(seed);\n  if (s0 < 0) {\n    s0 += 1;\n  }\n  s1 -= mash(seed);\n  if (s1 < 0) {\n    s1 += 1;\n  }\n  s2 -= mash(seed);\n  if (s2 < 0) {\n    s2 += 1;\n  }\n\n  return () => {\n    const t = 2091639 * s0 + c * 2.3283064365386963e-10;\n    s0 = s1;\n    s1 = s2;\n    c = t | 0;\n    s2 = t - c;\n    return s2;\n  };\n};\n\n// ---------------------------------------------------------------------------\n// Sequence resolution\n// ---------------------------------------------------------------------------\n\nconst getCallStack = (\n  frameCount: number = STACK_FRAMES,\n): { stack: string; site: string } => {\n  const originalLimit = Error.stackTraceLimit;\n  try {\n    Error.stackTraceLimit = FRAMES_TO_APP + frameCount;\n    const stack = new Error().stack;\n    if (stack == null) {\n      return { stack: UNKNOWN_CALL_SITE, site: UNKNOWN_CALL_SITE };\n    }\n    // Line 0 is the \"Error\" header; frame lines follow, innermost first, and the first\n    // FRAMES_TO_APP of them are ours.\n    const lines = stack.split(\"\\n\").slice(FRAMES_TO_APP + 1);\n    return {\n      stack: lines.join(\"\\n\") || UNKNOWN_CALL_SITE,\n      site: lines[0] ?? UNKNOWN_CALL_SITE,\n    };\n  } catch {\n    return { stack: UNKNOWN_CALL_SITE, site: UNKNOWN_CALL_SITE };\n  } finally {\n    Error.stackTraceLimit = originalLimit;\n  }\n};\n\nconst getRequestState = (): RequestRandomState | undefined => {\n  const ctx = requestCaptureContext.getStore();\n  if (ctx === undefined || ctx.mode !== \"replay\") {\n    return undefined;\n  }\n  const existing = stateByRequest.get(ctx);\n  if (existing !== undefined) {\n    return existing;\n  }\n  const created: RequestRandomState = {\n    frontendSessionId: ctx.frontendSessionId,\n    generatorBySequenceKey: new Map(),\n    nextCallerIdByCallSite: new Map(),\n    stackCaptures: 0,\n  };\n  stateByRequest.set(ctx, created);\n  return created;\n};\n\n/**\n * The generator for the sequence the current call belongs to, or undefined outside a\n * replayed request.\n *\n * Sequences are keyed by the whole call stack, so a second call down the same path continues\n * the same sequence and gets a different value. The *seed* comes from a counter kept per\n * immediate call site, which is what keeps a shared id helper honest: two call paths through\n * the same `generateId()` share a call site, so they are seeded 0 and 1 and return different\n * ids.\n *\n * Note what the seed deliberately does NOT contain: any part of the stack. Base and head are\n * different builds of the app, so the same logical call site has a different string in each —\n * a seed built from it would change on every rebuild. The consequence, which the browser\n * replayer shares, is that two *distinct* call sites each seen for the first time both seed at\n * 0 and hand out the same first value. That is the accepted trade: an alternative that\n * separated them (say, an ordinal per call site) would shift every later site's values as soon\n * as a PR added one randomness call, which is the butterfly effect this whole scheme exists to\n * avoid.\n *\n * Because callerIds are handed out in order of first arrival, every draw now depends on that\n * order — there is no longer a fixed-draw phase in front of the PRNG to absorb it, so a PR\n * that routes a new path through a shared helper can shift the values another path draws.\n * That fragility was the reason for the phase; a phase that returned one repeated constant\n * was not a workable way to pay for it.\n */\nconst openSequence = (): (() => number) | undefined => {\n  const state = getRequestState();\n  if (state === undefined) {\n    return undefined;\n  }\n\n  let sequenceKey = UNKNOWN_CALL_SITE;\n  let callSite = UNKNOWN_CALL_SITE;\n  if (state.stackCaptures < MAX_STACK_CAPTURES) {\n    state.stackCaptures++;\n    const captured = getCallStack();\n    sequenceKey = captured.stack;\n    callSite = captured.site;\n  }\n\n  const existing = state.generatorBySequenceKey.get(sequenceKey);\n  if (existing !== undefined) {\n    return existing;\n  }\n  const callerId = state.nextCallerIdByCallSite.get(callSite) ?? 0;\n  // Seeded from the counter only — never from the call-site or stack string itself. Those embed\n  // bundle filenames and line numbers, which differ between the base build and the head build\n  // of the very same code, so putting one in the seed would reseed every sequence on any\n  // rebuild and bring back exactly the diffs this exists to remove. The strings are grouping\n  // keys, nothing more.\n  const generator = createSeededRandom(\n    `meticulous-random-${state.frontendSessionId}-${callerId}`,\n  );\n  state.generatorBySequenceKey.set(sequenceKey, generator);\n  state.nextCallerIdByCallSite.set(callSite, callerId + 1);\n  return generator;\n};\n\n// ---------------------------------------------------------------------------\n// Derived primitives\n// ---------------------------------------------------------------------------\n\nconst HEX = \"0123456789abcdef\";\n/** The two bits of a v4 UUID's variant field are fixed, leaving these four values. */\nconst VARIANT = \"89ab\";\n\nconst buildUuid = (draw: () => number): string => {\n  let uuid = \"\";\n  for (let i = 0; i < 36; i++) {\n    if (i === 8 || i === 13 || i === 18 || i === 23) {\n      uuid += \"-\";\n    } else if (i === 14) {\n      uuid += \"4\";\n    } else if (i === 19) {\n      uuid += VARIANT[Math.floor(draw() * VARIANT.length)];\n    } else {\n      uuid += HEX[Math.floor(draw() * HEX.length)];\n    }\n  }\n  return uuid;\n};\n\n/**\n * Fills the view's bytes rather than its elements, so every typed array — including the\n * BigInt ones, whose elements cannot be assigned a number — is handled by one path.\n */\nconst fillBytes = (view: ArrayBufferView, draw: () => number): void => {\n  const bytes = new Uint8Array(view.buffer, view.byteOffset, view.byteLength);\n  for (let i = 0; i < bytes.length; i++) {\n    bytes[i] = Math.floor(draw() * 256);\n  }\n};\n\n// ---------------------------------------------------------------------------\n// Install\n// ---------------------------------------------------------------------------\n\nlet installed = false;\n\n/**\n * Replaces the worker's sources of randomness with per-request seeded generators. Idempotent,\n * and a no-op failure: a worker that will not let them be replaced still replays, just\n * without randomness virtualisation.\n *\n * Called lazily from the replay branch of the request wrapper rather than at module scope,\n * for the same reasons as the virtual clock: record mode and deployed production workers then\n * pay nothing, and the package declares no `sideEffects`, so a module-scope side effect could\n * legitimately be tree-shaken away by a customer's bundler.\n */\nexport const installVirtualRandom = (): void => {\n  if (installed) {\n    return;\n  }\n  installed = true;\n  try {\n    Math.random = () => openSequence()?.() ?? nativeMathRandom();\n\n    if (globalThis.crypto != null) {\n      Object.defineProperty(globalThis.crypto, \"randomUUID\", {\n        value: (): string => {\n          const draw = openSequence();\n          if (draw !== undefined) {\n            return buildUuid(draw);\n          }\n          return nativeRandomUUID?.() ?? buildUuid(nativeMathRandom);\n        },\n        configurable: true,\n        writable: true,\n      });\n\n      Object.defineProperty(globalThis.crypto, \"getRandomValues\", {\n        value: <T extends ArrayBufferView>(array: T): T => {\n          const draw = openSequence();\n          if (draw === undefined) {\n            return nativeGetRandomValues?.(array) ?? array;\n          }\n          fillBytes(array, draw);\n          return array;\n        },\n        configurable: true,\n        writable: true,\n      });\n    }\n  } catch (error) {\n    warnOnce(\n      \"virtual-random\",\n      \"Could not install the Meticulous replay random-number generators — ids minted by the app will differ between replays.\",\n      error,\n    );\n  }\n};\n"],"names":[],"mappings":"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","debugId":"bae5b317-9875-525c-b298-245193a2eca5"}