@remnic/core 9.30.1 → 9.31.0

package/src/local-llm.ts

@@ -8,6 +8,13 @@ import { mergeEnv, readEnvVar } from "./runtime/env.js";
 import { resolveLocalLlmCapabilities } from "./capabilities.js";
 import { resolvePipelineProcessingCapabilities } from "./capabilities.js";
 import { ChatTransport } from "./local-llm-transport.js";
+import {
+  extractNonRecoverableBackendReason,
+  extractNonRecoverableBackendReasonFromErrorText,
+  isAbortError,
+  normalizeBackendTripReason,
+  waitForRetryBackoff,
+} from "./local-llm-helpers.js";
 
 /** Trim trailing slash characters without backtracking regex. */
 function trimTrailingSlashes(s: string): string {
@@ -223,6 +230,7 @@ interface LocalLlmChatCompletionOptions {
   forceDisableThinking?: boolean;
   disableThinking?: boolean;
   priority?: LocalLlmRequestPriority;
+  signal?: AbortSignal;
 }
 
 interface LocalLlmQueuedRequest {
@@ -304,15 +312,6 @@ export class LocalLlmClient {
     return headers;
   }
 
-  private isAbortError(err: unknown): boolean {
-    if (!err || typeof err !== "object") return false;
-    const maybe = err as { name?: string; message?: string };
-    return (
-      maybe.name === "AbortError" ||
-      maybe.message === "This operation was aborted" ||
-      maybe.message === "The operation was aborted"
-    );
-  }
 
   /**
    * Set the ModelRegistry for caching detected capabilities
@@ -356,7 +355,7 @@ export class LocalLlmClient {
   }
 
   private markBackendUnavailable(reason: string, durationMs: number): void {
-    const normalizedReason = this.normalizeBackendTripReason(reason);
+    const normalizedReason = normalizeBackendTripReason(reason);
     if (durationMs > 0) {
       const untilMs = Date.now() + durationMs;
       this.getGlobalBackendState().set(this.getBackendKey(), { untilMs, reason: normalizedReason });
@@ -370,29 +369,6 @@ export class LocalLlmClient {
     );
   }
 
-  private extractNonRecoverableBackendReason(reason: string): string | null {
-    const match = reason.match(
-      /Failed to load model|Library not loaded|different Team IDs|code signature|llm_engine_mlx_amphibian/i,
-    );
-    return match?.[0] ?? null;
-  }
-
-  private extractNonRecoverableBackendReasonFromErrorText(errorText: string): string | null {
-    const directReason = this.extractNonRecoverableBackendReason(errorText);
-    if (directReason) return directReason;
-    try {
-      const parsed = JSON.parse(errorText) as { error?: { message?: string } };
-      return this.extractNonRecoverableBackendReason(parsed?.error?.message ?? "");
-    } catch {
-      return null;
-    }
-  }
-
-  private normalizeBackendTripReason(reason: string): string {
-    const cleaned = reason.replace(/\s+/g, " ").replace(/^[-:–—\s]+/, "").trim();
-    if (!cleaned) return "unknown local backend failure";
-    return cleaned.length > 160 ? `${cleaned.slice(0, 157)}...` : cleaned;
-  }
 
   /**
    * Fetch with timeout for health checks
@@ -401,13 +377,15 @@ export class LocalLlmClient {
     url: string,
     timeoutMs: number = 2000,
     headers?: Record<string, string>,
+    signal?: AbortSignal,
   ): Promise<{ ok: boolean; data: unknown; status: number | null }> {
     const controller = new AbortController();
+    const requestSignal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
     const timeout = setTimeout(() => controller.abort(), timeoutMs);
 
     try {
       const response = await fetch(url, {
-        signal: controller.signal,
+        signal: requestSignal,
         headers: this.buildRequestHeaders({ Accept: "application/json", ...(headers ?? {}) }),
       });
       clearTimeout(timeout);
@@ -430,10 +408,13 @@ export class LocalLlmClient {
 
   private async probeLmStudioNativeModels(
     probeBaseUrl: string,
+    signal?: AbortSignal,
   ): Promise<{ matched: boolean; unauthorized: boolean }> {
     let unauthorized = false;
     for (const endpoint of ["/api/v1/models", "/api/v0/models"]) {
-      const probe = await this.fetchWithTimeout(`${probeBaseUrl}${endpoint}`);
+      if (signal?.aborted) return { matched: false, unauthorized };
+      const probe = await this.fetchWithTimeout(`${probeBaseUrl}${endpoint}`, 2000, undefined, signal);
+      if (signal?.aborted) return { matched: false, unauthorized };
       if (probe.ok && isLmStudioNativeModelsResponse(probe.data)) {
         return { matched: true, unauthorized };
       }
@@ -448,7 +429,8 @@ export class LocalLlmClient {
    * Check if local LLM is available
    * Uses 127.0.0.1 instead of localhost to avoid DNS issues (consistent with tactician)
    */
-  async checkAvailability(): Promise<boolean> {
+  async checkAvailability(signal?: AbortSignal): Promise<boolean> {
+    if (signal?.aborted) return false;
     // Cache health check results for 1 minute
     const now = Date.now();
     const trippedState = this.getTrippedBackendState(now);
@@ -474,14 +456,17 @@ export class LocalLlmClient {
     let sawUnauthorizedProbe = false;
 
     // Try to detect which server type is running
+    if (signal?.aborted) return false;
     for (const serverConfig of orderedLocalServers(configuredBaseUrl)) {
       const healthUrl = `${probeBaseUrl}${serverConfig.healthEndpoint}`;
       log.debug(`checking ${serverConfig.type} at ${healthUrl}`);
 
-      const result = await this.fetchWithTimeout(healthUrl);
+      const result = await this.fetchWithTimeout(healthUrl, 2000, undefined, signal);
+      if (signal?.aborted) return false;
       if (result.ok && serverConfig.detectFn(result.data)) {
         if (serverConfig.type === "mlx") {
-          const lmStudioProbe = await this.probeLmStudioNativeModels(probeBaseUrl);
+          const lmStudioProbe = await this.probeLmStudioNativeModels(probeBaseUrl, signal);
+          if (signal?.aborted) return false;
           if (lmStudioProbe.unauthorized) {
             sawUnauthorizedProbe = true;
           }
@@ -495,7 +480,8 @@ export class LocalLlmClient {
         }
         if (serverConfig.type === "llamacpp") {
           let sawLlamaCppSignal = false;
-          const propsProbe = await this.fetchWithTimeout(`${probeBaseUrl}/props`);
+          const propsProbe = await this.fetchWithTimeout(`${probeBaseUrl}/props`, 2000, undefined, signal);
+          if (signal?.aborted) return false;
           if (propsProbe.ok && isLlamaCppPropsResponse(propsProbe.data)) {
             sawLlamaCppSignal = true;
           }
@@ -504,7 +490,8 @@ export class LocalLlmClient {
           }
 
           const modelsUrl = `${probeBaseUrl}${serverConfig.modelsEndpoint}`;
-          const modelsProbe = await this.fetchWithTimeout(modelsUrl);
+          const modelsProbe = await this.fetchWithTimeout(modelsUrl, 2000, undefined, signal);
+          if (signal?.aborted) return false;
           if (modelsProbe.ok && isLlamaCppModelsResponse(modelsProbe.data)) {
             sawLlamaCppSignal = true;
           }
@@ -530,11 +517,13 @@ export class LocalLlmClient {
         sawUnauthorizedProbe = true;
       }
     }
+    if (signal?.aborted) return false;
 
     // Generic check if specific detection failed
     try {
       const modelsUrl = `${probeBaseUrl}/v1/models`;
-      const result = await this.fetchWithTimeout(modelsUrl);
+      const result = await this.fetchWithTimeout(modelsUrl, 2000, undefined, signal);
+      if (signal?.aborted) return false;
       if (result.ok) {
         this.isAvailable = true;
         this.detectedType = "generic";
@@ -903,6 +892,10 @@ export class LocalLlmClient {
 
   private async runQueuedRequest(next: LocalLlmQueuedRequest): Promise<void> {
     try {
+      if (next.options.signal?.aborted) {
+        next.resolve(null);
+        return;
+      }
       const remainingCooldownMs = this.remainingCooldownMs();
       if (remainingCooldownMs > 0) {
         const additionalDropped = this.failOpenQueuedRequestsForCooldown();
@@ -949,7 +942,8 @@ export class LocalLlmClient {
     }
 
     try {
-      const isAvailable = await this.checkAvailability();
+      if (options.signal?.aborted) return null;
+      const isAvailable = await this.checkAvailability(options.signal);
       if (!isAvailable) {
         log.debug(
           `local LLM: checkAvailability returned false for ${this.config.localLlmUrl}`,
@@ -1040,6 +1034,16 @@ export class LocalLlmClient {
       let lastAbortError: Error | null = null;
       for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
         const attemptAbort = new AbortController();
+        const onCallerAbort = (): void => {
+          attemptAbort.abort(options.signal?.reason);
+        };
+        if (options.signal) {
+          if (options.signal.aborted) {
+            onCallerAbort();
+          } else {
+            options.signal.addEventListener("abort", onCallerAbort, { once: true });
+          }
+        }
         const attemptTimeout = setTimeout(() => attemptAbort.abort(), effectiveTimeoutMs);
         try {
           response = await this.chatTransport.post({
@@ -1052,19 +1056,20 @@ export class LocalLlmClient {
             budgetMs: this.config.localLlmTimeoutMs,
           });
         } catch (err) {
-          if (!this.isAbortError(err)) throw err;
+          if (!isAbortError(err)) throw err;
           lastAbortError = err instanceof Error ? err : new Error(String(err));
-          if (attempt < maxAttempts) {
-            const backoffMs = this.config.localLlmRetryBackoffMs * attempt;
-            log.warn(
-              `local LLM request aborted: op=${operation} attempt=${attempt}/${maxAttempts} timeoutMs=${effectiveTimeoutMs} model=${this.config.localLlmModel}; retrying after ${backoffMs}ms`,
-            );
-            await new Promise((resolve) => setTimeout(resolve, backoffMs));
-            continue;
+          if (options.signal?.aborted || attempt >= maxAttempts) {
+            break;
           }
-          break;
+          const backoffMs = this.config.localLlmRetryBackoffMs * attempt;
+          log.warn(
+            `local LLM request aborted: op=${operation} attempt=${attempt}/${maxAttempts} timeoutMs=${effectiveTimeoutMs} model=${this.config.localLlmModel}; retrying after ${backoffMs}ms`,
+          );
+          if (!(await waitForRetryBackoff(backoffMs, options.signal))) return null;
+          continue;
         } finally {
           clearTimeout(attemptTimeout);
+          options.signal?.removeEventListener("abort", onCallerAbort);
         }
 
         if (response.ok) break;
@@ -1072,7 +1077,7 @@ export class LocalLlmClient {
           try {
             const errorText = await response.clone().text();
             const nonRecoverableReason =
-              this.extractNonRecoverableBackendReasonFromErrorText(errorText);
+              extractNonRecoverableBackendReasonFromErrorText(errorText);
             if (nonRecoverableReason) {
               this.markBackendUnavailable(
                 nonRecoverableReason,
@@ -1091,12 +1096,11 @@ export class LocalLlmClient {
         log.warn(
           `local LLM request got ${response.status}; retrying (attempt ${attempt + 1}/${maxAttempts}) after ${backoffMs}ms`,
         );
-        await new Promise((resolve) => setTimeout(resolve, backoffMs));
+        if (!(await waitForRetryBackoff(backoffMs, options.signal))) return null;
       }
       log.debug(
         `local LLM: received response, status=${response?.status}, ok=${response?.ok}`,
       );
-
       if (!response) {
         if (lastAbortError) {
           log.warn(
@@ -1131,8 +1135,8 @@ export class LocalLlmClient {
           `(op=${operation}, model=${this.config.localLlmModel}, url=${chatUrl}, promptChars=${promptChars}, maxTokens=${requestBody.max_tokens as number})`,
         );
         const nonRecoverableReason =
-          this.extractNonRecoverableBackendReason(reason) ??
-          this.extractNonRecoverableBackendReasonFromErrorText(errorText);
+          extractNonRecoverableBackendReason(reason) ??
+          extractNonRecoverableBackendReasonFromErrorText(errorText);
         if (nonRecoverableReason) {
           this.markBackendUnavailable(
             nonRecoverableReason,
@@ -1206,7 +1210,7 @@ export class LocalLlmClient {
     } catch (err) {
       const errMsg = err instanceof Error ? err.message : String(err);
       const durationMs = Date.now() - startedAtMs;
-      if (this.isAbortError(err)) {
+      if (isAbortError(err)) {
         log.warn(
           `local LLM request aborted: op=${operation} timeoutMs=${options.timeoutMs ?? this.config.localLlmTimeoutMs} model=${this.config.localLlmModel} durationMs=${durationMs} error=${errMsg}`,
         );
@@ -1214,7 +1218,7 @@ export class LocalLlmClient {
       }
       log.warn(`local LLM request error: op=${operation} error=${errMsg}`);
       this.isAvailable = false; // Mark as unavailable on non-abort errors
-      const nonRecoverableReason = this.extractNonRecoverableBackendReason(errMsg);
+      const nonRecoverableReason = extractNonRecoverableBackendReason(errMsg);
       if (nonRecoverableReason) {
         this.markBackendUnavailable(
           nonRecoverableReason,

package/src/orchestration/extraction-run-helpers.ts

@@ -0,0 +1,309 @@
+import type { BufferTurn, ExtractionFailureClass, ExtractionResult, MetaState } from "../types.js";
+import type { StorageManager } from "../index.js";
+import { log } from "../logger.js";
+
+export function combineExtractionAbortSignals(
+  primary: AbortSignal | undefined,
+  deadlineController: AbortController | undefined,
+): AbortSignal | undefined {
+  if (!deadlineController) return primary;
+  return primary ? AbortSignal.any([primary, deadlineController.signal]) : deadlineController.signal;
+}
+
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+export function deriveTopicsFromExtraction(result: ExtractionResult): string[] {
+  if (!isRecord(result)) return [];
+  const topics = new Set<string>();
+  const facts = Array.isArray(result.facts) ? result.facts : [];
+  for (const rawFact of facts) {
+    if (!isRecord(rawFact)) continue;
+    const tags = Array.isArray(rawFact.tags) ? rawFact.tags : [];
+    for (const tag of tags) {
+      if (typeof tag === "string" && tag.length >= 2) topics.add(tag.toLowerCase());
+    }
+    if (typeof rawFact.entityRef === "string" && rawFact.entityRef.length >= 2) {
+      topics.add(rawFact.entityRef.toLowerCase());
+    }
+    if (typeof rawFact.category === "string" && rawFact.category.length > 0) {
+      topics.add(rawFact.category);
+    }
+  }
+  const entities = Array.isArray(result.entities) ? result.entities : [];
+  for (const rawEntity of entities) {
+    if (!isRecord(rawEntity)) continue;
+    if (typeof rawEntity.name === "string" && rawEntity.name.length >= 2) {
+      topics.add(rawEntity.name.toLowerCase());
+    }
+  }
+  return [...topics].slice(0, 16);
+}
+
+/** Bounded cap on persisted per-fingerprint retry-state entries (per namespace meta). */
+export const EXTRACTION_RETRY_STATE_MAX_ENTRIES = 500;
+
+export interface ExtractionRetryStateEntry {
+  attempts: number;
+  nextEligibleAtMs: number;
+  firstFailedAtMs: number;
+  lastFailureClass: ExtractionFailureClass;
+}
+
+export interface ExtractionResilienceStatus {
+  breaker: {
+    state: "closed" | "open" | "half_open";
+    openUntilMs: number;
+    consecutiveFailures: number;
+    lastReason: string;
+  };
+  backoffFingerprintCount: number;
+}
+
+/**
+ * Pure backoff scheduler. Returns the absolute ms timestamp at which a
+ * fingerprint that has failed `attempts` times becomes eligible again:
+ * exponential via the configured schedule, clamped to `maxBackoffMs`, with
+ * ±`jitterRatio` multiplicative jitter. `rng` is injectable for deterministic
+ * tests. Never returns a timestamp before `now`.
+ */
+export function computeExtractionRetryNextEligibleMs(
+  attempts: number,
+  scheduleMs: readonly number[],
+  maxBackoffMs: number,
+  jitterRatio: number,
+  now: number,
+  rng: () => number = Math.random,
+): number {
+  if (!Number.isFinite(attempts) || !Number.isInteger(attempts) || attempts < 1) {
+    throw new RangeError("attempts must be a finite integer >= 1");
+  }
+  if (!Number.isFinite(maxBackoffMs) || maxBackoffMs < 0) {
+    throw new RangeError("maxBackoffMs must be a finite number >= 0");
+  }
+  if (!Number.isFinite(jitterRatio) || jitterRatio < 0 || jitterRatio > 1) {
+    throw new RangeError("jitterRatio must be a finite number in [0, 1]");
+  }
+  const safeNow = Number.isFinite(now) ? now : 0;
+  const cap = maxBackoffMs;
+  if (!Array.isArray(scheduleMs) || scheduleMs.length === 0) {
+    return safeNow + cap;
+  }
+  const idx = Math.min(attempts - 1, scheduleMs.length - 1);
+  const step = scheduleMs[idx];
+  const base = Math.min(typeof step === "number" && Number.isFinite(step) && step > 0 ? step : cap, cap);
+  const randomValue = rng();
+  if (!Number.isFinite(randomValue) || randomValue < 0 || randomValue > 1) {
+    throw new RangeError("rng() must return a finite number in [0, 1]");
+  }
+  const jitter = 1 + (randomValue * 2 - 1) * jitterRatio;
+  return safeNow + Math.max(0, Math.round(base * jitter));
+}
+
+/**
+ * Cap the persisted retry-state array to the newest `maxEntries` by
+ * firstFailedAt. Guards invalid caps so they cannot turn `slice(-maxEntries)`
+ * into an unbounded copy (AGENTS.md rule 17).
+ */
+export function capExtractionRetryStateEntries<T extends { firstFailedAt: string }>(
+  entries: readonly T[],
+  maxEntries: number,
+): T[] {
+  if (!Number.isFinite(maxEntries) || !Number.isInteger(maxEntries) || maxEntries <= 0) return [];
+  const sorted = [...entries].sort((a, b) => a.firstFailedAt.localeCompare(b.firstFailedAt));
+  return sorted.slice(-maxEntries);
+}
+
+/**
+ * Derive a single `sourceConnector` from a batch of turns.
+ * Returns the connector ONLY when ALL turns carry the same connector.
+ * Mixed tagged/untagged batches return undefined — extraction facts are
+ * persisted at batch level, so attributing them to the single tagged
+ * connector would falsely label facts from untagged turns.
+ * Conflicting connectors (different values) also return undefined.
+ */
+export function deriveSourceConnector(turns: readonly BufferTurn[]): string | undefined {
+  if (turns.length === 0) return undefined;
+  const connectors = new Set<string>();
+  let untaggedCount = 0;
+  for (const turn of turns) {
+    if (typeof turn.sourceConnector === "string" && turn.sourceConnector.length > 0) {
+      connectors.add(turn.sourceConnector);
+    } else {
+      untaggedCount += 1;
+    }
+  }
+  // All turns must agree on the same connector — no untagged turns mixed in.
+  if (untaggedCount > 0) return undefined;
+  return connectors.size === 1 ? [...connectors][0] : undefined;
+}
+
+export async function runExtractionPostPersistBestEffort(
+  runDeadlineAware: (
+    operation: () => Promise<unknown>,
+    phase: string,
+    clearTimerOnError?: boolean,
+    options?: { ignoreAbort?: boolean; ignoreDeadline?: boolean },
+  ) => Promise<unknown>,
+  stage: string,
+  operation: () => Promise<unknown>,
+  options?: { ignoreAbort?: boolean; ignoreDeadline?: boolean; propagateErrors?: boolean },
+): Promise<void> {
+  try {
+    await runDeadlineAware(operation, stage, false, {
+      ignoreAbort: options?.ignoreAbort,
+      ignoreDeadline: options?.ignoreDeadline,
+    });
+  } catch (error) {
+    if (options?.propagateErrors) throw error;
+    log.warn(`runExtraction: ${stage} failed after persistence (non-fatal)`, error);
+  }
+}
+
+/**
+ * Applies deferred-judge retention only to live, non-shadow extraction runs.
+ * Replay/import paths must not synthesize live-buffer entries after persistence.
+ */
+export interface ExtractionDeferRetentionOptions {
+  clearBufferAfterExtraction: boolean;
+  extractionJudgeShadow: boolean;
+  getDeferredCount: () => number;
+  normalizedTurns: BufferTurn[];
+  bufferKey: string;
+  retainDeferredTurns: (bufferKey: string, turns: BufferTurn[], max: number) => Promise<void>;
+}
+
+export async function runExtractionDeferRetention(
+  runPostPersistBestEffort: (
+    stage: string,
+    operation: () => Promise<unknown>,
+    options?: { ignoreAbort?: boolean },
+  ) => Promise<void>,
+  options: ExtractionDeferRetentionOptions,
+): Promise<void> {
+  await runPostPersistBestEffort("during_defer_retention", async () => {
+    if (options.clearBufferAfterExtraction && !options.extractionJudgeShadow) {
+      const deferredCount = options.getDeferredCount();
+      if (deferredCount > 0 && options.normalizedTurns.length > 0) {
+        await options.retainDeferredTurns(options.bufferKey, options.normalizedTurns, 10);
+      } else {
+        await options.retainDeferredTurns(options.bufferKey, [], 0);
+      }
+    }
+  });
+}
+
+export interface ExtractionPostPersistOptions {
+  result: ExtractionResult;
+  storage: StorageManager;
+  meta?: MetaState;
+  extractionFingerprint?: string;
+  shouldPersistProcessedFingerprint: boolean;
+  recordProcessedExtractionFingerprint: (
+    storage: StorageManager,
+    fingerprint: string,
+    meta: MetaState,
+  ) => Promise<void>;
+  runDeadlineAware: (
+    operation: () => Promise<unknown>,
+    phase: string,
+    clearTimerOnError?: boolean,
+    options?: { ignoreAbort?: boolean; ignoreDeadline?: boolean },
+  ) => Promise<unknown>;
+  isDeadlineError: (error: unknown) => boolean;
+  createDeadlineError: (stage: string) => Error;
+  deadlineMs?: number;
+  clearBufferAfterExtraction: boolean;
+  runPostPersistBestEffort: (
+    stage: string,
+    operation: () => Promise<unknown>,
+    options?: { ignoreAbort?: boolean; ignoreDeadline?: boolean; propagateErrors?: boolean },
+  ) => Promise<void>;
+  extractionJudgeShadow: boolean;
+  getDeferredCount: () => number;
+  normalizedTurns: BufferTurn[];
+  bufferKey: string;
+  retainDeferredTurns: (bufferKey: string, turns: BufferTurn[], max: number) => Promise<void>;
+  clearBuffer: (options?: { ignoreAbort?: boolean }) => Promise<void>;
+  failOnExtractionFailure: boolean;
+}
+
+export interface ExtractionPostPersistResult {
+  meta?: MetaState;
+  metadataFailed: boolean;
+}
+
+export async function runExtractionPostPersist(
+  options: ExtractionPostPersistOptions,
+): Promise<ExtractionPostPersistResult> {
+  let metadataFailed = false;
+  let deadlineError: Error | undefined;
+  const recordFailure = (stage: string, error: unknown): void => {
+    metadataFailed = true;
+    if (options.isDeadlineError(error) && deadlineError === undefined) {
+      deadlineError = error as Error;
+    }
+    log.warn(`runExtraction: ${stage} failed after durable persistence; continuing with buffer clear`, error);
+  };
+  let meta = options.meta;
+  try {
+    meta ??= (await options.runDeadlineAware(
+      () => options.storage.loadMeta(),
+      "during_post_persist_load_meta",
+      false,
+    )) as MetaState;
+  } catch (error) {
+    recordFailure("metadata load", error);
+  }
+  if (meta && options.extractionFingerprint && options.shouldPersistProcessedFingerprint) {
+    try {
+      await options.runDeadlineAware(
+        () => options.recordProcessedExtractionFingerprint(options.storage, options.extractionFingerprint!, meta!),
+        "during_post_persist_fingerprint",
+        false,
+      );
+    } catch (error) {
+      recordFailure("processed fingerprint", error);
+    }
+  }
+  if (meta) {
+    meta.extractionCount += 1;
+    meta.lastExtractionAt = new Date().toISOString();
+    meta.totalMemories += Array.isArray(options.result.facts) ? options.result.facts.length : 0;
+    meta.totalEntities += Array.isArray(options.result.entities) ? options.result.entities.length : 0;
+    try {
+      await options.runDeadlineAware(
+        () => options.storage.saveMeta(meta!),
+        "during_post_persist_meta_save",
+        false,
+      );
+    } catch (error) {
+      recordFailure("metadata save", error);
+    }
+  }
+  const runBestEffort = options.runPostPersistBestEffort;
+  await runExtractionDeferRetention(runBestEffort, {
+    clearBufferAfterExtraction: options.clearBufferAfterExtraction,
+    extractionJudgeShadow: options.extractionJudgeShadow,
+    getDeferredCount: options.getDeferredCount,
+    normalizedTurns: options.normalizedTurns,
+    bufferKey: options.bufferKey,
+    retainDeferredTurns: options.retainDeferredTurns,
+  });
+  await runBestEffort(
+    "during_buffer_clear",
+    () => options.clearBuffer({ ignoreAbort: true }),
+    {
+      ignoreAbort: true,
+      ignoreDeadline: options.failOnExtractionFailure,
+      propagateErrors: options.failOnExtractionFailure,
+    },
+  );
+  if (options.failOnExtractionFailure && typeof options.deadlineMs === "number" && Date.now() >= options.deadlineMs) {
+    throw options.createDeadlineError("during_buffer_clear");
+  }
+  if (deadlineError) throw deadlineError;
+  return { meta, metadataFailed };
+}