pipework 0.274.0 → 0.276.0

package/src/cli/commands/check.ts

@@ -946,7 +946,7 @@ export function resolveEslintBin(cwd: string): string {
 // the file itself changes. Stamping the cache path with pipework's own version
 // (read here from pipework's package.json) makes a bump point eslint at a fresh
 // cache file, busting the stale verdicts. #781-followup
-function pipeworkVersion(): string {
+export function pipeworkVersion(): string {
   // dist/cli/commands/check.js → pipework root is three levels up; mirrors the
   // builtin-preset path resolution used in lintDirectory.
   const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', 'package.json')
@@ -1060,7 +1060,7 @@ export function hasFatalParseError(stdout: string): boolean {
   })
 }
 
-function hasEslintConfig(dir: string): boolean {
+export function hasEslintConfig(dir: string): boolean {
   return existsSync(join(dir, 'eslint.config.js'))
     || existsSync(join(dir, 'eslint.config.mjs'))
     || existsSync(join(dir, 'eslint.config.ts'))
@@ -1435,8 +1435,10 @@ export interface LintPopulation {
   readonly modules: ReadonlyArray<{ readonly path: string; readonly includes: readonly string[] | undefined }>
   /** Root files outside every module; empty off shard 1. */
   readonly root: string[]
-  /** Every file the run lints, repo-relative and sorted. */
+  /** Every file the globs reach, repo-relative and sorted; eslint may still ignore some. */
   readonly files: string[]
+  /** Each of `files` with the directory eslint runs in for it (a module, or the root pass). */
+  readonly candidates: ReadonlyArray<{ readonly file: string; readonly dir: string }>
 }
 
 /**
@@ -1454,15 +1456,17 @@ export function lintPopulation(
   const root = shard !== undefined && shard.index !== 1
     ? []
     : rootFilesOutsideModules(cwd, [...allModules], includes.for('.'))
-  const files = new Set<string>(root)
+  const owners = new Map<string, string>(root.map(f => [f, cwd]))
   for (const mod of modules) {
     const dir = join(cwd, mod.path)
     const prefix = normalizeModulePath(mod.path)
     for (const f of filesMatchingGlobs(dir, lintIncludeGlobs(dir, mod.includes))) {
-      files.add(prefix === '' ? f : `${prefix}/${f}`)
+      const file = prefix === '' ? f : `${prefix}/${f}`
+      if (!owners.has(file)) owners.set(file, dir)
     }
   }
-  return { modules, root, files: [...files].sort() }
+  const files = [...owners.keys()].sort()
+  return { modules, root, files, candidates: files.map(file => ({ file, dir: owners.get(file)! })) }
 }
 
 /**

package/src/cli/commands/lint-settings.ts

@@ -0,0 +1,218 @@
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { lintIncludeGlobs } from '../../lint/include.js'
+import { resolveLintConfig } from '../../lint/resolver.js'
+import { hasEslintConfig, pipeworkVersion, type LintPopulation } from './check.js'
+
+interface EslintApi {
+  isPathIgnored(file: string): Promise<boolean>
+  calculateConfigForFile(file: string): Promise<unknown>
+}
+type EslintCtor = new (options: Record<string, unknown>) => EslintApi
+
+export interface FileCoverage {
+  readonly file: string
+  readonly covered: boolean
+  readonly reason?: 'ignored' | 'no matching configuration'
+}
+
+export interface ModuleDigest {
+  readonly module: string
+  readonly digest: string
+  readonly inputs: Record<string, unknown>
+}
+
+const here = dirname(fileURLToPath(import.meta.url))
+
+function resolveFrom(cwd: string, request: string): string {
+  return createRequire(import.meta.url).resolve(request, { paths: [cwd, here] })
+}
+
+function packageVersion(cwd: string, name: string): string {
+  try {
+    const pkg = JSON.parse(readFileSync(resolveFrom(cwd, `${name}/package.json`), 'utf-8')) as { version?: string }
+    return pkg.version ?? 'unknown'
+  } catch {
+    return 'unknown'
+  }
+}
+
+async function loadEslint(cwd: string): Promise<EslintCtor> {
+  const mod = await import(pathToFileURL(resolveFrom(cwd, 'eslint')).href) as { ESLint?: EslintCtor; default?: { ESLint?: EslintCtor } }
+  const ctor = mod.ESLint ?? mod.default?.ESLint
+  if (ctor === undefined) throw new Error('eslint is installed but does not export ESLint')
+  return ctor
+}
+
+/**
+ * eslint as `check` runs it in `dir`: the directory's own eslint.config.* when it has
+ * one, else pipework's resolved preset for that directory (what `--config preset.js`
+ * loads, with the same cwd).
+ */
+async function eslintFor(ESLint: EslintCtor, dir: string): Promise<EslintApi> {
+  if (hasEslintConfig(dir)) return new ESLint({ cwd: dir })
+  return new ESLint({ cwd: dir, overrideConfigFile: true, baseConfig: await resolveLintConfig(dir) })
+}
+
+/**
+ * Whether eslint would lint each candidate file: not ignored, and some config block
+ * applies. The answer is eslint's own, asked with the config `check` uses.
+ */
+export async function classifyCoverage(cwd: string, population: LintPopulation): Promise<FileCoverage[]> {
+  const ESLint = await loadEslint(cwd)
+  const instances = new Map<string, EslintApi>()
+  const out: FileCoverage[] = []
+  for (const { file, dir } of population.candidates) {
+    let eslint = instances.get(dir)
+    if (eslint === undefined) {
+      eslint = await eslintFor(ESLint, dir)
+      instances.set(dir, eslint)
+    }
+    const abs = resolve(cwd, file)
+    if (await eslint.isPathIgnored(abs)) {
+      out.push({ file, covered: false, reason: 'ignored' })
+    } else if (await eslint.calculateConfigForFile(abs) === undefined) {
+      out.push({ file, covered: false, reason: 'no matching configuration' })
+    } else {
+      out.push({ file, covered: true })
+    }
+  }
+  return out
+}
+
+function isPlainObject(value: object): boolean {
+  const proto = Object.getPrototypeOf(value) as unknown
+  return proto === Object.prototype || proto === null
+}
+
+function describeNamed(value: object): Record<string, unknown> {
+  const meta = (value as { meta?: { name?: unknown; version?: unknown } }).meta
+  const rules = (value as { rules?: unknown }).rules
+  return {
+    object: value.constructor.name,
+    ...(typeof meta?.name === 'string' ? { name: meta.name } : {}),
+    ...(typeof meta?.version === 'string' ? { version: meta.version } : {}),
+    ...(typeof rules === 'object' && rules !== null ? { rules: Object.keys(rules).sort() } : {}),
+  }
+}
+
+/**
+ * A JSON value with sorted keys. A function is its name, a plugin or parser object its
+ * `meta` and rule names: never identity, so the same settings hash the same in every run.
+ */
+function canonical(value: unknown, seen: Set<object> = new Set()): unknown {
+  if (value === undefined) return null
+  if (typeof value === 'function') return { function: value.name }
+  if (typeof value === 'bigint') return String(value)
+  if (typeof value === 'symbol') return value.toString()
+  if (value instanceof RegExp) return { regexp: value.toString() }
+  if (typeof value !== 'object' || value === null) return value
+  if (seen.has(value)) return { cycle: true }
+  seen.add(value)
+  try {
+    if (Array.isArray(value)) return value.map(v => canonical(v, seen))
+    if (!isPlainObject(value)) return describeNamed(value)
+    const out: Record<string, unknown> = {}
+    for (const key of Object.keys(value).sort()) {
+      const item = (value as Record<string, unknown>)[key]
+      // `plugins` and `parser` hold live objects whose identity is meaningless.
+      if ((key === 'parser' || key === 'processor') && typeof item === 'object' && item !== null) out[key] = describeNamed(item)
+      else if (key === 'plugins' && typeof item === 'object' && item !== null && !Array.isArray(item)) {
+        out[key] = Object.fromEntries(Object.keys(item).sort().map(name =>
+          [name, describeNamed((item as Record<string, object>)[name]!)]))
+      } else out[key] = canonical(item, seen)
+    }
+    return out
+  } finally {
+    seen.delete(value)
+  }
+}
+
+function sha256(value: unknown): string {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex')
+}
+
+function ignoreGlobs(blocks: readonly unknown[]): string[] {
+  const globs: string[] = []
+  for (const block of blocks) {
+    if (typeof block !== 'object' || block === null) continue
+    const b = block as { files?: unknown; ignores?: unknown }
+    if (b.files === undefined && Array.isArray(b.ignores)) {
+      for (const g of b.ignores) if (typeof g === 'string') globs.push(g)
+    }
+  }
+  return globs
+}
+
+/**
+ * The digest of what decides lint for one module directory: include globs, and the
+ * sorted distinct resolved configs (eslint's own `calculateConfigForFile`: rules,
+ * language options, settings) over every covered file, so extras, module overrides and
+ * per-file blocks are all in and the set does not move when a file joins a region whose
+ * config is already present. Global ignores, plugin names and the preset blocks are
+ * inputs only where pipework's preset is what runs; a directory with its own
+ * eslint.config.* is described by the configs alone. The tsconfig the type-aware rules
+ * read is not an input.
+ */
+export async function digestModule(
+  cwd: string,
+  ESLint: EslintCtor,
+  label: string,
+  dir: string,
+  includes: readonly string[] | undefined,
+  coveredFiles: readonly string[],
+): Promise<ModuleDigest> {
+  const own = hasEslintConfig(dir)
+  const blocks = own ? undefined : await resolveLintConfig(dir)
+  const eslint = await eslintFor(ESLint, dir)
+  const configs = new Map<string, unknown>()
+  for (const file of coveredFiles) {
+    // eslint's Config is a class instance with its own toJSON (plugins and parsers by name).
+    const resolved = await eslint.calculateConfigForFile(resolve(cwd, file))
+    const config = canonical(JSON.parse(JSON.stringify(resolved ?? null)))
+    configs.set(JSON.stringify(config), config)
+  }
+  const inputs = canonical({
+    pipework: pipeworkVersion(),
+    eslint: packageVersion(cwd, 'eslint'),
+    typescriptEslint: packageVersion(cwd, '@typescript-eslint/eslint-plugin'),
+    include: lintIncludeGlobs(dir, includes),
+    configs: [...configs.keys()].sort().map(k => configs.get(k)),
+    ...(blocks === undefined ? {} : {
+      ignores: ignoreGlobs(blocks),
+      plugins: [...new Set(blocks.flatMap(b => typeof b === 'object' && b !== null && 'plugins' in b
+        ? Object.keys((b as { plugins: object }).plugins) : []))].sort(),
+      blocks,
+    }),
+  }) as Record<string, unknown>
+  return { module: label, digest: sha256(inputs), inputs }
+}
+
+export async function settingsDigests(
+  cwd: string,
+  population: LintPopulation,
+  includes: { for: (mod: string) => readonly string[] | undefined },
+  coverage: readonly FileCoverage[],
+  rootPass: boolean,
+): Promise<ModuleDigest[]> {
+  const ESLint = await loadEslint(cwd)
+  const coveredIn = new Map<string, string[]>()
+  const dirOf = new Map(population.candidates.map(c => [c.file, c.dir]))
+  for (const c of coverage) {
+    const dir = dirOf.get(c.file)
+    if (c.covered && dir !== undefined) coveredIn.set(dir, [...(coveredIn.get(dir) ?? []), c.file])
+  }
+  const out: ModuleDigest[] = []
+  const hasRoot = population.modules.some(m => m.path === '.' || m.path === '')
+  for (const mod of population.modules) {
+    const dir = join(cwd, mod.path)
+    out.push(await digestModule(cwd, ESLint, mod.path === '' ? '.' : mod.path, dir, mod.includes, coveredIn.get(dir) ?? []))
+  }
+  if (rootPass && !hasRoot) {
+    out.push(await digestModule(cwd, ESLint, '.', cwd, includes.for('.'), coveredIn.get(cwd) ?? []))
+  }
+  return out.sort((a, b) => a.module < b.module ? -1 : a.module > b.module ? 1 : 0)
+}

package/src/cli/commands/lint.ts

@@ -3,7 +3,8 @@ import { dirname, relative } from 'node:path'
 import { findConfig } from '../../core/config/discover.js'
 import { error } from '../output.js'
 import { builtinConfigArgs, lintPopulation, lintTargets, loadLintIncludes, resolveEslintBin, resolveModulePaths } from './check.js'
-import { parseShard } from './shard.js'
+import { parseShard, type Shard } from './shard.js'
+import { classifyCoverage, settingsDigests } from './lint-settings.js'
 
 // eslint options that take their value as the next argument. Anything else starting
 // with `-` is a switch, so the argument after it is a file.
@@ -38,6 +39,7 @@ export function namesFiles(args: readonly string[]): boolean {
  */
 export async function lintCommand(cwd: string, args: readonly string[]): Promise<number> {
   if (args.includes('--list-files')) return listFiles(cwd, args)
+  if (args.includes('--settings-digest')) return settingsDigest(cwd, args)
   const eslintBin = resolveEslintBin(cwd)
   const configPath = findConfig(cwd)
   const root = configPath === null ? cwd : dirname(configPath)
@@ -64,32 +66,81 @@ export async function lintCommand(cwd: string, args: readonly string[]): Promise
 }
 
 /**
- * `pipework lint --list-files [--shard i/n]`: the repo-relative files `check`'s lint
- * pass covers, one per line, read from pipework.config.ts. Nothing is linted.
+ * `--list-files` and `--settings-digest` take only `--shard <i>/<n>` and `--format json`.
+ * Returns the parsed options, or null after reporting the problem.
  */
-async function listFiles(cwd: string, args: readonly string[]): Promise<number> {
-  const rest = args.filter(a => a !== '--list-files')
-  let shard
-  if (rest.length === 2 && rest[0] === '--shard') {
-    try {
-      shard = parseShard(rest[1]!)
-    } catch (err) {
-      error(err instanceof Error ? err.message : String(err))
-      return 1
+function parseReportArgs(flag: string, args: readonly string[]): { shard: Shard | undefined; json: boolean } | null {
+  let shard: Shard | undefined
+  let json = false
+  const rest = args.filter(a => a !== flag)
+  const bad = (): null => {
+    error(`${flag} takes only --shard <i>/<n> and --format json; got ${rest.join(' ')}. It does not run eslint.`)
+    return null
+  }
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i]!
+    if (arg === '--shard' && i + 1 < rest.length) {
+      try {
+        shard = parseShard(rest[++i]!)
+      } catch (err) {
+        error(err instanceof Error ? err.message : String(err))
+        return null
+      }
+    } else if ((arg === '--format' && rest[i + 1] === 'json') || arg === '--format=json') {
+      if (arg === '--format') i++
+      json = true
+    } else {
+      return bad()
     }
-  } else if (rest.length > 0) {
-    error(`--list-files takes only --shard <i>/<n>; got ${rest.join(' ')}. It lists files and does not run eslint.`)
-    return 1
   }
+  return { shard, json }
+}
 
+async function reportPopulation(cwd: string, flag: string, args: readonly string[]) {
+  const opts = parseReportArgs(flag, args)
+  if (opts === null) return null
   const configPath = findConfig(cwd)
   const root = configPath === null ? cwd : dirname(configPath)
   const scope = await resolveModulePaths(root)
   if (scope.configError !== undefined) {
-    error(`Cannot list lint files: pipework.config.ts failed to load: ${scope.configError.message}`)
-    return 1
+    error(`Cannot ${flag === '--list-files' ? 'list lint files' : 'digest lint settings'}: pipework.config.ts failed to load: ${scope.configError.message}`)
+    return null
   }
-  const population = lintPopulation(root, scope.paths, await loadLintIncludes(root), shard)
-  if (population.files.length > 0) process.stdout.write(population.files.join('\n') + '\n')
+  const includes = await loadLintIncludes(root)
+  const population = lintPopulation(root, scope.paths, includes, opts.shard)
+  return { ...opts, root, includes, population }
+}
+
+/**
+ * `pipework lint --list-files [--shard i/n] [--format json]`: the repo-relative files
+ * `check`'s lint pass covers and eslint will lint, one per line. Files the include globs
+ * reach but the lint config ignores are left out; `--format json` lists every candidate
+ * with `covered` and, when false, why. Nothing is linted.
+ */
+async function listFiles(cwd: string, args: readonly string[]): Promise<number> {
+  const ctx = await reportPopulation(cwd, '--list-files', args)
+  if (ctx === null) return 1
+  const coverage = await classifyCoverage(ctx.root, ctx.population)
+  if (ctx.json) {
+    process.stdout.write(JSON.stringify(coverage, null, 2) + '\n')
+    return 0
+  }
+  const covered = coverage.filter(c => c.covered).map(c => c.file)
+  if (covered.length > 0) process.stdout.write(covered.join('\n') + '\n')
+  return 0
+}
+
+/**
+ * `pipework lint --settings-digest [--shard i/n] [--format json]`: one sha256 per
+ * module (the root pass is `.`) of what decides lint there. Nothing is linted.
+ */
+async function settingsDigest(cwd: string, args: readonly string[]): Promise<number> {
+  const ctx = await reportPopulation(cwd, '--settings-digest', args)
+  if (ctx === null) return 1
+  const coverage = await classifyCoverage(ctx.root, ctx.population)
+  const rootPass = ctx.shard === undefined || ctx.shard.index === 1
+  const digests = await settingsDigests(ctx.root, ctx.population, ctx.includes, coverage, rootPass)
+  if (ctx.json) process.stdout.write(JSON.stringify(digests, null, 2) + '\n')
+  else if (digests.length > 0) process.stdout.write(digests.map(d => `${d.module} ${d.digest}`).join('\n') + '\n')
   return 0
 }

package/src/cli/index.ts

@@ -24,7 +24,8 @@ ${bold('Commands:')}
   cardinality [files]  @downstream cardinality rules alone (same options)
   startup           Startup validation alone: pipework.config.ts loaded, no database
   lint [eslint args]  Lint the current module (the workspace at its root) with check's config; every argument goes to eslint
-                    lint --list-files [--shard i/n]: print the files check's lint covers, lint nothing
+                    lint --list-files [--shard i/n] [--format json]: print the files eslint will lint (json: every candidate, covered or not), lint nothing
+                    lint --settings-digest [--shard i/n] [--format json]: print a digest per module of the resolved lint settings, lint nothing
   codemod           Fill missing @downstream cardinality across the corpus
   db                Database lifecycle: setup, teardown, reset
   alerts unit-fault Record an abnormal systemd stop (ExecStopPost=pipework alerts unit-fault --unit %n)
@@ -93,6 +94,7 @@ ${bold('Examples:')}
   pipework lint                       # the module you are in, exactly as check lints it
   pipework lint --format json --output-file r.json src/a.ts   # only src/a.ts
   pipework lint --list-files --shard 1/4   # the files check's lint pass covers for part 1 of 4, from pipework.config.ts
+  pipework lint --settings-digest --format json   # per-module digest of what decides lint, for a lint-result cache key
   pipework codemod
   pipework codemod --dry-run
   pipework alerts unit-fault --unit subseam-core.service   # reads $SERVICE_RESULT, $EXIT_CODE, $EXIT_STATUS

package/src/data/db/pool.ts

@@ -43,9 +43,32 @@ export interface ManagedConnection {
    * without it, throws.
    */
   connectionIds(): Promise<ReadonlyArray<{ connectionId: number; backendPid: number }>>
+  /**
+   * Cancels the statement running on server backend `pid` (`pg_cancel_backend`),
+   * over a connection reserved for cancels (opened on first use, closed with
+   * this connection) so it never waits on the pool the statement runs in.
+   */
+  cancelBackend?(pid: number): Promise<void>
   close(options?: { timeoutSeconds?: number }): Promise<void>
 }
 
+/** A lazily opened single-connection client that only sends cancels. */
+function createCanceller(url: string): { cancel(pid: number): Promise<void>; close(): Promise<void> } {
+  let client: postgres.Sql | undefined
+  let closed = false
+  return {
+    async cancel(pid) {
+      if (closed) return
+      client ??= postgres(url, { max: 1, idle_timeout: 3, onnotice: () => {}, fetch_types: false })
+      await client`SELECT pg_cancel_backend(${pid})`
+    },
+    async close() {
+      closed = true
+      await client?.end({ timeout: 1 })
+    },
+  }
+}
+
 /** Options for `tap()` — pool size (default 1), idle timeout in seconds, and session settings (GUCs) sent in every connection's startup packet. */
 export interface ConnectOptions {
   readonly max?: number
@@ -121,13 +144,16 @@ export function tap(url: string, options?: ConnectOptions): ManagedConnection {
   })
 
   const db = splitLargeInserts(drizzle(client))
+  const canceller = createCanceller(url)
 
   return {
     name: 'manual',
     client,
     drizzle: db,
     connectionIds: () => probeConnectionIds(client, undefined),
+    cancelBackend: (pid) => canceller.cancel(pid),
     async close(options) {
+      await canceller.close()
       await client.end(endOptions(options))
     },
   }
@@ -165,6 +191,7 @@ export function createManagedConnection(
     ? createStatementWatch({ database: config.name, url: config.url, slowQueryMs: observability.slowQueryMs, inFlightQueryMs: observability.inFlightQueryMs })
     : undefined
   const db = splitLargeInserts(drizzle(client, statementWatch ? { statementWatch: statementWatch.watch } : {}))
+  const canceller = createCanceller(config.url)
 
   return {
     name: config.name,
@@ -174,8 +201,10 @@ export function createManagedConnection(
     },
     drizzle: db,
     connectionIds: () => probeConnectionIds(client, slot),
+    cancelBackend: (pid) => canceller.cancel(pid),
     async close(options) {
       onClose()
+      await canceller.close()
       await statementWatch?.close()
       await client.end(endOptions(options))
     },

package/src/request/context/run-in-transaction.ts

@@ -48,14 +48,14 @@ export async function executeInTransaction<T>(
 
       await propagateLocals(tx, ctx, tenant)
 
-      const disarm = await armCancellation(conn, tx, signal)
+      const cancellation = await armCancellation(conn, tx, signal)
       try {
         const result = await runInContext(childCtx, run)
         // Idle at the abort, nothing failed: throwing here rolls back instead of committing.
         signal?.throwIfAborted()
         return result
       } finally {
-        disarm()
+        await cancellation.settle()
       }
     })
   }
@@ -90,10 +90,15 @@ export async function executeInTransaction<T>(
       conn.drizzle.transaction(async (tx) => {
         childCtx.transactions.set(dbName, bindTransaction(ctx, dbName, tx, signal))
         await propagateLocals(tx, ctx, tenant)
-        disarms.push(await armCancellation(conn, tx, signal))
+        const cancellation = await armCancellation(conn, tx, signal)
+        disarms.push(cancellation.disarm)
         readyDatabases.add(dbName)
         signalReady()
-        await donePromise
+        try {
+          await donePromise
+        } finally {
+          await cancellation.settle()
+        }
       }),
     )
   }
@@ -142,34 +147,38 @@ export async function executeInTransaction<T>(
  * Arms server-side cancellation for one transaction: on abort, a separate
  * pooled connection issues `pg_cancel_backend` against the backend this
  * transaction holds, so an in-flight query fails with `query_canceled` and the
- * transaction unwinds. Returns a disarm function — always call it, or the
- * listener outlives the transaction and cancels a backend the pool has since
- * handed to someone else.
+ * transaction unwinds. Always call `settle()` before the transaction ends: it
+ * removes the listener and waits for a cancel already sent to be delivered, so
+ * none reaches a backend the pool has since handed to someone else. `disarm()`
+ * only removes the listener.
  */
 async function armCancellation(
   conn: ManagedConnection,
   tx: DB,
   signal: AbortSignal | undefined,
-): Promise<() => void> {
-  if (signal === undefined) return () => {}
+): Promise<{ disarm: () => void; settle: () => Promise<void> }> {
+  const none = { disarm: () => {}, settle: async () => {} }
+  if (signal === undefined) return none
 
   const [row] = await tx.execute(sql`SELECT pg_backend_pid() AS pid`)
   const pid = Number((row as { pid?: unknown } | undefined)?.pid)
-  if (!Number.isInteger(pid)) return () => {}
+  if (!Number.isInteger(pid)) return none
 
+  let pending: Promise<void> | undefined
   const cancel = (): void => {
     // Best effort: the backend may already have finished, and a failed cancel
     // must not replace the abort the caller is about to see.
-    void conn.drizzle.execute(sql`SELECT pg_cancel_backend(${pid})`).catch(() => {})
+    pending = (conn.cancelBackend?.(pid) ?? conn.drizzle.execute(sql`SELECT pg_cancel_backend(${pid})`)).then(() => {}, () => {})
   }
-
-  if (signal.aborted) {
-    cancel()
-    return () => {}
+  const disarm = (): void => { signal.removeEventListener('abort', cancel) }
+  const settle = async (): Promise<void> => {
+    disarm()
+    await pending
   }
 
-  signal.addEventListener('abort', cancel, { once: true })
-  return () => { signal.removeEventListener('abort', cancel) }
+  if (signal.aborted) cancel()
+  else signal.addEventListener('abort', cancel, { once: true })
+  return { disarm, settle }
 }
 
 /**

package/src/request/http/aborted.ts

@@ -13,3 +13,22 @@ export class RequestAbortedError extends PipeworkError {
     super(`[pipework] The client closed the connection before the response was sent (${method} ${route}).`, { method, route })
   }
 }
+
+/**
+ * Whether `error` is something the abort itself caused: anywhere in its `cause`
+ * chain, the signal's reason, a `RequestAbortedError`, an `AbortError`, or a
+ * Postgres `query_canceled` (57014) / `in_failed_sql_transaction` (25P02).
+ * Any other error after an abort is a real failure.
+ */
+export function isAbortCaused(error: unknown, signal: AbortSignal): boolean {
+  const seen = new Set<unknown>()
+  let current: unknown = error
+  while (current !== null && current !== undefined && !seen.has(current)) {
+    seen.add(current)
+    if (current === signal.reason || current instanceof RequestAbortedError) return true
+    const { name, code, cause } = current as { name?: unknown; code?: unknown; cause?: unknown }
+    if (name === 'AbortError' || code === '57014' || code === '25P02') return true
+    current = cause
+  }
+  return false
+}

package/src/request/http/namespace.ts

@@ -3,5 +3,5 @@ import { detectMediaType, resolveMediaType, SNIFF_BYTES } from './sniff.js'
 
 /** HTTP namespace: `http.file()` builds a file response; `http.detectMediaType()` names bytes the way uploads do; the server itself is managed by manifold.start().
  *
- * A client that disconnects before its response is finished aborts the request: the in-flight statement is cancelled, the transaction rolled back and the connection released. The context's `signal` (`flow.require().signal`) aborts with a `RequestAbortedError` (499, `REQUEST_ABORTED`); pass it to the handler's own outbound calls (`fetch(url, { signal })`, a `quota.call` send). The aborted request is not an internal error: `onInternalError` is not called and nothing is sent. A route opts out with `.route(method, path, { cancelOnDisconnect: false })`, e.g. a webhook receiver whose sender abandons slow deliveries and does not redeliver: its signal never aborts and the transaction commits after the socket closes. */
+ * A client that disconnects before its response is finished aborts the request: the in-flight statement is cancelled, the transaction rolled back and the connection released. The context's `signal` (`flow.require().signal`) aborts with a `RequestAbortedError` (499, `REQUEST_ABORTED`); pass it to the handler's own outbound calls (`fetch(url, { signal })`, a `quota.call` send). Nothing is sent, whether the handler then throws or completes (an injected call rejects with `AbortError`). What the abort caused (its reason, a cancelled statement) is not an internal error and `onInternalError` is not called; any other error thrown after the abort still reaches it. A route opts out with `.route(method, path, { cancelOnDisconnect: false })`, e.g. a webhook receiver whose sender abandons slow deliveries and does not redeliver: its signal never aborts and the transaction commits after the socket closes. */
 export const http = { file, detectMediaType, resolveMediaType, SNIFF_BYTES } as const