pipework 0.285.0 → 0.287.0

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_]*)?$/
 
@@ -188,6 +188,9 @@ const observabilitySchema = z.object({
   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, 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

@@ -131,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 (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. */
+  /** Names every statement `fn` starts, in `query:slow`, `query:large` and `query:in-flight` log lines (as `label`, beside the `sql` prefix) and, as a leading block comment on the SQL sent, in `pg_stat_activity.query`, server logs and `pg_stat_statements` text (the comment does not change the statement's queryid). In the comment the label is made safe: comment delimiters are split with a space, control characters become spaces, and it is cut to 80 characters; the log lines carry it as given. `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-label.ts

@@ -2,7 +2,34 @@ import { AsyncLocalStorage } from 'node:async_hooks'
 
 const scope = new AsyncLocalStorage<string>()
 
-/** Runs `fn` with `label` naming every statement it starts, in slow-query and in-flight-query log lines. */
+const COMMENT_LABEL_CHARS = 80
+
+/**
+ * Makes a label safe to sit inside a `/* ... *\/` comment. Postgres block comments nest, so both `*\/`
+ * and `/*` are broken apart by a space (repeated, so `*\/*` cannot recombine), control characters
+ * (newlines, NUL) become spaces, and the text is cut to 80 characters so it leaves room in
+ * `pg_stat_activity.query` (1024 bytes by default). Returns undefined when nothing printable is left.
+ */
+export function commentSafeLabel(label: string): string | undefined {
+  let safe = label.replace(/[\u0000-\u001f\u007f\u2028\u2029]+/g, ' ').trim().slice(0, COMMENT_LABEL_CHARS)
+  while (/\*\/|\/\*/.test(safe)) safe = safe.replace(/\*\/|\/\*/g, m => `${m[0]!} ${m[1]!}`)
+  safe = safe.trim()
+  return safe === '' ? undefined : safe
+}
+
+/**
+ * `sqlText` with the enclosing `labelled` label as a leading `/* label *\/` comment, so the label shows in
+ * `pg_stat_activity.query`, server logs and `pg_stat_statements` text. Unchanged outside a scope.
+ * A comment is chosen over `application_name` because it costs no round trip, needs no transaction
+ * and does not change `pg_stat_statements`' queryid (which ignores comments), so labels never split a statement's stats.
+ */
+export function withLabelComment(sqlText: string): string {
+  const label = scope.getStore()
+  const safe = label === undefined ? undefined : commentSafeLabel(label)
+  return safe === undefined ? sqlText : `/* ${safe} */ ${sqlText}`
+}
+
+/** Runs `fn` with `label` naming every statement it starts, in slow-query and in-flight-query log lines and as a leading SQL comment (see `withLabelComment`). */
 export function labelled<T>(label: string, fn: () => T): T {
   return scope.run(label, fn)
 }

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

@@ -1,7 +1,7 @@
 import postgres from 'postgres'
 import { createHash } from 'node:crypto'
 import { getLogger } from '../../core/logging/logger.js'
-import { currentQueryLabel } from './query-label.js'
+import { currentQueryLabel, withLabelComment } from './query-label.js'
 import { DrizzleQueryError } from '../query/errors.js'
 import { parameterBytes, setOperationArms } from './query-size.js'
 import type { StatementWatch } from '../query/postgres-js/session.js'
@@ -129,7 +129,7 @@ export function createStatementWatch(options: StatementWatchOptions): StatementW
        WHERE datname = current_database() AND pid <> pg_backend_pid() AND state <> 'idle'
          AND (query = $1 OR (length(query) >= ${String(PG_TRUNCATED_QUERY_LENGTH)} AND left($1, length(query)) = query))
        ORDER BY abs(extract(epoch FROM query_start) - $2::float8) LIMIT 1`,
-      [sqlText, startedMs / 1000],
+      [withLabelComment(sqlText), startedMs / 1000],
     ).then(rows => {
       const row = rows[0]
       return row === undefined

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/data/query/postgres-js/session.ts

@@ -13,6 +13,7 @@ import type { RelationalSchemaConfig, TablesRelationalConfig } from '../relation
 import { fillPlaceholders, type Query } from '../sql/sql.js';
 import { tracer } from '../tracing.js';
 import { type Assume, mapResultRow } from '../utils.js';
+import { withLabelComment } from '../../db/query-label.js';
 import { propagateObserved, throughErrorBoundary } from './driver-error-boundary.js';
 
 /** Wraps one statement's execution; installed by the pool to time it and report it while it runs. */
@@ -26,7 +27,7 @@ function noteSeen(): void {}
 
 /** Starts the statement and tells the watch which pending query it is, so it can learn the connection it runs on. */
 function startUnsafe(client: Sql, query: string, params: unknown[], seen: (pending: object) => void) {
-	const pending = client.unsafe(query, params as any[]);
+	const pending = client.unsafe(withLabelComment(query), params as any[]);
 	seen(pending);
 	return pending;
 }

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,
   },

package/src/infra/alerts/statement-sources.ts

@@ -0,0 +1,94 @@
+// An alert source over settled statements: per `pipe.labelled` label, the p90 of its last N durations against a budget.
+
+import type { StatementSettledEvent, StatementSettledFeed } from '../../core/config/statement-observer.js'
+import type { AlertSeverity } from './handle.js'
+import type { AlertCondition, 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
+
+interface Ring { readonly samples: number[]; next: number }
+
+/** Nearest rank: the smallest sample that at least 90% of the samples are at or under. */
+function p90(samples: readonly number[]): number {
+  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: StatementTimingOptions): StatementTimingSource {
+  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<string, number>()
+  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<string, Ring>()
+  let attached = false
+  const prefix = 'statement-slow:'
+
+  return {
+    name: 'statement-slow',
+    owns: key => key.startsWith(prefix),
+    observe(event: StatementSettledEvent): void {
+      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(): void { attached = true },
+    evaluate(): Promise<AlertCondition[]> {
+      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: AlertCondition[] = []
+      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)
+    },
+  }
+}