@remnic/core 1.1.0 → 1.1.1

package/dist/access-service.d.ts

@@ -1,17 +1,24 @@
+import './storage.js';
+import './recall-xray.js';
+import './recall-explain-renderer.js';
 import './types.js';
+import './recall-audit-anomaly.js';
 import './explicit-capture.js';
+import './cross-namespace-budget.js';
 import './memory-projection-store-DeSXPh1j.js';
+export { g as ENGRAM_ACCESS_WRITE_SCHEMA_VERSION, h as EngramAccessBriefingRequest, i as EngramAccessBriefingResponse, j as EngramAccessDaySummaryRequest, k as EngramAccessEntityListResponse, l as EngramAccessEntityResponse, m as EngramAccessEntitySummary, n as EngramAccessHealthResponse, a as EngramAccessInputError, o as EngramAccessLcmSearchRequest, p as EngramAccessLcmSearchResponse, q as EngramAccessLcmStatusResponse, r as EngramAccessMaintenanceResponse, s as EngramAccessMemoryBrowseRequest, t as EngramAccessMemoryBrowseResponse, u as EngramAccessMemoryRecord, v as EngramAccessMemoryResponse, w as EngramAccessMemoryStoreRequest, x as EngramAccessMemorySummary, y as EngramAccessObserveRequest, z as EngramAccessObserveResponse, A as EngramAccessQualityResponse, B as EngramAccessRecallExplainRequest, C as EngramAccessRecallExplainResponse, D as EngramAccessRecallRequest, F as EngramAccessRecallResponse, G as EngramAccessReviewDispositionRequest, H as EngramAccessReviewDispositionResponse, I as EngramAccessReviewQueueResponse, E as EngramAccessService, J as EngramAccessSetCodingContextRequest, K as EngramAccessSuggestionSubmitRequest, L as EngramAccessTimelineResponse, M as EngramAccessTrustZoneBrowseRequest, N as EngramAccessTrustZoneBrowseResponse, O as EngramAccessTrustZoneDemoSeedRequest, Q as EngramAccessTrustZoneDemoSeedResponse, R as EngramAccessTrustZonePromoteRequest, S as EngramAccessTrustZonePromoteResponse, T as EngramAccessTrustZoneRecordSummary, U as EngramAccessTrustZoneStatusResponse, V as EngramAccessWriteEnvelope, W as EngramAccessWriteResponse } from './access-service-Br8ZydTK.js';
 import './recall-state.js';
-import './orchestrator-DRYA6_lW.js';
-import './storage.js';
+import './orchestrator-CmJ-NTdJ.js';
 import './trust-zones.js';
 import './local-llm.js';
 import './fallback-llm.js';
-export { f as ENGRAM_ACCESS_WRITE_SCHEMA_VERSION, g as EngramAccessBriefingRequest, h as EngramAccessBriefingResponse, i as EngramAccessDaySummaryRequest, j as EngramAccessEntityListResponse, k as EngramAccessEntityResponse, l as EngramAccessEntitySummary, m as EngramAccessHealthResponse, a as EngramAccessInputError, n as EngramAccessLcmSearchRequest, o as EngramAccessLcmSearchResponse, p as EngramAccessLcmStatusResponse, q as EngramAccessMaintenanceResponse, r as EngramAccessMemoryBrowseRequest, s as EngramAccessMemoryBrowseResponse, t as EngramAccessMemoryRecord, u as EngramAccessMemoryResponse, v as EngramAccessMemoryStoreRequest, w as EngramAccessMemorySummary, x as EngramAccessObserveRequest, y as EngramAccessObserveResponse, z as EngramAccessQualityResponse, A as EngramAccessRecallExplainRequest, B as EngramAccessRecallExplainResponse, C as EngramAccessRecallRequest, D as EngramAccessRecallResponse, F as EngramAccessReviewDispositionRequest, G as EngramAccessReviewDispositionResponse, H as EngramAccessReviewQueueResponse, E as EngramAccessService, I as EngramAccessSuggestionSubmitRequest, J as EngramAccessTimelineResponse, K as EngramAccessTrustZoneBrowseRequest, L as EngramAccessTrustZoneBrowseResponse, M as EngramAccessTrustZoneDemoSeedRequest, N as EngramAccessTrustZoneDemoSeedResponse, O as EngramAccessTrustZonePromoteRequest, P as EngramAccessTrustZonePromoteResponse, Q as EngramAccessTrustZoneRecordSummary, R as EngramAccessTrustZoneStatusResponse, T as EngramAccessWriteEnvelope, U as EngramAccessWriteResponse } from './access-service-HmO1Trrx.js';
-import './buffer.js';
+import './memory-worth-outcomes.js';
 import './page-versioning.js';
+import './consolidation-operator.js';
 import 'better-sqlite3';
-import './port-C1GZFv8h.js';
+import './recall-audit.js';
+import './buffer.js';
+import './port-BADbLZU5.js';
 import './transcript.js';
 import './session-integrity.js';
 import './summarizer.js';
@@ -20,7 +27,7 @@ import './relevance.js';
 import './negative.js';
 import './session-observer-state.js';
 import './embedding-fallback.js';
-import './semantic-consolidation-DrvSYRdB.js';
+import './semantic-consolidation-CxJU6MJk.js';
 import './codex-materialize-CQlLTzke.js';
 import './logger.js';
 import 'zod';

package/dist/access-service.js

@@ -2,34 +2,42 @@ import {
   ENGRAM_ACCESS_WRITE_SCHEMA_VERSION,
   EngramAccessInputError,
   EngramAccessService
-} from "./chunk-MVTHXUBX.js";
-import "./chunk-ITRLGI2T.js";
+} from "./chunk-GKFXUTJ2.js";
+import "./chunk-ZAIM4TUE.js";
+import "./chunk-SOBJ6NEY.js";
+import "./chunk-3OGMS3PE.js";
 import "./chunk-EQINRHYR.js";
-import "./chunk-QDYXG4CS.js";
-import "./chunk-QNJMBKFK.js";
+import "./chunk-EIR5VLIH.js";
 import "./chunk-EEQLFRUM.js";
 import "./chunk-QDW3E4RD.js";
-import "./chunk-4NRAJUDS.js";
+import "./chunk-3FPTCC3Z.js";
+import "./chunk-2LGMW3DJ.js";
+import "./chunk-GDFS42HT.js";
+import "./chunk-RBBWYEFJ.js";
 import "./chunk-DT5TVLJE.js";
 import "./chunk-N5AKDXAI.js";
 import "./chunk-TBBDFYXW.js";
-import "./chunk-DGXUHMOV.js";
-import "./chunk-LPSF4OQH.js";
-import "./chunk-XKECPATV.js";
-import "./chunk-4LACOVZX.js";
-import "./chunk-GV6NLQ4X.js";
-import "./chunk-3WHVNEN7.js";
+import "./chunk-WVVA7F5A.js";
+import "./chunk-F5VP6YCB.js";
+import "./chunk-LTCGGW2D.js";
 import "./chunk-4KAN3GZ3.js";
-import "./chunk-6ZH4TU6I.js";
-import "./chunk-SCU65EZI.js";
-import "./chunk-BOUYNNYD.js";
 import "./chunk-6PFRXT4K.js";
 import "./chunk-TP4FZJIZ.js";
+import "./chunk-SCU65EZI.js";
+import "./chunk-BOUYNNYD.js";
 import "./chunk-DM2T26WE.js";
 import "./chunk-QSVPYQPG.js";
 import "./chunk-M62O4P4T.js";
 import "./chunk-4DJQYKMN.js";
+import "./chunk-X6GF3FX2.js";
+import "./chunk-FAAFWE4G.js";
 import "./chunk-2ODBA7MQ.js";
+import "./chunk-DGXUHMOV.js";
+import "./chunk-LPSF4OQH.js";
+import "./chunk-TVVEYCNW.js";
+import "./chunk-RFYAYKTD.js";
+import "./chunk-LBLXEFWK.js";
+import "./chunk-XKECPATV.js";
 export {
   ENGRAM_ACCESS_WRITE_SCHEMA_VERSION,
   EngramAccessInputError,

package/dist/bootstrap.d.ts

@@ -1,22 +1,25 @@
 import { PluginConfig } from './types.js';
-import { O as Orchestrator } from './orchestrator-DRYA6_lW.js';
+import { O as Orchestrator } from './orchestrator-CmJ-NTdJ.js';
 import './buffer.js';
 import './storage.js';
 import './page-versioning.js';
+import './consolidation-operator.js';
 import './memory-projection-store-DeSXPh1j.js';
 import 'better-sqlite3';
-import './port-C1GZFv8h.js';
+import './port-BADbLZU5.js';
 import './transcript.js';
 import './session-integrity.js';
 import './summarizer.js';
 import './model-registry.js';
 import './local-llm.js';
+import './fallback-llm.js';
 import './relevance.js';
 import './negative.js';
 import './recall-state.js';
+import './recall-xray.js';
 import './session-observer-state.js';
 import './embedding-fallback.js';
-import './semantic-consolidation-DrvSYRdB.js';
+import './semantic-consolidation-CxJU6MJk.js';
 import './codex-materialize-CQlLTzke.js';
 import './logger.js';
 import 'zod';

package/dist/briefing.d.ts

@@ -1,6 +1,7 @@
 import { StorageManager } from './storage.js';
 import { BriefingSections, BriefingFollowup, BriefingFocus, CalendarSource, CalendarEvent, MemoryFile, BriefingActiveThread, BriefingResult, EntityFile, BriefingRecentEntity } from './types.js';
 import './page-versioning.js';
+import './consolidation-operator.js';
 import './memory-projection-store-DeSXPh1j.js';
 import 'better-sqlite3';
 

package/dist/briefing.js

@@ -16,19 +16,20 @@ import {
   renderBriefingMarkdown,
   resolveBriefingSaveDir,
   validateBriefingFormat
-} from "./chunk-4LACOVZX.js";
-import "./chunk-GV6NLQ4X.js";
-import "./chunk-3WHVNEN7.js";
+} from "./chunk-WVVA7F5A.js";
+import "./chunk-F5VP6YCB.js";
+import "./chunk-LTCGGW2D.js";
 import "./chunk-4KAN3GZ3.js";
-import "./chunk-6ZH4TU6I.js";
-import "./chunk-SCU65EZI.js";
-import "./chunk-BOUYNNYD.js";
 import "./chunk-6PFRXT4K.js";
 import "./chunk-TP4FZJIZ.js";
+import "./chunk-SCU65EZI.js";
+import "./chunk-BOUYNNYD.js";
 import "./chunk-DM2T26WE.js";
 import "./chunk-QSVPYQPG.js";
 import "./chunk-M62O4P4T.js";
 import "./chunk-4DJQYKMN.js";
+import "./chunk-X6GF3FX2.js";
+import "./chunk-FAAFWE4G.js";
 import "./chunk-2ODBA7MQ.js";
 export {
   BRIEFING_FOLLOWUP_DEFAULT_MODEL,

package/dist/buffer-surprise-report.d.ts

@@ -0,0 +1,70 @@
+import { BufferSurpriseEvent } from './types.js';
+
+/**
+ * Buffer-surprise telemetry report (issue #563 PR 3).
+ *
+ * Reads the append-only `state/buffer-surprise-ledger.jsonl` file written
+ * by `SmartBuffer` and summarizes the recent distribution of surprise
+ * scores for the Doctor surface. This module is intentionally standalone
+ * and pure — the only I/O is reading the ledger via the injected
+ * `readEvents` callback, so it can be exercised directly in tests
+ * without touching the filesystem.
+ *
+ * # Output shape
+ *
+ * `BufferSurpriseDistribution` has fields sized for a one-screen Doctor
+ * display:
+ *
+ *   - `count`            — rows considered in the summary window.
+ *   - `triggeredCount`   — rows whose `triggeredFlush === true`.
+ *   - `triggeredRate`    — `triggeredCount / count`, or `0` when empty.
+ *   - `mean`             — arithmetic mean of `surpriseScore`.
+ *   - `median`           — middle value (50th percentile).
+ *   - `p90`              — 90th percentile (tail of novelty).
+ *   - `min`, `max`       — window extremes.
+ *   - `currentThreshold` — threshold from the MOST RECENT row, or `null`.
+ *
+ * All percentile math uses the nearest-rank method (no interpolation) so
+ * the report is stable across small windows.
+ *
+ * # Why a pure function + injected reader?
+ *
+ * The Doctor surface is exercised both at runtime (through the CLI and
+ * gateway tools) and in tests. A pure distribution helper fed from an
+ * arbitrary `readEvents` callback keeps the report logic trivially
+ * testable without spinning up a real `StorageManager`.
+ */
+
+interface BufferSurpriseDistribution {
+    count: number;
+    triggeredCount: number;
+    triggeredRate: number;
+    mean: number;
+    median: number;
+    p90: number;
+    min: number;
+    max: number;
+    currentThreshold: number | null;
+}
+interface BufferSurpriseReportOptions {
+    /**
+     * Maximum number of recent rows to include. Defaults to `200` — large
+     * enough to see a distribution, small enough to read in one sitting.
+     */
+    limit?: number;
+    /** Lower-bound ISO timestamp; rows at or before this are excluded. */
+    since?: string;
+}
+/**
+ * Reader callback shape. The helper does not want to know whether the
+ * rows come from a file, a queue, or an in-memory buffer.
+ */
+type BufferSurpriseReader = (options: BufferSurpriseReportOptions) => Promise<readonly BufferSurpriseEvent[]>;
+/**
+ * Summarize the recent buffer-surprise distribution. Returns the empty
+ * distribution shape when the ledger has no applicable rows — callers can
+ * detect this via `count === 0` and render "no data yet".
+ */
+declare function reportBufferSurpriseDistribution(readEvents: BufferSurpriseReader, options?: BufferSurpriseReportOptions): Promise<BufferSurpriseDistribution>;
+
+export { type BufferSurpriseDistribution, type BufferSurpriseReader, type BufferSurpriseReportOptions, reportBufferSurpriseDistribution };

package/dist/buffer-surprise-report.js

@@ -0,0 +1,7 @@
+import {
+  reportBufferSurpriseDistribution
+} from "./chunk-ASAITVLA.js";
+export {
+  reportBufferSurpriseDistribution
+};
+//# sourceMappingURL=buffer-surprise-report.js.map

package/dist/buffer-surprise-report.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/buffer-surprise.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Surprise helper — D-MEM-style novelty score for a turn against recent memories.
+ *
+ * Used (eventually, in a follow-up PR) by the smart buffer as an additive flush
+ * trigger: a turn that is semantically far from everything already in memory is
+ * "surprising" and worth extracting immediately, even if turn-count and signal
+ * heuristics would otherwise keep buffering.
+ *
+ * This module intentionally contains ONLY the pure scoring function. Wiring
+ * into the buffer, configuration flags, telemetry, and benchmark work live in
+ * later PRs (see issue #563). Keeping the helper in a sibling file instead of
+ * inside `buffer.ts` keeps the buffer module focused and makes the eventual
+ * integration a small, reviewable change.
+ *
+ * # Formula
+ *
+ * Given an input `turn` and a list of `recentMemories`:
+ *
+ * 1. Embed the turn and every candidate memory via the caller-provided
+ *    `embedFn`.
+ * 2. For each candidate, compute cosine similarity `cos(turn, candidate)` in
+ *    `[0, 1]` (negative cosines are clamped to 0 — "opposite directions"
+ *    is treated as maximally diverse, consistent with `recall-mmr.ts`).
+ * 3. Keep the top-`k` *highest* similarities (the turn's nearest neighbors).
+ * 4. Average those top-`k` similarities → `nearestSim ∈ [0, 1]`.
+ * 5. Return `1 − nearestSim` as the surprise score.
+ *
+ * Intuition: a turn that is close to at least one recent memory has a high
+ * `nearestSim` and therefore a *low* surprise (near 0 = redundant). A turn
+ * that is far from all of its k nearest neighbors has a low `nearestSim` and
+ * therefore a *high* surprise (near 1 = novel).
+ *
+ * Using the top-k average instead of a single nearest neighbor makes the
+ * score less sensitive to one outlier duplicate (e.g. an exact restatement of
+ * a stale fact). `k=1` reduces to pure nearest-neighbor distance.
+ *
+ * # Edge cases
+ *
+ * - `recentMemories` empty → returns `1.0` (maximally surprising). There is
+ *   nothing to compare against, so the turn cannot be redundant.
+ * - `k` default is `5`. It is clamped to `[1, recentMemories.length]` so that
+ *   small corpora still produce a meaningful score (e.g. 3 memories with
+ *   `k=5` behaves the same as `k=3`).
+ * - Zero-norm embeddings (all zeros) contribute similarity `0` (they cannot
+ *   be "close" to anything), which is treated as maximally surprising for
+ *   that pair. The rest of the corpus is scored normally.
+ * - Embedding-length mismatches between the turn and a candidate are treated
+ *   as similarity `0` for that pair. We do not silently truncate to the
+ *   shorter vector because that would hide a real configuration bug.
+ * - `embedFn` rejection is allowed to propagate. The caller decides whether
+ *   to catch, fall back, or fail the flush decision — this helper has no
+ *   opinion beyond the pure score.
+ *
+ * # Purity
+ *
+ * No I/O, no hidden globals. Given the same inputs and the same `embedFn`,
+ * the output is deterministic.
+ */
+/** Minimal shape of a recent memory passed to `computeSurprise`. */
+interface RecentMemoryLike {
+    /** Stable identifier. Only used for debug/logging; not part of the score. */
+    readonly id: string;
+    /** Text to embed and compare against the incoming turn. */
+    readonly content: string;
+}
+/** Options accepted by `computeSurprise`. */
+interface ComputeSurpriseOptions {
+    /**
+     * Embedding function. Called once for the turn and once per candidate
+     * memory. Callers may wrap a provider client, a local model, or a
+     * deterministic hash for tests.
+     */
+    readonly embedFn: (text: string) => Promise<readonly number[]>;
+    /**
+     * Number of nearest neighbors to average over. Defaults to 5. Clamped to
+     * `[1, recentMemories.length]`.
+     */
+    readonly k?: number;
+}
+/** Default k (top nearest neighbors to average). */
+declare const DEFAULT_SURPRISE_K = 5;
+/**
+ * Compute a surprise score in `[0, 1]` for `turn` against `recentMemories`.
+ *
+ * See the module-level docstring for the exact formula, edge cases, and
+ * purity guarantees.
+ *
+ * @param turn           The incoming turn text (caller is responsible for
+ *                       stringifying structured turn content — this helper
+ *                       only needs the text to embed).
+ * @param recentMemories Candidate memories to compare against.
+ * @param options        `embedFn` (required) and optional `k` (defaults to 5).
+ * @returns A scalar in `[0, 1]`. `1.0` = maximally surprising / novel;
+ *          `0.0` = redundant with at least one recent memory.
+ */
+declare function computeSurprise(turn: string, recentMemories: readonly RecentMemoryLike[], options: ComputeSurpriseOptions): Promise<number>;
+
+export { type ComputeSurpriseOptions, DEFAULT_SURPRISE_K, type RecentMemoryLike, computeSurprise };

package/dist/buffer-surprise.js

@@ -0,0 +1,11 @@
+import {
+  DEFAULT_SURPRISE_K,
+  computeSurprise
+} from "./chunk-5JRF2PZA.js";
+import "./chunk-KVE7R4CG.js";
+import "./chunk-4WMCPJWX.js";
+export {
+  DEFAULT_SURPRISE_K,
+  computeSurprise
+};
+//# sourceMappingURL=buffer-surprise.js.map

package/dist/buffer-surprise.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/buffer.d.ts

@@ -1,16 +1,55 @@
 import { StorageManager } from './storage.js';
 import { PluginConfig, BufferTurn } from './types.js';
 import './page-versioning.js';
+import './consolidation-operator.js';
 import './memory-projection-store-DeSXPh1j.js';
 import 'better-sqlite3';
 
 type TriggerDecision = "extract_now" | "extract_batch" | "keep_buffering";
+/**
+ * Optional surprise probe injected into `SmartBuffer`.
+ *
+ * Computes a D-MEM-style novelty score in `[0, 1]` for an incoming turn.
+ * The buffer treats the probe as purely additive: if it is not provided, if
+ * the feature flag is off, or if the probe throws/times out, the buffer
+ * falls back to the existing signal/turn-count/time triggers unchanged.
+ *
+ * Callers are responsible for sampling recent memories and passing them
+ * through the embedding pipeline — the buffer does not want to know about
+ * storage, embeddings, or QMD.
+ *
+ * @param bufferKey Identifier for the active buffer (session/thread).
+ * @param turn      The incoming turn whose novelty is being scored.
+ * @param recentTurns Turns already buffered for this key (most recent first
+ *                    is NOT guaranteed — treat as unordered corpus).
+ * @returns A surprise score in `[0, 1]`, or `null` if no score could be
+ *          produced (e.g. empty corpus, probe declined to embed).
+ */
+interface BufferSurpriseProbe {
+    scoreTurn(bufferKey: string, turn: BufferTurn, recentTurns: readonly BufferTurn[]): Promise<number | null>;
+}
 declare class SmartBuffer {
     private readonly config;
     private readonly storage;
     private state;
     private loaded;
-    constructor(config: PluginConfig, storage: StorageManager);
+    private readonly surpriseProbe;
+    /**
+     * Serialized write chain for `BUFFER_SURPRISE` telemetry events.
+     *
+     * The telemetry path is fire-and-forget (`addTurn` does not await the
+     * ledger append), but multiple concurrent appends would still settle
+     * out of order under variable filesystem latency. The report path
+     * assumes chronological ordering — it slices the tail of the ledger
+     * and treats the most recent entry as the current threshold in force.
+     * Chaining ensures each append only runs after the previous settles,
+     * preserving wall-clock order.
+     *
+     * We include a `.catch` on every link so a rejected append does not
+     * poison the chain (CLAUDE.md rule #40).
+     */
+    private surpriseTelemetryWriteChain;
+    constructor(config: PluginConfig, storage: StorageManager, surpriseProbe?: BufferSurpriseProbe | null);
     private entryFor;
     private peekEntry;
     private normalizeState;
@@ -25,12 +64,71 @@ declare class SmartBuffer {
     resetToEmpty(): void;
     save(): Promise<void>;
     addTurn(bufferKey: string, turn: BufferTurn): Promise<TriggerDecision>;
+    /**
+     * Enqueue a telemetry append on the serialized write chain.
+     *
+     * The chain is a classic `writeChain = writeChain.then(fn).catch(...)`
+     * — each link waits for the previous to settle before its append
+     * starts, so out-of-order chronology cannot happen even under
+     * variable filesystem latency. We always attach `.catch` so one
+     * rejection does not poison the chain for the rest of the session
+     * (CLAUDE.md rule #40). The error is logged through
+     * `emitSurpriseEventSafe` itself, which swallows its own rejections.
+     *
+     * Public surface is deliberately narrow — only `addTurn` should call
+     * this, so the surprise telemetry path stays centralized.
+     */
+    private queueSurpriseTelemetryWrite;
+    /**
+     * Append a single `BUFFER_SURPRISE` telemetry row (issue #563 PR 3).
+     *
+     * Deliberately swallows write errors: the buffer must never fail to
+     * record a turn because the observation ledger is read-only, out of
+     * disk, or otherwise unhappy. The log line at debug lets operators
+     * confirm the path fired without polluting the error channel.
+     */
+    private emitSurpriseEventSafe;
+    /**
+     * Invoke the injected surprise probe defensively. Any error (probe throws,
+     * embedder unavailable, timeout) is swallowed and logged at debug: the
+     * surprise path must never crash the happy-path trigger evaluation. A
+     * `null` return indicates "no score available, fall through to existing
+     * triggers".
+     */
+    private computeSurpriseSafe;
     private evaluate;
     getTurns(bufferKey?: string): BufferTurn[];
+    /**
+     * Retain a subset of the current turns across `clearAfterExtraction` so a
+     * future extraction pass sees the context behind a deferred candidate
+     * (issue #562, PR 2). Callers pass the turns that were seen during the
+     * current extraction; the buffer keeps the tail (latest `max` turns) as
+     * the retention window. Passing an empty array or `max <= 0` clears the
+     * retention slot instead.
+     */
+    retainDeferredTurns(bufferKey: string, turns: BufferTurn[], max?: number): Promise<void>;
+    /**
+     * Return the current retention window (issue #562, PR 2). Primarily for
+     * tests and diagnostics.
+     */
+    getRetainedDeferredTurns(bufferKey?: string): BufferTurn[];
     findBufferKeyForSession(sessionKey: string): Promise<string | null>;
     findBufferKeysForSession(sessionKey: string): Promise<string[]>;
     clearAfterExtraction(bufferKey?: string): Promise<void>;
     getExtractionCount(bufferKey?: string): number;
+    /**
+     * Await any pending `BUFFER_SURPRISE` telemetry writes.
+     *
+     * The telemetry path is fire-and-forget from the hot path's point of
+     * view, but tests and before-exit hooks sometimes need to make sure
+     * the ledger has been flushed before they assert on its contents or
+     * close the process. This method resolves once the current chain
+     * head has settled; new writes scheduled after this call return a
+     * separate, later settlement.
+     *
+     * Never throws — the chain already catches its own rejections.
+     */
+    flushSurpriseTelemetry(): Promise<void>;
 }
 
-export { SmartBuffer, type TriggerDecision };
+export { type BufferSurpriseProbe, SmartBuffer, type TriggerDecision };

package/dist/buffer.js

@@ -1,6 +1,6 @@
 import {
   SmartBuffer
-} from "./chunk-UVJFDP7P.js";
+} from "./chunk-JBMSGZEQ.js";
 import "./chunk-XYIK4LF6.js";
 import "./chunk-2ODBA7MQ.js";
 export {

package/dist/calibration.js

@@ -1,17 +1,17 @@
 import {
   FallbackLlmClient
-} from "./chunk-44ICJRF3.js";
+} from "./chunk-3GXCSUXR.js";
 import "./chunk-XZ2TIKGC.js";
-import "./chunk-Y27UJK6V.js";
 import "./chunk-ODWDQNRE.js";
+import "./chunk-Y27UJK6V.js";
 import "./chunk-UZB5KHKX.js";
 import "./chunk-MARWOCVP.js";
-import {
-  listJsonFiles
-} from "./chunk-LPSF4OQH.js";
 import {
   log
 } from "./chunk-2ODBA7MQ.js";
+import {
+  listJsonFiles
+} from "./chunk-LPSF4OQH.js";
 
 // src/calibration.ts
 import { createHash } from "crypto";

package/dist/causal-behavior.js

@@ -1,11 +1,14 @@
 import {
   readChainIndex,
   resolveChainsDir
-} from "./chunk-3QFQGRHO.js";
+} from "./chunk-XMHBH5H6.js";
 import "./chunk-URB2WSKZ.js";
 import {
   normalizeRecallTokens
 } from "./chunk-DT5TVLJE.js";
+import {
+  log
+} from "./chunk-2ODBA7MQ.js";
 import {
   isRecord
 } from "./chunk-DGXUHMOV.js";
@@ -13,9 +16,6 @@ import {
   listJsonFiles,
   readJsonFile
 } from "./chunk-LPSF4OQH.js";
-import {
-  log
-} from "./chunk-2ODBA7MQ.js";
 
 // src/causal-behavior.ts
 import path from "path";

package/dist/causal-chain.js

@@ -6,12 +6,12 @@ import {
   stitchCausalChain,
   validateCausalEdge,
   writeChainIndex
-} from "./chunk-3QFQGRHO.js";
+} from "./chunk-XMHBH5H6.js";
 import "./chunk-URB2WSKZ.js";
 import "./chunk-DT5TVLJE.js";
+import "./chunk-2ODBA7MQ.js";
 import "./chunk-DGXUHMOV.js";
 import "./chunk-LPSF4OQH.js";
-import "./chunk-2ODBA7MQ.js";
 export {
   makeEdgeId,
   readChainIndex,

package/dist/causal-consolidation.js

@@ -1,44 +1,45 @@
 import {
   readChainIndex,
   resolveChainsDir
-} from "./chunk-3QFQGRHO.js";
+} from "./chunk-XMHBH5H6.js";
 import {
   buildExtensionsBlockForConsolidation,
   runPostConsolidationMaterialize
-} from "./chunk-SYUK3VLY.js";
+} from "./chunk-BGJGXLZ7.js";
 import "./chunk-EJI5XIBB.js";
 import {
   FallbackLlmClient
-} from "./chunk-44ICJRF3.js";
+} from "./chunk-3GXCSUXR.js";
 import "./chunk-XZ2TIKGC.js";
-import "./chunk-Y27UJK6V.js";
 import "./chunk-ODWDQNRE.js";
+import "./chunk-Y27UJK6V.js";
 import "./chunk-UZB5KHKX.js";
 import "./chunk-URB2WSKZ.js";
 import "./chunk-MARWOCVP.js";
 import "./chunk-DT5TVLJE.js";
-import {
-  isRecord
-} from "./chunk-DGXUHMOV.js";
-import {
-  listJsonFiles,
-  readJsonFile
-} from "./chunk-LPSF4OQH.js";
-import "./chunk-GV6NLQ4X.js";
-import "./chunk-3WHVNEN7.js";
+import "./chunk-F5VP6YCB.js";
+import "./chunk-LTCGGW2D.js";
 import "./chunk-4KAN3GZ3.js";
-import "./chunk-6ZH4TU6I.js";
-import "./chunk-SCU65EZI.js";
-import "./chunk-BOUYNNYD.js";
 import "./chunk-6PFRXT4K.js";
 import "./chunk-TP4FZJIZ.js";
+import "./chunk-SCU65EZI.js";
+import "./chunk-BOUYNNYD.js";
 import "./chunk-DM2T26WE.js";
 import "./chunk-QSVPYQPG.js";
 import "./chunk-M62O4P4T.js";
 import "./chunk-4DJQYKMN.js";
+import "./chunk-X6GF3FX2.js";
+import "./chunk-FAAFWE4G.js";
 import {
   log
 } from "./chunk-2ODBA7MQ.js";
+import {
+  isRecord
+} from "./chunk-DGXUHMOV.js";
+import {
+  listJsonFiles,
+  readJsonFile
+} from "./chunk-LPSF4OQH.js";
 
 // src/causal-consolidation.ts
 import { createHash } from "crypto";