@gamaze/hicortex 0.23.2 → 0.24.0

package/assets/dashboard.html

@@ -865,6 +865,15 @@
   /* #423 phase 3: the capture-pause badge — the same amber family as the
      held badge (an operator state, not an error) */
   .cap-paused{ color:var(--amber); margin-left:5px; font-size:9px; letter-spacing:.08em; }
+  /* #530 follow-up: the distill-inbox row — stale badge + bar fill in the
+     amber family once the oldest queued item passes the payload's ECHOED warn
+     age. [hidden] must win over .cap-row2's flex (author display beats the
+     UA's hidden — the #billing-banner idiom) so a pre-#529 server shows
+     nothing, theme tokens only */
+  .cap-qrow[hidden]{ display:none; }
+  .cap-stale{ color:var(--amber); margin-left:5px; }
+  .cap-qrow .fill.warn{ background:var(--amber); }
+  .cap-qrow.stale .cap-dot{ background:var(--amber); }
 
   /* ================= the memory dropdown — opens UNDER the left search ================= */
   #panel{
@@ -1277,6 +1286,11 @@
     <div class="brow">
       <div class="bseg" id="g-capture">
         <div class="gh"><span class="t">Capture health</span><span class="sub" id="cap-sub">memory counts</span></div>
+        <!-- #530 follow-up: the distill inbox — the drain-side counterpart of
+             this card's delivery-side health. Pinned above the scrollable
+             #cap-rows; hidden until buildCapture's payload guard unhides it
+             (pre-#529 servers omit the block). -->
+        <div class="cap-row2 cap-qrow" id="cap-queue" hidden></div>
         <div id="cap-rows"></div>
       </div>
       <div class="bseg" id="g-roll">
@@ -3766,6 +3780,31 @@ function agoLabel(iso){
 function buildCapture(){
   const host=el('cap-rows');
   host.innerHTML='';
+  /* #530 follow-up: the distill-inbox row — rendered FIRST because every
+     render branch below returns early (a call after them would only run in
+     the degrade). The absent-block guard keeps it hidden on a pre-#529
+     server; the warn threshold is always the payload's echo (#476
+     degrade-literal precedent), never a page literal. */
+  const qrow=el('cap-queue');
+  qrow.innerHTML='';
+  qrow.className='cap-row2 cap-qrow';
+  const q=D&&D.distill_queue?D.distill_queue:null;
+  qrow.hidden=!q;
+  if(q){
+    const thr=q.warn_age_hours||24;
+    const oldest=(typeof q.oldest_age_hours==='number')?q.oldest_age_hours:null;
+    const stale=oldest!==null&&oldest>thr;
+    if(stale) qrow.classList.add('stale');
+    qrow.title='Distill inbox — deliveries are stored durably at POST time and distilled by the scheduled nightly run before consolidation'
+      +(stale?' — the oldest item is '+oldest+' h old (warn age '+thr+' h): the scheduled drain is behind':'');
+    qrow.innerHTML='<span class="cap-dot"></span>'
+      +'<span class="hn">Distill inbox</span>'
+      +'<span class="cap-bar"><span class="fill'+(stale?' warn':'')+'" style="width:'+(oldest===null?0:Math.min(1,oldest/thr)*100)+'%"></span></span>'
+      +'<span class="st"><b>'+fmt(q.depth||0)+'</b> queued'
+      +(oldest===null?' · inbox empty':' · oldest '+(oldest>=48?(oldest/24).toFixed(1)+'d':oldest.toFixed(1)+'h'))
+      +(stale?'<span class="cap-stale" title="oldest queued item past the '+thr+' h warn age — the scheduled drain is behind">&#9888; stale</span>':'')
+      +'</span>';
+  }
   const sub=el('cap-sub');
   const ch=D&&D.capture_health?D.capture_health:null;
   /* fix round 7: the rolling-window view — the card shows the normal 30 day

package/dist/calibration.d.ts

@@ -416,3 +416,34 @@ export declare function resolveOllamaFlushEvery(): number;
  *  HICORTEX_OLLAMA_FLUSH_WAIT_MS wins; invalid warns and keeps
  *  OLLAMA_FLUSH_WAIT_MS. */
 export declare function resolveOllamaFlushWaitMs(): number;
+/**
+ * Re-check interval (ms) while the drain's yield signal reports the LLM
+ * endpoint busy (#529 owner ruling 05.10.2026: interactive use always
+ * yields). The drain waits one interval between probe re-checks instead of
+ * polling in a tight loop; 30 s is short enough that the run resumes within
+ * half a minute of the owner going idle, long enough not to hammer the
+ * signal endpoint while a long interactive session runs.
+ */
+export declare const DRAIN_YIELD_POLL_MS = 30000;
+/**
+ * Per-item cap (ms) on yield waits (#529). The run deadline is the primary
+ * bound; this cap is the fail-open backstop so a misconfigured signal that
+ * always answers "busy" cannot stall one item past half an hour — the item
+ * proceeds and the next between-items checks decide again. 30 min matches
+ * the order of a long local-model generation, the longest legitimate busy.
+ */
+export declare const DRAIN_YIELD_WAIT_CAP_MS: number;
+/**
+ * Timeout (ms) for ONE yield-probe GET (#529). Deliberately short: the probe
+ * sits between drain items, and an endpoint that answers busy-signals at all
+ * answers them fast — anything slower reads as unreachable (fail-open).
+ */
+export declare const DRAIN_YIELD_PROBE_TIMEOUT_MS = 3000;
+/**
+ * Oldest-item age (hours) above which the distill inbox warns in
+ * `hicortex status` and on the dashboard (#529). 24 h ≈ two missed scheduled
+ * runs on the default 2×/day consolidation grid — items older than that are
+ * not "waiting for tonight" anymore, they are stuck, and the operator should
+ * look at the drain's last outcome.
+ */
+export declare const DRAIN_QUEUE_WARN_AGE_HOURS = 24;

package/dist/calibration.js

@@ -25,7 +25,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.STAGE_BELIEF_STRENGTH = exports.STAGE_FADING_STRENGTH = exports.STAGE_FADING_DAYS = exports.WEAK_PRIMARY_FLOOR = exports.CORRECTION_REWRITE_MIN_CONFIDENCE = exports.CORRECTION_MIN_SIMILARITY = exports.DEDUP_AUTO_MERGE_THRESHOLD = exports.IMPORTANCE_SETTLE_WINDOW_DAYS = exports.IMPORTANCE_CEILING = exports.BM25_WEIGHT_DOMAIN = exports.BM25_WEIGHT_PROJECT = exports.BM25_WEIGHT_BODY = exports.BOTH_CHANNEL_BOOST = exports.RRF_VECTOR_WEIGHT = exports.RRF_FTS_WEIGHT = exports.RRF_COMPOSITE_WEIGHT = exports.RRF_K = exports.SCOPE_AFFINITY_WEIGHT = exports.SUPERSEDED_DEMOTION = exports.RECENCY_HEAD_DAYS = exports.RECENCY_HEAD_WEIGHT = exports.RECENCY_HOURLY_DECAY = exports.SCORE_RECENCY_WEIGHT = exports.CONNECTIONS_SATURATION_DEGREE = exports.SCORE_CONNECTIONS_WEIGHT = exports.SCORE_STRENGTH_WEIGHT = exports.SCORE_SIMILARITY_WEIGHT = exports.VOLATILE_GATE_MAX_CHARS = exports.VOLATILE_STATUS_FILTER = exports.MEMORY_PRECISION_PROMPT_EXCERPT_CHARS = exports.MEMORY_PRECISION_DIVERGENCE_MIN_SHOWN = exports.MEMORY_PRECISION_REDUNDANT_ABOVE = exports.MEMORY_PRECISION_WINDOW_DAYS = exports.RECALL_USES_AXIS_MAX = exports.RECALL_USES_NORMAL_MAX = exports.RECALL_USES_LOW_MAX = exports.RECALL_RESHOW_TURNS = exports.NOVELTY_FLOOR_SLOTS = exports.RECALL_TITLE_CHARS = exports.RECALL_MIN_PROMPT_CHARS = exports.RECALL_MAX_ITEMS = exports.RECALL_MIN_SIMILARITY = exports.SESSION_INTENT_WEIGHT = exports.COLD_EXPOSURE_SLOTS = exports.RECENT_WINDOW_DAYS = exports.RECENT_LIMIT = exports.SEARCH_LIMIT = exports.PROMOTION_STRENGTH_FLOOR = exports.PROMOTION_RATE = exports.DECAY_HALF_LIFE_DAYS = void 0;
-exports.DIAGNOSTIC_ENV_TIER = exports.OLLAMA_FLUSH_WAIT_MS = exports.OLLAMA_FLUSH_EVERY = exports.NUM_CTX = exports.DEFAULT_FIRST_RUN_LOOKBACK_DAYS = exports.ENRICH_STRENGTH_DELTA = exports.STAGE_TRUTH_STRENGTH = void 0;
+exports.DRAIN_QUEUE_WARN_AGE_HOURS = exports.DRAIN_YIELD_PROBE_TIMEOUT_MS = exports.DRAIN_YIELD_WAIT_CAP_MS = exports.DRAIN_YIELD_POLL_MS = exports.DIAGNOSTIC_ENV_TIER = exports.OLLAMA_FLUSH_WAIT_MS = exports.OLLAMA_FLUSH_EVERY = exports.NUM_CTX = exports.DEFAULT_FIRST_RUN_LOOKBACK_DAYS = exports.ENRICH_STRENGTH_DELTA = exports.STAGE_TRUTH_STRENGTH = void 0;
 exports.resolveNumCtx = resolveNumCtx;
 exports.resolveOllamaFlushEvery = resolveOllamaFlushEvery;
 exports.resolveOllamaFlushWaitMs = resolveOllamaFlushWaitMs;
@@ -514,3 +514,40 @@ function resolveOllamaFlushWaitMs() {
     console.warn(`[hicortex] env HICORTEX_OLLAMA_FLUSH_WAIT_MS=${JSON.stringify(raw)} is not a positive finite number — using default ${exports.OLLAMA_FLUSH_WAIT_MS}.`);
     return exports.OLLAMA_FLUSH_WAIT_MS;
 }
+// ---------------------------------------------------------------------------
+// Distill inbox / drain family (#529) — delivery-compute separation. Delivery
+// (cheap, must never lose data) stores segments durably; compute (expensive,
+// scheduled) happens only inside the nightly's drain stage. These constants
+// shape the drain's interactive-yield seam and the inbox's visibility signal.
+// ---------------------------------------------------------------------------
+/**
+ * Re-check interval (ms) while the drain's yield signal reports the LLM
+ * endpoint busy (#529 owner ruling 05.10.2026: interactive use always
+ * yields). The drain waits one interval between probe re-checks instead of
+ * polling in a tight loop; 30 s is short enough that the run resumes within
+ * half a minute of the owner going idle, long enough not to hammer the
+ * signal endpoint while a long interactive session runs.
+ */
+exports.DRAIN_YIELD_POLL_MS = 30_000;
+/**
+ * Per-item cap (ms) on yield waits (#529). The run deadline is the primary
+ * bound; this cap is the fail-open backstop so a misconfigured signal that
+ * always answers "busy" cannot stall one item past half an hour — the item
+ * proceeds and the next between-items checks decide again. 30 min matches
+ * the order of a long local-model generation, the longest legitimate busy.
+ */
+exports.DRAIN_YIELD_WAIT_CAP_MS = 30 * 60_000;
+/**
+ * Timeout (ms) for ONE yield-probe GET (#529). Deliberately short: the probe
+ * sits between drain items, and an endpoint that answers busy-signals at all
+ * answers them fast — anything slower reads as unreachable (fail-open).
+ */
+exports.DRAIN_YIELD_PROBE_TIMEOUT_MS = 3_000;
+/**
+ * Oldest-item age (hours) above which the distill inbox warns in
+ * `hicortex status` and on the dashboard (#529). 24 h ≈ two missed scheduled
+ * runs on the default 2×/day consolidation grid — items older than that are
+ * not "waiting for tonight" anymore, they are stuck, and the operator should
+ * look at the drain's last outcome.
+ */
+exports.DRAIN_QUEUE_WARN_AGE_HOURS = 24;

package/dist/capture.d.ts

@@ -90,6 +90,13 @@ export interface PostResult {
         completion: number;
         total: number;
     };
+    /**
+     * #529: the 201 confirmed durable QUEUEING, not distillation — a queue-mode
+     * server stores the segment and the nightly's drain distills it in the
+     * scheduled run. Contract-wise identical to any other 201 (the cursor
+     * advances); the capture loop only swaps its log line on it.
+     */
+    queued?: boolean;
 }
 export type PostFn = (body: DistillBody) => Promise<PostResult>;
 export interface CaptureOptions {

package/dist/capture.js

@@ -301,7 +301,16 @@ async function captureBatches(batches, opts) {
                 }
                 if (advancesBoundary)
                     lastConfirmedEnd = seg.segEnd;
-                console.log(`[hicortex]     → ${result.distilled ?? 0} memories (segment ${body.segment_id})`);
+                // #529: a queue-mode 201 means "durably stored, distilled on the
+                // server's next scheduled run" — same confirmation, different log
+                // line, so a nightly log never reads "0 memories" as a failure when
+                // the server simply queued the segment.
+                if (result.queued) {
+                    console.log(`[hicortex]     Queued on server (segment ${body.segment_id}) — distilled on the next scheduled run`);
+                }
+                else {
+                    console.log(`[hicortex]     → ${result.distilled ?? 0} memories (segment ${body.segment_id})`);
+                }
                 for (const d of result.dropped ?? []) {
                     // #489: the response array carries BOTH gate kinds (substance +
                     // volatility) — the server's own log names the exact gate; this

package/dist/dashboard.d.ts

@@ -268,6 +268,20 @@ export interface DashboardData {
      * pre-#476 recall-card rendering when the block is absent.
      */
     memory_precision: MemoryPrecision;
+    /**
+     * #529 — the distill inbox: live queue depth + oldest-item age (the
+     * drain-side health signal; delivery-side health is capture_health
+     * above). ALWAYS present; `oldest_age_hours` null when empty. The warn
+     * threshold is ECHOED like every threshold (the page renders its own
+     * stale badge from it, never hardcodes 24). Live view only — no snapshot
+     * history (depth is ~0 at snapshot time by construction). A pre-#529
+     * server omits the block; the page guards.
+     */
+    distill_queue: {
+        depth: number;
+        oldest_age_hours: number | null;
+        warn_age_hours: number;
+    };
     digest: {
         date: string | null;
         run_at: string | null;

package/dist/dashboard.js

@@ -46,6 +46,7 @@ const config_read_js_1 = require("./config-read.js");
 const consolidate_js_1 = require("./consolidate.js");
 const capture_health_js_1 = require("./capture-health.js");
 const recall_precision_js_1 = require("./recall-precision.js");
+const distill_queue_js_1 = require("./distill-queue.js");
 const capture_pause_js_1 = require("./capture-pause.js");
 const state_js_1 = require("./state.js");
 const retrieval_js_1 = require("./retrieval.js");
@@ -585,6 +586,13 @@ function handleDashboardData(db, query, config) {
                 shown_sum: live.adoption?.shown_sum ?? 0,
                 used_sum: live.adoption?.used_sum ?? 0,
             }),
+            // #529: live inbox state — depth + oldest age + the echoed warn
+            // threshold. Live only (no series): depth at snapshot time is ~0 by
+            // construction, so history would be a flat line.
+            distill_queue: {
+                ...(0, distill_queue_js_1.readQueueStats)(db),
+                warn_age_hours: calibration_js_1.DRAIN_QUEUE_WARN_AGE_HOURS,
+            },
             // #423 phase 3: pauses + presence in one block — one source of truth
             // for the rail's dots, toggles and the capture card's PAUSED badges.
             fleet: {

package/dist/db.js

@@ -763,6 +763,51 @@ const MIGRATIONS = [
       `);
         },
     },
+    {
+        version: 24,
+        name: "distill_queue",
+        up: (db) => {
+            // #529 — the durable distill inbox. POST /distill in queue mode stores
+            // the REDACTED segment here and answers 201 immediately (no LLM call);
+            // the nightly drain distills rows oldest-first and deletes each row in
+            // the same transaction as its memory inserts. One table in the shared
+            // SQLite DB — one store, same backup and tooling as the corpus (owner
+            // decision; not files). The row carries every /distill wire field needed
+            // to re-distill later (attribution, project, session_date, privacy) so
+            // the drain reproduces the sync path's insert exactly.
+            //
+            // UNIQUE(session_id, segment_id) is the delivery-time idempotency key: a
+            // queued-but-undistilled segment re-POST answers 200 skipped (the
+            // handler's prechecks consult this table), and a failed drain attempt
+            // never duplicates on retry. Legacy no-segment posts normalize
+            // segment_id ''. session_id stays NULL for posts that carry no session
+            // key — SQLite unique indexes treat NULLs as distinct, so those rows
+            // (which have no dedup key by construction, same as the sync path's
+            // sourceSession-undefined inserts) each enqueue separately.
+            // Idempotent: IF NOT EXISTS (the v18/v21 pattern — plain CREATE).
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS distill_queue (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          session_id TEXT,
+          segment_id TEXT NOT NULL DEFAULT '',
+          source_agent TEXT,
+          source_agent_id TEXT,
+          source_domain TEXT,
+          source_machine TEXT,
+          project TEXT,
+          session_date TEXT,
+          privacy TEXT,
+          text TEXT NOT NULL,
+          arrived_at TEXT NOT NULL
+        )
+      `);
+            db.exec(`
+        CREATE UNIQUE INDEX IF NOT EXISTS idx_distill_queue_session_segment
+          ON distill_queue(session_id, segment_id)
+      `);
+            db.exec("CREATE INDEX IF NOT EXISTS idx_distill_queue_arrived ON distill_queue(arrived_at)");
+        },
+    },
 ];
 /**
  * Run all pending migrations against the database.

package/dist/distill-queue.d.ts

@@ -0,0 +1,203 @@
+/**
+ * The durable distill inbox + its drain (#529).
+ *
+ * Delivery and compute are separated: `POST /distill` in queue mode stores the
+ * REDACTED segment in the `distill_queue` table (migration v24) and answers
+ * 201 immediately — no LLM call, no probe, no chunk-size detection, no token
+ * gate (all of those move to the drain). The nightly's drain stage then
+ * distills queued items oldest-first, round-robin per client, before
+ * consolidation, so all distill LLM traffic happens inside the owner's
+ * scheduled runs instead of on the clients' drifting capture grids.
+ *
+ * This module holds BOTH halves as pure units:
+ *  - the inbox STORE (enqueue, dedup mirrors, depth/age stats, delete) — real
+ *    functions the /distill handler calls directly;
+ *  - the DRAIN — dependency-injected (LlmClient-like object, embed fn,
+ *    yield-probe, token-budget gate, run deadline, sleep) so the whole stage
+ *    is unit-testable with no HTTP and no real LLM. Every LLM call goes
+ *    through `distillSession` (distiller.ts) on the injected client — never a
+ *    bespoke fetch — so the drain inherits the #337 undici dispatcher, #355
+ *    single-flight, the retry ladder, and the circuit breaker by construction.
+ *
+ * Ordering contract (spec #529): oldest-first (rowid = arrival order),
+ * round-robin per client key (`source_machine` + `source_agent`) so one
+ * client's giant backlog cannot starve the others, and a session's segments
+ * in arrival order (natural — a client POSTs its segments sequentially, so
+ * ascending rowid within a client is per-session ascending).
+ *
+ * Checkpointing contract: per item, ALL memory inserts and the inbox-row
+ * delete commit in ONE transaction. An interrupted run (crash, deadline,
+ * endpoint outage) leaves processed items done and the rest queued — the
+ * segment-exact dedup keys (`<sid>#<segment_id>#<i>`) make the retry
+ * idempotent, dup-over-loss.
+ */
+import type Database from "better-sqlite3";
+import { detectChunkSize } from "./distiller.js";
+import type { LlmUsage, LlmConfig } from "./llm.js";
+import type { RunDeadline } from "./run-deadline.js";
+/** One queued delivery, as stored in `distill_queue`. */
+export interface DistillQueueRow {
+    id: number;
+    session_id: string | null;
+    segment_id: string;
+    source_agent: string | null;
+    source_agent_id: string | null;
+    source_domain: string | null;
+    source_machine: string | null;
+    project: string | null;
+    session_date: string | null;
+    privacy: string | null;
+    text: string;
+    arrived_at: string;
+}
+/**
+ * The wire fields of one /distill POST, as the queue-mode handler resolved
+ * them (post-redaction). `session_date` defaults to today AT ENQUEUE TIME —
+ * the sync path stamps `new Date()` at delivery, and the queue must not let a
+ * segment that waited ~12 h in the inbox drift to the drain-day's date.
+ */
+export interface EnqueueDistillInput {
+    /** REDACTED conversation text (the handler redacts before enqueueing). */
+    text: string;
+    source_agent?: unknown;
+    source_agent_id?: unknown;
+    source_domain?: unknown;
+    source_machine?: unknown;
+    project?: unknown;
+    session_id?: unknown;
+    segment_id?: unknown;
+    session_date?: unknown;
+    privacy?: unknown;
+}
+/**
+ * Insert one delivery into the inbox. Idempotent on the UNIQUE(session_id,
+ * segment_id) index — a re-POST of the SAME key (only reachable through a
+ * race: the handler's prechecks already answered the sequential re-POST with
+ * a 200 skip) reports `{ duplicate: true }` and inserts nothing. Posts with
+ * no session_id have no dedup key by construction and always insert (SQLite
+ * unique indexes treat NULLs as distinct).
+ */
+export declare function enqueueDistill(db: Database.Database, input: EnqueueDistillInput): {
+    duplicate: boolean;
+};
+/**
+ * Inbox mirror of the segment-exact delivery precheck: how many QUEUED rows
+ * match this exact `session_id` + `segment_id`. The handler adds this to
+ * `countExistingSegment` so a queued-but-undistilled segment's re-POST
+ * answers 200 skipped — the client's cursor advances and the segment is
+ * never queued twice.
+ */
+export declare function countQueuedSegment(db: Database.Database, sessionId: string, segmentId: string): number;
+/**
+ * Inbox mirror of the legacy session-level precheck: how many QUEUED rows
+ * belong to this session (whole-session OR any segment) — a legacy
+ * whole-session re-POST while any part of the session sits queued skips.
+ */
+export declare function countQueuedSession(db: Database.Database, sessionId: string): number;
+/** Queue depth (rows pending distillation). */
+export declare function queueDepth(db: Database.Database): number;
+/** Age (ms) of the oldest queued item; null when the inbox is empty. */
+export declare function oldestQueueAgeMs(db: Database.Database, now?: number): number | null;
+/** The visibility shape shared by `hicortex status`, /health/detail, and the
+ *  dashboard payload: depth + oldest-item age in hours (null = empty). */
+export interface QueueStats {
+    depth: number;
+    oldest_age_hours: number | null;
+}
+export declare function readQueueStats(db: Database.Database, now?: number): QueueStats;
+/**
+ * #529 bootstrap carve-out: a FRESH brain (empty memories table AND empty
+ * inbox) distills synchronously, exactly as pre-#529 — the first-ever
+ * delivery must not wait ~12 h for the next scheduled run. Anything else
+ * (memories exist OR rows are already queued) is ordinary queue mode.
+ */
+export declare function isFreshBrain(db: Database.Database): boolean;
+/**
+ * The ONE branch condition into the sync flow (owner ruling #529: kill
+ * switch and bootstrap carve-out share it — no third path):
+ *
+ *   queueMode = distillQueue enabled && NOT a fresh brain
+ *
+ * `distillQueueEnabled` is the already-strict-boolean-resolved kill switch
+ * (`readStrictBoolean(config, "distillQueue") !== false`, default ON); false
+ * lands here always → today's synchronous distill byte-for-byte.
+ */
+export declare function resolveQueueMode(db: Database.Database, distillQueueEnabled: boolean): boolean;
+/**
+ * The structural minimum the drain needs from an LLM client: `complete()` is
+ * the ONE surface (#405). Real `LlmClient` satisfies it; tests inject a stub.
+ * (LlmClient has private fields, so it cannot be the parameter type itself —
+ * distillSession only ever calls `complete()` on the value we pass.)
+ */
+export interface DrainLlm {
+    complete(prompt: string): Promise<{
+        text: string;
+        usage?: LlmUsage;
+    }>;
+}
+/** One yield-probe outcome (the HTTP shape is the caller's concern — nightly). */
+export type YieldStatus = "busy" | "idle" | "unreachable";
+export interface DrainOptions {
+    /** The LLM client all distill calls go through (null = no LLM configured). */
+    llm: DrainLlm | null;
+    /** Its config — drives the cached chunk-size detection, like the handler. */
+    llmConfig: LlmConfig | null;
+    /** Embed fn for the distilled entries (the nightly's embedder). */
+    embed: (text: string) => Promise<Float32Array>;
+    /**
+     * #5 token-budget gate, checked BETWEEN items (and once before the first
+     * item — zero LLM calls when already over the monthly cap). Injected so the
+     * drain unit never touches state.json; the nightly passes
+     * `() => isTokenBudgetExceeded(stateDir)`.
+     */
+    budgetExceeded?: () => boolean;
+    /** The ONE run deadline (#405) — `hit("drain")` between items. */
+    deadline?: RunDeadline;
+    /**
+     * #529 yield signal: the configured `drainYieldUrl`. Absent/unset ⇒ never
+     * wait. Provided with `probeBusy`, the drain waits out "busy" answers
+     * between items (bounded by the deadline + the wait cap).
+     */
+    yieldUrl?: string;
+    /** The probe itself (HTTP lives in nightly.ts; tests inject a fake). */
+    probeBusy?: (url: string) => Promise<YieldStatus>;
+    /** Injectable clock-wait so tests exercise busy-loops instantly. */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * Injectable chunk-size detector (tests pin it; production defaults to the
+     * real detectChunkSize, cached per endpoint like the /distill handler).
+     */
+    detectChunkSize?: typeof detectChunkSize;
+}
+export interface DrainReport {
+    /**
+     * "empty" (nothing queued — the common case right after a clean run),
+     * "completed" (every item done), "deferred" (run deadline fired; the rest
+     * stays queued for the next scheduled run), "budget" (monthly token cap;
+     * zero LLM calls past the refusal), "no_llm" (no LLM configured — items
+     * stay queued, consolidation reports its own no_llm), or "endpoint_down"
+     * (the first item's distillation threw after the ladder/breaker — never a
+     * tight retry loop; processed items stay done).
+     */
+    outcome: "empty" | "completed" | "deferred" | "budget" | "no_llm" | "endpoint_down";
+    /** Items fully processed (distilled or duplicate-skipped) this run. */
+    processed: number;
+    /** Of those, items that were already stored and only had their row deleted. */
+    duplicates: number;
+    /** Memories inserted this run. */
+    memories: number;
+    /** Items still queued after this run. */
+    remaining: number;
+    /** Tokens metered this drain (incl. a failed item's partial usage). */
+    usage: {
+        prompt: number;
+        completion: number;
+        total: number;
+    };
+}
+/**
+ * Drain the distill inbox. See the module doc for the ordering + checkpoint
+ * contracts. Pure w.r.t. its injected dependencies — no HTTP, no state.json
+ * reads (the nightly records the reported usage against the monthly meter).
+ */
+export declare function drainDistillQueue(db: Database.Database, opts: DrainOptions): Promise<DrainReport>;