@hicaru/pi-rlm 0.3.20 → 0.3.21

package/src/core/run-state.ts

@@ -109,9 +109,32 @@ const RUN_STATE_FIELDS: ReadonlySet<string> = new Set([
 const ARRAY_FIELDS: ReadonlySet<string> = new Set(["findings", "verifiedFacts", "openQuestions"]);
 const TASK_MAX_CHARS = 200;
 const NEXT_STEP_MAX_CHARS = 300;
+// Recall W2 contract alignment: STATE_FENCE_INSTRUCTION promises "≤ 5 keys per patch, every
+// string value ≤ 120 chars" — the validator now MEANS it. Oversized values are CLAMPED
+// fail-soft (the prose carries the story; Σ carries pointers), while the key count is
+// rejected with an explicit error (a restatement-shaped patch must come back as feedback —
+// §5.7: consistent validator feedback is the small-model bottleneck).
+const STATE_PATCH_MAX_KEYS = 5;
+const STATE_VALUE_MAX_CHARS = 120;
 // `findings` | `findings[+]` | `findings[2]` | `testedApproaches.h1`
 const PATCH_KEY = /^([a-zA-Z_][a-zA-Z0-9_]*)((?:\.[a-zA-Z_][a-zA-Z0-9_]*)*)(\[\+\]|\[\d+\])?$/;
 
+/** Fail-soft contract clamp — every string Σ value honors the promised ≤120 chars. */
+function clampStateValue(value: string): string {
+  return value.length > STATE_VALUE_MAX_CHARS ? value.slice(0, STATE_VALUE_MAX_CHARS) : value;
+}
+
+/** Clamp the string fields of a validated outcome record IN PLACE (string→clamped, everything
+ *  else — explicit `null` deletes included — passes through untouched; the strict-merge null
+ *  semantics live in strictMergeRecord and must never be eaten by the clamp). */
+function clampOutcomeRecord(value: Readonly<Record<string, unknown>>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, field] of Object.entries(value)) {
+    out[key] = typeof field === "string" ? clampStateValue(field) : field;
+  }
+  return out;
+}
+
 export function freshRunState(task: string): RunState {
   return {
     task,
@@ -256,20 +279,23 @@ export function enforceCaps(draft: MutableState): Result<RunState, PatchError> {
     artifacts: { ...draft.artifacts },
   };
   // bytesTotal: |Σ_t| must never exceed κ_Σ — deterministic eviction order keeps runs flat.
+  // Order (recall W2): diary entries (findings) go first, SPECULATIVE entries (openQuestions)
+  // next, FOUNDATION (verifiedFacts: paths/symbols/configs) survives longest — losing a
+  // foundational fact is the irreversible-recall failure the paper warns about (§7 case 2).
   let guard = 0;
   while (JSON.stringify(capped).length > RUN_STATE_LIMITS.bytesTotal && guard++ < 10_000) {
     if (capped.findings.length > 0) {
       capped.findings = capped.findings.slice(1);
       continue;
     }
-    if (capped.verifiedFacts.length > 0) {
-      capped.verifiedFacts = capped.verifiedFacts.slice(1);
-      continue;
-    }
     if (capped.openQuestions.length > 0) {
       capped.openQuestions = capped.openQuestions.slice(1);
       continue;
     }
+    if (capped.verifiedFacts.length > 0) {
+      capped.verifiedFacts = capped.verifiedFacts.slice(1);
+      continue;
+    }
     const approach = firstKey(capped.testedApproaches);
     if (approach !== undefined) {
       const rest = { ...capped.testedApproaches };
@@ -331,7 +357,7 @@ function applyKey(draft: MutableState, rawKey: string, value: unknown): Result<n
     }
     if (op === "[+]") {
       if (typeof value !== "string") return err({ kind: "type", path: rawKey, expected: "string" });
-      list.push(value);
+      list.push(clampStateValue(value));
     } else if (op !== undefined) {
       const index = Number.parseInt(op.slice(1, -1), 10);
       if (value === null) {
@@ -346,11 +372,11 @@ function applyKey(draft: MutableState, rawKey: string, value: unknown): Result<n
       if (index > list.length) {
         return err({ kind: "schema", detail: `${rawKey} would leave a hole (len=${list.length})` });
       }
-      list[index] = value;
+      list[index] = clampStateValue(value);
     } else {
       if (!isStringArray(value)) return err({ kind: "type", path: rawKey, expected: "string[]" });
       list.length = 0;
-      list.push(...dedupStrings(value));
+      list.push(...dedupStrings(value.map(clampStateValue)));
     }
     return ok(null);
   }
@@ -409,15 +435,17 @@ function applyKey(draft: MutableState, rawKey: string, value: unknown): Result<n
     if (!isPlainObject(value) || !isApproachOutcome(value)) {
       return err({ kind: "type", path: rawKey, expected: "ApproachOutcome" });
     }
+    // Contract clamp: outcome strings honor the promised ≤120 chars (nulls stay nulls).
+    const outcome = clampOutcomeRecord(value);
     const prev: unknown = cursor[leaf];
     const merged = isPlainObject(prev)
-      ? strictMergeRecord(prev, value, rawKey)
-      : ok<Record<string, unknown>, PatchError>({ ...value });
+      ? strictMergeRecord(prev, outcome, rawKey)
+      : ok<Record<string, unknown>, PatchError>(outcome);
     if (!merged.ok) return merged;
     refreshOrder(cursor, leaf, merged.value); // last-mention ordering for eviction
   } else {
     if (typeof value !== "string") return err({ kind: "type", path: rawKey, expected: "string" });
-    refreshOrder(cursor, leaf, value);
+    refreshOrder(cursor, leaf, clampStateValue(value));
   }
   commitRecord(draft, root, record);
   return ok(null);
@@ -454,6 +482,14 @@ export function applyPatch(prev: RunState, patch: unknown, t: number): Result<Ru
   }
   const ops = Object.entries(patch.state_patch);
   if (ops.length === 0) return err({ kind: "schema", detail: "empty state_patch" });
+  // Contract alignment (recall W2): the instruction promises ≤ 5 keys — a bigger patch is a
+  // restatement, and restatements must come back as feedback, not silently inflate Σ.
+  if (ops.length > STATE_PATCH_MAX_KEYS) {
+    return err({
+      kind: "schema",
+      detail: `${ops.length} keys — ≤ ${STATE_PATCH_MAX_KEYS} per patch; commit deltas only`,
+    });
+  }
   // Per-turn byte cap (bench rec #1): reject BEFORE the draft clone — a verbose restatement
   // must come back as an error observation, never silently eat output tokens.
   if (JSON.stringify(patch).length > RUN_STATE_LIMITS.patchBytes) {
@@ -469,6 +505,21 @@ export function applyPatch(prev: RunState, patch: unknown, t: number): Result<Ru
   return enforceCaps(draft);
 }
 
+/** The actual limits, spelled out at rejection time — a small model told only "cap exceeded"
+ *  thrashes blind retries into the degrade threshold. Field name → human limit (one source:
+ *  RUN_STATE_LIMITS + the scalar caps). */
+const CAP_LIMITS: Readonly<Record<string, string>> = Object.freeze({
+  task: `≤ ${TASK_MAX_CHARS} chars`,
+  nextStep: `≤ ${NEXT_STEP_MAX_CHARS} chars`,
+  findings: `≤ ${RUN_STATE_LIMITS.findings} entries`,
+  verifiedFacts: `≤ ${RUN_STATE_LIMITS.verifiedFacts} entries`,
+  testedApproaches: `≤ ${RUN_STATE_LIMITS.testedApproaches} entries`,
+  openQuestions: `≤ ${RUN_STATE_LIMITS.openQuestions} entries`,
+  artifacts: `≤ ${RUN_STATE_LIMITS.artifacts} entries`,
+  patchBytes: `≤ ${RUN_STATE_LIMITS.patchBytes} bytes per patch`,
+  bytesTotal: `≤ ${RUN_STATE_LIMITS.bytesTotal} bytes total`,
+});
+
 /** Human-facing patch rejection — becomes the next O_t prefix (error-as-observation). */
 export function patchErrorText(error: PatchError): string {
   switch (error.kind) {
@@ -478,8 +529,10 @@ export function patchErrorText(error: PatchError): string {
       return `type mismatch at "${error.path}" (expected ${error.expected})`;
     case "implicit-drop":
       return `implicit key drop at "${error.path}" — restate the key or delete it with null`;
-    case "cap":
-      return `cap exceeded on "${error.field}"`;
+    case "cap": {
+      const limit = CAP_LIMITS[error.field];
+      return `cap exceeded on "${error.field}"${limit === undefined ? "" : ` — the limit is ${limit}`}`;
+    }
   }
 }
 
@@ -491,6 +544,9 @@ export function patchErrorText(error: PatchError): string {
  * Idle degrade (bench rec #2): when `fenceRequested` is true (the turn conditioned on Σ)
  * and zero patches were accepted, the turn is IDLE — Σ inflated the prompt for nothing.
  * `RUN_STATE_IDLE_DEGRADE_TURNS` consecutive idle turns degrade, same as-built outcome.
+ * `productive` (root parity, recall W2): a turn that executed real repl work without
+ * raising RESETS the idle streak — heavy execution is progress even without a delta, and
+ * a mid-run amputation of Σ costs more than the prompt it saves.
  */
 export function applyStatePatches(
   mode: Extract<RunStateMode, { kind: "active" }>,
@@ -498,10 +554,11 @@ export function applyStatePatches(
   iteration: number,
   config: Pick<RlmConfig, "runStateRetryMax">,
   fenceRequested = false,
+  productive = false,
 ): { readonly mode: RunStateMode; readonly observation: string | undefined } {
   // Identity fast-path: a fence-free turn on a run that never asked for fences changes
   // nothing — keep the same mode object (callers may compare identity).
-  if (parsed.length === 0 && !fenceRequested) return { mode, observation: undefined };
+  if (parsed.length === 0 && !fenceRequested && !productive) return { mode, observation: undefined };
   let state = mode.state;
   let retries = mode.retries;
   let accepted = 0;
@@ -522,7 +579,8 @@ export function applyStatePatches(
     }
   }
   // Bench rec #2: accepted deltas reset the idle streak; a requested-but-empty turn grows it.
-  const idle = accepted > 0 || !fenceRequested ? 0 : mode.idle + 1;
+  // Productive-turn parity (root tracker): executed work resets the streak too.
+  const idle = accepted > 0 || !fenceRequested || productive ? 0 : mode.idle + 1;
   let nextMode: RunStateMode = { kind: "active", state, retries, idle };
   if (retries > config.runStateRetryMax) {
     nextMode = {
@@ -557,6 +615,9 @@ export const STATE_FENCE_INSTRUCTION: string =
   "Σ is an index of pointers, not a report: ≤ 5 keys per patch, every string value ≤ 120 chars, " +
   "telegraphic style (`path — fact`, `verdict — numbers`). NEVER paste findings, tables, JSON " +
   "blobs, or long excerpts into Σ — the prose carries the story, Σ carries only the pointers.\n" +
+  `Caps: findings ≤ ${RUN_STATE_LIMITS.findings}, verifiedFacts ≤ ${RUN_STATE_LIMITS.verifiedFacts}, ` +
+  `testedApproaches ≤ ${RUN_STATE_LIMITS.testedApproaches}, openQuestions/artifacts ≤ ${RUN_STATE_LIMITS.openQuestions}/${RUN_STATE_LIMITS.artifacts} — ` +
+  "oldest entries are evicted automatically, so push new facts and let Σ prune itself.\n" +
   "Keys: dotted paths write record leaves; [+] appends; [N] sets an array slot; null deletes.\n" +
   "Commit DELTAS only — never restate unchanged records or arrays; touch single dotted keys " +
   `or append with [+]. Whole-record restatements must keep EVERY key (implicit drops are ` +
@@ -578,6 +639,17 @@ export function runStateTurnBlock(state: RunState): string {
   return sigmaBlock(state, true);
 }
 
+/**
+ * Σ economics: re-sending a byte-identical Σ every turn is up to ~3K tokens of attention tax
+ * that carries zero new information — the model saw it one turn ago. The marker keeps the
+ * patch grammar within reach (a small model without it stops committing at all) while cutting
+ * the block ~10x. Callers must re-send the FULL block after compaction/rebase or degrade.
+ */
+export const SIGMA_UNCHANGED_LINE =
+  "[Σ] unchanged since last turn — deltas apply against it. Grammar: dotted keys, [+] append, " +
+  "[N] set slot, null delete; ≤ 5 keys per patch, every value ≤ 120 chars. Fence only NEW " +
+  "durable facts; an absent fence is free.";
+
 /**
  * Root Σ (WS-3b): the ROOT's A_t block. R2 (G2): with `withContract` the splice carries the
  * SAME fence contract (delegating to the one composer above — no re-wording), making the

package/src/core/session-archive.ts

@@ -0,0 +1,174 @@
+/**
+ * Session archive (recall W1) — the model-reachable copy of elided root history.
+ *
+ * The root context transform (core/root-context.ts) stubs every turn older than the keep
+ * window; before this module those bytes were unrecoverable — the session log is host-side
+ * only and the repl sandbox never saw native read/bash payloads. The archive closes the
+ * loop: every message the elision destroys is recorded here, rendered into markdown
+ * segments, and materialized into the sandbox under `ctx/session-log/` through the SAME
+ * upsert seam native edit/write uses (context/refresh.ts) — so the existing free
+ * search() / grep_context() BM25 recall them (RLM paper §2: context stays an environment;
+ * LLM-memory survey §5: query, not storage, is the recall bottleneck).
+ *
+ * The elision re-runs on EVERY provider call over a fresh clone, so records dedup by
+ * content hash (the transcript is append-only; the same stale turn re-elides each call).
+ * Segment materialization is idempotent per segment path and fail-soft end to end.
+ */
+
+import { truncateOutput } from "../text/parsing.ts";
+
+/** Sandbox namespace the segments materialize under — one wording source for the stubs
+ *  that teach recall (prompts/glossary.ts) and for the materialized paths. */
+export const ARCHIVE_NAMESPACE = "ctx/session-log/";
+
+/** Per-record cap: a 2MB tool payload is archived mid-truncated (head+tail) — recall needs
+ *  the shape and the needles, not every byte (paper A.4 compact-serialization doctrine). */
+const ARCHIVE_RECORD_MAX_CHARS = 100_000;
+/** Host-memory ring cap (chars). Already-materialized segments live in the worker; this
+ *  caps only the host copy. Configurable as `rootArchiveMaxChars` (0 = archive off). */
+export const ARCHIVE_DEFAULT_MAX_CHARS = 2_000_000;
+/** Dedup-set cap: FIFO eviction of the oldest hashes; a re-elided evicted message is
+ *  re-recorded harmlessly (a duplicate segment entry, not a correctness issue). */
+const HASH_SET_MAX = 8_192;
+
+const ARCHIVE_TRUNCATE_MARK = "chars archived out — the middle never enters the archive";
+
+export interface ArchivedEntry {
+  readonly role: "assistant" | "toolResult";
+  readonly toolName: string | undefined;
+  readonly text: string;
+}
+
+/** FNV-1a 32-bit over role+name+text — the dedup key (same double-hash idiom as skillstate). */
+function entryHash(entry: ArchivedEntry): string {
+  const basis = `${entry.role}\u0000${entry.toolName ?? ""}\u0000${entry.text}`;
+  let h1 = 0x811c9dc5;
+  let h2 = 0x811c9dc5;
+  for (let i = 0; i < basis.length; i++) {
+    const c = basis.charCodeAt(i);
+    h1 = (h1 ^ c) * 0x01000193;
+    h2 = (h2 ^ (c + i)) * 0x01000193;
+    h1 >>>= 0;
+    h2 >>>= 0;
+  }
+  return `${h1.toString(36)}${h2.toString(36)}`;
+}
+
+interface RingEntry {
+  readonly seq: number;
+  readonly hash: string;
+  readonly entry: ArchivedEntry;
+}
+
+export interface ArchiveSegment {
+  /** Unique context path for this segment (`ctx/session-log/turn-<a>-<b>.md`). */
+  readonly path: string;
+  readonly text: string;
+}
+
+export class SessionArchive {
+  private ring: RingEntry[] = [];
+  private readonly seen = new Map<string, true>();
+  private totalChars = 0;
+  private nextSeq = 1;
+  private materializedThrough = 0;
+  private lostWhilePending = 0;
+  private pendingChars = 0;
+  private pendingCount = 0;
+
+  constructor(private readonly maxChars: number) {}
+
+  /**
+   * Record one elided message. Returns the assigned seq, or undefined for
+   * empty/duplicate records. Per-record truncation applies BEFORE the ring cap.
+   */
+  record(entry: ArchivedEntry): number | undefined {
+    const text = entry.text.trim();
+    if (text === "") return undefined;
+    const capped: ArchivedEntry = {
+      ...entry,
+      text: text.length > ARCHIVE_RECORD_MAX_CHARS
+        ? truncateOutput(text, ARCHIVE_RECORD_MAX_CHARS, ARCHIVE_TRUNCATE_MARK)
+        : text,
+    };
+    const hash = entryHash(capped);
+    if (this.seen.has(hash)) return undefined;
+    this.seen.set(hash, true);
+    if (this.seen.size > HASH_SET_MAX) {
+      // FIFO: Map preserves insertion order; drop the oldest hash only.
+      const oldest = this.seen.keys().next();
+      if (oldest.done !== true) this.seen.delete(oldest.value);
+    }
+    const seq = this.nextSeq++;
+    this.ring.push({ seq, hash, entry: capped });
+    this.totalChars += capped.text.length;
+    if (seq > this.materializedThrough) {
+      this.pendingChars += capped.text.length;
+      this.pendingCount += 1;
+    }
+    this.evictOverCap();
+    return seq;
+  }
+
+  /** True when unmaterialized records exist (flush when the sandbox is next alive). */
+  get hasPending(): boolean {
+    return this.pendingCount > 0;
+  }
+
+  get pendingCharsValue(): number {
+    return this.pendingChars;
+  }
+
+  /** Telemetry: entries + chars currently held (host copy). */
+  get stats(): { readonly entries: number; readonly chars: number; readonly recorded: number } {
+    return { entries: this.ring.length, chars: this.totalChars, recorded: this.nextSeq - 1 };
+  }
+
+  /**
+   * Render every unmaterialized record into ONE segment and mark it materialized.
+   * Returns undefined when nothing is pending. The path embeds the covered seq range so
+   * segments never collide and the `ctx/session-log/*` glob covers them all.
+   */
+  renderPending(): ArchiveSegment | undefined {
+    const pending = this.ring.filter((r) => r.seq > this.materializedThrough);
+    if (pending.length === 0) return undefined;
+    const parts: string[] = [];
+    if (this.lostWhilePending > 0) {
+      parts.push(
+        `(archive cap dropped ${this.lostWhilePending} older elided turn(s) before materialization)`,
+      );
+      this.lostWhilePending = 0;
+    }
+    for (const r of pending) {
+      const label = r.entry.role === "toolResult" && r.entry.toolName !== undefined
+        ? `${r.entry.role} (${r.entry.toolName})`
+        : r.entry.role;
+      parts.push(`### turn ${r.seq} — ${label}\n${r.entry.text}`);
+    }
+    const first = pending[0]?.seq ?? 0;
+    const last = pending[pending.length - 1]?.seq ?? first;
+    this.materializedThrough = last;
+    this.pendingChars = 0;
+    this.pendingCount = 0;
+    return {
+      path: `${ARCHIVE_NAMESPACE}turn-${first}-${last}.md`,
+      text: parts.join("\n\n"),
+    };
+  }
+
+  /** Ring eviction: drop OLDEST entries until under cap. Evicting an unmaterialized
+   *  record loses it from recall — counted so the next segment says so honestly. */
+  private evictOverCap(): void {
+    while (this.totalChars > this.maxChars && this.ring.length > 1) {
+      const oldest = this.ring[0];
+      if (oldest === undefined) return;
+      this.ring = this.ring.slice(1);
+      this.totalChars -= oldest.entry.text.length;
+      if (oldest.seq > this.materializedThrough) {
+        this.pendingChars -= oldest.entry.text.length;
+        this.pendingCount -= 1;
+        this.lostWhilePending += 1;
+      }
+    }
+  }
+}

package/src/core/types.ts

@@ -121,6 +121,9 @@ export interface RlmConfig {
   readonly skillStateLeafTokens: number;
   /** BM25 score a note must clear before a leaf prompt gets grounded (below ⇒ byte-identical). */
   readonly skillStateMinScore: number;
+  /** BM25 score a note must clear before it enters the Ξ root block (below ⇒ not injected).
+   *  Was effectively 0 (`Number.MIN_VALUE`) — stale cross-session notes rode every prompt. */
+  readonly skillStateXiMinScore: number;
   /** Per-project note cap; LRU by ts with the top-hits quartile pinned (Workstream B). */
   readonly skillStateNotesPerProject: number;
 
@@ -141,6 +144,9 @@ export interface RlmConfig {
   readonly rootContextKeepTurns: number;
   /** Tool-result payloads older than the keep window are preview-capped at this many chars. */
   readonly rootContextElideChars: number;
+  /** Recall W1: host-memory ring cap (chars) for the session archive that makes elision
+   *  dereferenceable (`ctx/session-log/*` in the sandbox). 0 = archive off (plain stubs). */
+  readonly rootArchiveMaxChars: number;
   /** Splice the RootStateTracker Σ snapshot before the last user message each call. */
   readonly rootContextSnapshot: boolean;
   /** WS-4.2 (default OFF, paper §5.7 fence tax): the root may commit ΔΣ_t via a ```state