bare-agent 0.19.0 → 0.21.0

package/README.md

@@ -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,33 @@ 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** (`opts.retrieval`):
+
+| `retrieval` | Use it for | How |
+|---|---|---|
+| `'scan'` *(default over a corpus)* | "how many / all / count" | scans every slice, LLM-judges each, **code-counts** the union — the only path that can't silently undercount |
+| `'search'` | find a needle (few matches) | litectx `recall` handle tool, embeddings on — **cannot count** |
+| `'exact'` | rule / exact-term match | code-side AND-filter, embeddings off |
+| `'tools'` | mixed task (needle *and* count) | offers all three; the worker picks per sub-query by tool description |
+
+```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.

package/bareagent.context.md

@@ -1,7 +1,7 @@
 # bareagent — Integration Guide
 
 > For AI assistants and developers wiring bareagent into a project.
-> v0.19.0 | Node.js >= 18 | zero required deps (`bareguard ^0.9.0` optional peer for governance) | Apache 2.0
+> v0.21.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)
 
@@ -34,6 +34,9 @@ Eight entry points:
 | Size a goal before planning (no LLM) | assessComplexity — `needsPlanning` gates a Planner pass |
 | Kill a spawned child that hangs silently | createSpawnTool / spawnChild `{ idleTimeoutMs }` |
 | Execute a step DAG with parallelism | runPlan + executeFn |
+| Decompose a hard task into a verified tree (RLM) | recurse — decompose → fan-out → verify → synthesize in one call (**wire a gate**, cost is open by design) |
+| Count / answer "how many / all" over a corpus, honestly | recurse(task, ctx, `{ corpus, retrieval: 'scan' }`) — scans every slice, CODE-counts |
+| Give recurse workers a persona/role (senior-dev stance) | recurse(task, ctx, `{ persona }`) — prepended to every worker, carries down the tree; not applied to the verifier |
 | Track task state (pending/running/done/failed) | StateMachine |
 | Run agent turns on a schedule (cron, timers) | Scheduler |
 | Require human approval before dangerous actions | Checkpoint |
@@ -599,6 +602,72 @@ const results = await runPlan(steps, async (step) => {
 // results: [{ id: 's1', status: 'done', result: '...' }, { id: 's2', status: 'failed', error: '...' }, ...]
 ```
 
+## Wiring with recurse (RLM — decompose → fan-out → verify → synthesize)
+
+`recurse(task, ctx, opts)` is the **Recursive Language Models** primitive (v0.20.0): one import that decomposes a hard task into fresh-context workers, verifies against a setpoint, and synthesizes one result. It is **thin glue composed around `Loop`/`Planner`/`runPlan`/`Evaluator`/`spawn`** — not a new engine, never imported by `loop.js`. Returns `{ result, verdict, receipts }` on convergence, or `{ incomplete, best, missingSlices, receipts }` on guard exhaustion / a dead worker — **never a fabricated success** (RC-9).
+
+> **⚠️ Cost is open by DESIGN — wire a gate.** `recurse()` adds NO intrinsic total-work cap. On the **Family-A default** (model-driven) a node can spawn up to ~100 children per level, each recursing to `opts.maxDepth` (default 3) — so token/$ spend compounds and is bounded **only by your gate**, not by recurse. A live POC saw a weak model do 40–117 calls in one run. **Always wire bareguard** (`ctx.policy` via `wireGate`) for any non-trivial or untrusted run — it enforces depth/budget/call caps and turns a runaway into a clean `{ incomplete }` (proven: a wired `Gate` cut a 43–117-call runaway to 4–5 calls). The local brake without a gate is `opts.maxDepth: 1` (flat, no nesting). The forced modes (`mode:'fanout'`/`'partition'`) ARE bounded (deterministic count + concurrency cap).
+
+```javascript
+const { recurse, wireGate } = require('bare-agent');
+const { Gate } = require('bareguard');
+
+// ALWAYS run governed for real work — the gate is the total-work bound.
+const gate = new Gate({ budget: { maxCostUsd: 0.50 }, limits: { maxTurns: 30, maxDepth: 3 }, humanChannel: async () => ({ decision: 'deny' }) });
+await gate.init();
+const { policy, onLlmResult } = wireGate(gate);
+
+// ctx = runtime wiring threaded down the whole tree; opts = policy knobs.
+const ctx = { provider, policy, onLlmResult };     // policy + onLlmResult = the gate over every node + the verifier
+const out = await recurse('Audit this 2000-line module for security bugs and rank them', ctx, { maxDepth: 3 });
+
+if (out.incomplete) {
+  console.warn('did not converge:', out.missingSlices, '— best partial:', out.best);  // honest, never a faked pass
+} else {
+  console.log(out.result, out.verdict);            // the synthesized answer + the verifier's gap report
+}
+console.log(out.receipts.spawned.length);          // RC-10 audit tree: parent→child lineage, per-node tokens/verdict
+```
+
+**Control families (how the tree is shaped):**
+
+- **Family A — model-driven (default).** The worker is handed an in-process `spawn_child` tool and *decides* whether to split. `assessComplexity` is a **hint, not a gate** (only `simple → single-shot`, and the non-overridable `critical → force adversarial verify` safety floor). Nothing extra to set.
+- **Family B — forced fan-out (opt-in).** `{ count: N }` → exactly N independent parallel workers via `Planner`→`runPlan`; or `{ mode: 'fanout' }` → count derived from the complexity tier (medium/complex/critical → 2/4/6). Deterministic + concurrency-capped.
+- **`{ mode: 'partition', corpus, workerBudget }`** — data-driven WIDTH: measure the corpus, split into `max(count floor, ⌈size/workerBudget⌉)` parallel scan-workers, union-count. A pre-wave `recurse_partition` policy checkpoint fires before any worker spends.
+
+**Retrieval over a corpus** (`opts.corpus = {id,text}[]` or an async `() => Promise<Slice[]>`, e.g. `litectxCorpus(litectx, {kind})`). Context reaches a worker as a HANDLE routed by question shape:
+
+| `retrieval` | For | Note |
+|---|---|---|
+| `'scan'` *(default when `corpus` present)* | "how many / all / count" | scans every slice, LLM-judges, **CODE-counts** the union — the only path that can't undercount; `window` 8, `passes` 2 |
+| `'search'` | find a needle | litectx `recall` tool (needs `ctx.litectx`), embeddings on — **cannot count** |
+| `'exact'` | rule / exact-term match | code-side AND-filter, embeddings off |
+| `'tools'` | mixed task (needle *and* count) | offers `scan_count` + `search_memory` + `exact_match`; worker picks per sub-query by tool description |
+
+A completeness guard **upgrades** a `'search'` on a "how many / all" ask to `'scan'` (upgrade-only, never a silent downgrade). Aggregation is **always code**, never a model-stated number.
+
+```javascript
+// Honest count over a corpus — scans every slice, code-counts the matches.
+const { result } = await recurse(
+  'How many of these support tickets are billing disputes?',
+  { provider, policy },                            // still wire the gate
+  { corpus: tickets /* {id,text}[] */, retrieval: 'scan' },
+);
+console.log(result.count, result.matchedIds);      // a code-derived count + the ids that back it
+```
+
+**Synthesis (`opts.synthesize`):** a **function** (deterministic code-reduce over child `results` — use for arithmetic/aggregation; LLM arithmetic over partials carried ~10–15% error), or `'concat'` (lossless no-LLM join), or `'merge'` (isolated Loop-driven subjective merge). Default = the parent model's own closing-turn synthesis. **`opts.contract`** = a definition-of-done the verifier grades against (instead of the loose task); **`opts.evaluate`** overrides the verifier. Exported helpers for the per-query face: `buildScanTool`, `buildSearchTool`, `buildExactTool`, `litectxCorpus`.
+
+**Worker persona (`opts.persona`, v0.21.0):** a string PREPENDED to every Family-A worker's system prompt — give workers a stance (`persona: 'You are a senior security engineer; be specific and cite the exact file:line'`). It **augments**, never replaces, the built-in decomposition policy + depth-scrub (those drive the spawn mechanics), and **carries down the whole tree** (a child of a "senior security engineer" is still one). It is deliberately **not** applied to the isolated verifier (that isolation is what defeats self-grading sycophancy) nor the deterministic scan judge. Absent ⇒ the worker prompt is unchanged from pre-0.21.
+
+```javascript
+const out = await recurse('Audit auth.js, billing.js, gateway.js for authz bugs', ctx, {
+  persona: 'You are a blunt senior application-security engineer. Report each finding as file:line + impact + fix.',
+});
+```
+
+**What a delegated child inherits (important — the setpoint is the TOP node's job):** when a worker delegates with `spawn_child`, the child runs a **fresh `recurse`** that inherits `tools`, `synthesize`, `maxDepth`, and `persona` — but the parent's **`contract`/`evaluate` are stripped** (and the forced `count`/`mode` + the corpus `retrieval` knobs). A slice is not graded against the *whole*-task definition-of-done (that verdict is the top node's, and a slice satisfying the whole DoD is the wrong question); only the top `recurse` verifies the synthesized result. The non-overridable `critical → force-verify` safety floor still fires per node (it keys on the task text, not the contract). So: set `contract`/`evaluate` once at the top; they do not — and should not — re-run per intermediate node.
+
 ## Provider options
 
 ```javascript

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.19.0",
+  "version": "0.21.0",
   "files": [
     "index.js",
     "index.d.ts",
@@ -92,8 +92,8 @@
     }
   },
   "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",
@@ -102,7 +102,7 @@
   "devDependencies": {
     "@types/node": "^22.19.19",
     "bareguard": "^0.9.0",
-    "litectx": "^0.16.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;