[mo4islona]

Signal-managed graceful shutdown for pipeTo

Closes #210.

Summary

• pipeTo intercepts SIGTERM and SIGINT by default for every target (ADR-24): it cancels only the source side, so an in-flight commit or fork rollback runs on; the batch in flight is committed, the cursor is saved, resources close, and the promise rejects with PipelineStoppedError (E3001) — a stop must not look like a finished range
• shutdown: fn | { timeout, onShutdown } | false — a cleanup callback, a '30s'-style budget (E3002 PipelineShutdownTimeoutError on expiry) and an explicit opt-out; invalid settings reject with ShutdownConfigurationError (E0005) before the pipe starts
• Portal reads, streams and retry pauses end on the stop signal, including calls made through the cache and transformer hooks; the shared listener pair exists only while a managed run does, and the library never ends the process
• Targets stop through their normal flush-and-close path: BigQuery closes its streams but leaves a caller's writer open, the Pub/Sub publisher no longer closes a client it does not own, ClickHouse drops its extra store.close()
• Docs: docs/graceful-shutdown.md, ADR-24, specs 04/05/08/09/13/14/15, error registry (92 thrown = documented = registered)

Coverage

Full-suite v8 coverage on the remote box, base (origin/main) vs head:

Module	Stmts	Δ	Branch	Δ
All files	93.1%	+0.5	90.3%	+0.4
src/core	94.0%	+2.5	94.6%	-0.0
src/http-client	74.1%	+3.9	78.3%	+2.9
src/internal	95.9%	+0.8	88.6%	+3.0
src/portal-client	98.6%	+0.0	93.8%	+0.7
src/targets/bigquery	93.4%	+0.0	91.3%	+0.3
src/targets/clickhouse	95.5%	-0.3	92.7%	+0.4
src/targets/parquet	96.2%	+0.0	91.6%	+0.1
src/targets/pubsub	97.5%	+0.0	90.3%	+0.2

125 new tests (1543 → 1668).

Test plan

• Full suite with services (Postgres, ClickHouse) on the remote box: 1668 passed, 37 skipped, 0 failed — including the previously flaky listener-count assertion (a legacy test dropped a managed pipeTo promise, which kept the shared pair registered past the test; it now awaits the run, and the opt-out assertion reads the count in a synchronous window around the call)
• New unit suites: shutdown option parsing and drain/timeout behavior, portal-source shutdown integration (stop during startup, mid-drain, on shutdown callback ordering), HTTP and portal client abort semantics, target ownership (BigQuery streams, Pub/Sub client, ClickHouse, Parquet)
• New conformance suites with real child processes: conformance/shutdown/signals.test.ts (both signals, budgets, double signal), conformance/pubsub/backfill-stop.test.ts (SIGTERM mid-backfill leaves a resumable cursor)
• node spec/check-spec.mjs — error registry in sync
• Biome, typecheck, build

🤖 Generated with Claude Code