@cosmicdrift/kumiko-framework 0.1.0

package/src/lifecycle/__tests__/lifecycle-server.integration.ts

@@ -0,0 +1,108 @@
+// Full-stack proof for lifecycle ↔ buildServer wiring.
+// Drives drain() directly — SIGTERM plumbing has its own unit test.
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "vitest";
+import { defineFeature } from "../../engine";
+import { setupTestStack, type TestStack } from "../../stack";
+import { sharedWidgetEntity } from "../../testing";
+import { createLifecycle, type Lifecycle } from "../lifecycle";
+
+const widgetFeature = defineFeature("lifecycle-probe", (r) => {
+  r.entity("widget", sharedWidgetEntity);
+  // One MSP ensures buildServer actually constructs an eventDispatcher —
+  // without a consumer, dispatcher stays undefined and we wouldn't prove
+  // the shutdown-hook registration at all.
+  r.multiStreamProjection({
+    name: "observer",
+    apply: {
+      "widget.created": async () => {},
+    },
+  });
+});
+
+let stack: TestStack;
+let lifecycle: Lifecycle;
+let hookOrder: string[];
+
+beforeAll(async () => {
+  lifecycle = createLifecycle({ startReady: true });
+  hookOrder = [];
+
+  // Register BEFORE setupTestStack so buildServer's hook lands in the middle
+  // of registration order — our assertion below keys on that layout.
+  lifecycle.registerShutdownHook("probe-before-boot", async () => {
+    hookOrder.push("probe-before-boot");
+  });
+
+  stack = await setupTestStack({ features: [widgetFeature], lifecycle });
+
+  if (!stack.lifecycle) throw new Error("lifecycle not wired through setupTestStack");
+  if (!stack.eventDispatcher) throw new Error("eventDispatcher not built — MSP missing?");
+});
+
+afterEach(() => {
+  hookOrder.length = 0;
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+describe("lifecycle — /health/ready live state", () => {
+  test("returns 200 with state=ready before drain", async () => {
+    const res = await stack.app.request("/health/ready");
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      status: string;
+      state: string;
+      uptimeSec: number;
+      checks: { name: string; ok: boolean }[];
+    };
+    expect(body.status).toBe("ready");
+    expect(body.state).toBe("ready");
+    expect(body.uptimeSec).toBeGreaterThanOrEqual(0);
+    // Depth-check proof: db + redis were both probed, both green.
+    expect(body.checks.map((c) => c.name).sort()).toEqual(["db", "redis"]);
+    expect(body.checks.every((c) => c.ok)).toBe(true);
+  });
+
+  test("/health stays trivial regardless of lifecycle state", async () => {
+    const res = await stack.app.request("/health");
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ status: "ok" });
+  });
+});
+
+describe("lifecycle — drain wiring", () => {
+  test("buildServer registers eventDispatcher between caller hooks", () => {
+    // Order matters, not just existence: probe-before-boot was registered
+    // before setupTestStack, so buildServer's eventDispatcher hook must land
+    // AFTER it in registration order. probe-after-boot is registered in the
+    // next test, so it isn't in the list yet.
+    expect(lifecycle.hookNames()).toEqual(["probe-before-boot", "eventDispatcher"]);
+  });
+
+  test("drain() flips /health/ready to 503 and runs hooks LIFO", async () => {
+    // Second probe registered AFTER setupTestStack — landing last in
+    // registration order means LIFO drain runs it first.
+    lifecycle.registerShutdownHook("probe-after-boot", async () => {
+      hookOrder.push("probe-after-boot");
+    });
+
+    await lifecycle.drain({ timeoutMs: 2_000 });
+
+    expect(lifecycle.state()).toBe("stopped");
+
+    const res = await stack.app.request("/health/ready");
+    expect(res.status).toBe(503);
+    const body = (await res.json()) as { status: string; state: string };
+    expect(body.status).toBe("not_ready");
+    expect(body.state).toBe("stopped");
+
+    // LIFO proof: probe-after-boot ran first (last registered), then the
+    // dispatcher hook (registered by buildServer in the middle), then
+    // probe-before-boot (first registered). The dispatcher hook doesn't
+    // push into hookOrder, so we only see our two probes in inverse order.
+    expect(hookOrder).toEqual(["probe-after-boot", "probe-before-boot"]);
+  });
+});

package/src/lifecycle/__tests__/lifecycle.test.ts

@@ -0,0 +1,212 @@
+import { describe, expect, test, vi } from "vitest";
+import { createLifecycle } from "../lifecycle";
+
+describe("lifecycle — state machine", () => {
+  test("starts in 'starting' by default", () => {
+    const lc = createLifecycle();
+    expect(lc.state()).toBe("starting");
+  });
+
+  test("startReady option skips 'starting'", () => {
+    const lc = createLifecycle({ startReady: true });
+    expect(lc.state()).toBe("ready");
+  });
+
+  test("markReady transitions starting → ready", () => {
+    const lc = createLifecycle();
+    lc.markReady();
+    expect(lc.state()).toBe("ready");
+  });
+
+  test("markReady from 'ready' is a no-op", () => {
+    const lc = createLifecycle({ startReady: true });
+    const listener = vi.fn();
+    lc.onStateChange(listener);
+    lc.markReady();
+    expect(listener).not.toHaveBeenCalled();
+    expect(lc.state()).toBe("ready");
+  });
+
+  test("drain runs ready → draining → stopped once, second drain is a no-op", async () => {
+    const lc = createLifecycle({ startReady: true });
+    const transitions: string[] = [];
+    lc.onStateChange((_, to) => transitions.push(to));
+    await lc.drain({ timeoutMs: 100 });
+    expect(lc.state()).toBe("stopped");
+    expect(transitions).toEqual(["draining", "stopped"]);
+
+    // Second drain is a no-op — hooks must not run twice on double-SIGTERM.
+    await lc.drain({ timeoutMs: 100 });
+    expect(transitions).toEqual(["draining", "stopped"]);
+  });
+
+  test("markReady after drain is a no-op (state=stopped sticks)", async () => {
+    const lc = createLifecycle();
+    lc.markReady();
+    await lc.drain({ timeoutMs: 50 });
+    expect(lc.state()).toBe("stopped");
+
+    // Late markReady must not resurrect the lifecycle.
+    lc.markReady();
+    expect(lc.state()).toBe("stopped");
+  });
+});
+
+describe("lifecycle — shutdown hooks", () => {
+  test("hooks run in LIFO order", async () => {
+    const lc = createLifecycle({ startReady: true });
+    const calls: string[] = [];
+    lc.registerShutdownHook("first", async () => {
+      calls.push("first");
+    });
+    lc.registerShutdownHook("second", async () => {
+      calls.push("second");
+    });
+    lc.registerShutdownHook("third", async () => {
+      calls.push("third");
+    });
+    await lc.drain({ timeoutMs: 100 });
+    expect(calls).toEqual(["third", "second", "first"]);
+  });
+
+  test("one failing hook does not block the others, and the error is logged", async () => {
+    const logger = { error: vi.fn() };
+    const lc = createLifecycle({ startReady: true, logger });
+    const calls: string[] = [];
+    lc.registerShutdownHook("healthy-a", async () => {
+      calls.push("healthy-a");
+    });
+    lc.registerShutdownHook("broken", async () => {
+      throw new Error("boom");
+    });
+    lc.registerShutdownHook("healthy-b", async () => {
+      calls.push("healthy-b");
+    });
+    await expect(lc.drain({ timeoutMs: 100 })).resolves.toBeUndefined();
+    expect(calls).toEqual(["healthy-b", "healthy-a"]);
+    expect(lc.state()).toBe("stopped");
+
+    // Logging makes the failure visible to prod-ops. Silent swallow hid bugs.
+    expect(logger.error).toHaveBeenCalledTimes(1);
+    const [msg, ctx] = logger.error.mock.calls[0] as [string, { err: unknown }];
+    expect(msg).toMatch(/shutdown hook "broken" threw/);
+    expect((ctx.err as Error).message).toBe("boom");
+  });
+
+  test("registering after draining throws", async () => {
+    const lc = createLifecycle({ startReady: true });
+    await lc.drain({ timeoutMs: 50 });
+    expect(() => lc.registerShutdownHook("too-late", async () => {})).toThrow(/already stopped/);
+  });
+
+  test("hook receives the signal name that triggered drain", async () => {
+    const lc = createLifecycle({ startReady: true });
+    const seen: string[] = [];
+    lc.registerShutdownHook("spy", async (signal) => {
+      seen.push(signal);
+    });
+    await lc.drain({ signal: "SIGTERM", timeoutMs: 50 });
+    expect(seen).toEqual(["SIGTERM"]);
+  });
+
+  test("hookNames() reflects registration order", () => {
+    const lc = createLifecycle({ startReady: true });
+    expect(lc.hookNames()).toEqual([]);
+    lc.registerShutdownHook("a", async () => {});
+    lc.registerShutdownHook("b", async () => {});
+    expect(lc.hookNames()).toEqual(["a", "b"]);
+  });
+
+  test("hookNames() stays populated after drain (post-mortem ops use-case)", async () => {
+    // Contract: the name list is not cleared on drain. An operator inspecting
+    // a stopped process should still be able to see which hooks were wired.
+    const lc = createLifecycle({ startReady: true });
+    lc.registerShutdownHook("a", async () => {});
+    lc.registerShutdownHook("b", async () => {});
+    await lc.drain({ timeoutMs: 50 });
+    expect(lc.state()).toBe("stopped");
+    expect(lc.hookNames()).toEqual(["a", "b"]);
+  });
+});
+
+describe("lifecycle — drain timeout", () => {
+  test("timeout forces state to 'stopped' even if hook hangs", async () => {
+    const lc = createLifecycle({ startReady: true });
+    // Hook that never resolves — drain must force-stop via its timer.
+    lc.registerShutdownHook("hangs-forever", () => new Promise<void>(() => {}));
+
+    await lc.drain({ timeoutMs: 20 });
+    expect(lc.state()).toBe("stopped");
+  });
+
+  test("concurrent drain calls share the in-flight promise", async () => {
+    const lc = createLifecycle({ startReady: true });
+    let runs = 0;
+    lc.registerShutdownHook("count", async () => {
+      runs++;
+    });
+    const [a, b, c] = await Promise.all([
+      lc.drain({ timeoutMs: 100 }),
+      lc.drain({ timeoutMs: 100 }),
+      lc.drain({ timeoutMs: 100 }),
+    ]);
+    expect(runs).toBe(1);
+    expect([a, b, c]).toEqual([undefined, undefined, undefined]);
+  });
+});
+
+describe("lifecycle — onStateChange", () => {
+  test("subscribers receive from/to pairs", async () => {
+    const lc = createLifecycle();
+    const events: Array<[string, string]> = [];
+    lc.onStateChange((from, to) => events.push([from, to]));
+    lc.markReady();
+    await lc.drain({ timeoutMs: 50 });
+    expect(events).toEqual([
+      ["starting", "ready"],
+      ["ready", "draining"],
+      ["draining", "stopped"],
+    ]);
+  });
+
+  test("unsubscribe stops further callbacks", () => {
+    const lc = createLifecycle();
+    const cb = vi.fn();
+    const unsubscribe = lc.onStateChange(cb);
+    lc.markReady();
+    expect(cb).toHaveBeenCalledTimes(1);
+    unsubscribe();
+    // No more state changes expected to reach cb.
+    cb.mockClear();
+    // Trigger another transition — should not call cb.
+    void lc.drain({ timeoutMs: 50 });
+    expect(cb).not.toHaveBeenCalled();
+  });
+
+  test("broken listener does not break others, and the error is logged", () => {
+    const logger = { error: vi.fn() };
+    const lc = createLifecycle({ logger });
+    const healthy = vi.fn();
+    lc.onStateChange(() => {
+      throw new Error("subscriber exploded");
+    });
+    lc.onStateChange(healthy);
+    lc.markReady();
+    expect(lc.state()).toBe("ready");
+    expect(healthy).toHaveBeenCalledTimes(1);
+
+    expect(logger.error).toHaveBeenCalledTimes(1);
+    const [msg] = logger.error.mock.calls[0] as [string, unknown];
+    expect(msg).toMatch(/onStateChange listener threw during starting→ready/);
+  });
+});
+
+describe("lifecycle — uptimeSec", () => {
+  test("counts seconds since construction using injected clock", () => {
+    let t = 1_000_000;
+    const lc = createLifecycle({ now: () => t });
+    expect(lc.uptimeSec()).toBe(0);
+    t += 3_500;
+    expect(lc.uptimeSec()).toBe(3);
+  });
+});

package/src/lifecycle/__tests__/signal-handlers.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, test, vi } from "vitest";
+import { createLifecycle } from "../lifecycle";
+import { attachSignalHandlers } from "../signal-handlers";
+import { createTestLifecycle } from "./create-test-lifecycle";
+
+describe("attachSignalHandlers", () => {
+  test("SIGTERM triggers drain and calls exit(0)", async () => {
+    const lc = createLifecycle({ startReady: true });
+    const exit = vi.fn();
+    const hookCalls: string[] = [];
+    lc.registerShutdownHook("spy", async (signal) => {
+      hookCalls.push(signal);
+    });
+
+    const handle = attachSignalHandlers(lc, { exit, timeoutMs: 50 });
+    try {
+      process.emit("SIGTERM");
+      await waitFor(() => lc.state() === "stopped");
+      expect(hookCalls).toEqual(["SIGTERM"]);
+      expect(exit).toHaveBeenCalledWith(0);
+    } finally {
+      handle.detach();
+    }
+  });
+
+  test("SIGINT path drains with the right signal label", async () => {
+    const lc = createLifecycle({ startReady: true });
+    const exit = vi.fn();
+    const seen: string[] = [];
+    lc.registerShutdownHook("spy", async (signal) => {
+      seen.push(signal);
+    });
+
+    const handle = attachSignalHandlers(lc, { exit, timeoutMs: 50, signals: ["SIGINT"] });
+    try {
+      process.emit("SIGINT");
+      await waitFor(() => lc.state() === "stopped");
+      expect(seen).toEqual(["SIGINT"]);
+      expect(exit).toHaveBeenCalledWith(0);
+    } finally {
+      handle.detach();
+    }
+  });
+
+  test("multiple SIGTERMs still call exit exactly once", async () => {
+    const lc = createLifecycle({ startReady: true });
+    const exit = vi.fn();
+    // Slow hook so we can fire additional signals while drain is in-flight.
+    lc.registerShutdownHook("slow", async () => {
+      await new Promise((r) => setTimeout(r, 30));
+    });
+
+    const handle = attachSignalHandlers(lc, { exit, timeoutMs: 500 });
+    try {
+      process.emit("SIGTERM");
+      process.emit("SIGTERM");
+      process.emit("SIGTERM");
+      await waitFor(() => lc.state() === "stopped");
+      // Without the exitScheduled guard this would be 3 — the `.then` chains
+      // would each fire exit(0) independently.
+      expect(exit).toHaveBeenCalledTimes(1);
+      expect(exit).toHaveBeenCalledWith(0);
+    } finally {
+      handle.detach();
+    }
+  });
+
+  test("exit(1) is called when drain rejects", async () => {
+    // Our real lifecycle swallows hook errors internally so drain() always
+    // resolves. Mock a drain that rejects to cover the .catch branch —
+    // defensive code still needs a test or it rots.
+    const brokenLifecycle = createTestLifecycle({
+      drain: async () => {
+        throw new Error("drain itself exploded");
+      },
+    });
+    const exit = vi.fn();
+    const handle = attachSignalHandlers(brokenLifecycle, { exit, signals: ["SIGTERM"] });
+    try {
+      process.emit("SIGTERM");
+      await waitFor(() => exit.mock.calls.length > 0);
+      expect(exit).toHaveBeenCalledWith(1);
+    } finally {
+      handle.detach();
+    }
+  });
+
+  test("detach() removes the process listeners", () => {
+    const lc = createLifecycle({ startReady: true });
+    const exit = vi.fn();
+    const before = process.listenerCount("SIGTERM");
+    const handle = attachSignalHandlers(lc, { exit, signals: ["SIGTERM"] });
+    expect(process.listenerCount("SIGTERM")).toBe(before + 1);
+    handle.detach();
+    expect(process.listenerCount("SIGTERM")).toBe(before);
+  });
+});
+
+async function waitFor(predicate: () => boolean, timeoutMs = 500): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (predicate()) return;
+    await new Promise((r) => setTimeout(r, 5));
+  }
+  throw new Error("waitFor timed out");
+}

package/src/lifecycle/index.ts

@@ -0,0 +1,13 @@
+export {
+  createLifecycle,
+  type Lifecycle,
+  type LifecycleOptions,
+  type LifecycleState,
+  type ShutdownHookFn,
+  type StateChangeListener,
+} from "./lifecycle";
+export {
+  type AttachSignalHandlersOptions,
+  attachSignalHandlers,
+  type SignalHandlerHandle,
+} from "./signal-handlers";

package/src/lifecycle/lifecycle.ts

@@ -0,0 +1,160 @@
+// Process lifecycle: 4-state machine + LIFO shutdown hooks.
+// Signal wiring lives in signal-handlers.ts; v1 scope in architecture/lifecycle.md.
+
+import type { Logger } from "../logging/types";
+
+export type LifecycleState = "starting" | "ready" | "draining" | "stopped";
+
+export type StateChangeListener = (from: LifecycleState, to: LifecycleState) => void;
+
+export type ShutdownHookFn = (signal: string) => Promise<void>;
+
+export interface Lifecycle {
+  state(): LifecycleState;
+  uptimeSec(): number;
+  markReady(): void;
+  onStateChange(cb: StateChangeListener): () => void;
+  registerShutdownHook(name: string, fn: ShutdownHookFn): void;
+  // Introspection: which hooks are registered, in registration order (drain
+  // runs them reversed). Used by ops + integration tests to verify that
+  // auto-wired hooks (e.g. eventDispatcher.stop) actually landed.
+  hookNames(): readonly string[];
+  drain(opts?: { signal?: string; timeoutMs?: number }): Promise<void>;
+}
+
+export type LifecycleOptions = {
+  // Start directly in "ready" state. Useful for tests that don't want to
+  // orchestrate a full startup sequence.
+  readonly startReady?: boolean;
+  /** @internal Test-only clock injection for deterministic uptimeSec assertions. */
+  readonly now?: () => number;
+  // Structured logger for hook / listener failures. Falls back to
+  // console.error when absent — matches the pattern in pipeline/lifecycle-pipeline.ts
+  // so one-file scripts and test setups don't need to wire a logger.
+  readonly logger?: Pick<Logger, "error">;
+};
+
+const DEFAULT_DRAIN_TIMEOUT_MS = 40_000;
+
+export function createLifecycle(opts: LifecycleOptions = {}): Lifecycle {
+  const now = opts.now ?? (() => Date.now());
+  const startedAt = now();
+  const logError = makeErrorLogger(opts.logger);
+
+  let current: LifecycleState = opts.startReady ? "ready" : "starting";
+  const listeners = new Set<StateChangeListener>();
+  const hooks: Array<{ name: string; fn: ShutdownHookFn }> = [];
+  let drainPromise: Promise<void> | null = null;
+
+  function transition(to: LifecycleState): void {
+    const from = current;
+    // skip: no real state change (e.g. markReady() on an already-ready
+    // lifecycle). Listeners only fire on actual transitions.
+    if (from === to) return;
+    current = to;
+    for (const cb of listeners) {
+      try {
+        cb(from, to);
+      } catch (err) {
+        // A broken listener must not tear the state machine down, but swallowing
+        // silently hides bugs from ops. Log and move on.
+        logError(`onStateChange listener threw during ${from}→${to}`, err);
+      }
+    }
+  }
+
+  async function drainOnce(signal: string, timeoutMs: number): Promise<void> {
+    transition("draining");
+
+    const runAllHooks = async (): Promise<void> => {
+      // LIFO: the last thing registered is the first thing stopped. Matches
+      // the "things registered later depend on things registered earlier"
+      // convention — tear them down in reverse dependency order.
+      for (let i = hooks.length - 1; i >= 0; i--) {
+        const hook = hooks[i];
+        if (!hook) continue;
+        try {
+          await hook.fn(signal);
+        } catch (err) {
+          // Isolated failure: one broken hook must not block the others. Log
+          // so ops can see which hook failed during shutdown — silent swallow
+          // made prod incidents invisible.
+          logError(`shutdown hook "${hook.name}" threw`, err);
+        }
+      }
+    };
+
+    let forceTimer: ReturnType<typeof setTimeout> | undefined;
+    const forcePromise = new Promise<void>((resolve) => {
+      forceTimer = setTimeout(resolve, timeoutMs);
+    });
+
+    try {
+      await Promise.race([runAllHooks(), forcePromise]);
+    } finally {
+      if (forceTimer) clearTimeout(forceTimer);
+      transition("stopped");
+    }
+  }
+
+  return {
+    state: () => current,
+
+    uptimeSec: () => Math.floor((now() - startedAt) / 1000),
+
+    markReady: () => {
+      // skip: already past the "starting" phase. markReady is idempotent
+      // so boot orchestrators can call it defensively without branching.
+      if (current !== "starting") return;
+      transition("ready");
+    },
+
+    onStateChange: (cb) => {
+      listeners.add(cb);
+      return () => {
+        listeners.delete(cb);
+      };
+    },
+
+    registerShutdownHook: (name, fn) => {
+      // Accepting hooks after `draining` has started would silently drop them
+      // — better to reject so mis-wired late registrations surface.
+      if (current === "draining" || current === "stopped") {
+        throw new Error(
+          `Cannot register shutdown hook "${name}" — lifecycle is already ${current}`,
+        );
+      }
+      hooks.push({ name, fn });
+    },
+
+    hookNames: () => hooks.map((h) => h.name),
+
+    drain: async (drainOpts = {}) => {
+      const signal = drainOpts.signal ?? "manual";
+      const timeoutMs = drainOpts.timeoutMs ?? DEFAULT_DRAIN_TIMEOUT_MS;
+
+      // Re-entrant drain: concurrent calls share the in-flight promise.
+      // Post-stop calls are a no-op so double-SIGTERM doesn't double-run hooks.
+      if (drainPromise) return drainPromise;
+      // skip: already fully stopped (e.g. SIGTERM arrives after drain finished).
+      // Returning without action keeps the post-drain state pristine.
+      if (current === "stopped") return;
+
+      drainPromise = drainOnce(signal, timeoutMs);
+      return drainPromise;
+    },
+  };
+}
+
+// Builds a single error-log closure once per lifecycle instance. Structured
+// logger wins when present; otherwise plain stderr via console.error so we
+// never eat a failure silently.
+function makeErrorLogger(
+  logger: Pick<Logger, "error"> | undefined,
+): (msg: string, err: unknown) => void {
+  if (logger) {
+    return (msg, err) => logger.error(`[lifecycle] ${msg}`, { err });
+  }
+  // biome-ignore lint/suspicious/noConsole: ops-visible fallback when no logger is wired
+  return (msg, err) => console.error(`[lifecycle] ${msg}:`, err);
+}

package/src/lifecycle/signal-handlers.ts

@@ -0,0 +1,62 @@
+// Opt-in signal handlers. Kept separate from createLifecycle() so test
+// processes don't accidentally hijack SIGTERM/SIGINT — production `main.ts`
+// calls this explicitly, tests drive drain() directly.
+
+import type { Lifecycle } from "./lifecycle";
+
+export type AttachSignalHandlersOptions = {
+  readonly timeoutMs?: number;
+  // Which signals to listen for. Default covers orchestrator (K8s, systemd)
+  // SIGTERM and interactive Ctrl-C (SIGINT).
+  readonly signals?: readonly NodeJS.Signals[];
+  // Called after drain completes, default: process.exit(0). Inject a stub in
+  // tests to assert exit was requested without terminating the test runner.
+  readonly exit?: (code: number) => void;
+};
+
+export type SignalHandlerHandle = {
+  // Remove the listeners added by attach(). Useful for tests and for hot-
+  // swapping the lifecycle in a long-running process.
+  detach(): void;
+};
+
+export function attachSignalHandlers(
+  lifecycle: Lifecycle,
+  opts: AttachSignalHandlersOptions = {},
+): SignalHandlerHandle {
+  const signals: readonly NodeJS.Signals[] = opts.signals ?? ["SIGTERM", "SIGINT"];
+  const exitFn = opts.exit ?? ((code) => process.exit(code));
+
+  const listeners = new Map<NodeJS.Signals, () => void>();
+  // Guard so double-SIGTERM doesn't call exitFn twice. drain() is already
+  // idempotent via its shared promise, but its .then/.catch chain would fire
+  // per signal otherwise.
+  let exitScheduled = false;
+
+  for (const sig of signals) {
+    const handler = () => {
+      // skip: exit already scheduled by a prior signal — drain() is in flight
+      // and will fire exitFn itself when it settles. Second signal is a no-op.
+      if (exitScheduled) return;
+      exitScheduled = true;
+      void lifecycle
+        .drain({
+          signal: sig,
+          ...(opts.timeoutMs !== undefined && { timeoutMs: opts.timeoutMs }),
+        })
+        .then(() => exitFn(0))
+        .catch(() => exitFn(1));
+    };
+    process.on(sig, handler);
+    listeners.set(sig, handler);
+  }
+
+  return {
+    detach: () => {
+      for (const [sig, handler] of listeners) {
+        process.off(sig, handler);
+      }
+      listeners.clear();
+    },
+  };
+}