Add manual fingers-crossed buffer controls

Let callers flush or discard buffered records through sink methods or a
record-driven bufferAction callback. Support category and context
selectors while ending the matching lifecycle after each action.

Keep isolated buffer identities as structured metadata, and reset global
state before forwarding records so errors and synchronous re-entry cannot
leave stale buffers. Document the APIs and cover lifecycle edge cases
across runtimes.

Closes #205

Assisted-by: Codex:gpt-5.6-sol

Author: dahlia

CHANGES.md

@@ -10,10 +10,14 @@ To be released.
 
 ### @logtape/logtape
 
+ -  Added `FingersCrossedSink.flush()` and `FingersCrossedSink.discard()`
+    methods and the `FingersCrossedOptions.bufferAction` callback for flushing
+    or discarding isolated buffers when a request or job completes.  [[#205]]
  -  Added the `StreamSinkOptions.closeStream` option to dispose stream sinks
     without closing caller-owned streams. [[#203]]
 
 [#203]: https://github.com/dahlia/logtape/issues/203
+[#205]: https://github.com/dahlia/logtape/issues/205
 
 
 Version 2.3.1

changes.d/logtape/buffer-lifecycle-control.md

@@ -0,0 +1,3 @@
+ -  Added `FingersCrossedSink.flush()` and `FingersCrossedSink.discard()`
+    methods and the `FingersCrossedOptions.bufferAction` callback for flushing
+    or discarding isolated buffers when a request or job completes.  [[#205]]

docs/manual/sinks.md

@@ -594,6 +594,77 @@ await configure({
 With both isolations enabled, buffers are only flushed when both the category
 relationship matches and the context values are the same.
 
+### Record-driven buffer actions
+
+*This API is available since LogTape 2.4.0.*
+
+Use the `~FingersCrossedOptions.bufferAction` callback when a log record marks
+the end of a request, job, or other isolated lifecycle.  Return `"flush"` to
+emit the matching buffered records and the action record, or `"discard"` to
+drop both:
+
+~~~~ typescript twoslash
+// @noErrors: 2345
+import { fingersCrossed, getConsoleSink } from "@logtape/logtape";
+
+const sink = fingersCrossed(getConsoleSink(), {
+  isolateByContext: { keys: ["requestId"] },
+  bufferAction(record) {
+    const status = record.properties.status;
+    if (typeof status !== "number") return undefined;
+    return status >= 500 ? "flush" : "discard";
+  },
+});
+~~~~
+
+Returning `undefined` applies the regular `triggerLevel` and `bufferLevel`
+behavior.  The callback runs before LogTape checks whether the matching buffer
+has already been triggered, so a final request record also releases an active
+triggered context.
+
+Both callback actions are terminal.  After flushing or discarding, the same
+isolation key starts a fresh buffer if it appears again.  This differs from a
+`triggerLevel` match, which flushes the buffer and lets subsequent records for
+the triggered isolation pass through directly.
+
+### Manual buffer control
+
+*This API is available since LogTape 2.4.0.*
+
+The sink returned by `fingersCrossed()` implements `FingersCrossedSink`.  Use
+its `~FingersCrossedSink.flush()` and `~FingersCrossedSink.discard()` methods
+when the lifecycle ends outside the logging stream:
+
+~~~~ typescript twoslash
+// @noErrors: 2345
+import { fingersCrossed, getConsoleSink } from "@logtape/logtape";
+
+const sink = fingersCrossed(getConsoleSink(), {
+  isolateByContext: { keys: ["requestId"] },
+});
+
+// ---cut-before---
+function finishRequest(requestId: string, succeeded: boolean) {
+  if (succeeded) {
+    // A successful request no longer needs its diagnostic logs.
+    sink.discard({ context: { requestId } });
+  } else {
+    // Emit diagnostic logs when an external failure signal arrives.
+    sink.flush({ context: { requestId } });
+  }
+}
+~~~~
+
+A context-only selector applies to every category for that context.  Every key
+configured in `~FingersCrossedOptions.isolateByContext` must be present in the
+selector.  Adding `category` narrows the operation using the configured
+category isolation matcher.  Omit the selector to flush or discard every
+buffer.
+
+Both methods release buffered and triggered state.  Calling either method for
+an already-triggered isolation resets it, so the next record with the same key
+is buffered again.
+
 ### Buffer management
 
 The fingers crossed sink provides several mechanisms to manage memory usage

packages/logtape/src/mod.ts

@@ -69,7 +69,10 @@ export {
   type AsyncSink,
   type ConsoleSinkOptions,
   fingersCrossed,
+  type FingersCrossedBufferAction,
+  type FingersCrossedBufferSelector,
   type FingersCrossedOptions,
+  type FingersCrossedSink,
   fromAsyncSink,
   getConsoleSink,
   getStreamSink,