stitchkit 0.82.0 → 0.83.1

package/CHANGELOG.md

@@ -15,6 +15,86 @@ additive**; the first breaking change landed in 0.10.0. Grep the file for
 
 ## [Unreleased]
 
+## [0.83.1] — 2026-09-07
+
+### Fixed
+
+- **The drain bound could not fire when it was the only thing left to fire.**
+  0.83.0 unref'd the bound's timer, which reads like hygiene — a drain bound
+  should not keep a process alive while it is shutting down — and silently
+  destroyed the feature. A pending write holds nothing, so when the stuck write
+  is the last work in the process, an unref'd timer lets the event loop empty
+  and `close({ timeoutMs })` never settles at all. That is not an edge case, it
+  is the case the bound exists for; under Node the process exits 13 on the
+  unsettled await. The timer cannot outlive the deadline the caller asked for,
+  so it is ref'd again.
+
+  Every in-process test passed against the broken build, because a test runner
+  keeps the loop alive by itself. The consumer lane now runs the real failure
+  from the packed tarball under each runtime (`node: drain bound`), which is the
+  only place it was ever visible.
+
+## [0.83.0] — 2026-09-07
+
+### ⚠️ Breaking changes
+
+**Who must act:** anyone who builds an `ObservabilityDrainReport` by hand (a
+test double, a persisted report re-parsed through
+`ObservabilityDrainReportSchema`), and anyone who types an observability
+`flush()` as `Promise<void>`.
+
+- **`ObservabilityDrainReport` gained a required `drained` field.** Returned by
+  the framework, so reading code is unaffected; a hand-built object stops
+  compiling, and `ObservabilityDrainReportSchema.parse` rejects a stored report
+  written by an older version until it carries the field.
+  `// before: { request, tools, total, durationMs }` →
+  `// after: { request, tools, total, durationMs, drained }`
+
+- **Every observability `flush()` returns `Promise<boolean>` instead of
+  `Promise<void>`** — `true` when the generation admitted before the call
+  settled inside the bound. This is not only the audit sink: it redefines
+  `stitchkit/application` (`createApplicationEventSink`, and
+  `ApplicationSnapshot` delivery through `createApplicationSnapshotSink`, whose
+  `close` gained the same bound) and `stitchkit/agent-runtime`
+  (`createAgentRuntimeEventSink`, `createAgentObservability`). `await
+  sink.flush()` is unchanged; a declared `Promise<void>` is not. The outcome
+  could not be left to `getStatus()`: flush waits on a generation, the status
+  counts everything alive right now, so a complete flush and an expired one are
+  indistinguishable there.
+  `// before: const f: () => Promise<void> = sink.flush` →
+  `// after: const f: () => Promise<boolean> = sink.flush`
+
+### Added
+
+- **Every observability drain takes a bound.** `flush(bound?)` and
+  `close(bound?)` accept `{ timeoutMs?, signal? }` on `createObservability`,
+  `createApplicationEventSink`, `createApplicationSnapshotSink`,
+  `createAgentRuntimeEventSink` and `createAgentObservability`. Unbounded, a
+  drain waits for every accepted event however long the sink takes: one write
+  that never settled held `close()` forever, and an application whose shutdown
+  graph gives every other step a deadline spent its entire budget here and
+  exited by force — measured by a consumer as five forced shutdowns in a week,
+  each burning 110 seconds with every application operation already completed
+  and the transport closed in 26 ms. A drain that cannot be bounded cannot take
+  part in a shutdown budget: it either fits, or it cancels the budget. New
+  export `ObservabilityDrainBound`.
+
+- **`ObservabilityDrainReport.drained`** says whether every accepted event
+  settled. It is read from the counters rather than from which side of the race
+  won, so a bound that expires on a sink that has in fact finished — a shutdown
+  signal already aborted by an earlier step — reports `true` rather than a false
+  audit-loss alarm.
+
+### Fixed
+
+- **Sink counters were readable mid-update.** `completed` was incremented one
+  microtask before the write left `pending`, and an id left `preparing` two
+  microtasks after `admit` had already put it in `writes` — so a status read
+  landing in either gap counted one event twice, or reported `accepted` below
+  `completed + pending`. Harmless while nothing read the counters at speed; a
+  caller-supplied abort signal fires synchronously and lands a bounded drain's
+  report exactly there. Each counter now moves in the same tick as its map.
+
 ## [0.82.0] — 2026-09-06
 
 ### ⚠️ Breaking changes

package/dist/agent-runtime/events.d.ts

@@ -1,3 +1,4 @@
+import { type ObservabilityDrainBound } from '../internal/observability-sink.js';
 import type { ObservabilitySinkStatus } from '../observability/status.js';
 import { type AgentRuntimeEvent, type AgentRuntimePublisher } from './event-schema.js';
 export * from './event-schema.js';
@@ -17,9 +18,15 @@ export interface AgentRuntimeEventSinkConfig {
 }
 export interface AgentRuntimeEventSink {
     publish: AgentRuntimePublisher;
-    flush(): Promise<void>;
+    /** Whether the generation admitted before this call settled inside the bound. */
+    flush(bound?: ObservabilityDrainBound): Promise<boolean>;
     getStatus(): ObservabilitySinkStatus;
-    close(): Promise<ObservabilitySinkStatus>;
+    /**
+     * Stop admission and drain. Bounded the same way as every other drain here:
+     * without a bound it waits however long the sink takes, which is what used to
+     * consume an entire application shutdown budget when a write never settled.
+     */
+    close(bound?: ObservabilityDrainBound): Promise<ObservabilitySinkStatus>;
 }
 /** Bounded, failure-isolated transport-neutral delivery lifecycle. */
 export declare function createAgentRuntimeEventSink(config: AgentRuntimeEventSinkConfig): AgentRuntimeEventSink;

package/dist/agent-runtime/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/events.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EACL,KAAK,iBAAiB,EAEtB,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AAExB,cAAc,gBAAgB,CAAC;AAE/B,MAAM,WAAW,2BAA2B;IAC1C,KAAK,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,OAAO,CAAC,CAAC,KAAK,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,SAAS,CAAC;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,iBAAiB,CAAA;KAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzF,MAAM,CAAC,CAAC,KAAK,EAAE;QACb,MAAM,EAAE,UAAU,GAAG,QAAQ,CAAC;QAC9B,KAAK,EAAE,iBAAiB,CAAC;QACzB,OAAO,EAAE,MAAM,CAAC;KACjB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,qBAAqB,CAAC;IAC/B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,SAAS,IAAI,uBAAuB,CAAC;IACrC,KAAK,IAAI,OAAO,CAAC,uBAAuB,CAAC,CAAC;CAC3C;AAED,sEAAsE;AACtE,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,2BAA2B,GAClC,qBAAqB,CAiBvB"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EACL,KAAK,iBAAiB,EAEtB,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AAExB,cAAc,gBAAgB,CAAC;AAE/B,MAAM,WAAW,2BAA2B;IAC1C,KAAK,CAAC,KAAK,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,OAAO,CAAC,CAAC,KAAK,EAAE,iBAAiB,GAAG,iBAAiB,GAAG,SAAS,CAAC;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,CAAC,KAAK,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,iBAAiB,CAAA;KAAE,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzF,MAAM,CAAC,CAAC,KAAK,EAAE;QACb,MAAM,EAAE,UAAU,GAAG,QAAQ,CAAC;QAC9B,KAAK,EAAE,iBAAiB,CAAC;QACzB,OAAO,EAAE,MAAM,CAAC;KACjB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,qBAAqB,CAAC;IAC/B,iFAAiF;IACjF,KAAK,CAAC,KAAK,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,SAAS,IAAI,uBAAuB,CAAC;IACrC;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;CAC1E;AAED,sEAAsE;AACtE,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,2BAA2B,GAClC,qBAAqB,CAiBvB"}

package/dist/agent-runtime/observability.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { type ObservabilityDrainBound } from '../internal/observability-sink.js';
 import type { ObservabilitySinkStatus } from '../observability/status.js';
 export declare const AgentRunStartedEventSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
@@ -448,9 +449,15 @@ export interface AgentObservability {
         parentSpanId?: string;
     };
     emit(event: AgentRunEvent): void;
-    flush(): Promise<void>;
+    /** Whether the generation admitted before this call settled inside the bound. */
+    flush(bound?: ObservabilityDrainBound): Promise<boolean>;
     getStatus(): ObservabilitySinkStatus;
-    close(): Promise<ObservabilitySinkStatus>;
+    /**
+     * Stop admission and drain. Bounded the same way as every other drain here:
+     * without a bound it waits however long the sink takes, which is what used to
+     * consume an entire application shutdown budget when a write never settled.
+     */
+    close(bound?: ObservabilityDrainBound): Promise<ObservabilitySinkStatus>;
 }
 export declare function createAgentObservability(config: AgentRunSinkConfig): AgentObservability;
 //# sourceMappingURL=observability.d.ts.map

package/dist/agent-runtime/observability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/observability.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AA2BvE,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;;;;;iBAIrC,CAAC;AAEH,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAMvC,CAAC;AAEH,eAAO,MAAM,2BAA2B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAgBtC,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;2BAI9B,CAAC;AAEH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAC9E,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAClF,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAChF,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC;AAEhE,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,UAAU,GAAG,QAAQ,CAAC;IAC9B,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClD,MAAM,CAAC,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,WAAW,CAAC,CAAC,OAAO,EAAE,iBAAiB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,MAAM,CAAC,CAAC,IAAI,EAAE,gBAAgB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,kBAAkB;IACjC,SAAS,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG;QACvD,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;IACF,IAAI,CAAC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAC;IACjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,SAAS,IAAI,uBAAuB,CAAC;IACrC,KAAK,IAAI,OAAO,CAAC,uBAAuB,CAAC,CAAC;CAC3C;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,kBAAkB,GAAG,kBAAkB,CAkDvF"}
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../../src/agent-runtime/observability.ts"],"names":[],"mappings":"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"}

package/dist/agent-runtime-harness.js

@@ -2,12 +2,12 @@ import {
   composeAgentPrompt,
   createAgentRuntime,
   createAgentRuntimeEventSink
-} from "./index-1dd82z59.js";
+} from "./index-st8v8739.js";
 import {
   AgentModelDescriptorSchema
 } from "./index-tg3m2ec5.js";
 import"./index-y2s6h5bf.js";
-import"./index-a59da114.js";
+import"./index-wnfk50r0.js";
 import {
   walkContainedFiles
 } from "./index-rqpdar1e.js";

package/dist/agent-runtime.js

@@ -48,7 +48,7 @@ import {
   registerDeferredToolRepair,
   repairedSearchCall,
   selectAgentHistory
-} from "./index-1dd82z59.js";
+} from "./index-st8v8739.js";
 import {
   AgentModelCapabilitySchema,
   AgentModelCatalogEntrySchema,
@@ -72,7 +72,7 @@ import {
 } from "./index-y2s6h5bf.js";
 import {
   createBoundedSinkManager
-} from "./index-a59da114.js";
+} from "./index-wnfk50r0.js";
 import {
   AgentAdmissionEventSchema,
   AgentCheckpointEventSchema,
@@ -688,9 +688,9 @@ function createAgentObservability(config) {
         return AgentRunTerminalEventSchema.omit({ internalCause: true }).parse(parsed);
       });
     },
-    flush: () => manager.flush(),
+    flush: (bound) => manager.flush(bound),
     getStatus: () => manager.getStatus(),
-    close: () => manager.close()
+    close: (bound) => manager.close(bound)
   };
 }
 // src/agent-runtime/protocol.ts

package/dist/application/events.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { type ObservabilityDrainBound } from '../internal/observability-sink.js';
 import type { ObservabilitySinkStatus } from '../observability/status.js';
 import { type ApplicationSnapshot } from './schemas.js';
 export declare const ApplicationLifecycleEventSchema: z.ZodReadonly<z.ZodObject<{
@@ -56,9 +57,15 @@ export interface ApplicationEventSinkConfig {
 }
 export interface ApplicationEventSink {
     publish(snapshot: ApplicationSnapshot): void;
-    flush(): Promise<void>;
+    /** Whether the generation admitted before this call settled inside the bound. */
+    flush(bound?: ObservabilityDrainBound): Promise<boolean>;
     getStatus(): ObservabilitySinkStatus;
-    close(): Promise<ObservabilitySinkStatus>;
+    /**
+     * Stop admission and drain. Bounded the same way as every other drain here:
+     * without a bound it waits however long the sink takes, which is what used to
+     * consume an entire application shutdown budget when a write never settled.
+     */
+    close(bound?: ObservabilityDrainBound): Promise<ObservabilitySinkStatus>;
 }
 /** Failure-isolated operator event delivery; canonical truth remains the absolute snapshot. */
 export declare function createApplicationEventSink(config: ApplicationEventSinkConfig): ApplicationEventSink;

package/dist/application/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/application/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EAIL,KAAK,mBAAmB,EAEzB,MAAM,WAAW,CAAC;AAEnB,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBAa/B,CAAC;AACd,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,mBAAmB,GAC5B,yBAAyB,CAY3B;AAED,MAAM,WAAW,0BAA0B;IACzC,KAAK,CAAC,KAAK,EAAE,yBAAyB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,CAAC,OAAO,EAAE;QACpB,KAAK,EAAE,OAAO,CAAC;QACf,KAAK,CAAC,EAAE,yBAAyB,CAAC;KACnC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC7C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,SAAS,IAAI,uBAAuB,CAAC;IACrC,KAAK,IAAI,OAAO,CAAC,uBAAuB,CAAC,CAAC;CAC3C;AAED,+FAA+F;AAC/F,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,0BAA0B,GACjC,oBAAoB,CActB"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/application/events.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAEL,KAAK,uBAAuB,EAC7B,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EAIL,KAAK,mBAAmB,EAEzB,MAAM,WAAW,CAAC;AAEnB,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;mBAa/B,CAAC;AACd,MAAM,MAAM,yBAAyB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,+BAA+B,CAAC,CAAC;AAExF,wBAAgB,yBAAyB,CACvC,QAAQ,EAAE,mBAAmB,GAC5B,yBAAyB,CAY3B;AAED,MAAM,WAAW,0BAA0B;IACzC,KAAK,CAAC,KAAK,EAAE,yBAAyB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,CAAC,OAAO,EAAE;QACpB,KAAK,EAAE,OAAO,CAAC;QACf,KAAK,CAAC,EAAE,yBAAyB,CAAC;KACnC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC7C,iFAAiF;IACjF,KAAK,CAAC,KAAK,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,SAAS,IAAI,uBAAuB,CAAC;IACrC;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;CAC1E;AAED,+FAA+F;AAC/F,wBAAgB,0BAA0B,CACxC,MAAM,EAAE,0BAA0B,GACjC,oBAAoB,CActB"}

package/dist/application/latest-sink.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { type ObservabilityDrainBound } from '../internal/observability-sink.js';
 export declare const ApplicationSnapshotSinkStatusSchema: z.ZodReadonly<z.ZodObject<{
     accepting: z.ZodBoolean;
     received: z.ZodNumber;
@@ -28,8 +29,17 @@ export interface ApplicationSnapshotSink<TSnapshot extends RevisionedApplication
     /** Admit a newer absolute snapshot. Returns false after close or for a stale revision. */
     publish(snapshot: TSnapshot): boolean;
     getStatus(): ApplicationSnapshotSinkStatus;
-    /** Close admission and deliver the newest snapshot accepted before this boundary. */
-    close(): Promise<ApplicationSnapshotSinkStatus>;
+    /**
+     * Close admission and deliver the newest snapshot accepted before this
+     * boundary.
+     *
+     * Bounded like every other drain here. The application-kernel guide puts this
+     * call in a cleanup path, which is the same position — and the same failure —
+     * as the shutdown that spent its whole budget waiting on a write that never
+     * settled. The status is read after the wait ends, so `inFlight` and the
+     * queue say what was not delivered.
+     */
+    close(bound?: ObservabilityDrainBound): Promise<ApplicationSnapshotSinkStatus>;
 }
 /**
  * Deliver absolute state without growing a queue: one write runs while one newer

package/dist/application/latest-sink.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"latest-sink.d.ts","sourceRoot":"","sources":["../../src/application/latest-sink.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAKxB,eAAO,MAAM,mCAAmC;;;;;;;;;;;;mBAenC,CAAC;AACd,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CACjD,OAAO,mCAAmC,CAC3C,CAAC;AAEF,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,4BAA4B,CAAC,SAAS;IACrD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;CAC9B;AAED,MAAM,WAAW,6BAA6B,CAC5C,SAAS,SAAS,6BAA6B;IAE/C,KAAK,CAAC,QAAQ,EAAE,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,WAAW,CAAC,CAAC,OAAO,EAAE,4BAA4B,CAAC,SAAS,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtF;AAED,MAAM,WAAW,uBAAuB,CAAC,SAAS,SAAS,6BAA6B;IACtF,0FAA0F;IAC1F,OAAO,CAAC,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC;IACtC,SAAS,IAAI,6BAA6B,CAAC;IAC3C,qFAAqF;IACrF,KAAK,IAAI,OAAO,CAAC,6BAA6B,CAAC,CAAC;CACjD;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,SAAS,SAAS,6BAA6B,EAC3F,MAAM,EAAE,6BAA6B,CAAC,SAAS,CAAC,GAC/C,uBAAuB,CAAC,SAAS,CAAC,CAgHpC"}
+{"version":3,"file":"latest-sink.d.ts","sourceRoot":"","sources":["../../src/application/latest-sink.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAEL,KAAK,uBAAuB,EAE7B,MAAM,gCAAgC,CAAC;AAKxC,eAAO,MAAM,mCAAmC;;;;;;;;;;;;mBAenC,CAAC;AACd,MAAM,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,CACjD,OAAO,mCAAmC,CAC3C,CAAC;AAEF,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,4BAA4B,CAAC,SAAS;IACrD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;CAC9B;AAED,MAAM,WAAW,6BAA6B,CAC5C,SAAS,SAAS,6BAA6B;IAE/C,KAAK,CAAC,QAAQ,EAAE,SAAS,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACjD,WAAW,CAAC,CAAC,OAAO,EAAE,4BAA4B,CAAC,SAAS,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACtF;AAED,MAAM,WAAW,uBAAuB,CAAC,SAAS,SAAS,6BAA6B;IACtF,0FAA0F;IAC1F,OAAO,CAAC,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC;IACtC,SAAS,IAAI,6BAA6B,CAAC;IAC3C;;;;;;;;;OASG;IACH,KAAK,CAAC,KAAK,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,6BAA6B,CAAC,CAAC;CAChF;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAAC,SAAS,SAAS,6BAA6B,EAC3F,MAAM,EAAE,6BAA6B,CAAC,SAAS,CAAC,GAC/C,uBAAuB,CAAC,SAAS,CAAC,CAoHpC"}

package/dist/application-opentelemetry.js

@@ -1,10 +1,11 @@
 import {
   ActivitySnapshotSchema,
   ManagedScheduleStatusSchema
-} from "./index-6s7n2v50.js";
+} from "./index-9f8ztey6.js";
 import {
   ApplicationSnapshotSchema
 } from "./index-3gye9wzb.js";
+import"./index-wnfk50r0.js";
 import"./index-7gnkny4z.js";
 
 // src/application/opentelemetry.ts

package/dist/application.js

@@ -26,7 +26,7 @@ import {
   createActivityProjection,
   createApplicationSnapshotSink,
   createManagedSchedule
-} from "./index-6s7n2v50.js";
+} from "./index-9f8ztey6.js";
 import {
   DiagnosticJournalCloseResultSchema,
   DiagnosticJournalFailurePhaseSchema,
@@ -60,7 +60,7 @@ import {
 import"./index-3z73fh2c.js";
 import {
   createBoundedSinkManager
-} from "./index-a59da114.js";
+} from "./index-wnfk50r0.js";
 import {
   backoffDelay,
   createBackoff
@@ -576,9 +576,9 @@ function createApplicationEventSink(config) {
     publish(snapshot) {
       manager.submit(() => applicationLifecycleEvent(snapshot));
     },
-    flush: () => manager.flush(),
+    flush: (bound) => manager.flush(bound),
     getStatus: () => manager.getStatus(),
-    close: () => manager.close()
+    close: (bound) => manager.close(bound)
   };
 }
 // src/application/health.ts

package/dist/{index-6s7n2v50.js → index-9f8ztey6.js}

@@ -1,6 +1,10 @@
 import {
   ApplicationIdSchema
 } from "./index-3gye9wzb.js";
+import {
+  assertDrainBound,
+  withinBound
+} from "./index-wnfk50r0.js";
 import {
   createBoundedChannel
 } from "./index-7gnkny4z.js";
@@ -111,16 +115,17 @@ function createApplicationSnapshotSink(config) {
       return true;
     },
     getStatus,
-    close() {
-      if (closePromise)
-        return closePromise;
-      accepting = false;
-      pending.close({ mode: "drain" });
-      closePromise = new Promise((resolve) => {
-        resolveClose = resolve;
-        settleCloseIfIdle();
-      });
-      return closePromise;
+    close(bound) {
+      assertDrainBound(bound);
+      if (!closePromise) {
+        accepting = false;
+        pending.close({ mode: "drain" });
+        closePromise = new Promise((resolve) => {
+          resolveClose = resolve;
+          settleCloseIfIdle();
+        });
+      }
+      return withinBound(closePromise, bound).then(() => getStatus());
     }
   };
 }

package/dist/{index-1dd82z59.js → index-st8v8739.js}

@@ -8,7 +8,7 @@ import {
 } from "./index-y2s6h5bf.js";
 import {
   createBoundedSinkManager
-} from "./index-a59da114.js";
+} from "./index-wnfk50r0.js";
 import {
   AgentRuntimeEventSchema,
   agentDurableEventId
@@ -201,9 +201,9 @@ function createAgentRuntimeEventSink(config) {
       if (projected)
         manager.submit(() => AgentRuntimeEventSchema.parse(projected));
     },
-    flush: () => manager.flush(),
+    flush: (bound) => manager.flush(bound),
     getStatus: () => manager.getStatus(),
-    close: () => manager.close()
+    close: (bound) => manager.close(bound)
   };
 }
 

package/dist/{index-a59da114.js → index-wnfk50r0.js}

@@ -21,7 +21,8 @@ var ObservabilityStatusObjectSchema = z.object({
 });
 var ObservabilityStatusSchema = ObservabilityStatusObjectSchema.readonly();
 var ObservabilityDrainReportSchema = ObservabilityStatusObjectSchema.extend({
-  durationMs: z.number().nonnegative()
+  durationMs: z.number().nonnegative(),
+  drained: z.boolean()
 }).readonly();
 var SUMMED_STATUS_KEYS = [
   "capacity",
@@ -56,6 +57,41 @@ function aggregateObservabilityStatus(surfaces, closed) {
 }
 
 // src/internal/observability-sink.ts
+function assertDrainBound(bound) {
+  const timeoutMs = bound?.timeoutMs;
+  if (timeoutMs === undefined)
+    return;
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) {
+    throw new TypeError("Observability drain timeoutMs must be a non-negative finite number");
+  }
+}
+function withinBound(work, bound) {
+  assertDrainBound(bound);
+  const { timeoutMs, signal } = bound ?? {};
+  if (timeoutMs === undefined && !signal)
+    return work.then(() => true);
+  let timer;
+  let onAbort;
+  const reached = new Promise((resolve) => {
+    const give = () => resolve(false);
+    if (signal?.aborted) {
+      give();
+      return;
+    }
+    if (signal) {
+      onAbort = give;
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+    if (timeoutMs !== undefined)
+      timer = setTimeout(give, timeoutMs);
+  });
+  return Promise.race([work.then(() => true), reached]).finally(() => {
+    if (timer !== undefined)
+      clearTimeout(timer);
+    if (onAbort && signal)
+      signal.removeEventListener("abort", onAbort);
+  });
+}
 var DEFAULT_MAX_PENDING = 1000;
 function invokeIsolated(callback) {
   if (!callback)
@@ -76,7 +112,7 @@ function createBoundedSinkManager(config) {
   let dropped = 0;
   let failed = 0;
   let preparationFailed = 0;
-  let closePromise;
+  let drain;
   const preparing = new Map;
   const writes = new Map;
   const reportError = (error, event) => {
@@ -102,12 +138,16 @@ function createBoundedSinkManager(config) {
       return;
     }
     accepted += 1;
-    const write = Promise.resolve().then(() => config.write(event)).then(() => {
+    const settle = (record) => {
+      record();
+      writes.delete(id);
+    };
+    const write = Promise.resolve().then(() => config.write(event)).then(() => settle(() => {
       completed += 1;
-    }).catch((error) => {
+    }), (error) => settle(() => {
       failed += 1;
       reportError(error, event);
-    }).finally(() => writes.delete(id));
+    }));
     writes.set(id, write);
   };
   const awaitGeneration = async (boundary) => {
@@ -129,22 +169,26 @@ function createBoundedSinkManager(config) {
         });
         return;
       }
-      const preparation = Promise.resolve().then(produce).then((event) => admit(id, event)).catch((error) => {
+      const preparation = Promise.resolve().then(produce).then((event) => {
+        preparing.delete(id);
+        admit(id, event);
+      }, (error) => {
+        preparing.delete(id);
         preparationFailed += 1;
         reportError(error);
-      }).finally(() => preparing.delete(id));
+      });
       preparing.set(id, preparation);
     },
-    flush() {
-      return awaitGeneration(sequence);
+    flush(bound) {
+      assertDrainBound(bound);
+      return withinBound(awaitGeneration(sequence), bound);
     },
     getStatus,
-    close() {
-      if (closePromise)
-        return closePromise;
+    close(bound) {
+      assertDrainBound(bound);
+      drain ??= awaitGeneration(sequence);
       closed = true;
-      closePromise = awaitGeneration(sequence).then(getStatus);
-      return closePromise;
+      return withinBound(drain, bound).then(getStatus);
     }
   };
   function getStatus() {
@@ -164,4 +208,4 @@ function createBoundedSinkManager(config) {
   }
 }
 
-export { ObservabilitySinkStatusSchema, ObservabilityStatusSchema, ObservabilityDrainReportSchema, aggregateObservabilityStatus, createBoundedSinkManager };
+export { ObservabilitySinkStatusSchema, ObservabilityStatusSchema, ObservabilityDrainReportSchema, aggregateObservabilityStatus, assertDrainBound, withinBound, createBoundedSinkManager };

package/dist/internal/observability-sink.d.ts

@@ -16,11 +16,66 @@ export interface BoundedSinkConfig<EVENT> {
     onSinkError?(failure: BoundedSinkError<EVENT>): void | Promise<void>;
     onDrop?(drop: BoundedSinkDrop<EVENT>): void | Promise<void>;
 }
+/**
+ * A caller's limit on how long a drain may WAIT.
+ *
+ * Unbounded, a drain waits for every accepted event however long the sink
+ * takes — correct when the sink is healthy, fatal when it is not. One write
+ * that never settles, a database that has stopped answering, held `close()`
+ * forever; an application whose shutdown graph gives every other step a
+ * deadline then spent its whole budget here and exited by force. A drain that
+ * cannot be bounded cannot take part in a shutdown budget: it either fits, or
+ * it cancels the budget.
+ *
+ * The bound ends the WAITING, not the writes: a sink's `write` is handed no
+ * cancellation, so an outstanding one keeps running against whatever the caller
+ * closes next. And it is a bound on waiting for I/O, not on wall time — no
+ * bound can preempt a `write` that occupies the event loop.
+ */
+export interface ObservabilityDrainBound {
+    /** Give up waiting after this many milliseconds. */
+    timeoutMs?: number;
+    /** Give up waiting when this signal aborts. */
+    signal?: AbortSignal;
+}
+/**
+ * Refuse a nonsensical bound BEFORE anything is mutated, so a call that throws
+ * has no effect — admission stays open rather than half-closed.
+ */
+export declare function assertDrainBound(bound: ObservabilityDrainBound | undefined): void;
+/**
+ * Wait for `work`, but not past `bound`. Resolves `true` when the work settled
+ * first, `false` when the bound did.
+ *
+ * Composed by hand rather than with `AbortSignal.any`, because the composite it
+ * returns registers itself on the caller's signal and is never released: on Bun
+ * that is a dependent leaked per drain against a process-lifetime signal, and
+ * `flush({ signal })` per batch is exactly the shape that accumulates them.
+ * A listener and a timer, both disposed here, cost nothing and leave nothing.
+ *
+ * The timer is REF'D, and that is the whole mechanism. Unref'ing it reads like
+ * good hygiene — a drain bound should not keep a process alive while it is
+ * shutting down — and it silently destroys the feature: a pending write holds
+ * nothing, so when the stuck write is the last thing left, an unref'd timer
+ * lets the loop empty and the bound never fires at all. That is not an edge
+ * case, it is the case this exists for. The timer cannot outlive the deadline
+ * the caller itself asked for, so holding the loop for exactly that long is
+ * what was wanted. Found only by installing the published package and running
+ * it under `node`, where the process exits 13 on an unsettled top-level await;
+ * every in-process test passes because the runner keeps the loop alive.
+ */
+export declare function withinBound(work: Promise<unknown>, bound: ObservabilityDrainBound | undefined): Promise<boolean>;
 export interface BoundedSinkManager<EVENT> {
     submit(produce: () => EVENT | Promise<EVENT>): void;
-    flush(): Promise<void>;
+    /** Whether the generation admitted before this call settled inside the bound. */
+    flush(bound?: ObservabilityDrainBound): Promise<boolean>;
     getStatus(): ObservabilitySinkStatus;
-    close(): Promise<ObservabilitySinkStatus>;
+    /**
+     * Stop admission and drain. The status is read AFTER the wait ends, so
+     * `pending` and `preparing` say what the sink had not written — including
+     * when the bound ended the wait early.
+     */
+    close(bound?: ObservabilityDrainBound): Promise<ObservabilitySinkStatus>;
 }
 export declare function createBoundedSinkManager<EVENT>(config: BoundedSinkConfig<EVENT>): BoundedSinkManager<EVENT>;
 //# sourceMappingURL=observability-sink.d.ts.map

package/dist/internal/observability-sink.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observability-sink.d.ts","sourceRoot":"","sources":["../../src/internal/observability-sink.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,uBAAuB,EAE7B,MAAM,yBAAyB,CAAC;AAEjC,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE1D,MAAM,WAAW,gBAAgB,CAAC,KAAK;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,eAAe,CAAC,KAAK;IACpC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB,CAAC,KAAK;IACtC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,MAAM,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,CAAC,OAAO,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,MAAM,CAAC,CAAC,IAAI,EAAE,eAAe,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AAED,MAAM,WAAW,kBAAkB,CAAC,KAAK;IACvC,MAAM,CAAC,OAAO,EAAE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IACpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,SAAS,IAAI,uBAAuB,CAAC;IACrC,KAAK,IAAI,OAAO,CAAC,uBAAuB,CAAC,CAAC;CAC3C;AAaD,wBAAgB,wBAAwB,CAAC,KAAK,EAC5C,MAAM,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAC/B,kBAAkB,CAAC,KAAK,CAAC,CA8H3B"}
+{"version":3,"file":"observability-sink.d.ts","sourceRoot":"","sources":["../../src/internal/observability-sink.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,uBAAuB,EAE7B,MAAM,yBAAyB,CAAC;AAEjC,MAAM,MAAM,qBAAqB,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE1D,MAAM,WAAW,gBAAgB,CAAC,KAAK;IACrC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,KAAK,CAAC;CACf;AAED,MAAM,WAAW,eAAe,CAAC,KAAK;IACpC,MAAM,EAAE,qBAAqB,CAAC;IAC9B,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB,CAAC,KAAK;IACtC,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1C,MAAM,CAAC,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,CAAC,OAAO,EAAE,gBAAgB,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrE,MAAM,CAAC,CAAC,IAAI,EAAE,eAAe,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,uBAAuB;IACtC,oDAAoD;IACpD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+CAA+C;IAC/C,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,uBAAuB,GAAG,SAAS,GAAG,IAAI,CAMjF;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,EACtB,KAAK,EAAE,uBAAuB,GAAG,SAAS,GACzC,OAAO,CAAC,OAAO,CAAC,CA2BlB;AAED,MAAM,WAAW,kBAAkB,CAAC,KAAK;IACvC,MAAM,CAAC,OAAO,EAAE,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;IACpD,iFAAiF;IACjF,KAAK,CAAC,KAAK,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACzD,SAAS,IAAI,uBAAuB,CAAC;IACrC;;;;OAIG;IACH,KAAK,CAAC,KAAK,CAAC,EAAE,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAC;CAC1E;AAaD,wBAAgB,wBAAwB,CAAC,KAAK,EAC5C,MAAM,EAAE,iBAAiB,CAAC,KAAK,CAAC,GAC/B,kBAAkB,CAAC,KAAK,CAAC,CAuJ3B"}

package/dist/observability/audit.d.ts

@@ -4,6 +4,7 @@
  * Both are normalised into `RequestEvent` without nested fetch wrappers.
  */
 import type { RuntimeContext } from '../contract/index.js';
+import { type ObservabilityDrainBound } from '../internal/observability-sink.js';
 import type { MethodDef } from '../server/types.js';
 import type { ToolCallHooks } from '../tools/execute.js';
 import { type DimensionCollision, type RequestContext } from './context.js';
@@ -66,13 +67,28 @@ export interface HttpRequestObserver {
 export interface Observability {
     request?: HttpRequestObserver;
     toolCall: ToolCallHooks;
-    /** Wait for events admitted before this call. */
-    flush(): Promise<void>;
+    /**
+     * Wait for events admitted before this call; `true` when they settled inside
+     * the bound.
+     *
+     * The outcome is RETURNED rather than left to `getStatus()`, which cannot
+     * answer it: flush waits on the generation admitted before this call, while
+     * the status counts everything alive right now — so a nonzero `pending` after
+     * a complete flush and after an expired one look identical.
+     */
+    flush(bound?: ObservabilityDrainBound): Promise<boolean>;
     /** Read an immutable snapshot of each enabled sink and their aggregate. */
     getStatus(): ObservabilityStatus;
-    /** Stop admission and drain every previously accepted event. Idempotent. */
-    close(): Promise<ObservabilityDrainReport>;
+    /**
+     * Stop admission and drain every previously accepted event. Idempotent.
+     *
+     * With a bound, returns a report rather than waiting past it; `drained` says
+     * which happened. The drain itself is started once and shared, so a second
+     * call with a shorter bound observes the same drain under its own limit.
+     */
+    close(bound?: ObservabilityDrainBound): Promise<ObservabilityDrainReport>;
 }
+export type { ObservabilityDrainBound };
 export type ProjectedDimensions = Readonly<Record<string, string | undefined>>;
 /** Typed, explicit attribution rules composed into an application's hooks. */
 export interface DimensionsProjectorConfig<TContext extends RuntimeContext, TResult> {

package/dist/observability/audit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/observability/audit.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAOlD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAc,MAAM,kBAAkB,CAAC;AAClE,OAAO,EACL,KAAK,kBAAkB,EAEvB,KAAK,cAAc,EAEpB,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EAAe,KAAK,eAAe,EAAmB,MAAM,YAAY,CAAC;AAChF,OAAO,EAEL,KAAK,wBAAwB,EAG7B,KAAK,mBAAmB,EAEzB,MAAM,UAAU,CAAC;AAGlB,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,KAAK,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,iFAAiF;IACjF,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC;IAC1C,yEAAyE;IACzE,QAAQ,CAAC,EAAE,eAAe,CAAC;IAC3B,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,SAAS,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3D,8DAA8D;IAC9D,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD;AAED,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,QAAQ,CAAC;AAEnD,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,YAAY,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,0BAA2B,SAAQ,sBAAsB;IACxE,2DAA2D;IAC3D,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,0BAA0B,CAAC;IACrC,KAAK,CAAC,EAAE,sBAAsB,CAAC;CAChC;AAED,gEAAgE;AAChE,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,cAAc,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3B,4EAA4E;IAC5E,OAAO,CAAC,EAAE,WAAW,CAAC;CACvB;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,cAAc,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,qBAAqB,GAAG,IAAI,CAAC;CACnD;AAED,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,OAAO,CAAC,EAAE,mBAAmB,CAAC;IAC9B,QAAQ,EAAE,aAAa,CAAC;IACxB,iDAAiD;IACjD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,2EAA2E;IAC3E,SAAS,IAAI,mBAAmB,CAAC;IACjC,4EAA4E;IAC5E,KAAK,IAAI,OAAO,CAAC,wBAAwB,CAAC,CAAC;CAC5C;AAED,MAAM,MAAM,mBAAmB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;AAE/E,8EAA8E;AAC9E,MAAM,WAAW,yBAAyB,CAAC,QAAQ,SAAS,cAAc,EAAE,OAAO;IACjF,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,KAAK,mBAAmB,CAAC;IACtE,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,KAAK,mBAAmB,CAAC;IACtF,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,KAAK,mBAAmB,CAAC;IACrF,kEAAkE;IAClE,SAAS,CAAC,EAAE,kBAAkB,CAAC;CAChC;AAED,MAAM,WAAW,mBAAmB,CAAC,QAAQ,SAAS,cAAc,EAAE,OAAO;IAC3E,OAAO,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,GAAG,IAAI,CAAC;IAClD,MAAM,CAAC,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC;IACrE,KAAK,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;CAClE;AAgBD;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,QAAQ,SAAS,cAAc,GAAG,cAAc,EAChD,OAAO,GAAG,OAAO,EAEjB,MAAM,EAAE,yBAAyB,CAAC,QAAQ,EAAE,OAAO,CAAC,GACnD,mBAAmB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAcxC;AA2ED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,aAAa,CA8J9E"}
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../src/observability/audit.ts"],"names":[],"mappings":"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"}

package/dist/observability/index.d.ts

@@ -6,7 +6,7 @@
  * framework-owned HTTP completion plus canonical tool hooks into independent
  * sinks.
  */
-export { createDimensionsProjector, createObservability, type DimensionsProjector, type DimensionsProjectorConfig, type HttpRequestCompletion, type HttpRequestObserver, type Observability, type ObservabilityConfig, type ProjectedDimensions, type RequestEventSinkConfig, type RequestObservabilityConfig, type SinkDrop, type SinkDropReason, type SinkError, } from './audit.js';
+export { createDimensionsProjector, createObservability, type DimensionsProjector, type DimensionsProjectorConfig, type HttpRequestCompletion, type HttpRequestObserver, type Observability, type ObservabilityConfig, type ObservabilityDrainBound, type ProjectedDimensions, type RequestEventSinkConfig, type RequestObservabilityConfig, type SinkDrop, type SinkDropReason, type SinkError, } from './audit.js';
 export { type BoundedLoggerBounds, type BoundedLoggerOptions, createBoundedLogger, DEFAULT_REDACT_PATHS, } from './bounded-logger.js';
 export { type DimensionCollision, getRequestContext, getTraceId, getUserId, type RequestContext, runWithRequestContext, type SetRequestDimensionsOptions, setRequestDimensions, setRequestEndpoint, setRequestError, setRequestUser, type WrapRequestContextOptions, wrapInRequestContext, } from './context.js';
 export type { RequestEvent } from './event.js';

package/dist/observability/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAC/B,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,SAAS,GACf,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,kBAAkB,EACvB,iBAAiB,EACjB,UAAU,EACV,SAAS,EACT,KAAK,cAAc,EACnB,qBAAqB,EACrB,KAAK,2BAA2B,EAChC,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,KAAK,yBAAyB,EAC9B,oBAAoB,GACrB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EACL,KAAK,SAAS,EACd,WAAW,EACX,MAAM,EACN,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,wBAAwB,EAC7B,8BAA8B,EAC9B,KAAK,uBAAuB,EAC5B,6BAA6B,EAC7B,KAAK,mBAAmB,EACxB,yBAAyB,GAC1B,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,yBAAyB,EACzB,mBAAmB,EACnB,KAAK,YAAY,GAClB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,KAAK,mBAAmB,EACxB,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC1B,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACxB,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAC/B,KAAK,QAAQ,EACb,KAAK,cAAc,EACnB,KAAK,SAAS,GACf,MAAM,SAAS,CAAC;AACjB,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,oBAAoB,EACzB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,KAAK,kBAAkB,EACvB,iBAAiB,EACjB,UAAU,EACV,SAAS,EACT,KAAK,cAAc,EACnB,qBAAqB,EACrB,KAAK,2BAA2B,EAChC,oBAAoB,EACpB,kBAAkB,EAClB,eAAe,EACf,cAAc,EACd,KAAK,yBAAyB,EAC9B,oBAAoB,GACrB,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,EACL,KAAK,SAAS,EACd,WAAW,EACX,MAAM,EACN,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,eAAe,EACf,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,KAAK,wBAAwB,EAC7B,8BAA8B,EAC9B,KAAK,uBAAuB,EAC5B,6BAA6B,EAC7B,KAAK,mBAAmB,EACxB,yBAAyB,GAC1B,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,SAAS,EACT,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,yBAAyB,EACzB,mBAAmB,EACnB,KAAK,YAAY,GAClB,MAAM,SAAS,CAAC"}

package/dist/observability/index.js

@@ -3,8 +3,10 @@ import {
   ObservabilitySinkStatusSchema,
   ObservabilityStatusSchema,
   aggregateObservabilityStatus,
-  createBoundedSinkManager
-} from "../index-a59da114.js";
+  assertDrainBound,
+  createBoundedSinkManager,
+  withinBound
+} from "../index-wnfk50r0.js";
 import {
   measureSize,
   redact,
@@ -115,7 +117,9 @@ function createObservability(config) {
   const requestManager = config.request ? createSinkManager(config.request) : undefined;
   const toolManager = config.tools ? createSinkManager(config.tools) : undefined;
   let closed = false;
-  let closePromise;
+  let drain;
+  let drainStartedAt = 0;
+  let unbounded;
   const request = config.request ? {
     includePayload: config.request.includePayload ?? false,
     complete: ({ context, statusCode, durationMs, payload, outcome }) => {
@@ -232,23 +236,34 @@ function createObservability(config) {
   return {
     ...request && { request },
     toolCall: toolCall ?? {},
-    async flush() {
-      await Promise.all([requestManager?.flush(), toolManager?.flush()]);
+    flush(bound) {
+      assertDrainBound(bound);
+      return withinBound(Promise.all([requestManager?.flush(), toolManager?.flush()]), bound);
     },
     getStatus,
-    close() {
-      if (!closePromise) {
+    close(bound) {
+      assertDrainBound(bound);
+      if (!drain) {
         closed = true;
-        const startedAt = performance.now();
-        closePromise = Promise.all([requestManager?.close(), toolManager?.close()]).then(() => {
-          const status = getStatus();
-          return ObservabilityDrainReportSchema.parse({
-            ...status,
-            durationMs: performance.now() - startedAt
-          });
+        drainStartedAt = performance.now();
+        drain = Promise.all([requestManager?.close(), toolManager?.close()]).then(() => {
+          return;
+        });
+      }
+      const startedAt = drainStartedAt;
+      const report = () => {
+        const status = getStatus();
+        return ObservabilityDrainReportSchema.parse({
+          ...status,
+          durationMs: performance.now() - startedAt,
+          drained: status.total.pending + status.total.preparing === 0
         });
+      };
+      if (!bound?.signal && bound?.timeoutMs === undefined) {
+        unbounded ??= withinBound(drain, undefined).then(report);
+        return unbounded;
       }
-      return closePromise;
+      return withinBound(drain, bound).then(report);
     }
   };
 }

package/dist/observability/status.d.ts

@@ -98,6 +98,7 @@ export declare const ObservabilityDrainReportSchema: z.ZodReadonly<z.ZodObject<{
         closed: z.ZodBoolean;
     }, z.core.$strip>>;
     durationMs: z.ZodNumber;
+    drained: z.ZodBoolean;
 }, z.core.$strip>>;
 export type ObservabilityDrainReport = z.infer<typeof ObservabilityDrainReportSchema>;
 /** Build and freeze the aggregate without exposing mutable counters. */

package/dist/observability/status.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/observability/status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,yEAAyE;AACzE,eAAO,MAAM,6BAA6B;;;;;;;;;;;;kBAc7B,CAAC;AAEd,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AASpF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAA6C,CAAC;AAEpF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,sFAAsF;AACtF,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAE9B,CAAC;AAEd,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAiBtF,wEAAwE;AACxE,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,SAAS,uBAAuB,EAAE,EAC5C,MAAM,EAAE,OAAO,GACd,uBAAuB,CAiBzB"}
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../../src/observability/status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,yEAAyE;AACzE,eAAO,MAAM,6BAA6B;;;;;;;;;;;;kBAc7B,CAAC;AAEd,MAAM,MAAM,uBAAuB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,6BAA6B,CAAC,CAAC;AASpF,eAAO,MAAM,yBAAyB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAA6C,CAAC;AAEpF,MAAM,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,yBAAyB,CAAC,CAAC;AAE5E,sFAAsF;AACtF,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAoB9B,CAAC;AAEd,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAiBtF,wEAAwE;AACxE,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,SAAS,uBAAuB,EAAE,EAC5C,MAAM,EAAE,OAAO,GACd,uBAAuB,CAiBzB"}

package/llms-full.txt

@@ -63,11 +63,11 @@ own, recorded as an ADR.
 | `stitchkit/tracking/server` | server (Bun or Node) | evolving | the decisions a tracking backend makes — dispositions, visit lease over an application-owned store, active intervals, presence; no database |
 | `stitchkit/release` | browser **and** server | evolving | a page follows the release it was built for — `createReleaseMarker` on the server, `createReleaseWatcher` in the browser, the `X-Build-Id` header and a socket event between them |
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
-| `stitchkit/observability` | server | stable | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 1 of the 28 minors since 0.56.2, most recently 0.83.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the store and managed-resource conformance kits |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 11 of the 27 minors since 0.56.2, most recently 0.75.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 12 of the 28 minors since 0.56.2, most recently 0.83.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
 | `stitchkit/agent-runtime/coding-tools` | server (Bun or Node) | evolving | bounded host-authorized direct file and shell tools; a root boundary, not an OS sandbox |
 | `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
@@ -75,7 +75,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 6 of the 27 minors since 0.56.2, most recently 0.79.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 7 of the 28 minors since 0.56.2, most recently 0.83.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -9486,7 +9486,7 @@ export const observability = createObservability({
 })
 
 const status = observability.getStatus()
-const drained = await observability.close()
+const report = await observability.close({ timeoutMs: 5_000 })
 ```
 
 `maxPending` defaults to `1000` per sink and must be a positive safe integer.
@@ -9504,14 +9504,71 @@ without parsing callback logs.
 
 `flush()` snapshots the current generation and waits only for events admitted
 up to that call. `close()` atomically stops admission, drains every accepted
-generation and returns the final counters plus `durationMs`; repeated calls
-return the same report. Graceful shutdown order is therefore:
+generation and returns the final counters plus `durationMs`; repeated unbounded
+calls return the same report. Graceful shutdown order is therefore:
 
 1. stop HTTP/MCP admission;
 2. wait for active requests and tool calls;
-3. `await observability.close()`;
+3. `await observability.close({ timeoutMs })`;
 4. close the database/storage connection used by the sinks.
 
+### Give the drain a bound in a shutdown budget
+
+Unbounded, `close()` waits for every accepted event however long the sink takes.
+That is right when the sink is healthy and fatal when it is not: one write that
+never settles — a database that has stopped answering — holds the drain forever,
+and a shutdown that gives every other step a deadline then spends its entire
+budget here and exits by force. A drain that cannot be bounded cannot take part
+in a shutdown budget: it either fits, or it cancels the budget.
+
+Both `flush` and `close` take `{ timeoutMs?, signal? }`:
+
+```ts
+const report = await observability.close({ timeoutMs: 5_000 })
+if (!report.drained) {
+  const t = report.total
+  logger.warn('audit drain incomplete', {
+    stillWriting: t.pending + t.preparing,
+    neverWritten: t.received - t.filtered - t.completed,
+  })
+}
+```
+
+Those are two different numbers and the difference matters. `pending +
+preparing` is what the drain was still waiting for when the bound expired —
+events handed to `write` that may yet succeed. `received - filtered -
+completed` is every event the sink has not written **for any reason**: those,
+plus the ones already lost to `failed`, `dropped` and `preparationFailed`. A
+shutdown log that wants to state how much audit was lost wants the second; one
+that wants to explain why the drain did not finish wants the first.
+
+`drained` is read from the counters, not from which side of the race won, so a
+bound that expires on a sink that has in fact finished — a shutdown signal
+already aborted by an earlier step — reports `true` rather than a false alarm.
+
+The bound ends the **waiting**, not the writes: a sink's `write` is handed no
+cancellation, so an outstanding one keeps running against whatever the consumer
+closes next. It is a bound on waiting for I/O, not on wall time — no bound can
+preempt a `write` that occupies the event loop. Racing `close()` against your
+own timer looks equivalent and is not: it discards the report along with the
+wait.
+
+`flush(bound?)` takes the same bound and returns whether the generation it
+waited on settled. That outcome is returned rather than left to `getStatus()`,
+which cannot answer it: flush waits on the events admitted before the call while
+the status counts everything alive right now, so a complete flush and an expired
+one look identical there.
+
+Every other sink in the framework takes the same bound —
+`createApplicationEventSink`, `createApplicationSnapshotSink`,
+`createAgentRuntimeEventSink`, `createAgentObservability`. The hazard was never
+specific to the audit sink; it was specific to waiting without a limit.
+
+The drain itself is started once and shared, so a second `close` with a shorter
+bound observes the same drain under its own limit rather than starting another.
+Passing no bound keeps the previous behaviour exactly, including the identical
+returned promise.
+
 Stitchkit manages only in-process delivery. If process-crash durability matters,
 make `write` enqueue into a consumer-owned durable outbox and let that adapter
 own retry, replay and storage policy:
@@ -10970,6 +11027,53 @@ makes one thing your job rather than the resolver's:
 The mechanical part is identical either way. Only the *noticing* differs, and an
 exact pin moves it onto you.
 
+## Released migration: 0.83.0
+
+Two things, both mechanical, and only if you touch an observability sink.
+
+```bash
+rg -n "createObservability|createApplicationEventSink|createApplicationSnapshotSink|createAgentRuntimeEventSink|createAgentObservability"
+```
+
+**1. `flush()` returns `Promise<boolean>`.** `await sink.flush()` needs no
+change. Only a declared type does:
+
+```ts
+// before
+const flushAudit: () => Promise<void> = observability.flush
+// after
+const flushAudit: () => Promise<boolean> = observability.flush
+```
+
+**2. `ObservabilityDrainReport` carries `drained`.** The framework builds it, so
+reading code is unchanged. A hand-built report — a test double, or one persisted
+and re-parsed through `ObservabilityDrainReportSchema` — needs the field:
+
+```ts
+// before
+{ request, tools, total, durationMs }
+// after
+{ request, tools, total, durationMs, drained: true }
+```
+
+Then take the thing this release exists for. Every drain now accepts
+`{ timeoutMs?, signal? }`, so a shutdown can give the audit drain the same
+deadline it gives every other step:
+
+```ts
+const report = await observability.close({ timeoutMs: 5_000 })
+if (!report.drained) {
+  logger.warn('audit drain incomplete', {
+    unwritten: report.total.received - report.total.filtered - report.total.completed,
+  })
+}
+```
+
+The bound ends the **waiting**, not the writes: a sink's `write` is handed no
+cancellation, so an outstanding one keeps running against whatever you close
+next. Racing `close()` against your own timer looks equivalent and is not — it
+discards the report along with the wait.
+
 ## Released migration: 0.82.0
 
 One thing, and only if you mount MCP or agent tools from a `createTrackingContract` contract.
@@ -15279,10 +15383,11 @@ audit event. See the [Observability guide](../guide/observability.md).
 | `BoundedLoggerBounds` / `BoundedLoggerOptions` | _type_ | per-value and total record ceilings plus sink/redaction configuration |
 | `RequestEvent` | _type_ | the normalised audit event handed to the sink; opt-in HTTP cancellation rows carry `outcome: 'cancelled'` |
 | `ObservabilityConfig` | _type_ | independent request and tool sink configuration |
-| `Observability` | _type_ | `{ request?, toolCall, getStatus(), flush(), close() }` with bounded sink lifecycle |
+| `Observability` | _type_ | `{ request?, toolCall, getStatus(), flush(bound?): Promise<boolean>, close(bound?) }` with bounded sink lifecycle |
+| `ObservabilityDrainBound` | _type_ | `timeoutMs` and/or `signal` limiting how long `flush`/`close` wait; the wait ends, outstanding writes do not |
 | `ObservabilitySinkStatus` | _type_ | immutable counters for one bounded request/tool sink |
 | `ObservabilityStatus` | _type_ | per-surface plus aggregate operational snapshot |
-| `ObservabilityDrainReport` | _type_ | final closed/drained snapshot plus duration |
+| `ObservabilityDrainReport` | _type_ | final closed/drained snapshot, `durationMs` (the shared drain's age, not this call's wait), and `drained` — read from the counters, `false` only when `total.pending + total.preparing` is nonzero |
 | `ObservabilitySinkStatusSchema` / `ObservabilityStatusSchema` / `ObservabilityDrainReportSchema` | schema | runtime schemas for status/report integration boundaries |
 | `RequestEventSinkConfig` | _type_ | `write`, filter/sanitisation, `maxPending`, `onSinkError` and `onDrop` |
 | `RequestObservabilityConfig` | _type_ | request sink plus opt-in payload capture and default-off `includeCancelled` rows |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.82.0",
+  "version": "0.83.1",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",