pipework 0.284.0 → 0.286.0

package/dist/infra/alerts/namespace.js

@@ -8,6 +8,7 @@ import { recordFault, recordFaultFor, useFaultTarget, faultsSource } from './fau
 import { recordBeatFor } from './beat.js';
 import { deliveryFailedSource, webhookFailedSource, creditsSource } from './subsystem-sources.js';
 import { emailSource, storageSource, accessLinksSource, lockoutsSource } from './infra-sources.js';
+import { statementTimingSource } from './statement-sources.js';
 import { schedulesSource, stepsSource, pipelinesSource, tracesSource } from './async-sources.js';
 /** Alerts namespace — raise and resolve keyed conditions, grouped, delivered to sinks through an outbox, traced. */
 export const alerts = {
@@ -74,6 +75,8 @@ export const alerts = {
         traces: tracesSource,
         /** Raises `fault:<kind>` per kind of swallowed failure recorded by `recordFault` since the last tick (the pipework subsystems record audit-write, quota-record, credits-callback, trace-steps-lost, queue-* and scheduler faults). `kinds` limits it. */
         faults: faultsSource,
+        /** Raises `statement-slow:<label>` while the p90 of a `pipe.labelled` label's last `window` settled statements is over that label's budget; give the returned source to `observability.statementTiming` too. */
+        statementTiming: statementTimingSource,
         /** Raises `loop-stalled:<name>` while a background loop (scheduler, reaper, claim loop, support drain) has not run or succeeded within its allowance; the tick itself is covered by `pipework alerts stale`. */
         loopStalled: loopStalledSource,
     },

package/dist/infra/alerts/namespace.js.map

@@ -1 +1 @@
-{"version":3,"file":"namespace.js","sourceRoot":"","sources":["../../../src/infra/alerts/namespace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,aAAa,EAAE,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,iBAAiB,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAChM,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AACvF,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AACjG,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAClG,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEhG,oHAAoH;AACpH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,gCAAgC;IAChC,MAAM,EAAE,YAAY;IACpB,0HAA0H;IAC1H,IAAI,EAAE,UAAU;IAChB,wLAAwL;IACxL,YAAY;IACZ,oHAAoH;IACpH,aAAa,EAAE,iBAAiB;IAChC,2DAA2D;IAC3D,OAAO,EAAE,WAAW;IACpB,+DAA+D;IAC/D,MAAM,EAAE,UAAU;IAClB,kJAAkJ;IAClJ,SAAS;IACT,yRAAyR;IACzR,WAAW;IACX,oJAAoJ;IACpJ,cAAc;IACd,6QAA6Q;IAC7Q,cAAc;IACd,6NAA6N;IAC7N,UAAU,EAAE,aAAa;IACzB,MAAM,EAAE;QACN,4EAA4E;QAC5E,UAAU,EAAE,gBAAgB;QAC5B,iFAAiF;QACjF,WAAW,EAAE,iBAAiB;QAC9B,mGAAmG;QACnG,OAAO,EAAE,aAAa;QACtB,yGAAyG;QACzG,cAAc,EAAE,oBAAoB;QACpC,yDAAyD;QACzD,MAAM,EAAE,YAAY;QACpB,6IAA6I;QAC7I,SAAS,EAAE,eAAe;QAC1B,2HAA2H;QAC3H,KAAK,EAAE,WAAW;QAClB,iIAAiI;QACjI,OAAO,EAAE,aAAa;QACtB,0IAA0I;QAC1I,cAAc,EAAE,oBAAoB;QACpC,yJAAyJ;QACzJ,aAAa,EAAE,mBAAmB;QAClC,gIAAgI;QAChI,OAAO,EAAE,aAAa;QACtB,4JAA4J;QAC5J,KAAK,EAAE,WAAW;QAClB,+EAA+E;QAC/E,OAAO,EAAE,aAAa;QACtB,gGAAgG;QAChG,WAAW,EAAE,iBAAiB;QAC9B,oHAAoH;QACpH,QAAQ,EAAE,cAAc;QACxB,kIAAkI;QAClI,SAAS,EAAE,eAAe;QAC1B,iKAAiK;QACjK,KAAK,EAAE,WAAW;QAClB,qLAAqL;QACrL,SAAS,EAAE,eAAe;QAC1B,qKAAqK;QACrK,MAAM,EAAE,YAAY;QACpB,yPAAyP;QACzP,MAAM,EAAE,YAAY;QACpB,gNAAgN;QAChN,WAAW,EAAE,iBAAiB;KAC/B;CACO,CAAA"}
+{"version":3,"file":"namespace.js","sourceRoot":"","sources":["../../../src/infra/alerts/namespace.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAA;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AACvD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,aAAa,EAAE,YAAY,EAAE,oBAAoB,EAAE,eAAe,EAAE,iBAAiB,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAChM,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AACvF,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAA;AACzC,OAAO,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AACjG,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,iBAAiB,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAClG,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAA;AAC9D,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEhG,oHAAoH;AACpH,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,gCAAgC;IAChC,MAAM,EAAE,YAAY;IACpB,0HAA0H;IAC1H,IAAI,EAAE,UAAU;IAChB,wLAAwL;IACxL,YAAY;IACZ,oHAAoH;IACpH,aAAa,EAAE,iBAAiB;IAChC,2DAA2D;IAC3D,OAAO,EAAE,WAAW;IACpB,+DAA+D;IAC/D,MAAM,EAAE,UAAU;IAClB,kJAAkJ;IAClJ,SAAS;IACT,yRAAyR;IACzR,WAAW;IACX,oJAAoJ;IACpJ,cAAc;IACd,6QAA6Q;IAC7Q,cAAc;IACd,6NAA6N;IAC7N,UAAU,EAAE,aAAa;IACzB,MAAM,EAAE;QACN,4EAA4E;QAC5E,UAAU,EAAE,gBAAgB;QAC5B,iFAAiF;QACjF,WAAW,EAAE,iBAAiB;QAC9B,mGAAmG;QACnG,OAAO,EAAE,aAAa;QACtB,yGAAyG;QACzG,cAAc,EAAE,oBAAoB;QACpC,yDAAyD;QACzD,MAAM,EAAE,YAAY;QACpB,6IAA6I;QAC7I,SAAS,EAAE,eAAe;QAC1B,2HAA2H;QAC3H,KAAK,EAAE,WAAW;QAClB,iIAAiI;QACjI,OAAO,EAAE,aAAa;QACtB,0IAA0I;QAC1I,cAAc,EAAE,oBAAoB;QACpC,yJAAyJ;QACzJ,aAAa,EAAE,mBAAmB;QAClC,gIAAgI;QAChI,OAAO,EAAE,aAAa;QACtB,4JAA4J;QAC5J,KAAK,EAAE,WAAW;QAClB,+EAA+E;QAC/E,OAAO,EAAE,aAAa;QACtB,gGAAgG;QAChG,WAAW,EAAE,iBAAiB;QAC9B,oHAAoH;QACpH,QAAQ,EAAE,cAAc;QACxB,kIAAkI;QAClI,SAAS,EAAE,eAAe;QAC1B,iKAAiK;QACjK,KAAK,EAAE,WAAW;QAClB,qLAAqL;QACrL,SAAS,EAAE,eAAe;QAC1B,qKAAqK;QACrK,MAAM,EAAE,YAAY;QACpB,yPAAyP;QACzP,MAAM,EAAE,YAAY;QACpB,gNAAgN;QAChN,eAAe,EAAE,qBAAqB;QACtC,gNAAgN;QAChN,WAAW,EAAE,iBAAiB;KAC/B;CACO,CAAA"}

package/dist/infra/alerts/statement-sources.d.ts

@@ -0,0 +1,27 @@
+import type { StatementSettledFeed } from '../../core/config/statement-observer.js';
+import type { AlertSeverity } from './handle.js';
+import type { AlertSource } from './sources.js';
+export interface StatementTimingOptions {
+    /** Budget in ms per label: `{ 'gate-read': 1000 }`. A label not named here is never recorded. At least one. */
+    readonly budgets: Readonly<Record<string, number>>;
+    /** N: statements per label the p90 is taken over. The source stays quiet for a label until N have settled. */
+    readonly window: number;
+    /** Default `warning`, as the backlog source. */
+    readonly severity?: AlertSeverity;
+    readonly owner?: string;
+    readonly runbook?: string;
+}
+/** What `alerts.source.statementTiming` returns: an `AlertSource` that is also passed as `observability.statementTiming`. */
+export type StatementTimingSource = AlertSource & StatementSettledFeed;
+/**
+ * Raises `statement-slow:<label>` while the p90 duration of a label's last `window` settled statements is over
+ * that label's budget; resolves when it is back under. Statements are fed in-process by
+ * `observability.statementTiming` (pass the returned source there as well as to `alerts.create({ sources })`;
+ * the app's own `onStatementSettled` still fires). Only the labels in `budgets` are recorded, each in a ring of
+ * `window` numbers, so memory is bounded by `window` times the labels named; unlabelled statements and other
+ * labels are ignored. Failed statements count, with the time they took. The window is this process's: a tick sees
+ * only statements that settled in its own process, and a label that stops being called keeps its last window.
+ * Context carries `label`, `p90Ms`, `window` and `budgetMs`.
+ */
+export declare function statementTimingSource(options: StatementTimingOptions): StatementTimingSource;
+//# sourceMappingURL=statement-sources.d.ts.map

package/dist/infra/alerts/statement-sources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"statement-sources.d.ts","sourceRoot":"","sources":["../../../src/infra/alerts/statement-sources.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAyB,oBAAoB,EAAE,MAAM,yCAAyC,CAAA;AAC1G,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAChD,OAAO,KAAK,EAAkB,WAAW,EAAE,MAAM,cAAc,CAAA;AAE/D,MAAM,WAAW,sBAAsB;IACrC,+GAA+G;IAC/G,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAClD,8GAA8G;IAC9G,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,gDAAgD;IAChD,QAAQ,CAAC,QAAQ,CAAC,EAAE,aAAa,CAAA;IACjC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED,6HAA6H;AAC7H,MAAM,MAAM,qBAAqB,GAAG,WAAW,GAAG,oBAAoB,CAAA;AAUtE;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,qBAAqB,CAuD5F"}

package/dist/infra/alerts/statement-sources.js

@@ -0,0 +1,84 @@
+// An alert source over settled statements: per `pipe.labelled` label, the p90 of its last N durations against a budget.
+/** Nearest rank: the smallest sample that at least 90% of the samples are at or under. */
+function p90(samples) {
+    const sorted = [...samples].sort((a, b) => a - b);
+    return sorted[Math.ceil(sorted.length * 0.9) - 1];
+}
+/**
+ * Raises `statement-slow:<label>` while the p90 duration of a label's last `window` settled statements is over
+ * that label's budget; resolves when it is back under. Statements are fed in-process by
+ * `observability.statementTiming` (pass the returned source there as well as to `alerts.create({ sources })`;
+ * the app's own `onStatementSettled` still fires). Only the labels in `budgets` are recorded, each in a ring of
+ * `window` numbers, so memory is bounded by `window` times the labels named; unlabelled statements and other
+ * labels are ignored. Failed statements count, with the time they took. The window is this process's: a tick sees
+ * only statements that settled in its own process, and a label that stops being called keeps its last window.
+ * Context carries `label`, `p90Ms`, `window` and `budgetMs`.
+ */
+export function statementTimingSource(options) {
+    const who = 'alerts.source.statementTiming';
+    if (!Number.isInteger(options.window) || options.window < 1) {
+        throw new Error(`[pipework] ${who} window must be a positive integer number of statements, got ${String(options.window)}.`);
+    }
+    const entries = Object.entries(options.budgets);
+    if (entries.length === 0)
+        throw new Error(`[pipework] ${who} needs budgets: at least one label and its budget in ms.`);
+    const budgets = new Map();
+    for (const [label, budget] of entries) {
+        if (label === '')
+            throw new Error(`[pipework] ${who} budgets: a label must not be empty.`);
+        if (typeof budget !== 'number' || !Number.isFinite(budget) || budget <= 0) {
+            throw new Error(`[pipework] ${who} budget for "${label}" must be a positive number of milliseconds, got ${String(budget)}.`);
+        }
+        budgets.set(label, budget);
+    }
+    const size = options.window;
+    const severity = options.severity ?? 'warning';
+    const rings = new Map();
+    let attached = false;
+    const prefix = 'statement-slow:';
+    return {
+        name: 'statement-slow',
+        owns: key => key.startsWith(prefix),
+        observe(event) {
+            if (event.label === null || !budgets.has(event.label))
+                return;
+            let ring = rings.get(event.label);
+            if (ring === undefined) {
+                ring = { samples: [], next: 0 };
+                rings.set(event.label, ring);
+            }
+            if (ring.samples.length < size)
+                ring.samples.push(event.durationMs);
+            else {
+                ring.samples[ring.next] = event.durationMs;
+                ring.next = (ring.next + 1) % size;
+            }
+        },
+        attach() { attached = true; },
+        evaluate() {
+            if (!attached) {
+                return Promise.reject(new Error(`[pipework] ${who} was never given to the blueprint: set observability.statementTiming to this source, or it sees no statements.`));
+            }
+            const out = [];
+            for (const [label, budget] of budgets) {
+                const ring = rings.get(label);
+                if (ring === undefined || ring.samples.length < size)
+                    continue;
+                const value = p90(ring.samples);
+                if (value <= budget)
+                    continue;
+                out.push({
+                    key: `${prefix}${label}`,
+                    severity,
+                    message: `p90 of the last ${String(size)} "${label}" statements is ${String(value)} ms, over its ${String(budget)} ms budget`,
+                    subject: { entity: 'statement-label', entityId: label },
+                    ...(options.owner !== undefined ? { owner: options.owner } : {}),
+                    ...(options.runbook !== undefined ? { runbook: options.runbook } : {}),
+                    context: { label, p90Ms: value, window: size, budgetMs: budget },
+                });
+            }
+            return Promise.resolve(out);
+        },
+    };
+}
+//# sourceMappingURL=statement-sources.js.map

package/dist/infra/alerts/statement-sources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statement-sources.js","sourceRoot":"","sources":["../../../src/infra/alerts/statement-sources.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pipework",
-  "version": "0.284.0",
+  "version": "0.286.0",
   "description": "TypeScript framework for multi-tenant SaaS applications. PostgreSQL-only.",
   "type": "module",
   "license": "MIT",

package/src/core/config/load.ts

@@ -4,7 +4,7 @@ import { resolveEnvironment, resolveEnvironmentStrict, resolveDbUrl, resolveTest
 import { ConfigError } from './errors.js'
 import { resolveEnvVars } from './env-resolve.js'
 import { consumeConfigBaseDir } from './base-dir.js'
-import type { StatementObserver, StatementSettledObserver } from './statement-observer.js'
+import { composeSettledObservers, type StatementObserver, type StatementSettledObserver } from './statement-observer.js'
 
 export interface ResolvedObservability {
   readonly slowQueryMs: number
@@ -247,6 +247,8 @@ function buildResolved(config: Blueprint, environment: Environment, baseDir: str
 
   const env = Object.freeze(resolveEnvVars((config.env ?? {}) as import('./env-types.js').EnvDefs, environment))
 
+  config.observability?.statementTiming?.attach()
+
   return {
     raw: config,
     environment,
@@ -261,7 +263,10 @@ function buildResolved(config: Blueprint, environment: Environment, baseDir: str
       logAllQueries: config.observability?.logAllQueries ?? false,
       poolMetricsInterval: config.observability?.poolMetricsInterval ?? 0,
       onStatement: config.observability?.onStatement,
-      onStatementSettled: config.observability?.onStatementSettled,
+      onStatementSettled: composeSettledObservers([
+        ...(config.observability?.onStatementSettled !== undefined ? [config.observability.onStatementSettled] : []),
+        ...(config.observability?.statementTiming !== undefined ? [config.observability.statementTiming.observe] : []),
+      ]),
     },
     trace: {
       hotRetentionDays: config.trace?.hotRetentionDays ?? 7,

package/src/core/config/schema.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod/v4'
-import type { StatementObserver, StatementSettledObserver } from './statement-observer.js'
+import type { StatementObserver, StatementSettledObserver, StatementSettledFeed } from './statement-observer.js'
 
 const SETTING_NAME = /^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)?$/
 
@@ -187,7 +187,10 @@ const observabilitySchema = z.object({
     .describe('Per-statement observer — fires once per statement written to the wire, including driver-issued BEGIN/SAVEPOINT/COMMIT/ROLLBACK'),
   onStatementSettled: z.custom<StatementSettledObserver>(v => typeof v === 'function', { message: 'Expected a function' })
     .optional()
-    .describe('Per-statement completion hook — fires once per statement when it settles, with label, durationMs, rows, connectionId and (on failure) a sanitized error'),
+    .describe('Per-statement completion hook — fires once per statement when it settles, with label, statementId, statementPrefix, durationMs, rows, connectionId and (on failure) a sanitized error. Covers every statement through pipework\'s query path (pipe(), pipe.* writes, connection.drizzle, transactions, savepoints, the test harness), not the driver\'s own BEGIN/COMMIT, the raw client door or the migration runner\'s connection'),
+  statementTiming: z.custom<StatementSettledFeed>(v => typeof v === 'object' && v !== null && typeof (v as { observe?: unknown }).observe === 'function' && typeof (v as { attach?: unknown }).attach === 'function', { message: 'Expected the value returned by alerts.source.statementTiming' })
+    .optional()
+    .describe('Feeds alerts.source.statementTiming from every settled statement; fires alongside onStatementSettled, which keeps working'),
 })
 
 const envVarDefSchema = z.discriminatedUnion('type', [

package/src/core/config/statement-observer.ts

@@ -63,14 +63,39 @@ export interface StatementSettledError {
 /**
  * One statement as it settles — the completion counterpart to `StatementEvent`.
  * Fields are only ever added to this payload, never reshaped.
+ *
+ * Fires for every statement through pipework's query path (`pipe()`, `pipe.*`
+ * writes, `connection.drizzle`, transactions, savepoints, the test harness), not
+ * for the driver's own BEGIN/COMMIT, the raw `client` door or the migration
+ * runner's connection: a sum of `durationMs` leaves those out.
  */
 export interface StatementSettledEvent {
   /**
    * The `pipe.labelled` label in effect when the statement settled; null when
-   * none. This is the label alone: unlike `query:slow`, it never falls back to
-   * the statement text.
+   * none. This is the label alone: it never falls back to the statement text
+   * (`statementPrefix` carries that).
    */
   readonly label: string | null
+  /**
+   * Which statement shape this was, stable across calls and processes:
+   * `v1:` followed by the first 16 hex characters of the SHA-256 of the
+   * statement text exactly as sent to the server (parameterized, `$1`, `$2`...
+   * placeholders) with every run of whitespace collapsed to one space and the
+   * ends trimmed, hashed as UTF-8. It holds no constants and no bound values, so
+   * the same statement with different parameter values or different
+   * formatting has the same id, and different SQL has a different one.
+   * `v1` names this exact definition: a change to the hash, the length or the
+   * normalization gets a new prefix (`v2:`), never a silent redefinition, so
+   * records keyed on an id never split without the prefix saying so.
+   */
+  readonly statementId: string
+  /**
+   * The first 120 characters of the same whitespace-collapsed statement text
+   * (placeholders, no bound values): what `query:slow`, `query:in-flight` and
+   * `query:large` log as `sql`. A readable name for `statementId`; two shapes
+   * can share a prefix, so key on `statementId`.
+   */
+  readonly statementPrefix: string
   /**
    * Wall-clock milliseconds the statement took, measured by the same timer as
    * `query:slow` (so for one statement the two agree exactly).
@@ -93,13 +118,12 @@ export interface StatementSettledEvent {
 }
 
 /**
- * Caller-supplied completion hook. Fires once per statement that settles, on
- * every statement pipework runs through its own query path: `pipe()`, every
- * `pipe.*` write, `connection.drizzle`, transactions and savepoints, and the
- * test harness's connections. It does not fire for the driver's own
- * transaction control (`BEGIN`/`SAVEPOINT`/`COMMIT`/`ROLLBACK`), nor for the
- * raw `ManagedConnection.client` door, nor for the migration runner's own
- * connection; `onStatement` is the hook that sees wire truth.
+ * Caller-supplied completion hook. Fires once per statement that settles, for
+ * every statement through pipework's query path (`pipe()`, `pipe.*` writes,
+ * `connection.drizzle`, transactions, savepoints, the test harness), not for the
+ * driver's own BEGIN/COMMIT, the raw `client` door or the migration runner's
+ * connection; `onStatement` is the hook that sees wire truth. The event names the
+ * statement by `statementId` and `statementPrefix`, never by its parameters.
  *
  * Pure observation, fired after the statement has settled and its result is on
  * its way back: a hook that throws, or returns a promise that rejects, is
@@ -107,3 +131,35 @@ export interface StatementSettledEvent {
  * A returned promise is not awaited.
  */
 export type StatementSettledObserver = (event: StatementSettledEvent) => void | Promise<void>
+
+/**
+ * Something fed by every settled statement in addition to `observability.onStatementSettled`, passed as
+ * `observability.statementTiming` (`alerts.source.statementTiming` returns one). Both it and the app's own hook
+ * fire for each statement; neither replaces the other. `attach` is called once when the blueprint resolves, so the
+ * feed can tell that it was wired in.
+ */
+export interface StatementSettledFeed {
+  readonly observe: StatementSettledObserver
+  attach(): void
+}
+
+/** The hooks that fire for each settled statement, in order, one throwing never keeping the next from running. */
+export function composeSettledObservers(observers: readonly StatementSettledObserver[]): StatementSettledObserver | undefined {
+  if (observers.length === 0) return undefined
+  if (observers.length === 1) return observers[0]
+  return (event) => {
+    const pending: Promise<void>[] = []
+    const thrown: unknown[] = []
+    for (const observer of observers) {
+      try {
+        const out = observer(event)
+        if (out !== undefined) pending.push(out)
+      } catch (err) {
+        thrown.push(err)
+      }
+    }
+    if (thrown.length > 0) throw thrown[0]
+    if (pending.length > 0) return Promise.all(pending).then(() => undefined)
+    return undefined
+  }
+}

package/src/data/db/expressions.ts

@@ -341,6 +341,21 @@ export function arrayAppend<C extends Column>(col: C, value: ElementOf<C>): SQL<
   return sql<C['_']['data']>`array_append(${col}, ${element(col, value)}::${el})`
 }
 
+/**
+ * An array built from expressions: `ARRAY[e1, e2, ...]::<element>[]`, for the second argument of
+ * `arrayOverlaps` / `arrayContains` / `arrayContained`:
+ * `arrayOverlaps(t.keys, arrayOf(t.keys, concat(o.key, ':x'), concat(o.key, ':*')))`.
+ * `like` is an array column that supplies the element type (the one the result is compared with, or any
+ * column of the same type); it is read for its type only and does not appear in the SQL.
+ * A column or SQL expression element is used as is; a JS value is bound and converted by the element
+ * column's driver mapping. With no elements the result is the empty array `ARRAY[]::<element>[]`.
+ */
+export function arrayOf<C extends Column>(like: C, ...elements: Array<ElementOf<C> | Column | SQL>): SQL<C['_']['data']> {
+  const el = sql.raw(elementType(like, 'arrayOf'))
+  const parts = elements.map(e => (is(e, DrizzleColumn) || is(e, DrizzleSQL) ? e : element(like, e)))
+  return sql<C['_']['data']>`ARRAY[${sql.join(parts.map(p => sql`${p}`), sql`, `)}]::${el}[]`
+}
+
 /** PostgreSQL `array_remove(col, value)` — drops every element equal to `value`. `value` is bound and cast to the element type. */
 export function arrayRemove<C extends Column>(col: C, value: ElementOf<C>): SQL<C['_']['data']> {
   const el = sql.raw(elementType(col, 'arrayRemove'))

package/src/data/db/filter.ts

@@ -5,9 +5,9 @@ import {
 } from '../query/index.js'
 import { countAgg, countDistinctAgg, sumAgg, sumDistinctAgg, avgAgg, avgDistinctAgg, maxAgg, minAgg, boolAnd, boolOr, arrayAgg, stringAgg, jsonbAgg, jsonbObjectAgg, jsonbBuildObject } from './aggregates.js'
 import { except, exceptAll, intersect, intersectAll, union, unionAll } from '../query/pg-core/index.js'
-import { increment, decrement, add, subtract, coalesce, now, scalar, cast, collate, interval, clockTimestamp, strpos, textContains, startsWith, left, right, length, concat, arrayReplace, arrayHas, splitPart, lower, upper, trim, replace, substring, reverse, lpad, rpad, regexpReplace, regexpMatch, stringToArray, cardinality, arrayAt, arrayPosition, arraySlice, arrayToString, arrayAppend, arrayRemove, dateTrunc, rowNumber, rank, denseRank, over, identifier, withRecursive, caseWhen, walCurrentLsn, walReplayLsn, replicaFresh } from './expressions.js'
+import { increment, decrement, add, subtract, coalesce, now, scalar, cast, collate, interval, clockTimestamp, strpos, textContains, startsWith, left, right, length, concat, arrayReplace, arrayHas, splitPart, lower, upper, trim, replace, substring, reverse, lpad, rpad, regexpReplace, regexpMatch, stringToArray, cardinality, arrayAt, arrayPosition, arraySlice, arrayToString, arrayAppend, arrayOf, arrayRemove, dateTrunc, rowNumber, rank, denseRank, over, identifier, withRecursive, caseWhen, walCurrentLsn, walReplayLsn, replicaFresh } from './expressions.js'
 import { ago, castUuid, castJsonb, castTimestamp, castBoolean, castNumeric, castInteger, castText, nextSequence } from './composed.js'
-import { json as jsonbExtract, pathText as jsonbExtractText, contains as jsonbContains, merge as jsonbMerge, remove as jsonbRemove } from '../jsonb/query.js'
+import { json as jsonbExtract, pathText as jsonbExtractText, contains as jsonbContains, merge as jsonbMerge, concat as jsonbConcat, remove as jsonbRemove } from '../jsonb/query.js'
 import { arrayAny, arrayAll, jsonbElements } from './array-elements.js'
 import { inList, notInList } from './in-list.js'
 
@@ -56,6 +56,7 @@ export const filter = {
   arraySlice,
   arrayToString,
   arrayAppend,
+  arrayOf,
   arrayRemove,
   dateTrunc,
   rowNumber,
@@ -81,6 +82,7 @@ export const filter = {
   jsonbExtractText,
   jsonbContains,
   jsonbMerge,
+  jsonbConcat,
   jsonbRemove,
   arrayAny,
   arrayAll,

package/src/data/db/namespace.ts

@@ -38,7 +38,7 @@ export const pipe = Object.assign(getDb, {
   /** Query operators and aggregates — eq, gt, lt, and, or, count, sum, etc. */
   filter,
 
-  /** Names every statement `fn` starts, in `query:slow`, `query:large` and `query:in-flight` log lines: `pipe.labelled('servable-footprints', async () => await ...)`. A query builder is lazy: `fn` must await it, not return it, or it runs outside the scope. */
+  /** Names every statement `fn` starts, in `query:slow`, `query:large` and `query:in-flight` log lines (as `label`, beside the `sql` prefix): `pipe.labelled('servable-footprints', async () => await ...)`. A query builder is lazy: `fn` must await it, not return it, or it runs outside the scope. */
   labelled,
 
   /** Raw statement tag — for a statement pipework does not model. Interpolated values are parameters; `sql.raw` is not. Runs on the caller's connection, so inside a request it is the request transaction. Writes still go through pipe.update / insert / delete, which is what audit hooks. */

package/src/data/db/query-watch.ts

@@ -1,4 +1,5 @@
 import postgres from 'postgres'
+import { createHash } from 'node:crypto'
 import { getLogger } from '../../core/logging/logger.js'
 import { currentQueryLabel } from './query-label.js'
 import { DrizzleQueryError } from '../query/errors.js'
@@ -7,6 +8,7 @@ import type { StatementWatch } from '../query/postgres-js/session.js'
 import type { StatementSettledError, StatementSettledObserver } from '../../core/config/statement-observer.js'
 
 const LABEL_SQL_CHARS = 120
+const STATEMENT_ID_HEX_CHARS = 16
 const SAMPLE_TIMEOUT_MS = 2_000
 const PG_TRUNCATED_QUERY_LENGTH = 1_000
 
@@ -82,8 +84,22 @@ function settledError(raw: unknown): StatementSettledError {
   }
 }
 
-function labelFor(sqlText: string): string {
-  return currentQueryLabel() ?? sqlText.replace(/\s+/g, ' ').trim().slice(0, LABEL_SQL_CHARS)
+function collapse(sqlText: string): string {
+  return sqlText.replace(/\s+/g, ' ').trim()
+}
+
+/** The first 120 characters of the whitespace-collapsed statement text: the `sql` of the log lines and `statementPrefix`. */
+function sqlPrefix(sqlText: string): string {
+  return collapse(sqlText).slice(0, LABEL_SQL_CHARS)
+}
+
+/**
+ * `v1:` + the first 16 hex characters (64 bits) of the SHA-256 of the whitespace-collapsed
+ * parameterized text. 64 bits keeps a collision among an app's few thousand statement shapes
+ * negligible (birthday bound near 4 billion shapes) while the id stays short in a log line.
+ */
+function statementIdOf(sqlText: string): string {
+  return `v1:${createHash('sha256').update(collapse(sqlText)).digest('hex').slice(0, STATEMENT_ID_HEX_CHARS)}`
 }
 
 /**
@@ -157,7 +173,7 @@ export function createStatementWatch(options: StatementWatchOptions): StatementW
       check('sqlChars', b.sqlChars, () => sqlText.length)
       check('arms', b.arms, () => setOperationArms(sqlText))
       check('rows', b.rows, () => (outcome !== undefined && 'result' in outcome ? rowsOf(outcome.result) : 0))
-      if (over.length > 0) getLogger().warn({ label: labelFor(sqlText), database, over, ...measured }, 'query:large')
+      if (over.length > 0) getLogger().warn({ label: currentQueryLabel() ?? null, sql: sqlPrefix(sqlText), database, over, ...measured }, 'query:large')
     } catch { /* a measurement must never affect the statement */ }
   }
 
@@ -170,13 +186,14 @@ export function createStatementWatch(options: StatementWatchOptions): StatementW
     let settled = false
     if (inFlightQueryMs !== undefined) {
       const log = getLogger()
-      const label = labelFor(sqlText)
+      const label = currentQueryLabel() ?? null
+      const sql = sqlPrefix(sqlText)
       interval = setInterval(() => {
         const elapsedS = Math.round((Date.now() - startedMs) / 100) / 10
         void sampleBackend(sqlText, startedMs).then(backend => {
           if (settled) return
           log.warn({
-            label, elapsedS, database,
+            label, sql, elapsedS, database,
             pid: backend.pid, state: backend.state,
             waitEventType: backend.waitEventType, waitEvent: backend.waitEvent,
           }, 'query:in-flight')
@@ -196,7 +213,7 @@ export function createStatementWatch(options: StatementWatchOptions): StatementW
       if (interval !== undefined) clearInterval(interval)
       const durationMs = Date.now() - startedMs
       if (slowQueryMs > 0 && durationMs > slowQueryMs) {
-        getLogger().warn({ label: labelFor(sqlText), durationMs, database }, 'query:slow')
+        getLogger().warn({ label: currentQueryLabel() ?? null, sql: sqlPrefix(sqlText), durationMs, database }, 'query:slow')
       }
       const parameters = pendingQuery === undefined ? undefined : (pendingQuery as { parameters?: unknown }).parameters
       if (watchesSize) warnIfLarge(sqlText, parameters, outcome, budgets)
@@ -204,6 +221,8 @@ export function createStatementWatch(options: StatementWatchOptions): StatementW
         const connectionId = typeof parameters === 'object' && parameters !== null ? connections?.get(parameters) ?? null : null
         fireSettled({
           label: currentQueryLabel() ?? null,
+          statementId: statementIdOf(sqlText),
+          statementPrefix: sqlPrefix(sqlText),
           durationMs,
           rows: 'result' in outcome ? rowsOf(outcome.result) : 0,
           connectionId,

package/src/data/jsonb/namespace.ts

@@ -1,4 +1,4 @@
-import { contains, merge, remove, containedBy, hasKey, text, json, path, pathText } from './query.js'
+import { contains, merge, concat, remove, containedBy, hasKey, text, json, path, pathText } from './query.js'
 import { boolean, number, integer } from './composed.js'
 
 /** JSONB query operators — typed helpers for PostgreSQL JSONB containment, key checks, and field extraction. */
@@ -7,6 +7,8 @@ export const jsonb = {
   contains,
   /** Merges an object into a JSONB column in `.set()`: `coalesce(col, '{}') || value`. Top-level keys overwrite; others are kept. */
   merge,
+  /** Appends to a JSONB column in `.set()`: `col || $1::jsonb`, value bound as jsonb. An array appends its elements; a null column stays null. */
+  concat,
   /** Removes top-level keys from a JSONB column in `.set()`: `col - 'key'`. Composes as the column of `jsonb.merge`. */
   remove,
   /** The <@ contained-by operator — tests whether a JSONB column is contained by the given value. */

package/src/data/jsonb/query.ts

@@ -43,6 +43,25 @@ export function pathText(column: Column | SQL, ...keys: string[]): SQL<string> {
   return text(intermediate, finalKey)
 }
 
+/**
+ * Appends to a JSONB column for `.set()`, typically in `onConflictDoUpdate`: `col || $1::jsonb`, with `value`
+ * serialized and bound as jsonb. Appending an array to an array column adds its elements (`[1] || [2]` is `[1, 2]`);
+ * an object merges its top-level keys. The append happens in the statement, so concurrent upserts each
+ * add their element and none is lost. A null column stays null (SQL `||`): seed the column on insert, or
+ * wrap it in `coalesce(col, '[]'::jsonb)`.
+ */
+export function concat(column: Column | SQL, value: unknown): SQL {
+  const json: unknown = JSON.stringify(value)
+  if (typeof json !== 'string') {
+    throw new Error(
+      '[pipework] jsonb.concat() needs a JSON-serializable value, got ' + typeof value + '.\n\n' +
+      '  undefined, functions and symbols have no JSON form.\n' +
+      "  Fix: pass a value JSON can hold: jsonb.concat(col, [{ id: 1 }]).\n",
+    )
+  }
+  return sql`(${column} || ${json}::jsonb)`
+}
+
 /**
  * Merges `value` into a JSONB column for `.set()`: `coalesce(col, '{}'::jsonb) || value::jsonb`. Top-level keys
  * in `value` overwrite; others are kept; a null column becomes `value`. The merge happens in the statement,
@@ -57,7 +76,7 @@ export function merge(column: Column | SQL, value: Record<string, unknown>): SQL
       "  Fix: pass an object: jsonb.merge(col, { key: 'value' }).\n",
     )
   }
-  return sql`coalesce(${column}, '{}'::jsonb) || ${JSON.stringify(value)}::jsonb`
+  return sql`(coalesce(${column}, '{}'::jsonb) || ${JSON.stringify(value)}::jsonb)`
 }
 
 /**
@@ -81,6 +100,6 @@ export function remove(column: Column | SQL, ...keys: string[]): SQL {
       )
     }
   }
-  if (keys.length === 1) return sql`${column} - ${keys[0]!}::text`
-  return sql`${column} - array[${sql.join(keys.map(k => sql`${k}`), sql`, `)}]::text[]`
+  if (keys.length === 1) return sql`(${column} - ${keys[0]!}::text)`
+  return sql`(${column} - array[${sql.join(keys.map(k => sql`${k}`), sql`, `)}]::text[])`
 }

package/src/index.ts

@@ -21,7 +21,7 @@ export type { TimeoutOptions } from './data/db/timeouts.js'
 // sanctioned door to a raw connection; keeps the WRAPPED_PACKAGES postgres ban airtight.
 export { tap } from './data/db/pool.js'
 export type { ManagedConnection, ConnectOptions } from './data/db/pool.js'
-export type { StatementObserver, StatementEvent, StatementSettledObserver, StatementSettledEvent, StatementSettledError } from './core/config/statement-observer.js'
+export type { StatementObserver, StatementEvent, StatementSettledObserver, StatementSettledEvent, StatementSettledError, StatementSettledFeed } from './core/config/statement-observer.js'
 
 export type { DefinedTable, ExternalTable, DomainDefinition, DefinitionMethods, FieldDescriptor, FieldModifiers, FieldMeta, DefineOptions,
   FactoryBuilder, FactoryOptions, TraitDefinition, FieldColumn, ProjectedColumns,

package/src/infra/alerts/index.ts

@@ -10,3 +10,4 @@ export type { AlertsHttpOptions } from './http.js'
 export { clientFaults } from './client-faults.js'
 export type { ClientFaultsOptions, ClientFaultReport } from './client-faults.js'
 export type { RequestFaultsOptions } from './request-faults.js'
+export type { StatementTimingOptions, StatementTimingSource } from './statement-sources.js'

package/src/infra/alerts/namespace.ts

@@ -8,6 +8,7 @@ import { recordFault, recordFaultFor, useFaultTarget, faultsSource } from './fau
 import { recordBeatFor } from './beat.js'
 import { deliveryFailedSource, webhookFailedSource, creditsSource } from './subsystem-sources.js'
 import { emailSource, storageSource, accessLinksSource, lockoutsSource } from './infra-sources.js'
+import { statementTimingSource } from './statement-sources.js'
 import { schedulesSource, stepsSource, pipelinesSource, tracesSource } from './async-sources.js'
 
 /** Alerts namespace — raise and resolve keyed conditions, grouped, delivered to sinks through an outbox, traced. */
@@ -75,6 +76,8 @@ export const alerts = {
     traces: tracesSource,
     /** Raises `fault:<kind>` per kind of swallowed failure recorded by `recordFault` since the last tick (the pipework subsystems record audit-write, quota-record, credits-callback, trace-steps-lost, queue-* and scheduler faults). `kinds` limits it. */
     faults: faultsSource,
+    /** Raises `statement-slow:<label>` while the p90 of a `pipe.labelled` label's last `window` settled statements is over that label's budget; give the returned source to `observability.statementTiming` too. */
+    statementTiming: statementTimingSource,
     /** Raises `loop-stalled:<name>` while a background loop (scheduler, reaper, claim loop, support drain) has not run or succeeded within its allowance; the tick itself is covered by `pipework alerts stale`. */
     loopStalled: loopStalledSource,
   },