@animalabs/context-manager 0.3.0 → 0.5.0

package/dist/src/types/strategy.d.ts

@@ -1,4 +1,5 @@
-import type { Membrane } from '@animalabs/membrane';
+import type { JsStore } from '@animalabs/chronicle';
+import type { Membrane, ContentBlock } from '@animalabs/membrane';
 import type { StoredMessage, MessageId, Sequence } from './message.js';
 import type { ContextEntry, TokenBudget } from './context.js';
 /**
@@ -45,6 +46,22 @@ export interface StrategyContext {
     membrane?: Membrane;
     /** Current sequence number */
     currentSequence: Sequence;
+    /**
+     * Underlying Chronicle store. Strategies may register their own state slots
+     * (via `store.registerState`) for durable strategy state that needs to
+     * survive process restart and follow Chronicle branches.
+     *
+     * State IDs should be scoped under `namespace` to avoid collisions with
+     * other strategies or with the message/context-log states.
+     */
+    store: JsStore;
+    /**
+     * Namespace under which this strategy should scope its state IDs.
+     * Use as a prefix: e.g. `${namespace}/autobio:summaries`. Always defined;
+     * defaults to a stable per-manager value when no caller-supplied namespace
+     * exists, so strategies never need to handle the unscoped case.
+     */
+    namespace: string;
 }
 /**
  * Result of readiness check.
@@ -93,6 +110,36 @@ export interface ContextStrategy {
      * This is the core method that determines what goes in the context window.
      */
     select(store: MessageStoreView, log: ContextLogView, budget: TokenBudget): ContextEntry[];
+    /**
+     * Optional: at ingestion time, decide whether to split this incoming
+     * message into multiple shards (because it's too large to be a single
+     * fold unit). If returned, the framework stores each shard as a separate
+     * StoredMessage with the shared `bodyGroupId` and per-shard `shardIndex`,
+     * and the render path will reassemble them into one API message at
+     * compile time.
+     *
+     * Return null or undefined to skip chunking (message stored as one record).
+     *
+     * See `docs/adaptive-resolution-design.md` §3.6.
+     */
+    chunkIngressMessage?(participant: string, content: ContentBlock[]): IngressChunkResult | null;
+}
+/**
+ * Result of a strategy's ingestion-time chunking decision.
+ */
+export interface IngressChunkResult {
+    /** Stable id shared by all shards of this message. */
+    bodyGroupId: string;
+    /**
+     * The shards in source order. Each becomes a separate StoredMessage.
+     * Concatenating the shards' text content must reproduce the original
+     * message body byte-for-byte.
+     */
+    shards: Array<{
+        content: ContentBlock[];
+        /** Order within the bodyGroup, starting at 0. */
+        shardIndex: number;
+    }>;
 }
 /**
  * Strategy that supports resetting the head window for topic transitions.
@@ -108,6 +155,103 @@ export interface ResettableStrategy extends ContextStrategy {
  * Type guard for strategies that support head window reset.
  */
 export declare function isResettableStrategy(s: ContextStrategy): s is ResettableStrategy;
+/**
+ * Strategy that supports protected ranges (pins + documents).
+ * Pinned ranges are excluded from compression and render raw at their
+ * original chronological position. Implemented by AutobiographicalStrategy.
+ */
+export interface PinnableStrategy extends ContextStrategy {
+    pinRange(firstMessageId: string, lastMessageId: string, opts?: {
+        name?: string;
+    }): string;
+    markDocument(messageId: string, opts?: {
+        name?: string;
+    }): string;
+    unpin(pinId: string): boolean;
+    listPins(): ReadonlyArray<ProtectedRange>;
+}
+/** Type guard for strategies that support pins / documents. */
+export declare function isPinnableStrategy(s: ContextStrategy): s is PinnableStrategy;
+/**
+ * Query for `searchSummaries`. At least one of `text` or `regex` should be
+ * provided to constrain results; otherwise all summaries pass.
+ */
+export interface SearchQuery {
+    /** Case-insensitive substring match against summary content. */
+    text?: string;
+    /** Regex match against summary content (overrides `text` if both set). */
+    regex?: RegExp;
+    /** Filter by summary level(s). Default: all levels. */
+    levels?: SummaryLevel[];
+    /** Maximum number of results to return. Default: 50. */
+    limit?: number;
+    /**
+     * Include summaries that have been merged into a higher-level summary.
+     * Default: false (only "live" unmerged summaries are returned).
+     */
+    includeMerged?: boolean;
+}
+/** Result of a single search match. */
+export interface SearchResult {
+    summary: SummaryEntry;
+    /** Number of times the query pattern matched in the summary content. */
+    matches: number;
+}
+/**
+ * Strategy that supports searching its summary archive. Implemented by
+ * AutobiographicalStrategy.
+ */
+export interface SearchableStrategy extends ContextStrategy {
+    searchSummaries(query: SearchQuery): SearchResult[];
+    getSummary(id: string): SummaryEntry | null;
+}
+/** Type guard for strategies that support search. */
+export declare function isSearchableStrategy(s: ContextStrategy): s is SearchableStrategy;
+/**
+ * Per-render observability stats from a strategy. Counts and token sums for
+ * head / tail / summaries / pending work, suitable for TUIs and dashboards
+ * that want to display "how much of the context is folded vs raw" at a
+ * glance. Token sums use the strategy's own estimates so they line up with
+ * the numbers `select()` uses for budget math.
+ */
+export interface RenderStats {
+    head: {
+        messages: number;
+        tokens: number;
+    };
+    tail: {
+        messages: number;
+        tokens: number;
+    };
+    summaries: {
+        l1: {
+            count: number;
+            tokens: number;
+        };
+        l2: {
+            count: number;
+            tokens: number;
+        };
+        l3: {
+            count: number;
+            tokens: number;
+        };
+    };
+    pending: {
+        chunks: number;
+        merges: number;
+    };
+}
+/**
+ * Strategy that can produce render-time observability stats. Implemented by
+ * AutobiographicalStrategy. Optional capability — strategies that don't
+ * implement it simply have `ContextManager.getRenderStats()` return `null`.
+ */
+export interface RenderStatsCapableStrategy extends ContextStrategy {
+    getRenderStats(store: MessageStoreView): RenderStats;
+}
+/** Type guard for strategies that produce render stats. */
+export declare function isRenderStatsCapable(s: ContextStrategy): s is RenderStatsCapableStrategy;
 /**
  * Configuration for the Autobiographical strategy.
  */
@@ -156,42 +300,190 @@ export interface AutobiographicalConfig {
     l2BudgetTokens?: number;
     /** Token budget for L1 summaries in select() (default: 30000) */
     l1BudgetTokens?: number;
+    /**
+     * When true (default), each selected summary emits as its own positioned
+     * Q/A recall pair, sorted chronologically by source range. When false,
+     * all selected summaries are concatenated into one Q/A pair between head
+     * and tail (legacy behavior pre-2026-05-10).
+     *
+     * Per-region positioning is the spec-faithful behavior: it lets the agent
+     * see each memory in its temporal place rather than as a wall of unrelated
+     * recollections from another speaker. Without it, hierarchical compression
+     * is structurally similar to the dual-recall corruption pattern that
+     * caused Lena's context degradation on Hermes.
+     */
+    positionedRecallPairs?: boolean;
+    /**
+     * Template for the per-pair recall question header. Substitutions:
+     *   {id}    — summary id (e.g. "L1-3")
+     *   {level} — summary level (1, 2, or 3)
+     *   {first} — first source message id
+     *   {last}  — last source message id
+     * Default: '[Recall {id}]'.
+     *
+     * Only used when `positionedRecallPairs` is true.
+     */
+    recallHeaderTemplate?: string;
+    /**
+     * Per-tool retention limit: keep at most the last N `tool_result` blocks
+     * for each tool name. Older results get their content replaced with a
+     * brief marker referencing the tool name and how many newer results exist.
+     *
+     * Two shapes accepted:
+     *  - `number`: applies as a global default across all tools.
+     *  - `Record<toolName, number>`: per-tool limit; tools not listed are
+     *    unlimited.
+     *
+     * Default: undefined (no pruning). Use a small number (1–5) for tools
+     * that produce verbose, mostly-stale output (e.g. file listings, http
+     * fetches, log queries).
+     */
+    toolResultMaxLastN?: number | Record<string, number>;
+    /**
+     * Truncate `tool_use` block inputs whose serialized JSON exceeds this
+     * many tokens. The truncated input becomes `{ "_truncated": true,
+     * "_originalTokens": N }` plus a head slice of the original input
+     * keys for context. Default: 0 (no truncation).
+     */
+    toolUseInputMaxTokens?: number;
+    /**
+     * Cap on the number of speculative L1 summaries the strategy will hold
+     * (queued + unmerged). When `count(unmerged L1s) + count(queued chunks)`
+     * exceeds this cap, `onNewMessage`'s auto-tick is held back. Chunks
+     * still form and queue, but compression is deferred until a manual
+     * `tick()` or `compile()` triggers it.
+     *
+     * Default: undefined (no cap; compression fires eagerly on every
+     * new message when `autoTickOnNewMessage` is true).
+     */
+    maxSpeculativeL1s?: number;
+    /**
+     * When false, the rendering pipeline emits the full ideal context (head
+     * window + all selected summaries + all recent messages) without
+     * truncating to fit `budget.maxTokens`. The caller's API will reject if
+     * the result exceeds the model's context window — the philosophy is
+     * "surface the overage rather than silently lose content."
+     *
+     * Default: true (legacy budget-aware truncation: stops emitting recall
+     * pairs and recent messages when the running total exceeds maxTokens).
+     *
+     * Recommended setting for long-lived agents on large-context models
+     * (e.g. opus-4-7 with 1M context): false. The window is generous enough
+     * that overflow is rare, and when it does happen you want to know.
+     */
+    enforceBudget?: boolean;
+    /**
+     * Enable picker-driven adaptive resolution. When true, `select()` uses
+     * the FoldingStrategy + Picker to choose per-message resolution under
+     * token-budget pressure rather than the threshold-driven `checkMergeThreshold`
+     * path. Default: false (existing hierarchical behavior preserved).
+     */
+    adaptiveResolution?: boolean;
+    /**
+     * Folding strategy name when adaptiveResolution is on. One of:
+     *   'flat-profile' (default) — level-equalizing
+     *   'oldest-first' — chronological
+     * Custom strategies can be plugged in by the host application.
+     */
+    foldingStrategy?: 'flat-profile' | 'oldest-first';
+    /**
+     * Slack ratio (hysteresis) for the picker. The picker folds until total
+     * tokens ≤ budget * (1 - slack), and stays quiet while between slack
+     * and budget. Default 0.1.
+     */
+    compressionSlackRatio?: number;
+    /**
+     * Enable bottom-up speculative pre-production of higher-level summaries.
+     * When a new L_k summary is produced, if N siblings exist that would share
+     * an L_{k+1} parent, the L_{k+1} is enqueued for production immediately
+     * (no picker request needed). Default true when adaptiveResolution is on.
+     */
+    speculativeProduction?: boolean;
 }
 /**
  * Compression level in the hierarchical pyramid.
+ *
+ * Historically constrained to 1 | 2 | 3. As of the adaptive-resolution design
+ * (`docs/adaptive-resolution-design.md`), levels are unbounded: the picker
+ * can recursively produce L4, L5, ... as needed. The narrower literal type
+ * is kept as `LegacySummaryLevel` for code that still assumes the old shape.
  */
-export type SummaryLevel = 1 | 2 | 3;
+export type SummaryLevel = number;
+/**
+ * The narrow level type used by pre-adaptive-resolution code paths.
+ * Prefer `SummaryLevel` for new code.
+ */
+export type LegacySummaryLevel = 1 | 2 | 3;
 /**
  * A summary entry in the hierarchical memory pyramid.
  * L1: compressed from raw message chunks.
- * L2: merged from mergeThreshold L1s.
- * L3: merged from mergeThreshold L2s.
+ * L_{k>1}: merged from mergeThreshold L_{k-1}s.
  */
 export interface SummaryEntry {
     /** Unique ID (e.g., "L1-0", "L2-3") */
     id: string;
-    /** Compression level */
+    /** Compression level (1, 2, 3, ... — unbounded in the adaptive-resolution design) */
     level: SummaryLevel;
     /** The summary text */
     content: string;
-    /** Estimated token count (content.length / 4) */
+    /** Estimated token count (content.length / 4 or tokenizer-cached) */
     tokens: number;
-    /** Level of the sources: 0 = raw messages, 1 = L1s, 2 = L2s */
-    sourceLevel: 0 | 1 | 2;
-    /** IDs of source items (message IDs for L1, summary IDs for L2/L3) */
+    /**
+     * Level of the sources: 0 = raw messages, k = L_k summaries.
+     * Pre-adaptive code uses 0 | 1 | 2; new code may produce higher values.
+     */
+    sourceLevel: number;
+    /** IDs of source items (message IDs for L1, summary IDs for L_{k>1}) */
     sourceIds: string[];
     /** Range of original message IDs covered */
     sourceRange: {
         first: string;
         last: string;
     };
-    /** If merged into a higher-level summary, that summary's ID */
+    /**
+     * The L_{level+1} summary this one is a source for, if produced.
+     * Pure archive metadata in the adaptive-resolution design — display
+     * decisions live on per-chunk `currentResolution`, not here.
+     */
+    parentId?: string;
+    /**
+     * @deprecated Renamed to `parentId` in the adaptive-resolution design.
+     * Kept for read compatibility with chronicles produced by the old
+     * threshold-driven path. New writes should set `parentId` only.
+     */
     mergedInto?: string;
     /** Creation timestamp */
     created: number;
     /** Phase type tag (used by KnowledgeStrategy for asymmetric budget) */
     phaseType?: string;
 }
+/**
+ * Helper: read the parent pointer from a summary, accepting either the
+ * new `parentId` field or the deprecated `mergedInto` alias.
+ */
+export declare function getSummaryParentId(s: SummaryEntry): string | undefined;
+/**
+ * A range of messages protected from compression. Pins keep a span of raw
+ * messages visible at their original position in the rendered context.
+ *
+ * - `kind: 'pin'` — generic protected range (any first/last span).
+ * - `kind: 'document'` — typically a single message containing a body of
+ *   information the agent wants to retain in full; semantically identical
+ *   to a single-message pin, distinguished by metadata for tooling.
+ */
+export interface ProtectedRange {
+    /** Stable id assigned at pin time. */
+    id: string;
+    /** First message id of the protected range (inclusive). */
+    firstMessageId: string;
+    /** Last message id of the protected range (inclusive). */
+    lastMessageId: string;
+    kind: 'pin' | 'document';
+    /** Optional human-readable label. */
+    name?: string;
+    /** Creation timestamp (ms since epoch). */
+    created: number;
+}
 /**
  * Phase type for knowledge extraction workflows.
  */

package/dist/src/types/strategy.d.ts.map

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

package/dist/src/types/strategy.js

@@ -4,6 +4,32 @@
 export function isResettableStrategy(s) {
     return 'resetHeadWindow' in s && typeof s.resetHeadWindow === 'function';
 }
+/** Type guard for strategies that support pins / documents. */
+export function isPinnableStrategy(s) {
+    return ('pinRange' in s &&
+        typeof s.pinRange === 'function' &&
+        'unpin' in s &&
+        typeof s.unpin === 'function');
+}
+/** Type guard for strategies that support search. */
+export function isSearchableStrategy(s) {
+    return ('searchSummaries' in s &&
+        typeof s.searchSummaries === 'function' &&
+        'getSummary' in s &&
+        typeof s.getSummary === 'function');
+}
+/** Type guard for strategies that produce render stats. */
+export function isRenderStatsCapable(s) {
+    return ('getRenderStats' in s &&
+        typeof s.getRenderStats === 'function');
+}
+/**
+ * Helper: read the parent pointer from a summary, accepting either the
+ * new `parentId` field or the deprecated `mergedInto` alias.
+ */
+export function getSummaryParentId(s) {
+    return s.parentId ?? s.mergedInto;
+}
 /**
  * Default configuration for Autobiographical strategy.
  */
@@ -28,5 +54,7 @@ Write naturally, as recollection of what you experienced.`,
     summaryContextLabel: 'What do you remember from earlier?',
     summaryParticipant: 'Claude',
     maxMessageTokens: 0,
+    positionedRecallPairs: true,
+    recallHeaderTemplate: '[Recall {id}]',
 };
 //# sourceMappingURL=strategy.js.map

package/dist/src/types/strategy.js.map

@@ -1 +1 @@
-{"version":3,"file":"strategy.js","sourceRoot":"","sources":["../../../src/types/strategy.ts"],"names":[],"mappings":"AA2HA;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,CAAkB;IACrD,OAAO,iBAAiB,IAAI,CAAC,IAAI,OAAQ,CAAwB,CAAC,eAAe,KAAK,UAAU,CAAC;AACnG,CAAC;AAiID;;GAEG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAA2B;IACrE,iBAAiB,EAAE,IAAI;IACvB,kBAAkB,EAAE,KAAK;IACzB,gBAAgB,EAAE,CAAC;IACnB,sBAAsB,EAAE,IAAI;IAC5B,qBAAqB,EAAE,IAAI;IAC3B,oBAAoB,EAAE,KAAK;IAC3B,mBAAmB,EAAE,qMAAqM;IAC1N,iBAAiB,EAAE;;;;;;;;;0DASqC;IACxD,mBAAmB,EAAE,oCAAoC;IACzD,kBAAkB,EAAE,QAAQ;IAC5B,gBAAgB,EAAE,CAAC;CACpB,CAAC"}
+{"version":3,"file":"strategy.js","sourceRoot":"","sources":["../../../src/types/strategy.ts"],"names":[],"mappings":"AA+KA;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,CAAkB;IACrD,OAAO,iBAAiB,IAAI,CAAC,IAAI,OAAQ,CAAwB,CAAC,eAAe,KAAK,UAAU,CAAC;AACnG,CAAC;AAcD,+DAA+D;AAC/D,MAAM,UAAU,kBAAkB,CAAC,CAAkB;IACnD,OAAO,CACL,UAAU,IAAI,CAAC;QACf,OAAQ,CAAsB,CAAC,QAAQ,KAAK,UAAU;QACtD,OAAO,IAAI,CAAC;QACZ,OAAQ,CAAsB,CAAC,KAAK,KAAK,UAAU,CACpD,CAAC;AACJ,CAAC;AAsCD,qDAAqD;AACrD,MAAM,UAAU,oBAAoB,CAAC,CAAkB;IACrD,OAAO,CACL,iBAAiB,IAAI,CAAC;QACtB,OAAQ,CAAwB,CAAC,eAAe,KAAK,UAAU;QAC/D,YAAY,IAAI,CAAC;QACjB,OAAQ,CAAwB,CAAC,UAAU,KAAK,UAAU,CAC3D,CAAC;AACJ,CAAC;AA6BD,2DAA2D;AAC3D,MAAM,UAAU,oBAAoB,CAAC,CAAkB;IACrD,OAAO,CACL,gBAAgB,IAAI,CAAC;QACrB,OAAQ,CAAgC,CAAC,cAAc,KAAK,UAAU,CACvE,CAAC;AACJ,CAAC;AAiOD;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,CAAe;IAChD,OAAO,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,UAAU,CAAC;AACpC,CAAC;AA+DD;;GAEG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAA2B;IACrE,iBAAiB,EAAE,IAAI;IACvB,kBAAkB,EAAE,KAAK;IACzB,gBAAgB,EAAE,CAAC;IACnB,sBAAsB,EAAE,IAAI;IAC5B,qBAAqB,EAAE,IAAI;IAC3B,oBAAoB,EAAE,KAAK;IAC3B,mBAAmB,EAAE,qMAAqM;IAC1N,iBAAiB,EAAE;;;;;;;;;0DASqC;IACxD,mBAAmB,EAAE,oCAAoC;IACzD,kBAAkB,EAAE,QAAQ;IAC5B,gBAAgB,EAAE,CAAC;IACnB,qBAAqB,EAAE,IAAI;IAC3B,oBAAoB,EAAE,eAAe;CACtC,CAAC"}

package/dist/test/adaptive/branching.test.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Tests that branching a chronicle correctly inherits and diverges
+ * adaptive-resolution state.
+ *
+ * Per the design doc §8 open question #4: "Branching semantics for on-chunk
+ * state. New chronicle branches inherit chunk state at the fork point via
+ * the existing branch-scoped slot model. An agent unfold on branch A does
+ * not leak into branch B."
+ *
+ * Adaptive state lives in two places:
+ *   - On the StoredMessage itself (bodyGroupId, shardIndex, currentResolution,
+ *     lockedByAgent — set at append time, immutable for that record)
+ *   - In strategy state slots (autobio:resolutions, autobio:locks,
+ *     autobio:summaries)
+ *
+ * The chronicle's branch model copy-on-writes the state slots, so the fork
+ * sees state-at-fork-point and can diverge without affecting the parent.
+ */
+export {};
+//# sourceMappingURL=branching.test.d.ts.map

package/dist/test/adaptive/branching.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branching.test.d.ts","sourceRoot":"","sources":["../../../test/adaptive/branching.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}

package/dist/test/adaptive/branching.test.js

@@ -0,0 +1,176 @@
+/**
+ * Tests that branching a chronicle correctly inherits and diverges
+ * adaptive-resolution state.
+ *
+ * Per the design doc §8 open question #4: "Branching semantics for on-chunk
+ * state. New chronicle branches inherit chunk state at the fork point via
+ * the existing branch-scoped slot model. An agent unfold on branch A does
+ * not leak into branch B."
+ *
+ * Adaptive state lives in two places:
+ *   - On the StoredMessage itself (bodyGroupId, shardIndex, currentResolution,
+ *     lockedByAgent — set at append time, immutable for that record)
+ *   - In strategy state slots (autobio:resolutions, autobio:locks,
+ *     autobio:summaries)
+ *
+ * The chronicle's branch model copy-on-writes the state slots, so the fork
+ * sees state-at-fork-point and can diverge without affecting the parent.
+ */
+import { describe, it, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { rmSync, existsSync } from 'node:fs';
+import { ContextManager, AutobiographicalStrategy } from '../../src/index.js';
+const TEST_STORE_PATH = './test-adaptive-branching-store';
+function cleanup() {
+    if (existsSync(TEST_STORE_PATH)) {
+        rmSync(TEST_STORE_PATH, { recursive: true, force: true });
+    }
+}
+function makeMockMembrane() {
+    let callCount = 0;
+    return {
+        complete: async () => {
+            callCount++;
+            return {
+                content: [{ type: 'text', text: `[mock summary #${callCount}]` }],
+            };
+        },
+        get callCount() {
+            return callCount;
+        },
+    };
+}
+describe('AutobiographicalStrategy — branching semantics', () => {
+    before(() => cleanup());
+    after(() => cleanup());
+    beforeEach(() => cleanup());
+    it('fork inherits resolutions at fork point; divergence does not leak back', async () => {
+        const mock = makeMockMembrane();
+        const strategy = new AutobiographicalStrategy({
+            adaptiveResolution: true,
+            targetChunkTokens: 100,
+            recentWindowTokens: 200,
+        });
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+            membrane: mock,
+        });
+        // Build up some history
+        const ids = [];
+        for (let i = 0; i < 20; i++) {
+            ids.push(manager.addMessage('User', [{ type: 'text', text: `Turn ${i}. ` + 'word '.repeat(40) }]));
+        }
+        while (!manager.isReady()) {
+            await manager.tick();
+        }
+        // Force some folds
+        await manager.compile({ maxTokens: 3000, reserveForResponse: 200 });
+        const parentResolutions = new Map(strategy.resolutions);
+        const parentBranchName = manager.store.currentBranch().name;
+        // Fork
+        const forkName = await manager.fork('test-fork');
+        const forkResolutions = new Map(strategy.resolutions);
+        // Fork should inherit parent's resolutions at fork point
+        assert.equal(forkResolutions.size, parentResolutions.size);
+        for (const [id, level] of parentResolutions) {
+            assert.equal(forkResolutions.get(id), level, `fork should inherit resolution for ${id}`);
+        }
+        // Diverge on the fork — add more turns, force deeper folding
+        for (let i = 20; i < 40; i++) {
+            manager.addMessage('User', [{ type: 'text', text: `Fork-only turn ${i}. ` + 'word '.repeat(40) }]);
+        }
+        while (!manager.isReady()) {
+            await manager.tick();
+        }
+        await manager.compile({ maxTokens: 2000, reserveForResponse: 200 });
+        const forkDivergedResolutions = new Map(strategy.resolutions);
+        const forkDivergedMessageCount = manager.getAllMessages().length;
+        // Switch back to parent
+        await manager.switchBranch(parentBranchName);
+        const parentResolutionsAfterSwitch = new Map(strategy.resolutions);
+        const parentMessageCount = manager.getAllMessages().length;
+        // Parent should still have its ORIGINAL state — the fork's divergence
+        // didn't leak back.
+        assert.equal(parentMessageCount, 20, 'parent should still have 20 messages');
+        assert.notEqual(parentMessageCount, forkDivergedMessageCount);
+        assert.equal(parentResolutionsAfterSwitch.size, parentResolutions.size);
+        for (const [id, level] of parentResolutions) {
+            assert.equal(parentResolutionsAfterSwitch.get(id), level, `parent ${id}: expected unchanged resolution L${level} after fork diverged`);
+        }
+        manager.close();
+    });
+    it('locks on fork do not affect parent', async () => {
+        const mock = makeMockMembrane();
+        const strategy = new AutobiographicalStrategy({
+            adaptiveResolution: true,
+            targetChunkTokens: 100,
+        });
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+            membrane: mock,
+        });
+        const ids = [];
+        for (let i = 0; i < 10; i++) {
+            ids.push(manager.addMessage('User', [{ type: 'text', text: `M${i}` }]));
+        }
+        const parentBranch = manager.store.currentBranch().name;
+        await manager.fork('lock-fork');
+        // Lock on the fork
+        strategy.lockChunk(ids[3]);
+        strategy.lockChunk(ids[7]);
+        const forkLocks = new Set(strategy.locked);
+        assert.equal(forkLocks.size, 2);
+        // Switch back to parent — locks should be empty
+        await manager.switchBranch(parentBranch);
+        const parentLocks = strategy.locked;
+        assert.equal(parentLocks.size, 0, 'parent should not see fork-only locks');
+        // Switch back to fork — locks should still be there
+        await manager.switchBranch('lock-fork');
+        const forkLocksAfter = strategy.locked;
+        assert.equal(forkLocksAfter.size, 2);
+        assert.ok(forkLocksAfter.has(ids[3]));
+        assert.ok(forkLocksAfter.has(ids[7]));
+        manager.close();
+    });
+    it('summaries on fork do not affect parent', async () => {
+        const mock = makeMockMembrane();
+        const strategy = new AutobiographicalStrategy({
+            adaptiveResolution: true,
+            targetChunkTokens: 80,
+            mergeThreshold: 3,
+            recentWindowTokens: 50,
+        });
+        const manager = await ContextManager.open({
+            path: TEST_STORE_PATH,
+            strategy,
+            membrane: mock,
+        });
+        // Build enough for some summaries
+        for (let i = 0; i < 20; i++) {
+            manager.addMessage('User', [{ type: 'text', text: `T${i}. ` + 'word '.repeat(20) }]);
+        }
+        while (!manager.isReady()) {
+            await manager.tick();
+        }
+        const parentSummaryCount = strategy.summaries.length;
+        const parentBranch = manager.store.currentBranch().name;
+        // Fork and add more content → more summaries on fork only
+        await manager.fork('sum-fork');
+        for (let i = 20; i < 50; i++) {
+            manager.addMessage('User', [{ type: 'text', text: `T${i}. ` + 'word '.repeat(20) }]);
+        }
+        while (!manager.isReady()) {
+            await manager.tick();
+        }
+        const forkSummaryCount = strategy.summaries.length;
+        assert.ok(forkSummaryCount > parentSummaryCount, `fork should have more summaries (${forkSummaryCount}) than parent (${parentSummaryCount})`);
+        // Switch back to parent
+        await manager.switchBranch(parentBranch);
+        const parentSummaryCountAfter = strategy.summaries.length;
+        assert.equal(parentSummaryCountAfter, parentSummaryCount, `parent should still have ${parentSummaryCount} summaries after fork diverged`);
+        manager.close();
+    });
+});
+//# sourceMappingURL=branching.test.js.map

package/dist/test/adaptive/branching.test.js.map

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

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

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=chunker.test.d.ts.map