@animalabs/context-manager 0.4.0 → 0.5.1

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

@@ -0,0 +1,70 @@
+/**
+ * Deterministic chunker for messages that exceed `chunkThreshold` tokens.
+ *
+ * Splits a message body into shards such that concatenating the shards in
+ * order reproduces the original body byte-for-byte. Each shard is identified
+ * by a stable `sourceHash` so re-ingesting the same content produces
+ * identical shard boundaries (and reuses any existing L_k summaries via the
+ * archive's hash-keyed lookup).
+ *
+ * Strategy:
+ *  1. Structural pass — split at markdown headings, code-fence boundaries,
+ *     blank-line paragraph breaks. Prefer larger structural units when they
+ *     fit under `chunkSize`.
+ *  2. Token-bucket fallback — when a structural unit alone exceeds
+ *     `chunkSize`, split it at paragraph or line boundaries until each
+ *     resulting piece fits.
+ *  3. Last-resort hard split — only when no structural seam exists in the
+ *     piece (e.g., one very long line). Splits at the largest UTF-8-safe
+ *     position under the threshold.
+ *
+ * See `docs/adaptive-resolution-design.md` §3.6.
+ */
+export interface ChunkerOptions {
+    /**
+     * Messages with token count strictly greater than this are chunked.
+     * Messages at or below are passed through unchanged.
+     * Default: 8192.
+     */
+    chunkThreshold: number;
+    /**
+     * Target token count per shard. The chunker aims for shards close to
+     * but not exceeding this size. Default: 4096.
+     */
+    chunkSize: number;
+    /**
+     * Approximate characters per token. Used for size estimation since we
+     * can't easily run a tokenizer here. Default: 4.0. The picker uses
+     * cached real token counts; the chunker only needs approximate sizing.
+     */
+    charsPerToken: number;
+}
+export declare const DEFAULT_CHUNKER_OPTIONS: ChunkerOptions;
+export interface Shard {
+    /** Order of this shard within its bodyGroup, starting at 0. */
+    index: number;
+    /** Byte offsets into the original body. [start, end) — UTF-8 byte positions. */
+    range: {
+        startByte: number;
+        endByte: number;
+    };
+    /** Shard content (a substring of the original body). */
+    content: string;
+    /** SHA-256 of the shard content. */
+    sourceHash: string;
+    /** Approximate token count (chars / charsPerToken, rounded). */
+    approxTokens: number;
+}
+export interface ShardingResult {
+    /** True if the message was split into multiple shards. */
+    wasSharded: boolean;
+    /** The shards. If wasSharded is false, exactly one shard containing the entire body. */
+    shards: Shard[];
+    /** The stable group id for these shards (sha256 of the full original body, prefixed). */
+    bodyGroupId: string;
+}
+/**
+ * Chunk a message body. Pure function — no side effects.
+ */
+export declare function chunkMessage(body: string, options?: Partial<ChunkerOptions>): ShardingResult;
+//# sourceMappingURL=chunker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"chunker.d.ts","sourceRoot":"","sources":["../../../src/adaptive/chunker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,cAAc,EAAE,MAAM,CAAC;IAEvB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;;;OAIG;IACH,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,uBAAuB,EAAE,cAIrC,CAAC;AAEF,MAAM,WAAW,KAAK;IACpB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,0DAA0D;IAC1D,UAAU,EAAE,OAAO,CAAC;IACpB,wFAAwF;IACxF,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,yFAAyF;IACzF,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,OAAO,CAAC,cAAc,CAAM,GAAG,cAAc,CAqFhG"}

package/dist/src/adaptive/chunker.js

@@ -0,0 +1,233 @@
+/**
+ * Deterministic chunker for messages that exceed `chunkThreshold` tokens.
+ *
+ * Splits a message body into shards such that concatenating the shards in
+ * order reproduces the original body byte-for-byte. Each shard is identified
+ * by a stable `sourceHash` so re-ingesting the same content produces
+ * identical shard boundaries (and reuses any existing L_k summaries via the
+ * archive's hash-keyed lookup).
+ *
+ * Strategy:
+ *  1. Structural pass — split at markdown headings, code-fence boundaries,
+ *     blank-line paragraph breaks. Prefer larger structural units when they
+ *     fit under `chunkSize`.
+ *  2. Token-bucket fallback — when a structural unit alone exceeds
+ *     `chunkSize`, split it at paragraph or line boundaries until each
+ *     resulting piece fits.
+ *  3. Last-resort hard split — only when no structural seam exists in the
+ *     piece (e.g., one very long line). Splits at the largest UTF-8-safe
+ *     position under the threshold.
+ *
+ * See `docs/adaptive-resolution-design.md` §3.6.
+ */
+import { createHash } from 'node:crypto';
+export const DEFAULT_CHUNKER_OPTIONS = {
+    chunkThreshold: 8192,
+    chunkSize: 4096,
+    charsPerToken: 4.0,
+};
+/**
+ * Chunk a message body. Pure function — no side effects.
+ */
+export function chunkMessage(body, options = {}) {
+    const opts = { ...DEFAULT_CHUNKER_OPTIONS, ...options };
+    const totalApproxTokens = Math.ceil(body.length / opts.charsPerToken);
+    const bodyHash = hashOf(body);
+    const bodyGroupId = `bg-${bodyHash.slice(0, 16)}`;
+    if (totalApproxTokens <= opts.chunkThreshold) {
+        return {
+            wasSharded: false,
+            bodyGroupId,
+            shards: [
+                {
+                    index: 0,
+                    range: { startByte: 0, endByte: byteLength(body) },
+                    content: body,
+                    sourceHash: bodyHash,
+                    approxTokens: totalApproxTokens,
+                },
+            ],
+        };
+    }
+    // Build a list of split points — preferred seams in priority order.
+    // Each seam is a byte offset into the body. The chunker walks the body
+    // and emits shards by greedily accumulating content up to chunkSize at
+    // the highest-quality seam available.
+    const seams = findSeams(body);
+    const targetChars = opts.chunkSize * opts.charsPerToken;
+    const maxChars = opts.chunkSize * opts.charsPerToken * 1.25; // 25% overflow tolerance to land on a clean seam
+    const shards = [];
+    let cursor = 0;
+    let index = 0;
+    const bodyByteLen = byteLength(body);
+    while (cursor < body.length) {
+        // Find the best seam to split at, given the [cursor, cursor + maxChars] window.
+        const windowEnd = Math.min(cursor + maxChars, body.length);
+        const targetEnd = Math.min(cursor + targetChars, body.length);
+        let splitAt;
+        if (windowEnd >= body.length) {
+            splitAt = body.length;
+        }
+        else {
+            splitAt = bestSeamIn(seams, cursor, targetEnd, windowEnd, body);
+        }
+        // Ensure forward progress: if no seam found and we'd produce an empty
+        // shard, take a hard split at the targetEnd.
+        if (splitAt <= cursor) {
+            splitAt = safeCharBoundary(body, targetEnd);
+        }
+        const content = body.slice(cursor, splitAt);
+        const startByte = byteLengthOf(body, 0, cursor);
+        const endByte = startByte + byteLength(content);
+        shards.push({
+            index,
+            range: { startByte, endByte },
+            content,
+            sourceHash: hashOf(content),
+            approxTokens: Math.ceil(content.length / opts.charsPerToken),
+        });
+        cursor = splitAt;
+        index += 1;
+    }
+    // Sanity: byte-faithful reassembly
+    const reassembled = shards.map((s) => s.content).join('');
+    if (reassembled !== body) {
+        throw new Error(`chunker: shard reassembly mismatch (original=${body.length} chars, reassembled=${reassembled.length} chars)`);
+    }
+    if (shards[shards.length - 1].range.endByte !== bodyByteLen) {
+        throw new Error(`chunker: byte-range mismatch (expected end=${bodyByteLen}, got=${shards[shards.length - 1].range.endByte})`);
+    }
+    return {
+        wasSharded: true,
+        bodyGroupId,
+        shards,
+    };
+}
+function findSeams(body) {
+    const seams = [];
+    // Markdown headings: ^(#+)\s
+    // Match at line starts.
+    const headingRe = /(?:^|\n)(#{1,6})\s[^\n]*\n/g;
+    let m;
+    while ((m = headingRe.exec(body)) !== null) {
+        const hashes = m[1];
+        // Position is just before the heading's newline so the heading itself
+        // starts the next shard (cleaner visual boundary).
+        const lineStart = m.index === 0 ? 0 : m.index + 1;
+        if (lineStart === 0)
+            continue; // can't split at the start
+        seams.push({
+            offset: lineStart,
+            priority: hashes.length <= 2 ? 100 : 90,
+        });
+    }
+    // Code-fence boundaries.
+    const fenceRe = /\n```[^\n]*\n/g;
+    while ((m = fenceRe.exec(body)) !== null) {
+        seams.push({ offset: m.index + 1, priority: 80 });
+    }
+    // Blank lines (paragraph breaks): \n\n
+    const blankRe = /\n\n+/g;
+    while ((m = blankRe.exec(body)) !== null) {
+        // Position is just after the last \n in the sequence, so the next
+        // shard begins at the non-blank content.
+        seams.push({ offset: m.index + m[0].length, priority: 70 });
+    }
+    // Single newlines.
+    const nlRe = /\n/g;
+    while ((m = nlRe.exec(body)) !== null) {
+        seams.push({ offset: m.index + 1, priority: 50 });
+    }
+    // Sentence ends.
+    const sentRe = /[.!?]\s+/g;
+    while ((m = sentRe.exec(body)) !== null) {
+        seams.push({ offset: m.index + m[0].length, priority: 30 });
+    }
+    // Word boundaries (any whitespace).
+    const wsRe = /\s+/g;
+    while ((m = wsRe.exec(body)) !== null) {
+        seams.push({ offset: m.index + m[0].length, priority: 10 });
+    }
+    // Deduplicate by offset, keeping highest priority.
+    const byOffset = new Map();
+    for (const s of seams) {
+        const prev = byOffset.get(s.offset);
+        if (prev === undefined || prev < s.priority)
+            byOffset.set(s.offset, s.priority);
+    }
+    return Array.from(byOffset.entries())
+        .map(([offset, priority]) => ({ offset, priority }))
+        .sort((a, b) => a.offset - b.offset);
+}
+/**
+ * Find the highest-priority seam in (cursor, windowEnd] that falls at or
+ * before targetEnd if possible, otherwise the closest after targetEnd up to
+ * windowEnd. Returns the chosen split offset.
+ */
+function bestSeamIn(seams, cursor, targetEnd, windowEnd, body) {
+    // Binary search for the first seam strictly > cursor.
+    let lo = 0;
+    let hi = seams.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (seams[mid].offset <= cursor)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    let bestPreTarget = null;
+    let bestPostTarget = null;
+    for (let i = lo; i < seams.length; i++) {
+        const s = seams[i];
+        if (s.offset > windowEnd)
+            break;
+        if (s.offset <= targetEnd) {
+            if (!bestPreTarget || s.priority > bestPreTarget.priority || (s.priority === bestPreTarget.priority && s.offset > bestPreTarget.offset)) {
+                bestPreTarget = s;
+            }
+        }
+        else {
+            if (!bestPostTarget || s.priority > bestPostTarget.priority || (s.priority === bestPostTarget.priority && s.offset < bestPostTarget.offset)) {
+                bestPostTarget = s;
+            }
+        }
+    }
+    // Prefer the best seam at or before target.
+    if (bestPreTarget)
+        return bestPreTarget.offset;
+    if (bestPostTarget)
+        return bestPostTarget.offset;
+    // No seams in window — hard split at a UTF-8-safe boundary near target.
+    return safeCharBoundary(body, targetEnd);
+}
+/**
+ * Return an offset ≤ target that doesn't fall inside a UTF-16 surrogate pair.
+ * The chunker operates on JS strings (UTF-16); splitting inside a surrogate
+ * pair would corrupt the output.
+ */
+function safeCharBoundary(body, target) {
+    if (target >= body.length)
+        return body.length;
+    if (target <= 0)
+        return 0;
+    const code = body.charCodeAt(target);
+    // If we'd split before a low surrogate, back up one.
+    if (code >= 0xdc00 && code <= 0xdfff) {
+        return target - 1;
+    }
+    return target;
+}
+/** UTF-8 byte length of a JS string. */
+function byteLength(s) {
+    return Buffer.byteLength(s, 'utf8');
+}
+/** UTF-8 byte length of body[start..end] without allocating the slice when possible. */
+function byteLengthOf(body, start, end) {
+    if (start === 0 && end === 0)
+        return 0;
+    return Buffer.byteLength(body.slice(start, end), 'utf8');
+}
+function hashOf(s) {
+    return createHash('sha256').update(s, 'utf8').digest('hex');
+}
+//# sourceMappingURL=chunker.js.map

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

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

package/dist/src/adaptive/folding-strategy.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Pluggable folding strategy interface for the adaptive-resolution picker.
+ *
+ * The picker is a generic orchestrator; the policy (which group to raise next,
+ * whether to lower, whether to request a missing summary) lives in a strategy
+ * object. V1 ships `FlatProfileStrategy` (default, level-equalizing) and
+ * `OldestFirstStrategy` (chronological, matches the rev-1 design).
+ *
+ * See `docs/adaptive-resolution-design.md` §3.5.
+ */
+import type { MessageId } from '../types/message.js';
+import type { SummaryEntry } from '../types/strategy.js';
+/** Identifier of a summary in the archive (e.g., "L2-15"). */
+export type SummaryId = string;
+/** Identifier of a chunk — for now equivalent to a MessageId. */
+export type ChunkId = MessageId;
+/** Half-open range of chunks, identified by message IDs. */
+export interface ChunkRange {
+    firstChunkId: ChunkId;
+    lastChunkId: ChunkId;
+}
+/**
+ * A view of a single chunk for strategy decisions.
+ *
+ * Strategies should treat ChunkView as read-only. Use the picker's
+ * apply() to commit fold operations rather than mutating fields directly.
+ */
+export interface ChunkView {
+    id: ChunkId;
+    /** Position in source order (lower = older). */
+    sequence: number;
+    /** Approximate tokens of raw content. */
+    rawTokens: number;
+    /** Current display resolution. 0 = raw, k>0 = L_k summary. */
+    currentResolution: number;
+    /** Whether the picker is forbidden from changing currentResolution. */
+    lockedByAgent: boolean;
+    /** If this chunk is a shard of a larger logical message, the group id. */
+    bodyGroupId?: string;
+    /** True if this chunk is in the head window (kept raw). */
+    inHead: boolean;
+    /** True if this chunk is in the tail window (kept raw). */
+    inTail: boolean;
+    /** True if this chunk is pinned. */
+    pinned: boolean;
+    /**
+     * The chunk's ancestor at level k in the summary tree, if one exists.
+     * Returns null if the level has not been produced for this chunk's range.
+     */
+    ancestorAt(level: number): SummaryEntry | null;
+    /** The highest level k for which a summary exists covering this chunk. */
+    maxAvailableLevel(): number;
+}
+/**
+ * Read-only view passed to a FoldingStrategy.
+ */
+export interface FoldingState {
+    /** All chunks in source order. */
+    chunks(): readonly ChunkView[];
+    /** Chunks that are foldable — not in head/tail, not pinned, not locked. */
+    foldableMiddle(): readonly ChunkView[];
+    /** Look up a summary by id. */
+    getSummary(id: SummaryId): SummaryEntry | null;
+    /** All leaf chunks under a given summary (recursively walks the tree). */
+    leavesUnder(groupRoot: SummaryId): readonly ChunkView[];
+    /**
+     * Estimate of total tokens that would be rendered with the current
+     * per-chunk resolutions. Cached; recompute via recomputeTokens() after
+     * applying a fold op.
+     */
+    tokenCount(): number;
+}
+/** A fold operation returned by FoldingStrategy.selectNextFold. */
+export type FoldOp = {
+    kind: 'raise';
+    /** L_{k+1} summary id that becomes the new visible level for the group. */
+    groupRoot: SummaryId;
+} | {
+    kind: 'lower';
+    /** L_k summary id whose group is being lowered to (k-1). V2 only. */
+    groupRoot: SummaryId;
+} | {
+    kind: 'produce';
+    /** Level to produce (e.g., 2 for L2). */
+    level: number;
+    /** Range of chunks the produced summary should cover. */
+    range: ChunkRange;
+};
+/**
+ * Budget context for the strategy.
+ */
+export interface FoldingBudget {
+    /** Hard maximum tokens (model context - response reserve). */
+    totalBudget: number;
+    /** Soft target tokens (totalBudget * (1 - slack)). Strategies fold until at or below. */
+    targetBudget: number;
+    /** Slack ratio (e.g., 0.1 for 10%). */
+    slack: number;
+}
+/**
+ * Pluggable strategy interface.
+ *
+ * The picker calls selectNextFold() repeatedly until it returns null. On
+ * each call, the strategy inspects current state and returns one operation:
+ *  - 'raise' — fold a group up one level (the picker applies it and re-asks)
+ *  - 'lower' — refold down one level (V2; default V1 strategies don't emit this)
+ *  - 'produce' — request lazy summary production (the picker enqueues it
+ *    and stops; the next compile will retry)
+ *
+ * A strategy MUST converge: it must either eventually return null, or emit
+ * a 'produce' op that doesn't loop indefinitely. The picker has its own
+ * loop-bound safeguard, but well-behaved strategies make it unnecessary.
+ */
+export interface FoldingStrategy {
+    readonly name: string;
+    selectNextFold(state: FoldingState, budget: FoldingBudget): FoldOp | null;
+}
+//# sourceMappingURL=folding-strategy.d.ts.map

package/dist/src/adaptive/folding-strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"folding-strategy.d.ts","sourceRoot":"","sources":["../../../src/adaptive/folding-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,8DAA8D;AAC9D,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B,iEAAiE;AACjE,MAAM,MAAM,OAAO,GAAG,SAAS,CAAC;AAEhC,4DAA4D;AAC5D,MAAM,WAAW,UAAU;IACzB,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,OAAO,CAAC;IACZ,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,iBAAiB,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,aAAa,EAAE,OAAO,CAAC;IACvB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,MAAM,EAAE,OAAO,CAAC;IAChB,2DAA2D;IAC3D,MAAM,EAAE,OAAO,CAAC;IAChB,oCAAoC;IACpC,MAAM,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAAC;IAC/C,0EAA0E;IAC1E,iBAAiB,IAAI,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,kCAAkC;IAClC,MAAM,IAAI,SAAS,SAAS,EAAE,CAAC;IAC/B,2EAA2E;IAC3E,cAAc,IAAI,SAAS,SAAS,EAAE,CAAC;IACvC,+BAA+B;IAC/B,UAAU,CAAC,EAAE,EAAE,SAAS,GAAG,YAAY,GAAG,IAAI,CAAC;IAC/C,0EAA0E;IAC1E,WAAW,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,SAAS,EAAE,CAAC;IACxD;;;;OAIG;IACH,UAAU,IAAI,MAAM,CAAC;CACtB;AAED,mEAAmE;AACnE,MAAM,MAAM,MAAM,GACd;IACE,IAAI,EAAE,OAAO,CAAC;IACd,2EAA2E;IAC3E,SAAS,EAAE,SAAS,CAAC;CACtB,GACD;IACE,IAAI,EAAE,OAAO,CAAC;IACd,qEAAqE;IACrE,SAAS,EAAE,SAAS,CAAC;CACtB,GACD;IACE,IAAI,EAAE,SAAS,CAAC;IAChB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,KAAK,EAAE,UAAU,CAAC;CACnB,CAAC;AAEN;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,yFAAyF;IACzF,YAAY,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAAC;CAC3E"}

package/dist/src/adaptive/folding-strategy.js

@@ -0,0 +1,12 @@
+/**
+ * Pluggable folding strategy interface for the adaptive-resolution picker.
+ *
+ * The picker is a generic orchestrator; the policy (which group to raise next,
+ * whether to lower, whether to request a missing summary) lives in a strategy
+ * object. V1 ships `FlatProfileStrategy` (default, level-equalizing) and
+ * `OldestFirstStrategy` (chronological, matches the rev-1 design).
+ *
+ * See `docs/adaptive-resolution-design.md` §3.5.
+ */
+export {};
+//# sourceMappingURL=folding-strategy.js.map

package/dist/src/adaptive/folding-strategy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"folding-strategy.js","sourceRoot":"","sources":["../../../src/adaptive/folding-strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

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

@@ -0,0 +1,17 @@
+/**
+ * Adaptive-resolution context management subsystem.
+ *
+ * See `docs/adaptive-resolution-design.md` for the architectural overview.
+ *
+ * Status: V1 implementation, not yet wired into `AutobiographicalStrategy`.
+ * Modules in this directory are exercised via the test harness in
+ * `test/adaptive/` and will be integrated into the strategy in a follow-up
+ * once the design is validated against real workloads.
+ */
+export { chunkMessage, DEFAULT_CHUNKER_OPTIONS, type ChunkerOptions, type Shard, type ShardingResult, } from './chunker.js';
+export type { FoldingStrategy, FoldingState, FoldingBudget, FoldOp, ChunkView, ChunkId, ChunkRange, SummaryId, } from './folding-strategy.js';
+export { FlatProfileStrategy } from './strategies/flat-profile.js';
+export { OldestFirstStrategy } from './strategies/oldest-first.js';
+export { Picker, OverBudgetError, type PickerInputs, type PickerResult, type PickerChunk, } from './picker.js';
+export { concatBodyGroups, placeholderRecallText } from './render.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adaptive/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EACL,YAAY,EACZ,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,KAAK,EACV,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,eAAe,EACf,YAAY,EACZ,aAAa,EACb,MAAM,EACN,SAAS,EACT,OAAO,EACP,UAAU,EACV,SAAS,GACV,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAGnE,OAAO,EACL,MAAM,EACN,eAAe,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC"}

package/dist/src/adaptive/index.js

@@ -0,0 +1,23 @@
+/**
+ * Adaptive-resolution context management subsystem.
+ *
+ * See `docs/adaptive-resolution-design.md` for the architectural overview.
+ *
+ * Status: V1 implementation, not yet wired into `AutobiographicalStrategy`.
+ * Modules in this directory are exercised via the test harness in
+ * `test/adaptive/` and will be integrated into the strategy in a follow-up
+ * once the design is validated against real workloads.
+ */
+// Chunker
+export { chunkMessage, DEFAULT_CHUNKER_OPTIONS, } from './chunker.js';
+// Concrete strategies
+export { FlatProfileStrategy } from './strategies/flat-profile.js';
+export { OldestFirstStrategy } from './strategies/oldest-first.js';
+// Picker
+export { Picker, OverBudgetError, } from './picker.js';
+// Render helpers
+export { concatBodyGroups, placeholderRecallText } from './render.js';
+// Chunk locking is exposed as a method on `AutobiographicalStrategy`
+// (`lockChunk(id)` / `unlockChunk(id)`); there is no standalone lock API at
+// the adaptive layer. The picker honors `PickerChunk.lockedByAgent`.
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adaptive/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,UAAU;AACV,OAAO,EACL,YAAY,EACZ,uBAAuB,GAIxB,MAAM,cAAc,CAAC;AActB,sBAAsB;AACtB,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAEnE,SAAS;AACT,OAAO,EACL,MAAM,EACN,eAAe,GAIhB,MAAM,aAAa,CAAC;AAErB,iBAAiB;AACjB,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEtE,qEAAqE;AACrE,4EAA4E;AAC5E,qEAAqE"}

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

@@ -0,0 +1,103 @@
+/**
+ * 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, FoldingBudget, FoldOp, ChunkId, SummaryId } from './folding-strategy.js';
+import type { SummaryEntry } 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 declare 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'];
+    });
+}
+/**
+ * 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;
+}
+export declare class Picker {
+    private readonly strategy;
+    constructor(strategy: FoldingStrategy);
+    run(inputs: PickerInputs, budget: FoldingBudget): PickerResult;
+}
+//# sourceMappingURL=picker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"picker.d.ts","sourceRoot":"","sources":["../../../src/adaptive/picker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EACV,eAAe,EAEf,aAAa,EACb,MAAM,EAEN,OAAO,EACP,SAAS,EAEV,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGzD;;;;;;;;;;GAUG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oEAAoE;IACpE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,gBAAgB,EAAE,MAAM,CAAC;QACzB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;gBAEU,IAAI,EAAE;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,eAAe,CAAC,aAAa,CAAC,CAAC;KAC7C;CAcF;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,aAAa,EAAE,OAAO,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAED,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,oCAAoC;IACpC,SAAS,EAAE,WAAW,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC;IAChD;;;OAGG;IACH,gBAAgB,CAAC,EAAE,WAAW,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAClD,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,YAAY,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;IACnC,6DAA6D;IAC7D,YAAY,EAAE,WAAW,CAAC,OAAO,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,YAAY;IAC3B,8DAA8D;IAC9D,gBAAgB,EAAE,WAAW,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC/C,sCAAsC;IACtC,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,yDAAyD;IACzD,SAAS,EAAE,OAAO,CAAC;IACnB,yEAAyE;IACzE,SAAS,EAAE,OAAO,CAAC;IACnB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;CACpB;AAuBD,qBAAa,MAAM;IACL,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,eAAe;IAEtD,GAAG,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,GAAG,YAAY;CA0C/D"}