@alwaysmeticulous/backend-recorder-workerd 2.325.0 → 2.327.0

package/dist/postgres/capture.js

@@ -0,0 +1,136 @@
+
+!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]="b2626960-f48d-5500-a2b3-a8c9fbaf2002")}catch(e){}}();
+import { serializeCapturedError } from "../error-capture.js";
+//#region src/postgres/capture.ts
+/**
+* The record-side contract for postgres.js (the `postgres` npm package), shared by the Node
+* recorder's `met-postgres-js-instrumentation/` and the in-worker `withMeticulousPostgres`.
+*
+* It lives in this package for the same reason `kv-capture.ts` does: a query recorded from a
+* deployed Worker has to produce the byte-identical span a Node-recorded one does, because
+* `PostgresJsMockStore` derives its match key from those attributes at load time. Get the
+* serialization subtly wrong on one surface and every replay of a Worker recording misses.
+* `packages/backend-recorder-js/src/postgres-js-capture-shared.ts` re-exports everything here
+* and keeps the replay half (key building, result/error reconstruction) to itself — that half
+* needs a synchronous SHA-256 and never runs inside a Worker.
+*/
+const POSTGRES_JS_QUERY_TEXT_ATTR = "meticulous.postgresjs.query.text";
+const POSTGRES_JS_QUERY_PARAMS_ATTR = "meticulous.postgresjs.query.params";
+const POSTGRES_JS_ROW_MODE_ATTR = "meticulous.postgresjs.row_mode";
+const POSTGRES_JS_RESULT_ATTR = "meticulous.postgresjs.result";
+const POSTGRES_JS_RESULT_TRUNCATED_ATTR = "meticulous.postgresjs.result.truncated";
+const POSTGRES_JS_ERROR_ATTR = "meticulous.postgresjs.error";
+const MAX_POSTGRES_JS_RESULT_SIZE = 256 * 1024;
+const resolveRowMode = (isRaw) => {
+	if (isRaw === "values") return "values";
+	return isRaw ? "raw" : "";
+};
+/**
+* Rebuilds the SQL text from a tagged template's literal chunks, with `$1`, `$2`… where the
+* interpolated values went.
+*
+* The SQL text does not exist at interception time: postgres.js builds `query.string` only once
+* a query reaches a connection, and replay never executes, so both sides must derive the text
+* from `query.strings` instead.
+*/
+const reconstructQueryText = (strings) => {
+	if (!Array.isArray(strings) || strings.length === 0) return;
+	let text = "";
+	for (let i = 0; i < strings.length; i++) {
+		const chunk = strings[i];
+		if (typeof chunk !== "string") return;
+		text += i === 0 ? chunk : `$${i}${chunk}`;
+	}
+	return text;
+};
+/**
+* Canonical serialization of the query's interpolated values.
+*
+* Read from `query.args` (the raw JS values), never `query.parameters`: the latter does not
+* exist until postgres.js builds the statement, and its `Bind` step then mutates it in place
+* into wire-format strings — so it differs between the two sides.
+*
+* `args` is heterogeneous: postgres.js' dynamic helpers put `Builder` / `Identifier` /
+* `Parameter` instances in there alongside plain values. JSON-encoding them is stable across
+* calls, which is all the match key needs.
+*/
+const serializePostgresJsArgs = (args) => {
+	try {
+		return JSON.stringify(Array.isArray(args) ? args : []);
+	} catch {
+		return "[]";
+	}
+};
+/** The leading SQL keyword, for the span name only. */
+const postgresJsCommandOf = (text) => /^\s*([a-z]+)/i.exec(text)?.[1]?.toLowerCase() ?? "query";
+const asRecord = (value) => value != null && typeof value === "object" ? value : {};
+const numberOrNull = (value) => typeof value === "number" ? value : null;
+/**
+* postgres.js resolves a query with a `Result` — an `Array` subclass whose metadata lives in
+* five non-enumerable own properties, so `JSON.stringify` would capture only the rows. Pull them
+* out explicitly.
+*
+* Two fields are dropped on purpose: each column's `parser` (a function, so it can't survive
+* JSON, and consumers never call it on an already-parsed row) and `state` (a live
+* per-connection `{pid, secret}` handle used only for query cancellation, which is meaningless
+* without a connection).
+*/
+const serializeOneResult = (res) => {
+	const meta = res;
+	const statement = asRecord(meta?.statement);
+	return {
+		rows: Array.isArray(res) ? [...res] : [],
+		count: numberOrNull(meta?.count),
+		command: typeof meta?.command === "string" ? meta.command : null,
+		columns: Array.isArray(meta?.columns) ? meta.columns.map((column) => {
+			const c = asRecord(column);
+			return {
+				name: String(c.name ?? ""),
+				type: numberOrNull(c.type) ?? 0,
+				table: numberOrNull(c.table) ?? 0,
+				number: numberOrNull(c.number) ?? 0
+			};
+		}) : [],
+		statement: meta?.statement != null ? {
+			string: String(statement.string ?? ""),
+			types: Array.isArray(statement.types) ? statement.types : [],
+			name: String(statement.name ?? "")
+		} : null
+	};
+};
+/**
+* Serializes a postgres.js result (or the array form a multi-statement / `simple` query resolves
+* to) to a JSON string for storage as a span attribute.
+*/
+const serializePostgresJsResult = (result) => {
+	const serialized = Array.isArray(result) && result.length > 0 && result.every((r) => isResultLike(r)) ? result.map(serializeOneResult) : serializeOneResult(result);
+	return JSON.stringify(serialized);
+};
+const isResultLike = (value) => Array.isArray(value) && Object.prototype.hasOwnProperty.call(value, "command") && Object.prototype.hasOwnProperty.call(value, "count");
+const ERROR_DEBUG_PROPS = new Set([
+	"stack",
+	"query",
+	"parameters",
+	"args",
+	"types"
+]);
+/**
+* Captures a rejected query's error as a JSON string. postgres.js surfaces server errors as
+* `PostgresError` (`extends Error`, with the server's `code`/`severity`/`detail`/… fields
+* `Object.assign`ed on) and transport/validation failures as plain `Error`s carrying `code`. All
+* of those live in own enumerable properties, so copying those plus `message` (own but
+* non-enumerable, from the `Error` constructor) captures everything a consumer inspects.
+*/
+const serializePostgresJsError = (error) => serializeCapturedError(error, ERROR_DEBUG_PROPS);
+/**
+* Whether a query resolves with a single `Result` we can capture and replay. Cursors,
+* `.forEach()`, `.readable()`/`.writable()` (COPY streams) and `.describe()` resolve with
+* something else, and `sql.file()` is constructed with no template chunks at all (its text is
+* only read from disk later). All of those pass straight through, unrecorded and unmocked.
+*/
+const isSupportedPostgresJsQuery = (query) => reconstructQueryText(query.strings) != null && !query.onlyDescribe && !query.streaming && query.cursorFn == null && query.cursorRows == null && query.forEachFn == null;
+//#endregion
+export { MAX_POSTGRES_JS_RESULT_SIZE, POSTGRES_JS_ERROR_ATTR, POSTGRES_JS_QUERY_PARAMS_ATTR, POSTGRES_JS_QUERY_TEXT_ATTR, POSTGRES_JS_RESULT_ATTR, POSTGRES_JS_RESULT_TRUNCATED_ATTR, POSTGRES_JS_ROW_MODE_ATTR, isSupportedPostgresJsQuery, postgresJsCommandOf, reconstructQueryText, resolveRowMode, serializePostgresJsArgs, serializePostgresJsError, serializePostgresJsResult };
+
+//# sourceMappingURL=capture.js.map
+//# debugId=b2626960-f48d-5500-a2b3-a8c9fbaf2002

package/dist/postgres/capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.js","sources":["../../src/postgres/capture.ts"],"sourcesContent":["import { serializeCapturedError } from \"../error-capture\";\n\n/**\n * The record-side contract for postgres.js (the `postgres` npm package), shared by the Node\n * recorder's `met-postgres-js-instrumentation/` and the in-worker `withMeticulousPostgres`.\n *\n * It lives in this package for the same reason `kv-capture.ts` does: a query recorded from a\n * deployed Worker has to produce the byte-identical span a Node-recorded one does, because\n * `PostgresJsMockStore` derives its match key from those attributes at load time. Get the\n * serialization subtly wrong on one surface and every replay of a Worker recording misses.\n * `packages/backend-recorder-js/src/postgres-js-capture-shared.ts` re-exports everything here\n * and keeps the replay half (key building, result/error reconstruction) to itself — that half\n * needs a synchronous SHA-256 and never runs inside a Worker.\n */\n\n// Custom Meticulous span attributes carrying the query input + result. Kept distinct from the\n// `pg` attributes (`meticulous.pg.*`) so the two stores can never match each other's spans,\n// even though both talk to Postgres.\nexport const POSTGRES_JS_QUERY_TEXT_ATTR = \"meticulous.postgresjs.query.text\";\nexport const POSTGRES_JS_QUERY_PARAMS_ATTR =\n  \"meticulous.postgresjs.query.params\";\nexport const POSTGRES_JS_ROW_MODE_ATTR = \"meticulous.postgresjs.row_mode\";\nexport const POSTGRES_JS_RESULT_ATTR = \"meticulous.postgresjs.result\";\nexport const POSTGRES_JS_RESULT_TRUNCATED_ATTR =\n  \"meticulous.postgresjs.result.truncated\";\n// Set instead of `result` when the query rejected, so a query that legitimately errors (a\n// constraint violation, a missing relation) replays as the same error rather than as a \"no\n// recorded result\" miss.\nexport const POSTGRES_JS_ERROR_ATTR = \"meticulous.postgresjs.error\";\n\n// Cap the captured result to bound span size, matching the HTTP/undici/pg 256 KB cap.\nexport const MAX_POSTGRES_JS_RESULT_SIZE = 256 * 1024;\n\n/**\n * How the rows of a result are shaped: objects keyed by column name by default, or arrays under\n * `.values()` / `.raw()`. postgres.js records this on the query as `isRaw` (`undefined` |\n * `true` | `\"values\"`).\n *\n * This belongs in the match key because the SAME sql text returns different row shapes\n * depending on it — Drizzle's postgres-js driver calls `.values()` for typed selects but awaits\n * the query directly for `db.execute`, so both shapes occur for identical text.\n */\nexport type PostgresJsRowMode = \"\" | \"raw\" | \"values\";\n\nexport const resolveRowMode = (isRaw: unknown): PostgresJsRowMode => {\n  if (isRaw === \"values\") {\n    return \"values\";\n  }\n  return isRaw ? \"raw\" : \"\";\n};\n\n/**\n * Rebuilds the SQL text from a tagged template's literal chunks, with `$1`, `$2`… where the\n * interpolated values went.\n *\n * The SQL text does not exist at interception time: postgres.js builds `query.string` only once\n * a query reaches a connection, and replay never executes, so both sides must derive the text\n * from `query.strings` instead.\n */\nexport const reconstructQueryText = (strings: unknown): string | undefined => {\n  if (!Array.isArray(strings) || strings.length === 0) {\n    return undefined;\n  }\n  let text = \"\";\n  for (let i = 0; i < strings.length; i++) {\n    const chunk = strings[i];\n    if (typeof chunk !== \"string\") {\n      return undefined;\n    }\n    text += i === 0 ? chunk : `$${i}${chunk}`;\n  }\n  return text;\n};\n\n/**\n * Canonical serialization of the query's interpolated values.\n *\n * Read from `query.args` (the raw JS values), never `query.parameters`: the latter does not\n * exist until postgres.js builds the statement, and its `Bind` step then mutates it in place\n * into wire-format strings — so it differs between the two sides.\n *\n * `args` is heterogeneous: postgres.js' dynamic helpers put `Builder` / `Identifier` /\n * `Parameter` instances in there alongside plain values. JSON-encoding them is stable across\n * calls, which is all the match key needs.\n */\nexport const serializePostgresJsArgs = (args: unknown): string => {\n  try {\n    return JSON.stringify(Array.isArray(args) ? args : []);\n  } catch {\n    return \"[]\";\n  }\n};\n\n/** The leading SQL keyword, for the span name only. */\nexport const postgresJsCommandOf = (text: string): string =>\n  /^\\s*([a-z]+)/i.exec(text)?.[1]?.toLowerCase() ?? \"query\";\n\ninterface SerializedPostgresJsResult {\n  rows: unknown[];\n  count: number | null;\n  command: string | null;\n  columns: { name: string; type: number; table: number; number: number }[];\n  statement: { string: string; types: number[]; name: string } | null;\n}\n\n/**\n * The metadata postgres.js hangs off a `Result`. Declared with `unknown` values so the\n * serializer below narrows every field rather than trusting the shape.\n */\ninterface PostgresJsResultLike {\n  count?: unknown;\n  command?: unknown;\n  columns?: unknown;\n  statement?: unknown;\n}\n\nconst asRecord = (value: unknown): Record<string, unknown> =>\n  value != null && typeof value === \"object\"\n    ? (value as Record<string, unknown>)\n    : {};\n\nconst numberOrNull = (value: unknown): number | null =>\n  typeof value === \"number\" ? value : null;\n\n/**\n * postgres.js resolves a query with a `Result` — an `Array` subclass whose metadata lives in\n * five non-enumerable own properties, so `JSON.stringify` would capture only the rows. Pull them\n * out explicitly.\n *\n * Two fields are dropped on purpose: each column's `parser` (a function, so it can't survive\n * JSON, and consumers never call it on an already-parsed row) and `state` (a live\n * per-connection `{pid, secret}` handle used only for query cancellation, which is meaningless\n * without a connection).\n */\nconst serializeOneResult = (res: unknown): SerializedPostgresJsResult => {\n  const meta = res as PostgresJsResultLike | null | undefined;\n  const statement = asRecord(meta?.statement);\n  return {\n    rows: Array.isArray(res) ? [...(res as unknown[])] : [],\n    count: numberOrNull(meta?.count),\n    command: typeof meta?.command === \"string\" ? meta.command : null,\n    columns: Array.isArray(meta?.columns)\n      ? meta.columns.map((column) => {\n          const c = asRecord(column);\n          return {\n            name: String(c.name ?? \"\"),\n            type: numberOrNull(c.type) ?? 0,\n            table: numberOrNull(c.table) ?? 0,\n            number: numberOrNull(c.number) ?? 0,\n          };\n        })\n      : [],\n    statement:\n      meta?.statement != null\n        ? {\n            string: String(statement.string ?? \"\"),\n            types: Array.isArray(statement.types)\n              ? (statement.types as number[])\n              : [],\n            name: String(statement.name ?? \"\"),\n          }\n        : null,\n  };\n};\n\n/**\n * Serializes a postgres.js result (or the array form a multi-statement / `simple` query resolves\n * to) to a JSON string for storage as a span attribute.\n */\nexport const serializePostgresJsResult = (result: unknown): string => {\n  // A Result IS an Array, so an array-of-Results is only distinguishable by its elements. The\n  // `length > 0` guard matters: `[].every(...)` is true, so without it every zero-row result (a\n  // SELECT that matched nothing, an INSERT without RETURNING, BEGIN/COMMIT) would be mistaken\n  // for an empty list of results and lose its `count`/`command`.\n  const isMultiple =\n    Array.isArray(result) &&\n    result.length > 0 &&\n    result.every((r) => isResultLike(r));\n  const serialized = isMultiple\n    ? (result as unknown[]).map(serializeOneResult)\n    : serializeOneResult(result);\n  return JSON.stringify(serialized);\n};\n\n// A `Result` carries `command`/`count` own properties; a plain row object or scalar does not.\nconst isResultLike = (value: unknown): boolean =>\n  Array.isArray(value) &&\n  Object.prototype.hasOwnProperty.call(value, \"command\") &&\n  Object.prototype.hasOwnProperty.call(value, \"count\");\n\n// Own properties postgres.js attaches to a query error for debugging. Excluded from the\n// captured error: they are large, redundant with the query attributes we already record, and\n// only enumerable when the app enabled postgres.js' `debug` option.\nconst ERROR_DEBUG_PROPS = new Set([\n  \"stack\",\n  \"query\",\n  \"parameters\",\n  \"args\",\n  \"types\",\n]);\n\n/**\n * Captures a rejected query's error as a JSON string. postgres.js surfaces server errors as\n * `PostgresError` (`extends Error`, with the server's `code`/`severity`/`detail`/… fields\n * `Object.assign`ed on) and transport/validation failures as plain `Error`s carrying `code`. All\n * of those live in own enumerable properties, so copying those plus `message` (own but\n * non-enumerable, from the `Error` constructor) captures everything a consumer inspects.\n */\nexport const serializePostgresJsError = (error: unknown): string =>\n  serializeCapturedError(error, ERROR_DEBUG_PROPS);\n\n/**\n * The shape of postgres.js' internal `Query` that both sides rely on. Declared structurally (no\n * `postgres` dependency).\n */\nexport interface PostgresJsQueryLike {\n  /** Template chunks: the literal parts of a tagged template, or `[text]` for `unsafe`. */\n  strings: unknown;\n  /** The interpolated values, still raw JS values at interception time. */\n  args: unknown;\n  /** `undefined` by default, `true` after `.raw()`, `\"values\"` after `.values()`. */\n  isRaw?: unknown;\n  /** Set once `handle()` has run; guards against double-instrumenting one query. */\n  executed?: boolean;\n  /** Set by `.describe()` — resolves with a Statement, not a Result. */\n  onlyDescribe?: boolean;\n  /** Set by `.cursor()` / `.forEach()` / `.readable()` — streaming, not a single Result. */\n  cursorFn?: unknown;\n  cursorRows?: unknown;\n  forEachFn?: unknown;\n  streaming?: unknown;\n  options?: {\n    /**\n     * Present only on the implicit `begin` query `sql.begin()` issues. postgres.js needs it\n     * called with the serving connection before the transaction body runs.\n     */\n    onexecute?: (connection: unknown) => void;\n    [key: string]: unknown;\n  };\n  resolve: (result: unknown) => void;\n  reject: (error: unknown) => void;\n}\n\n/**\n * Whether a query resolves with a single `Result` we can capture and replay. Cursors,\n * `.forEach()`, `.readable()`/`.writable()` (COPY streams) and `.describe()` resolve with\n * something else, and `sql.file()` is constructed with no template chunks at all (its text is\n * only read from disk later). All of those pass straight through, unrecorded and unmocked.\n */\nexport const isSupportedPostgresJsQuery = (\n  query: PostgresJsQueryLike,\n): boolean =>\n  reconstructQueryText(query.strings) != null &&\n  !query.onlyDescribe &&\n  !query.streaming &&\n  query.cursorFn == null &&\n  query.cursorRows == null &&\n  query.forEachFn == null;\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAkBA,MAAa,8BAA8B;AAC3C,MAAa,gCACX;AACF,MAAa,4BAA4B;AACzC,MAAa,0BAA0B;AACvC,MAAa,oCACX;AAIF,MAAa,yBAAyB;AAGtC,MAAa,8BAA8B,MAAM;AAajD,MAAa,kBAAkB,UAAsC;AACnE,KAAI,UAAU,SACZ,QAAO;AAET,QAAO,QAAQ,QAAQ;;;;;;;;;;AAWzB,MAAa,wBAAwB,YAAyC;AAC5E,KAAI,CAAC,MAAM,QAAQ,QAAQ,IAAI,QAAQ,WAAW,EAChD;CAEF,IAAI,OAAO;AACX,MAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,QAAQ,KAAK;EACvC,MAAM,QAAQ,QAAQ;AACtB,MAAI,OAAO,UAAU,SACnB;AAEF,UAAQ,MAAM,IAAI,QAAQ,IAAI,IAAI;;AAEpC,QAAO;;;;;;;;;;;;;AAcT,MAAa,2BAA2B,SAA0B;AAChE,KAAI;AACF,SAAO,KAAK,UAAU,MAAM,QAAQ,KAAK,GAAG,OAAO,EAAE,CAAC;SAChD;AACN,SAAO;;;;AAKX,MAAa,uBAAuB,SAClC,gBAAgB,KAAK,KAAK,GAAG,IAAI,aAAa,IAAI;AAqBpD,MAAM,YAAY,UAChB,SAAS,QAAQ,OAAO,UAAU,WAC7B,QACD,EAAE;AAER,MAAM,gBAAgB,UACpB,OAAO,UAAU,WAAW,QAAQ;;;;;;;;;;;AAYtC,MAAM,sBAAsB,QAA6C;CACvE,MAAM,OAAO;CACb,MAAM,YAAY,SAAS,MAAM,UAAU;AAC3C,QAAO;EACL,MAAM,MAAM,QAAQ,IAAI,GAAG,CAAC,GAAI,IAAkB,GAAG,EAAE;EACvD,OAAO,aAAa,MAAM,MAAM;EAChC,SAAS,OAAO,MAAM,YAAY,WAAW,KAAK,UAAU;EAC5D,SAAS,MAAM,QAAQ,MAAM,QAAQ,GACjC,KAAK,QAAQ,KAAK,WAAW;GAC3B,MAAM,IAAI,SAAS,OAAO;AAC1B,UAAO;IACL,MAAM,OAAO,EAAE,QAAQ,GAAG;IAC1B,MAAM,aAAa,EAAE,KAAK,IAAI;IAC9B,OAAO,aAAa,EAAE,MAAM,IAAI;IAChC,QAAQ,aAAa,EAAE,OAAO,IAAI;IACnC;IACD,GACF,EAAE;EACN,WACE,MAAM,aAAa,OACf;GACE,QAAQ,OAAO,UAAU,UAAU,GAAG;GACtC,OAAO,MAAM,QAAQ,UAAU,MAAM,GAChC,UAAU,QACX,EAAE;GACN,MAAM,OAAO,UAAU,QAAQ,GAAG;GACnC,GACD;EACP;;;;;;AAOH,MAAa,6BAA6B,WAA4B;CASpE,MAAM,aAHJ,MAAM,QAAQ,OAAO,IACrB,OAAO,SAAS,KAChB,OAAO,OAAO,MAAM,aAAa,EAAE,CAAC,GAEjC,OAAqB,IAAI,mBAAmB,GAC7C,mBAAmB,OAAO;AAC9B,QAAO,KAAK,UAAU,WAAW;;AAInC,MAAM,gBAAgB,UACpB,MAAM,QAAQ,MAAM,IACpB,OAAO,UAAU,eAAe,KAAK,OAAO,UAAU,IACtD,OAAO,UAAU,eAAe,KAAK,OAAO,QAAQ;AAKtD,MAAM,oBAAoB,IAAI,IAAI;CAChC;CACA;CACA;CACA;CACA;CACD,CAAC;;;;;;;;AASF,MAAa,4BAA4B,UACvC,uBAAuB,OAAO,kBAAkB;;;;;;;AAwClD,MAAa,8BACX,UAEA,qBAAqB,MAAM,QAAQ,IAAI,QACvC,CAAC,MAAM,gBACP,CAAC,MAAM,aACP,MAAM,YAAY,QAClB,MAAM,cAAc,QACpB,MAAM,aAAa","debugId":"b2626960-f48d-5500-a2b3-a8c9fbaf2002"}

package/dist/postgres/with-meticulous-postgres.d.ts

@@ -0,0 +1,32 @@
+//#region src/postgres/with-meticulous-postgres.d.ts
+/**
+ * Records postgres.js queries a deployed Worker makes — typically over Hyperdrive, which is the
+ * only way a Worker reaches Postgres.
+ *
+ * There is no seam to patch automatically here. The Node recorder can hook Node's module loader
+ * to patch `postgres/{src,cjs/src,cf/src}/query.js`, but a Worker is a single bundle: `postgres`
+ * was inlined at build time and never passes through a loader. So the app hands us its client:
+ *
+ *   const sql = withMeticulousPostgres(postgres(env.HYPERDRIVE.connectionString));
+ *
+ * Every postgres.js query funnels through one internal method, `Query.prototype.handle`, and this
+ * reaches that shared prototype *through the instance* — via a throwaway query, which is free
+ * because postgres.js queries are lazy and nothing executes until awaited. One call therefore also
+ * covers read-replica clients and any other client in the isolate.
+ *
+ * Apply it **outermost** if something else also wraps the client (Sentry's
+ * `instrumentPostgresJsSql`, a logging proxy): those wrappers return a proxy whose `handle` is
+ * still the shared prototype's, so ordering does not change what is captured — but keeping ours
+ * outermost matches the Node recorder's contract and stays correct if that ever changes.
+ *
+ * Record-only, deliberately. A Worker recording is replayed against the app running under Node,
+ * where `@alwaysmeticulous/backend-recorder-js` serves these queries from its own mock store —
+ * which is why the captured attributes here are exactly the ones that store reads. Outside a
+ * recorded request this is a complete pass-through, so it is safe to leave in deployed code.
+ *
+ * Returns the client unchanged; the patch is on the prototype.
+ */
+declare const withMeticulousPostgres: <Sql>(sql: Sql) => Sql;
+//#endregion
+export { withMeticulousPostgres };
+//# sourceMappingURL=with-meticulous-postgres.d.ts.map

package/dist/postgres/with-meticulous-postgres.js

@@ -0,0 +1,152 @@
+
+!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]="bcb30e85-33e1-52b2-9e08-5dd84f66d61c")}catch(e){}}();
+import { requestCaptureContext } from "../context.js";
+import { warnOnce } from "../log.js";
+import { MAX_POSTGRES_JS_RESULT_SIZE, isSupportedPostgresJsQuery, reconstructQueryText, resolveRowMode, serializePostgresJsArgs, serializePostgresJsError, serializePostgresJsResult } from "./capture.js";
+//#region src/postgres/with-meticulous-postgres.ts
+/**
+* Records postgres.js queries a deployed Worker makes — typically over Hyperdrive, which is the
+* only way a Worker reaches Postgres.
+*
+* There is no seam to patch automatically here. The Node recorder can hook Node's module loader
+* to patch `postgres/{src,cjs/src,cf/src}/query.js`, but a Worker is a single bundle: `postgres`
+* was inlined at build time and never passes through a loader. So the app hands us its client:
+*
+*   const sql = withMeticulousPostgres(postgres(env.HYPERDRIVE.connectionString));
+*
+* Every postgres.js query funnels through one internal method, `Query.prototype.handle`, and this
+* reaches that shared prototype *through the instance* — via a throwaway query, which is free
+* because postgres.js queries are lazy and nothing executes until awaited. One call therefore also
+* covers read-replica clients and any other client in the isolate.
+*
+* Apply it **outermost** if something else also wraps the client (Sentry's
+* `instrumentPostgresJsSql`, a logging proxy): those wrappers return a proxy whose `handle` is
+* still the shared prototype's, so ordering does not change what is captured — but keeping ours
+* outermost matches the Node recorder's contract and stays correct if that ever changes.
+*
+* Record-only, deliberately. A Worker recording is replayed against the app running under Node,
+* where `@alwaysmeticulous/backend-recorder-js` serves these queries from its own mock store —
+* which is why the captured attributes here are exactly the ones that store reads. Outside a
+* recorded request this is a complete pass-through, so it is safe to leave in deployed code.
+*
+* Returns the client unchanged; the patch is on the prototype.
+*/
+const withMeticulousPostgres = (sql) => {
+	try {
+		const prototype = findQueryPrototype(sql);
+		if (prototype === void 0) {
+			warnOnce("postgres-wrapper-unsupported", "withMeticulousPostgres could not reach postgres.js' Query prototype — queries will not be recorded.");
+			return sql;
+		}
+		patchHandle(prototype);
+	} catch (error) {
+		warnOnce("postgres-wrapper-failed", "withMeticulousPostgres failed — queries will not be recorded.", error);
+	}
+	return sql;
+};
+const HANDLE_PATCHED = Symbol.for("meticulous.workerd.postgresJsPatched");
+/**
+* The `Query` prototype, reached by building a query and reading its prototype.
+*
+* `sql.unsafe` is used rather than a tagged template because it takes the text as a plain
+* argument: no interpolation, and postgres.js does not touch a connection until the query is
+* awaited, which nothing here does. The query is discarded.
+*/
+const findQueryPrototype = (sql) => {
+	const unsafe = sql?.unsafe;
+	if (typeof unsafe !== "function") return;
+	const probe = unsafe.call(sql, "select 1");
+	if (probe === null || typeof probe !== "object") return;
+	const prototype = Object.getPrototypeOf(probe);
+	if (prototype === null) return;
+	const descriptor = Object.getOwnPropertyDescriptor(prototype, "handle");
+	return descriptor !== void 0 && typeof descriptor.value === "function" && descriptor.configurable === true ? prototype : void 0;
+};
+const patchHandle = (prototype) => {
+	const original = Object.getOwnPropertyDescriptor(prototype, "handle")?.value;
+	if (original === void 0 || original[HANDLE_PATCHED] === true) return;
+	const patched = function() {
+		if (this.executed || !isSupportedPostgresJsQuery(this)) return original.call(this);
+		const ctx = requestCaptureContext.getStore();
+		if (!ctx || ctx.mode !== "record") return original.call(this);
+		try {
+			captureQuery(ctx, this);
+		} catch (error) {
+			warnOnce("postgres-capture", "Failed to capture a postgres.js query.", error);
+		}
+		return original.call(this);
+	};
+	Object.defineProperty(patched, HANDLE_PATCHED, {
+		value: true,
+		enumerable: false,
+		configurable: true
+	});
+	Object.defineProperty(prototype, "handle", {
+		value: patched,
+		writable: true,
+		enumerable: false,
+		configurable: true
+	});
+};
+/**
+* Wraps the query's own `resolve`/`reject` so the outcome is captured without the query being
+* awaited here — the same trick the Node instrumentation uses, and the only place a query's input
+* and its result are both visible.
+*/
+const captureQuery = (ctx, query) => {
+	const queryText = reconstructQueryText(query.strings);
+	if (queryText === void 0) return;
+	const startTimeMs = Date.now();
+	const base = {
+		kind: "postgres",
+		requestId: ctx.requestId,
+		...ctx.frontendSessionId !== void 0 ? { frontendSessionId: ctx.frontendSessionId } : {},
+		traceId: ctx.traceId,
+		serverSpanId: ctx.serverSpanId,
+		queryText,
+		params: serializePostgresJsArgs(query.args),
+		rowMode: resolveRowMode(query.isRaw),
+		startTimeMs
+	};
+	const report = (outcome) => {
+		try {
+			ctx.buffer.add({
+				...base,
+				...outcome,
+				endTimeMs: Date.now()
+			});
+		} catch (error) {
+			warnOnce("postgres-report", "Failed to report a postgres.js query.", error);
+		}
+	};
+	const originalResolve = query.resolve;
+	const originalReject = query.reject;
+	query.resolve = (result) => {
+		let json;
+		try {
+			json = serializePostgresJsResult(result);
+		} catch {
+			json = void 0;
+		}
+		report(json === void 0 ? {} : { result: {
+			body: json.length > 262144 ? json.slice(0, MAX_POSTGRES_JS_RESULT_SIZE) : json,
+			truncated: json.length > MAX_POSTGRES_JS_RESULT_SIZE
+		} });
+		return originalResolve.call(query, result);
+	};
+	query.reject = (error) => {
+		let errorJson;
+		try {
+			errorJson = serializePostgresJsError(error);
+		} catch {
+			errorJson = void 0;
+		}
+		report(errorJson === void 0 ? {} : { errorJson });
+		return originalReject.call(query, error);
+	};
+};
+//#endregion
+export { withMeticulousPostgres };
+
+//# sourceMappingURL=with-meticulous-postgres.js.map
+//# debugId=bcb30e85-33e1-52b2-9e08-5dd84f66d61c

package/dist/postgres/with-meticulous-postgres.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-meticulous-postgres.js","sources":["../../src/postgres/with-meticulous-postgres.ts"],"sourcesContent":["import { type RequestCaptureContext, requestCaptureContext } from \"../context\";\nimport { warnOnce } from \"../log\";\nimport type { PostgresQueryEvent } from \"../protocol\";\nimport {\n  isSupportedPostgresJsQuery,\n  MAX_POSTGRES_JS_RESULT_SIZE,\n  type PostgresJsQueryLike,\n  reconstructQueryText,\n  resolveRowMode,\n  serializePostgresJsArgs,\n  serializePostgresJsError,\n  serializePostgresJsResult,\n} from \"./capture\";\n\n/**\n * Records postgres.js queries a deployed Worker makes — typically over Hyperdrive, which is the\n * only way a Worker reaches Postgres.\n *\n * There is no seam to patch automatically here. The Node recorder can hook Node's module loader\n * to patch `postgres/{src,cjs/src,cf/src}/query.js`, but a Worker is a single bundle: `postgres`\n * was inlined at build time and never passes through a loader. So the app hands us its client:\n *\n *   const sql = withMeticulousPostgres(postgres(env.HYPERDRIVE.connectionString));\n *\n * Every postgres.js query funnels through one internal method, `Query.prototype.handle`, and this\n * reaches that shared prototype *through the instance* — via a throwaway query, which is free\n * because postgres.js queries are lazy and nothing executes until awaited. One call therefore also\n * covers read-replica clients and any other client in the isolate.\n *\n * Apply it **outermost** if something else also wraps the client (Sentry's\n * `instrumentPostgresJsSql`, a logging proxy): those wrappers return a proxy whose `handle` is\n * still the shared prototype's, so ordering does not change what is captured — but keeping ours\n * outermost matches the Node recorder's contract and stays correct if that ever changes.\n *\n * Record-only, deliberately. A Worker recording is replayed against the app running under Node,\n * where `@alwaysmeticulous/backend-recorder-js` serves these queries from its own mock store —\n * which is why the captured attributes here are exactly the ones that store reads. Outside a\n * recorded request this is a complete pass-through, so it is safe to leave in deployed code.\n *\n * Returns the client unchanged; the patch is on the prototype.\n */\nexport const withMeticulousPostgres = <Sql>(sql: Sql): Sql => {\n  try {\n    const prototype = findQueryPrototype(sql);\n    if (prototype === undefined) {\n      warnOnce(\n        \"postgres-wrapper-unsupported\",\n        \"withMeticulousPostgres could not reach postgres.js' Query prototype — queries will not be recorded.\",\n      );\n      return sql;\n    }\n    patchHandle(prototype);\n  } catch (error) {\n    warnOnce(\n      \"postgres-wrapper-failed\",\n      \"withMeticulousPostgres failed — queries will not be recorded.\",\n      error,\n    );\n  }\n  return sql;\n};\n\n// Symbol.for so a second copy of the shim (e.g. bundled twice) still detects the patch.\nconst HANDLE_PATCHED = Symbol.for(\"meticulous.workerd.postgresJsPatched\");\n\ntype HandleFn = (this: PostgresJsQueryLike) => unknown;\n\n/**\n * The `Query` prototype, reached by building a query and reading its prototype.\n *\n * `sql.unsafe` is used rather than a tagged template because it takes the text as a plain\n * argument: no interpolation, and postgres.js does not touch a connection until the query is\n * awaited, which nothing here does. The query is discarded.\n */\nconst findQueryPrototype = (sql: unknown): object | undefined => {\n  const unsafe = (sql as { unsafe?: unknown } | null)?.unsafe;\n  if (typeof unsafe !== \"function\") {\n    return undefined;\n  }\n  const probe: unknown = (unsafe as (text: string) => unknown).call(\n    sql,\n    \"select 1\",\n  );\n  if (probe === null || typeof probe !== \"object\") {\n    return undefined;\n  }\n  const prototype = Object.getPrototypeOf(probe) as object | null;\n  if (prototype === null) {\n    return undefined;\n  }\n  const descriptor = Object.getOwnPropertyDescriptor(prototype, \"handle\");\n  return descriptor !== undefined &&\n    typeof descriptor.value === \"function\" &&\n    descriptor.configurable === true\n    ? prototype\n    : undefined;\n};\n\nconst patchHandle = (prototype: object): void => {\n  const descriptor = Object.getOwnPropertyDescriptor(prototype, \"handle\");\n  const original = descriptor?.value as HandleFn | undefined;\n  if (\n    original === undefined ||\n    (original as unknown as Record<symbol, unknown>)[HANDLE_PATCHED] === true\n  ) {\n    return;\n  }\n\n  const patched = function (this: PostgresJsQueryLike): unknown {\n    // `handle` is reachable from then/catch/finally/execute, so it can be called more than once\n    // for one query; postgres.js itself no-ops on the repeats via `executed`. Bail before\n    // instrumenting so a query is never captured twice.\n    if (this.executed || !isSupportedPostgresJsQuery(this)) {\n      return original.call(this);\n    }\n    const ctx = requestCaptureContext.getStore();\n    if (!ctx || ctx.mode !== \"record\") {\n      return original.call(this);\n    }\n    try {\n      captureQuery(ctx, this);\n    } catch (error) {\n      warnOnce(\n        \"postgres-capture\",\n        \"Failed to capture a postgres.js query.\",\n        error,\n      );\n    }\n    return original.call(this);\n  };\n  Object.defineProperty(patched, HANDLE_PATCHED, {\n    value: true,\n    enumerable: false,\n    configurable: true,\n  });\n  Object.defineProperty(prototype, \"handle\", {\n    value: patched,\n    writable: true,\n    enumerable: false,\n    configurable: true,\n  });\n};\n\n/**\n * Wraps the query's own `resolve`/`reject` so the outcome is captured without the query being\n * awaited here — the same trick the Node instrumentation uses, and the only place a query's input\n * and its result are both visible.\n */\nconst captureQuery = (\n  ctx: RequestCaptureContext,\n  query: PostgresJsQueryLike,\n): void => {\n  const queryText = reconstructQueryText(query.strings);\n  if (queryText === undefined) {\n    return;\n  }\n  const startTimeMs = Date.now();\n  const base = {\n    kind: \"postgres\" as const,\n    requestId: ctx.requestId,\n    ...(ctx.frontendSessionId !== undefined\n      ? { frontendSessionId: ctx.frontendSessionId }\n      : {}),\n    traceId: ctx.traceId,\n    serverSpanId: ctx.serverSpanId,\n    queryText,\n    params: serializePostgresJsArgs(query.args),\n    rowMode: resolveRowMode(query.isRaw),\n    startTimeMs,\n  };\n\n  const report = (outcome: Partial<PostgresQueryEvent>): void => {\n    try {\n      ctx.buffer.add({ ...base, ...outcome, endTimeMs: Date.now() });\n    } catch (error) {\n      warnOnce(\n        \"postgres-report\",\n        \"Failed to report a postgres.js query.\",\n        error,\n      );\n    }\n  };\n\n  const originalResolve = query.resolve;\n  const originalReject = query.reject;\n  query.resolve = (result: unknown) => {\n    // A result that cannot be serialized is simply not captured → it misses during replay and\n    // errors hermetically, rather than serving something wrong.\n    let json: string | undefined;\n    try {\n      json = serializePostgresJsResult(result);\n    } catch {\n      json = undefined;\n    }\n    report(\n      json === undefined\n        ? {}\n        : {\n            result: {\n              body:\n                json.length > MAX_POSTGRES_JS_RESULT_SIZE\n                  ? json.slice(0, MAX_POSTGRES_JS_RESULT_SIZE)\n                  : json,\n              truncated: json.length > MAX_POSTGRES_JS_RESULT_SIZE,\n            },\n          },\n    );\n    return originalResolve.call(query, result);\n  };\n  query.reject = (error: unknown) => {\n    let errorJson: string | undefined;\n    try {\n      errorJson = serializePostgresJsError(error);\n    } catch {\n      errorJson = undefined;\n    }\n    report(errorJson === undefined ? {} : { errorJson });\n    return originalReject.call(query, error);\n  };\n};\n"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,MAAa,0BAA+B,QAAkB;AAC5D,KAAI;EACF,MAAM,YAAY,mBAAmB,IAAI;AACzC,MAAI,cAAc,KAAA,GAAW;AAC3B,YACE,gCACA,sGACD;AACD,UAAO;;AAET,cAAY,UAAU;UACf,OAAO;AACd,WACE,2BACA,iEACA,MACD;;AAEH,QAAO;;AAIT,MAAM,iBAAiB,OAAO,IAAI,uCAAuC;;;;;;;;AAWzE,MAAM,sBAAsB,QAAqC;CAC/D,MAAM,SAAU,KAAqC;AACrD,KAAI,OAAO,WAAW,WACpB;CAEF,MAAM,QAAkB,OAAqC,KAC3D,KACA,WACD;AACD,KAAI,UAAU,QAAQ,OAAO,UAAU,SACrC;CAEF,MAAM,YAAY,OAAO,eAAe,MAAM;AAC9C,KAAI,cAAc,KAChB;CAEF,MAAM,aAAa,OAAO,yBAAyB,WAAW,SAAS;AACvE,QAAO,eAAe,KAAA,KACpB,OAAO,WAAW,UAAU,cAC5B,WAAW,iBAAiB,OAC1B,YACA,KAAA;;AAGN,MAAM,eAAe,cAA4B;CAE/C,MAAM,WADa,OAAO,yBAAyB,WAAW,SACnC,EAAE;AAC7B,KACE,aAAa,KAAA,KACZ,SAAgD,oBAAoB,KAErE;CAGF,MAAM,UAAU,WAA8C;AAI5D,MAAI,KAAK,YAAY,CAAC,2BAA2B,KAAK,CACpD,QAAO,SAAS,KAAK,KAAK;EAE5B,MAAM,MAAM,sBAAsB,UAAU;AAC5C,MAAI,CAAC,OAAO,IAAI,SAAS,SACvB,QAAO,SAAS,KAAK,KAAK;AAE5B,MAAI;AACF,gBAAa,KAAK,KAAK;WAChB,OAAO;AACd,YACE,oBACA,0CACA,MACD;;AAEH,SAAO,SAAS,KAAK,KAAK;;AAE5B,QAAO,eAAe,SAAS,gBAAgB;EAC7C,OAAO;EACP,YAAY;EACZ,cAAc;EACf,CAAC;AACF,QAAO,eAAe,WAAW,UAAU;EACzC,OAAO;EACP,UAAU;EACV,YAAY;EACZ,cAAc;EACf,CAAC;;;;;;;AAQJ,MAAM,gBACJ,KACA,UACS;CACT,MAAM,YAAY,qBAAqB,MAAM,QAAQ;AACrD,KAAI,cAAc,KAAA,EAChB;CAEF,MAAM,cAAc,KAAK,KAAK;CAC9B,MAAM,OAAO;EACX,MAAM;EACN,WAAW,IAAI;EACf,GAAI,IAAI,sBAAsB,KAAA,IAC1B,EAAE,mBAAmB,IAAI,mBAAmB,GAC5C,EAAE;EACN,SAAS,IAAI;EACb,cAAc,IAAI;EAClB;EACA,QAAQ,wBAAwB,MAAM,KAAK;EAC3C,SAAS,eAAe,MAAM,MAAM;EACpC;EACD;CAED,MAAM,UAAU,YAA+C;AAC7D,MAAI;AACF,OAAI,OAAO,IAAI;IAAE,GAAG;IAAM,GAAG;IAAS,WAAW,KAAK,KAAK;IAAE,CAAC;WACvD,OAAO;AACd,YACE,mBACA,yCACA,MACD;;;CAIL,MAAM,kBAAkB,MAAM;CAC9B,MAAM,iBAAiB,MAAM;AAC7B,OAAM,WAAW,WAAoB;EAGnC,IAAI;AACJ,MAAI;AACF,UAAO,0BAA0B,OAAO;UAClC;AACN,UAAO,KAAA;;AAET,SACE,SAAS,KAAA,IACL,EAAE,GACF,EACE,QAAQ;GACN,MACE,KAAK,SAAA,SACD,KAAK,MAAM,GAAG,4BAA4B,GAC1C;GACN,WAAW,KAAK,SAAS;GAC1B,EACF,CACN;AACD,SAAO,gBAAgB,KAAK,OAAO,OAAO;;AAE5C,OAAM,UAAU,UAAmB;EACjC,IAAI;AACJ,MAAI;AACF,eAAY,yBAAyB,MAAM;UACrC;AACN,eAAY,KAAA;;AAEd,SAAO,cAAc,KAAA,IAAY,EAAE,GAAG,EAAE,WAAW,CAAC;AACpD,SAAO,eAAe,KAAK,OAAO,MAAM","debugId":"bcb30e85-33e1-52b2-9e08-5dd84f66d61c"}

package/dist/protocol.d.ts

@@ -4,7 +4,7 @@
  * recorder sidecar. The sidecar imports these types (type-only), so this file
  * is the single source of truth for the shape of capture events.
  */
-declare const SIDECAR_PROTOCOL_VERSION = "1";
+declare const SIDECAR_PROTOCOL_VERSION = "2";
 /** Header carrying {@link SIDECAR_PROTOCOL_VERSION} on every shim → sidecar request. */
 declare const SIDECAR_PROTOCOL_VERSION_HEADER = "x-meticulous-sidecar-protocol-version";
 /**
@@ -12,6 +12,8 @@ declare const SIDECAR_PROTOCOL_VERSION_HEADER = "x-meticulous-sidecar-protocol-v
  * under recording; its value ties backend spans to the frontend session.
  */
 declare const FRONTEND_SESSION_ID_HEADER = "x-meticulous-session-id";
+/** Header identifying one replay attempt of a recorded frontend session. */
+declare const REPLAY_ID_HEADER = "x-meticulous-replay-id";
 /**
  * A request carrying this header set to `"true"` is never served from the recording and
  * never fails on a miss — it goes to the real network. Use it for a call that must be live
@@ -24,9 +26,9 @@ declare const FRONTEND_SESSION_ID_HEADER = "x-meticulous-session-id";
 declare const METICULOUS_PASSTHROUGH_HEADER = "meticulous-passthrough";
 declare const SIDECAR_EVENTS_PATH = "/v1/events";
 /**
- * Replay routes. A sidecar started in record mode answers 404 on both, which the shim
- * treats as "replay unavailable" and falls back to plain pass-through — so a new shim
- * keeps working against an older, record-only sidecar.
+ * Replay routes. A sidecar started in record mode answers 404 on both. Replay is hermetic,
+ * so an unanswered outbound-fetch lookup fails the app's call rather than letting it reach
+ * the real service — the same as any other failure to stub.
  */
 declare const SIDECAR_REPLAY_SESSION_PATH = "/v1/replay/session";
 declare const SIDECAR_REPLAY_OUTBOUND_FETCH_PATH = "/v1/replay/outbound-fetch";
@@ -42,9 +44,12 @@ declare const REPLAY_SIDECAR_URL_HEADER = "x-meticulous-backend-replay-sidecar-u
 /**
  * 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. Mirrors the Node backend
- * recorder, which persists only content-type plus the Meticulous session
- * header.
+ * capture time, before it ever leaves the worker.
+ *
+ * The Node backend recorder persists the same two, plus the inbound request's
+ * `Cookie` header on SERVER spans (`recorded-request-headers.ts`). This list
+ * has not followed it there, so a workerd recording of an authenticated server
+ * render still carries no session cookie.
  */
 declare const CAPTURED_HEADERS: readonly ["content-type", "x-meticulous-session-id"];
 interface CapturedBody {
@@ -53,11 +58,33 @@ interface CapturedBody {
   /** True when the body exceeded the capture cap or the read was cut short. */
   truncated: boolean;
 }
-interface BaseRequestEvent {
+/**
+ * The fields every capture event carries to say which request, session and trace it belongs to.
+ */
+interface CorrelatedEvent {
   /** Correlates outbound events to the inbound request being handled. */
   requestId: string;
   /** Value of {@link FRONTEND_SESSION_ID_HEADER} on the inbound request, if any. */
   frontendSessionId?: string;
+  /**
+   * Trace the request's spans belong to (32 hex chars), minted by the shim.
+   *
+   * The shim mints it, rather than the sidecar deriving it from {@link requestId}, so span
+   * assembly is stateless: a sidecar that had to remember `requestId → traceId` would give a
+   * request's SERVER span and its CLIENT children different traces whenever it lost that memory
+   * between two batches — which, for a Worker-hosted sidecar, an eviction can do at any moment.
+   *
+   * Optional so a sidecar keeps working against a shim that predates this field, in which case
+   * it falls back to its own per-`requestId` map.
+   */
+  traceId?: string;
+  /**
+   * Span id of the request's SERVER span (16 hex chars), also minted by the shim: it is the
+   * parent of every CLIENT span the request produced, and the inbound event's own span id.
+   */
+  serverSpanId?: string;
+}
+interface BaseRequestEvent extends CorrelatedEvent {
   method: string;
   /** Full URL including query string. */
   url: string;
@@ -76,6 +103,19 @@ interface BaseRequestEvent {
  */
 interface InboundRequestEvent extends BaseRequestEvent {
   kind: "inbound";
+  /**
+   * Where {@link BaseRequestEvent.frontendSessionId} came from. Absent means the browser
+   * minted it and sent it on the request, which is the normal case. `"backend"` means the
+   * shim minted it for a document navigation the browser could not tag, and the page may or
+   * may not have gone on to adopt it — a distinction ingestion needs, because an unadopted
+   * backend-minted id names a session that will never exist and must be treated as unstamped.
+   * The sidecar turns it into `meticulous.session_id_origin`.
+   *
+   * Optional, and therefore compatible with an older sidecar (which ignores it) — which is
+   * why adding it does not bump {@link SIDECAR_PROTOCOL_VERSION}, a strict-equality check
+   * whose bump would instead make this shim unusable against one.
+   */
+  sessionIdOrigin?: "backend";
 }
 /**
  * An outgoing `fetch` call made while handling an inbound request (becomes a
@@ -123,11 +163,8 @@ type KvOmittedReason = "binary" | "stream";
  * {@link BaseRequestEvent} beyond correlation and timing. Values are JSON so that a single
  * `JSON.parse` reconstructs exactly what the app saw, whichever `type` the read asked for.
  */
-interface KvOperationEvent {
+interface KvOperationEvent extends CorrelatedEvent {
   kind: "kv";
-  /** Correlates the operation to the inbound request being handled. */
-  requestId: string;
-  frontendSessionId?: string;
   /**
    * The `env` key the KV namespace was found under. Always present, unlike on a binding
    * event: a namespace has no factory equivalent to `DurableObjectNamespace.get()`, so one
@@ -164,7 +201,34 @@ interface KvOperationEvent {
   /** Set when the operation threw. */
   error?: string;
 }
-type CaptureEvent = InboundRequestEvent | OutboundRequestEvent | BindingRequestEvent | KvOperationEvent;
+/**
+ * One postgres.js query made while handling an inbound request (becomes a CLIENT span).
+ *
+ * Deliberately carries the same fields the Node recorder puts on a postgres.js span rather than
+ * anything Worker-specific: `PostgresJsMockStore` builds its match key from those attributes at
+ * load time, so a query recorded here replays through the existing Node mock path unchanged.
+ * See `postgres/capture.ts` for the serialization, which both surfaces share.
+ */
+interface PostgresQueryEvent extends CorrelatedEvent {
+  kind: "postgres";
+  /** SQL rebuilt from the tagged template's chunks, with `$1`, `$2`… placeholders. */
+  queryText: string;
+  /** JSON of the interpolated values, from `serializePostgresJsArgs`. */
+  params: string;
+  /** `""`, `"raw"` or `"values"` — the row shape the query asked for. */
+  rowMode: string;
+  /** JSON of the resolved `Result`, capped at {@link MAX_POSTGRES_JS_RESULT_SIZE}. */
+  result?: CapturedBody;
+  /**
+   * JSON of the rejection, from `serializePostgresJsError`. Set instead of {@link result}, and
+   * distinct from the transport-level `error` string on the HTTP-shaped events: this one is a
+   * recorded outcome the replay reproduces, not a note that capture failed.
+   */
+  errorJson?: string;
+  startTimeMs: number;
+  endTimeMs: number;
+}
+type CaptureEvent = InboundRequestEvent | OutboundRequestEvent | BindingRequestEvent | KvOperationEvent | PostgresQueryEvent;
 interface CaptureEventsPayload {
   events: CaptureEvent[];
 }
@@ -183,6 +247,7 @@ interface ReplaySessionInfoResponse {
 /** Lookup for a single outbound `fetch`, sent to {@link SIDECAR_REPLAY_OUTBOUND_FETCH_PATH}. */
 interface OutboundFetchLookupRequest {
   frontendSessionId: string;
+  replayId: string;
   method: string;
   /** Full URL including query string. */
   url: string;
@@ -194,9 +259,10 @@ interface OutboundFetchLookupRequest {
   requestBody?: CapturedBody;
 }
 /**
- * A recorded response to serve, a miss the caller must fail, or an instruction to let the
- * real call through. An unrecognised `outcome` must be treated as `passthrough`, so an older
- * shim keeps working against a newer sidecar.
+ * A recorded response to serve, or a signal the caller must fail the request. Replay is
+ * hermetic, so the shim never turns any of these into a real call — nor an outcome it does
+ * not recognise. The only live path is the request-side `meticulous-passthrough` header,
+ * handled before the lookup, not any response here.
  */
 type OutboundFetchLookupResponse = {
   outcome: "mock";
@@ -205,21 +271,15 @@ type OutboundFetchLookupResponse = {
   headers: Record<string, string>;
 }
 /**
- * The store was consulted and holds nothing for this call. Replay is hermetic, so the
- * shim fails the request rather than letting it reach the real service — matching the
- * Node backend recorder's http/undici mocks.
+ * The store holds nothing for this call — a genuine miss, or a call the sidecar could not
+ * look up at all (an unparseable URL). Replay is hermetic, so the shim fails the request
+ * rather than letting it reach the real service — matching the Node backend recorder's
+ * http/undici mocks. There is deliberately no "let the call through" outcome: the only
+ * live path is the request-side `meticulous-passthrough` header.
  */
 | {
   outcome: "no-mock";
-}
-/**
- * The call cannot be looked up at all (an unparseable URL), so there is no miss to report.
- * Also what an older sidecar answers on a miss, in which case the shim degrades to the
- * pre-`no-mock` fail-open behaviour rather than breaking the app.
- */
-| {
-  outcome: "passthrough";
 };
 //#endregion
-export { 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 };
+export { BindingRequestEvent, CAPTURED_HEADERS, CaptureEvent, CaptureEventsPayload, CapturedBody, FRONTEND_SESSION_ID_HEADER, InboundRequestEvent, KvOmittedReason, KvOperation, KvOperationEvent, METICULOUS_PASSTHROUGH_HEADER, OutboundFetchLookupRequest, OutboundFetchLookupResponse, OutboundRequestEvent, PostgresQueryEvent, REPLAY_ID_HEADER, REPLAY_SIDECAR_URL_HEADER, ReplaySessionInfoResponse, SIDECAR_EVENTS_PATH, SIDECAR_PROTOCOL_VERSION, SIDECAR_PROTOCOL_VERSION_HEADER, SIDECAR_REPLAY_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH };
 //# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.js

@@ -5,8 +5,8 @@
 * 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]="40d02ddc-000e-5f33-972c-1fa95ad7e2ea")}catch(e){}}();
-const SIDECAR_PROTOCOL_VERSION = "1";
+!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){}}();
+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";
 /**
@@ -14,6 +14,8 @@ const SIDECAR_PROTOCOL_VERSION_HEADER = "x-meticulous-sidecar-protocol-version";
 * under recording; its value ties backend spans to the frontend session.
 */
 const FRONTEND_SESSION_ID_HEADER = "x-meticulous-session-id";
+/** Header identifying one replay attempt of a recorded frontend session. */
+const REPLAY_ID_HEADER = "x-meticulous-replay-id";
 /**
 * A request carrying this header set to `"true"` is never served from the recording and
 * never fails on a miss — it goes to the real network. Use it for a call that must be live
@@ -26,9 +28,9 @@ const FRONTEND_SESSION_ID_HEADER = "x-meticulous-session-id";
 const METICULOUS_PASSTHROUGH_HEADER = "meticulous-passthrough";
 const SIDECAR_EVENTS_PATH = "/v1/events";
 /**
-* Replay routes. A sidecar started in record mode answers 404 on both, which the shim
-* treats as "replay unavailable" and falls back to plain pass-through — so a new shim
-* keeps working against an older, record-only sidecar.
+* Replay routes. A sidecar started in record mode answers 404 on both. Replay is hermetic,
+* so an unanswered outbound-fetch lookup fails the app's call rather than letting it reach
+* the real service — the same as any other failure to stub.
 */
 const SIDECAR_REPLAY_SESSION_PATH = "/v1/replay/session";
 const SIDECAR_REPLAY_OUTBOUND_FETCH_PATH = "/v1/replay/outbound-fetch";
@@ -44,13 +46,16 @@ const REPLAY_SIDECAR_URL_HEADER = "x-meticulous-backend-replay-sidecar-url";
 /**
 * 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. Mirrors the Node backend
-* recorder, which persists only content-type plus the Meticulous session
-* header.
+* capture time, before it ever leaves the worker.
+*
+* The Node backend recorder persists the same two, plus the inbound request's
+* `Cookie` header on SERVER spans (`recorded-request-headers.ts`). This list
+* has not followed it there, so a workerd recording of an authenticated server
+* render still carries no session cookie.
 */
 const CAPTURED_HEADERS = ["content-type", FRONTEND_SESSION_ID_HEADER];
 //#endregion
-export { CAPTURED_HEADERS, FRONTEND_SESSION_ID_HEADER, METICULOUS_PASSTHROUGH_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_OUTBOUND_FETCH_PATH, SIDECAR_REPLAY_SESSION_PATH };
 
 //# sourceMappingURL=protocol.js.map
-//# debugId=40d02ddc-000e-5f33-972c-1fa95ad7e2ea
+//# debugId=ca4290fa-420e-5b3e-be68-65bc78d7f094