instar 1.3.232 → 1.3.233

package/dist/monitoring/CorrectionCaptureBacklog.js

@@ -0,0 +1,290 @@
+/**
+ * CorrectionCaptureBacklog — a bounded, durable retry queue for captures the
+ * Correction & Preference Learning Sentinel could NOT distill at capture time
+ * because the LLM was rate-limited / capacity-throttled (spec §3.1 extension).
+ *
+ * THE PROBLEM IT FIXES: the capture→distill hop runs through a rate-limited
+ * LlmQueue behind the account-global LLM circuit breaker. Under sustained
+ * throttling EVERY distill throws (daily-cap / reserve-breach / aborted /
+ * breaker-open) and the old hot path dropped the capture silently — so on a
+ * throttled agent the correction ledger stayed permanently EMPTY even though
+ * Layer-0 was detecting corrections. This store PERSISTS the (already
+ * pre-scrubbed) capture instead of dropping it, so a later headroom window can
+ * distill it into the CorrectionLedger.
+ *
+ * PRIVACY POSTURE (critical — a bounded extension of the ephemeral-ring model):
+ *   - It persists ONLY the ALREADY-PRE-SCRUBBED turns. The §3.3 deterministic
+ *     scrub (scrubSecrets) runs in buildDistillPrompt BEFORE anything reaches
+ *     this store — the caller hands us the post-scrub turn text, never raw user
+ *     text. We re-scrub defensively on enqueue (belt-and-suspenders), so even a
+ *     mis-wired caller cannot leak a raw secret to disk.
+ *   - Bounded retention TWO ways: a max-entries cap (evict oldest on overflow)
+ *     AND a TTL (pruneExpired discards stale rows). Entries are DELETED the
+ *     instant they distill (markDistilled) or exhaust their retries (bumpAttempt).
+ *   - No API route exposes backlog row content. The scrubbed turn text never
+ *     crosses HTTP — only counts are observable.
+ *
+ * DISCIPLINE (mirrors CorrectionLedger): SQLite WAL, prune-in-transaction, a
+ * detected/age index, fail-open (every method swallows storage errors so a
+ * backlog fault can NEVER throw into the fire-and-forget capture seam).
+ */
+import Database from 'better-sqlite3';
+import { registerSqliteHandle } from '../core/SqliteRegistry.js';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { NativeModuleHealer } from '../memory/NativeModuleHealer.js';
+import { scrubSecrets } from './scrubSecrets.js';
+const DEFAULT_MAX_ENTRIES = 200;
+const DEFAULT_MAX_RETRIES = 3;
+const DEFAULT_MIN_RETRY_GAP_MS = 60_000;
+const SCHEMA = [
+    `CREATE TABLE IF NOT EXISTS correction_capture_backlog (
+     id                   TEXT PRIMARY KEY,
+     topic_id             INTEGER NOT NULL,
+     scrubbed_turns_json  TEXT NOT NULL,
+     dedupe_hash          TEXT NOT NULL,
+     deterministic_weight INTEGER NOT NULL DEFAULT 0,
+     session_id           TEXT,
+     captured_at          INTEGER NOT NULL,
+     attempts             INTEGER NOT NULL DEFAULT 0,
+     last_attempt_at      INTEGER
+   )`,
+    // Oldest-first claim/evict ordering + TTL prune scan.
+    `CREATE INDEX IF NOT EXISTS idx_ccb_captured ON correction_capture_backlog(captured_at)`,
+    // Near-identical dedupe lookup.
+    `CREATE INDEX IF NOT EXISTS idx_ccb_dedupe ON correction_capture_backlog(dedupe_hash)`,
+];
+/**
+ * Bounded durable backlog of pre-scrubbed captures awaiting an LLM headroom
+ * window. Every method is fail-open — a storage fault returns a safe default and
+ * never throws into the capture seam.
+ */
+export class CorrectionCaptureBacklog {
+    db;
+    maxEntries;
+    maxRetries;
+    minRetryGapMs;
+    onError;
+    nowFn;
+    constructor(opts) {
+        this.maxEntries = opts.maxEntries && opts.maxEntries > 0 ? opts.maxEntries : DEFAULT_MAX_ENTRIES;
+        this.maxRetries =
+            typeof opts.maxRetries === 'number' && opts.maxRetries >= 0 ? opts.maxRetries : DEFAULT_MAX_RETRIES;
+        this.minRetryGapMs =
+            typeof opts.minRetryGapMs === 'number' && opts.minRetryGapMs >= 0
+                ? opts.minRetryGapMs
+                : DEFAULT_MIN_RETRY_GAP_MS;
+        this.nowFn = opts.now ?? (() => Date.now());
+        this.onError =
+            opts.onError ?? ((where, err) => console.error(`[CorrectionCaptureBacklog] ${where}:`, err));
+        if (opts.dbPath !== ':memory:') {
+            fs.mkdirSync(path.dirname(opts.dbPath), { recursive: true });
+        }
+        this.db = NativeModuleHealer.openWithHealSync('CorrectionCaptureBacklog', () => new Database(opts.dbPath));
+        this.db.pragma('journal_mode = WAL');
+        this.db.pragma('synchronous = NORMAL');
+        for (const ddl of SCHEMA)
+            this.db.exec(ddl);
+        registerSqliteHandle(() => { try {
+            this.db?.close();
+        }
+        catch { /* already closed */ } });
+    }
+    /**
+     * Re-scrub turns defensively (belt-and-suspenders over the §3.3 pre-scrub) and
+     * return ONLY {fromUser, text} — never the raw at-timestamp ring metadata.
+     */
+    sanitizeTurns(turns) {
+        return (Array.isArray(turns) ? turns : []).map((t) => ({
+            fromUser: !!t.fromUser,
+            text: scrubSecrets(String(t?.text ?? '')).slice(0, 1000),
+        }));
+    }
+    /** A stable hash over (topicId + scrubbed turn text) for near-identical dedupe. */
+    dedupeHashOf(topicId, turns) {
+        const canon = `${topicId}|` + turns.map((t) => `${t.fromUser ? 'u' : 'a'}:${t.text.trim()}`).join('\n');
+        return crypto.createHash('sha256').update(canon).digest('hex');
+    }
+    /**
+     * Persist a pre-scrubbed capture for a later distill. Dedupes against a
+     * near-identical existing entry (same topic + same scrubbed turns) — a repeat
+     * just bumps the existing row's captured_at forward rather than duplicating.
+     * Evicts the oldest entry when at the max-entries cap. Fail-open: returns the
+     * stored entry id, or null on any error (caller falls back to the old drop).
+     */
+    enqueue(input) {
+        try {
+            if (input.topicId == null)
+                return null;
+            const turns = this.sanitizeTurns(input.turns);
+            if (turns.length === 0)
+                return null;
+            const dedupeHash = this.dedupeHashOf(input.topicId, turns);
+            const capturedAt = input.capturedAt ?? this.nowFn();
+            const txn = this.db.transaction(() => {
+                // Near-identical dedupe: refresh the existing row's recency instead of
+                // inserting a duplicate (so a rapid restate doesn't fill the cap).
+                const existing = this.db
+                    .prepare(`SELECT id FROM correction_capture_backlog WHERE dedupe_hash = ? LIMIT 1`)
+                    .get(dedupeHash);
+                if (existing) {
+                    this.db
+                        .prepare(`UPDATE correction_capture_backlog SET captured_at = ? WHERE id = ?`)
+                        .run(capturedAt, existing.id);
+                    return existing.id;
+                }
+                // Evict oldest rows while at/over the cap (leave room for this insert).
+                const count = this.db
+                    .prepare(`SELECT COUNT(*) c FROM correction_capture_backlog`)
+                    .get().c;
+                const overflow = count - (this.maxEntries - 1);
+                if (overflow > 0) {
+                    this.db
+                        .prepare(`DELETE FROM correction_capture_backlog
+                WHERE id IN (
+                  SELECT id FROM correction_capture_backlog
+                  ORDER BY captured_at ASC, id ASC LIMIT @overflow)`)
+                        .run({ overflow });
+                }
+                const id = `CCB-${crypto.randomBytes(6).toString('hex')}`;
+                this.db
+                    .prepare(`INSERT INTO correction_capture_backlog
+               (id, topic_id, scrubbed_turns_json, dedupe_hash, deterministic_weight,
+                session_id, captured_at, attempts, last_attempt_at)
+             VALUES (?, ?, ?, ?, ?, ?, ?, 0, NULL)`)
+                    .run(id, input.topicId, JSON.stringify(turns), dedupeHash, Math.max(0, Math.round(input.deterministicWeight || 0)), input.sessionId ?? null, capturedAt);
+                return id;
+            });
+            return txn();
+        }
+        catch (err) {
+            this.onError('enqueue', err);
+            return null;
+        }
+    }
+    /**
+     * Claim up to `n` oldest entries eligible for a drain attempt: not exhausted
+     * (attempts <= maxRetries) and not attempted within minRetryGapMs. Read-only —
+     * does NOT consume the row; the drainer markDistilled()s on success or
+     * bumpAttempt()s on failure. Fail-open: returns [] on error.
+     */
+    claimBatch(n) {
+        try {
+            const limit = Math.max(0, Math.min(Math.floor(n) || 0, 50));
+            if (limit === 0)
+                return [];
+            const now = this.nowFn();
+            const cutoff = now - this.minRetryGapMs;
+            const rows = this.db
+                .prepare(`SELECT * FROM correction_capture_backlog
+            WHERE attempts <= @maxRetries
+              AND (last_attempt_at IS NULL OR last_attempt_at <= @cutoff)
+            ORDER BY captured_at ASC, id ASC
+            LIMIT @limit`)
+                .all({ maxRetries: this.maxRetries, cutoff, limit });
+            return rows.map((r) => this.rowToEntry(r)).filter((e) => e !== null);
+        }
+        catch (err) {
+            this.onError('claimBatch', err);
+            return [];
+        }
+    }
+    /** Delete an entry once it has been distilled into the ledger. Fail-open. */
+    markDistilled(id) {
+        try {
+            this.db.prepare(`DELETE FROM correction_capture_backlog WHERE id = ?`).run(id);
+        }
+        catch (err) {
+            this.onError('markDistilled', err);
+        }
+    }
+    /**
+     * Record a failed drain attempt. Increments attempts + stamps last_attempt_at;
+     * DROPS the entry once attempts EXCEEDS maxRetries (give-up — bounded, no
+     * infinite retry). Returns true if the entry was dropped. Fail-open.
+     */
+    bumpAttempt(id) {
+        try {
+            const now = this.nowFn();
+            const res = this.db
+                .prepare(`UPDATE correction_capture_backlog
+              SET attempts = attempts + 1, last_attempt_at = @now
+            WHERE id = @id`)
+                .run({ id, now });
+            if (res.changes === 0)
+                return false;
+            const row = this.db
+                .prepare(`SELECT attempts FROM correction_capture_backlog WHERE id = ?`)
+                .get(id);
+            if (row && row.attempts > this.maxRetries) {
+                this.db.prepare(`DELETE FROM correction_capture_backlog WHERE id = ?`).run(id);
+                return true;
+            }
+            return false;
+        }
+        catch (err) {
+            this.onError('bumpAttempt', err);
+            return false;
+        }
+    }
+    /** Discard entries older than ttlMs (prune-in-transaction). Returns rows removed. Fail-open. */
+    pruneExpired(ttlMs) {
+        try {
+            if (!(ttlMs > 0))
+                return 0;
+            const cutoff = this.nowFn() - ttlMs;
+            const res = this.db
+                .prepare(`DELETE FROM correction_capture_backlog WHERE captured_at < ?`)
+                .run(cutoff);
+            return res.changes ?? 0;
+        }
+        catch (err) {
+            this.onError('pruneExpired', err);
+            return 0;
+        }
+    }
+    /** Current backlog depth (observability). Fail-open → 0. */
+    count() {
+        try {
+            const row = this.db
+                .prepare(`SELECT COUNT(*) c FROM correction_capture_backlog`)
+                .get();
+            return row?.c ?? 0;
+        }
+        catch (err) {
+            this.onError('count', err);
+            return 0;
+        }
+    }
+    close() {
+        try {
+            this.db.close();
+        }
+        catch { /* ignore */ }
+    }
+    rowToEntry(r) {
+        try {
+            const parsed = JSON.parse(String(r.scrubbed_turns_json ?? '[]'));
+            const turns = (Array.isArray(parsed) ? parsed : []).map((t) => ({
+                fromUser: !!t.fromUser,
+                text: String(t?.text ?? ''),
+                at: 0, // ring metadata is not persisted; synthesized for the prompt builder.
+            }));
+            return {
+                id: r.id,
+                topicId: r.topic_id,
+                turns,
+                deterministicWeight: r.deterministic_weight ?? 0,
+                sessionId: r.session_id ?? null,
+                capturedAt: r.captured_at,
+                attempts: r.attempts ?? 0,
+                lastAttemptAt: r.last_attempt_at ?? null,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+}
+//# sourceMappingURL=CorrectionCaptureBacklog.js.map

package/dist/monitoring/CorrectionCaptureBacklog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CorrectionCaptureBacklog.js","sourceRoot":"","sources":["../../src/monitoring/CorrectionCaptureBacklog.ts"],"names":[],"mappings":"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"}

package/dist/monitoring/CorrectionCaptureLoop.d.ts

@@ -20,10 +20,17 @@
  * `kind` is enum-validated (the LLM cannot widen it); llm_confidence is advisory.
  *
  * LlmQueue discipline (spec §3.1): every enqueue() is wrapped in try/catch for
- * ALL THREE throw paths (daily-cap, reserve-breach, LlmAbortedError) → DROP
- * silently, no retry, no backlog.
+ * ALL FOUR capacity throw paths (daily-cap, reserve-breach, LlmAbortedError,
+ * breaker-open). Previously these DROPPED the capture silently. Now, when a
+ * bounded durable backlog is wired (default-on when the feature is enabled), a
+ * capacity throw PERSISTS the already-pre-scrubbed capture to the backlog so a
+ * later headroom window can distill it ('distill-backlogged'). A non-capacity
+ * throw (e.g. a malformed provider error) still drops ('distill-dropped'), and
+ * if the backlog enqueue itself fails the capture falls back to the old drop —
+ * the fire-and-forget seam never throws regardless.
  */
 import type { CorrectionLedger, CorrectionKind } from './CorrectionLedger.js';
+import type { CorrectionCaptureBacklog } from './CorrectionCaptureBacklog.js';
 export interface CaptureTurn {
     text: string;
     fromUser: boolean;
@@ -80,6 +87,21 @@ export declare function buildDistillPrompt(turns: CaptureTurn[]): string;
  * over the LLM's best-effort scrub).
  */
 export declare function parseDistillEnvelope(raw: string): DistillEnvelope | null;
+/**
+ * Is this distill rejection a rate-limit / capacity / backpressure condition
+ * (i.e. "the LLM is unavailable RIGHT NOW, try later") rather than a genuine
+ * fault (malformed output, programmer error)? Only capacity throws are worth
+ * backlogging — a later headroom window can succeed where they failed. The four
+ * shapes the per-sentinel distill path can throw:
+ *   - LlmQueue daily-cap:       Error('LLM daily spend cap exceeded')
+ *   - LlmQueue reserve breach:  Error('...breach interactive reserve')
+ *   - LlmQueue abort:           LlmAbortedError (name === 'LlmAbortedError')
+ *   - circuit breaker open:     LlmCircuitOpenError (`circuitOpen === true`)
+ * Plus a defensive net for provider rate-limit strings (429 / quota / "rate
+ * limit"). Conservative: an unrecognized error is NOT treated as capacity (it
+ * drops, preserving the old behavior for genuine faults).
+ */
+export declare function isCapacityThrow(err: unknown): boolean;
 export type DistillFn = (prompt: string) => Promise<string>;
 export interface CaptureAndDistillDeps {
     ring: CaptureRing;
@@ -94,6 +116,10 @@ export interface CaptureAndDistillDeps {
         maxPerWindow: number;
         windowMs: number;
     };
+    /** Durable retry backlog. When wired, a CAPACITY distill throw persists the
+     *  pre-scrubbed capture here ('distill-backlogged') instead of dropping it, so
+     *  a later headroom window can distill it. null/undefined → old drop behavior. */
+    backlog?: CorrectionCaptureBacklog | null;
     /** Audit sink — one structured line per capture decision. Never throws. */
     audit?: (event: {
         decision: string;
@@ -102,7 +128,7 @@ export interface CaptureAndDistillDeps {
     }) => void;
     now?: () => number;
 }
-export type CaptureDecision = 'recorded' | 'noise' | 'no-signal' | 'no-topic' | 'shed' | 'rate-limited' | 'distill-dropped' | 'distill-malformed' | 'error';
+export type CaptureDecision = 'recorded' | 'noise' | 'no-signal' | 'no-topic' | 'shed' | 'rate-limited' | 'distill-dropped' | 'distill-backlogged' | 'distill-malformed' | 'error';
 /** Per-topic rate-limit state, owned by the loop wiring (persists across turns). */
 export interface CaptureRateState {
     attempts: Map<number, number[]>;
@@ -127,4 +153,48 @@ export declare function captureAndDistill(deps: CaptureAndDistillDeps, input: {
     deterministicWeight: number;
     isLearningSignal: boolean;
 }, rateState?: CaptureRateState): Promise<CaptureDecision>;
+export interface DrainBacklogDeps {
+    backlog: CorrectionCaptureBacklog;
+    ledger: CorrectionLedger;
+    distill: DistillFn;
+    /** Pure, NON-mutating "is the LLM available right now?" gate (breaker closed +
+     *  not load-shedding). The drainer NEVER runs while this is false — draining
+     *  into an open breaker would just re-fail every entry. Wire to
+     *  llmCircuitAvailable() (which does not consume a half-open probe slot). */
+    llmAvailable: () => boolean;
+    /** TTL (ms) — entries older than this are pruned before draining. */
+    ttlMs?: number;
+    /** Audit sink — one structured line per drain decision. Never throws. */
+    audit?: (event: {
+        decision: string;
+        topicId: number | null;
+        detail?: string;
+    }) => void;
+}
+export interface DrainResult {
+    /** Why the drain stopped without processing (when applicable). */
+    skipped?: 'breaker-open' | 'empty';
+    claimed: number;
+    distilled: number;
+    recorded: number;
+    failed: number;
+    dropped: number;
+    pruned: number;
+}
+/**
+ * Opportunistically distill up to `batchSize` backlogged captures into the
+ * CorrectionLedger. OFF-HOT-PATH (call via void/async, NEVER on the message
+ * seam). Bounded (batchSize), fail-open (a per-entry fault bumps that entry, a
+ * top-level fault returns a safe result), and SKIPPED when the LLM is
+ * unavailable (breaker open / shedding) — draining into an open breaker would
+ * only re-trip it and waste the entries' retry budget.
+ *
+ * Per entry: build the SAME distill prompt (turns are already scrubbed on
+ * persist; buildDistillPrompt re-scrubs harmlessly), parse the envelope, and —
+ * on a real, non-noise learning — record it to the ledger then DELETE the
+ * backlog row (markDistilled). A capacity throw OR a malformed/failed distill
+ * bumps the entry's attempt count (dropped once it exceeds maxRetries). A 'noise'
+ * verdict is terminal: the row is deleted (markDistilled) — it carried no lesson.
+ */
+export declare function drainBacklog(deps: DrainBacklogDeps, batchSize: number): Promise<DrainResult>;
 //# sourceMappingURL=CorrectionCaptureLoop.d.ts.map

package/dist/monitoring/CorrectionCaptureLoop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CorrectionCaptureLoop.d.ts","sourceRoot":"","sources":["../../src/monitoring/CorrectionCaptureLoop.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"CorrectionCaptureLoop.d.ts","sourceRoot":"","sources":["../../src/monitoring/CorrectionCaptureLoop.ts"],"names":[],"mappings":"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"}

package/dist/monitoring/CorrectionCaptureLoop.js

@@ -145,6 +145,43 @@ export function parseDistillEnvelope(raw) {
         scrubbed_summary: scrubSecrets(summaryRaw || learningRaw).slice(0, 500),
     };
 }
+// ── Capacity-throw classification ────────────────────────────────────────
+/**
+ * Is this distill rejection a rate-limit / capacity / backpressure condition
+ * (i.e. "the LLM is unavailable RIGHT NOW, try later") rather than a genuine
+ * fault (malformed output, programmer error)? Only capacity throws are worth
+ * backlogging — a later headroom window can succeed where they failed. The four
+ * shapes the per-sentinel distill path can throw:
+ *   - LlmQueue daily-cap:       Error('LLM daily spend cap exceeded')
+ *   - LlmQueue reserve breach:  Error('...breach interactive reserve')
+ *   - LlmQueue abort:           LlmAbortedError (name === 'LlmAbortedError')
+ *   - circuit breaker open:     LlmCircuitOpenError (`circuitOpen === true`)
+ * Plus a defensive net for provider rate-limit strings (429 / quota / "rate
+ * limit"). Conservative: an unrecognized error is NOT treated as capacity (it
+ * drops, preserving the old behavior for genuine faults).
+ */
+export function isCapacityThrow(err) {
+    if (!err)
+        return false;
+    const e = err;
+    if (e.circuitOpen === true)
+        return true;
+    if (e.isRateLimit === true)
+        return true;
+    if (e.name === 'LlmAbortedError' || e.name === 'LlmCircuitOpenError')
+        return true;
+    const msg = typeof e.message === 'string' ? e.message.toLowerCase() : '';
+    if (!msg)
+        return false;
+    return (msg.includes('daily spend cap') ||
+        msg.includes('interactive reserve') ||
+        msg.includes('rate limit') ||
+        msg.includes('rate-limit') ||
+        msg.includes('circuit breaker open') ||
+        msg.includes('too many requests') ||
+        /\b429\b/.test(msg) ||
+        msg.includes('quota'));
+}
 export function makeCaptureRateState() {
     return { attempts: new Map() };
 }
@@ -207,8 +244,33 @@ export async function captureAndDistill(deps, input, rateState) {
         try {
             response = await deps.distill(prompt);
         }
-        catch {
-            // @silent-fallback-ok — cap / reserve / abort all mean "skip this capture".
+        catch (distillErr) {
+            // A CAPACITY throw (daily-cap / reserve / abort / breaker-open) means "the
+            // LLM is unavailable right now" — persist the pre-scrubbed capture to the
+            // durable backlog so a later headroom window distills it (instead of the
+            // old silent drop that left a throttled agent's ledger permanently empty).
+            // enqueue() re-scrubs every turn defensively, so ONLY pre-scrubbed text is
+            // ever persisted. Wrapped in try/catch → any backlog fault falls back to
+            // the old drop. A NON-capacity fault still drops.
+            if (deps.backlog && isCapacityThrow(distillErr)) {
+                try {
+                    const id = deps.backlog.enqueue({
+                        topicId: input.topicId,
+                        turns: window,
+                        deterministicWeight: input.deterministicWeight,
+                        sessionId: input.sessionId ?? null,
+                        capturedAt: now(),
+                    });
+                    if (id) {
+                        deps.audit?.({ decision: 'distill-backlogged', topicId: input.topicId, detail: id });
+                        return 'distill-backlogged';
+                    }
+                }
+                catch {
+                    // @silent-fallback-ok — backlog fault must never break capture; drop.
+                }
+            }
+            // @silent-fallback-ok — non-capacity fault, or backlog absent/failed.
             deps.audit?.({ decision: 'distill-dropped', topicId: input.topicId });
             return 'distill-dropped';
         }
@@ -246,4 +308,112 @@ export async function captureAndDistill(deps, input, rateState) {
         return 'error';
     }
 }
+/**
+ * Opportunistically distill up to `batchSize` backlogged captures into the
+ * CorrectionLedger. OFF-HOT-PATH (call via void/async, NEVER on the message
+ * seam). Bounded (batchSize), fail-open (a per-entry fault bumps that entry, a
+ * top-level fault returns a safe result), and SKIPPED when the LLM is
+ * unavailable (breaker open / shedding) — draining into an open breaker would
+ * only re-trip it and waste the entries' retry budget.
+ *
+ * Per entry: build the SAME distill prompt (turns are already scrubbed on
+ * persist; buildDistillPrompt re-scrubs harmlessly), parse the envelope, and —
+ * on a real, non-noise learning — record it to the ledger then DELETE the
+ * backlog row (markDistilled). A capacity throw OR a malformed/failed distill
+ * bumps the entry's attempt count (dropped once it exceeds maxRetries). A 'noise'
+ * verdict is terminal: the row is deleted (markDistilled) — it carried no lesson.
+ */
+export async function drainBacklog(deps, batchSize) {
+    const result = { claimed: 0, distilled: 0, recorded: 0, failed: 0, dropped: 0, pruned: 0 };
+    try {
+        // Prune stale entries first (bounded retention).
+        if (deps.ttlMs && deps.ttlMs > 0) {
+            result.pruned = deps.backlog.pruneExpired(deps.ttlMs);
+        }
+        // NEVER drain while the breaker is open / shedding.
+        if (!deps.llmAvailable()) {
+            result.skipped = 'breaker-open';
+            deps.audit?.({ decision: 'drain-skipped-breaker-open', topicId: null });
+            return result;
+        }
+        const batch = deps.backlog.claimBatch(batchSize);
+        result.claimed = batch.length;
+        if (batch.length === 0) {
+            result.skipped = 'empty';
+            return result;
+        }
+        for (const entry of batch) {
+            // Re-check availability between entries — a mid-drain trip stops the batch
+            // cleanly (remaining entries keep their attempt budget for next time).
+            if (!deps.llmAvailable()) {
+                deps.audit?.({ decision: 'drain-stopped-breaker-open', topicId: entry.topicId });
+                break;
+            }
+            try {
+                const prompt = buildDistillPrompt(entry.turns);
+                const response = await deps.distill(prompt);
+                result.distilled++;
+                const envelope = parseDistillEnvelope(response);
+                if (!envelope) {
+                    // Malformed — count a failed attempt (a later retry may parse).
+                    const dropped = deps.backlog.bumpAttempt(entry.id);
+                    result.failed++;
+                    if (dropped)
+                        result.dropped++;
+                    deps.audit?.({ decision: dropped ? 'drain-malformed-dropped' : 'drain-malformed', topicId: entry.topicId });
+                    continue;
+                }
+                if (envelope.kind === 'noise') {
+                    // Terminal — no lesson; delete the row.
+                    deps.backlog.markDistilled(entry.id);
+                    deps.audit?.({ decision: 'drain-noise', topicId: entry.topicId });
+                    continue;
+                }
+                const rec = deps.ledger.record({
+                    kind: envelope.kind,
+                    learning: envelope.learning,
+                    scrubbedSummary: envelope.scrubbed_summary,
+                    deterministicWeight: entry.deterministicWeight,
+                    llmConfidence: envelope.llm_confidence,
+                    topicId: entry.topicId,
+                    sessionId: entry.sessionId ?? null,
+                });
+                if (rec) {
+                    deps.backlog.markDistilled(entry.id);
+                    result.recorded++;
+                    deps.audit?.({ decision: 'drain-recorded', topicId: entry.topicId, detail: `${envelope.kind} ${rec.dedupeKey.slice(0, 24)}` });
+                }
+                else {
+                    // Ledger write failed — keep the entry, count an attempt.
+                    const dropped = deps.backlog.bumpAttempt(entry.id);
+                    result.failed++;
+                    if (dropped)
+                        result.dropped++;
+                    deps.audit?.({ decision: dropped ? 'drain-ledger-failed-dropped' : 'drain-ledger-failed', topicId: entry.topicId });
+                }
+            }
+            catch (entryErr) {
+                // A capacity throw or any other per-entry fault: bump the attempt and
+                // move on (the seam never throws). If this was a fresh breaker trip the
+                // next-entry availability check stops the batch.
+                const dropped = deps.backlog.bumpAttempt(entry.id);
+                result.failed++;
+                if (dropped)
+                    result.dropped++;
+                deps.audit?.({
+                    decision: dropped ? 'drain-failed-dropped' : 'drain-failed',
+                    topicId: entry.topicId,
+                    detail: entryErr instanceof Error ? entryErr.message.slice(0, 80) : undefined,
+                });
+                if (isCapacityThrow(entryErr))
+                    break; // breaker likely tripped — stop the batch.
+            }
+        }
+    }
+    catch (err) {
+        // Top-level fault — never propagates (off-hot-path, fail-open).
+        deps.audit?.({ decision: 'drain-error', topicId: null, detail: err instanceof Error ? err.message : String(err) });
+    }
+    return result;
+}
 //# sourceMappingURL=CorrectionCaptureLoop.js.map