@animalabs/context-manager 0.4.0 → 0.5.0

package/src/adaptive/picker.ts

@@ -0,0 +1,442 @@
+/**
+ * Picker orchestrator for the adaptive-resolution design.
+ *
+ * The picker is a thin loop: build a FoldingState, call strategy.selectNextFold
+ * until it returns null, applying 'raise'/'lower' ops as they come and recording
+ * 'produce' ops for the caller to enqueue.
+ *
+ * The picker is stateless across runs — all persistent state lives on the
+ * per-chunk fields. Each run builds a fresh FoldingState from the inputs.
+ *
+ * See `docs/adaptive-resolution-design.md` §5.
+ */
+
+import type {
+  FoldingStrategy,
+  FoldingState,
+  FoldingBudget,
+  FoldOp,
+  ChunkView,
+  ChunkId,
+  SummaryId,
+  ChunkRange,
+} from './folding-strategy.js';
+import type { SummaryEntry } from '../types/strategy.js';
+import { getSummaryParentId } from '../types/strategy.js';
+
+/**
+ * Error raised by the strategy when the picker has folded everything it can
+ * and the resulting context still exceeds the hard token budget.
+ *
+ * The strategy throws this rather than silently dropping entries. The host
+ * application decides how to respond — typical responses: raise the budget,
+ * switch to a larger-context model, drop the head/tail windows explicitly,
+ * or surface a "context too large" error to the user.
+ *
+ * See `docs/adaptive-resolution-design.md` §3.10.
+ */
+export class OverBudgetError extends Error {
+  /** The hard budget the strategy was trying to fit under. */
+  readonly budget: number;
+  /** The token count the strategy could not reduce below `budget`. */
+  readonly actual: number;
+  /** Diagnostic snapshot of the picker's final state. */
+  readonly diagnostics: {
+    headTokens: number;
+    tailTokens: number;
+    middleTokens: number;
+    middleChunkCount: number;
+    deepestLevel: number;
+  };
+
+  constructor(opts: {
+    budget: number;
+    actual: number;
+    diagnostics: OverBudgetError['diagnostics'];
+  }) {
+    super(
+      `Adaptive picker exhausted but ${opts.actual} tokens still exceed hard budget ${opts.budget}` +
+        ` (head=${opts.diagnostics.headTokens}, tail=${opts.diagnostics.tailTokens},` +
+        ` middle=${opts.diagnostics.middleTokens} across ${opts.diagnostics.middleChunkCount} chunks,` +
+        ` deepest fold level=L${opts.diagnostics.deepestLevel})`
+    );
+    // Writable per Error convention so instanceof-by-name works across
+    // iframe / vm boundaries; the field stays writable on the prototype.
+    this.name = 'OverBudgetError';
+    this.budget = opts.budget;
+    this.actual = opts.actual;
+    this.diagnostics = opts.diagnostics;
+  }
+}
+
+/**
+ * Minimal chunk representation used by the picker. Real callers will adapt
+ * their `StoredMessage` instances to this shape.
+ */
+export interface PickerChunk {
+  id: ChunkId;
+  sequence: number;
+  rawTokens: number;
+  currentResolution: number;
+  lockedByAgent: boolean;
+  bodyGroupId?: string;
+  pinned: boolean;
+  /**
+   * The L1 summary covering this chunk, if any. Higher levels are derived
+   * by walking parentId pointers in the summary tree.
+   */
+  l1Id?: SummaryId;
+}
+
+export interface PickerInputs {
+  /** All chunks in source order (oldest first). */
+  chunks: PickerChunk[];
+  /** All summaries, indexed by id. */
+  summaries: ReadonlyMap<SummaryId, SummaryEntry>;
+  /**
+   * Token count for each summary's recall pair. Keyed by summary id.
+   * If missing, falls back to SummaryEntry.tokens.
+   */
+  recallPairTokens?: ReadonlyMap<SummaryId, number>;
+  /** Tokens consumed by the head window (fixed, not foldable). */
+  headTokens: number;
+  /** Tokens consumed by the tail window (fixed, not foldable). */
+  tailTokens: number;
+  /** Indices into chunks[] that are inside the head window. */
+  headChunkIds: ReadonlySet<ChunkId>;
+  /** Indices into chunks[] that are inside the tail window. */
+  tailChunkIds: ReadonlySet<ChunkId>;
+}
+
+export interface PickerResult {
+  /** Final resolution state per chunk after all applied ops. */
+  finalResolutions: ReadonlyMap<ChunkId, number>;
+  /** Ops applied this run, in order. */
+  applied: FoldOp[];
+  /** Pending production requests the picker emitted. */
+  produced: FoldOp[];
+  /** Final token count after applying all ops. */
+  finalTokens: number;
+  /** True if the picker stopped because budget was met. */
+  budgetMet: boolean;
+  /** True if the picker stopped because no further folds were possible. */
+  exhausted: boolean;
+  /** Number of iterations the picker performed. */
+  iterations: number;
+}
+
+/**
+ * Floor for the per-run loop bound. Scales with chronicle size to keep the
+ * picker from spuriously declaring non-convergence on large stores. See
+ * {@link iterationBound}.
+ */
+const MIN_ITERATIONS = 1_000;
+
+/**
+ * Compute the per-run loop bound from chronicle size. A well-behaved strategy
+ * converges in at most ~one op per chunk per level (`chunks.length * log_N`),
+ * so `chunks.length * 10` is a generous safety net at any reasonable N, and
+ * `MIN_ITERATIONS` ensures small chronicles still get adequate headroom for
+ * exploratory ops before the strategy commits to a fold.
+ *
+ * Returning a numeric bound rather than a constant means a 5K-chunk run no
+ * longer trips a fixed 10K ceiling that wasn't sized for it.
+ */
+function iterationBound(chunkCount: number): number {
+  return Math.max(MIN_ITERATIONS, chunkCount * 10);
+}
+
+export class Picker {
+  constructor(private readonly strategy: FoldingStrategy) {}
+
+  run(inputs: PickerInputs, budget: FoldingBudget): PickerResult {
+    const state = new MutableFoldingState(inputs);
+    const applied: FoldOp[] = [];
+    const produced: FoldOp[] = [];
+    let iterations = 0;
+    const maxIterations = iterationBound(inputs.chunks.length);
+
+    while (iterations < maxIterations) {
+      const op = this.strategy.selectNextFold(state, budget);
+      if (!op) break;
+      iterations++;
+
+      if (op.kind === 'raise') {
+        state.applyRaise(op.groupRoot);
+        applied.push(op);
+      } else if (op.kind === 'lower') {
+        state.applyLower(op.groupRoot);
+        applied.push(op);
+      } else {
+        // produce — record and stop. Caller enqueues; next compile retries.
+        produced.push(op);
+        break;
+      }
+    }
+
+    if (iterations >= maxIterations) {
+      throw new Error(
+        `Picker: strategy ${this.strategy.name} exceeded iteration bound (${maxIterations}` +
+          ` for ${inputs.chunks.length} chunks); likely non-converging`
+      );
+    }
+
+    return {
+      finalResolutions: state.snapshotResolutions(),
+      applied,
+      produced,
+      finalTokens: state.tokenCount(),
+      budgetMet: state.tokenCount() <= budget.targetBudget,
+      exhausted: produced.length === 0 && state.tokenCount() > budget.targetBudget,
+      iterations,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal mutable state used during one picker run.
+ *
+ * Implements FoldingState (the strategy-facing view) and additional methods
+ * for applying fold ops.
+ */
+class MutableFoldingState implements FoldingState {
+  private readonly chunkById = new Map<ChunkId, PickerChunk>();
+  private readonly chunkOrder: PickerChunk[];
+  private readonly summaries: ReadonlyMap<SummaryId, SummaryEntry>;
+  private readonly recallPairTokens: ReadonlyMap<SummaryId, number>;
+  private readonly headChunkIds: ReadonlySet<ChunkId>;
+  private readonly tailChunkIds: ReadonlySet<ChunkId>;
+  private readonly headTokens: number;
+  private readonly tailTokens: number;
+
+  // Cached: chunks that are foldable (middle, not pinned, not locked).
+  // Updated lazily when needed.
+  private foldableCache: ChunkView[] | null = null;
+  private allChunkViews: ChunkView[] | null = null;
+  private tokenCacheValid = false;
+  private tokenCacheValue = 0;
+
+  // For each chunk, its current resolution (mirrors PickerChunk.currentResolution).
+  private resolutions = new Map<ChunkId, number>();
+
+  constructor(inputs: PickerInputs) {
+    this.chunkOrder = [...inputs.chunks].sort((a, b) => a.sequence - b.sequence);
+    for (const c of this.chunkOrder) {
+      this.chunkById.set(c.id, c);
+      this.resolutions.set(c.id, c.currentResolution);
+    }
+    this.summaries = inputs.summaries;
+    this.recallPairTokens = inputs.recallPairTokens ?? new Map();
+    this.headChunkIds = inputs.headChunkIds;
+    this.tailChunkIds = inputs.tailChunkIds;
+    this.headTokens = inputs.headTokens;
+    this.tailTokens = inputs.tailTokens;
+  }
+
+  // ---- FoldingState interface ----
+
+  chunks(): readonly ChunkView[] {
+    if (!this.allChunkViews) {
+      this.allChunkViews = this.chunkOrder.map((c) => this.makeView(c));
+    }
+    return this.allChunkViews;
+  }
+
+  foldableMiddle(): readonly ChunkView[] {
+    if (this.foldableCache) return this.foldableCache;
+    const out: ChunkView[] = [];
+    for (const c of this.chunkOrder) {
+      const inHead = this.headChunkIds.has(c.id);
+      const inTail = this.tailChunkIds.has(c.id);
+      if (inHead || inTail || c.pinned || c.lockedByAgent) continue;
+      out.push(this.makeView(c));
+    }
+    this.foldableCache = out;
+    return out;
+  }
+
+  getSummary(id: SummaryId): SummaryEntry | null {
+    return this.summaries.get(id) ?? null;
+  }
+
+  leavesUnder(groupRoot: SummaryId): readonly ChunkView[] {
+    const summary = this.summaries.get(groupRoot);
+    if (!summary) return [];
+    const leafIds = this.collectLeafIds(summary);
+    const views: ChunkView[] = [];
+    for (const id of leafIds) {
+      const c = this.chunkById.get(id);
+      if (c) views.push(this.makeView(c));
+    }
+    return views;
+  }
+
+  tokenCount(): number {
+    if (this.tokenCacheValid) return this.tokenCacheValue;
+    this.tokenCacheValue = this.computeTokens();
+    this.tokenCacheValid = true;
+    return this.tokenCacheValue;
+  }
+
+  // ---- Mutation methods (picker-internal) ----
+
+  applyRaise(groupRoot: SummaryId): void {
+    const summary = this.summaries.get(groupRoot);
+    if (!summary) {
+      throw new Error(`Picker: applyRaise: unknown groupRoot ${groupRoot}`);
+    }
+    const targetLevel = summary.level;
+    const leafIds = this.collectLeafIds(summary);
+    for (const id of leafIds) {
+      const chunk = this.chunkById.get(id);
+      if (!chunk) continue;
+      // Skip chunks that the picker has no authority over for resolution.
+      // Pinned chunks always render raw (handled at render time), but we
+      // also avoid setting stale resolution state on them — the resolution
+      // field is meaningless while pinned and might be visited later if
+      // the pin is removed, which would be surprising.
+      if (chunk.pinned) continue;
+      if (chunk.lockedByAgent) continue;
+      if (this.headChunkIds.has(id) || this.tailChunkIds.has(id)) continue;
+      const current = this.resolutions.get(id) ?? 0;
+      if (current < targetLevel) {
+        this.resolutions.set(id, targetLevel);
+      }
+    }
+    this.invalidateCaches();
+  }
+
+  applyLower(groupRoot: SummaryId): void {
+    const summary = this.summaries.get(groupRoot);
+    if (!summary) {
+      throw new Error(`Picker: applyLower: unknown groupRoot ${groupRoot}`);
+    }
+    // Lower every leaf under groupRoot by one level (clamped at 0).
+    const leafIds = this.collectLeafIds(summary);
+    for (const id of leafIds) {
+      const chunk = this.chunkById.get(id);
+      if (!chunk) continue;
+      if (chunk.lockedByAgent) continue;
+      const current = this.resolutions.get(id) ?? 0;
+      if (current > 0) {
+        this.resolutions.set(id, current - 1);
+      }
+    }
+    this.invalidateCaches();
+  }
+
+  snapshotResolutions(): ReadonlyMap<ChunkId, number> {
+    return new Map(this.resolutions);
+  }
+
+  // ---- Internals ----
+
+  private invalidateCaches(): void {
+    this.foldableCache = null;
+    this.allChunkViews = null;
+    this.tokenCacheValid = false;
+  }
+
+  private makeView(c: PickerChunk): ChunkView {
+    const self = this;
+    return {
+      id: c.id,
+      sequence: c.sequence,
+      rawTokens: c.rawTokens,
+      currentResolution: self.resolutions.get(c.id) ?? 0,
+      lockedByAgent: c.lockedByAgent,
+      bodyGroupId: c.bodyGroupId,
+      inHead: self.headChunkIds.has(c.id),
+      inTail: self.tailChunkIds.has(c.id),
+      pinned: c.pinned,
+      ancestorAt(level: number): SummaryEntry | null {
+        return self.ancestorAt(c, level);
+      },
+      maxAvailableLevel(): number {
+        return self.maxAvailableLevel(c);
+      },
+    };
+  }
+
+  private ancestorAt(chunk: PickerChunk, level: number): SummaryEntry | null {
+    if (level <= 0) return null;
+    if (!chunk.l1Id) return null;
+    let current: SummaryEntry | undefined = this.summaries.get(chunk.l1Id);
+    while (current && current.level < level) {
+      const parentId = getSummaryParentId(current);
+      if (!parentId) return null;
+      current = this.summaries.get(parentId);
+    }
+    if (!current || current.level !== level) return null;
+    return current;
+  }
+
+  private maxAvailableLevel(chunk: PickerChunk): number {
+    if (!chunk.l1Id) return 0;
+    let current: SummaryEntry | undefined = this.summaries.get(chunk.l1Id);
+    let max = 0;
+    while (current) {
+      max = current.level;
+      const parentId = getSummaryParentId(current);
+      if (!parentId) break;
+      current = this.summaries.get(parentId);
+    }
+    return max;
+  }
+
+  private collectLeafIds(summary: SummaryEntry): ChunkId[] {
+    // Walk down the summary tree from `summary` to leaf chunks.
+    // sourceLevel === 0 means sourceIds are message ids (leaves).
+    // Otherwise sourceIds are summary ids and we recurse.
+    const out: ChunkId[] = [];
+    const visit = (s: SummaryEntry): void => {
+      if (s.sourceLevel === 0) {
+        for (const mid of s.sourceIds) out.push(mid);
+      } else {
+        for (const sid of s.sourceIds) {
+          const child = this.summaries.get(sid);
+          if (child) visit(child);
+        }
+      }
+    };
+    visit(summary);
+    return out;
+  }
+
+  /**
+   * Compute total tokens given current resolutions.
+   * Algorithm:
+   *  - Head + tail are fixed.
+   *  - For chunks in foldableMiddle: those at L0 contribute rawTokens.
+   *  - Those at L_k (k>0): emit the recall pair for the chunk's L_k ancestor
+   *    once per distinct ancestor (sibling chunks under the same ancestor
+   *    share the same rendered recall pair).
+   */
+  private computeTokens(): number {
+    let total = this.headTokens + this.tailTokens;
+    const renderedSummaries = new Set<SummaryId>();
+    for (const c of this.chunkOrder) {
+      if (this.headChunkIds.has(c.id) || this.tailChunkIds.has(c.id)) continue;
+      // Pinned chunks render at L0 regardless of resolution.
+      const effectiveResolution = c.pinned ? 0 : this.resolutions.get(c.id) ?? 0;
+      if (effectiveResolution === 0) {
+        total += c.rawTokens;
+        continue;
+      }
+      const ancestor = this.ancestorAt(c, effectiveResolution);
+      if (!ancestor) {
+        // Resolution is set but summary doesn't exist — treat as L0 for
+        // accounting purposes (the renderer will need to make the same call).
+        total += c.rawTokens;
+        continue;
+      }
+      if (renderedSummaries.has(ancestor.id)) continue;
+      renderedSummaries.add(ancestor.id);
+      const tok = this.recallPairTokens.get(ancestor.id) ?? ancestor.tokens;
+      total += tok;
+    }
+    return total;
+  }
+}

package/src/adaptive/render.ts

@@ -0,0 +1,115 @@
+/**
+ * Render helpers for the adaptive-resolution design.
+ *
+ * The main operation is "group consecutive same-bodyGroupId messages into
+ * a single API message via body concatenation," which is how a chunked
+ * document or large message is reassembled at the API boundary.
+ *
+ * See `docs/adaptive-resolution-design.md` §3.6.
+ */
+
+import type { ContentBlock } from '@animalabs/membrane';
+import type { StoredMessage } from '../types/message.js';
+
+/**
+ * Group consecutive messages that share a bodyGroupId into composite
+ * messages whose body is the byte-faithful concatenation of the shards'
+ * text content. Messages with a null/undefined bodyGroupId pass through
+ * unchanged.
+ *
+ * For a shard at non-zero currentResolution, the shard's text in the
+ * concatenation is replaced by `getRecallText(shard)`. The renderer is
+ * responsible for providing recall content that's appropriate for the
+ * level (an L_k recall pair, formatted however the deployment prefers).
+ *
+ * Properties:
+ *  - **Byte-faithful** when all shards in a group are at L0 and getRecallText
+ *    is not called: the concatenated body equals the original message body
+ *    byte-for-byte. Verified by tests in test/adaptive/render.test.ts.
+ *  - **One API message per group**, regardless of shard count. No turn
+ *    markers between shards.
+ *  - **Order preserved**: shards within a group are sorted by `shardIndex`
+ *    before concatenation; if shardIndex is missing, the order in the input
+ *    array is used.
+ */
+export function concatBodyGroups(
+  messages: readonly StoredMessage[],
+  getRecallText: (shard: StoredMessage) => string
+): StoredMessage[] {
+  const out: StoredMessage[] = [];
+  let i = 0;
+  while (i < messages.length) {
+    const m = messages[i];
+    if (!m.bodyGroupId) {
+      out.push(m);
+      i++;
+      continue;
+    }
+    // Collect all consecutive messages with the same bodyGroupId.
+    const groupId = m.bodyGroupId;
+    const groupStart = i;
+    while (i < messages.length && messages[i].bodyGroupId === groupId) {
+      i++;
+    }
+    const group = messages.slice(groupStart, i);
+    // Sort by shardIndex if present.
+    const sorted = [...group].sort(
+      (a, b) => (a.shardIndex ?? 0) - (b.shardIndex ?? 0)
+    );
+
+    const concatenated = sorted.map((shard) => {
+      const res = shard.currentResolution ?? 0;
+      if (res === 0) {
+        return extractTextContent(shard.content);
+      }
+      return getRecallText(shard);
+    }).join('');
+
+    // Build the composite message. Inherit id/participant/timestamp from
+    // the first shard; combine metadata; build a single text content block.
+    const composite: StoredMessage = {
+      id: sorted[0].id,
+      sequence: sorted[0].sequence,
+      participant: sorted[0].participant,
+      content: [{ type: 'text', text: concatenated } as ContentBlock],
+      metadata: {
+        ...(sorted[0].metadata ?? {}),
+        bodyGroupId: groupId,
+        shardCount: sorted.length,
+      },
+      timestamp: sorted[0].timestamp,
+    };
+    out.push(composite);
+  }
+  return out;
+}
+
+/**
+ * Extract text content from a message's content blocks. For shards we
+ * expect (and require) all content to be text — they were produced by
+ * the chunker, which only splits strings. If non-text blocks slip through,
+ * they're stringified as best-effort.
+ */
+function extractTextContent(blocks: ContentBlock[]): string {
+  const out: string[] = [];
+  for (const b of blocks) {
+    if (b.type === 'text') {
+      out.push(b.text);
+    } else {
+      // Non-text content in a sharded body shouldn't happen, but if it
+      // does, we serialize as a placeholder rather than crashing.
+      out.push(`[non-text content: ${b.type}]`);
+    }
+  }
+  return out.join('');
+}
+
+/**
+ * Default getRecallText for testing or when the strategy hasn't provided
+ * a custom one. Returns a simple "[summary of N tokens]" placeholder so
+ * the concat doesn't accidentally include the raw shard text.
+ */
+export function placeholderRecallText(shard: StoredMessage): string {
+  const level = shard.currentResolution ?? 0;
+  return `\n[L${level} recall of chunk ${shard.id}]\n`;
+}

package/src/adaptive/strategies/flat-profile.ts

@@ -0,0 +1,96 @@
+/**
+ * Default folding strategy: keep visible-item counts roughly equal across levels.
+ *
+ * On each call: if we're over the soft target, find the level with the most
+ * *rendered items* (distinct ancestors among chunks at that resolution),
+ * pick the oldest raisable group at that level, raise it. Tiebreak on level:
+ * lower level wins (fold finer detail before consolidating coarser regions).
+ *
+ * Monotonic (never emits 'lower'). Memory-fading by construction:
+ * a given chunk's resolution only ever increases.
+ *
+ * See `docs/adaptive-resolution-design.md` §3.7.
+ */
+
+import type {
+  FoldingStrategy,
+  FoldingState,
+  FoldingBudget,
+  FoldOp,
+  ChunkId,
+  ChunkView,
+  SummaryId,
+} from '../folding-strategy.js';
+
+export class FlatProfileStrategy implements FoldingStrategy {
+  readonly name = 'flat-profile';
+
+  selectNextFold(state: FoldingState, budget: FoldingBudget): FoldOp | null {
+    if (state.tokenCount() <= budget.targetBudget) return null;
+
+    const middle = state.foldableMiddle();
+    if (middle.length === 0) return null;
+
+    // Count rendered items at each level.
+    // A "rendered item" at level k > 0 is a distinct L_k ancestor.
+    // At level 0, each raw chunk is its own item.
+    const visibleAtLevel = new Map<number, Set<SummaryId | ChunkId>>();
+    for (const chunk of middle) {
+      const k = chunk.currentResolution;
+      if (!visibleAtLevel.has(k)) visibleAtLevel.set(k, new Set());
+      if (k === 0) {
+        visibleAtLevel.get(k)!.add(chunk.id);
+      } else {
+        const ancestor = chunk.ancestorAt(k);
+        if (ancestor) visibleAtLevel.get(k)!.add(ancestor.id);
+      }
+    }
+
+    // Pick most-populous level; tiebreak: lower wins.
+    let bestLevel = -1;
+    let bestCount = 0;
+    for (const [level, items] of visibleAtLevel) {
+      const count = items.size;
+      if (count > bestCount || (count === bestCount && (bestLevel < 0 || level < bestLevel))) {
+        bestLevel = level;
+        bestCount = count;
+      }
+    }
+    if (bestLevel < 0) return null;
+
+    // Find the oldest raisable group at bestLevel. A "group" at level k is
+    // the set of chunks sharing an L_{k+1} ancestor. We want to raise that
+    // group all the way to L_{k+1}.
+    //
+    // The oldest group is the one containing the oldest chunk at level k.
+    const oldestChunk = middle.find((c) => c.currentResolution === bestLevel);
+    if (!oldestChunk) return null;
+
+    const parentLevel = bestLevel + 1;
+    const parentSummary = oldestChunk.ancestorAt(parentLevel);
+    if (!parentSummary) {
+      // L_{k+1} not produced for this chunk's group yet — request it.
+      //
+      // Range semantics differ by level:
+      //  - bestLevel === 0: the caller is asking for an L1 covering this
+      //    raw chunk. In the autobio chunker model the chunk-to-L1 mapping
+      //    is 1:1 — a chunk's message span IS the L1's source range — so
+      //    a single-chunk range is the correct request. (Strategies that
+      //    bundle N raw chunks into one L1 would override this.)
+      //  - bestLevel > 0: the caller is asking for an L_{k+1} merge. We
+      //    use the chunk's existing L_k ancestor's range as a request
+      //    hint; the consumer expands it to cover the full sibling set
+      //    at L_k that should consolidate into the missing L_{k+1}.
+      const lkAncestor = bestLevel === 0 ? null : oldestChunk.ancestorAt(bestLevel);
+      const range = lkAncestor
+        ? {
+            firstChunkId: lkAncestor.sourceRange.first,
+            lastChunkId: lkAncestor.sourceRange.last,
+          }
+        : { firstChunkId: oldestChunk.id, lastChunkId: oldestChunk.id };
+      return { kind: 'produce', level: parentLevel, range };
+    }
+
+    return { kind: 'raise', groupRoot: parentSummary.id };
+  }
+}

package/src/adaptive/strategies/oldest-first.ts

@@ -0,0 +1,48 @@
+/**
+ * Oldest-first folding strategy.
+ *
+ * Always raise the chronologically-oldest raisable chunk's group, regardless
+ * of level distribution. This is the "memory fades chronologically" policy
+ * — the simplest possible monotonic strategy and the one originally proposed
+ * in rev 1 of the design doc.
+ *
+ * Kept for comparison against FlatProfileStrategy and as a fallback during
+ * early rollout.
+ *
+ * See `docs/adaptive-resolution-design.md` §3.5.
+ */
+
+import type {
+  FoldingStrategy,
+  FoldingState,
+  FoldingBudget,
+  FoldOp,
+} from '../folding-strategy.js';
+
+export class OldestFirstStrategy implements FoldingStrategy {
+  readonly name = 'oldest-first';
+
+  selectNextFold(state: FoldingState, budget: FoldingBudget): FoldOp | null {
+    if (state.tokenCount() <= budget.targetBudget) return null;
+
+    const middle = state.foldableMiddle();
+    if (middle.length === 0) return null;
+
+    // Find the oldest raisable chunk.
+    const oldest = middle[0];
+    const targetLevel = oldest.currentResolution + 1;
+    const parent = oldest.ancestorAt(targetLevel);
+    if (!parent) {
+      const lkAncestor = oldest.currentResolution === 0 ? null : oldest.ancestorAt(oldest.currentResolution);
+      const range = lkAncestor
+        ? {
+            firstChunkId: lkAncestor.sourceRange.first,
+            lastChunkId: lkAncestor.sourceRange.last,
+          }
+        : { firstChunkId: oldest.id, lastChunkId: oldest.id };
+      return { kind: 'produce', level: targetLevel, range };
+    }
+
+    return { kind: 'raise', groupRoot: parent.id };
+  }
+}