bare-agent 0.18.0 → 0.20.0

package/README.md

@@ -17,9 +17,9 @@
   <img src="https://img.shields.io/badge/license-Apache%202.0-2a4f8c" alt="license: Apache 2.0">
 </p>
 
-**Lightweight agent orchestration. One required dep ([bareguard](https://npmjs.com/package/bareguard) ^0.9.0).**
+**Lightweight agent orchestration. Zero required deps — optional [bareguard](https://npmjs.com/package/bareguard) peer for single-gate governance.**
 
-Lightweight enough to understand completely. Complete enough to not reinvent wheels. Not a framework, not 50,000 lines of opinions — just composable building blocks for agents. Single-gate governance via bareguard: every tool call traverses one policy hook, one audit log, one budget cap.
+Lightweight enough to understand completely. Complete enough to not reinvent wheels. Not a framework, not 50,000 lines of opinions — just composable building blocks for agents. The core imports nothing; when you want governance, wire bareguard and every tool call traverses one policy hook, one audit log, one budget cap.
 
 ## Quick start
 
@@ -62,7 +62,7 @@ and show me the wiring code.
 
 ## What's inside
 
-Every piece works alone — take what you need, ignore the rest. Two axes: **Act** (get work done) and **Verify** (check it, keep context clean), with **one gate** over both.
+Every piece works alone — take what you need, ignore the rest. Two axes: **Act** (get work done) and **Verify** (check it, keep context clean), with **one gate** over both — plus **`recurse`**, an Act-side primitive big enough to earn its own spotlight below.
 
 ### Act — get work done
 
@@ -72,6 +72,7 @@ Every piece works alone — take what you need, ignore the rest. Two axes: **Act
 | **Planner** | Break a goal into a step DAG. Cached |
 | **assessComplexity** | Rate a goal `simple`→`critical` from its text — no LLM. Gates whether to plan |
 | **runPlan** | Run plan steps in parallel waves. Dependency-aware, per-step retry |
+| **recurse** | RLM decompose→fan-out→verify→synthesize in one call. Model-driven (`spawn_child`) or forced fan-out (`count`); `retrieval:'scan'` answers "how many / all" over a corpus by scanning every slice and code-counting — never a faked pass (honest `{incomplete, missingSlices}`) |
 | **Memory** | Persist + recall across sessions via a swappable `Store` — zero-dep JSON, SQLite, or [litectx](https://npmjs.com/package/litectx) in a one-line swap |
 | **StateMachine** | Task lifecycle: `pending → running → done / failed / waiting / cancelled` |
 | **Scheduler** | Cron or relative triggers. Jobs survive restarts |
@@ -91,6 +92,26 @@ Every piece works alone — take what you need, ignore the rest. Two axes: **Act
 | **SkillRegistry** | Surface skills on demand: one meta-tool catalog; activating a skill injects its instructions and unlocks its tools |
 | **stash** | Compact finished work out of the live window (restorable), or auto-fold the middle under token pressure |
 
+### Recurse — break a hard task into a tree *(the RLM primitive)*
+
+`recurse(task, ctx, opts)` does **decompose → fan-out → verify → synthesize** in one call — Recursive Language Models as a single import, composed *around* the Loop (never a new engine). The default is **model-driven**: the worker is handed a `spawn_child` tool and decides whether to split, bounded by depth + bareguard (no second guard layer). Forced fan-out (`count` / `mode:'fanout'`) and data-driven width (`mode:'partition'`, measured from a corpus) are opt-in. The headline guarantee: **aggregation is code, never a model-stated number**, and a dead worker or exhausted guard returns an honest `{ incomplete, missingSlices }` — never a faked pass.
+
+Over a corpus, context reaches a worker as a **handle routed by question shape**: `'scan'` answers *"how many / all"* by scanning every slice and **code-counting** the matches (the only path that can't silently undercount); `'search'` / `'exact'` are per-query handle tools for needles and rules; `'tools'` offers all three and lets the worker pick per sub-query.
+
+```js
+const { recurse } = require('bare-agent');
+
+// Honest count over a corpus: scans every slice, LLM-judges each, CODE-counts the union.
+const { result } = await recurse(
+  'How many of these support tickets are billing disputes?',
+  { provider },
+  { corpus: tickets /* {id,text}[] */, retrieval: 'scan' },
+);
+console.log(result.count, result.matchedIds);   // a code-derived count + the ids that back it
+```
+
+> **⚠️ Cost is open by design — wire a cap.** `recurse()` adds no intrinsic total-work limit. On the model-driven default a node can spawn up to ~100 children per level, each recursing to `maxDepth` (default 3), so **token / $ spend compounds and is bounded only by your gate** — not by recurse. Run it **with bareguard** (`ctx.policy`, which enforces depth/budget/call caps) **or with some token/USD cap** for any non-trivial or untrusted task; ungoverned, a weak model that over-decomposes *will* burn tokens. For a hard local brake without a gate, set `maxDepth: 1` (flat, no nesting). The forced modes (`mode:'fanout'` / `'partition'`) are bounded by a deterministic count + concurrency cap; the open path is the model-driven default.
+
 **Govern — one gate over both axes.** `wireGate(gate)` routes every LLM + tool call through one bareguard policy + audit + budget. Denied tools never reach the model; halts (turn / budget / content caps) exit cleanly. `require('bare-agent/bareguard')`
 
 **Providers:** OpenAI-compatible (OpenAI, OpenRouter, Groq, vLLM, LM Studio), Anthropic, Gemini (native), Ollama, CLIPipe, Fallback — or bring your own (one `generate` method). All return the same shape; swap freely. Usage including prompt-cache tiers is normalized, so `result.metrics` reports honest cumulative tokens + cost — and `null`, never a silent `0`, for a model it couldn't price.
@@ -99,7 +120,7 @@ Every piece works alone — take what you need, ignore the rest. Two axes: **Act
 
 **Cross-language:** Run as a subprocess; talk JSONL over stdin/stdout from Python, Go, Rust, Ruby, or Java. Wrappers in [`contrib/`](contrib/README.md).
 
-**Deps:** 1 required (`bareguard ^0.9.0`). Optional: `cron-parser`, `better-sqlite3`, `barebrowse`, `baremobile`, `wearehere`.
+**Deps:** none required — the core imports nothing. Optional peers: `bareguard ^0.9.0` (governance), `better-sqlite3` (SQLite store); optional: `cron-parser`, `barebrowse`, `baremobile`, `wearehere`.
 
 This table is the map, not the manual — per-component wiring and API detail live in the [Integration Guide](bareagent.context.md) and [Usage Guide](docs/02-features/usage-guide.md).
 

package/bareagent.context.md

@@ -1,13 +1,13 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.18.0 | Node.js >= 18 | one required dep (`bareguard ^0.9.0`) | Apache 2.0
+> v0.20.0 | Node.js >= 18 | zero required deps (`bareguard ^0.9.0` optional peer for governance) | Apache 2.0
 >
 > Full human guide with composition examples, design philosophy, and recipes: [Usage Guide](docs/02-features/usage-guide.md)
 
 ## What this is
 
-bareagent is a lightweight agent orchestration library (~2.4K lines of core, one required dep). It provides composable components for LLM tool-calling loops, goal planning, state tracking, scheduled actions, human approval gates, persistent memory, circuit breaking, provider fallback, single-gate governance via [bareguard](https://npmjs.com/package/bareguard), cross-platform shell tools, and an MCP bridge. All components are independent — use one, use all, or bring your own.
+bareagent is a lightweight agent orchestration library (small core, zero required runtime deps — `bareguard` is an optional peer for governance). It provides composable components for LLM tool-calling loops, goal planning, state tracking, scheduled actions, human approval gates, persistent memory, circuit breaking, provider fallback, single-gate governance via [bareguard](https://npmjs.com/package/bareguard), cross-platform shell tools, and an MCP bridge. All components are independent — use one, use all, or bring your own.
 
 ```
 npm install bare-agent

package/index.d.ts

@@ -2,6 +2,11 @@ import { Loop } from "./src/loop";
 import { Planner } from "./src/planner";
 import { Evaluator } from "./src/evaluator";
 import { refine } from "./src/refine";
+import { recurse } from "./src/recurse";
+import { buildSearchTool } from "./src/recurse-retrieval";
+import { buildExactTool } from "./src/recurse-retrieval";
+import { buildScanTool } from "./src/recurse-retrieval";
+import { litectxCorpus } from "./src/recurse-retrieval";
 import { remember } from "./src/remember";
 import { assessComplexity } from "./src/complexity";
 import { isCritical } from "./src/complexity";
@@ -29,4 +34,4 @@ import { TimeoutError } from "./src/errors";
 import { ValidationError } from "./src/errors";
 import { CircuitOpenError } from "./src/errors";
 import { HaltError } from "./src/errors";
-export { Loop, Planner, Evaluator, refine, remember, assessComplexity, isCritical, SkillRegistry, createStashSkill, StateMachine, Scheduler, Checkpoint, Memory, Stream, Retry, runPlan, CircuitBreaker, wireGate, defaultActionTranslator, toUnits, fromUnits, unitAssembler, unitTrimmer, harvestKey, BareAgentError, ProviderError, ToolError, TimeoutError, ValidationError, CircuitOpenError, HaltError };
+export { Loop, Planner, Evaluator, refine, recurse, buildSearchTool, buildExactTool, buildScanTool, litectxCorpus, remember, assessComplexity, isCritical, SkillRegistry, createStashSkill, StateMachine, Scheduler, Checkpoint, Memory, Stream, Retry, runPlan, CircuitBreaker, wireGate, defaultActionTranslator, toUnits, fromUnits, unitAssembler, unitTrimmer, harvestKey, BareAgentError, ProviderError, ToolError, TimeoutError, ValidationError, CircuitOpenError, HaltError };

package/index.js

@@ -4,6 +4,8 @@ const { Loop } = require('./src/loop');
 const { Planner } = require('./src/planner');
 const { Evaluator } = require('./src/evaluator');
 const { refine } = require('./src/refine');
+const { recurse } = require('./src/recurse');
+const { buildSearchTool, buildExactTool, buildScanTool, litectxCorpus } = require('./src/recurse-retrieval');
 const { remember } = require('./src/remember');
 const { assessComplexity, isCritical } = require('./src/complexity');
 const { SkillRegistry } = require('./src/skills');
@@ -33,6 +35,11 @@ module.exports = {
   Planner,
   Evaluator,
   refine,
+  recurse,
+  buildSearchTool,
+  buildExactTool,
+  buildScanTool,
+  litectxCorpus,
   remember,
   assessComplexity,
   isCritical,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "files": [
     "index.js",
     "index.d.ts",
@@ -13,7 +13,7 @@
     "LICENSE",
     "NOTICE"
   ],
-  "description": "Lightweight, composable agent orchestration for autonomous agents. Multi-agent primitives (spawn, defer, MCP meta-tools), single-gate governance via bareguard, cross-platform shell tools, MCP bridge. Lightweight core, one required dep.",
+  "description": "Lightweight, composable agent orchestration for autonomous agents. Multi-agent primitives (spawn, defer, MCP meta-tools), single-gate governance via an optional bareguard peer, cross-platform shell tools, MCP bridge. Zero required runtime deps.",
   "license": "Apache-2.0",
   "author": "hamr0",
   "repository": {
@@ -74,25 +74,26 @@
     "bareguard",
     "governance"
   ],
-  "dependencies": {
-    "bareguard": "^0.9.0"
-  },
   "optionalDependencies": {
     "barebrowse": "^0.5.0",
     "baremobile": "^0.7.0",
     "cron-parser": "^4.9.0"
   },
   "peerDependencies": {
+    "bareguard": "^0.9.0",
     "better-sqlite3": ">=9.0.0"
   },
   "peerDependenciesMeta": {
+    "bareguard": {
+      "optional": true
+    },
     "better-sqlite3": {
       "optional": true
     }
   },
   "scripts": {
-    "test": "node --test --test-force-exit test/**/*.test.js",
-    "test:unit": "node --test --test-force-exit \"test/!(integration*|*mcp*|spawn*).test.js\"",
+    "test": "node --test test/**/*.test.js",
+    "test:unit": "node --test \"test/!(integration*|*mcp*|spawn*).test.js\"",
     "typecheck": "tsc --noEmit",
     "prebuild:types": "node scripts/clean-types.js",
     "build:types": "tsc",
@@ -100,7 +101,8 @@
   },
   "devDependencies": {
     "@types/node": "^22.19.19",
-    "litectx": "^0.16.0",
+    "bareguard": "^0.9.0",
+    "litectx": "^0.26.0",
     "typescript": "^5.7.0"
   }
 }

package/src/planner.d.ts

@@ -30,6 +30,17 @@ export type PlannerOptions = {
      * - Cache time-to-live in ms. 0 disables caching.
      */
     cacheTTL?: number | undefined;
+    /**
+     * - Budget hook
+     * (mirror of Evaluator's). Forwards the planning call's `usage` to the gate so decomposition spend is
+     * visible — without it the plan call is invisible to bareguard's budget (the RLM Family-B meter gap). A
+     * cache hit does NOT forward (no LLM call happened).
+     */
+    onLlmResult?: ((payload: {
+        usage: any;
+        model: string | null;
+        kind: "plan";
+    }) => any) | undefined;
 };
 export class Planner {
     /**
@@ -41,10 +52,18 @@ export class Planner {
     prompt: string;
     _cacheTTL: number;
     _cache: Map<any, any>;
+    onLlmResult: ((payload: {
+        usage: any;
+        model: string | null;
+        kind: "plan";
+    }) => any) | null;
     /**
      * Generate a step DAG from a goal.
      * @param {string} goal - The user's goal to decompose.
-     * @param {{info?: string}} [context={}] - Optional context with info field.
+     * @param {{info?: string, count?: number}} [context={}] - Optional context. `info` is prior
+     *   context to factor in. `count` (RLM NB-2 seam): when a positive integer, forces the plan to
+     *   exactly that many INDEPENDENT, parallelizable steps (all `dependsOn: []`) instead of the
+     *   model's free 2–7 — lets `recurse()` impose the deterministic tier→count for forced fan-out.
      * @returns {Promise<Step[]>}
      * @throws {Error} `[Planner] could not parse plan` — when LLM output is not parseable JSON.
      * @throws {Error} `[Planner] expected JSON array` — when parsed result is not an array.
@@ -52,6 +71,7 @@ export class Planner {
      */
     plan(goal: string, context?: {
         info?: string;
+        count?: number;
     }): Promise<Step[]>;
     clearCache(): void;
     /**

package/src/planner.js

@@ -15,6 +15,10 @@
  * @property {Provider} provider - LLM provider (must implement generate()).
  * @property {string} [prompt] - Custom planning prompt override.
  * @property {number} [cacheTTL] - Cache time-to-live in ms. 0 disables caching.
+ * @property {(payload: {usage: any, model: string|null, kind: 'plan'}) => any} [onLlmResult] - Budget hook
+ *   (mirror of Evaluator's). Forwards the planning call's `usage` to the gate so decomposition spend is
+ *   visible — without it the plan call is invisible to bareguard's budget (the RLM Family-B meter gap). A
+ *   cache hit does NOT forward (no LLM call happened).
  */
 
 const PLAN_PROMPT = `You are a planning agent. Break the user's goal into concrete steps.
@@ -42,28 +46,38 @@ class Planner {
     this.prompt = options.prompt || PLAN_PROMPT;
     this._cacheTTL = options.cacheTTL || 0;
     this._cache = new Map();
+    this.onLlmResult = options.onLlmResult || null;
   }
 
   /**
    * Generate a step DAG from a goal.
    * @param {string} goal - The user's goal to decompose.
-   * @param {{info?: string}} [context={}] - Optional context with info field.
+   * @param {{info?: string, count?: number}} [context={}] - Optional context. `info` is prior
+   *   context to factor in. `count` (RLM NB-2 seam): when a positive integer, forces the plan to
+   *   exactly that many INDEPENDENT, parallelizable steps (all `dependsOn: []`) instead of the
+   *   model's free 2–7 — lets `recurse()` impose the deterministic tier→count for forced fan-out.
    * @returns {Promise<Step[]>}
    * @throws {Error} `[Planner] could not parse plan` — when LLM output is not parseable JSON.
    * @throws {Error} `[Planner] expected JSON array` — when parsed result is not an array.
    * @throws {Error} `[Planner] step missing id or action` — when a step lacks required fields.
    */
   async plan(goal, context = {}) {
+    // NB-2: a forced fan-out count (positive integer only — a 0/NaN/negative falls back to free planning).
+    const count = Number.isInteger(context.count) && /** @type {number} */ (context.count) > 0
+      ? /** @type {number} */ (context.count) : null;
     if (this._cacheTTL > 0) {
-      const cacheKey = JSON.stringify({ goal, info: context.info || '' });
+      const cacheKey = JSON.stringify({ goal, info: context.info || '', count });
       const cached = this._cache.get(cacheKey);
       if (cached && Date.now() < cached.expiresAt) {
         return cached.result;
       }
     }
 
+    const system = count
+      ? `${this.prompt}\n\nOVERRIDE: ignore the "2-7 steps" guidance. Decompose into EXACTLY ${count} independent, parallelizable steps, each with "dependsOn": []. Split the goal into ${count} disjoint slices of comparable size that together cover it with no overlap.`
+      : this.prompt;
     const messages = [
-      { role: 'system', content: this.prompt },
+      { role: 'system', content: system },
     ];
     if (context.info) {
       messages.push({ role: 'user', content: `Context: ${context.info}` });
@@ -75,10 +89,16 @@ class Planner {
       temperature: 0,
     });
 
+    // Budget visibility: forward the planning call's usage to the gate (mirror of Evaluator). Only on a real
+    // LLM call — a cache hit returned earlier without reaching here, so it never double-counts.
+    if (this.onLlmResult) {
+      await this.onLlmResult({ usage: result.usage || null, model: result.model || this.provider.model || null, kind: 'plan' });
+    }
+
     const steps = this._parse(result.text);
 
     if (this._cacheTTL > 0) {
-      const cacheKey = JSON.stringify({ goal, info: context.info || '' });
+      const cacheKey = JSON.stringify({ goal, info: context.info || '', count });
       this._cache.set(cacheKey, { result: steps, expiresAt: Date.now() + this._cacheTTL });
     }
 

package/src/recurse-prompts.d.ts

@@ -0,0 +1,22 @@
+/**
+ * NB-5 — the decomposition-policy system blurb + few-shot. Prepended to a Family-A worker's system prompt so
+ * the model has an in-context example of HOW to split before it is offered the `spawn_child` A-tool. Flat-first
+ * (§4.2/§8): the model fans out flat over a window-sized batch and only escalates to a nested `spawn_child`
+ * when a single sub-task is genuinely too large to handle directly. Worked splits are deliberately small —
+ * the lift is from showing the SHAPE of a good split, not from volume.
+ * @type {string}
+ */
+export const DECOMPOSITION_POLICY: string;
+/**
+ * NB-4 / RC-12 — the depth-aware capability-scrub suffix. Deeper workers get a more conservative prompt:
+ * "prefer direct action, only delegate if truly necessary." Combined with the inline `canSpawn` check (the
+ * tool half of the scrub: `depth < maxDepth` withholds `spawn_child` at the cap) in recurse.js, this realizes
+ * guard #5's prompt+tool-shaping half (the part bareguard's blind
+ * `policy` cap cannot express). At depth 0 there is no suffix (the top-level worker decomposes freely);
+ * from depth 1 on, each level nudges harder toward answering directly so recursion contracts toward its base
+ * case rather than fanning out without bound.
+ * @param {number} depth - The worker's depth (0 = top level).
+ * @param {number} maxDepth - The topology ceiling; at `depth >= maxDepth` the `spawn_child` tool is withheld.
+ * @returns {string} A suffix to append to the worker system prompt ('' at depth 0).
+ */
+export function capabilityScrub(depth: number, maxDepth: number): string;

package/src/recurse-prompts.js

@@ -0,0 +1,71 @@
+'use strict';
+
+// NB-5 + NB-4 prompt assets for src/recurse.js (RLM_PRD §4.3). Pure text, ZERO runtime — kept in their own
+// file so the decomposition policy (which the RLM paper Fig 4 shows directly lifts accuracy and the
+// first-split-correct rate) is inspectable and editable without touching the glue. Two assets:
+//   - DECOMPOSITION_POLICY (NB-5): the worker's system-prompt blurb + 1-2 worked splits.
+//   - capabilityScrub (NB-4 / RC-12): the depth-conservative suffix deeper workers receive.
+
+/**
+ * NB-5 — the decomposition-policy system blurb + few-shot. Prepended to a Family-A worker's system prompt so
+ * the model has an in-context example of HOW to split before it is offered the `spawn_child` A-tool. Flat-first
+ * (§4.2/§8): the model fans out flat over a window-sized batch and only escalates to a nested `spawn_child`
+ * when a single sub-task is genuinely too large to handle directly. Worked splits are deliberately small —
+ * the lift is from showing the SHAPE of a good split, not from volume.
+ * @type {string}
+ */
+const DECOMPOSITION_POLICY = [
+  'You solve a task by DECOMPOSING it, not by swallowing everything at once.',
+  '',
+  'How to decompose:',
+  '- Break the task into independent sub-tasks, each small enough to handle in one focused pass.',
+  '- Prefer a FLAT split (several sibling sub-tasks) over a deep one. Only nest — split a sub-task again —',
+  '  when that single sub-task is itself too large to handle directly.',
+  '- When you have a sub-task that is large or independent, delegate it with the `spawn_child` tool: it runs',
+  '  in a FRESH context window and returns only its result. Do the small/glue parts yourself.',
+  '- After the sub-results come back, COMBINE them into one final answer for the original task.',
+  '- If you can answer directly without splitting, just do so — decomposition is for tasks too big for one pass.',
+  '',
+  'Worked example 1 (flat split):',
+  '  Task: "Summarize the security posture of services A, B, and C."',
+  '  Good split: spawn_child("Summarize the security posture of service A"), same for B, same for C,',
+  '  then combine the three summaries into one posture report.',
+  '',
+  'Worked example 2 (nest only on overflow):',
+  '  Task: "Count matching records across a 10,000-line log."',
+  '  The log is too large for one pass, so split it into chunks and spawn_child a count for each chunk;',
+  '  if a chunk is STILL too large, that child splits again. Sum the per-chunk counts in your final answer.',
+].join('\n');
+
+/**
+ * NB-4 / RC-12 — the depth-aware capability-scrub suffix. Deeper workers get a more conservative prompt:
+ * "prefer direct action, only delegate if truly necessary." Combined with the inline `canSpawn` check (the
+ * tool half of the scrub: `depth < maxDepth` withholds `spawn_child` at the cap) in recurse.js, this realizes
+ * guard #5's prompt+tool-shaping half (the part bareguard's blind
+ * `policy` cap cannot express). At depth 0 there is no suffix (the top-level worker decomposes freely);
+ * from depth 1 on, each level nudges harder toward answering directly so recursion contracts toward its base
+ * case rather than fanning out without bound.
+ * @param {number} depth - The worker's depth (0 = top level).
+ * @param {number} maxDepth - The topology ceiling; at `depth >= maxDepth` the `spawn_child` tool is withheld.
+ * @returns {string} A suffix to append to the worker system prompt ('' at depth 0).
+ */
+function capabilityScrub(depth, maxDepth) {
+  if (depth <= 0) return '';
+  if (depth >= maxDepth) {
+    return [
+      '',
+      `DEPTH ${depth} of ${maxDepth} — this is the deepest level. You CANNOT delegate further; there is no`,
+      'spawn tool here. Answer this sub-task DIRECTLY and concisely from what you have. If the sub-task is',
+      'still too large to answer faithfully, say so explicitly rather than guessing — an honest "incomplete"',
+      'is correct; a fabricated answer is not.',
+    ].join('\n');
+  }
+  return [
+    '',
+    `DEPTH ${depth} of ${maxDepth} — you are already inside a delegated sub-task. PREFER DIRECT ACTION:`,
+    'answer this sub-task yourself if you reasonably can. Only delegate further (spawn_child) when a part of',
+    'it is genuinely too large to handle in one pass. Keep the recursion shallow.',
+  ].join('\n');
+}
+
+module.exports = { DECOMPOSITION_POLICY, capabilityScrub };

package/src/recurse-retrieval.d.ts

@@ -0,0 +1,174 @@
+export type Slice = {
+    /**
+     * - Stable, word-like id (no whitespace/commas — it is echoed back by the judge).
+     */
+    id: string;
+    /**
+     * - The item content shown to the judge.
+     */
+    text: string;
+};
+export type Provider = import("../types").Provider;
+export type ToolDef = import("../types").ToolDef;
+/**
+ * SCAN — process every slice, LLM-judge each window, union matching ids across windows AND passes, CODE-count
+ * the union. The default reliability mechanism (§9.2.1): the only path that does not silently undercount.
+ * RC-9: a dead window is recorded in `missingSlices`, never folded into the count as a zero.
+ * @param {string} predicate - The task the slices are judged against.
+ * @param {Slice[]} corpus - The array slice-source (already validated/normalized by the caller).
+ * @param {object} opts
+ * @param {Provider} opts.provider
+ * @param {number} [opts.window]
+ * @param {number} [opts.passes]
+ * @param {object} [opts.ctx]
+ * @param {Function} [opts.onLlmResult]
+ * @param {Function} [opts.policy]
+ * @returns {Promise<{matchedIds: string[], count: number, missingSlices: string[], window: number, passes: number, scanned: number}>}
+ * @throws {HaltError} a governance cap halted a window judge.
+ */
+export function scanCount(predicate: string, corpus: Slice[], opts: {
+    provider: Provider;
+    window?: number | undefined;
+    passes?: number | undefined;
+    ctx?: object;
+    onLlmResult?: Function | undefined;
+    policy?: Function | undefined;
+}): Promise<{
+    matchedIds: string[];
+    count: number;
+    missingSlices: string[];
+    window: number;
+    passes: number;
+    scanned: number;
+}>;
+/**
+ * @typedef {object} Slice
+ * @property {string} id - Stable, word-like id (no whitespace/commas — it is echoed back by the judge).
+ * @property {string} text - The item content shown to the judge.
+ */
+/**
+ * Judge ONE window: run an isolated Loop with the classify prompt over the window's items, and intersect the
+ * returned ids with the ids actually SHOWN this window (RC-2 — a window's judge can only "match" what it was
+ * given; a hallucinated id from another window is dropped). A governance HaltError propagates (the caller turns
+ * it into a clean incomplete); any other Loop fault marks the window DEAD (→ RC-9 missingSlices), never a
+ * silent zero that would undercount.
+ * @param {string} predicate
+ * @param {Slice[]} window
+ * @param {{provider: Provider, ctx?: object, onLlmResult?: Function, policy?: Function, nonce: number}} opts
+ * @returns {Promise<{ids: string[]|null, dead: boolean}>}
+ * @throws {HaltError}
+ */
+export function judgeWindow(predicate: string, window: Slice[], opts: {
+    provider: Provider;
+    ctx?: object;
+    onLlmResult?: Function;
+    policy?: Function;
+    nonce: number;
+}): Promise<{
+    ids: string[] | null;
+    dead: boolean;
+}>;
+/**
+ * The §9.2-validated classify system prompt, GENERALIZED from the POC's hardcoded "SPORTS news" predicate to
+ * an arbitrary one. The load-bearing wording is verbatim ("Examine EACH item individually", "Output ONLY the
+ * IDs", "Comma-separated. If none, output 'none'. No count, no prose.") — the predicate is the only variable.
+ * It MUST return ids, not a count: counting is CODE's job (RC-5 / §9.1), so the judge never does arithmetic.
+ * @param {string} predicate - The task/goal the items are judged against.
+ * @returns {string}
+ */
+export function classifySystem(predicate: string): string;
+/**
+ * Does this text imply a completeness ("all / every / count / how many") ask? Used to upgrade a capped search
+ * to a scan (the only complete path). Conservative by design — a false positive only costs a thorough scan.
+ * @param {unknown} text
+ * @returns {boolean}
+ */
+export function impliesCompleteness(text: unknown): boolean;
+/**
+ * Normalize a raw slice-source into validated `{id, text}` slices (drops malformed entries — a slice with no
+ * string id/text cannot be judged or counted, so it is excluded rather than silently miscounted).
+ * @param {unknown} corpus
+ * @returns {Slice[]}
+ */
+export function normalizeCorpus(corpus: unknown): Slice[];
+/**
+ * The `search` handle tool (RC-5 needle path): litectx `recall` — embeddings ON, `fact`/`episode` (the
+ * KNN-nominate kinds), capped at `KNN_K`. For FINDING the relevant few; the description tells the worker it
+ * CANNOT count (the completeness guard catches a "how many" ask before this tool is ever offered). Returns the
+ * matched items' bodies as text the worker reads; never the whole corpus.
+ * @param {{recall: Function}} litectx
+ * @param {{kinds?: string[], n?: number}} [opts]
+ * @returns {ToolDef}
+ */
+export function buildSearchTool(litectx: {
+    recall: Function;
+}, opts?: {
+    kinds?: string[];
+    n?: number;
+}): ToolDef;
+/**
+ * The `exact` handle tool (RC-5 rule path): a deterministic, embeddings-free code-side predicate filter over
+ * the slice-source — returns every record whose text contains ALL given terms (case-insensitive AND). This is
+ * the "code-side predicate filter" half of §9.2.1; it is complete over the slices it is given (no recall cap)
+ * but only as good as a lexical rule. (FTS-AND over a litectx instance is the alternative, but needs embeddings
+ * OFF to stay exact — deferred; the code-side filter is the embeddings-free path shipped now.)
+ * @param {Slice[]} corpus - The validated slice-source.
+ * @returns {ToolDef}
+ */
+export function buildExactTool(corpus: Slice[]): ToolDef;
+/**
+ * The `scan` handle tool (RC-5 COMPLETE path, the per-query Family-A face of §10 step 7) — the deterministic
+ * counterpart to `search`/`exact` as a TOOL a worker may call per sub-query. Where `search_memory` returns the
+ * top FEW (capped, cannot count) and `exact_match` is a lexical rule, `scan_count` runs the full §9.2.1 scan
+ * (`scanCount`) over EVERY record and returns an exact, CODE-counted total — the only tool that does not silently
+ * undercount. The completeness routing lives in the DESCRIPTIONS, not a code-guard: this tool says "use for how
+ * many / all / count"; `search_memory` says "never use to count" — so a worker picks the complete path per
+ * sub-query (the shape can differ per sub-query with no adopter declaration). RC-9 honesty is preserved at the
+ * tool boundary: a dead window surfaces as an explicit `INCOMPLETE — the count is a floor`, never a clean number
+ * over a hole. A governance `HaltError` from the inner scan PROPAGATES (the Loop turns it into a clean halt —
+ * never wrapped to a `ToolError`).
+ * @param {Slice[] | (() => Promise<Slice[]>)} corpus - The slice-source (array or async, like `litectxCorpus`);
+ *   materialized lazily on first call and cached for the tool's lifetime.
+ * @param {{provider: Provider, window?: number, passes?: number, ctx?: object, onLlmResult?: Function, policy?: Function}} opts
+ * @returns {ToolDef}
+ */
+export function buildScanTool(corpus: Slice[] | (() => Promise<Slice[]>), opts: {
+    provider: Provider;
+    window?: number;
+    passes?: number;
+    ctx?: object;
+    onLlmResult?: Function;
+    policy?: Function;
+}): ToolDef;
+/**
+ * Build a SCAN slice-source backed by a litectx-RESIDENT corpus (facts/episodes the agent already accrued) —
+ * the §10-step-7 deferral un-blocked by litectx 0.26's `enumerate` verb (spec:
+ * docs/01-product/litectx-enumerate-spec.md). Returns the generic async slice-source recurse's scan reads: a
+ * `() => Promise<Slice[]>` that pages through EVERY row of `kind` via `enumerate` (exhaustive — the rank-free
+ * read `recall` structurally cannot do) and maps each to `{id: item.path, text: item.body}`. recurse stays
+ * litectx-agnostic: it depends on this source SHAPE, never on litectx (same stance as `remember`'s Store
+ * socket) — an adopter can hand any `() => Promise<Slice[]>` (a DB, a file, an API) instead.
+ *
+ * Only for a corpus ALREADY in litectx for its own reasons — never ingest a fresh corpus just to enumerate it
+ * back (strictly worse than scanning the in-hand array; spec §1.1).
+ * @param {{enumerate: Function}} litectx
+ * @param {{kind?: 'fact'|'episode', pageSize?: number}} [opts]
+ * @returns {() => Promise<Slice[]>}
+ */
+export function litectxCorpus(litectx: {
+    enumerate: Function;
+}, opts?: {
+    kind?: "fact" | "episode";
+    pageSize?: number;
+}): () => Promise<Slice[]>;
+/**
+ * Deterministic rotation by `k` — the shuffled-boundary mechanism for multi-pass union WITHOUT an RNG (keeps
+ * RC-3 determinism: same corpus + same passes ⇒ identical scan). Rotating the array changes which items share a
+ * window (and each item's within-window position), so an item under-recalled at one window's tail in pass 0
+ * lands mid-window in pass 1 — the §9.2.1 mechanism that lifts recall ~0.85 → ~0.93.
+ * @template T @param {T[]} arr @param {number} k @returns {T[]}
+ */
+export function rotate<T>(arr: T[], k: number): T[];
+export const SCAN_WINDOW: 8;
+export const SCAN_PASSES: 2;
+export const KNN_K: 8;