lossless-core 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,2019 @@
+import { Static, TSchema, Type } from "typebox";
+//#region src/assembly.d.ts
+export interface AssemblyMsg {
+  role: string;
+  content?: unknown;
+  /** AgentMessage UserMessage compatibility (Pi requires it on outgoing messages). */
+  timestamp?: number;
+}
+export interface AlignedEntry {
+  entryId: string;
+  role: string;
+  text: string;
+  /** Raw content blocks when `text` is not a faithful rendering of them
+   * (`payloadOf`). Carried so ingest stores the same bytes at every call site. */
+  payload?: string;
+  fileHint?: {
+    path: string;
+  };
+}
+export declare const SYNTHETIC_MARKER = "[LCM session memory";
+export declare function tailKeyOf(m: AssemblyMsg | undefined): string;
+/** Characters the estimator counts for a context: the same rendering `cutIndexFor`
+ * measures, so a calibration describes the quantity every threshold here is
+ * compared against. */
+export declare function contextChars(messages: readonly AssemblyMsg[]): number;
+export declare function cutIndexFor(messages: readonly AssemblyMsg[], keepRecentTokens: number): number | null;
+export interface SyntheticMessage {
+  role: "user";
+  content: string;
+  timestamp: number;
+}
+export type SummaryTier = "rich" | "terse" | "stub";
+export interface RenderableSummary {
+  id: number;
+  depth: number;
+  firstEntryId: string;
+  lastEntryId: string;
+  text: string;
+  thoroughText?: string;
+  tier: SummaryTier;
+}
+export declare const STUB_CHARS = 200;
+export type PlainSummary = Omit<RenderableSummary, "tier" | "thoroughText">;
+export declare function renderSummaries(summaries: readonly RenderableSummary[]): string;
+export declare function renderFrontier(nodes: readonly PlainSummary[]): string;
+export declare function buildSynthetic(summaries: readonly RenderableSummary[]): SyntheticMessage;
+//#endregion
+//#region src/commit-policy.d.ts
+export interface AppliedSummary {
+  id: number;
+  depth: number;
+  text: string;
+  thoroughText?: string;
+  firstEntryId: string;
+  lastEntryId: string;
+  tier: SummaryTier;
+}
+export type AssemblyAction = "quiet" | "consider-apply" | "stable" | "recommit";
+export interface CommitState {
+  cutCount: number;
+  synthetic: SyntheticMessage;
+  applied: AppliedSummary[];
+  summaryId: number;
+  appliedAtOccupancy: number;
+  tailKey: string;
+}
+export declare const DEFAULT_SWAP_RATIO = 0.7;
+export declare const DEFAULT_RECUT_RATIO = 0.85;
+export declare const WINDOW_SAFETY_CEILING = 0.9;
+/** Ceiling for the resolved recut fraction: a line above 1.0 is unreachable, so
+ * the pin never re-cuts and the raw tail grows past the window while "stable"
+ * is reported forever. Strictly above WINDOW_SAFETY_CEILING + RECUT_ABOVE_SWAP_MARGIN. */
+export declare const RECUT_CEILING = 0.95;
+export declare const REZONE_MARGIN = 1.18;
+export interface ThresholdConfig {
+  swapAtRatio?: number;
+  swapAtTokens?: number;
+  recutAtRatio?: number;
+  recutAtTokens?: number;
+  smartZone?: number;
+}
+export type ZoneThresholds = ThresholdConfig;
+export interface ResolvedThresholds {
+  swap: number;
+  recut: number;
+  clamped: boolean;
+}
+export declare function mergeZone(global: ThresholdConfig, zone?: ZoneThresholds): ThresholdConfig;
+export declare function thresholdConflicts(cfg: ThresholdConfig, scope?: string): string[];
+export declare function effectiveThresholds(cfg: ThresholdConfig, contextWindow: number): ResolvedThresholds;
+export declare function nextAction(state: CommitState | null, occupancy: number, swapRatio: number, recutRatio: number): AssemblyAction;
+export declare function cutMayReplace(previous: CommitState | null, newCutCount: number): boolean;
+//#endregion
+//#region src/metrics.d.ts
+export declare function metricsPath(): string;
+/** The metrics log, oldest generation first, so a window longer than one
+ * generation still reads as one history. */
+export declare function metricsLogFiles(): string[];
+export declare function rotateIfNeeded(path: string, maxBytes: number): void;
+export declare function pruneGenerations(path: string, keep: number): void;
+export declare function appendMetric(record: MetricRecord): void;
+export interface UsageLike {
+  input?: unknown;
+  output?: unknown;
+  cacheRead?: unknown;
+  cacheWrite?: unknown;
+  cost?: {
+    input?: unknown;
+    output?: unknown;
+    total?: unknown;
+  };
+}
+interface MetricBase {
+  /** Session tag. Absent on rows written outside a session (`gc`, `import`). */
+  session?: string;
+}
+export type MetricSpan = [string, string];
+export type SummaryStage = "leaf" | "condensed";
+export type CompactionStage = "blocking" | "async" | "direct";
+export type SummaryLevel = 1 | 2 | 3;
+/** One model's turn in a summarizer chain, in the order it was tried. */
+type SummarizerAttempt = {
+  model: string;
+  outcome: "ok" | "empty";
+} | {
+  model: string;
+  outcome: "threw";
+  error: string;
+};
+export type UsageCounters = {
+  input: number | null;
+  output: number | null;
+  cacheRead: number | null;
+  cacheWrite: number | null;
+  costInput: number | null;
+  costOutput: number | null;
+  costTotal: number | null;
+};
+/** The counters to put on a row, or `undefined` when the provider billed
+ * nothing (an aborted call, or a provider that reports no usage). */
+export declare function billedCounters(usage: UsageLike | undefined): UsageCounters | undefined;
+/** One metrics row per measured assistant message: no numeric counter at all
+ * (aborted turn, legacy row) yields `undefined`, so it does not count as a turn
+ * in the report's cache-economics averages. */
+export declare function usageRecord(usage: UsageLike | undefined): UsageRow | undefined;
+export type SummarizerStage = "blocking" | "async";
+/** Why a summarizer call failed, as far as the provider's own text says. A
+ * closed set, and `unknown` is a real answer: a classification that guesses is
+ * worse than a bucket that says it could not tell, and the raw message stays on
+ * the row either way. `capped` is not a provider failure: it is the pass giving
+ * up after too many of them, and the category beside it says which one. */
+export type SummarizerFailureCategory = "auth" | "rate-limit" | "timeout" | "unavailable" | "length" | "empty" | "capped" | "unknown";
+/** `ok` answered with usable text, `empty` answered with none, `failure` was rejected. */
+export type SummarizerOutcome = "ok" | "empty" | "failure";
+export interface SummarizerUsageOptions {
+  /** The resolved model key, as `modelKey` renders it. */
+  model: string;
+  stage?: SummarizerStage;
+  outcome: SummarizerOutcome;
+  /** The provider's own stop word, so `length` and `error` are told apart. */
+  stopReason?: string;
+  session?: string;
+}
+export type SummarizerUsageRow = UsageCounters & {
+  event: "lcm";
+  kind: "summarizer-usage";
+  model: string;
+  stage?: SummarizerStage;
+  outcome: SummarizerOutcome;
+  stopReason?: string;
+  session?: string;
+};
+/** One provider call the summarizer made. `usage` rows cannot carry it, since
+ * those come from Pi's `message_end` for the session's own messages while the
+ * summarizer talks to the model registry directly. */
+export declare function summarizerUsageRecord(usage: UsageLike | undefined, opts: SummarizerUsageOptions): SummarizerUsageRow | undefined;
+export type UsageRow = MetricBase & UsageCounters & {
+  event: "usage";
+};
+interface LcmRowBase extends MetricBase {
+  event: "lcm";
+}
+export type ContextDecisionRow = LcmRowBase & {
+  kind: "context-decision";
+  action: string;
+  occupancy: number;
+  tokens: number;
+  window: number;
+  soft: number;
+  commit: number;
+  zone?: string;
+  committed: boolean;
+  /** Present when `tokens` is the estimator's count rather than Pi's: the
+   * reported figure described a context other than the one on hand. */
+  tokensEstimated?: true;
+};
+export type ProjectionOverBudgetRow = LcmRowBase & {
+  kind: "projection-over-budget";
+  nodes: number;
+  renderedTokens: number;
+  budgetTokens: number;
+};
+export type SwapAppliedRow = LcmRowBase & {
+  kind: "swap-applied";
+  summaryId: number;
+  cutCount: number;
+  distinctBoundary: boolean;
+  appliedAtOccupancy: number;
+  nodes: number;
+  stubbed: number;
+  renderedTokens: number;
+  budgetTokens: number;
+};
+/**
+ * A swap the policy did not commit. `tokens` is the occupancy that triggered
+ * the bail; the kick-backoff writer names the entry it declined to kick instead.
+ */
+export type SwapBlockedRow = LcmRowBase & {
+  kind: "swap-blocked";
+  reason: string;
+  occupancy: number;
+  tokens?: number;
+  entryId?: string;
+};
+export type PiCompactionRow = LcmRowBase & {
+  kind: "pi-compaction";
+  entryId: string;
+  tokens?: number;
+  window?: number;
+};
+/** One calibration sample against Pi's own count: the characters this build
+ * counted for the growth of the context, the tokens Pi reported for it, and the
+ * ratio the samples now support. A null ratio is the answer "cannot say", which is
+ * why the row carries the sample beside it. */
+export type EstimateCalibratedRow = LcmRowBase & {
+  kind: "estimate-calibrated";
+  chars: number;
+  tokens: number;
+  charsPerToken: number | null;
+  samples: number;
+};
+/** A provider stated the real context window in an overflow error, which is the
+ * one window number in this system that is not a belief. */
+export type WindowCorrectedRow = LcmRowBase & {
+  kind: "window-corrected";
+  model: string;
+  window: number;
+  source: string;
+};
+/** A refused request proved the window in use was too big without naming the
+ * real one: the window for the next turn is floored at what the request carried,
+ * and `window` is the stored correction when one exists. */
+export type WindowFloorRow = LcmRowBase & {
+  kind: "window-floor";
+  tokens: number;
+  window: number | null;
+};
+export type ConfigProblemRow = LcmRowBase & {
+  kind: "config-problem";
+  problems: string[];
+};
+export type SummaryInputClippedRow = LcmRowBase & {
+  kind: "summary-input-clipped";
+  entryId: string;
+  keptChars: number;
+  droppedChars: number;
+};
+export type SummaryFallbackStoredRow = LcmRowBase & {
+  kind: "summary-fallback-stored";
+  stage: SummaryStage;
+  span: MetricSpan;
+  sourceChars: number;
+};
+export type SummaryStoredRow = LcmRowBase & {
+  kind: "summary-stored";
+  stage: SummaryStage;
+  level: SummaryLevel;
+  depth: number;
+  tokens: number;
+  summaryId: number;
+  span: MetricSpan;
+};
+export type SummarySkippedCoveredRow = LcmRowBase & {
+  kind: "summary-skipped-covered";
+  stage: SummaryStage;
+  span: MetricSpan;
+  messages: number;
+};
+export type SummarySkippedExistingRow = LcmRowBase & {
+  kind: "summary-skipped-existing";
+  stage: SummaryStage;
+  summaryId: number;
+  depth: number;
+  span: MetricSpan;
+  attemptedTokens: number;
+  existingTokens: number;
+};
+export type SummaryOversizedRow = LcmRowBase & {
+  kind: "summary-oversized";
+  stage: SummaryStage;
+  depth: number;
+  tokens: number;
+  targetTokens: number;
+  sourceTokens: number;
+  retried: boolean;
+  level: SummaryLevel;
+  span: MetricSpan;
+};
+export type SummaryReplacedRow = LcmRowBase & {
+  kind: "summary-replaced";
+  stage: SummaryStage;
+  summaryId: number;
+  beforeTokens: number;
+  afterTokens: number;
+};
+export type SummaryFinalTruncatedRow = LcmRowBase & {
+  kind: "summary-final-truncated";
+  stage: CompactionStage;
+  span: MetricSpan;
+  beforeTokens: number;
+  afterTokens: number;
+};
+export type CondensationStalledRow = LcmRowBase & {
+  kind: "condensation-stalled";
+  reason: string;
+  nodes: number;
+  minDepth: number;
+  frontierTokens: number;
+  targetTokens: number;
+  cap: number;
+};
+export type CondensationReducedRow = LcmRowBase & {
+  kind: "condensation-reduced";
+  summaryId: number;
+  depth: number;
+  level: SummaryLevel;
+  beforeTokens: number;
+  afterTokens: number;
+  targetTokens: number;
+  frontierTokens: number;
+};
+export type CompactionCompleteRow = LcmRowBase & {
+  kind: "compaction-complete";
+  leaves: number;
+  condensed: number;
+  ingested: number;
+  span: MetricSpan;
+};
+/** A summarizer call that answered with nothing, or that threw. An empty answer
+ * is its own reason, so only a throw needs the category that says why. */
+export type SummarizerErrorRow = LcmRowBase & {
+  kind: "summarizer-error";
+  level: SummaryLevel;
+  sourceChars: number;
+} & ({
+  reason: "empty-response";
+  maxTokens: number;
+} | {
+  reason: "threw";
+  error: string;
+  category: SummarizerFailureCategory;
+});
+/** A pass that stopped calling the model and finished its span with the
+ * mechanical truncate. One row per completer, not per refused call: a refusal
+ * never reaches a provider, so it is not a `summarizer-error`, and the forty
+ * calls it stands for are one fact. */
+export type SummarizerCappedRow = LcmRowBase & {
+  kind: "summarizer-capped";
+  stage?: SummarizerStage;
+  fingerprint: string;
+  /** Failed walks this completer paid for before it gave up; 0 when the span
+   * was already remembered or the refusal was a budget's. */
+  failedWalks: number;
+  category: SummarizerFailureCategory;
+  source: "pass" | "span-memory" | "budget";
+  /** Which budget refused: one request's estimate, or the pass's accumulator. */
+  reason?: "call" | "pass";
+  spentTokens?: number;
+  budgetTokens?: number;
+  span: MetricSpan;
+};
+export type SummarizerFallbackRow = LcmRowBase & {
+  kind: "summarizer-fallback";
+  attempts: SummarizerAttempt[];
+  used: string | null;
+};
+/** A configured model key that did not resolve, so a substitution is billing. */
+export type SummarizerModelRow = LcmRowBase & {
+  kind: "summarizer-model";
+  requested: string[];
+  chain: string[];
+  unresolved: string[];
+};
+/**
+ * A compaction failed. The two writers are told apart by stage: the `gc` path
+ * has a db path and no session, the hook path has a session and one of the two
+ * span handles.
+ */
+export type CompactionErrorRow = LcmRowBase & {
+  kind: "compaction-error";
+  error: string;
+} & ({
+  stage: "gc" | "migrate";
+  db: string;
+} | {
+  stage: "blocking" | "async";
+  entryId?: string;
+  spanEnd?: string;
+});
+export type CompactionAwaitedRow = LcmRowBase & {
+  kind: "compaction-awaited";
+  elapsedMs: number;
+  timedOut: boolean;
+};
+export type CompactionQueuedRow = LcmRowBase & {
+  kind: "compaction-queued";
+  entryId: string;
+  queued: number;
+};
+export type CompactionQueuedDroppedRow = LcmRowBase & {
+  kind: "compaction-queued-dropped";
+  entryId: string;
+  reason: "store-reset";
+};
+export type CompactionTimeoutClearedRow = LcmRowBase & {
+  kind: "compaction-timeout-cleared";
+  elapsedMs: number;
+};
+/** A pass whose result was computed under conditions the session no longer
+ * holds, so the rows it wrote were deleted instead of applied. `changed` is
+ * empty when only the model moved. */
+export type CompactionStaleRow = LcmRowBase & {
+  kind: "compaction-stale";
+  reason: "model-changed" | "settings-changed";
+  changed: string[];
+  stage: SummarizerStage;
+  entryId: string;
+  span: MetricSpan;
+  dropped: number;
+};
+/** Rows a pass wrote that never became memory: what a dead or stale handle left,
+ * reaped by the next run, or dropped at commit because a child they named was
+ * gone. The count is the work that has to be done again. */
+export type CompactionAbandonedRow = LcmRowBase & {
+  kind: "compaction-abandoned";
+  stage: SummarizerStage;
+  dropped: number;
+};
+/** Why a pass produced no text. `no-entries` is a span the store holds no message
+ * row for, and `covered` is one whose every message is already memory or another
+ * live run's. Neither is a failure, so neither is a `compaction-error`. */
+export type CompactionNoopReason = "no-entries" | "covered";
+/** A pass that stored nothing, with the span it was given. The walk was paid for,
+ * so the count is worth keeping even when the outcome is correct. */
+export type CompactionNoopRow = LcmRowBase & {
+  kind: "compaction-noop";
+  stage: SummarizerStage;
+  reason: CompactionNoopReason;
+  ingested: number;
+  span?: MetricSpan;
+};
+/** A store left behind by an older build, upgraded in place by `/lcm migrate` so
+ * cross-session search can read it. Only that command writes one: a search skips
+ * a store it cannot read. */
+export type StoreMigratedRow = LcmRowBase & {
+  kind: "store-migrated";
+  db: string;
+  fromGeneration: number;
+  toGeneration: number;
+};
+export type GcDeletedRow = LcmRowBase & {
+  kind: "gc-deleted";
+  db: string;
+  reason: string;
+  sizeBytes: number;
+  exportedTo: string;
+};
+export type BranchRemovedRow = LcmRowBase & {
+  kind: "branch-removed";
+  removed: number;
+  restored: number;
+};
+export type FileExternalizedRow = LcmRowBase & {
+  kind: "file-externalized";
+  entryId: string;
+  fileId: string;
+  path: string;
+  fileKind: string;
+  bytes: number;
+};
+/** A large body with no path behind it, so nothing could be externalized. */
+export type LargeInlineRow = LcmRowBase & {
+  kind: "large-inline";
+  entryId: string;
+  chars: number;
+};
+export type RecallRow = LcmRowBase & {
+  kind: "recall";
+  tool: "lcm_grep" | "lcm_describe";
+  outcome: "hit" | "miss" | "error";
+  hits?: number;
+  id?: number;
+  depth?: number;
+  tokens?: number;
+  sessionsScanned?: number;
+  sessionsSkipped?: number;
+};
+/** One procedural long-context evaluation run: the
+ * seed and size of the generated context, and whether every needle stayed
+ * reachable. `fromProjection` is what the surface a model sees already carried,
+ * `fromRecall` is what the memory had to recover, and `failed` is the count that
+ * has to stay zero. */
+export type EvalRow = LcmRowBase & {
+  kind: "eval";
+  seed: number;
+  turns: number;
+  needles: number;
+  passes: number;
+  depth: number;
+  fidelity: number;
+  fromProjection: number;
+  fromRecall: number;
+  failed: number;
+  surfaceTokens: number;
+};
+/** One bounded-reader run, with the provider calls it made. `scope` is set when
+ * the caller named a source instead of searching for it, and the id it named
+ * rides along, so an addressed read can be counted apart from a search without
+ * reading the tool's arguments back. */
+export type RetrievalRow = LcmRowBase & {
+  kind: "retrieval";
+  queryChars: number;
+  budgetTokens: number;
+  steps: number;
+  retrievedTokens: number;
+  stop: string;
+  reason?: string;
+  scope?: "summary" | "entry";
+  summaryId?: number;
+  entryId?: string;
+} & Partial<UsageCounters>;
+export type ImportRow = MetricBase & {
+  event: "lcm";
+  kind: "import";
+  db: string;
+} & ({
+  refused: string;
+} | {
+  messagesInserted: number;
+  messagesSkipped: number;
+  summariesInserted: number;
+  summariesSkipped: number;
+});
+export type LcmMetricRecord = ContextDecisionRow | ProjectionOverBudgetRow | SwapAppliedRow | SwapBlockedRow | PiCompactionRow | EstimateCalibratedRow | WindowCorrectedRow | WindowFloorRow | ConfigProblemRow | SummaryInputClippedRow | SummaryFallbackStoredRow | SummaryStoredRow | SummarySkippedCoveredRow | SummarySkippedExistingRow | SummaryOversizedRow | SummaryReplacedRow | SummaryFinalTruncatedRow | CondensationStalledRow | CondensationReducedRow | CompactionCompleteRow | SummarizerErrorRow | SummarizerCappedRow | SummarizerFallbackRow | SummarizerModelRow | SummarizerUsageRow | CompactionErrorRow | CompactionAwaitedRow | CompactionQueuedRow | CompactionQueuedDroppedRow | CompactionTimeoutClearedRow | CompactionStaleRow | CompactionAbandonedRow | CompactionNoopRow | GcDeletedRow | StoreMigratedRow | BranchRemovedRow | FileExternalizedRow | LargeInlineRow | RecallRow | RetrievalRow | EvalRow | ImportRow;
+export type MetricRecord = UsageRow | LcmMetricRecord;
+//#endregion
+//#region src/files.d.ts
+/** Characters of a body's description that stay in the preview. The message row
+ * keeps every character, so this bounds what the summarizer reads, not what is
+ * retained. */
+export declare const FILE_PREVIEW_CHARS = 1200;
+export declare const FILE_KINDS: readonly ["json", "jsonl", "csv", "tsv", "code", "text"];
+export type FileKind = (typeof FILE_KINDS)[number];
+export declare function isFileKind(value: unknown): value is FileKind;
+export interface FileDescriptor {
+  fileId: string;
+  path: string;
+  /** Characters retained in the message, not bytes on disk. */
+  bytes: number;
+  sha256: string;
+  kind: FileKind;
+  preview: string;
+}
+export declare function fileHandle(d: FileDescriptor): string;
+export declare function filePreviewText(d: FileDescriptor): string;
+export declare function describeFile(path: string, text: string): FileDescriptor;
+/** What the body is, decided by structure rather than by extension alone: a
+ * `.ts` file holding a JSON array is JSON, and a `.txt` file holding JSON is
+ * JSON too. The parse is tried before the extension for that reason. */
+export declare function kindOf(path: string, text: string): FileKind;
+export declare function structureOf(kind: FileKind, path: string, text: string): string;
+export declare function previewOf(kind: FileKind, path: string, text: string): string;
+//#endregion
+//#region src/pattern-scan.d.ts
+/** One row the pattern path scans. The text is the stored message, whole: the
+ * FTS index holds a prefix, and reading only that is the defect this path
+ * exists to fix. */
+export interface ScannedRow {
+  rowid: number;
+  entryId: string;
+  role: string;
+  text: string;
+  removed: boolean;
+}
+/** A row that matched, with the first match's position and how many the row
+ * held. `partial` is set when the row was longer than the per-row cap, so a
+ * reader knows the scan stopped before the end of that row. */
+export interface PatternHit {
+  row: ScannedRow;
+  matches: number;
+  at: number;
+  partial: boolean;
+  scannedChars: number;
+}
+export type PatternStop = "end" | "deadline" | "page";
+export interface PatternScanOutcome {
+  hits: PatternHit[];
+  rows: number;
+  partialRows: number;
+  more: boolean;
+  stopped: PatternStop;
+  lastRowId?: number;
+  lastEntryId?: string;
+}
+export interface PatternScanOptions {
+  pattern: CompiledPattern;
+  offset: number;
+  limit: number;
+  /** Characters of one row the scan reads. Above the FTS prefix on purpose,
+   * below the size of an externalized body, and named on the hit when it bites. */
+  perRowChars: number;
+  deadlineAt: number;
+  now: () => number;
+}
+/** The characters a caller can hand a regular expression. A row longer than this
+ * is read up to the cap and the hit says so: a partial scan that looks complete
+ * is the same defect as an index that stops at 100,000 characters. */
+export declare const PATTERN_ROW_CHARS = 200000;
+/** How long one pattern call may scan. Long enough for a session's messages at
+ * 200,000 characters a row, short enough that a pathological pattern is a slow
+ * call rather than a hung session. */
+export declare const PATTERN_DEADLINE_MS = 1000;
+export declare const PATTERN_PAGE_ROWS = 200;
+/** Matches counted in one row before the scan moves on. A row that mentions a
+ * path a thousand times is one hit line, and counting the thousandth costs the
+ * deadline that the next row needs. */
+export declare const MAX_MATCHES_PER_ROW = 100;
+export declare function scanRows(rows: Iterable<ScannedRow>, opts: PatternScanOptions): PatternScanOutcome;
+/** A pattern this module compiled and validated, so a scan cannot receive a
+ * caller's own stateful `RegExp`. */
+export type CompiledPattern = RegExp & {
+  readonly __brand: "CompiledPattern";
+};
+export type PatternCompileResult = {
+  ok: true;
+  pattern: CompiledPattern;
+} | {
+  ok: false;
+  reason: string;
+};
+/** Compile a caller's pattern, with `g` for iteration and `i` unless the caller
+ * asked for case sensitivity, which is the reading the FTS path already has. A
+ * refusal is returned before any row is read. */
+export declare function compilePattern(pattern: string, caseSensitive: boolean): PatternCompileResult;
+//#endregion
+//#region src/store.d.ts
+export type LcmRole = "user" | "assistant" | "toolResult" | "custom";
+/** Any role string Pi may emit (custom, branchSummary, bashExecution...) folds to the four stored roles. */
+export declare function normalizeRole(r: string): LcmRole;
+export interface StoredMessage {
+  id: number;
+  entryId: string;
+  role: LcmRole;
+  text: string;
+  tokens: number;
+  timestamp: number;
+  /** JSON of the content blocks, present only when `text` is not a faithful
+   * rendering of them (a thinking block, an image, a signature). Absent means
+   * the derived text is the whole message. */
+  payload?: string;
+  /** Set when the entry has left the active branch. The bytes stay; search
+   * excludes the row unless a caller asks for it. */
+  removedAt?: number;
+}
+export interface GrepHit {
+  entryId: string;
+  role: LcmRole;
+  text: string;
+  /** The entry has left the active branch; its text is retained. */
+  removed?: boolean;
+  coveringSummaryId?: number;
+}
+export interface SummaryNode {
+  id: number;
+  kind: "leaf" | "condensed";
+  text: string;
+  tokens: number;
+  depth: number;
+  firstEntryId: string;
+  lastEntryId: string;
+  createdAt: number;
+  /** A richer sibling text the ladder produced and did not store as primary,
+   * so the projection can serve more detail when the budget has room. */
+  thoroughText?: string;
+  thoroughTokens?: number;
+}
+export interface IntegritySnapshot {
+  ftsOk: boolean;
+  messageRows: number;
+  shapes: Array<{
+    id: number;
+    kind: "leaf" | "condensed";
+    depth: number;
+    messages: number;
+    children: number;
+  }>;
+  spans: Array<{
+    id: number;
+    first: string;
+    last: string;
+    firstRowid: number | null;
+    lastRowid: number | null;
+  }>;
+  duplicateSpans: Array<{
+    first: string;
+    last: string;
+    kind: string;
+    count: number;
+  }>;
+  orphanChildParents: number[];
+  deadRuns: Array<{
+    session: string | null;
+    rows: number[];
+  }>;
+  untrackedPending: number[];
+  foreignKeyViolations: number;
+  schemaVersion: number;
+  uncoveredMessages: number;
+}
+/** A fresh row, or the row that already owns the span; `existingTokens` comes
+ * from that row, so a caller reports the collision, not its intended write.
+ * `own` says whether the run that asked may count this row as its own and replace
+ * its text: a row it wrote, a committed row, or its own pending row. Another live
+ * run's pending row is none of those. */
+export type InsertSummaryResult = {
+  id: number;
+  created: true;
+  own: true;
+} | {
+  id: number;
+  created: false;
+  own: boolean;
+  existingTokens: number;
+  /** The colliding row's summary text. A caller whose view cannot read the row
+   * still has to answer for the span it was given, and this is that span's
+   * summary to reuse. */
+  existingText: string;
+  foreignLive: boolean;
+};
+/** What a caller hands `insertSummary`. `run` stamps the row pending for that run;
+ * without it the row is committed memory. */
+export type InsertSummaryInput = {
+  kind: "leaf" | "condensed";
+  text: string;
+  tokens: number;
+  depth: number;
+  firstEntryId: string;
+  lastEntryId: string;
+  messageIds?: number[];
+  childSummaryIds?: number[];
+  fileIds?: string[];
+  thoroughText?: string;
+  run?: string;
+};
+/** What a compaction pass needs from the store: the committed memory plus, when
+ * the pass reads through `LcmStore.forRun`, the rows of its own run. `LcmStore`
+ * satisfies this with the committed-only meaning. */
+export interface PassStore extends IngestStore {
+  /** The branch range a set of entry ids occupies: the oldest and the newest row
+   * the store holds among them, or null when it holds none. Pi's context array
+   * is not branch order (it hoists the newest compaction entry to the front),
+   * while a span is a row range, so the store, whose rows are appended in
+   * branch order, is what decides which end comes first. */
+  spanBounds(entryIds: readonly string[]): {
+    firstEntryId: string;
+    lastEntryId: string;
+  } | null;
+  uncoveredMessagesInSpan(firstEntryId: string, lastEntryId: string): StoredMessage[];
+  filesForMessages(ids: readonly number[]): Array<FileDescriptor & {
+    messageId: number;
+  }>;
+  frontier(firstEntryId: string, lastEntryId: string): SummaryNode[];
+  getSummary(id: number): SummaryNode | undefined;
+  parentSummaryIds(summaryId: number): number[];
+  fileIdsForSummaries(ids: readonly number[]): string[];
+  insertSummary(s: InsertSummaryInput): InsertSummaryResult;
+  updateSummaryText(id: number, text: string, tokens: number): void;
+  setThoroughText(id: number, thoroughText: string): void;
+}
+export interface IngestStore {
+  hasEntry(entryId: string): boolean;
+  insertMessage(m: {
+    entryId: string;
+    role: LcmRole;
+    text: string;
+    tokens: number;
+    timestamp: number;
+    payload?: string;
+  }): number;
+  insertFile(d: FileDescriptor, firstEntryId: string): void;
+  linkMessageFile(messageId: number, fileId: string): void;
+}
+/** Characters of a message the full-text index covers. Storage is verbatim, so
+ * this bounds the index and not the row. */
+export declare const FTS_PREFIX_CHARS = 100000;
+/** First published schema: pre-publish development stores were wiped, so every
+ * store in the wild starts here and later generations count from this one. */
+export declare const SCHEMA_VERSION = 1;
+/** A store left behind by an older build. A read-only open refuses it rather than
+ * migrating it: a search must not rewrite a file it is only reading, and a store
+ * that cannot answer this build's statements has to be a reported skip. */
+export declare class StaleStoreError extends Error {
+  readonly generation: number;
+  constructor(generation: number);
+}
+/** What a store knows about a model rather than about a session: the token ratio
+ * measured for it against Pi's reported usage, and the context window a provider
+ * stated when it refused an over-window request. A null ratio is a measurement that
+ * disagree with itself, which is a state the estimator reads as "keep the
+ * constant" and the report names. A null window is a model no provider has
+ * corrected, which leaves Pi's belief in place. */
+export interface ModelState {
+  charsPerToken: number | null;
+  samples: number;
+  contextWindow: number | null;
+  windowSource: string | null;
+}
+export declare const WINDOW_SOURCE_PROVIDER = "provider-error";
+export declare class LcmStore {
+  private db;
+  private dbPath;
+  /** Opened for reading a past session's store: no migration ran, so `generation`
+   * is the file's own and a caller may have to skip it. */
+  private readOnly;
+  /** The schema generation this file carries, which read-only opens do not
+   * change. A writer holds `SCHEMA_VERSION` by the time its constructor returns. */
+  readonly generation: number;
+  /** True while a `transaction` callback is running, so a reentrant call joins
+   * the open transaction instead of nesting one, which SQLite rejects. */
+  private inTransaction;
+  /** Tokens of the runs this handle has open. Two runs can overlap inside one
+   * handle, because the blocking path stops waiting for the async pass, so a
+   * token names a run and not the handle. Whether a run this handle does not
+   * hold is still running is read from the `runs` table, never from here. */
+  private liveTokens;
+  private reapedInRun;
+  private stmts;
+  constructor(dbPath: string, opts?: {
+    readOnly?: boolean;
+    queryOnly?: boolean;
+  });
+  /** Close the handle: no run of this handle survives it, and the connection is
+   * released even when a run could not be abandoned, so a failure here cannot
+   * leave a connection and a set of invisible rows behind. */
+  close(): void;
+  /** Open a run: rows written with its token are pending until `commitRun`, and
+   * the row this writes is what lets another handle tell it from a run whose
+   * writer is gone. Reaps what such a run left, which this handle cannot be. */
+  openRun(opts?: {
+    session?: string;
+  }): {
+    token: string;
+    dropped: number;
+  };
+  /** True while any run is open whose writer is still there, this handle's or
+   * another process's, which is what an import has to wait for. */
+  hasLiveRun(): boolean;
+  /** Commit a run: drop its pending rows whose child no longer resolves, then flip
+   * the rest. One transaction, so a reader never sees a half-committed run, and
+   * idempotent for a token this handle no longer holds. */
+  commitRun(token: string): {
+    committed: number;
+    dropped: number;
+  };
+  /** Delete a run's pending rows and close it. Idempotent, so a `finally` can call
+   * it after a commit has already closed the run. */
+  abandonRun(token: string): number;
+  /** A view of this store for one run: the committed memory plus that run's own
+   * rows, which is what a pass must read to see its own writes. */
+  forRun(token: string): PassStore;
+  /** True while the run that wrote a row is still going somewhere, as far as this
+   * store can tell. A run this handle holds is live; a run written by this
+   * process is live, because a pid cannot separate two handles in one process and
+   * refusing to delete is the safe answer; a run written by another process is
+   * live while its pid is. A row whose run has no record at all was written
+   * without one, which no open path does, so nothing owns it. */
+  private isRunLive;
+  /** Delete what a run left behind whose writer is gone, and its record with it.
+   * A live owner's rows are never touched, whatever handle asks, which is what
+   * makes a second handle safe to open. No reader can see the rows this removes,
+   * and each one holds the span it claims. */
+  private reapPending;
+  /** Delete this run's pending rows whose child no longer exists, deepest first: a
+   * parent that loses a child must not leave a grandparent behind. A child can go
+   * away between the frontier read that selected it and this commit. */
+  private dropUnresolvable;
+  hasEntry(entryId: string): boolean;
+  insertMessage(m: {
+    entryId: string;
+    role: LcmRole;
+    text: string;
+    tokens: number;
+    timestamp: number;
+    payload?: string;
+  }): number;
+  /** One write transaction around a group of statements, so a compaction is
+   * atomic: the node row, its provenance rows and its file links either all
+   * land or none do. `node:sqlite` ships no transaction helper, so the
+   * statements are explicit. A reentrant call joins the open transaction: the
+   * caller that opened it owns the commit, so an inner throw rolls the whole
+   * group back rather than leaving a half-applied write. */
+  transaction<T>(fn: () => T): T;
+  insertSummary(s: InsertSummaryInput): InsertSummaryResult;
+  insertFile(d: FileDescriptor, firstEntryId: string): void;
+  linkMessageFile(messageId: number, fileId: string): void;
+  filesForMessages(ids: readonly number[]): Array<FileDescriptor & {
+    messageId: number;
+  }>;
+  fileIdsForMessages(ids: readonly number[]): string[];
+  fileIdsForSummaries(ids: readonly number[]): string[];
+  filesForSummaries(ids: readonly number[]): FileDescriptor[];
+  allFiles(): Array<FileDescriptor & {
+    entryIds: string[];
+  }>;
+  /** Replace a node's text in place: the span, provenance, and created_at stay. */
+  updateSummaryText(id: number, text: string, tokens: number): void;
+  setThoroughText(id: number, thoroughText: string): void;
+  messagesInSpan(firstEntryId: string, lastEntryId: string): StoredMessage[];
+  spanBounds(entryIds: readonly string[]): {
+    firstEntryId: string;
+    lastEntryId: string;
+  } | null;
+  uncoveredMessagesInSpan(firstEntryId: string, lastEntryId: string, run?: string): StoredMessage[];
+  /** Minimal top-level cover: no summary's child, oldest first, dropping any node
+   * whose span sits inside the previous kept one, which is what keeps the cover
+   * non-nested: condensation's group span must be one no row already holds. */
+  frontier(firstEntryId: string, lastEntryId: string, run?: string): SummaryNode[];
+  grep(pattern: string, opts?: {
+    limit?: number;
+    offset?: number;
+    withinMessageIds?: ReadonlySet<number>;
+    includeRemoved?: boolean;
+  }): GrepHit[];
+  grepCount(pattern: string, opts?: {
+    withinMessageIds?: ReadonlySet<number>;
+    includeRemoved?: boolean;
+  }): number | undefined;
+  messagePage(afterRowId: number, limit: number, opts?: {
+    withinMessageIds?: ReadonlySet<number>;
+    includeRemoved?: boolean;
+  }): ScannedRow[];
+  coveringSummaryId(entryId: string): number | undefined;
+  messageByEntryId(entryId: string): StoredMessage | undefined;
+  parentSummaryIds(summaryId: number, run?: string): number[];
+  childSummaryIds(summaryId: number): number[];
+  getSummary(id: number, run?: string): SummaryNode | undefined;
+  /** Bounded by a visited set, so a corrupt cycle cannot recurse forever. */
+  coveredMessageIds(summaryId: number, seen?: Set<number>): number[];
+  integritySnapshot(): IntegritySnapshot;
+  /** Restore the full-text index. The schema is re-applied first, because a
+   * dropped virtual table cannot be rebuilt, only recreated, and the DDL that
+   * knows how is the schema itself. Everything in it is `IF NOT EXISTS` apart
+   * from the two triggers, which are dropped and recreated on purpose. */
+  rebuildFts(): void;
+  deleteOrphanSpans(): number;
+  deleteOrphanChildren(): number;
+  reapDeadRuns(): number;
+  /** When one span is claimed twice, the row that carries provenance wins over
+   * one that cannot be expanded, and the newest wins between equals. */
+  dedupeSpans(): number;
+  /** Mark entries that left the active branch, or clear the mark when a
+   * navigation brings them back. Returns the rows the call actually changed, so
+   * a metric can tell a real change from a no-op reconciliation. */
+  setRemoved(entryIds: readonly string[], removedAt: number | null): number;
+  removedMessageCount(): number;
+  messagesByIds(ids: number[]): StoredMessage[];
+  allMessages(): StoredMessage[];
+  entrySpan(): {
+    first: string;
+    last: string;
+  } | undefined;
+  coveredSize(summaryId: number): {
+    tokens: number;
+    messages: number;
+  };
+  allSummaries(): SummaryNode[];
+  messageCount(): number;
+  backup(backupPath: string): void;
+  /** The calibration recorded for a model. `undefined` is a model nothing has
+   * sampled; a null ratio is one whose samples disagreed, which the caller reads
+   * as "keep the constant" rather than "no data". */
+  getModelState(modelKey: string): ModelState | undefined;
+  setModelState(modelKey: string, state: Pick<ModelState, "charsPerToken" | "samples">): void;
+  /** Records the window a provider stated. Its own statement rather than part of
+   * `setModelState`, because the two are learned at different moments: a later
+   * calibration must not clear a window, and a window must not touch samples. */
+  setModelWindow(modelKey: string, contextWindow: number, source: string): void;
+  stats(): {
+    messages: number;
+    summaries: number;
+    dbBytes: number;
+    payloadMessages: number;
+    payloadBytes: number;
+    files: number;
+    fileBytes: number;
+    removedMessages: number;
+  };
+}
+//#endregion
+//#region src/summarize.d.ts
+export interface LlmComplete {
+  (systemPrompt: string, userText: string, maxTokens: number): Promise<string>;
+}
+export interface EscalationResult {
+  text: string;
+  level: 1 | 2 | 3;
+  sourceTokens: number;
+  retried: boolean;
+  thoroughText?: string;
+}
+export declare function summarizeWithEscalation(items: Array<{
+  role: string;
+  text: string;
+}>, targetTokens: number, llm: LlmComplete, session?: string): Promise<EscalationResult>;
+/** Summarize with the terse rung only, for a source that is already a summary:
+ * the thorough ladder would spend two provider calls re-summarizing text that
+ * was made thorough once. Here the terse answer is the only ask, so a result
+ * that does not reduce the source falls to the deterministic truncate. */
+export declare function summarizeTerse(items: Array<{
+  role: string;
+  text: string;
+}>, targetTokens: number, llm: LlmComplete, session?: string): Promise<EscalationResult>;
+export declare function deterministicTruncate(text: string, targetTokens: number): string;
+//#endregion
+//#region src/compaction-engine.d.ts
+/** Deepest condensed node the DAG may grow. With MAX_DAG_FANOUT children this
+ * covers 8^8 leaf chunks, so it is a structural assert, not a tuning knob: a
+ * pass that cannot meet its budget reports `condensation-stalled` rather than
+ * stopping here silently. */
+export declare const MAX_DAG_DEPTH = 8;
+export declare const MAX_DAG_FANOUT = 8;
+export interface CompactionSpanEntry {
+  entryId: string;
+  role: LcmRole;
+  text: string;
+  payload?: string;
+}
+export interface CompactionInput {
+  span: readonly CompactionSpanEntry[];
+  previousSummary?: string;
+  targetTokens?: number;
+  /** Where the returned summary must reach back to; defaults to the span start. */
+  frontierFrom?: string;
+}
+export type CompactionOutcome = {
+  kind: "stored";
+  summaryText: string;
+  leafSummaryIds: number[];
+  condensedSummaryIds: number[];
+  ingested: number;
+} |
+/** No text, and why. A span another live run claimed, a span an existing node
+ * already covers, and a span the store holds no row for are all states a pass
+ * is allowed to find itself in, so the caller decides what to do with the state
+ * instead of receiving a throw. A pass in this state stored nothing: every row
+ * it writes sits inside the span it renders.
+ */
+{
+  kind: "nothing";
+  reason: CompactionNoopReason;
+  ingested: number;
+};
+export declare function runCompaction(store: PassStore, input: CompactionInput, llm: LlmComplete, opts?: {
+  leafChunkTokens?: number;
+  maxChunks?: number;
+  /** Masks stored text on its way to a model: the summarizer input, every
+   * recall view, and the summary this pass stores. It never changes what is
+   * written to the messages table. */
+  redact?: (text: string) => string;
+  /** Session tag for every metric this pass writes; without it a
+   * fallback event cannot be attributed to a session. */
+  session?: string;
+  maxDepth?: number;
+  stage?: "blocking" | "async" | "direct";
+}): Promise<CompactionOutcome>;
+/** The next group to condense: the oldest run of adjacent same-depth nodes, at
+ * the shallowest depth with a run of two or more, capped at MAX_DAG_FANOUT.
+ * Shallowest first keeps the tree balanced and the depth cap unreachable, since
+ * a parent mixing depths grows the frontier instead of shrinking it. */
+export declare function condensationGroup(frontier: readonly SummaryNode[], opts?: {
+  maxDepth?: number;
+}): SummaryNode[] | undefined;
+//#endregion
+//#region src/context-policy.d.ts
+export interface ContextPolicyInput {
+  rawMessages: readonly AssemblyMsg[];
+  getCtxEntries: () => readonly AlignedEntry[];
+  occupancy: number;
+  tokens: number;
+  /** True when `tokens` is the estimator's count rather than Pi's, because the
+   * reported figure described a context other than the one on hand. */
+  tokensEstimated?: true;
+  contextWindow: number;
+  /** The window the ratio thresholds are measured against, when it differs from
+   * Pi's belief: a correction from a provider's overflow error, or the one-shot
+   * floor a refused request proved. The belief stays in `contextWindow` because a
+   * correction is not a window change the pin should be dropped over. */
+  thresholdWindow?: number;
+  modelKey: string;
+  zone?: string;
+  thresholds: ThresholdConfig;
+  keepRecentTokens: number;
+  summaryTokens: number;
+  clampNotified: boolean;
+  commitState: CommitState | null;
+  pinnedModelKey: string;
+  pinnedWindow: number;
+}
+export type BailReason = "nothing-to-age" | "no-boundary" | "tail-exceeds-entries" | "aged-empty" | "aged-unstored" | "monotonic-refused" | "tail-shrunk" | "tail-mismatch" | "projection-over-budget";
+export type NonEmpty<T> = readonly [T, ...T[]];
+export interface ContextPolicyBase {
+  commitState: CommitState | null;
+  metrics: LcmMetricRecord[];
+  pinnedModelKey: string;
+  pinnedWindow: number;
+  clampNotified: boolean;
+  clampWarning?: string;
+}
+export type ContextPolicyResult = ContextPolicyBase & ({
+  outcome: "quiet";
+} | {
+  outcome: "reapply";
+  messages: AssemblyMsg[];
+} | {
+  outcome: "swap";
+  messages: AssemblyMsg[];
+} | {
+  outcome: "bail";
+  reason: BailReason;
+  messages?: AssemblyMsg[];
+} | {
+  outcome: "kick";
+  reason: "summary-missing";
+  aged: NonEmpty<AlignedEntry>;
+  /** The span this kick is about, in the order the store resolves one. The
+   * adapter keys its latch on it, so the latch and the coverage check
+   * cannot disagree about which boundary is missing. */
+  span: {
+    firstEntryId: string;
+    lastEntryId: string;
+  };
+  messages?: AssemblyMsg[];
+});
+export interface ContextPolicyDeps {
+  thresholds: (cfg: ThresholdConfig, window: number) => ResolvedThresholds;
+  nextAction: (state: CommitState | null, occupancy: number, swap: number, recut: number) => AssemblyAction;
+  cutIndexFor: (msgs: readonly AssemblyMsg[], keepRecentTokens: number) => number | null;
+  cutMayReplace: (previous: CommitState | null, newCutCount: number) => boolean;
+  frontier: (firstEntryId: string, lastEntryId: string) => SummaryNode[];
+  /** The aged set's own ends as a span: branch order, and only entries the store
+   * holds. Pi's context array is not branch order (it hoists the newest
+   * compaction entry to the front), and a span whose ends are inverted resolves
+   * to nothing, so this answers with the end pair a store query can use. Null
+   * when the store holds none of the aged entries, which is a state rather than
+   * a kick. */
+  spanBounds: (aged: NonEmpty<AlignedEntry>) => {
+    firstEntryId: string;
+    lastEntryId: string;
+  } | null;
+  buildSynthetic: (summaries: readonly RenderableSummary[]) => CommitState["synthetic"];
+  /** The mask node text passes through on its way to a model. The store keeps
+   * the bytes, so every read seam takes this rather than storing a masked
+   * copy; `makeRedact` is the provider a real caller passes. */
+  redact: (text: string) => string;
+}
+export interface FailedBoundary {
+  attempts: number;
+  lastAt: number;
+}
+export declare const KICK_MAX_ATTEMPTS = 3;
+export declare const KICK_BACKOFF_MS: number;
+export declare function shouldKickBoundary(latch: FailedBoundary | undefined, now: number): boolean;
+export declare function applyContextPolicy(input: ContextPolicyInput, deps: ContextPolicyDeps): ContextPolicyResult;
+export interface CompactionBounds {
+  startEntryId?: string;
+  firstKeptEntryId: string;
+}
+/** Blocking-regime span (session_before_compact), computed the way Pi's
+ * prepareCompaction does: branch entries from the previous compaction's first
+ * kept entry up to but excluding the new one, minus compaction rows. Entry ids,
+ * not message text, so bash and branch-summary rows align. An unknown
+ * firstKeptEntryId yields an empty span, so the caller falls back to Pi. */
+export declare function resolveCompactionSpan(branchMsgs: readonly AlignedEntry[], bounds: CompactionBounds): AlignedEntry[];
+//#endregion
+//#region src/integrity.d.ts
+export type FindingKind = "fts-index" | "summary-span" | "summary-shape" | "orphan-child" | "duplicate-span" | "foreign-key" | "schema-version" | "dead-run" | "coverage";
+export interface Finding {
+  kind: FindingKind;
+  /** `violation` is an invariant the DAG depends on; `coverage` is a count. */
+  severity: "violation" | "info";
+  count: number;
+  detail: string;
+  sample: string[];
+}
+export interface IntegrityReport {
+  /** How many checks ran, so "no findings" cannot be confused with "no checks". */
+  checks: number;
+  findings: Finding[];
+}
+export declare function checkIntegrity(store: LcmStore): IntegrityReport;
+/** Fix what can be fixed without guessing: the derived index, rows whose span no
+ * longer exists, nodes whose child no longer resolves, rows a run whose writer is
+ * gone left behind, and predated duplicate spans. An inverted span is left
+ * alone, because which end is right needs the session file. */
+export declare function repairIntegrity(store: LcmStore): string[];
+//#endregion
+//#region src/host.d.ts
+/** What one call was billed, in numbers, so a pass can sum its spend.
+ * `UsageLike` in `metrics.ts` is the tolerant reader of the same facts at the
+ * metrics boundary, and a `Usage` satisfies it. */
+export interface Usage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  /** A subset of `cacheWrite`, reported by hosts that split retention. */
+  cacheWrite1h?: number;
+  /** A subset of `output`, reported by hosts that expose the breakdown. */
+  reasoning?: number;
+  totalTokens: number;
+  cost: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    total: number;
+  };
+}
+/** How core tells the operator something. A host with no UI is `none` rather
+ * than a dropped callback, so a caller has one branch and no optional to miss. */
+export type Notices = {
+  readonly kind: "none";
+} | {
+  readonly kind: "ui";
+  notify(text: string, level: "info" | "warning"): void;
+};
+/** One model the host can call. `key` is the spelling config zones and metric
+ * rows already use; `model` is the host's own handle, opaque here. */
+export interface ModelRef<Model> {
+  readonly key: string;
+  readonly reasoning: boolean;
+  readonly model: Model;
+}
+export interface ModelRequest {
+  readonly provider: string;
+  readonly id: string;
+}
+export interface CompletionRequest {
+  readonly prompt: string;
+  readonly maxTokens: number;
+}
+/** What a call came back with. `stop` is the host's own word, kept verbatim for
+ * metric rows; `capped` is the host saying the answer was cut short, which is
+ * the one thing a caller must never store. */
+export type ModelAnswer = {
+  outcome: "answer";
+  text: string;
+  stop: string;
+  usage: Usage | undefined;
+} | {
+  outcome: "failed";
+  reason: string;
+  capped: boolean;
+  stop: string;
+  usage: Usage | undefined;
+};
+export interface ModelHost<Model> {
+  readonly notices: Notices;
+  session(): ModelRef<Model> | undefined;
+  find(requested: ModelRequest): ModelRef<Model> | undefined;
+  complete(model: ModelRef<Model>, request: CompletionRequest): Promise<ModelAnswer>;
+}
+/** A tool the reader may call. The schema is the host's, passed through rather
+ * than rebuilt. */
+export interface ReaderTool {
+  name: string;
+  description: string;
+  parameters: TSchema;
+}
+export interface ReaderCall {
+  readonly id: string;
+  readonly name: string;
+  readonly arguments: Record<string, unknown>;
+}
+export interface ReaderResult {
+  readonly call: ReaderCall;
+  readonly text: string;
+}
+/** What one reader step produced. `reads` asks the caller to run the calls;
+ * `answered` means the reader is done, with whatever text it accumulated. */
+export type ReaderReply = {
+  outcome: "reads";
+  calls: readonly ReaderCall[];
+  text: string;
+  usage: Usage | undefined;
+} | {
+  outcome: "answered";
+  text: string;
+  usage: Usage | undefined;
+} | {
+  outcome: "failed";
+  reason: string;
+  usage: Usage | undefined;
+};
+export interface ReaderRequest {
+  readonly systemPrompt: string;
+  readonly brief: string;
+  readonly tools: readonly ReaderTool[];
+}
+/** One reader conversation. The host owns the transcript: `next` appends the
+ * results it is handed, appends its own reply, and calls the model. */
+export interface Reading {
+  next(results: readonly ReaderResult[]): Promise<ReaderReply>;
+}
+export interface Reader {
+  begin(request: ReaderRequest): Reading;
+}
+//#endregion
+//#region src/llm.d.ts
+export interface SummarizerConfig {
+  /** One model id, or an ordered fallback chain. `auto` is the session model. */
+  summarizer?: string | string[];
+  /** Tokens one request may cost, estimate plus output cap, before it is refused
+   * rather than paid for. A backstop, not a throttle. */
+  summarizerTokensPerCall?: number;
+  /** Tokens one pass may spend across all its calls, counted from what the
+   * provider reported. Reaching it finishes the pass mechanically. */
+  summarizerTokensPerPass?: number;
+}
+/**
+ * Thinking tokens are charged against the completion budget, so a reasoning
+ * model can spend the whole cap before it emits any text. The headroom sits on
+ * top of the caller's request, so the requested output size does not change.
+ */
+export declare const REASONING_HEADROOM = 4096;
+export interface ResolvedChain<Model> {
+  /** The models to try, in order and deduped. Empty when nothing resolves. */
+  models: ModelRef<Model>[];
+  /** Configured entries the host could not resolve, in order. */
+  unresolved: string[];
+  requested: string[];
+}
+/** Expand the configured chain: `auto` (the session model) goes last unless the
+ * chain names it, so one bad entry still leaves the session able to summarize. */
+export declare function resolveModels<Model>(host: ModelHost<Model>, config: SummarizerConfig): ResolvedChain<Model>;
+/** The one rendering of a resolved chain. The level travels with the warning so
+ * no caller can pick a different notify level for the same chain. */
+export type ChainReport = {
+  level: "info";
+  state: string;
+} | {
+  level: "warning";
+  state: string;
+  warning: string;
+};
+export declare function describeSummarizerChain<Model>(chain: ResolvedChain<Model>): ChainReport;
+/** The span every call from one completer summarizes. The failure cap is per
+ * span, so a completer is built with the span it will be asked about. */
+export interface SummarizedSpan {
+  firstEntryId: string;
+  lastEntryId: string;
+}
+export interface MakeLlmOptions {
+  session: string;
+  stage?: SummarizerStage;
+  span: SummarizedSpan;
+}
+/** Failed walks in a row before a pass stops calling the model and lets the
+ * ladder's deterministic truncate finish the span. One is too eager, because a
+ * single transport blip would turn a whole span mechanical; past three, another
+ * call carries no new information about the provider and costs its latency. */
+export declare const SUMMARIZER_FAILURE_CAP = 3;
+/** What one request may cost before it is refused instead of paid for. It exists
+ * for a pathological chunk rather than for a normal one. */
+export declare const SUMMARIZER_CALL_TOKENS = 60000;
+/** What one pass may spend across all of its calls. */
+export declare const SUMMARIZER_PASS_TOKENS = 250000;
+export declare function retriableCategory(category: SummarizerFailureCategory): boolean;
+/** How long a span whose calls were capped is left alone. Shorter than the kick
+ * backoff (`KICK_BACKOFF_MS`) on purpose: this guards a retry inside one turn,
+ * it is not the breaker that stops re-kicks across turns. */
+export declare const FAILED_SPAN_TTL_MS = 60000;
+/** What a failed span is identified by: the two ends a caller asked about and
+ * the chain it asked. A different model is a different attempt, not the same
+ * failure, so the chain is part of the key. */
+export declare function spanFingerprint(span: SummarizedSpan, chain: readonly string[]): string;
+/**
+ * A call that reached no usable answer. `category` is what the provider's own
+ * text says: a best-effort read that answers `unknown` rather than guessing, and
+ * `capped` when the caller should stop asking rather than the provider failing.
+ */
+export declare class SummarizerFailure extends Error {
+  readonly category: SummarizerFailureCategory;
+  constructor(message: string, category: SummarizerFailureCategory);
+}
+/** Which bucket a provider's error text falls in. A 5xx or a dropped connection
+ * is `unavailable` before it is `timeout`, because the gateway's own timeout is
+ * a request that never reached a model. */
+export declare function classifyFailure(text: string | undefined): SummarizerFailureCategory;
+export declare function makeLlm<Model>(host: ModelHost<Model>, config: SummarizerConfig, opts: MakeLlmOptions): ((systemPrompt: string, userText: string, maxTokens: number) => Promise<string>) | null;
+/** Sessions share the process, so each one gets to see the config it runs, and
+ * a session that starts fresh should not inherit a refusal from the last one. */
+export declare function resetSummarizerState(): void;
+//#endregion
+//#region src/report.d.ts
+type Row = MetricRecord;
+type KeysOf<T> = T extends unknown ? keyof T : never;
+type ValueOf<T, K> = T extends unknown ? (K extends keyof T ? T[K] : never) : never;
+type AnyField = KeysOf<Row>;
+type FieldOf<K extends AnyField> = ValueOf<Row, K>;
+type RowFields = { [K in AnyField]?: FieldOf<K>; };
+export type MetricsEvent = RowFields & {
+  ts?: number;
+  [key: string]: unknown;
+};
+export declare function collectMetricsEvents(): MetricsEvent[];
+export interface DepthStat {
+  depth: number;
+  count: number;
+  totalTokens: number;
+  avgTokens: number;
+}
+export declare function depthStats(summaries: readonly {
+  depth: number;
+  tokens: number;
+}[]): DepthStat[];
+export declare function buildReport(events: readonly MetricsEvent[]): string;
+//#endregion
+//#region src/diagnose.d.ts
+export interface FactConfig {
+  swapAtTokens?: number;
+  recutAtTokens?: number;
+  smartZone?: number;
+  swapAtRatio?: number;
+  recutAtRatio?: number;
+  assemblyEnabled?: boolean;
+}
+export interface SessionFacts {
+  stats: ReturnType<LcmStore["stats"]>;
+  integrity: {
+    checks: number;
+    findings: Finding[];
+    repairs: string[];
+  };
+  depthRows: DepthStat[];
+  pin: CommitState | null;
+  model: string;
+  window: {
+    tokens: number;
+    effective: ResolvedThresholds;
+  } | null;
+  chain: ChainReport;
+  zoneConfigured: boolean;
+  config: FactConfig;
+  keepRecentTokens: number;
+  configPath?: string;
+}
+/**
+ * The store, projection and model facts, in the order both readers print them.
+ * Generated from numbers and config values, so nothing here needs a mask: no
+ * line can carry a character a session produced.
+ */
+export declare function sessionFactLines(f: SessionFacts): string[];
+export declare const MAX_METRIC_ROWS = 25;
+export declare const MAX_BUNDLE_BYTES = 8192;
+export interface DiagnoseBundleInput {
+  /** Resolved at print time, so a package that moved still names its version.
+   * Each is a label the host composes, `name version`, because this core names
+   * no product: the header a second harness prints names that harness. */
+  versions: {
+    plugin: () => string;
+    host: () => string;
+  };
+  runtime: {
+    node: string;
+    platform: string;
+    arch: string;
+    mode: string;
+  };
+  /** Basenames and a version, never a path. */
+  session: {
+    store: string;
+    file: string;
+    format: string;
+  };
+  facts: SessionFacts;
+  config: {
+    effective: string;
+    path: string;
+  };
+  /** Every metrics row for this session, oldest first. The bundle takes the
+   * tail, so it does not have to guess how many there are. */
+  metrics: readonly Record<string, unknown>[];
+  redact: (text: string) => string;
+  home: string;
+}
+/** The block a reporter pastes. Generated lines and foreign strings are kept
+ * apart: a line this module builds is never masked, because masking is what
+ * turns `modelKey` into `[REDACTED]`, and a value that came from outside is
+ * always masked. Absolute paths get one of two treatments: `~` inside the home
+ * directory, `<path>` outside it. */
+export declare function buildDiagnoseBundle(input: DiagnoseBundleInput): string;
+export declare function sanitizeRow(row: Record<string, unknown>, redact: (text: string) => string, home: string): Record<string, unknown>;
+/** The session file's format version, from the header line Pi rewrites on every
+ * flush. A file that is missing, unreadable or not a session header renders the
+ * honest fallback rather than a wrong number. */
+export declare function readSessionFormat(sessionFile: string | undefined): string;
+/** The host package's version, resolved from the caller's own module
+ * (`import.meta.url`); a bundled engine cannot know where its host lives. */
+export declare function hostVersion(hostPackage: string, from: string | URL): string;
+/** The `version` of the nearest `package.json` named `name`, walking up from the
+ * directory holding `from`. A manifest that is missing, unreadable, unparsable
+ * or named something else is not the answer, so a wrong anchor fails the name
+ * check instead of reporting a stranger's version. */
+export declare function packageVersionNear(from: string, name: string): string | undefined;
+//#endregion
+//#region src/estimate-tokens.d.ts
+export declare const CHARS_PER_TOKEN = 4;
+/** Samples below this count say nothing: with two points any line fits, and the
+ * first turns of a session are exactly where the overhead has not cancelled. */
+export declare const CALIBRATION_MIN_SAMPLES = 3;
+/** Samples kept in memory. A cap keeps the median describing the recent turns of
+ * the session rather than its whole history, which is what a model switch inside
+ * one session would otherwise be unable to move. */
+export declare const CALIBRATION_SAMPLE_CAP = 8;
+/** One observation of the same session: how many characters this build counted in
+ * the messages, and how many tokens Pi reported for the request that carried
+ * them. Sampling differences rather than totals is what cancels the system prompt
+ * and tool definitions, which this build never counts. */
+export interface EstimateSample {
+  chars: number;
+  tokens: number;
+}
+export declare function estimateTokens(text: string): number;
+export declare function tokensFromChars(chars: number): number;
+/** A reported count below this share of the estimate describes a context other
+ * than the one on hand: Pi reports its last measurement, and after a resume that
+ * measurement belongs to the previous process. The estimator's own error is
+ * bounded by the calibration band, which is a factor of two in either direction
+ * around the constant, so anything below a quarter is a different turn rather
+ * than a miscount. A reported count too high only compacts early, which is why
+ * this looks one way. */
+export declare const STALE_REPORT_SHARE = 0.25;
+export declare function calibrate(samples: readonly EstimateSample[]): number | null;
+/** A configured token budget in the units `estimateTokens` counts. The estimator
+ * counts chars / 4, so a model whose real ratio is 6 needs 1.5 times the
+ * configured number of estimated tokens accumulated before it has kept the
+ * context the user asked for. Without a ratio the budget is left alone, which is
+ * the constant's own reading of it. */
+export declare function scaledBudget(tokens: number, charsPerToken: number | null): number;
+//#endregion
+//#region src/eval.d.ts
+/** The seed CI runs. Fixed, so a change in the answer is a change in the engine
+ * rather than a change in the fixture. */
+export declare const SMALL_SEED = 20260915;
+export interface EvalOptions {
+  seed: number;
+  turns: number;
+  needles: number;
+  fillerChars: number;
+}
+export interface EvalNeedle {
+  id: string;
+  entryId: string;
+  value: number;
+  /** The exact text stored in the entry, `N07=4821`. */
+  line: string;
+}
+export interface EvalFixture {
+  seed: number;
+  entries: Array<{
+    entryId: string;
+    role: LcmRole;
+    text: string;
+    timestamp: number;
+  }>;
+  needles: EvalNeedle[];
+  key: {
+    needles: number;
+    sum: number;
+  };
+}
+/** mulberry32: 32 bits of state, integer output, no dependency. The generator is
+ * the fixture, so it has to be as frozen as the seed. */
+export declare function seededRandom(seed: number): () => number;
+/** Context of any length, with the answer key beside it. Needles are spread
+ * across the turns rather than clustered at one end, so a pass that walks the
+ * oldest span first meets needles at every depth. */
+export declare function generateContext(opts: EvalOptions): EvalFixture;
+/** How many uncovered messages one pass takes. Wide enough that a pass writes
+ * several leaf chunks and then condenses them, so "N compactions" exercises the
+ * DAG's second level and not only its first. */
+export declare const EVAL_SPAN_MESSAGES = 24;
+export declare const EVAL_LEAF_CHUNK_TOKENS = 2000;
+/** The token budget the pass must fit its frontier into, small on purpose: it is
+ * what makes a pass condense the leaves it just wrote. */
+export declare const EVAL_TARGET_TOKENS = 400;
+export interface EvalResult {
+  seed: number;
+  turns: number;
+  needles: number;
+  passes: number;
+  depth: number;
+  summaries: number;
+  condensed: number;
+  fidelity: number;
+  covered: number;
+  readable: number;
+  fromProjection: number;
+  fromRecall: number;
+  failed: number;
+  surfaceTokens: number;
+  answered: boolean;
+}
+export interface EvalRunOptions {
+  passes: number;
+  dbPath?: string;
+  record?: boolean;
+}
+export declare function runEval(opts: EvalOptions, run: EvalRunOptions): Promise<EvalResult>;
+export declare function formatEvalTable(results: readonly EvalResult[]): string;
+//#endregion
+//#region src/export.d.ts
+/** The format this build writes, and the only one it reads. A range reads as a
+ * compatibility promise while the row readers ignore the number, and the store,
+ * not the file, holds the truth: a file that does not fit is re-exported. */
+export declare const EXPORT_VERSION = 1;
+/** A message row: the store's numeric id is not portable, so the entry id is
+ * the handle an importer resolves through. */
+export interface ExportMessageRow {
+  v: number;
+  rowType: "message";
+  entryId: string;
+  role: LcmRole;
+  text: string;
+  tokens: number;
+  timestamp: number;
+  payload?: string;
+}
+/** A summary row. Provenance makes a summary usable: a leaf names the messages
+ * it covers, a condensed node names children by file position, since ids are
+ * assigned on import. `createdAt` is not carried, because the store assigns its
+ * own and a field no import can restore would be a lie in the file. A run in
+ * flight is not exported: what this returns is committed memory, so a pass still
+ * holding pending rows is invisible here and an import waits for it. */
+export interface ExportSummaryRow {
+  v: number;
+  rowType: "summary";
+  ordinal: number;
+  kind: "leaf" | "condensed";
+  text: string;
+  tokens: number;
+  depth: number;
+  firstEntryId: string;
+  lastEntryId: string;
+  messageEntryIds: string[];
+  childOrdinals: number[];
+}
+export type ExportRow = ExportMessageRow | ExportSummaryRow | ExportFileRow;
+export interface ExportFileRow {
+  v: number;
+  rowType: "file";
+  fileId: string;
+  path: string;
+  bytes: number;
+  sha256: string;
+  kind: FileKind;
+  preview: string;
+  entryIds: string[];
+}
+export declare function exportTranscript(store: LcmStore): {
+  messages: StoredMessage[];
+  summaries: SummaryNode[];
+  toJSONL: () => string;
+};
+//#endregion
+//#region src/format.d.ts
+export declare function fmtTokens(n: number): string;
+export declare function fmtBytes(n: number): string;
+//#endregion
+//#region src/home-paths.d.ts
+/** Escape hatch for a live session that carries a test signal for another
+ * reason, so the guard can never brick one. */
+export declare const ALLOW_REAL_HOME_FLAG = "LCM_ALLOW_REAL_HOME";
+export declare function isUnderTempDir(path: string): boolean;
+/** Every path this extension touches under the user's home resolves here, so one
+ * guard covers them all instead of one per call site. A test run refuses a path
+ * outside its temp home rather than touching the real config. */
+export declare function lcmHomePath(...segments: string[]): string;
+//#endregion
+//#region src/import.d.ts
+export interface ImportResult {
+  messagesInserted: number;
+  messagesSkipped: number;
+  summariesInserted: number;
+  summariesSkipped: number;
+  /** Set when the import was refused, with the text naming the reason. The
+   * counters say what landed before it was: a refusal ahead of the summary loop
+   * writes nothing, and one inside it names the rows that did land. */
+  refused?: string;
+}
+export type ParsedExport = {
+  rows: ExportRow[];
+} | {
+  error: string;
+};
+/** Read a file written by `/lcm export`: every line is validated before any is
+ * used, so a truncated or foreign file is refused without a partial import and
+ * the caller can report a line number. */
+export declare function parseExport(text: string): ParsedExport;
+export declare function importTranscript(store: LcmStore, rows: readonly ExportRow[]): ImportResult;
+//#endregion
+//#region src/ingest.d.ts
+export interface IngestibleEntry {
+  entryId: string;
+  role: LcmRole;
+  text: string;
+  timestamp: number;
+  payload?: string;
+  /** The path a tool call named for this body, when one did. The only
+   * deterministic signal that a body is a file, so the only externalization
+   * trigger. */
+  fileHint?: {
+    path: string;
+  };
+  /** Pi's own head compaction, landing as a `custom` role because every role Pi
+   * does not name folds to `custom`: the one observable event that the window
+   * filled and LCM did not hold it. */
+  piCompaction?: boolean;
+}
+export interface ExternalizedFile {
+  entryId: string;
+  fileId: string;
+  path: string;
+  kind: string;
+  bytes: number;
+}
+export interface IngestStats {
+  inserted: number;
+  skipped: number;
+  /** Entry ids inserted with `piCompaction`, so a re-scan cannot count one twice. */
+  piCompactions: string[];
+  files: ExternalizedFile[];
+  largeInline: Array<{
+    entryId: string;
+    chars: number;
+  }>;
+}
+export interface IngestWatermark {
+  id: string;
+}
+export interface RawEntryLike {
+  id?: string;
+}
+export declare function isIngestible(e: {
+  entryId: string;
+  text: string;
+}): boolean;
+/** The watermark a hook carries after considering `delta`: its last entry,
+ * whether or not any of it was stored. A turn that carries nothing addressable
+ * still moves the watermark, or the next turn rescans the whole session. */
+export declare function nextIngestWatermark(delta: Array<{
+  entryId: string;
+}>): IngestWatermark | null;
+export interface RawIngestDelta {
+  startIndex: number;
+  reset: boolean;
+}
+export declare function computeRawIngestDelta(entries: readonly RawEntryLike[], watermark: IngestWatermark | null): RawIngestDelta;
+export declare function entryToText(content: unknown): string;
+/** The raw content blocks as JSON when `entryToText(content)` is not a faithful
+ * rendering of them, `undefined` when the derived text is the whole message.
+ * The whole array is stored, so a payload is never itself a lossy projection;
+ * the rule about which messages get one is what keeps a text-only message at a
+ * single copy. */
+export declare function payloadOf(content: unknown): string | undefined;
+export declare function ingestEntries(store: IngestStore, entries: readonly IngestibleEntry[], opts?: {
+  externalize?: {
+    largeFileChars: number;
+  };
+}): IngestStats;
+//#endregion
+//#region src/overflow-window.d.ts
+/** A window outside this band is a misread rather than a model: no provider
+ * serves a context under a thousand tokens or over a hundred million, and a
+ * number outside it means a pattern caught the request count, a status code, or
+ * something else that was not a limit. A refused parse is the floor path, which
+ * costs one conservative turn instead of a wrong permanent window. */
+export declare const WINDOW_MIN = 1000;
+export declare const WINDOW_MAX = 100000000;
+/** The window in tokens a provider stated in an overflow message, or null when
+ * the message does not name one. Null is an answer: the caller keeps Pi's belief
+ * and arms the one-shot floor, which is all a body like "400/413 status code (no
+ * body)" can support. */
+export declare function windowFromError(errorMessage: string | undefined): number | null;
+export declare const WINDOW_PATTERN_EXAMPLES: readonly string[];
+//#endregion
+//#region src/recall-view.d.ts
+export declare const GREP_PAGE_HITS = 20;
+export type ViewResult = {
+  ok: true;
+  text: string;
+  details: Record<string, unknown>;
+} | {
+  ok: false;
+  text: string;
+};
+export declare function grepView(store: LcmStore, redact: (text: string) => string, params: {
+  query?: string;
+  pattern?: string;
+  caseSensitive?: boolean;
+  offset?: number;
+  limit?: number;
+  summaryId?: number;
+  includeRemoved?: boolean;
+  /** Resume a pattern scan after this entry id, which is what a deadline stop
+   * names. A page cannot express where a clock ran out. */
+  after?: string;
+  now?: () => number;
+}): ViewResult;
+export declare function describeView(store: LcmStore, redact: (text: string) => string, id: number): ViewResult;
+/** List the summary's messages, or read one of them as a window of characters.
+ * A message read without a summary names an entry directly, which is how an
+ * entry that no leaf covers yet is read at all. */
+export type ExpandParams = {
+  mode: "list";
+  id: number;
+  offset: number;
+  limit: number;
+  maxChars: number;
+} | {
+  mode: "message";
+  id?: number;
+  entryId: string;
+  charOffset: number;
+  maxChars: number;
+};
+export declare function expandView(store: LcmStore, redact: (text: string) => string, params: ExpandParams): ViewResult;
+export declare function historyManifest(store: LcmStore, limit: number): string;
+//#endregion
+//#region src/redact.d.ts
+/** Redactor that re-reads the flag on every call, so a cockpit toggle takes
+ * effect immediately: a getter, because patchConfig replaces the config object
+ * and closing over it would pin the session-start value. */
+export declare function makeRedact(getConfig: () => {
+  redactSecrets?: boolean;
+}): (text: string) => string;
+export declare function redactSecrets(text: string): string;
+//#endregion
+//#region src/retention.d.ts
+export declare const SCRATCH_MAX_AGE_MS: number;
+export interface DbFootprint {
+  path: string;
+  name: string;
+  sizeBytes: number;
+  modifiedAt: number;
+}
+export interface GcCandidate {
+  path: string;
+  sizeBytes: number;
+  modifiedAt: number;
+  reason: "session-gone" | "scratch-expired";
+}
+export declare function hashSessionPath(sessionFilePath: string): string;
+export declare function listDbFootprints(dir: string): DbFootprint[];
+export declare function retentionCandidates(opts: {
+  dir: string;
+  liveDbPath: string | undefined;
+  sessionPathHashes: ReadonlySet<string>;
+  now: number;
+  scratchMaxAgeMs: number;
+}): GcCandidate[];
+//#endregion
+//#region src/retrieval.d.ts
+export declare const RETRIEVAL_STEPS = 6;
+export declare const MANIFEST_NODES = 20;
+export declare const MAX_EXPAND_CHARS = 20000;
+export declare const DEFAULT_RETRIEVAL_TOKENS = 10000;
+export declare const MIN_RETRIEVAL_TOKENS = 500;
+export declare const MAX_RETRIEVAL_TOKENS = 40000;
+export interface RetrievalRequest {
+  query: string;
+  prompt: string;
+  budgetTokens: number;
+  maxSteps: number;
+  /** Masks stored text on its way to the reader and on its way back. Applied
+   * inside this module so a reader cannot be wired without one. */
+  redact: (text: string) => string;
+  scope?: RetrievalScope;
+}
+export type RetrievalScope = {
+  kind: "summary";
+  summaryId: number;
+} | {
+  kind: "entry";
+  entryId: string;
+};
+interface RetrievalBase {
+  steps: number;
+  retrievedTokens: number;
+  usage?: Usage;
+}
+export type RetrievalRun = (RetrievalBase & {
+  kind: "answered";
+  text: string;
+}) | (RetrievalBase & {
+  kind: "stopped";
+  reason: "steps" | "budget";
+  text: string;
+}) |
+/** The address named something the store does not hold, so no model was called. */
+(RetrievalBase & {
+  kind: "refused";
+  reason: string;
+}) | (RetrievalBase & {
+  kind: "failed";
+  reason: string;
+});
+export declare function runRetrieval(store: LcmStore, request: RetrievalRequest, reader: Reader): Promise<RetrievalRun>;
+//#endregion
+//#region src/sessions.d.ts
+/** Most recent past sessions one scan considers. A cap, not a promise: the
+ * deadline below is what bounds the work. */
+export declare const SESSION_SCAN_LIMIT = 20;
+/** Session headers one listing reads before it picks the newest `SESSION_SCAN_LIMIT`.
+ * A header is one small read, so a few hundred sessions cost one syscall each. */
+export declare const SESSION_HEADER_CAP = 200;
+/** Wall-clock budget for one cross-session search. A scan that runs out returns
+ * what it found and says it was truncated. */
+export declare const SESSION_SEARCH_DEADLINE_MS = 1500;
+export declare const SESSION_HITS_LIMIT = 40;
+export interface SessionRef {
+  hash: string;
+  sessionFile: string;
+  storePath: string;
+  cwd: string;
+  sessionId: string;
+  /** Header timestamp in ms, or the file's mtime when the header has none. */
+  when: number;
+}
+/** Why a candidate past session could not be searched. Each reason is a count the
+ * caller reports, never an error it raises: a store this build cannot read is
+ * skipped, not migrated. */
+export type SessionSkip = "missing" | "unreadable" | "older-generation";
+/** Line 1 of a session file: `{"type":"session","id":...,"timestamp":...,
+ * "cwd":...}`. Reading stops at the first newline, so a session with a broken
+ * line 2 still lists. */
+declare const HEADER_LINE: Type.TObject<{
+  type: Type.TLiteral<"session">;
+  cwd: Type.TString;
+  id: Type.TString;
+  timestamp: Type.TString;
+}>;
+export declare function readSessionHeader(sessionFile: string): Omit<Static<typeof HEADER_LINE>, "type"> | undefined;
+export declare function sessionStorePath(storesDir: string, sessionFile: string): string;
+export declare function listSessions(opts: {
+  sessionsRoot: string;
+  storesDir: string;
+  cwd?: string;
+  limit?: number;
+  /** How deep to walk. Pi nests one directory per project cwd, so 4 is slack. */
+  maxDepth?: number;
+  excludeHash?: string;
+}): SessionRef[];
+/** The generation a store file carries, read without migrating it. `undefined`
+ * when the file cannot be read at all. */
+export declare function storeGeneration(storePath: string): number | undefined;
+export declare function openSessionStore(ref: SessionRef): {
+  kind: "opened";
+  store: LcmStore;
+} | {
+  kind: "skipped";
+  reason: SessionSkip;
+};
+export interface SessionHit extends GrepHit {
+  session: string;
+  sessionId: string;
+  cwd: string;
+  when: number;
+}
+export interface SessionSearchResult {
+  hits: SessionHit[];
+  scanned: number;
+  skipped: Record<SessionSkip, number>;
+  /** True when the deadline or the hit cap ended the scan early. */
+  truncated: boolean;
+  elapsedMs: number;
+}
+export declare function searchSessions(refs: readonly SessionRef[], query: string, opts?: {
+  limit?: number;
+  deadlineMs?: number;
+  perSession?: number;
+  now?: () => number;
+}): SessionSearchResult;
+export declare const SEARCH_SCOPE_HELP = "session (default) searches this session. sessions searches past sessions in this project's working directory. all_sessions searches past sessions in every project. A cross-session hit is a pointer labelled [lcm:session <hash>] that lcm_expand_query({session, entry_id}) reads, so a past session's text is never injected into the context on its own.";
+/** The cross-session hits as one labelled block, plus what the scan did not read.
+ * `redact` is required because this hands a past session's stored text to a
+ * model, and that store holds secrets this session's mask has to reach. */
+export declare function formatSessionHits(result: SessionSearchResult, redact: (text: string) => string): string;
+export declare function sessionsForScope(opts: {
+  scope: "sessions" | "all_sessions";
+  sessionsRoot: string;
+  storesDir: string;
+  cwd: string;
+  excludeHash?: string;
+  limit?: number;
+}): SessionRef[];
+//#endregion
+//# sourceMappingURL=index.d.mts.map