@alwaysmeticulous/backend-recorder-workerd 2.319.0 → 2.323.0

package/README.md

@@ -36,6 +36,8 @@ The shim is passive: outgoing requests go straight to their real destination; th
    npx @alwaysmeticulous/cli record backend -- npx wrangler dev
    ```
 
+   If the recorder cannot start — no credentials, no network to fetch the sidecar bundle, an unusable port — the CLI warns and runs your dev command unrecorded rather than failing, so this is safe to leave in a `dev` script.
+
    Or run the sidecar standalone with `npx @alwaysmeticulous/cli record backend` and point the shim at it yourself — the value must be a worker var/binding (host environment variables are not visible inside workerd), e.g. in `.dev.vars`:
 
    ```
@@ -51,12 +53,26 @@ Without `METICULOUS_SIDECAR_URL` (or `options.sidecarUrl`) the wrapper is a comp
 - **Inbound requests** (method, URL, headers, status; no bodies), correlated to the frontend session via the `x-meticulous-session-id` header stamped by the Meticulous frontend recorder.
 - **Outgoing `fetch` calls** made while handling an inbound request: method, URL, headers, status, and request/response bodies (UTF-8, capped at 256 KB; long-lived streams such as SSE are captured truncated).
 - **Calls through `fetch`-shaped bindings** — service bindings and Durable Object stubs — recorded like outgoing fetches, plus the `env` key the call went through. No code change is needed: the binding's `fetch` is instrumented wherever the app reads it from, including via `cloudflare:workers` rather than the handler's `env` argument.
+- **KV namespace operations** — `get`, `getWithMetadata`, `put`, `delete` and `list` on a namespace found on `env`, recorded with the binding name, the key, the call's arguments and the value as JSON (so one `JSON.parse` reconstructs exactly what the app saw, whichever `type` the read asked for). Also no code change needed. A value read as a stream is never read by the recorder — that would take the bytes from the app — and binary values are skipped; both cases are recorded with the reason instead of the value.
+
+Request bodies have secret-looking JSON fields (`clientSecret`, `apiKey`, `token`, `password`, …) replaced with `REDACTED` before they leave the worker, since plenty of APIs carry a credential in the body rather than a header. Response bodies are stored verbatim. A KV `put` value is redacted the same way, for the same reason; a value read back from KV is stored verbatim, like a response body.
+
+## Replay
+
+The same wrapper serves the recording back when Meticulous replays a session against your app: outgoing `fetch` calls are answered from the recording instead of reaching the real service, the clock is frozen at the recorded session's end, and `Math.random` / `crypto.randomUUID` / `crypto.getRandomValues` are seeded so ids the app mints are identical in every replay. Replay is activated by a header the Meticulous replay runner injects, so nothing extra is needed to enable it.
+
+Replay is **hermetic**: a call the recording does not cover fails with a `[backend-recorder] workerd replay: …` error rather than quietly reaching the real service, so a gap in the recording surfaces instead of turning a replay into live traffic. For a call that must stay live during a replay, set the `meticulous-passthrough` header to `true` on the request:
+
+```ts
+await fetch(url, { headers: { "meticulous-passthrough": "true" } });
+```
 
-Request bodies have secret-looking JSON fields (`clientSecret`, `apiKey`, `token`, `password`, …) replaced with `REDACTED` before they leave the worker, since plenty of APIs carry a credential in the body rather than a header. Response bodies are stored verbatim.
+Calls through bindings and KV namespaces are not served from the recording (see Limitations) and are never failed — they always reach the real binding.
 
 ## Limitations
 
-- Bindings other than `fetch`-shaped ones are not captured: KV, D1, R2, Queues, and RPC method calls on a named entrypoint (`env.SVC.someMethod()`) — an RPC method is not a patchable property, so it cannot be intercepted this way.
+- Bindings other than `fetch`-shaped ones and KV namespaces are not captured: D1, R2, Queues, and RPC method calls on a named entrypoint (`env.SVC.someMethod()`) — an RPC method is not a patchable property, so it cannot be intercepted this way.
+- A KV value that is not text is recorded without its value: reading a `stream` would take the bytes away from the app, and binary values are skipped because KV blobs are large and not UTF-8. The operation, key and arguments are still recorded, with `omitted` saying which case it was.
 - Assets bindings are skipped by default (`ASSETS`, `__STATIC_CONTENT`): asset bytes are large and often binary, and asset serving is usually a worker's highest-volume call. Use `options.skipBindings` to skip others.
 - A Durable Object stub is recorded without a binding name, since the stub comes from `namespace.get()` rather than being a binding itself.
 - A binding reference bound before the first instrumented request (`const f = env.SVC.fetch.bind(env.SVC)` at module scope) escapes instrumentation. Holding the binding _object_ and calling `.fetch()` on it per request — what SDKs normally do — is captured.

package/dist/fetch-patch.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]="860c32d0-1245-5707-9cd4-7680ba2d00aa")}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]="e73e6f17-4a76-5ec4-a107-3aa991c55b22")}catch(e){}}();
 import { requestCaptureContext } from "./context.js";
 import { getOriginalFetch, setOriginalFetch } from "./original-fetch.js";
 import { captureOutboundCall } from "./outbound-capture.js";
@@ -13,7 +13,8 @@ const FETCH_PATCHED = Symbol.for("meticulous.workerd.fetchPatched");
 *     never in the request path); request and response are cloned and reported in the
 *     background.
 *   - replaying: decide-then-serve. The call is looked up against the sidecar's mock store
-*     and a recorded response is synthesised, or the real call is let through on a miss.
+*     and a recorded response is synthesised, or the call fails — replay is hermetic unless
+*     the request opts out with the `meticulous-passthrough` header.
 *
 * Outside a withMeticulous request context the patch is a pure pass-through. Idempotent.
 */
@@ -41,4 +42,4 @@ const patchedFetch = async (input, init) => {
 export { installFetchPatch };
 
 //# sourceMappingURL=fetch-patch.js.map
-//# debugId=860c32d0-1245-5707-9cd4-7680ba2d00aa
+//# debugId=e73e6f17-4a76-5ec4-a107-3aa991c55b22

package/dist/fetch-patch.js.map

@@ -1 +1 @@
-{"version":3,"file":"fetch-patch.js","sources":["../src/fetch-patch.ts"],"sourcesContent":["import { requestCaptureContext } from \"./context\";\nimport { getOriginalFetch, setOriginalFetch } from \"./original-fetch\";\nimport { captureOutboundCall } from \"./outbound-capture\";\nimport { replayOutboundCall } from \"./replay-fetch\";\n\ntype FetchFn = typeof globalThis.fetch;\n\n// Symbol.for so a second copy of the shim (e.g. bundled twice) still detects the patch.\nconst FETCH_PATCHED = Symbol.for(\"meticulous.workerd.fetchPatched\");\n\nexport { getOriginalFetch } from \"./original-fetch\";\nexport { headersToRecord } from \"./outbound-capture\";\n\n/**\n * Replaces globalThis.fetch with the mode-appropriate interception:\n *\n *   - recording: a passive capture tee. The real fetch is called directly (the sidecar is\n *     never in the request path); request and response are cloned and reported in the\n *     background.\n *   - replaying: decide-then-serve. The call is looked up against the sidecar's mock store\n *     and a recorded response is synthesised, or the real call is let through on a miss.\n *\n * Outside a withMeticulous request context the patch is a pure pass-through. Idempotent.\n */\nexport const installFetchPatch = (): void => {\n  const holder = globalThis as { [FETCH_PATCHED]?: boolean };\n  if (holder[FETCH_PATCHED]) {\n    return;\n  }\n  holder[FETCH_PATCHED] = true;\n  setOriginalFetch(globalThis.fetch.bind(globalThis));\n  globalThis.fetch = patchedFetch;\n};\n\nconst patchedFetch: FetchFn = async (input, init) => {\n  const original = getOriginalFetch();\n  const ctx = requestCaptureContext.getStore();\n  if (!ctx) {\n    return original(input, init);\n  }\n\n  // Normalize to a single Request. This may consume `input`'s body (when\n  // `input` is a Request), so from here on the real fetch must be given\n  // `request`, never the original arguments.\n  let request: Request;\n  try {\n    request = new Request(input, init);\n  } catch {\n    // Unconstructable arguments — let the real fetch produce the error.\n    return original(input, init);\n  }\n\n  // Never intercept the shim's own traffic to the sidecar. Defence in depth: every\n  // shim → sidecar call already goes through the unpatched fetch.\n  if (request.url.startsWith(`${ctx.sidecarUrl}/`)) {\n    return original(request);\n  }\n\n  return ctx.mode === \"replay\"\n    ? replayOutboundCall(ctx, request, (req) => original(req))\n    : captureOutboundCall(ctx, { kind: \"outbound\" }, request, (req) =>\n        original(req),\n      );\n};\n"],"names":[],"mappings":";;;;;;;AAQA,MAAM,gBAAgB,OAAO,IAAI,kCAAkC;;;;;;;;;;;;AAgBnE,MAAa,0BAAgC;CAC3C,MAAM,SAAS;AACf,KAAI,OAAO,eACT;AAEF,QAAO,iBAAiB;AACxB,kBAAiB,WAAW,MAAM,KAAK,WAAW,CAAC;AACnD,YAAW,QAAQ;;AAGrB,MAAM,eAAwB,OAAO,OAAO,SAAS;CACnD,MAAM,WAAW,kBAAkB;CACnC,MAAM,MAAM,sBAAsB,UAAU;AAC5C,KAAI,CAAC,IACH,QAAO,SAAS,OAAO,KAAK;CAM9B,IAAI;AACJ,KAAI;AACF,YAAU,IAAI,QAAQ,OAAO,KAAK;SAC5B;AAEN,SAAO,SAAS,OAAO,KAAK;;AAK9B,KAAI,QAAQ,IAAI,WAAW,GAAG,IAAI,WAAW,GAAG,CAC9C,QAAO,SAAS,QAAQ;AAG1B,QAAO,IAAI,SAAS,WAChB,mBAAmB,KAAK,UAAU,QAAQ,SAAS,IAAI,CAAC,GACxD,oBAAoB,KAAK,EAAE,MAAM,YAAY,EAAE,UAAU,QACvD,SAAS,IAAI,CACd","debugId":"860c32d0-1245-5707-9cd4-7680ba2d00aa"}
+{"version":3,"file":"fetch-patch.js","sources":["../src/fetch-patch.ts"],"sourcesContent":["import { requestCaptureContext } from \"./context\";\nimport { getOriginalFetch, setOriginalFetch } from \"./original-fetch\";\nimport { captureOutboundCall } from \"./outbound-capture\";\nimport { replayOutboundCall } from \"./replay-fetch\";\n\ntype FetchFn = typeof globalThis.fetch;\n\n// Symbol.for so a second copy of the shim (e.g. bundled twice) still detects the patch.\nconst FETCH_PATCHED = Symbol.for(\"meticulous.workerd.fetchPatched\");\n\nexport { getOriginalFetch } from \"./original-fetch\";\nexport { headersToRecord } from \"./outbound-capture\";\n\n/**\n * Replaces globalThis.fetch with the mode-appropriate interception:\n *\n *   - recording: a passive capture tee. The real fetch is called directly (the sidecar is\n *     never in the request path); request and response are cloned and reported in the\n *     background.\n *   - replaying: decide-then-serve. The call is looked up against the sidecar's mock store\n *     and a recorded response is synthesised, or the call fails — replay is hermetic unless\n *     the request opts out with the `meticulous-passthrough` header.\n *\n * Outside a withMeticulous request context the patch is a pure pass-through. Idempotent.\n */\nexport const installFetchPatch = (): void => {\n  const holder = globalThis as { [FETCH_PATCHED]?: boolean };\n  if (holder[FETCH_PATCHED]) {\n    return;\n  }\n  holder[FETCH_PATCHED] = true;\n  setOriginalFetch(globalThis.fetch.bind(globalThis));\n  globalThis.fetch = patchedFetch;\n};\n\nconst patchedFetch: FetchFn = async (input, init) => {\n  const original = getOriginalFetch();\n  const ctx = requestCaptureContext.getStore();\n  if (!ctx) {\n    return original(input, init);\n  }\n\n  // Normalize to a single Request. This may consume `input`'s body (when\n  // `input` is a Request), so from here on the real fetch must be given\n  // `request`, never the original arguments.\n  let request: Request;\n  try {\n    request = new Request(input, init);\n  } catch {\n    // Unconstructable arguments — let the real fetch produce the error.\n    return original(input, init);\n  }\n\n  // Never intercept the shim's own traffic to the sidecar. Defence in depth: every\n  // shim → sidecar call already goes through the unpatched fetch.\n  if (request.url.startsWith(`${ctx.sidecarUrl}/`)) {\n    return original(request);\n  }\n\n  return ctx.mode === \"replay\"\n    ? replayOutboundCall(ctx, request, (req) => original(req))\n    : captureOutboundCall(ctx, { kind: \"outbound\" }, request, (req) =>\n        original(req),\n      );\n};\n"],"names":[],"mappings":";;;;;;;AAQA,MAAM,gBAAgB,OAAO,IAAI,kCAAkC;;;;;;;;;;;;;AAiBnE,MAAa,0BAAgC;CAC3C,MAAM,SAAS;AACf,KAAI,OAAO,eACT;AAEF,QAAO,iBAAiB;AACxB,kBAAiB,WAAW,MAAM,KAAK,WAAW,CAAC;AACnD,YAAW,QAAQ;;AAGrB,MAAM,eAAwB,OAAO,OAAO,SAAS;CACnD,MAAM,WAAW,kBAAkB;CACnC,MAAM,MAAM,sBAAsB,UAAU;AAC5C,KAAI,CAAC,IACH,QAAO,SAAS,OAAO,KAAK;CAM9B,IAAI;AACJ,KAAI;AACF,YAAU,IAAI,QAAQ,OAAO,KAAK;SAC5B;AAEN,SAAO,SAAS,OAAO,KAAK;;AAK9B,KAAI,QAAQ,IAAI,WAAW,GAAG,IAAI,WAAW,GAAG,CAC9C,QAAO,SAAS,QAAQ;AAG1B,QAAO,IAAI,SAAS,WAChB,mBAAmB,KAAK,UAAU,QAAQ,SAAS,IAAI,CAAC,GACxD,oBAAoB,KAAK,EAAE,MAAM,YAAY,EAAE,UAAU,QACvD,SAAS,IAAI,CACd","debugId":"e73e6f17-4a76-5ec4-a107-3aa991c55b22"}

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { BindingRequestEvent, CAPTURED_HEADERS, CaptureEvent, CaptureEventsPayload, CapturedBody, FRONTEND_SESSION_ID_HEADER, InboundRequestEvent, OutboundFetchLookupRequest, OutboundFetchLookupResponse, OutboundRequestEvent, REPLAY_SIDECAR_URL_HEADER, ReplaySessionInfoResponse, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH } from "./protocol.js";
+import { BindingRequestEvent, CAPTURED_HEADERS, CaptureEvent, CaptureEventsPayload, CapturedBody, FRONTEND_SESSION_ID_HEADER, InboundRequestEvent, KvOmittedReason, KvOperation, KvOperationEvent, METICULOUS_PASSTHROUGH_HEADER, OutboundFetchLookupRequest, OutboundFetchLookupResponse, OutboundRequestEvent, REPLAY_SIDECAR_URL_HEADER, ReplaySessionInfoResponse, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH } from "./protocol.js";
 import { MAX_BODY_CAPTURE_SIZE, readBodyWithCap, readRequestBodyWithCap } from "./body-capture.js";
 import { headersToRecord } from "./outbound-capture.js";
 import { STR_REDACTED, redactRequestBody } from "./redact-body.js";
@@ -18,6 +18,7 @@ interface WithMeticulousOptions {
   /**
    * Binding names to leave unrecorded, on top of the defaults (`ASSETS`,
    * `__STATIC_CONTENT`). Use this for a binding whose traffic is high-volume or binary.
+   * Applies to KV namespaces as well as `fetch`-shaped bindings.
    */
   skipBindings?: readonly string[];
 }
@@ -30,13 +31,18 @@ interface WithMeticulousOptions {
  *   });
  *
  * **Recording** activates on a `METICULOUS_SIDECAR_URL` var/binding (e.g. via `.dev.vars`
- * or `wrangler dev --var`) or `options.sidecarUrl`. Inbound requests and outgoing `fetch`
- * calls are reported to the sidecar as capture events, without affecting the app.
+ * or `wrangler dev --var`) or `options.sidecarUrl`. Inbound requests, outgoing `fetch`
+ * calls, calls through `fetch`-shaped bindings and KV namespace operations are reported to
+ * the sidecar as capture events, without affecting the app.
  *
  * **Replay** activates on the `x-meticulous-backend-replay-sidecar-url` header, injected by
  * the Meticulous replay runner on requests to the app under test. Outgoing `fetch` calls are
- * then served from the recording instead of reaching the real service, and the clock is
- * frozen at the recorded session's end so recorded credentials are still valid. Workerd
+ * then served from the recording instead of reaching the real service — and a call the
+ * recording does not cover fails, rather than quietly becoming live traffic; put a
+ * `meticulous-passthrough: true` header on a request that must stay real. The clock is frozen
+ * at the recorded session's end so recorded credentials are still valid, and `Math.random` /
+ * `crypto.randomUUID` / `crypto.getRandomValues` are seeded so ids the app mints are the same
+ * in every replay of that session. Workerd
  * cannot read container environment variables, which is why per-replay config arrives as a
  * request header; the shim validates it and only honours a loopback / docker-gateway /
  * private-network `http:` origin.
@@ -52,5 +58,5 @@ interface WithMeticulousOptions {
  */
 declare const withMeticulous: <H extends MeticulousWorkerHandler<never>>(handler: H, options?: WithMeticulousOptions) => H;
 //#endregion
-export { type BindingRequestEvent, CAPTURED_HEADERS, type CaptureEvent, type CaptureEventsPayload, type CapturedBody, FRONTEND_SESSION_ID_HEADER, type InboundRequestEvent, MAX_BODY_CAPTURE_SIZE, MeticulousExecutionContext, MeticulousWorkerHandler, type OutboundFetchLookupRequest, type OutboundFetchLookupResponse, type OutboundRequestEvent, REPLAY_SIDECAR_URL_HEADER, type ReplaySessionInfoResponse, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH, STR_REDACTED, WithMeticulousOptions, headersToRecord, readBodyWithCap, readRequestBodyWithCap, redactRequestBody, withMeticulous };
+export { type BindingRequestEvent, CAPTURED_HEADERS, type CaptureEvent, type CaptureEventsPayload, type CapturedBody, FRONTEND_SESSION_ID_HEADER, type InboundRequestEvent, type KvOmittedReason, type KvOperation, type KvOperationEvent, MAX_BODY_CAPTURE_SIZE, METICULOUS_PASSTHROUGH_HEADER, MeticulousExecutionContext, MeticulousWorkerHandler, type OutboundFetchLookupRequest, type OutboundFetchLookupResponse, type OutboundRequestEvent, REPLAY_SIDECAR_URL_HEADER, type ReplaySessionInfoResponse, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH, STR_REDACTED, WithMeticulousOptions, headersToRecord, readBodyWithCap, readRequestBodyWithCap, redactRequestBody, withMeticulous };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":["import { installBindingPatch } from \"./binding-patch\";\nimport {\n  type RequestCaptureContext,\n  type RequestReplayContext,\n  requestCaptureContext,\n} from \"./context\";\nimport { installFetchPatch } from \"./fetch-patch\";\nimport { warnOnce } from \"./log\";\nimport { getOriginalFetch } from \"./original-fetch\";\nimport { headersToRecord } from \"./outbound-capture\";\nimport {\n  FRONTEND_SESSION_ID_HEADER,\n  type InboundRequestEvent,\n  REPLAY_SIDECAR_URL_HEADER,\n} from \"./protocol\";\nimport { parseReplaySidecarUrl } from \"./replay-sidecar-url\";\nimport { getReplaySessionInfo, postCaptureEvents } from \"./sidecar-client\";\nimport { installVirtualClock } from \"./virtual-clock\";\n\nexport type {\n  BindingRequestEvent,\n  CaptureEvent,\n  CapturedBody,\n  CaptureEventsPayload,\n  InboundRequestEvent,\n  OutboundFetchLookupRequest,\n  OutboundFetchLookupResponse,\n  OutboundRequestEvent,\n  ReplaySessionInfoResponse,\n} from \"./protocol\";\nexport {\n  CAPTURED_HEADERS,\n  FRONTEND_SESSION_ID_HEADER,\n  REPLAY_SIDECAR_URL_HEADER,\n  SIDECAR_EVENTS_PATH,\n  SIDECAR_PROTOCOL_VERSION,\n  SIDECAR_PROTOCOL_VERSION_HEADER,\n  SIDECAR_REPLAY_OUTBOUND_FETCH_PATH,\n  SIDECAR_REPLAY_SESSION_PATH,\n} from \"./protocol\";\nexport {\n  MAX_BODY_CAPTURE_SIZE,\n  readBodyWithCap,\n  readRequestBodyWithCap,\n} from \"./body-capture\";\nexport { headersToRecord } from \"./outbound-capture\";\nexport { redactRequestBody, STR_REDACTED } from \"./redact-body\";\n\n/** Structural subset of workerd's ExecutionContext — avoids a @cloudflare/workers-types dependency. */\nexport interface MeticulousExecutionContext {\n  waitUntil(promise: Promise<unknown>): void;\n}\n\n/** Structural subset of an ES-module Worker handler (`export default {...}`). */\nexport interface MeticulousWorkerHandler<Env = never> {\n  fetch(\n    request: Request,\n    env: Env,\n    ctx: MeticulousExecutionContext,\n  ): Response | Promise<Response>;\n}\n\nexport interface WithMeticulousOptions {\n  /** Overrides the sidecar origin; defaults to the METICULOUS_SIDECAR_URL var/binding. */\n  sidecarUrl?: string;\n  /**\n   * Binding names to leave unrecorded, on top of the defaults (`ASSETS`,\n   * `__STATIC_CONTENT`). Use this for a binding whose traffic is high-volume or binary.\n   */\n  skipBindings?: readonly string[];\n}\n\n/**\n * Wraps an ES-module Worker handler so Meticulous can record, or replay, the app's HTTP\n * behaviour:\n *\n *   export default withMeticulous({\n *     async fetch(request, env, ctx) { ... },\n *   });\n *\n * **Recording** activates on a `METICULOUS_SIDECAR_URL` var/binding (e.g. via `.dev.vars`\n * or `wrangler dev --var`) or `options.sidecarUrl`. Inbound requests and outgoing `fetch`\n * calls are reported to the sidecar as capture events, without affecting the app.\n *\n * **Replay** activates on the `x-meticulous-backend-replay-sidecar-url` header, injected by\n * the Meticulous replay runner on requests to the app under test. Outgoing `fetch` calls are\n * then served from the recording instead of reaching the real service, and the clock is\n * frozen at the recorded session's end so recorded credentials are still valid. Workerd\n * cannot read container environment variables, which is why per-replay config arrives as a\n * request header; the shim validates it and only honours a loopback / docker-gateway /\n * private-network `http:` origin.\n *\n * Replay takes precedence over recording when both are configured. A stale\n * `METICULOUS_SIDECAR_URL` baked into an image's `.dev.vars` is far more likely than a\n * spurious replay header (nothing but the replay runner emits it), and letting the env win\n * would silently record a replay instead of mocking it.\n *\n * With neither configured the wrapper is a complete pass-through, so it is safe to keep in\n * deployed code. Requires the `nodejs_als` (or `nodejs_compat`) compatibility flag. A\n * capture failure or unreachable sidecar never affects the app.\n */\nexport const withMeticulous = <H extends MeticulousWorkerHandler<never>>(\n  handler: H,\n  options?: WithMeticulousOptions,\n): H => {\n  const wrappedFetch = async (\n    request: Request,\n    env: unknown,\n    ctx: MeticulousExecutionContext,\n  ): Promise<Response> => {\n    const invokeHandler = () => handler.fetch(request, env as never, ctx);\n\n    let sidecarUrl: string | undefined;\n    let replayContext: RequestReplayContext | undefined;\n    try {\n      replayContext = await resolveReplayContext(request, ctx);\n      sidecarUrl =\n        replayContext === undefined\n          ? resolveSidecarUrl(options, env)\n          : undefined;\n      if (replayContext !== undefined || sidecarUrl !== undefined) {\n        installFetchPatch();\n      }\n      if (sidecarUrl !== undefined) {\n        // Lazily, inside the request path, and never at module scope: the package declares\n        // no `sideEffects` and is built with `platform: \"neutral\"`, so a module-scope side\n        // effect can legitimately be tree-shaken by a customer's bundler. Re-run per\n        // request because `env` is the only handle on the binding instances.\n        //\n        // Record mode only. Binding calls are recorded as their own technology\n        // (`workerd-binding`) and the replay sidecar's store holds only `workerd-fetch`\n        // spans, so there is nothing to serve them from — and patching would only route\n        // them into the capture tee, which POSTs to an events route a replay sidecar 404s.\n        installBindingPatch(env, { skipBindings: options?.skipBindings });\n      }\n    } catch (error) {\n      warnOnce(\n        \"shim-init\",\n        \"Failed to initialize the Meticulous backend recorder shim — recording disabled.\",\n        error,\n      );\n      replayContext = undefined;\n      sidecarUrl = undefined;\n    }\n\n    if (replayContext !== undefined) {\n      // Install the clock before any app code runs, so a module that reads Date.now() at\n      // call time (the firebase auth libraries do) sees the session's frozen instant.\n      installVirtualClock();\n      // No inbound reporting in replay mode: there is no exporter behind the replay\n      // sidecar, and the events route 404s there.\n      return requestCaptureContext.run(replayContext, invokeHandler);\n    }\n\n    if (sidecarUrl === undefined) {\n      return invokeHandler();\n    }\n\n    const captureCtx = buildCaptureContext(request, sidecarUrl, ctx);\n    const startTimeMs = Date.now();\n    let requestHeaders: Record<string, string[]> = {};\n    let method = \"GET\";\n    let url = \"\";\n    try {\n      requestHeaders = headersToRecord(request.headers);\n      method = request.method;\n      url = request.url;\n    } catch (error) {\n      warnOnce(\n        \"inbound-capture\",\n        \"Failed to capture the inbound request.\",\n        error,\n      );\n    }\n\n    const reportInbound = (\n      outcome:\n        | { statusCode: number; responseHeaders: Record<string, string[]> }\n        | { error: string },\n    ): void => {\n      try {\n        const event: InboundRequestEvent = {\n          kind: \"inbound\",\n          requestId: captureCtx.requestId,\n          ...(captureCtx.frontendSessionId !== undefined\n            ? { frontendSessionId: captureCtx.frontendSessionId }\n            : {}),\n          method,\n          url,\n          requestHeaders,\n          startTimeMs,\n          endTimeMs: Date.now(),\n          ...outcome,\n        };\n        captureCtx.waitUntil(\n          postCaptureEvents(getOriginalFetch(), sidecarUrl, [event]),\n        );\n      } catch (error) {\n        warnOnce(\n          \"inbound-report\",\n          \"Failed to report the inbound request.\",\n          error,\n        );\n      }\n    };\n\n    let response: Response;\n    try {\n      response = await requestCaptureContext.run(captureCtx, invokeHandler);\n    } catch (error) {\n      reportInbound({ error: String(error) });\n      throw error;\n    }\n\n    try {\n      reportInbound({\n        statusCode: response.status,\n        responseHeaders: headersToRecord(response.headers),\n      });\n    } catch (error) {\n      warnOnce(\n        \"inbound-report\",\n        \"Failed to report the inbound request.\",\n        error,\n      );\n    }\n    return response;\n  };\n\n  // The wrapper only replaces `fetch` (same call signature), but TypeScript\n  // cannot verify a spread against the bare generic H.\n  return { ...handler, fetch: wrappedFetch } as H;\n};\n\n/**\n * Whether this request should be replayed, and the context to serve it under.\n *\n * Both the session id and a usable sidecar URL must be present: mocks are indexed per\n * session, so replay without a session id could only miss. The sidecar is consulted once\n * per (sidecar, session) per isolate to confirm it holds mocks and to learn the clock\n * anchor — a sidecar that does not recognise the session, or the route, means replay is\n * unavailable and the request runs normally.\n */\nconst resolveReplayContext = async (\n  request: Request,\n  ctx: MeticulousExecutionContext,\n): Promise<RequestReplayContext | undefined> => {\n  let sidecarUrl: string | undefined;\n  let frontendSessionId: string | undefined;\n  try {\n    sidecarUrl = parseReplaySidecarUrl(\n      request.headers.get(REPLAY_SIDECAR_URL_HEADER),\n    );\n    frontendSessionId =\n      request.headers.get(FRONTEND_SESSION_ID_HEADER) ?? undefined;\n  } catch {\n    return undefined;\n  }\n  if (sidecarUrl === undefined || frontendSessionId === undefined) {\n    return undefined;\n  }\n\n  const info = await getCachedReplaySessionInfo(sidecarUrl, frontendSessionId);\n  if (info === null) {\n    return undefined;\n  }\n\n  return {\n    mode: \"replay\",\n    requestId: crypto.randomUUID(),\n    frontendSessionId,\n    sidecarUrl,\n    clockAnchorMs: info.clockAnchorMs,\n    waitUntil: buildWaitUntil(ctx),\n  };\n};\n\n// Caches the promise, not the result, so concurrent first requests share one round trip.\n// Bounded so a stream of unrecognised session ids cannot grow it without limit.\nconst MAX_CACHED_SESSIONS = 50;\nconst replaySessionInfoCache = new Map<\n  string,\n  Promise<{ clockAnchorMs: number | undefined } | null>\n>();\n\nconst getCachedReplaySessionInfo = (\n  sidecarUrl: string,\n  frontendSessionId: string,\n): Promise<{ clockAnchorMs: number | undefined } | null> => {\n  const key = `${sidecarUrl}\u0000${frontendSessionId}`;\n  const cached = replaySessionInfoCache.get(key);\n  if (cached !== undefined) {\n    return cached;\n  }\n  const pending = getReplaySessionInfo(\n    getOriginalFetch(),\n    sidecarUrl,\n    frontendSessionId,\n  ).then((result) => {\n    if (result.outcome === \"unreachable\") {\n      // Only settled answers are worth keeping. Caching a timeout or transport blip would\n      // disable mocking for this session for the life of the isolate, quietly sending every\n      // later outbound call to the real service — the failure this path exists to prevent.\n      // Dropping the entry costs one extra handshake and lets the next request recover.\n      replaySessionInfoCache.delete(key);\n      return null;\n    }\n    return result.outcome === \"found\"\n      ? { clockAnchorMs: result.clockAnchorMs }\n      : null;\n  });\n  if (replaySessionInfoCache.size >= MAX_CACHED_SESSIONS) {\n    const oldest = replaySessionInfoCache.keys().next();\n    if (!oldest.done) {\n      replaySessionInfoCache.delete(oldest.value);\n    }\n  }\n  replaySessionInfoCache.set(key, pending);\n  return pending;\n};\n\nconst resolveSidecarUrl = (\n  options: WithMeticulousOptions | undefined,\n  env: unknown,\n): string | undefined => {\n  const fromEnv =\n    env !== null && typeof env === \"object\"\n      ? (env as Record<string, unknown>)[\"METICULOUS_SIDECAR_URL\"]\n      : undefined;\n  const raw = options?.sidecarUrl ?? fromEnv;\n  if (typeof raw !== \"string\" || raw.length === 0) {\n    return undefined;\n  }\n  return raw.replace(/\\/+$/, \"\");\n};\n\nconst buildCaptureContext = (\n  request: Request,\n  sidecarUrl: string,\n  ctx: MeticulousExecutionContext,\n): RequestCaptureContext => {\n  let frontendSessionId: string | undefined;\n  try {\n    frontendSessionId =\n      request.headers.get(FRONTEND_SESSION_ID_HEADER) ?? undefined;\n  } catch {\n    frontendSessionId = undefined;\n  }\n  return {\n    mode: \"record\",\n    requestId: crypto.randomUUID(),\n    frontendSessionId,\n    sidecarUrl,\n    waitUntil: buildWaitUntil(ctx),\n  };\n};\n\nconst buildWaitUntil =\n  (ctx: MeticulousExecutionContext) =>\n  (promise: Promise<unknown>): void => {\n    try {\n      ctx.waitUntil(promise);\n    } catch (error) {\n      warnOnce(\n        \"wait-until\",\n        \"ctx.waitUntil failed — capture events may be lost.\",\n        error,\n      );\n    }\n  };\n"],"names":[],"mappings":"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","debugId":"8791d2a2-34c5-5ddf-81a1-7f74833160ef"}
+{"version":3,"file":"index.js","sources":["../src/index.ts"],"sourcesContent":["import { installBindingPatch } from \"./binding-patch\";\nimport {\n  type RequestCaptureContext,\n  type RequestReplayContext,\n  requestCaptureContext,\n} from \"./context\";\nimport { installFetchPatch } from \"./fetch-patch\";\nimport { installKvPatch } from \"./kv-patch\";\nimport { warnOnce } from \"./log\";\nimport { getOriginalFetch } from \"./original-fetch\";\nimport { headersToRecord } from \"./outbound-capture\";\nimport {\n  FRONTEND_SESSION_ID_HEADER,\n  type InboundRequestEvent,\n  REPLAY_SIDECAR_URL_HEADER,\n} from \"./protocol\";\nimport { parseReplaySidecarUrl } from \"./replay-sidecar-url\";\nimport { getReplaySessionInfo, postCaptureEvents } from \"./sidecar-client\";\nimport { installVirtualClock } from \"./virtual-clock\";\nimport { installVirtualRandom } from \"./virtual-random\";\n\nexport type {\n  BindingRequestEvent,\n  CaptureEvent,\n  CapturedBody,\n  CaptureEventsPayload,\n  InboundRequestEvent,\n  KvOmittedReason,\n  KvOperation,\n  KvOperationEvent,\n  OutboundFetchLookupRequest,\n  OutboundFetchLookupResponse,\n  OutboundRequestEvent,\n  ReplaySessionInfoResponse,\n} from \"./protocol\";\nexport {\n  CAPTURED_HEADERS,\n  FRONTEND_SESSION_ID_HEADER,\n  METICULOUS_PASSTHROUGH_HEADER,\n  REPLAY_SIDECAR_URL_HEADER,\n  SIDECAR_EVENTS_PATH,\n  SIDECAR_PROTOCOL_VERSION,\n  SIDECAR_PROTOCOL_VERSION_HEADER,\n  SIDECAR_REPLAY_OUTBOUND_FETCH_PATH,\n  SIDECAR_REPLAY_SESSION_PATH,\n} from \"./protocol\";\nexport {\n  MAX_BODY_CAPTURE_SIZE,\n  readBodyWithCap,\n  readRequestBodyWithCap,\n} from \"./body-capture\";\nexport { headersToRecord } from \"./outbound-capture\";\nexport { redactRequestBody, STR_REDACTED } from \"./redact-body\";\n\n/** Structural subset of workerd's ExecutionContext — avoids a @cloudflare/workers-types dependency. */\nexport interface MeticulousExecutionContext {\n  waitUntil(promise: Promise<unknown>): void;\n}\n\n/** Structural subset of an ES-module Worker handler (`export default {...}`). */\nexport interface MeticulousWorkerHandler<Env = never> {\n  fetch(\n    request: Request,\n    env: Env,\n    ctx: MeticulousExecutionContext,\n  ): Response | Promise<Response>;\n}\n\nexport interface WithMeticulousOptions {\n  /** Overrides the sidecar origin; defaults to the METICULOUS_SIDECAR_URL var/binding. */\n  sidecarUrl?: string;\n  /**\n   * Binding names to leave unrecorded, on top of the defaults (`ASSETS`,\n   * `__STATIC_CONTENT`). Use this for a binding whose traffic is high-volume or binary.\n   * Applies to KV namespaces as well as `fetch`-shaped bindings.\n   */\n  skipBindings?: readonly string[];\n}\n\n/**\n * Wraps an ES-module Worker handler so Meticulous can record, or replay, the app's HTTP\n * behaviour:\n *\n *   export default withMeticulous({\n *     async fetch(request, env, ctx) { ... },\n *   });\n *\n * **Recording** activates on a `METICULOUS_SIDECAR_URL` var/binding (e.g. via `.dev.vars`\n * or `wrangler dev --var`) or `options.sidecarUrl`. Inbound requests, outgoing `fetch`\n * calls, calls through `fetch`-shaped bindings and KV namespace operations are reported to\n * the sidecar as capture events, without affecting the app.\n *\n * **Replay** activates on the `x-meticulous-backend-replay-sidecar-url` header, injected by\n * the Meticulous replay runner on requests to the app under test. Outgoing `fetch` calls are\n * then served from the recording instead of reaching the real service — and a call the\n * recording does not cover fails, rather than quietly becoming live traffic; put a\n * `meticulous-passthrough: true` header on a request that must stay real. The clock is frozen\n * at the recorded session's end so recorded credentials are still valid, and `Math.random` /\n * `crypto.randomUUID` / `crypto.getRandomValues` are seeded so ids the app mints are the same\n * in every replay of that session. Workerd\n * cannot read container environment variables, which is why per-replay config arrives as a\n * request header; the shim validates it and only honours a loopback / docker-gateway /\n * private-network `http:` origin.\n *\n * Replay takes precedence over recording when both are configured. A stale\n * `METICULOUS_SIDECAR_URL` baked into an image's `.dev.vars` is far more likely than a\n * spurious replay header (nothing but the replay runner emits it), and letting the env win\n * would silently record a replay instead of mocking it.\n *\n * With neither configured the wrapper is a complete pass-through, so it is safe to keep in\n * deployed code. Requires the `nodejs_als` (or `nodejs_compat`) compatibility flag. A\n * capture failure or unreachable sidecar never affects the app.\n */\nexport const withMeticulous = <H extends MeticulousWorkerHandler<never>>(\n  handler: H,\n  options?: WithMeticulousOptions,\n): H => {\n  const wrappedFetch = async (\n    request: Request,\n    env: unknown,\n    ctx: MeticulousExecutionContext,\n  ): Promise<Response> => {\n    const invokeHandler = () => handler.fetch(request, env as never, ctx);\n\n    let sidecarUrl: string | undefined;\n    let replayContext: RequestReplayContext | undefined;\n    try {\n      replayContext = await resolveReplayContext(request, ctx);\n      sidecarUrl =\n        replayContext === undefined\n          ? resolveSidecarUrl(options, env)\n          : undefined;\n      if (replayContext !== undefined || sidecarUrl !== undefined) {\n        installFetchPatch();\n      }\n      if (sidecarUrl !== undefined) {\n        // Lazily, inside the request path, and never at module scope: the package declares\n        // no `sideEffects` and is built with `platform: \"neutral\"`, so a module-scope side\n        // effect can legitimately be tree-shaken by a customer's bundler. Re-run per\n        // request because `env` is the only handle on the binding instances.\n        //\n        // Record mode only. Binding and KV calls are recorded as their own technologies\n        // (`workerd-binding`, `workerd-kv`) and the replay sidecar's store holds only\n        // `workerd-fetch` spans, so there is nothing to serve them from — and patching would\n        // only route them into the capture tee, which POSTs to an events route a replay\n        // sidecar 404s.\n        installBindingPatch(env, { skipBindings: options?.skipBindings });\n        installKvPatch(env, { skipBindings: options?.skipBindings });\n      }\n    } catch (error) {\n      warnOnce(\n        \"shim-init\",\n        \"Failed to initialize the Meticulous backend recorder shim — recording disabled.\",\n        error,\n      );\n      replayContext = undefined;\n      sidecarUrl = undefined;\n    }\n\n    if (replayContext !== undefined) {\n      // Install the clock before any app code runs, so a module that reads Date.now() at\n      // call time (the firebase auth libraries do) sees the session's frozen instant.\n      installVirtualClock();\n      // Likewise the random generators: an id the app mints during SSR (a guest id, a\n      // request id) otherwise differs between a base and a head replay, and every rendered\n      // page carrying it diffs forever.\n      installVirtualRandom();\n      // No inbound reporting in replay mode: there is no exporter behind the replay\n      // sidecar, and the events route 404s there.\n      return requestCaptureContext.run(replayContext, invokeHandler);\n    }\n\n    if (sidecarUrl === undefined) {\n      return invokeHandler();\n    }\n\n    const captureCtx = buildCaptureContext(request, sidecarUrl, ctx);\n    const startTimeMs = Date.now();\n    let requestHeaders: Record<string, string[]> = {};\n    let method = \"GET\";\n    let url = \"\";\n    try {\n      requestHeaders = headersToRecord(request.headers);\n      method = request.method;\n      url = request.url;\n    } catch (error) {\n      warnOnce(\n        \"inbound-capture\",\n        \"Failed to capture the inbound request.\",\n        error,\n      );\n    }\n\n    const reportInbound = (\n      outcome:\n        | { statusCode: number; responseHeaders: Record<string, string[]> }\n        | { error: string },\n    ): void => {\n      try {\n        const event: InboundRequestEvent = {\n          kind: \"inbound\",\n          requestId: captureCtx.requestId,\n          ...(captureCtx.frontendSessionId !== undefined\n            ? { frontendSessionId: captureCtx.frontendSessionId }\n            : {}),\n          method,\n          url,\n          requestHeaders,\n          startTimeMs,\n          endTimeMs: Date.now(),\n          ...outcome,\n        };\n        captureCtx.waitUntil(\n          postCaptureEvents(getOriginalFetch(), sidecarUrl, [event]),\n        );\n      } catch (error) {\n        warnOnce(\n          \"inbound-report\",\n          \"Failed to report the inbound request.\",\n          error,\n        );\n      }\n    };\n\n    let response: Response;\n    try {\n      response = await requestCaptureContext.run(captureCtx, invokeHandler);\n    } catch (error) {\n      reportInbound({ error: String(error) });\n      throw error;\n    }\n\n    try {\n      reportInbound({\n        statusCode: response.status,\n        responseHeaders: headersToRecord(response.headers),\n      });\n    } catch (error) {\n      warnOnce(\n        \"inbound-report\",\n        \"Failed to report the inbound request.\",\n        error,\n      );\n    }\n    return response;\n  };\n\n  // The wrapper only replaces `fetch` (same call signature), but TypeScript\n  // cannot verify a spread against the bare generic H.\n  return { ...handler, fetch: wrappedFetch } as H;\n};\n\n/**\n * Whether this request should be replayed, and the context to serve it under.\n *\n * Both the session id and a usable sidecar URL must be present: mocks are indexed per\n * session, so replay without a session id could only miss. The sidecar is consulted once\n * per (sidecar, session) per isolate to confirm it holds mocks and to learn the clock\n * anchor — a sidecar that does not recognise the session, or the route, means replay is\n * unavailable and the request runs normally.\n */\nconst resolveReplayContext = async (\n  request: Request,\n  ctx: MeticulousExecutionContext,\n): Promise<RequestReplayContext | undefined> => {\n  let sidecarUrl: string | undefined;\n  let frontendSessionId: string | undefined;\n  try {\n    sidecarUrl = parseReplaySidecarUrl(\n      request.headers.get(REPLAY_SIDECAR_URL_HEADER),\n    );\n    frontendSessionId =\n      request.headers.get(FRONTEND_SESSION_ID_HEADER) ?? undefined;\n  } catch {\n    return undefined;\n  }\n  if (sidecarUrl === undefined || frontendSessionId === undefined) {\n    return undefined;\n  }\n\n  const info = await getCachedReplaySessionInfo(sidecarUrl, frontendSessionId);\n  if (info === null) {\n    return undefined;\n  }\n\n  return {\n    mode: \"replay\",\n    requestId: crypto.randomUUID(),\n    frontendSessionId,\n    sidecarUrl,\n    clockAnchorMs: info.clockAnchorMs,\n    waitUntil: buildWaitUntil(ctx),\n  };\n};\n\n// Caches the promise, not the result, so concurrent first requests share one round trip.\n// Bounded so a stream of unrecognised session ids cannot grow it without limit.\nconst MAX_CACHED_SESSIONS = 50;\nconst replaySessionInfoCache = new Map<\n  string,\n  Promise<{ clockAnchorMs: number | undefined } | null>\n>();\n\nconst getCachedReplaySessionInfo = (\n  sidecarUrl: string,\n  frontendSessionId: string,\n): Promise<{ clockAnchorMs: number | undefined } | null> => {\n  const key = `${sidecarUrl}\u0000${frontendSessionId}`;\n  const cached = replaySessionInfoCache.get(key);\n  if (cached !== undefined) {\n    return cached;\n  }\n  const pending = getReplaySessionInfo(\n    getOriginalFetch(),\n    sidecarUrl,\n    frontendSessionId,\n  ).then((result) => {\n    if (result.outcome === \"unreachable\") {\n      // Only settled answers are worth keeping. Caching a timeout or transport blip would\n      // disable mocking for this session for the life of the isolate, quietly sending every\n      // later outbound call to the real service — the failure this path exists to prevent.\n      // Dropping the entry costs one extra handshake and lets the next request recover.\n      replaySessionInfoCache.delete(key);\n      return null;\n    }\n    return result.outcome === \"found\"\n      ? { clockAnchorMs: result.clockAnchorMs }\n      : null;\n  });\n  if (replaySessionInfoCache.size >= MAX_CACHED_SESSIONS) {\n    const oldest = replaySessionInfoCache.keys().next();\n    if (!oldest.done) {\n      replaySessionInfoCache.delete(oldest.value);\n    }\n  }\n  replaySessionInfoCache.set(key, pending);\n  return pending;\n};\n\nconst resolveSidecarUrl = (\n  options: WithMeticulousOptions | undefined,\n  env: unknown,\n): string | undefined => {\n  const fromEnv =\n    env !== null && typeof env === \"object\"\n      ? (env as Record<string, unknown>)[\"METICULOUS_SIDECAR_URL\"]\n      : undefined;\n  const raw = options?.sidecarUrl ?? fromEnv;\n  if (typeof raw !== \"string\" || raw.length === 0) {\n    return undefined;\n  }\n  return raw.replace(/\\/+$/, \"\");\n};\n\nconst buildCaptureContext = (\n  request: Request,\n  sidecarUrl: string,\n  ctx: MeticulousExecutionContext,\n): RequestCaptureContext => {\n  let frontendSessionId: string | undefined;\n  try {\n    frontendSessionId =\n      request.headers.get(FRONTEND_SESSION_ID_HEADER) ?? undefined;\n  } catch {\n    frontendSessionId = undefined;\n  }\n  return {\n    mode: \"record\",\n    requestId: crypto.randomUUID(),\n    frontendSessionId,\n    sidecarUrl,\n    waitUntil: buildWaitUntil(ctx),\n  };\n};\n\nconst buildWaitUntil =\n  (ctx: MeticulousExecutionContext) =>\n  (promise: Promise<unknown>): void => {\n    try {\n      ctx.waitUntil(promise);\n    } catch (error) {\n      warnOnce(\n        \"wait-until\",\n        \"ctx.waitUntil failed — capture events may be lost.\",\n        error,\n      );\n    }\n  };\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiHA,MAAa,kBACX,SACA,YACM;CACN,MAAM,eAAe,OACnB,SACA,KACA,QACsB;EACtB,MAAM,sBAAsB,QAAQ,MAAM,SAAS,KAAc,IAAI;EAErE,IAAI;EACJ,IAAI;AACJ,MAAI;AACF,mBAAgB,MAAM,qBAAqB,SAAS,IAAI;AACxD,gBACE,kBAAkB,KAAA,IACd,kBAAkB,SAAS,IAAI,GAC/B,KAAA;AACN,OAAI,kBAAkB,KAAA,KAAa,eAAe,KAAA,EAChD,oBAAmB;AAErB,OAAI,eAAe,KAAA,GAAW;AAW5B,wBAAoB,KAAK,EAAE,cAAc,SAAS,cAAc,CAAC;AACjE,mBAAe,KAAK,EAAE,cAAc,SAAS,cAAc,CAAC;;WAEvD,OAAO;AACd,YACE,aACA,mFACA,MACD;AACD,mBAAgB,KAAA;AAChB,gBAAa,KAAA;;AAGf,MAAI,kBAAkB,KAAA,GAAW;AAG/B,wBAAqB;AAIrB,yBAAsB;AAGtB,UAAO,sBAAsB,IAAI,eAAe,cAAc;;AAGhE,MAAI,eAAe,KAAA,EACjB,QAAO,eAAe;EAGxB,MAAM,aAAa,oBAAoB,SAAS,YAAY,IAAI;EAChE,MAAM,cAAc,KAAK,KAAK;EAC9B,IAAI,iBAA2C,EAAE;EACjD,IAAI,SAAS;EACb,IAAI,MAAM;AACV,MAAI;AACF,oBAAiB,gBAAgB,QAAQ,QAAQ;AACjD,YAAS,QAAQ;AACjB,SAAM,QAAQ;WACP,OAAO;AACd,YACE,mBACA,0CACA,MACD;;EAGH,MAAM,iBACJ,YAGS;AACT,OAAI;IACF,MAAM,QAA6B;KACjC,MAAM;KACN,WAAW,WAAW;KACtB,GAAI,WAAW,sBAAsB,KAAA,IACjC,EAAE,mBAAmB,WAAW,mBAAmB,GACnD,EAAE;KACN;KACA;KACA;KACA;KACA,WAAW,KAAK,KAAK;KACrB,GAAG;KACJ;AACD,eAAW,UACT,kBAAkB,kBAAkB,EAAE,YAAY,CAAC,MAAM,CAAC,CAC3D;YACM,OAAO;AACd,aACE,kBACA,yCACA,MACD;;;EAIL,IAAI;AACJ,MAAI;AACF,cAAW,MAAM,sBAAsB,IAAI,YAAY,cAAc;WAC9D,OAAO;AACd,iBAAc,EAAE,OAAO,OAAO,MAAM,EAAE,CAAC;AACvC,SAAM;;AAGR,MAAI;AACF,iBAAc;IACZ,YAAY,SAAS;IACrB,iBAAiB,gBAAgB,SAAS,QAAQ;IACnD,CAAC;WACK,OAAO;AACd,YACE,kBACA,yCACA,MACD;;AAEH,SAAO;;AAKT,QAAO;EAAE,GAAG;EAAS,OAAO;EAAc;;;;;;;;;;;AAY5C,MAAM,uBAAuB,OAC3B,SACA,QAC8C;CAC9C,IAAI;CACJ,IAAI;AACJ,KAAI;AACF,eAAa,sBACX,QAAQ,QAAQ,IAAI,0BAA0B,CAC/C;AACD,sBACE,QAAQ,QAAQ,IAAA,0BAA+B,IAAI,KAAA;SAC/C;AACN;;AAEF,KAAI,eAAe,KAAA,KAAa,sBAAsB,KAAA,EACpD;CAGF,MAAM,OAAO,MAAM,2BAA2B,YAAY,kBAAkB;AAC5E,KAAI,SAAS,KACX;AAGF,QAAO;EACL,MAAM;EACN,WAAW,OAAO,YAAY;EAC9B;EACA;EACA,eAAe,KAAK;EACpB,WAAW,eAAe,IAAI;EAC/B;;AAKH,MAAM,sBAAsB;AAC5B,MAAM,yCAAyB,IAAI,KAGhC;AAEH,MAAM,8BACJ,YACA,sBAC0D;CAC1D,MAAM,MAAM,GAAG,WAAW,GAAG;CAC7B,MAAM,SAAS,uBAAuB,IAAI,IAAI;AAC9C,KAAI,WAAW,KAAA,EACb,QAAO;CAET,MAAM,UAAU,qBACd,kBAAkB,EAClB,YACA,kBACD,CAAC,MAAM,WAAW;AACjB,MAAI,OAAO,YAAY,eAAe;AAKpC,0BAAuB,OAAO,IAAI;AAClC,UAAO;;AAET,SAAO,OAAO,YAAY,UACtB,EAAE,eAAe,OAAO,eAAe,GACvC;GACJ;AACF,KAAI,uBAAuB,QAAQ,qBAAqB;EACtD,MAAM,SAAS,uBAAuB,MAAM,CAAC,MAAM;AACnD,MAAI,CAAC,OAAO,KACV,wBAAuB,OAAO,OAAO,MAAM;;AAG/C,wBAAuB,IAAI,KAAK,QAAQ;AACxC,QAAO;;AAGT,MAAM,qBACJ,SACA,QACuB;CACvB,MAAM,UACJ,QAAQ,QAAQ,OAAO,QAAQ,WAC1B,IAAgC,4BACjC,KAAA;CACN,MAAM,MAAM,SAAS,cAAc;AACnC,KAAI,OAAO,QAAQ,YAAY,IAAI,WAAW,EAC5C;AAEF,QAAO,IAAI,QAAQ,QAAQ,GAAG;;AAGhC,MAAM,uBACJ,SACA,YACA,QAC0B;CAC1B,IAAI;AACJ,KAAI;AACF,sBACE,QAAQ,QAAQ,IAAA,0BAA+B,IAAI,KAAA;SAC/C;AACN,sBAAoB,KAAA;;AAEtB,QAAO;EACL,MAAM;EACN,WAAW,OAAO,YAAY;EAC9B;EACA;EACA,WAAW,eAAe,IAAI;EAC/B;;AAGH,MAAM,kBACH,SACA,YAAoC;AACnC,KAAI;AACF,MAAI,UAAU,QAAQ;UACf,OAAO;AACd,WACE,cACA,sDACA,MACD","debugId":"00301fec-a17c-5e8e-8e2f-f16608d3b611"}

package/dist/kv-patch.js

@@ -0,0 +1,261 @@
+
+!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]="93bf09ea-4e78-5ac4-92cd-661f2ce03542")}catch(e){}}();
+import { requestCaptureContext } from "./context.js";
+import { warnOnce } from "./log.js";
+import { redactRequestBody } from "./redact-body.js";
+import { MAX_BODY_CAPTURE_SIZE } from "./body-capture.js";
+import { getOriginalFetch } from "./original-fetch.js";
+import { postCaptureEvents } from "./sidecar-client.js";
+//#region src/kv-patch.ts
+/**
+* Records operations on Cloudflare KV namespace bindings (`env.MY_KV.get(key)`).
+*
+* KV is invisible to both the `globalThis.fetch` patch and the binding patch: a namespace is
+* a host object with no `fetch`, and workerd services its methods internally rather than as
+* a subrequest. So the namespace's *prototype* methods are patched instead — the same move
+* `binding-patch.ts` makes on a Fetcher, and the Node recorder on `Redis.prototype.sendCommand`.
+*
+* The prototype is reached from an instance found on `env`: as with bindings there is no
+* global to name, and going through an instance is what makes this work for an app that reads
+* its bindings from `cloudflare:workers` rather than the handler argument — that module hands
+* out a different `env` object but the same namespace instances, so the prototype is shared
+* either way.
+*
+* Verified against real workerd in `packages/backend-recorder-js/src/__tests__/`:
+* `workerd-binding-patch.spec.ts` pins the property shape this relies on (every recorded
+* method inherited and configurable, one prototype across namespaces), and
+* `workerd-kv-sidecar.spec.ts` drives real KV through the patch end to end.
+*/
+const KV_PATCHED = Symbol.for("meticulous.workerd.kvPatched");
+/**
+* The methods recorded, and the shape a KV namespace is recognised by.
+*
+* `getWithMetadata` is what separates KV from R2: an R2 bucket also has `get`, `put`,
+* `delete` and `list`, so without it a bucket would be duck-typed as a namespace and its
+* (large, binary) objects pushed through value capture.
+*/
+const RECORDED_KV_METHODS = [
+	"get",
+	"getWithMetadata",
+	"put",
+	"delete",
+	"list"
+];
+/**
+* The namespaces being recorded, and the `env` key each was found under.
+*
+* Doubles as the allow-list: only an instance in here is recorded. A skipped namespace is
+* simply never registered, and — since the patch can land on a prototype shared with another
+* binding type — nothing that is not a discovered KV namespace can be recorded by accident.
+*/
+const kvBindingNames = /* @__PURE__ */ new WeakMap();
+/**
+* Discovers KV namespace bindings on `env` and patches their shared prototype so their
+* operations are recorded. Safe to call on every request — discovery is cheap and the patch
+* itself is applied once per prototype per isolate.
+*
+* Never throws: a runtime that does not permit the patch simply goes unrecorded.
+*/
+const installKvPatch = (env, options) => {
+	try {
+		for (const { name, value, skip } of kvBindings(env, options?.skipBindings)) {
+			patchKvMethods(value);
+			if (!skip) kvBindingNames.set(value, name);
+		}
+	} catch (error) {
+		warnOnce("kv-patch-install", "Failed to install the Meticulous KV patch — KV operations will not be recorded.", error);
+	}
+};
+const kvBindings = (env, skipBindings) => {
+	if (env === null || typeof env !== "object") return [];
+	const skipped = new Set(skipBindings ?? []);
+	const found = [];
+	for (const [name, value] of Object.entries(env)) if (isKvNamespaceLike(value)) found.push({
+		name,
+		value,
+		skip: skipped.has(name)
+	});
+	return found;
+};
+const isKvNamespaceLike = (value) => value !== null && typeof value === "object" && RECORDED_KV_METHODS.every((method) => typeof value[method] === "function");
+/**
+* Patches every recorded method, or none of them: a half-patched namespace would record a
+* partial view of the app's KV usage, which is worse than recording none of it, because
+* nothing in the recording would say which half is missing. So the whole chain is resolved
+* first, and only then patched.
+*
+* Each method is patched where it actually lives rather than on the instance's immediate
+* prototype — workerd already puts an inherited method further up the chain for Durable
+* Object stubs, so assuming one flat prototype is not safe.
+*/
+const patchKvMethods = (binding) => {
+	const owners = /* @__PURE__ */ new Map();
+	for (const method of RECORDED_KV_METHODS) {
+		const owner = findMethodOwner(binding, method);
+		if (owner === void 0) {
+			warnOnce("kv-patch-unsupported", `This runtime does not expose a patchable KV \`${method}\` — KV operations will not be recorded.`);
+			return;
+		}
+		owners.set(method, owner);
+	}
+	for (const [method, { owner, original }] of owners) {
+		if (original[KV_PATCHED] === true) continue;
+		Object.defineProperty(owner, method, {
+			value: patchedKvMethod(method, original),
+			writable: true,
+			enumerable: false,
+			configurable: true
+		});
+	}
+};
+/**
+* The prototype whose `method` a call on `instance` would reach, or undefined if there is none
+* or it cannot be replaced. The search stops at the first prototype that *has* the property,
+* patchable or not: that is the one a call resolves to, so anything further up is shadowed.
+*/
+const findMethodOwner = (instance, method) => {
+	if (Object.hasOwn(instance, method)) return;
+	let current = Object.getPrototypeOf(instance);
+	while (current !== null) {
+		const descriptor = Object.getOwnPropertyDescriptor(current, method);
+		if (descriptor !== void 0) return typeof descriptor.value === "function" && descriptor.configurable === true ? {
+			owner: current,
+			original: descriptor.value
+		} : void 0;
+		current = Object.getPrototypeOf(current);
+	}
+};
+/**
+* A `function`, not an arrow: `this` is the namespace the call was made on, and it must be
+* forwarded to the original or workerd throws "Illegal invocation".
+*/
+const patchedKvMethod = (operation, original) => {
+	const patched = function(...args) {
+		const passThrough = () => original.apply(this, args);
+		const ctx = requestCaptureContext.getStore();
+		if (!ctx || ctx.mode !== "record") return passThrough();
+		const receiver = typeof this === "object" && this !== null ? this : void 0;
+		const bindingName = receiver === void 0 ? void 0 : kvBindingNames.get(receiver);
+		if (bindingName === void 0) return passThrough();
+		return captureKvOperation(ctx, operation, bindingName, args, passThrough);
+	};
+	Object.defineProperty(patched, KV_PATCHED, {
+		value: true,
+		enumerable: false,
+		configurable: true
+	});
+	return patched;
+};
+/**
+* Records an operation without affecting it: the real method runs untouched and its result is
+* returned as-is, with the event reported in the background via `ctx.waitUntil`. Any capture
+* failure is warned about once and swallowed — recording must never break the app.
+*/
+const captureKvOperation = async (ctx, operation, bindingName, args, invoke) => {
+	const startTimeMs = Date.now();
+	let result;
+	try {
+		result = await invoke();
+	} catch (error) {
+		report(ctx, operation, bindingName, args, startTimeMs, { error: String(error) });
+		throw error;
+	}
+	report(ctx, operation, bindingName, args, startTimeMs, { result });
+	return result;
+};
+const report = (ctx, operation, bindingName, args, startTimeMs, outcome) => {
+	try {
+		const event = buildKvEvent(ctx, operation, bindingName, args, startTimeMs, outcome);
+		ctx.waitUntil(postCaptureEvents(getOriginalFetch(), ctx.sidecarUrl, [event]));
+	} catch (error) {
+		warnOnce("kv-report", "Failed to report a KV operation.", error);
+	}
+};
+const buildKvEvent = (ctx, operation, bindingName, args, startTimeMs, outcome) => {
+	const [key] = args;
+	const written = operation === "put" ? serializeWrittenValue(args[1]) : void 0;
+	const read = "result" in outcome ? serializeKvValue(outcome.result) : void 0;
+	const omitted = written?.omitted ?? read?.omitted;
+	const serializedArgs = serializeKvArgs(operation, args);
+	return {
+		kind: "kv",
+		requestId: ctx.requestId,
+		...ctx.frontendSessionId !== void 0 ? { frontendSessionId: ctx.frontendSessionId } : {},
+		bindingName,
+		operation,
+		...typeof key === "string" ? { key } : {},
+		...serializedArgs !== void 0 ? { args: serializedArgs } : {},
+		...written?.captured !== void 0 ? { value: written.captured } : {},
+		...read?.captured !== void 0 ? { result: read.captured } : {},
+		...omitted !== void 0 ? { omitted } : {},
+		startTimeMs,
+		endTimeMs: Date.now(),
+		..."error" in outcome ? { error: outcome.error } : {}
+	};
+};
+/**
+* JSON of a value workerd returned, with anything unpersistable replaced by `null` and the
+* reason reported alongside. A `Map` (what a bulk `get` returns) becomes a plain object,
+* which `JSON.stringify` would otherwise flatten to `{}`.
+*
+* Read values are stored verbatim, deliberately: a future replay would serve them straight
+* back to the app, so redacting one would corrupt what the app receives. Only the write path
+* ({@link serializeWrittenValue}) is redacted — nothing ever replays a `put`.
+*/
+const serializeKvValue = (value) => {
+	let omitted;
+	try {
+		const json = JSON.stringify(value, (_key, nested) => {
+			const reason = omittedReason(nested);
+			if (reason !== void 0) {
+				omitted ??= reason;
+				return null;
+			}
+			return nested instanceof Map ? Object.fromEntries(nested) : nested;
+		});
+		return {
+			...json !== void 0 ? { captured: capture(json) } : {},
+			...omitted !== void 0 ? { omitted } : {}
+		};
+	} catch {
+		return {};
+	}
+};
+/**
+* JSON of the value a `put` wrote, redacted like a request body. KV takes a string, an
+* ArrayBuffer(View) or a stream; only the string form can be captured, and it is redacted as
+* text before being JSON-encoded so that secret-looking fields *inside* the app's payload are
+* caught (redacting the JSON-encoded form would only ever see one opaque string).
+*/
+const serializeWrittenValue = (value) => {
+	if (typeof value === "string") try {
+		return { captured: capture(JSON.stringify(redactRequestBody(value))) };
+	} catch {
+		return {};
+	}
+	return serializeKvValue(value);
+};
+/**
+* JSON of the call's arguments. A `put` value is replaced by `null` rather than dropped, so
+* the remaining arguments keep their positions — and so the value is only ever persisted via
+* the redacted {@link serializeWrittenValue} path.
+*/
+const serializeKvArgs = (operation, args) => {
+	return serializeKvValue(operation === "put" ? args.map((arg, index) => index === 1 ? null : arg) : args).captured;
+};
+const omittedReason = (value) => {
+	if (typeof ReadableStream !== "undefined" && value instanceof ReadableStream) return "stream";
+	if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) return "binary";
+};
+const capture = (json) => json.length > 262144 ? {
+	body: json.slice(0, MAX_BODY_CAPTURE_SIZE),
+	truncated: true
+} : {
+	body: json,
+	truncated: false
+};
+//#endregion
+export { installKvPatch };
+
+//# sourceMappingURL=kv-patch.js.map
+//# debugId=93bf09ea-4e78-5ac4-92cd-661f2ce03542

package/dist/kv-patch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv-patch.js","sources":["../src/kv-patch.ts"],"sourcesContent":["import { MAX_BODY_CAPTURE_SIZE } from \"./body-capture\";\nimport { type RequestCaptureContext, requestCaptureContext } from \"./context\";\nimport { warnOnce } from \"./log\";\nimport { getOriginalFetch } from \"./original-fetch\";\nimport type {\n  CapturedBody,\n  KvOmittedReason,\n  KvOperation,\n  KvOperationEvent,\n} from \"./protocol\";\nimport { redactRequestBody } from \"./redact-body\";\nimport { postCaptureEvents } from \"./sidecar-client\";\n\n/**\n * Records operations on Cloudflare KV namespace bindings (`env.MY_KV.get(key)`).\n *\n * KV is invisible to both the `globalThis.fetch` patch and the binding patch: a namespace is\n * a host object with no `fetch`, and workerd services its methods internally rather than as\n * a subrequest. So the namespace's *prototype* methods are patched instead — the same move\n * `binding-patch.ts` makes on a Fetcher, and the Node recorder on `Redis.prototype.sendCommand`.\n *\n * The prototype is reached from an instance found on `env`: as with bindings there is no\n * global to name, and going through an instance is what makes this work for an app that reads\n * its bindings from `cloudflare:workers` rather than the handler argument — that module hands\n * out a different `env` object but the same namespace instances, so the prototype is shared\n * either way.\n *\n * Verified against real workerd in `packages/backend-recorder-js/src/__tests__/`:\n * `workerd-binding-patch.spec.ts` pins the property shape this relies on (every recorded\n * method inherited and configurable, one prototype across namespaces), and\n * `workerd-kv-sidecar.spec.ts` drives real KV through the patch end to end.\n */\n\n// Marks a patched method, rather than the prototype holding it: methods can live at different\n// depths of one chain, and a base prototype can be shared with another binding type, so\n// \"already ours\" has to be answerable per function. Symbol.for so a second copy of the shim\n// (e.g. bundled twice) still detects the patch.\nconst KV_PATCHED = Symbol.for(\"meticulous.workerd.kvPatched\");\n\n/**\n * The methods recorded, and the shape a KV namespace is recognised by.\n *\n * `getWithMetadata` is what separates KV from R2: an R2 bucket also has `get`, `put`,\n * `delete` and `list`, so without it a bucket would be duck-typed as a namespace and its\n * (large, binary) objects pushed through value capture.\n */\nconst RECORDED_KV_METHODS = [\n  \"get\",\n  \"getWithMetadata\",\n  \"put\",\n  \"delete\",\n  \"list\",\n] as const;\n\n/**\n * The namespaces being recorded, and the `env` key each was found under.\n *\n * Doubles as the allow-list: only an instance in here is recorded. A skipped namespace is\n * simply never registered, and — since the patch can land on a prototype shared with another\n * binding type — nothing that is not a discovered KV namespace can be recorded by accident.\n */\nconst kvBindingNames = new WeakMap<object, string>();\n\ntype KvMethod = (...args: unknown[]) => Promise<unknown>;\n\ntype KvNamespaceLike = Record<KvOperation, KvMethod>;\n\nexport interface InstallKvPatchOptions {\n  /** Binding names to leave unrecorded. */\n  skipBindings?: readonly string[];\n}\n\n/**\n * Discovers KV namespace bindings on `env` and patches their shared prototype so their\n * operations are recorded. Safe to call on every request — discovery is cheap and the patch\n * itself is applied once per prototype per isolate.\n *\n * Never throws: a runtime that does not permit the patch simply goes unrecorded.\n */\nexport const installKvPatch = (\n  env: unknown,\n  options?: InstallKvPatchOptions,\n): void => {\n  try {\n    for (const { name, value, skip } of kvBindings(\n      env,\n      options?.skipBindings,\n    )) {\n      // Patch even a skipped namespace's methods: they are shared with every other namespace,\n      // so seeding them is what gives those coverage. Skipping is enforced by leaving the\n      // instance off the allow-list below, not by declining to patch.\n      patchKvMethods(value);\n      if (!skip) {\n        kvBindingNames.set(value, name);\n      }\n    }\n  } catch (error) {\n    warnOnce(\n      \"kv-patch-install\",\n      \"Failed to install the Meticulous KV patch — KV operations will not be recorded.\",\n      error,\n    );\n  }\n};\n\ninterface DiscoveredKvBinding {\n  name: string;\n  value: object;\n  skip: boolean;\n}\n\nconst kvBindings = (\n  env: unknown,\n  skipBindings: readonly string[] | undefined,\n): DiscoveredKvBinding[] => {\n  if (env === null || typeof env !== \"object\") {\n    return [];\n  }\n  const skipped = new Set<string>(skipBindings ?? []);\n  const found: DiscoveredKvBinding[] = [];\n  for (const [name, value] of Object.entries(env)) {\n    if (isKvNamespaceLike(value)) {\n      found.push({ name, value, skip: skipped.has(name) });\n    }\n  }\n  return found;\n};\n\nconst isKvNamespaceLike = (value: unknown): value is object & KvNamespaceLike =>\n  value !== null &&\n  typeof value === \"object\" &&\n  RECORDED_KV_METHODS.every(\n    (method) =>\n      typeof (value as Record<string, unknown>)[method] === \"function\",\n  );\n\n/**\n * Patches every recorded method, or none of them: a half-patched namespace would record a\n * partial view of the app's KV usage, which is worse than recording none of it, because\n * nothing in the recording would say which half is missing. So the whole chain is resolved\n * first, and only then patched.\n *\n * Each method is patched where it actually lives rather than on the instance's immediate\n * prototype — workerd already puts an inherited method further up the chain for Durable\n * Object stubs, so assuming one flat prototype is not safe.\n */\nconst patchKvMethods = (binding: object): void => {\n  const owners = new Map<KvOperation, MethodOwner>();\n  for (const method of RECORDED_KV_METHODS) {\n    const owner = findMethodOwner(binding, method);\n    if (owner === undefined) {\n      // Either the method is an own per-instance property or the runtime has locked the\n      // prototype. Recording KV is not possible; everything else keeps working.\n      warnOnce(\n        \"kv-patch-unsupported\",\n        `This runtime does not expose a patchable KV \\`${method}\\` — KV operations will not be recorded.`,\n      );\n      return;\n    }\n    owners.set(method, owner);\n  }\n\n  for (const [method, { owner, original }] of owners) {\n    if ((original as unknown as Record<symbol, unknown>)[KV_PATCHED] === true) {\n      continue;\n    }\n    Object.defineProperty(owner, method, {\n      value: patchedKvMethod(method, original),\n      writable: true,\n      enumerable: false,\n      configurable: true,\n    });\n  }\n};\n\ninterface MethodOwner {\n  owner: object;\n  original: KvMethod;\n}\n\n/**\n * The prototype whose `method` a call on `instance` would reach, or undefined if there is none\n * or it cannot be replaced. The search stops at the first prototype that *has* the property,\n * patchable or not: that is the one a call resolves to, so anything further up is shadowed.\n */\nconst findMethodOwner = (\n  instance: object,\n  method: KvOperation,\n): MethodOwner | undefined => {\n  if (Object.hasOwn(instance, method)) {\n    // An own per-instance method would shadow anything we patched on the prototype.\n    return undefined;\n  }\n  let current: object | null = Object.getPrototypeOf(instance) as object | null;\n  while (current !== null) {\n    const descriptor = Object.getOwnPropertyDescriptor(current, method);\n    if (descriptor !== undefined) {\n      return typeof descriptor.value === \"function\" &&\n        descriptor.configurable === true\n        ? { owner: current, original: descriptor.value as KvMethod }\n        : undefined;\n    }\n    current = Object.getPrototypeOf(current) as object | null;\n  }\n  return undefined;\n};\n\n/**\n * A `function`, not an arrow: `this` is the namespace the call was made on, and it must be\n * forwarded to the original or workerd throws \"Illegal invocation\".\n */\nconst patchedKvMethod = (\n  operation: KvOperation,\n  original: KvMethod,\n): KvMethod => {\n  const patched = function (\n    this: unknown,\n    ...args: unknown[]\n  ): Promise<unknown> {\n    const passThrough = (): Promise<unknown> => original.apply(this, args);\n\n    const ctx = requestCaptureContext.getStore();\n    // Record mode only. `installKvPatch` is not called for a replay request, but the patch is\n    // per-isolate: a record request could have installed it earlier, and no mock store serves\n    // KV, so a replay request must reach the real namespace.\n    if (!ctx || ctx.mode !== \"record\") {\n      return passThrough();\n    }\n    const receiver =\n      typeof this === \"object\" && this !== null ? this : undefined;\n    // Only namespaces discovered on `env` are recorded — see `kvBindingNames`.\n    const bindingName =\n      receiver === undefined ? undefined : kvBindingNames.get(receiver);\n    if (bindingName === undefined) {\n      return passThrough();\n    }\n\n    return captureKvOperation(ctx, operation, bindingName, args, passThrough);\n  };\n  Object.defineProperty(patched, KV_PATCHED, {\n    value: true,\n    enumerable: false,\n    configurable: true,\n  });\n  return patched;\n};\n\n/**\n * Records an operation without affecting it: the real method runs untouched and its result is\n * returned as-is, with the event reported in the background via `ctx.waitUntil`. Any capture\n * failure is warned about once and swallowed — recording must never break the app.\n */\nconst captureKvOperation = async (\n  ctx: RequestCaptureContext,\n  operation: KvOperation,\n  bindingName: string,\n  args: unknown[],\n  invoke: () => Promise<unknown>,\n): Promise<unknown> => {\n  const startTimeMs = Date.now();\n  let result: unknown;\n  try {\n    result = await invoke();\n  } catch (error) {\n    report(ctx, operation, bindingName, args, startTimeMs, {\n      error: String(error),\n    });\n    throw error;\n  }\n  report(ctx, operation, bindingName, args, startTimeMs, { result });\n  return result;\n};\n\nconst report = (\n  ctx: RequestCaptureContext,\n  operation: KvOperation,\n  bindingName: string,\n  args: unknown[],\n  startTimeMs: number,\n  outcome: { result: unknown } | { error: string },\n): void => {\n  try {\n    const event = buildKvEvent(\n      ctx,\n      operation,\n      bindingName,\n      args,\n      startTimeMs,\n      outcome,\n    );\n    // postCaptureEvents never rejects — it warns once on an unreachable sidecar.\n    ctx.waitUntil(\n      postCaptureEvents(getOriginalFetch(), ctx.sidecarUrl, [event]),\n    );\n  } catch (error) {\n    warnOnce(\"kv-report\", \"Failed to report a KV operation.\", error);\n  }\n};\n\nconst buildKvEvent = (\n  ctx: RequestCaptureContext,\n  operation: KvOperation,\n  bindingName: string,\n  args: unknown[],\n  startTimeMs: number,\n  outcome: { result: unknown } | { error: string },\n): KvOperationEvent => {\n  const [key] = args;\n  const written =\n    operation === \"put\" ? serializeWrittenValue(args[1]) : undefined;\n  const read =\n    \"result\" in outcome ? serializeKvValue(outcome.result) : undefined;\n  const omitted = written?.omitted ?? read?.omitted;\n  const serializedArgs = serializeKvArgs(operation, args);\n\n  return {\n    kind: \"kv\",\n    requestId: ctx.requestId,\n    ...(ctx.frontendSessionId !== undefined\n      ? { frontendSessionId: ctx.frontendSessionId }\n      : {}),\n    bindingName,\n    operation,\n    ...(typeof key === \"string\" ? { key } : {}),\n    ...(serializedArgs !== undefined ? { args: serializedArgs } : {}),\n    ...(written?.captured !== undefined ? { value: written.captured } : {}),\n    ...(read?.captured !== undefined ? { result: read.captured } : {}),\n    ...(omitted !== undefined ? { omitted } : {}),\n    startTimeMs,\n    endTimeMs: Date.now(),\n    ...(\"error\" in outcome ? { error: outcome.error } : {}),\n  };\n};\n\ninterface SerializedKvValue {\n  captured?: CapturedBody;\n  omitted?: KvOmittedReason;\n}\n\n/**\n * JSON of a value workerd returned, with anything unpersistable replaced by `null` and the\n * reason reported alongside. A `Map` (what a bulk `get` returns) becomes a plain object,\n * which `JSON.stringify` would otherwise flatten to `{}`.\n *\n * Read values are stored verbatim, deliberately: a future replay would serve them straight\n * back to the app, so redacting one would corrupt what the app receives. Only the write path\n * ({@link serializeWrittenValue}) is redacted — nothing ever replays a `put`.\n */\nconst serializeKvValue = (value: unknown): SerializedKvValue => {\n  let omitted: KvOmittedReason | undefined;\n  try {\n    const json = JSON.stringify(value, (_key: string, nested: unknown) => {\n      const reason = omittedReason(nested);\n      if (reason !== undefined) {\n        omitted ??= reason;\n        return null;\n      }\n      return nested instanceof Map\n        ? Object.fromEntries(nested as Map<string, unknown>)\n        : nested;\n    });\n    return {\n      // `undefined` (what `put`/`delete` resolve to) has no JSON form — nothing to capture.\n      ...(json !== undefined ? { captured: capture(json) } : {}),\n      ...(omitted !== undefined ? { omitted } : {}),\n    };\n  } catch {\n    // Circular, or a getter that throws. The operation itself is still recorded.\n    return {};\n  }\n};\n\n/**\n * JSON of the value a `put` wrote, redacted like a request body. KV takes a string, an\n * ArrayBuffer(View) or a stream; only the string form can be captured, and it is redacted as\n * text before being JSON-encoded so that secret-looking fields *inside* the app's payload are\n * caught (redacting the JSON-encoded form would only ever see one opaque string).\n */\nconst serializeWrittenValue = (value: unknown): SerializedKvValue => {\n  if (typeof value === \"string\") {\n    try {\n      return { captured: capture(JSON.stringify(redactRequestBody(value))) };\n    } catch {\n      return {};\n    }\n  }\n  return serializeKvValue(value);\n};\n\n/**\n * JSON of the call's arguments. A `put` value is replaced by `null` rather than dropped, so\n * the remaining arguments keep their positions — and so the value is only ever persisted via\n * the redacted {@link serializeWrittenValue} path.\n */\nconst serializeKvArgs = (\n  operation: KvOperation,\n  args: unknown[],\n): CapturedBody | undefined => {\n  const withoutValue =\n    operation === \"put\"\n      ? args.map((arg, index) => (index === 1 ? null : arg))\n      : args;\n  return serializeKvValue(withoutValue).captured;\n};\n\nconst omittedReason = (value: unknown): KvOmittedReason | undefined => {\n  // A stream is never read, only recognised: reading it would consume the app's bytes.\n  if (\n    typeof ReadableStream !== \"undefined\" &&\n    value instanceof ReadableStream\n  ) {\n    return \"stream\";\n  }\n  if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {\n    return \"binary\";\n  }\n  return undefined;\n};\n\nconst capture = (json: string): CapturedBody =>\n  json.length > MAX_BODY_CAPTURE_SIZE\n    ? { body: json.slice(0, MAX_BODY_CAPTURE_SIZE), truncated: true }\n    : { body: json, truncated: false };\n"],"names":[],"mappings":"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","debugId":"93bf09ea-4e78-5ac4-92cd-661f2ce03542"}

package/dist/log.js

@@ -1,6 +1,14 @@
 //#region src/log.ts
+/**
+* console.warn every time. Only for something the app is about to see anyway (a replay call
+* that cannot be served, which throws), where knowing _which_ call it was matters more than
+* keeping the log short — a deduped key would hide every miss after the first.
+*/
 
-!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]="4a78549a-41a2-5625-a0b7-315324af09b5")}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]="af311c85-9c8c-5901-81b9-33d469149fa7")}catch(e){}}();
+const warn = (message) => {
+	console.warn(`[meticulous] ${message}`);
+};
 const warned = /* @__PURE__ */ new Set();
 /** console.warn once per unique key — capture problems must never spam or break the app. */
 const warnOnce = (key, message, error) => {
@@ -10,7 +18,7 @@ const warnOnce = (key, message, error) => {
 	else console.warn(`[meticulous] ${message}`, error);
 };
 //#endregion
-export { warnOnce };
+export { warn, warnOnce };
 
 //# sourceMappingURL=log.js.map
-//# debugId=4a78549a-41a2-5625-a0b7-315324af09b5
+//# debugId=af311c85-9c8c-5901-81b9-33d469149fa7

package/dist/log.js.map

@@ -1 +1 @@
-{"version":3,"file":"log.js","sources":["../src/log.ts"],"sourcesContent":["const warned = new Set<string>();\n\n/** console.warn once per unique key — capture problems must never spam or break the app. */\nexport const warnOnce = (\n  key: string,\n  message: string,\n  error?: unknown,\n): void => {\n  if (warned.has(key)) {\n    return;\n  }\n  warned.add(key);\n  if (error === undefined) {\n    console.warn(`[meticulous] ${message}`);\n  } else {\n    console.warn(`[meticulous] ${message}`, error);\n  }\n};\n"],"names":[],"mappings":";;;AAAA,MAAM,yBAAS,IAAI,KAAa;;AAGhC,MAAa,YACX,KACA,SACA,UACS;AACT,KAAI,OAAO,IAAI,IAAI,CACjB;AAEF,QAAO,IAAI,IAAI;AACf,KAAI,UAAU,KAAA,EACZ,SAAQ,KAAK,gBAAgB,UAAU;KAEvC,SAAQ,KAAK,gBAAgB,WAAW,MAAM","debugId":"4a78549a-41a2-5625-a0b7-315324af09b5"}
+{"version":3,"file":"log.js","sources":["../src/log.ts"],"sourcesContent":["/**\n * console.warn every time. Only for something the app is about to see anyway (a replay call\n * that cannot be served, which throws), where knowing _which_ call it was matters more than\n * keeping the log short — a deduped key would hide every miss after the first.\n */\nexport const warn = (message: string): void => {\n  console.warn(`[meticulous] ${message}`);\n};\n\nconst warned = new Set<string>();\n\n/** console.warn once per unique key — capture problems must never spam or break the app. */\nexport const warnOnce = (\n  key: string,\n  message: string,\n  error?: unknown,\n): void => {\n  if (warned.has(key)) {\n    return;\n  }\n  warned.add(key);\n  if (error === undefined) {\n    console.warn(`[meticulous] ${message}`);\n  } else {\n    console.warn(`[meticulous] ${message}`, error);\n  }\n};\n"],"names":[],"mappings":";;;;;;;;AAKA,MAAa,QAAQ,YAA0B;AAC7C,SAAQ,KAAK,gBAAgB,UAAU;;AAGzC,MAAM,yBAAS,IAAI,KAAa;;AAGhC,MAAa,YACX,KACA,SACA,UACS;AACT,KAAI,OAAO,IAAI,IAAI,CACjB;AAEF,QAAO,IAAI,IAAI;AACf,KAAI,UAAU,KAAA,EACZ,SAAQ,KAAK,gBAAgB,UAAU;KAEvC,SAAQ,KAAK,gBAAgB,WAAW,MAAM","debugId":"af311c85-9c8c-5901-81b9-33d469149fa7"}