@hicaru/pi-rlm 0.3.16 → 0.3.18

package/src/config/settings.ts

@@ -5,9 +5,10 @@ import { dirname, join } from "node:path";
 import { getAgentDir, type ModelRegistry } from "@earendil-works/pi-coding-agent";
 import type { Api, Model, ThinkingLevel } from "@earendil-works/pi-ai";
 import type { RlmConfig } from "../core/types.ts";
+import { trace, traceEnabled } from "../util/trace.ts";
 import { DEFAULT_CONFIG } from "./defaults.ts";
 
-export interface PersistedSettings {
+interface PersistedSettings {
   readonly config: Partial<RlmConfig>;
   /** "provider/id" of the pinned sub-LLM, or undefined for "cheapest (auto)".
    *  `null` = explicit "cheapest" clear (omit key on disk). */
@@ -31,6 +32,21 @@ function validateBoolean(v: unknown): boolean | undefined {
   return typeof v === "boolean" ? v : undefined;
 }
 
+/**
+ * R0 enforcement (/tmp/ROOT_FULL_SKILLSTATE_PLAN.md): the SKILL.state paradigm flags are
+ * operating law — they ALWAYS resolve to `true`, whatever rlm.json says. An explicit `false`
+ * is not an error (fail-soft by contract): it is traced (`skillstate.override-ignored`) and
+ * ignored, so a hostile or typo'd config loses visibly instead of crashing the load or
+ * silently unbounding the root context. Calibrations (window sizes, budgets) stay tunable —
+ * the PARADIGM is enforced, the calibrations are not.
+ */
+function validateEnforcedOn(value: unknown, flag: string): true {
+  if (value === false && traceEnabled) {
+    trace("skillstate.override-ignored", { flag, value });
+  }
+  return true;
+}
+
 function validateString(v: unknown): string | undefined {
   return typeof v === "string" && v.trim() ? v : undefined;
 }
@@ -104,8 +120,7 @@ export function validateConfig(raw: unknown): Partial<RlmConfig> {
   if (subSystemPrompt !== undefined) out.subSystemPrompt = subSystemPrompt;
   const sandboxInitTimeoutMs = validateNumber(r.sandboxInitTimeoutMs, 100);
   if (sandboxInitTimeoutMs !== undefined) out.sandboxInitTimeoutMs = sandboxInitTimeoutMs;
-  // `libraryLoader` is the pre-rename key — still read so an existing rlm.json survives the upgrade.
-  const contextLoader = validateBoolean(r.contextLoader) ?? validateBoolean(r.libraryLoader);
+  const contextLoader = validateBoolean(r.contextLoader);
   if (contextLoader !== undefined) out.contextLoader = contextLoader;
   const autoSeedCwd = validateBoolean(r.autoSeedCwd);
   if (autoSeedCwd !== undefined) out.autoSeedCwd = autoSeedCwd;
@@ -127,18 +142,6 @@ export function validateConfig(raw: unknown): Partial<RlmConfig> {
   if (enableLedger !== undefined) out.enableLedger = enableLedger;
   const rlmBudget = validateNumber(r.rlmBudget, 0);
   if (rlmBudget !== undefined) out.rlmBudget = rlmBudget;
-  // v5 durable memory
-  const enableMemory = validateBoolean(r.enableMemory);
-  if (enableMemory !== undefined) out.enableMemory = enableMemory;
-  const injectNoteTokens = validateNumber(r.injectNoteTokens, 100);
-  if (injectNoteTokens !== undefined) out.injectNoteTokens = injectNoteTokens;
-  const evolveEvery = validateNumber(r.evolveEvery, 0);
-  if (evolveEvery !== undefined) out.evolveEvery = evolveEvery;
-  if (r.memoryDir === null) out.memoryDir = null;
-  else {
-    const memoryDir = validateString(r.memoryDir);
-    if (memoryDir !== undefined) out.memoryDir = memoryDir;
-  }
   // v5 provider concurrency caps: { provider: minConcurrent }
   if (typeof r.providerMaxConcurrent === "object" && r.providerMaxConcurrent !== null) {
     const caps: Record<string, number> = {};
@@ -148,11 +151,39 @@ export function validateConfig(raw: unknown): Partial<RlmConfig> {
     }
     if (Object.keys(caps).length > 0) out.providerMaxConcurrent = Object.freeze(caps);
   }
-  // v5 child surface doctrine
-  if (r.childSurface === "delegation" || r.childSurface === "legacy") out.childSurface = r.childSurface;
   // Verification-discipline nudge (default OFF).
   const enableVerificationNudge = validateBoolean(r.enableVerificationNudge);
   if (enableVerificationNudge !== undefined) out.enableVerificationNudge = enableVerificationNudge;
+  // SKILL.state integration (Workstreams A–F) — paradigm flags ENFORCED (R0); runStateRetryMax
+  // is a calibration and stays tunable.
+  out.enableRunState = validateEnforcedOn(r.enableRunState, "enableRunState");
+  const runStateRetryMax = validateNumber(r.runStateRetryMax, 0);
+  if (runStateRetryMax !== undefined) out.runStateRetryMax = runStateRetryMax;
+  out.enableSkillState = validateEnforcedOn(r.enableSkillState, "enableSkillState");
+  out.enableSkillStateDistill = validateEnforcedOn(r.enableSkillStateDistill, "enableSkillStateDistill");
+  const skillStateMaxTokens = validateNumber(r.skillStateMaxTokens, 50);
+  if (skillStateMaxTokens !== undefined) out.skillStateMaxTokens = skillStateMaxTokens;
+  const skillStateLeafTokens = validateNumber(r.skillStateLeafTokens, 0);
+  if (skillStateLeafTokens !== undefined) out.skillStateLeafTokens = skillStateLeafTokens;
+  const skillStateMinScore = validateNumber(r.skillStateMinScore, 0);
+  if (skillStateMinScore !== undefined) out.skillStateMinScore = skillStateMinScore;
+  const skillStateNotesPerProject = validateNumber(r.skillStateNotesPerProject, 1);
+  if (skillStateNotesPerProject !== undefined) out.skillStateNotesPerProject = skillStateNotesPerProject;
+  // Root Σ integration (WS-2..WS-4) — paradigm flags ENFORCED (R0); the window/byte knobs
+  // below are calibrations and stay tunable.
+  out.enableRootDigestCompaction = validateEnforcedOn(r.enableRootDigestCompaction, "enableRootDigestCompaction");
+  const rootDigestKeepRecentChars = validateNumber(r.rootDigestKeepRecentChars, 200);
+  if (rootDigestKeepRecentChars !== undefined) out.rootDigestKeepRecentChars = rootDigestKeepRecentChars;
+  const rootDigestMaxChars = validateNumber(r.rootDigestMaxChars, 200);
+  if (rootDigestMaxChars !== undefined) out.rootDigestMaxChars = rootDigestMaxChars;
+  out.enableRootContextTransform = validateEnforcedOn(r.enableRootContextTransform, "enableRootContextTransform");
+  const rootContextKeepTurns = validateNumber(r.rootContextKeepTurns, 0);
+  if (rootContextKeepTurns !== undefined) out.rootContextKeepTurns = rootContextKeepTurns;
+  const rootContextElideChars = validateNumber(r.rootContextElideChars, 100);
+  if (rootContextElideChars !== undefined) out.rootContextElideChars = rootContextElideChars;
+  const rootContextSnapshot = validateBoolean(r.rootContextSnapshot);
+  if (rootContextSnapshot !== undefined) out.rootContextSnapshot = rootContextSnapshot;
+  out.enableRootStateFences = validateEnforcedOn(r.enableRootStateFences, "enableRootStateFences");
   if (typeof r.subSampling === "object" && r.subSampling !== null) {
     const ss = r.subSampling as Record<string, unknown>;
     const sampling: { maxTokens?: number; temperature?: number; reasoning?: ThinkingLevel } = {};
@@ -185,8 +216,7 @@ export async function loadSettings(): Promise<PersistedSettings> {
     const r = raw as Record<string, unknown>;
     return {
       config: validateConfig(r.config),
-      // `worker` is the pre-rename key — still read so an existing pin survives the upgrade.
-      llm: validateString(r.llm) ?? validateString(r.worker),
+      llm: validateString(r.llm),
       rlm: validateString(r.rlm),
     };
   } catch {
@@ -242,16 +272,8 @@ export function modelRef(model: Model<Api> | undefined): string | undefined {
   return model ? `${model.provider}/${model.id}` : undefined;
 }
 
-/**
- * Human-readable "provider/id" for a sub-call node: the resolved override when one was
- * supplied and resolves, otherwise the fallback model. Shared by the llm and rlm bridges
- * so sub-call trees label their nodes identically.
- */
-export function displayModelRef(
-  registry: ModelRegistry,
-  override: string | null,
-  fallback: Model<Api>,
-): string {
-  const resolved = override ? (resolveModelId(registry, override) ?? fallback) : fallback;
-  return modelRef(resolved) ?? fallback.id;
+/** Single "provider/id" projection for sub-call node labels — shared by the llm and rlm
+ *  bridges so sub-call trees label their nodes identically. */
+export function modelLabelOf(model: Model<Api>): string {
+  return modelRef(model) ?? model.id;
 }

package/src/config/skillstate.ts

@@ -0,0 +1,465 @@
+/**
+ * Workstream B — SkillState: the persistent cross-session distilled-knowledge store.
+ *
+ * One file per agent (`rlm-skillstate.json`), one section per project (cwd fingerprint). Notes
+ * are A-Mem-shaped (minus embeddings — BM25 lexical scoring only): write-time keywords/tags/
+ * contextual description, reinforcement by re-encounter (`hits`), LRU eviction with the
+ * top-hits quartile pinned.
+ *
+ * Persistence mirrors `config/settings.ts` exactly — the documented template, not copied
+ * logic: fail-soft reader narrowing `JSON.parse(…) as unknown` through a type guard, fail-soft
+ * boolean writer (`mkdir` → `writeFile` → `true | false`), frozen empty value on miss/corrupt.
+ * The three-state pin semantics of settings (`undefined` = merge-from-disk, `null` = explicit
+ * clear) do not apply here: the session-scoped SkillStore is the single writer — it hydrates
+ * the whole file, mutates its own project section, and flushes the whole file back, so other
+ * projects' sections ride along untouched.
+ */
+
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { bm25Rank } from "../util/bm25.ts";
+import { deepMergeWithNullDeletion } from "../util/state-merge.ts";
+import { formatError } from "../util/errors.ts";
+import { isRecord } from "../util/type-guards.ts";
+import type { RunState } from "../core/run-state.ts";
+import type { RlmConfig } from "../core/types.ts";
+import { skillStateLines } from "../prompts/glossary.ts";
+
+export const SKILL_STATE_FILE = "rlm-skillstate.json";
+
+/** A-Mem-derived note (no embedding): write-time annotation + reinforcement counter. */
+export interface SkillNote {
+  /** Claim key — hash(project + normalized text); ledger-style dedup id. */
+  readonly id: string;
+  /** ≤240 chars, factual, path-anchored. */
+  readonly text: string;
+  /** A-Mem K_i. */
+  readonly keywords: readonly string[];
+  /** A-Mem G_i — "config" | "gotcha" | "symbol" | "recipe". */
+  readonly tags: readonly string[];
+  /** A-Mem X_i — why it matters (≤120 chars). */
+  readonly context: string;
+  /** Reinforcement count: a duplicate write bumps this instead of duplicating. */
+  readonly hits: number;
+  readonly ts: number;
+}
+
+export interface SkillStateFile {
+  readonly version: 1;
+  /** key: cwd fingerprint (projectFingerprint of the absolute cwd). */
+  readonly projects: Readonly<Record<string, readonly SkillNote[]>>;
+}
+
+export const EMPTY_SKILL_STATE: SkillStateFile = Object.freeze({
+  version: 1,
+  projects: Object.freeze({}),
+});
+
+const TAGS: ReadonlySet<string> = new Set(["config", "gotcha", "symbol", "recipe"]);
+const NOTE_MAX_CHARS = 240;
+const CONTEXT_MAX_CHARS = 120;
+const KEYWORDS_MAX = 6;
+
+export function skillStatePath(dir?: string): string {
+  return join(dir ?? getAgentDir(), SKILL_STATE_FILE);
+}
+
+/** Deterministic project key — stable across sessions on the same machine. */
+export function projectFingerprint(cwd: string): string {
+  return fnv1aHex(resolve(cwd), 0x811c9dc5).slice(0, 12);
+}
+
+/**
+ * Root Σ WS-1: the BM25 query for a root Ξ composition — the LIVE user prompt wins so
+ * mid-session harvested notes rank against what the user is actually asking; the static
+ * system-prompt slice is only the empty-prompt fallback (prior behavior).
+ */
+export function xiQuery(prompt: string, fallback: string): string {
+  const trimmed = prompt.trim();
+  return trimmed !== "" ? trimmed : fallback;
+}
+
+/** FNV-1a hex; two passes for long ids. Never cryptographic — dedup keys only. */
+function fnv1aHex(text: string, seed: number): string {
+  let hash = seed | 0;
+  for (let i = 0; i < text.length; i++) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+function noteId(project: string, text: string): string {
+  const normalized = text.trim().toLowerCase().replace(/\s+/g, " ");
+  return `${fnv1aHex(`${project}\u0000${normalized}`, 0x811c9dc5)}${fnv1aHex(normalized, 0x01000193)}`;
+}
+
+function normalizeTags(tags: readonly string[] | undefined): readonly string[] {
+  if (tags === undefined) return ["symbol"];
+  const out: string[] = [];
+  for (const tag of tags) {
+    if (TAGS.has(tag) && !out.includes(tag)) out.push(tag);
+  }
+  return out.length > 0 ? out : ["symbol"];
+}
+
+export function isSkillNote(value: unknown): value is SkillNote {
+  if (!isRecord(value)) return false;
+  return (
+    typeof value.id === "string" &&
+    typeof value.text === "string" &&
+    isStringArray(value.keywords) &&
+    isStringArray(value.tags) &&
+    typeof value.context === "string" &&
+    typeof value.hits === "number" &&
+    typeof value.ts === "number"
+  );
+}
+
+export function isSkillStateFile(value: unknown): value is SkillStateFile {
+  if (!isRecord(value) || value.version !== 1 || !isRecord(value.projects)) return false;
+  for (const notes of Object.values(value.projects)) {
+    if (!Array.isArray(notes)) return false;
+    // Corrupt notes are dropped, not fatal (fail-soft read discipline).
+    if (!notes.every((n) => isSkillNote(n))) return false;
+  }
+  return true;
+}
+
+function isStringArray(value: unknown): value is readonly string[] {
+  return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+
+/** Fail-soft reader — mirrors settings.ts:loadSettings. Corrupt/missing ⇒ frozen empty. */
+export async function loadSkillState(dir?: string): Promise<SkillStateFile> {
+  try {
+    const raw = JSON.parse(await readFile(skillStatePath(dir), "utf8")) as unknown;
+    if (isSkillStateFile(raw)) return raw;
+    return EMPTY_SKILL_STATE;
+  } catch {
+    return EMPTY_SKILL_STATE;
+  }
+}
+
+/** Fail-soft boolean writer — mirrors settings.ts:saveSettings. */
+export async function saveSkillState(s: SkillStateFile, dir?: string): Promise<boolean> {
+  try {
+    const p = skillStatePath(dir);
+    await mkdir(dirname(p), { recursive: true });
+    await writeFile(p, JSON.stringify(s));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ── Distillation: Σ → notes (the construction half of the one interface) ────────────────
+
+/** Input note shape accepted by SkillStore.merge — ids are computed, never supplied. */
+export interface SkillNoteInput {
+  readonly text: string;
+  readonly keywords?: readonly string[];
+  readonly tags?: readonly string[];
+  readonly context?: string;
+}
+
+const PATH_TOKEN = /(?:[\w@.-]+\/)+[\w@.-]+/g;
+const CAMEL_SPLIT = /(?<=[a-z0-9])(?=[A-Z])/;
+
+/** Deterministic keywords: path tokens + camelCase parts + long words, deduped, ≤6. */
+function keywordsOf(text: string): readonly string[] {
+  const out: string[] = [];
+  const push = (word: string): void => {
+    const w = word.trim();
+    if (w.length >= 3 && !out.includes(w) && out.length < KEYWORDS_MAX) out.push(w);
+  };
+  for (const match of text.matchAll(PATH_TOKEN)) push(match[0]);
+  for (const raw of text.split(/[^0-9A-Za-z]+/)) {
+    if (raw.length > 3) {
+      const parts = raw.split(CAMEL_SPLIT);
+      if (parts.length > 1) for (const part of parts) push(part.toLowerCase());
+    }
+  }
+  return out;
+}
+
+/**
+ * Workstream B Hook 1 (deterministic half): harvest Σ into note inputs — zero extra tokens.
+ * verifiedFacts → "symbol" notes; successful approaches → "recipe" notes.
+ */
+export function notesFromRunState(state: RunState): readonly SkillNoteInput[] {
+  const notes: SkillNoteInput[] = [];
+  for (const fact of state.verifiedFacts) {
+    if (fact.trim().length < 8) continue;
+    notes.push({
+      text: fact.trim().slice(0, NOTE_MAX_CHARS),
+      keywords: keywordsOf(fact),
+      tags: ["symbol"],
+      context: state.task.slice(0, CONTEXT_MAX_CHARS),
+    });
+  }
+  for (const [key, outcome] of Object.entries(state.testedApproaches)) {
+    if (outcome.status !== "succeeded") continue;
+    const text = `${key}: ${outcome.evidence}`.slice(0, NOTE_MAX_CHARS);
+    notes.push({
+      text,
+      keywords: keywordsOf(text),
+      tags: ["recipe"],
+      context: state.task.slice(0, CONTEXT_MAX_CHARS),
+    });
+  }
+  return notes;
+}
+
+/** A-Mem phrasing prompt (Hook 1, LLM half — enableSkillStateDistill, default ON). */
+export function distillPromptFor(state: RunState): string {
+  return [
+    "Distill AT MOST 6 durable, reusable project facts from this run. One per line, exactly:",
+    "text | kw1, kw2 | tag",
+    'tag ∈ {config, gotcha, symbol, recipe}. text ≤240 chars, factual, path-anchored. No preamble.',
+    "",
+    `Run task: ${state.task}`,
+    "Verified facts:",
+    ...state.verifiedFacts.slice(-12).map((f) => `- ${f}`),
+  ].join("\n");
+}
+
+/** Defensive parser for the distill leaf's output — anything malformed is dropped. */
+export function parseDistilledNotes(raw: string): readonly SkillNoteInput[] {
+  const out: SkillNoteInput[] = [];
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim().replace(/^-\s*/, "");
+    if (trimmed === "") continue;
+    const parts = trimmed.split("|");
+    if (parts.length < 2) continue;
+    const text = parts[0].trim();
+    if (text.length < 8) continue;
+    const keywords = (parts[1] ?? "")
+      .split(",")
+      .map((k) => k.trim())
+      .filter((k) => k.length >= 3)
+      .slice(0, KEYWORDS_MAX);
+    const tags = (parts[2] ?? "")
+      .split(/[\s,]+/)
+      .map((t) => t.trim())
+      .filter((t) => TAGS.has(t));
+    out.push({ text: text.slice(0, NOTE_MAX_CHARS), keywords, tags: normalizeTags(tags) });
+    if (out.length >= 6) break;
+  }
+  return out;
+}
+
+// ── Read path: BM25 selection for Ξ, leaf grounding, and skill_search ───────────────────
+
+function noteCorpus(note: SkillNote): string {
+  return `${note.text} ${note.keywords.join(" ")} ${note.tags.join(" ")} ${note.context}`;
+}
+
+export interface SkillSearchHit {
+  readonly id: string;
+  readonly text: string;
+  readonly tags: readonly string[];
+  readonly score: number;
+}
+
+/**
+ * The session-scoped store — hydrated once at session_start, flushed at session_shutdown.
+ * All recall (Ξ block, leaf grounding, skill_search) reads through the same BM25 rank.
+ */
+export class SkillStore {
+  private constructor(
+    private file: SkillStateFile,
+    private readonly project: string,
+    private readonly notesPerProject: number,
+    private readonly dir: string | undefined,
+    private dirty = false,
+  ) {}
+
+  static async hydrate(notesPerProject: number, dir?: string): Promise<SkillStore> {
+    return new SkillStore(
+      await loadSkillState(dir),
+      projectFingerprint(process.cwd()),
+      Math.max(1, Math.floor(notesPerProject)),
+      dir,
+    );
+  }
+
+  get projectKey(): string {
+    return this.project;
+  }
+
+  get noteCount(): number {
+    return this.file.projects[this.project]?.length ?? 0;
+  }
+
+  /** Test/telemetry seam — the exact on-disk shape a flush would write. */
+  snapshot(): SkillStateFile {
+    return this.file;
+  }
+
+  /** Workstream E: the sandbox skill_search surface. Score > 0 hits only, best first. */
+  search(query: string, k = 8): readonly SkillSearchHit[] {
+    const notes = this.file.projects[this.project] ?? [];
+    if (notes.length === 0 || query.trim() === "") return [];
+    const ranked = bm25Rank(
+      query,
+      notes.map((note) => ({ item: note, text: noteCorpus(note) })),
+      Math.max(1, Math.min(32, k)),
+    );
+    return ranked.map(({ item, score }) => ({
+      id: item.id,
+      text: item.text,
+      tags: item.tags,
+      score: Math.round(score * 100) / 100,
+    }));
+  }
+
+  /** Ξ body lines shared by blockFor/sliceForPrompt — packed greedily under the char budget. */
+  private pack(
+    query: string,
+    k: number,
+    budgetChars: number,
+    minScore: number,
+  ): readonly string[] {
+    const notes = this.file.projects[this.project] ?? [];
+    if (notes.length === 0) return [];
+    const ranked = bm25Rank(
+      query,
+      notes.map((note) => ({ item: note, text: noteCorpus(note) })),
+      Math.min(k, notes.length),
+    );
+    const lines: string[] = [];
+    let used = 0;
+    for (const { item, score } of ranked) {
+      if (score < minScore) break; // ranked desc — the first miss ends the window
+      const line = `- (${item.tags[0] ?? "symbol"}) ${item.text}`;
+      if (used + line.length + 1 > budgetChars) continue; // too fat — try the next, smaller
+      lines.push(line);
+      used += line.length + 1;
+    }
+    return lines;
+  }
+
+  /**
+   * Workstream C: the full Ξ block for a root prompt (header via skillStateLines — the single
+   * wording source). "" when nothing is relevant or the store is empty.
+   */
+  blockFor(query: string, budgetTokens: number): string {
+    const lines = this.pack(query, 24, Math.max(0, budgetTokens) * 4, Number.MIN_VALUE);
+    if (lines.length === 0) return "";
+    return skillStateLines(lines.length, lines.join("\n"));
+  }
+
+  /**
+   * Workstream D: grounded leaf lines. "" unless the top BM25 score clears `minScore`
+   * (below-threshold prompts stay byte-identical — grounding must never add noise).
+   */
+  sliceForPrompt(query: string, budgetTokens: number, minScore: number): string {
+    const lines = this.pack(query, 8, Math.max(0, budgetTokens) * 4, minScore);
+    return lines.join("\n");
+  }
+
+  /**
+   * Dedup write: duplicate (by normalized text) bumps `hits` and refreshes `ts`; new notes
+   * insert. Per-project cap with LRU-by-ts eviction, top-hits quartile pinned.
+   */
+  merge(inputs: readonly SkillNoteInput[]): void {
+    if (inputs.length === 0) return;
+    const existing = this.file.projects[this.project] ?? [];
+    const byId = new Map<string, SkillNote>(existing.map((note) => [note.id, note]));
+    const now = Date.now();
+    for (const input of inputs) {
+      const text = input.text.trim();
+      if (text === "") continue;
+      const id = noteId(this.project, text);
+      const prev = byId.get(id);
+      if (prev !== undefined) {
+        // Reinforcement, not duplication. The one merge (state-merge.ts) composes the update;
+        // the result is re-narrowed — a malformed merge outcome keeps the previous note.
+        const mergedKeywords = [...prev.keywords];
+        for (const keyword of input.keywords ?? []) {
+          if (!mergedKeywords.includes(keyword) && mergedKeywords.length < KEYWORDS_MAX) {
+            mergedKeywords.push(keyword);
+          }
+        }
+        const merged = deepMergeWithNullDeletion(prev, {
+          hits: prev.hits + 1,
+          ts: now,
+          keywords: mergedKeywords,
+        });
+        byId.set(id, isSkillNote(merged) ? merged : prev);
+      } else {
+        const note: SkillNote = {
+          id,
+          text: text.slice(0, NOTE_MAX_CHARS),
+          keywords: (input.keywords ?? []).slice(0, KEYWORDS_MAX),
+          tags: normalizeTags(input.tags),
+          context: (input.context ?? "").slice(0, CONTEXT_MAX_CHARS),
+          hits: 1,
+          ts: now,
+        };
+        byId.set(id, note);
+      }
+    }
+    let notes = [...byId.values()];
+    if (notes.length > this.notesPerProject) {
+      // Pinned: top quartile by hits (ceil) — frequently-reinforced facts survive eviction.
+      const byHits = [...notes].sort((a, b) => b.hits - a.hits || b.ts - a.ts);
+      const pinned = new Set(
+        byHits.slice(0, Math.max(1, Math.ceil(byHits.length / 4))).map((note) => note.id),
+      );
+      const evictable = notes
+        .filter((note) => !pinned.has(note.id))
+        .sort((a, b) => a.ts - b.ts);
+      const evict = new Set(evictable.slice(0, notes.length - this.notesPerProject).map((note) => note.id));
+      notes = notes.filter((note) => !evict.has(note.id));
+    }
+    this.file = { version: 1, projects: { ...this.file.projects, [this.project]: notes } };
+    this.dirty = true;
+  }
+
+  /** Flush to disk (fail-soft). Other projects' sections ride along from the hydrated file. */
+  async flush(): Promise<boolean> {
+    if (!this.dirty) return true;
+    const written = await saveSkillState(this.file, this.dir);
+    if (written) this.dirty = false;
+    return written;
+  }
+}
+
+// ── Wiring helpers (one implementation each — both composition roots reuse these) ────────
+
+/**
+ * Workstream D leaf grounding — THE implementation complete1 delegates to via
+ * `SubcallHandlerDeps.groundLeaf`. Below-threshold ⇒ byte-identical prompt.
+ */
+export function groundLeafPrompt(
+  store: SkillStore,
+  config: Pick<RlmConfig, "skillStateLeafTokens" | "skillStateMinScore">,
+  prompt: string,
+): string {
+  const slice = store.sliceForPrompt(prompt, config.skillStateLeafTokens, config.skillStateMinScore);
+  return slice === "" ? prompt : `[Project facts]\n${slice}\n\n${prompt}`;
+}
+
+/**
+ * Workstream E host handler — the ONE skill_search implementation, served to both sandboxes
+ * (engine + repl tool). Unwired/disabled stores reply with an error string, never a throw.
+ */
+export function skillSearchHandler(
+  getStore: () => SkillStore | undefined,
+): (query: string, k: number, depth: number) => Promise<string> {
+  return async (query, k) => {
+    const store = getStore();
+    if (store === undefined) return formatError("skill state store not configured");
+    try {
+      return JSON.stringify(store.search(query, k));
+    } catch (err: unknown) {
+      return formatError(err instanceof Error ? err.message : String(err));
+    }
+  };
+}
+
+/** The config slice groundLeafPrompt needs — callers pass their live RlmConfig. */
+export type GroundLeafConfig = Pick<RlmConfig, "skillStateLeafTokens" | "skillStateMinScore">;

package/src/context/md-cache.ts

@@ -19,7 +19,7 @@ import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { homedir } from "node:os";
 
-export interface FileStamp {
+interface FileStamp {
   readonly size: number;
   readonly mtimeMs: number;
 }

package/src/context/merge.ts

@@ -14,7 +14,7 @@ import {
 } from "./namespace.ts";
 import type { ContextFile } from "./types.ts";
 
-export interface FilteredContext {
+interface FilteredContext {
   readonly files: readonly ContextFile[];
   /** Prefixes that selected zero files — the caller decides whether that is fatal. */
   readonly unmatched: readonly string[];

package/src/context/namespace.ts

@@ -10,7 +10,7 @@ import { basename, isAbsolute, resolve } from "node:path";
 import { estimateTokens } from "../text/tokens.ts";
 import { LEGACY_UNKNOWN_PREFIX, type ContextFile } from "./types.ts";
 
-export interface ContextNamespace {
+interface ContextNamespace {
   readonly sourceId: string;
   readonly pathPrefix: string;
 }
@@ -105,7 +105,7 @@ export function namespaceContextFilesWithChars(
   for (const item of payload) {
     if (item === null || typeof item !== "object") continue;
     const rec = item as Record<string, unknown>;
-    const content = typeof rec.content === "string" ? rec.content : String(rec.content ?? "");
+    const content = typeof rec.content === "string" ? rec.content : "";
     let path = typeof rec.path === "string" ? rec.path : "unknown";
     path = applyPathPrefix(path, prefix);
     const tokens = typeof rec.tokens === "number" && Number.isFinite(rec.tokens)

package/src/context/refresh.ts

@@ -69,7 +69,7 @@ export function upsertContextFile(
       item !== null &&
       typeof item === "object" &&
       "path" in item &&
-      typeof (item as { path: unknown }).path === "string" &&
+      typeof (item).path === "string" &&
       pathMatches((item as { path: string }).path, path, cwd)
     ) {
       next[n++] = entry;