@animalabs/context-manager 0.4.0 → 0.5.1

package/dist/src/adaptive/picker.js

@@ -0,0 +1,357 @@
+/**
+ * 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 { 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. */
+    budget;
+    /** The token count the strategy could not reduce below `budget`. */
+    actual;
+    /** Diagnostic snapshot of the picker's final state. */
+    diagnostics;
+    constructor(opts) {
+        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;
+    }
+}
+/**
+ * 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) {
+    return Math.max(MIN_ITERATIONS, chunkCount * 10);
+}
+export class Picker {
+    strategy;
+    constructor(strategy) {
+        this.strategy = strategy;
+    }
+    run(inputs, budget) {
+        const state = new MutableFoldingState(inputs);
+        const applied = [];
+        const produced = [];
+        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 {
+    chunkById = new Map();
+    chunkOrder;
+    summaries;
+    recallPairTokens;
+    headChunkIds;
+    tailChunkIds;
+    headTokens;
+    tailTokens;
+    // Cached: chunks that are foldable (middle, not pinned, not locked).
+    // Updated lazily when needed.
+    foldableCache = null;
+    allChunkViews = null;
+    tokenCacheValid = false;
+    tokenCacheValue = 0;
+    // For each chunk, its current resolution (mirrors PickerChunk.currentResolution).
+    resolutions = new Map();
+    constructor(inputs) {
+        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() {
+        if (!this.allChunkViews) {
+            this.allChunkViews = this.chunkOrder.map((c) => this.makeView(c));
+        }
+        return this.allChunkViews;
+    }
+    foldableMiddle() {
+        if (this.foldableCache)
+            return this.foldableCache;
+        const out = [];
+        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) {
+        return this.summaries.get(id) ?? null;
+    }
+    leavesUnder(groupRoot) {
+        const summary = this.summaries.get(groupRoot);
+        if (!summary)
+            return [];
+        const leafIds = this.collectLeafIds(summary);
+        const views = [];
+        for (const id of leafIds) {
+            const c = this.chunkById.get(id);
+            if (c)
+                views.push(this.makeView(c));
+        }
+        return views;
+    }
+    tokenCount() {
+        if (this.tokenCacheValid)
+            return this.tokenCacheValue;
+        this.tokenCacheValue = this.computeTokens();
+        this.tokenCacheValid = true;
+        return this.tokenCacheValue;
+    }
+    // ---- Mutation methods (picker-internal) ----
+    applyRaise(groupRoot) {
+        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) {
+        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() {
+        return new Map(this.resolutions);
+    }
+    // ---- Internals ----
+    invalidateCaches() {
+        this.foldableCache = null;
+        this.allChunkViews = null;
+        this.tokenCacheValid = false;
+    }
+    makeView(c) {
+        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) {
+                return self.ancestorAt(c, level);
+            },
+            maxAvailableLevel() {
+                return self.maxAvailableLevel(c);
+            },
+        };
+    }
+    ancestorAt(chunk, level) {
+        if (level <= 0)
+            return null;
+        if (!chunk.l1Id)
+            return null;
+        let current = 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;
+    }
+    maxAvailableLevel(chunk) {
+        if (!chunk.l1Id)
+            return 0;
+        let current = 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;
+    }
+    collectLeafIds(summary) {
+        // 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 = [];
+        const visit = (s) => {
+            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).
+     */
+    computeTokens() {
+        let total = this.headTokens + this.tailTokens;
+        const renderedSummaries = new Set();
+        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;
+    }
+}
+//# sourceMappingURL=picker.js.map

package/dist/src/adaptive/picker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"picker.js","sourceRoot":"","sources":["../../../src/adaptive/picker.ts"],"names":[],"mappings":"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"}

package/dist/src/adaptive/render.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 { 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 declare function concatBodyGroups(messages: readonly StoredMessage[], getRecallText: (shard: StoredMessage) => string): StoredMessage[];
+/**
+ * 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 declare function placeholderRecallText(shard: StoredMessage): string;
+//# sourceMappingURL=render.d.ts.map

package/dist/src/adaptive/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../../src/adaptive/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,aAAa,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,MAAM,GAC9C,aAAa,EAAE,CA+CjB;AAsBD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAGlE"}

package/dist/src/adaptive/render.js

@@ -0,0 +1,104 @@
+/**
+ * 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.
+ */
+/**
+ * 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, getRecallText) {
+    const out = [];
+    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 = {
+            id: sorted[0].id,
+            sequence: sorted[0].sequence,
+            participant: sorted[0].participant,
+            content: [{ type: 'text', text: concatenated }],
+            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) {
+    const out = [];
+    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) {
+    const level = shard.currentResolution ?? 0;
+    return `\n[L${level} recall of chunk ${shard.id}]\n`;
+}
+//# sourceMappingURL=render.js.map

package/dist/src/adaptive/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../../../src/adaptive/render.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,19 @@
+/**
+ * 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 } from '../folding-strategy.js';
+export declare class FlatProfileStrategy implements FoldingStrategy {
+    readonly name = "flat-profile";
+    selectNextFold(state: FoldingState, budget: FoldingBudget): FoldOp | null;
+}
+//# sourceMappingURL=flat-profile.d.ts.map

package/dist/src/adaptive/strategies/flat-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flat-profile.d.ts","sourceRoot":"","sources":["../../../../src/adaptive/strategies/flat-profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,eAAe,EACf,YAAY,EACZ,aAAa,EACb,MAAM,EAIP,MAAM,wBAAwB,CAAC;AAEhC,qBAAa,mBAAoB,YAAW,eAAe;IACzD,QAAQ,CAAC,IAAI,kBAAkB;IAE/B,cAAc,CAAC,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI;CAoE1E"}

package/dist/src/adaptive/strategies/flat-profile.js

@@ -0,0 +1,86 @@
+/**
+ * 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.
+ */
+export class FlatProfileStrategy {
+    name = 'flat-profile';
+    selectNextFold(state, budget) {
+        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();
+        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 };
+    }
+}
+//# sourceMappingURL=flat-profile.js.map

package/dist/src/adaptive/strategies/flat-profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flat-profile.js","sourceRoot":"","sources":["../../../../src/adaptive/strategies/flat-profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAYH,MAAM,OAAO,mBAAmB;IACrB,IAAI,GAAG,cAAc,CAAC;IAE/B,cAAc,CAAC,KAAmB,EAAE,MAAqB;QACvD,IAAI,KAAK,CAAC,UAAU,EAAE,IAAI,MAAM,CAAC,YAAY;YAAE,OAAO,IAAI,CAAC;QAE3D,MAAM,MAAM,GAAG,KAAK,CAAC,cAAc,EAAE,CAAC;QACtC,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAErC,sCAAsC;QACtC,+DAA+D;QAC/D,8CAA8C;QAC9C,MAAM,cAAc,GAAG,IAAI,GAAG,EAAoC,CAAC;QACnE,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,CAAC,GAAG,KAAK,CAAC,iBAAiB,CAAC;YAClC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,cAAc,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;YAC7D,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;gBACZ,cAAc,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YACvC,CAAC;iBAAM,CAAC;gBACN,MAAM,QAAQ,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;gBACrC,IAAI,QAAQ;oBAAE,cAAc,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;YACxD,CAAC;QACH,CAAC;QAED,kDAAkD;QAClD,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC;QACnB,IAAI,SAAS,GAAG,CAAC,CAAC;QAClB,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,cAAc,EAAE,CAAC;YAC5C,MAAM,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC;YACzB,IAAI,KAAK,GAAG,SAAS,IAAI,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,SAAS,GAAG,CAAC,IAAI,KAAK,GAAG,SAAS,CAAC,CAAC,EAAE,CAAC;gBACvF,SAAS,GAAG,KAAK,CAAC;gBAClB,SAAS,GAAG,KAAK,CAAC;YACpB,CAAC;QACH,CAAC;QACD,IAAI,SAAS,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAE/B,uEAAuE;QACvE,uEAAuE;QACvE,gCAAgC;QAChC,EAAE;QACF,sEAAsE;QACtE,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,iBAAiB,KAAK,SAAS,CAAC,CAAC;QAC1E,IAAI,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC;QAE9B,MAAM,WAAW,GAAG,SAAS,GAAG,CAAC,CAAC;QAClC,MAAM,aAAa,GAAG,WAAW,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC;QAC1D,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,gEAAgE;YAChE,EAAE;YACF,mCAAmC;YACnC,mEAAmE;YACnE,qEAAqE;YACrE,mEAAmE;YACnE,mEAAmE;YACnE,2DAA2D;YAC3D,kEAAkE;YAClE,gEAAgE;YAChE,iEAAiE;YACjE,8DAA8D;YAC9D,MAAM,UAAU,GAAG,SAAS,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;YAC9E,MAAM,KAAK,GAAG,UAAU;gBACtB,CAAC,CAAC;oBACE,YAAY,EAAE,UAAU,CAAC,WAAW,CAAC,KAAK;oBAC1C,WAAW,EAAE,UAAU,CAAC,WAAW,CAAC,IAAI;iBACzC;gBACH,CAAC,CAAC,EAAE,YAAY,EAAE,WAAW,CAAC,EAAE,EAAE,WAAW,EAAE,WAAW,CAAC,EAAE,EAAE,CAAC;YAClE,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;QACxD,CAAC;QAED,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,aAAa,CAAC,EAAE,EAAE,CAAC;IACxD,CAAC;CACF"}

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

@@ -0,0 +1,19 @@
+/**
+ * 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 declare class OldestFirstStrategy implements FoldingStrategy {
+    readonly name = "oldest-first";
+    selectNextFold(state: FoldingState, budget: FoldingBudget): FoldOp | null;
+}
+//# sourceMappingURL=oldest-first.d.ts.map