@hicaru/pi-rlm 0.3.16 → 0.3.17

package/src/text/agent-text.ts

@@ -0,0 +1,58 @@
+/**
+ * Text extraction from host AgentMessages (coding-agent `Message | CustomMessage | …` union).
+ *
+ * The root-Σ modules (core/root-digest.ts, core/root-context.ts) and the index.ts event
+ * handlers all need the same "text payload of a message" projection. One implementation
+ * here; callers never re-walk content blocks. Everything takes `unknown` and narrows via
+ * guards — host shapes evolve, this module is the single adaptation seam.
+ */
+
+/** Text payload of one content block list / string: string as-is, `{text}` blocks joined. */
+export function textContentOf(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  const parts = new Array<string>(content.length);
+  let n = 0;
+  for (const block of content) {
+    if (isTextBlock(block)) parts[n++] = block.text;
+  }
+  parts.length = n;
+  return parts.join("");
+}
+
+function isTextBlock(block: unknown): block is { readonly type: "text"; readonly text: string } {
+  return (
+    typeof block === "object" && block !== null &&
+    (block as Record<string, unknown>).type === "text" &&
+    typeof (block as Record<string, unknown>).text === "string"
+  );
+}
+
+/**
+ * Text payload of a whole AgentMessage: role-disciplined extraction. `thinking` blocks and
+ * tool-call payloads are deliberately skipped (digests/elision want observable prose and
+ * results, never the model's private reasoning). Unknown shapes yield "".
+ */
+export function agentMessageText(message: unknown): string {
+  if (typeof message !== "object" || message === null) return "";
+  const m = message as Record<string, unknown>;
+  switch (m.role) {
+    case "user":
+    case "assistant":
+    case "custom":
+    case "toolResult":
+      return textContentOf(m.content);
+    case "compactionSummary":
+    case "branchSummary":
+      return typeof m.summary === "string" ? m.summary : "";
+    default:
+      return "";
+  }
+}
+
+/** First non-blank line, trimmed and capped — the error-reason shape trackers store. */
+export function firstLine(text: string, maxChars = 200): string {
+  const line = text.split("\n", 1)[0] ?? "";
+  const trimmed = line.trim();
+  return trimmed.length > maxChars ? trimmed.slice(0, maxChars) : trimmed;
+}

package/src/text/parsing.ts

@@ -15,6 +15,8 @@ const FENCE = /(`{3,})[ \t]*repl[ \t]*\r?\n([\s\S]*?)\1/g;
 const FALLBACK_FENCE = /(`{3,})[ \t]*([^`\r\n]*)[ \t]*\r?\n([\s\S]*?)\1/g;
 const PYTHON_TAG = /^py(thon)?$/i;
 
+import { errorMessage } from "../util/errors.ts";
+
 /** Shared fence scan: run `re` over `text`, keep bodies the selector accepts (same trimming). */
 function collectFences(text: string, re: RegExp, select: (m: RegExpExecArray) => string | null): string[] {
   const blocks: string[] = [];
@@ -40,11 +42,41 @@ export function findReplBlocks(text: string): string[] {
   });
 }
 
-/** Truncate REPL stdout for the model's context window (head + tail, with an elision note). */
-export function truncateOutput(text: string, limit = 20_000): string {
+/** One ```state fence: parsed JSON payload, or the parse error (error-as-observation). */
+export type StateFenceResult =
+  | { readonly ok: true; readonly value: unknown }
+  | { readonly ok: false; readonly error: string };
+
+const STATE_FENCE = /(`{3,})[ \t]*state[ \t]*\r?\n([\s\S]*?)\1/g;
+
+/**
+ * Workstream A: extract ```state fences (model-proposed ΔΣ_t) from a response, in document
+ * order. ```repl parsing is untouched — the two fences coexist in one response. Malformed
+ * JSON is surfaced as an error result for the retry loop, never thrown.
+ */
+export function findStatePatches(text: string): readonly StateFenceResult[] {
+  const out: StateFenceResult[] = [];
+  let m: RegExpExecArray | null;
+  STATE_FENCE.lastIndex = 0;
+  while ((m = STATE_FENCE.exec(text)) !== null) {
+    const body = (m[2] ?? "").trim();
+    if (body === "") continue;
+    try {
+      out.push({ ok: true, value: JSON.parse(body) as unknown });
+    } catch (err: unknown) {
+      out.push({ ok: false, error: errorMessage(err) });
+    }
+  }
+  return out;
+}
+
+/** Truncate REPL stdout for the model's context window (head + tail, with an elision note).
+ *  `mark` lets callers specialize the wording (root elision cites the session log) while the
+ *  head/tail math stays the one implementation. */
+export function truncateOutput(text: string, limit = 20_000, mark = "chars elided"): string {
   if (text.length <= limit) return text;
   const head = Math.floor(limit * 0.7);
   const tail = limit - head;
   const cut = text.length - head - tail;
-  return `${text.slice(0, head)}\n... [${cut} chars elided] ...\n${text.slice(-tail)}`;
+  return `${text.slice(0, head)}\n... [${cut} ${mark}] ...\n${text.slice(-tail)}`;
 }

package/src/text/preview.ts

@@ -4,6 +4,9 @@ import type { ReplResult } from "../sandbox/protocol.ts";
 
 const DEFAULT_PREVIEW_CHARS = 200;
 
+/** Chars of a task/prompt shown on the collapsed tool-call line (repl + rlm tools share it). */
+export const CALL_PREVIEW_CHARS = 80;
+
 export function previewText(text: string, maxChars = DEFAULT_PREVIEW_CHARS): string {
   const normalized = text.replace(/\s+/g, " ").trim();
   return normalized.length > maxChars ? `${normalized.slice(0, Math.max(0, maxChars - 1))}…` : normalized;

package/src/text/repl-output.ts

@@ -6,7 +6,7 @@
 import { truncateOutput } from "./parsing.ts";
 
 /** Max stderr kept in model-visible REPL output (headless history and native tool_result). */
-export const STDERR_LIMIT = 8_000;
+const STDERR_LIMIT = 8_000;
 
 /** Prefix stderr so the model can tell prints from exceptions. Empty when stderr is blank. */
 export function formatReplStderr(stderr: string, limit = STDERR_LIMIT): string {

package/src/tool/background-tasks.ts

@@ -19,7 +19,7 @@ import type { Invocation } from "../bridge/handlers/index.ts";
 import { trace, traceEnabled } from "../util/trace.ts";
 
 /** What a drain hands to the turn that is reporting it. */
-export interface BackgroundDrain {
+interface BackgroundDrain {
   readonly subcalls: readonly RlmSubcall[];
   readonly totals: SubcallTotals;
 }

package/src/tool/repl-render.ts

@@ -12,7 +12,7 @@ const EXPANDED_STDERR_CHARS = 500;
 
 // ── Collapsed view ──
 
-export function replStats(details: ReplDetails, theme: Theme): string {
+function replStats(details: ReplDetails, theme: Theme): string {
   const elapsed = details.executionTimeMs > 0 ? `${details.executionTimeMs}ms` : undefined;
   return cardStatsLine(details.totals, theme, elapsed, details.backgroundPending);
 }

package/src/tool/repl-result.ts

@@ -10,7 +10,7 @@ import { capReplResultText, replDelegationNudge } from "../mode/native-guards.ts
 import { formatReplStderr } from "../text/repl-output.ts";
 
 /** Model-visible text assembled from a repl() result. */
-export interface ReplResultText {
+interface ReplResultText {
   readonly text: string;
 }
 

package/src/tool/repl-tool.ts

@@ -29,7 +29,6 @@ import { SandboxManager } from "../sandbox/sandbox-manager.ts";
 import type { SubcallOpts } from "../sandbox/sandbox.ts";
 import { createSubcallHandlers, type Invocation } from "../bridge/handlers/index.ts";
 import { TaskLedger } from "../core/ledger.ts";
-import type { MemoryStore } from "../core/memory.ts";
 import { BackgroundTasks } from "./background-tasks.ts";
 import type { ReplResult } from "../sandbox/protocol.ts";
 import { RlmEmitter } from "./rlm-events.ts";
@@ -38,18 +37,21 @@ import { SubcallStore } from "./subcall-store.ts";
 import type { ReplDetails } from "./repl-details.ts";
 import type { RlmSubcall } from "./rlm-details.ts";
 import { createEngine } from "../core/engine.ts";
+import type { RunState } from "../core/run-state.ts";
 import { modelRef } from "../config/settings.ts";
 import { spinnerFrame } from "../ui/theme.ts";
-import { previewText } from "../text/preview.ts";
+import { CALL_PREVIEW_CHARS, previewText } from "../text/preview.ts";
 import { errorMessage } from "../util/errors.ts";
+import {
+  groundLeafPrompt,
+  skillSearchHandler,
+  type SkillStore,
+} from "../config/skillstate.ts";
 import { createProgressNotifier, validateToolParams } from "./tool-utils.ts";
 import { buildReplResultText, collectReplWarnings } from "./repl-result.ts";
 import { renderReplCollapsed, renderReplExpanded } from "./repl-render.ts";
 import { attachTracer, trace, traceEnabled } from "../util/trace.ts";
 
-/** Chars of code shown on the tool call line. */
-const CALL_PREVIEW_CHARS = 80;
-
 /** Last non-empty line of a Python traceback — the `TypeError: …` line, not the frames. */
 function lastLine(text: string): string {
   const lines = text.trimEnd().split("\n");
@@ -62,7 +64,7 @@ function lastLine(text: string): string {
 
 // ── Parameter schema ──
 
-export const ReplToolParams = Object.freeze(Type.Object({
+const ReplToolParams = Object.freeze(Type.Object({
   code: Type.String({ description: "Python code to execute in the persistent REPL sandbox" }),
 }));
 
@@ -103,7 +105,7 @@ class NativeBridgeState {
 
 // ── Tool factory ──
 
-export interface ReplToolDeps {
+interface ReplToolDeps {
   readonly sandboxManager: SandboxManager;
   readonly model: Model<Api>;
   readonly llmModel: Model<Api>;
@@ -119,10 +121,14 @@ export interface ReplToolDeps {
   readonly resolveGates?: () => SubcallGates;
   /** Session-scoped home for detached spawn() work. */
   readonly background: BackgroundTasks;
+  /** SKILL.state (Workstream B): session store — leaf grounding, skill_search, child Ξ. */
+  readonly skillStore?: SkillStore;
+  /** Root Σ (WS-4): engine-finalize Σ observer, forwarded to createEngine (one seam). */
+  readonly onRunState?: (state: RunState) => void;
+  /** Ξ composer for repl()-spawned child engines (first hop; deeper hops copy via childRun). */
+  readonly getSkillBlock?: (task: string) => string | undefined;
   /** Session tree panel index; omitted → runs don't appear in the widget. */
   readonly runRegistry?: RunRegistry;
-  /** v5 durable memory (session-wide `.rlm` store); omitted → memory off for this tool. */
-  readonly memory?: MemoryStore;
   readonly signal?: AbortSignal;
   readonly onUsage?: (usage: Usage, role: "sub") => void;
   readonly ensureContext?: () => Promise<void>;
@@ -149,25 +155,40 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
   const getModel = (): Model<Api> => deps.getModel?.() ?? deps.model;
   // v5 (audit C6): resolve lazily per call so provider-cap edits via /rlm-config apply live.
   const currentGates = (): SubcallGates => deps.resolveGates?.() ?? deps.gates;
+  // Workstream D: leaf grounding — one closure, self-gating on the live config.
+  const groundLeaf = (prompt: string): string => {
+    const store = deps.skillStore;
+    const cfg = getConfig();
+    if (store === undefined || !cfg.enableSkillState) return prompt;
+    return groundLeafPrompt(store, cfg, prompt);
+  };
 
   // Each rlm_query spawns a child RLM with its own sandbox and turn loop, not a flat
   // one-shot llm_query. The engine is created per call so the child's subcalls, turn
   // progress and cost deltas land on the emitter the parent invocation is using.
-  const runChild = (input: RlmInput, inv: Invocation): Promise<RlmResult> => createEngine({
-    model: getModel(),
-    llmModel: getLlmModel(),
-    registry,
-    config: getConfig(),
-    signal,
-    memory: deps.memory,
-    gates: currentGates(),
-    // Same emitter the parent subcall node lives on — see SubcallHandlerDeps.runChild.
-    emitter: inv.emitter,
-    // Everything a child engine spends is sub-work from this tool's perspective, including
-    // the child's own root turns — so fold both roles into "sub" rather than casting.
-    onUsage: onUsage === undefined ? undefined : (usage: Usage) => onUsage(usage, "sub"),
-    limits: limitsFromConfig(getConfig()),
-  })(input);
+  const runChild = (input: RlmInput, inv: Invocation): Promise<RlmResult> => {
+    // Ξ inheritance, first hop (Workstream C): a repl()-spawned child has no parent RlmInput
+    // to copy from, so the session store composes the block for its task here. Deeper hops
+    // copy input.skillBlock inside childRun (DRY #6 — one construction site).
+    const block = input.skillBlock ?? deps.getSkillBlock?.(input.rootPrompt);
+    const childInput: RlmInput = block === undefined ? input : { ...input, skillBlock: block };
+    return createEngine({
+      model: getModel(),
+      llmModel: getLlmModel(),
+      registry,
+      config: getConfig(),
+      signal,
+      gates: currentGates(),
+      // Same emitter the parent subcall node lives on — see SubcallHandlerDeps.runChild.
+      emitter: inv.emitter,
+      // Everything a child engine spends is sub-work from this tool's perspective, including
+      // the child's own root turns — so fold both roles into "sub" rather than casting.
+      onUsage: onUsage === undefined ? undefined : (usage: Usage) => onUsage(usage, "sub"),
+      limits: limitsFromConfig(getConfig()),
+      skillStore: deps.skillStore,
+      onRunState: deps.onRunState,
+    })(childInput);
+  };
 
   // Built once: the same closures stay correct across repl() calls because everything
   // per-invocation is reached through bridgeState.resolve, not captured here.
@@ -188,8 +209,10 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
     // earlier repl() reaches a child spawned in a later one. Populated before any interrupt can
     // fire: execute() awaits ensureContext() before getOrCreate().
     getChildContext: () => sandboxManager.contextPayload ?? undefined,
+    // SKILL.state: leaf grounding (Workstream D) + Ξ inheritance for children (DRY #6).
+    groundLeaf,
+    getSkillBlock: (task) => deps.getSkillBlock?.(task),
     ledger: sessionLedger,
-    memory: deps.memory,
     trackDetached: (task) => background.track(task),
   });
 
@@ -322,7 +345,8 @@ export function createReplTool(deps: ReplToolDeps): ToolDefinition<typeof ReplTo
           ...subcallHandlers,
           ...(contextBundle?.handlers ?? {}),
           ledgerClaims: () => Promise.resolve(sessionLedger.listClaims()),
-          memoryOp: (op, args) => Promise.resolve(deps.memory?.serviceOp(op, args) ?? "memory off"),
+          // SKILL.state (Workstream E): the model-visible recall surface — one function.
+          skillSearch: skillSearchHandler(() => (getConfig().enableSkillState ? deps.skillStore : undefined)),
         });
 
         // Detect queue contention AFTER sandbox init (initPromise settled, isExecuting now accurate)

package/src/tool/rlm-tool.ts

@@ -13,7 +13,7 @@ import { modelRef } from "../config/settings.ts";
 import { spinnerFrame } from "../ui/theme.ts";
 import type { RunRegistry } from "../ui/panel/run-registry.ts";
 import { markdownTheme } from "../ui/theme-adapter.ts";
-import { previewText } from "../text/preview.ts";
+import { CALL_PREVIEW_CHARS, previewText } from "../text/preview.ts";
 import { errorMessage } from "../util/errors.ts";
 import { type RlmDetails } from "./rlm-details.ts";
 import { RlmEmitter } from "./rlm-events.ts";
@@ -21,14 +21,12 @@ import { RlmEventAggregator } from "./rlm-aggregator.ts";
 import { cardHeader, cardStatsLine, renderCollapsedCard } from "./subcall-render.ts";
 import { createProgressNotifier, validateToolParams } from "./tool-utils.ts";
 
-/** Chars of the prompt shown on the tool call line. */
-const CALL_PREVIEW_CHARS = 80;
-
 // ── Parameter schema ──
 
-export const RlmToolParams = Object.freeze(Type.Object({
+const RlmToolParams = Object.freeze(Type.Object({
   prompt: Type.String({ description: "The task or question for the RLM engine" }),
   context: Type.Optional(Type.String({ description: "Optional context. If omitted, the working directory is packed into context." })),
+  narrative: Type.Optional(Type.Boolean({ description: "History-as-deliverable run (audit/provenance/debug narrative): RunState stays off — the archive is the product." })),
 }));
 
 // ── Rendering helpers ──
@@ -101,6 +99,7 @@ export function createRlmTool(controller: RlmController, runRegistry?: RunRegist
         const input: StartInput = {
           rootPrompt: params.prompt,
           context: params.context ?? undefined,
+          narrative: params.narrative,
         };
         const { done } = controller.start(ctx, input, emitter);
         const result = await done;

package/src/tool/subcall-render.ts

@@ -14,7 +14,7 @@ import type { Theme } from "@earendil-works/pi-coding-agent";
 
 // ── Glyphs ──
 
-export function headlineStatusGlyph(status: SubcallStatus | "aborted" | "done", theme: Theme): string {
+function headlineStatusGlyph(status: SubcallStatus | "aborted" | "done", theme: Theme): string {
   switch (status) {
     case "done": return theme.fg("success", "✓");
     case "error": return theme.fg("error", "✗");

package/src/tool/subcall-store.ts

@@ -7,7 +7,7 @@
  * subcall accumulation logic.
  */
 import type { RlmEmitter, SubcallCreatedEvent, SubcallUpdatedEvent } from "./rlm-events.ts";
-import type { RlmSubcall, SubcallStatus } from "./rlm-details.ts";
+import type { RlmSubcall } from "./rlm-details.ts";
 import { EmitterListener } from "./emitter-listener.ts";
 
 type MutableSubcall = {
@@ -153,7 +153,7 @@ export class SubcallStore extends EmitterListener {
         tokens += node.tokens;
         tokensIn += node.tokensIn;
         tokensOut += node.tokensOut;
-        taken.push(Object.freeze({ ...node, status: node.status as SubcallStatus }));
+        taken.push(Object.freeze({ ...node, status: node.status }));
         this.subcalls.delete(node.id);
       }
     }

package/src/tool/tool-utils.ts

@@ -4,7 +4,7 @@ import type { Static, TSchema } from "typebox";
 import { Value } from "typebox/value";
 import { err, ok, type Result } from "../util/errors.ts";
 
-export interface TextToolResponse<Details> {
+interface TextToolResponse<Details> {
   readonly content: { readonly type: "text"; readonly text: string }[];
   readonly details: Details;
 }
@@ -15,7 +15,7 @@ export function validateToolParams<Schema extends TSchema, Details>(
   toolName: string,
   createErrorDetails: (errors: string) => Details,
 ): Result<Static<Schema>, TextToolResponse<Details>> {
-  if (Value.Check(schema, rawParams)) return ok(rawParams as Static<Schema>);
+  if (Value.Check(schema, rawParams)) return ok(rawParams);
   const errors = [...Value.Errors(schema, rawParams)]
     .map((error) => `${error.instancePath}: ${error.message}`)
     .join("; ");
@@ -25,9 +25,9 @@ export function validateToolParams<Schema extends TSchema, Details>(
   });
 }
 
-export type TextUpdateCallback<Details> = (update: TextToolResponse<Details>) => void;
+type TextUpdateCallback<Details> = (update: TextToolResponse<Details>) => void;
 
-export interface ProgressNotifierOptions<Details> {
+interface ProgressNotifierOptions<Details> {
   readonly onUpdate?: TextUpdateCallback<Details>;
   readonly getDetails: () => Details;
   readonly isRunning: (details: Details) => boolean;
@@ -35,7 +35,7 @@ export interface ProgressNotifierOptions<Details> {
   readonly intervalMs?: number;
 }
 
-export interface ProgressNotifier {
+interface ProgressNotifier {
   readonly notify: () => void;
   readonly start: () => void;
   readonly stop: () => void;

package/src/ui/intro.ts

@@ -4,7 +4,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import type { RlmController } from "../mode/rlm-mode.ts";
 import { modelLabel } from "./status.ts";
 
-export const RLM_GUIDE = `# RLM mode
+const RLM_GUIDE = `# RLM mode
 
 {state}
 

package/src/ui/modal/timeline-store.ts

@@ -16,7 +16,7 @@ import type {
 } from "../../tool/rlm-events.ts";
 import { EmitterListener } from "../../tool/emitter-listener.ts";
 
-export const TIMELINE_CAP = 200;
+const TIMELINE_CAP = 200;
 
 export type TimelineIcon = "spawn" | "phase" | "done" | "error" | "note" | "turn";
 

package/src/ui/model-picker/drilldown.ts

@@ -58,7 +58,7 @@ async function pickFromList(
     });
     if (initialIndex > 0) list.setSelectedIndex(initialIndex);
     const isFilterText = (s: string): boolean =>
-      s.length > 0 && [...s].every((char) => char >= " " && char !== "\x7f");
+      s.length > 0 && Array.from(s).every((char) => char >= " " && char !== "\x7f");
     const isBackspace = (s: string): boolean => s === "\x7f" || s === "\b";
     list.onSelect = (item) => done(item.value);
     list.onCancel = () => done(null);

package/src/ui/model-picker/levels.ts

@@ -10,7 +10,7 @@ import { DynamicBorder } from "@earendil-works/pi-coding-agent";
 import type { Api, Model, ThinkingLevel } from "@earendil-works/pi-ai";
 import { Container, SelectList, Text } from "@earendil-works/pi-tui";
 
-const LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+const LEVELS = Object.freeze(["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const);
 export type SelectableThinkingLevel = (typeof LEVELS)[number];
 
 /** Levels the model actually supports, in canonical order. */

package/src/ui/panel/run-registry.ts

@@ -14,7 +14,7 @@ import type { RlmRunStatus, RlmSubcall, SubcallPhase } from "../../tool/rlm-deta
 import type { RunSnapshot } from "../tree/tree-model.ts";
 import { TimelineStore } from "../modal/timeline-store.ts";
 
-export interface RunRegistration {
+interface RunRegistration {
   readonly runId: string;
   /** Root row label — prompt or code preview. */
   readonly label: string;

package/src/ui/tree/tree-rows.ts

@@ -59,7 +59,7 @@ function formatGroup(row: GroupRow, selected: boolean, width: number, theme: The
   return assembleLine(left, row.tokens, row.tokensIn, row.tokensOut, row.model, selected, width, theme);
 }
 
-export function formatRow(row: TreeRow, selected: boolean, width: number, theme: Theme): string {
+function formatRow(row: TreeRow, selected: boolean, width: number, theme: Theme): string {
   return row.type === "group" ? formatGroup(row, selected, width, theme) : formatNode(row, selected, width, theme);
 }
 

package/src/ui/tree/tree-widget.ts

@@ -28,7 +28,7 @@ const KEYS = Object.freeze({
 } as const);
 
 /** What the panel should do after a keypress. Discriminated — never a boolean soup. */
-export type KeyAction =
+type KeyAction =
   | { readonly type: "swallowed" }
   | { readonly type: "unfocus" }
   | { readonly type: "open"; readonly runId: string; readonly nodeId: string };

package/src/util/bm25.ts

@@ -0,0 +1,97 @@
+/**
+ * Host-side Okapi BM25 (Workstreams C/D/E ranking).
+ *
+ * BM25 DUALITY, documented not accidental: this file and `sandbox/py/retrieval.py`
+ * (`_Bm25Index`) implement the SAME scoring for two runtimes — identical constants, identical
+ * tokenizer, identical idf/norm formulas — so a note ranked here lands in the same order the
+ * sandbox-side `search` would put it. Keep the two files in lockstep (AGENTS.md convention).
+ */
+
+const BM25_K1 = 1.2; // mirrors retrieval.py:_BM25_K1
+const BM25_B = 0.75; // mirrors retrieval.py:_BM25_B
+// Mirrors retrieval.py:_TOKEN_SPLIT / _CAMEL_SPLIT: lowercased alphanumeric runs plus
+// camelCase parts, so `resolveModelId`-style identifiers match their prose spellings.
+const TOKEN_SPLIT = /[^0-9A-Za-z]+/;
+const CAMEL_SPLIT = /(?<=[a-z0-9])(?=[A-Z])/;
+
+export function bm25Tokenize(text: string): readonly string[] {
+  const out: string[] = [];
+  for (const raw of text.split(TOKEN_SPLIT)) {
+    if (raw === "") continue;
+    const lowered = raw.toLowerCase();
+    out.push(lowered);
+    if (raw.length > 3) {
+      const parts = raw.split(CAMEL_SPLIT);
+      if (parts.length > 1) {
+        for (const part of parts) {
+          const piece = part.toLowerCase();
+          if (piece !== "" && piece !== lowered) out.push(piece);
+        }
+      }
+    }
+  }
+  return out;
+}
+
+export interface Bm25Entry<T> {
+  readonly item: T;
+  readonly text: string;
+}
+
+export interface Bm25Hit<T> {
+  readonly item: T;
+  readonly score: number;
+}
+
+/**
+ * Rank entries against a query, best first, top-k, score > 0 only.
+ * Pre-allocated score/index arrays; no growth in the scoring loops.
+ */
+export function bm25Rank<T>(
+  query: string,
+  entries: readonly Bm25Entry<T>[],
+  k: number,
+): readonly Bm25Hit<T>[] {
+  const n = entries.length;
+  if (n === 0 || k <= 0) return [];
+  const docLens = new Array<number>(n);
+  const postings = new Map<string, Array<readonly [number, number]>>();
+  for (let i = 0; i < n; i++) {
+    const terms = bm25Tokenize(entries[i].text);
+    docLens[i] = terms.length;
+    const freq = new Map<string, number>();
+    for (const term of terms) freq.set(term, (freq.get(term) ?? 0) + 1);
+    for (const [term, tf] of freq) {
+      const list = postings.get(term);
+      if (list !== undefined) list.push([i, tf]);
+      else postings.set(term, [[i, tf]]);
+    }
+  }
+  let totalLen = 0;
+  for (let i = 0; i < n; i++) totalLen += docLens[i];
+  const avgLen = totalLen > 0 ? totalLen / n : 1.0;
+
+  const scores = new Array<number>(n).fill(0);
+  const seen = new Set<string>();
+  for (const term of bm25Tokenize(query)) {
+    if (seen.has(term)) continue; // Python twin scores set(terms)
+    seen.add(term);
+    const posting = postings.get(term);
+    if (posting === undefined) continue;
+    const df = posting.length;
+    const idf = Math.log(1.0 + (n - df + 0.5) / (df + 0.5));
+    for (const [idx, tf] of posting) {
+      const norm = BM25_K1 * (1.0 - BM25_B + BM25_B * (docLens[idx] / avgLen));
+      scores[idx] += (idf * (tf * (BM25_K1 + 1.0))) / (tf + norm);
+    }
+  }
+
+  const order = Array.from({ length: n }, (_, i) => i);
+  order.sort((a, b) => scores[b] - scores[a] || a - b); // deterministic tie-break
+  const out: Bm25Hit<T>[] = [];
+  for (let i = 0; i < n && out.length < k; i++) {
+    const idx = order[i];
+    if (scores[idx] > 0) out.push({ item: entries[idx].item, score: scores[idx] });
+  }
+  return out;
+}

package/src/util/concurrency.ts

@@ -93,7 +93,7 @@ export function createSubcallGates(leafLimit: number, childLimit: number = leafL
 }
 
 /** Provider-capped config slice (RlmConfig satisfies this structurally). */
-export interface ProviderCapConfig {
+interface ProviderCapConfig {
   readonly maxConcurrentSubcalls: number;
   readonly maxConcurrentChildren: number;
   /** v5: per-provider concurrent-request caps, e.g. { zai: 4 }. Caps only ever LOWER a limit. */

package/src/util/errors.ts

@@ -12,7 +12,7 @@ export function err<T = never, E = string>(error: E): Result<T, E> {
   return { ok: false, error };
 }
 
-export const ERROR_PREFIX = "Error:";
+const ERROR_PREFIX = "Error:";
 
 export function formatError(message: string): string {
   return `${ERROR_PREFIX} ${message}`;