@animalabs/context-manager 0.5.2 → 0.5.4

package/src/adaptive/kv-replay.ts

@@ -0,0 +1,238 @@
+/**
+ * Session replay for measuring REAL KV-cache stability.
+ *
+ * `replaySession` is the BASELINE: the production-default `FlatProfileStrategy`
+ * (level-equalizing) run through the real `Picker`, replayed over a growing
+ * session. Compare it against `replayControlled` (the KV-stable controller) to
+ * see what minimizing prefix churn actually buys. (Prior to the half-life/λ
+ * solver's removal this line ran `solveStableFrontier`; the λ value model was
+ * retired — see docs/kv-stable-context-control.md.)
+ *
+ * At each step it:
+ *   1. exposes only the chunks/summaries that existed by that point
+ *      (a summary is available once its youngest covered message has happened —
+ *      `SummaryNode.lastSequence <= now`; compression is bottom-up over time);
+ *   2. folds the middle to a FIXED token cap, carrying F_prev forward, with the
+ *      newest `rawTailTokens` pinned raw (the flat zone);
+ *   3. READS a PERSISTENT provider cache (`CacheStore`, Anthropic ≤4
+ *      breakpoints) for the longest live stored prefix still byte-identical to
+ *      this render — entries written ANY prior turn — then WRITES this render's
+ *      breakpoints back. A prefix frozen many turns ago is still a hit today.
+ *
+ * Pure and deterministic.
+ */
+
+import type { ChunkId } from './folding-strategy.js';
+import type { PickerInputs, PickerChunk } from './picker.js';
+import type { SummaryEntry } from '../types/strategy.js';
+import { SummaryTree } from './summary-tree.js';
+import { Picker } from './picker.js';
+import { FlatProfileStrategy } from './strategies/flat-profile.js';
+import { renderLayout, type RenderLayout, type Frontier } from './render-offsets.js';
+import { placeMarkers, CacheStore } from './kv-cache-sim.js';
+
+export interface ReplayOptions {
+  /** Fixed context-window cap each step folds against (tokens). */
+  budgetTokens: number;
+  /** Cache breakpoints to place per step (1…4). Default 4. */
+  markerCount?: number;
+  /** Newest-N tokens kept raw (the protected flat zone). */
+  rawTailTokens?: number;
+  /** Approximate number of replay steps (history is down-sampled to this).
+   *  Default 120. */
+  targetSteps?: number;
+  /** Cache entries older than this many steps are evicted (provider TTL).
+   *  Default Infinity (keep all — the faithful upper bound on reuse). */
+  cacheTtlSteps?: number;
+}
+
+export interface ReplayStep {
+  /** Newest visible source sequence at this step. */
+  now: number;
+  /** Visible chunk count. */
+  numChunks: number;
+  /** Rendered tokens of this step's frontier. */
+  renderedTokens: number;
+  /** Tokens served from the simulated provider cache this step. */
+  cachedTokens: number;
+  /** Tokens recomputed this step (cache miss). */
+  recomputedTokens: number;
+  /** cachedTokens / renderedTokens, in [0, 1]. */
+  hitRate: number;
+  /** Source sequence at/after which the frontier was re-optimized. */
+  boundarySequence: number;
+  /** Solver could not fit under the cap this step. */
+  overBudget: boolean;
+  /** Deepest fold level present in the rendered frontier (0 = all raw). */
+  deepestLevel: number;
+  /** Age (in steps) of the cache entry that served this step's hit — evidence
+   *  the hit came from an older write, not just the previous turn. −1 = miss. */
+  cacheAgeSteps: number;
+}
+
+export interface ReplayResult {
+  steps: ReplayStep[];
+  /** Σ renderedTokens over all steps. */
+  totalRendered: number;
+  /** Σ recomputedTokens over all steps (the cache-miss bill). */
+  totalRecomputed: number;
+  /** (totalRendered − totalRecomputed) / totalRendered, in [0, 1]. */
+  overallHitRate: number;
+}
+
+/**
+ * Replay a full session (the exported PickerInputs snapshot) as growing
+ * history, measuring per-step provider-cache hit under a fixed budget.
+ */
+export function replaySession(fullInputs: PickerInputs, opts: ReplayOptions): ReplayResult {
+  const markerCount = opts.markerCount ?? 4;
+  const targetSteps = Math.max(1, opts.targetSteps ?? 120);
+
+  // Availability threshold per summary: youngest covered leaf sequence.
+  // Built once over the full tree; a summary is usable at `now` iff <= now.
+  const fullTree = new SummaryTree(fullInputs);
+  const availableAt = new Map<string, number>();
+  for (const s of fullTree.allSummaries()) availableAt.set(s.id, s.lastSequence);
+
+  const allChunks = [...fullInputs.chunks].sort((a, b) => a.sequence - b.sequence);
+  const seqValues = allChunks.map((c) => c.sequence);
+
+  // Down-sample to ~targetSteps growth points (always include the final state).
+  const stride = Math.max(1, Math.ceil(seqValues.length / targetSteps));
+  const stepSeqs: number[] = [];
+  for (let i = 0; i < seqValues.length; i += stride) stepSeqs.push(seqValues[i]);
+  const last = seqValues[seqValues.length - 1];
+  if (stepSeqs[stepSeqs.length - 1] !== last) stepSeqs.push(last);
+
+  const steps: ReplayStep[] = [];
+  let fprev: Frontier = new Map<ChunkId, number>();
+  const cache = new CacheStore({ ttlSteps: opts.cacheTtlSteps });
+  let totalRendered = 0;
+  let totalRecomputed = 0;
+
+  for (const now of stepSeqs) {
+    const visiblePlain = allChunks.filter((c) => c.sequence <= now);
+    const tailIds = rawTailSet(visiblePlain, opts.rawTailTokens ?? 0);
+    // Pin the flat zone so flat-profile won't fold it AND it renders as
+    // individual raw units — not collapsed into one fixed-key 'tail' unit,
+    // which would falsely match across turns in the cache.
+    const visible = visiblePlain.map((c) => (tailIds.has(c.id) ? { ...c, pinned: true } : c));
+    const summaries = new Map<string, SummaryEntry>();
+    const recallPairTokens = new Map<string, number>();
+    for (const [id, s] of fullInputs.summaries) {
+      const lastSeq = availableAt.get(id);
+      if (lastSeq !== undefined && lastSeq >= 0 && lastSeq <= now) {
+        summaries.set(id, s);
+        const rp = fullInputs.recallPairTokens?.get(id);
+        if (rp !== undefined) recallPairTokens.set(id, rp);
+      }
+    }
+
+    const inputs: PickerInputs = {
+      chunks: visible,
+      summaries,
+      recallPairTokens,
+      headTokens: 0,
+      tailTokens: 0,
+      headChunkIds: new Set(),
+      tailChunkIds: new Set(),
+    };
+    const tree = new SummaryTree(inputs);
+
+    // Baseline policy: the production default, FlatProfileStrategy, via the real
+    // Picker — folds the middle to the budget, leaving the pinned flat zone raw.
+    const result = new Picker(new FlatProfileStrategy()).run(inputs, {
+      totalBudget: opts.budgetTokens,
+      targetBudget: opts.budgetTokens,
+      slack: 0,
+    });
+    const resolutions = result.finalResolutions;
+
+    const layout = renderLayout(inputs, tree, resolutions);
+    // READ the persistent cache: longest live stored prefix that still matches.
+    const hit = cache.read(layout);
+    const recomputedTokens = layout.totalTokens - hit.cachedTokens;
+    // WRITE this render's breakpoints back (hinting at the earliest change vs
+    // F_prev), then advance the turn clock so future reads see this write.
+    const boundarySeq = earliestChangedSequence(fprev, resolutions, visible);
+    const boundaryUnitIndex = unitsBeforeSequence(layout, tree, boundarySeq);
+    cache.write(layout, placeMarkers(layout, markerCount, { boundaryUnitIndex }));
+    cache.tick();
+
+    let deepestLevel = 0;
+    for (const lvl of resolutions.values()) if (lvl > deepestLevel) deepestLevel = lvl;
+
+    steps.push({
+      now,
+      numChunks: visible.length,
+      renderedTokens: layout.totalTokens,
+      cachedTokens: hit.cachedTokens,
+      recomputedTokens,
+      hitRate: layout.totalTokens > 0 ? hit.cachedTokens / layout.totalTokens : 0,
+      boundarySequence: boundarySeq,
+      overBudget: result.finalTokens > opts.budgetTokens,
+      deepestLevel,
+      cacheAgeSteps: hit.ageSteps,
+    });
+    totalRendered += layout.totalTokens;
+    totalRecomputed += recomputedTokens;
+
+    fprev = resolutions;
+  }
+
+  return {
+    steps,
+    totalRendered,
+    totalRecomputed,
+    overallHitRate: totalRendered > 0 ? (totalRendered - totalRecomputed) / totalRendered : 0,
+  };
+}
+
+// ---------------------------------------------------------------------------
+
+/** Earliest source sequence whose resolution changed `prev → next` (the marker
+ *  hint / churn boundary). MAX_SAFE_INTEGER when nothing changed. */
+function earliestChangedSequence(
+  prev: Frontier,
+  next: ReadonlyMap<ChunkId, number>,
+  ordered: PickerChunk[],
+): number {
+  for (const c of ordered) {
+    if ((prev.get(c.id) ?? 0) !== (next.get(c.id) ?? 0)) return c.sequence;
+  }
+  return Number.MAX_SAFE_INTEGER;
+}
+
+/** Chunk ids within the newest `tailTokens` of raw content (kept non-foldable). */
+function rawTailSet(orderedChunks: PickerChunk[], tailTokens: number): Set<ChunkId> {
+  const s = new Set<ChunkId>();
+  if (tailTokens <= 0) return s;
+  let used = 0;
+  for (let i = orderedChunks.length - 1; i >= 0; i--) {
+    s.add(orderedChunks[i].id);
+    used += orderedChunks[i].rawTokens;
+    if (used >= tailTokens) break;
+  }
+  return s;
+}
+
+/** Number of leading rendered units whose start sequence is < `boundary` (the
+ *  frozen-prefix length → a natural cache breakpoint). */
+function unitsBeforeSequence(layout: RenderLayout, tree: SummaryTree, boundary: number): number {
+  let count = 0;
+  for (const u of layout.units) {
+    if (unitStartSeq(u, tree) < boundary) count++;
+    else break;
+  }
+  return count;
+}
+
+function unitStartSeq(
+  u: RenderLayout['units'][number],
+  tree: SummaryTree,
+): number {
+  if (u.kind === 'raw') return tree.leaf(u.key)?.sequence ?? 0;
+  if (u.kind === 'recall') return tree.summary(u.key)?.firstSequence ?? 0;
+  if (u.kind === 'head') return -1;
+  return Number.MAX_SAFE_INTEGER; // tail
+}

package/src/adaptive/render-offsets.ts

@@ -0,0 +1,116 @@
+/**
+ * Rendered-unit / offset accounting for the adaptive compiled context.
+ *
+ * `render.ts` reconstructs content byte-faithfully but exposes no token
+ * positions. The V2 best-fit KV term needs them: KV cost is governed by the
+ * EARLIEST position at which a new frontier diverges from the previous one —
+ * the provider caches the longest byte-identical prefix, so every token after
+ * the first divergence is recomputed (`docs/best-fit-frontier-resolution.md`
+ * §4, §4.1).
+ *
+ * `renderLayout` produces the ordered sequence of rendered units (head,
+ * per-chunk raw/recall in source order, tail) with cumulative token offsets,
+ * matching `MutableFoldingState.computeTokens` exactly:
+ *  - head/tail are fixed blocks;
+ *  - pinned chunks render raw (L0) regardless of resolution;
+ *  - a folded chunk emits its L_k ancestor's recall pair, once per distinct
+ *    ancestor (siblings share one recall pair);
+ *  - a resolution whose ancestor summary is missing falls back to raw.
+ *
+ * Pure and deterministic.
+ */
+
+import type { ChunkId, SummaryId } from './folding-strategy.js';
+import type { PickerInputs } from './picker.js';
+import type { SummaryTree } from './summary-tree.js';
+
+/** Resolution map: chunkId → display level (0 = raw). */
+export type Frontier = ReadonlyMap<ChunkId, number>;
+
+export interface RenderedUnit {
+  kind: 'head' | 'raw' | 'recall' | 'tail';
+  /**
+   * Stable identity for prefix comparison. Two units are byte-identical iff
+   * they share (kind, key): 'head'/'tail' for the fixed blocks, the chunk id
+   * for a raw shard, the summary id for a recall pair.
+   */
+  key: string;
+  tokens: number;
+  /** Cumulative tokens BEFORE this unit (its start offset in the prefix). */
+  offset: number;
+}
+
+export interface RenderLayout {
+  units: RenderedUnit[];
+  totalTokens: number;
+}
+
+/**
+ * Build the ordered rendered-unit layout for a frontier. `totalTokens` equals
+ * `MutableFoldingState.computeTokens` for the same resolutions.
+ */
+export function renderLayout(
+  inputs: PickerInputs,
+  tree: SummaryTree,
+  frontier: Frontier,
+): RenderLayout {
+  const units: RenderedUnit[] = [];
+  let offset = 0;
+  const push = (kind: RenderedUnit['kind'], key: string, tokens: number): void => {
+    units.push({ kind, key, tokens, offset });
+    offset += tokens;
+  };
+
+  if (inputs.headTokens > 0) push('head', 'head', inputs.headTokens);
+
+  const ordered = [...inputs.chunks].sort((a, b) => a.sequence - b.sequence);
+  const renderedSummaries = new Set<SummaryId>();
+  for (const c of ordered) {
+    if (inputs.headChunkIds.has(c.id) || inputs.tailChunkIds.has(c.id)) continue;
+    const effective = c.pinned ? 0 : frontier.get(c.id) ?? 0;
+    if (effective === 0) {
+      push('raw', c.id, c.rawTokens);
+      continue;
+    }
+    const ancestor = tree.ancestorAt(c.id, effective);
+    if (!ancestor) {
+      // Resolution set but summary missing — render raw (renderer makes the
+      // same call). Matches computeTokens' fallback.
+      push('raw', c.id, c.rawTokens);
+      continue;
+    }
+    if (renderedSummaries.has(ancestor.id)) continue; // sibling shares the pair
+    renderedSummaries.add(ancestor.id);
+    push('recall', ancestor.id, ancestor.recallTokens);
+  }
+
+  if (inputs.tailTokens > 0) push('tail', 'tail', inputs.tailTokens);
+
+  return { units, totalTokens: offset };
+}
+
+/**
+ * Earliest index at which two unit sequences differ (by kind+key).
+ * Returns -1 when the sequences are identical; otherwise the first differing
+ * index (which may be `min(len)` when one is a strict prefix of the other).
+ */
+export function earliestDivergenceIndex(a: RenderedUnit[], b: RenderedUnit[]): number {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) {
+    if (a[i].kind !== b[i].kind || a[i].key !== b[i].key) return i;
+  }
+  return a.length === b.length ? -1 : n;
+}
+
+/**
+ * KV cost of moving from `prev` to `next`: the number of tokens in `next` that
+ * must be recomputed — everything from the earliest divergence onward. 0 when
+ * `next`'s units are an exact prefix of (or identical to) `prev`'s, since the
+ * whole of `next` is then a cached prefix.
+ */
+export function kvCost(prev: RenderLayout, next: RenderLayout): number {
+  const d = earliestDivergenceIndex(prev.units, next.units);
+  if (d === -1) return 0; // identical
+  if (d >= next.units.length) return 0; // next is a prefix of prev → fully cached
+  return next.totalTokens - next.units[d].offset;
+}

package/src/adaptive/strategies/kv-stable.ts

@@ -0,0 +1,123 @@
+/**
+ * KvStableStrategy — the KV-stable context controller plugged into the existing
+ * picker (see `docs/kv-stable-context-control.md`).
+ *
+ * Same "solve-once-then-walk" bridge as `BestFitStrategy`: on the first
+ * `selectNextFold` it computes a target frontier with `planControlledFrontier`
+ * (the *same* policy the replay harness measures), memoizes it, then emits one
+ * `raise`/`lower` op per call to walk the live state toward it, returning `null`
+ * once reached. The picker already applies raise/lower — no picker change.
+ *
+ * Unlike `BestFitStrategy` (which maximizes value − λ·KVcost over a half-life
+ * recency model), this minimizes real prefix churn directly: it holds the flat
+ * zone (head/tail/pinned) raw, never folds locked chunks, and sheds the foldable
+ * middle oldest-first/leveled under a per-turn divergence **reach cap** (the
+ * perturbation cap P), bounded by per-chunk log-age saliency caps, yielding the
+ * reach cap only as far as needed to stay under the hard wall (`totalBudget`).
+ * No λ, no recency half-life.
+ *
+ * Like `BestFitStrategy`, it does not emit `produce` ops — deeper folding than
+ * has been produced is the speculative pre-producer's job; the controller only
+ * targets levels whose summaries already exist. Deterministic.
+ */
+
+import type {
+  FoldingStrategy,
+  FoldingState,
+  FoldingBudget,
+  FoldOp,
+  ChunkId,
+} from '../folding-strategy.js';
+import type { PickerInputs } from '../picker.js';
+import { SummaryTree } from '../summary-tree.js';
+import { planControlledFrontier } from '../kv-control.js';
+
+export interface KvStableOptions {
+  /** Per-turn divergence reach — the structural perturbation cap P, in tokens.
+   *  Smaller = gentler per-turn KV churn (shallow divergence) but less efficient
+   *  compression. Exceeded only to stay under the hard wall. Default: the hard
+   *  budget (effectively unbounded within the window). */
+  reachTokens?: number;
+  /** Base-k summary grouping (matches the strategy's mergeThreshold). Default 6. */
+  mergeThreshold?: number;
+}
+
+export class KvStableStrategy implements FoldingStrategy {
+  readonly name = 'kv-stable';
+
+  private readonly inputs: PickerInputs;
+  private readonly opts: KvStableOptions;
+  private readonly fPrev: Map<ChunkId, number>;
+  private target: Map<ChunkId, number> | null = null;
+
+  constructor(inputs: PickerInputs, opts: KvStableOptions = {}) {
+    this.inputs = inputs;
+    this.opts = opts;
+    this.fPrev = new Map(inputs.chunks.map((c) => [c.id, c.currentResolution]));
+  }
+
+  selectNextFold(state: FoldingState, budget: FoldingBudget): FoldOp | null {
+    if (!this.target) this.target = this.solve(budget);
+    return this.nextOp(state);
+  }
+
+  /** Target frontier this run is walking toward (null before the first call). */
+  targetFrontier(): ReadonlyMap<ChunkId, number> | null {
+    return this.target;
+  }
+
+  private solve(budget: FoldingBudget): Map<ChunkId, number> {
+    const tree = new SummaryTree(this.inputs);
+
+    // Flat zone (forced raw, never folded): head, tail, pinned. Frozen (kept at
+    // their carried resolution, never folded): locked.
+    const rawZone = new Set<ChunkId>();
+    const frozen = new Set<ChunkId>();
+    let now = 0;
+    for (const c of this.inputs.chunks) {
+      if (c.sequence > now) now = c.sequence;
+      if (this.inputs.headChunkIds.has(c.id) || this.inputs.tailChunkIds.has(c.id) || c.pinned) {
+        rawZone.add(c.id);
+      } else if (c.lockedByAgent) {
+        frozen.add(c.id);
+      }
+    }
+
+    return planControlledFrontier(this.inputs, tree, {
+      previous: this.fPrev,
+      // Bidirectional within the slack band: fold when over the hard budget,
+      // un-fold to use headroom when under the soft target. Both reach-bounded;
+      // [targetBudget, totalBudget] is the quiet dead band.
+      foldAtTokens: budget.totalBudget,
+      expandAtTokens: budget.targetBudget,
+      targetTokens: budget.targetBudget,
+      windowTokens: budget.totalBudget,
+      reachTokens: this.opts.reachTokens,
+      rawZone,
+      frozen,
+      now,
+      mergeThreshold: this.opts.mergeThreshold,
+    }).resolutions;
+  }
+
+  /** Emit one op moving the live state toward the target frontier. */
+  private nextOp(state: FoldingState): FoldOp | null {
+    const target = this.target!;
+    for (const c of state.chunks()) {
+      if (c.inHead || c.inTail || c.pinned || c.lockedByAgent) continue;
+      const cur = c.currentResolution;
+      const tgt = target.get(c.id) ?? 0;
+      if (cur === tgt) continue;
+
+      if (cur < tgt) {
+        const summary = c.ancestorAt(tgt);
+        if (!summary) continue; // unrealizable target (summary not produced) — skip
+        return { kind: 'raise', groupRoot: summary.id };
+      }
+      const summary = c.ancestorAt(cur);
+      if (!summary) continue;
+      return { kind: 'lower', groupRoot: summary.id };
+    }
+    return null;
+  }
+}