@animalabs/context-manager 0.5.3 → 0.5.5

package/dist/test/adaptive/kv-replay.test.js

@@ -0,0 +1,112 @@
+/**
+ * Tests for session replay (kv-replay.ts) — the flat-profile BASELINE replay.
+ *
+ * Load-bearing properties:
+ *  - deterministic: same inputs → identical ReplayResult;
+ *  - growth is monotonic (visible chunks never shrink) and the cold start has
+ *    no cache;
+ *  - the availability rule holds: never folds a chunk to a level whose summary
+ *    couldn't exist yet (lastSequence > now);
+ *  - per-step bounds: 0 ≤ recomputed ≤ rendered, hitRate ∈ [0, 1];
+ *  - the controller (replayControlled) is no worse than the flat baseline on
+ *    average per-turn perturbation under the same budget.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { SummaryTree } from '../../src/adaptive/summary-tree.js';
+import { replaySession } from '../../src/adaptive/kv-replay.js';
+import { replayControlled } from '../../src/adaptive/kv-control.js';
+import { buildChronicleWithChain } from './harness.js';
+function inputsOf(ch) {
+    return {
+        chunks: ch.chunks,
+        summaries: ch.summaries,
+        recallPairTokens: ch.recallPairTokens,
+        headTokens: 0,
+        tailTokens: 0,
+        headChunkIds: new Set(),
+        tailChunkIds: new Set(),
+    };
+}
+/** A session big enough that a fixed cap forces folding partway through. */
+function session() {
+    const ch = buildChronicleWithChain({
+        chunkCount: 72, tokensPerChunk: 1000, mergeThreshold: 6, recallPairTokens: 200,
+    });
+    return inputsOf(ch);
+}
+const COMMON = {
+    budgetTokens: 24_000, // 72k raw will blow past this → folding kicks in
+    markerCount: 4,
+    rawTailTokens: 4_000,
+};
+test('replay is deterministic', () => {
+    const inputs = session();
+    assert.deepEqual(replaySession(inputs, COMMON), replaySession(inputs, COMMON));
+});
+test('growth is monotonic and the cold start has no cache', () => {
+    const r = replaySession(session(), COMMON);
+    assert.ok(r.steps.length > 1);
+    assert.equal(r.steps[0].cachedTokens, 0, 'first step is a cold cache');
+    assert.equal(r.steps[0].recomputedTokens, r.steps[0].renderedTokens);
+    for (let i = 1; i < r.steps.length; i++) {
+        assert.ok(r.steps[i].numChunks >= r.steps[i - 1].numChunks, 'visible chunks never shrink');
+        assert.ok(r.steps[i].now >= r.steps[i - 1].now, 'now advances');
+    }
+});
+test('per-step bounds: 0 ≤ recomputed ≤ rendered, hitRate ∈ [0,1]', () => {
+    const r = replaySession(session(), COMMON);
+    for (const s of r.steps) {
+        assert.ok(s.recomputedTokens >= 0 && s.recomputedTokens <= s.renderedTokens, 'recompute in range');
+        assert.ok(s.cachedTokens >= 0, 'cached ≥ 0');
+        assert.equal(s.cachedTokens + s.recomputedTokens, s.renderedTokens, 'cached + recompute = rendered');
+        assert.ok(s.hitRate >= 0 && s.hitRate <= 1, 'hitRate in [0,1]');
+    }
+    assert.ok(r.overallHitRate >= 0 && r.overallHitRate <= 1);
+});
+test('availability rule: never folds to a level that does not exist yet', () => {
+    const inputs = session();
+    const tree = new SummaryTree(inputs);
+    const maxAvailableLevel = (now) => {
+        let max = 0;
+        for (const s of tree.allSummaries()) {
+            if (s.lastSequence >= 0 && s.lastSequence <= now && s.level > max)
+                max = s.level;
+        }
+        return max;
+    };
+    const r = replaySession(inputs, COMMON);
+    let sawDeep = false;
+    for (const s of r.steps) {
+        assert.ok(s.deepestLevel <= maxAvailableLevel(s.now), `step now=${s.now}: folded to L${s.deepestLevel} but only L${maxAvailableLevel(s.now)} available`);
+        if (maxAvailableLevel(s.now) >= 2)
+            sawDeep = true;
+    }
+    assert.ok(sawDeep, 'fixture should expose L2+ summaries by the end');
+});
+test('controller (kv-stable) is no worse than the flat baseline on average per-turn perturbation', () => {
+    const inputs = session();
+    const flat = replaySession(inputs, COMMON);
+    const kv = replayControlled(inputs, {
+        windowTokens: 60_000,
+        budgetTokens: COMMON.budgetTokens,
+        attendedWindowTokens: COMMON.rawTailTokens,
+        markerCount: COMMON.markerCount,
+        targetSteps: 120,
+    });
+    // Per-turn perturbation for the flat baseline (recompute beyond new content).
+    const flatRms = (() => {
+        let prevNow = -1, sumsq = 0;
+        for (const s of flat.steps) {
+            const newContent = inputs.chunks
+                .filter((c) => c.sequence > prevNow && c.sequence <= s.now)
+                .reduce((a, c) => a + c.rawTokens, 0);
+            const p = Math.max(0, s.recomputedTokens - newContent);
+            sumsq += p * p;
+            prevNow = s.now;
+        }
+        return Math.sqrt(sumsq / flat.steps.length);
+    })();
+    assert.ok(kv.rmsPerturbation <= flatRms * 1.05, `controller RMS perturbation ${kv.rmsPerturbation.toFixed(0)} ≤ flat ${flatRms.toFixed(0)} (×1.05)`);
+});
+//# sourceMappingURL=kv-replay.test.js.map

package/dist/test/adaptive/kv-replay.test.js.map

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

package/dist/test/adaptive/kv-stable-strategy.test.d.ts

@@ -0,0 +1,10 @@
+/**
+ * End-to-end: KvStableStrategy driven through the real Picker.run loop.
+ *
+ * Asserts the controller policy works as a drop-in FoldingStrategy: the picker
+ * walks to exactly the planned frontier, the result fits the budget, pins/locks
+ * are honored, and the same `planControlledFrontier` the replay harness measures
+ * is what the picker reaches.
+ */
+export {};
+//# sourceMappingURL=kv-stable-strategy.test.d.ts.map

package/dist/test/adaptive/kv-stable-strategy.test.d.ts.map

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

package/dist/test/adaptive/kv-stable-strategy.test.js

@@ -0,0 +1,89 @@
+/**
+ * End-to-end: KvStableStrategy driven through the real Picker.run loop.
+ *
+ * Asserts the controller policy works as a drop-in FoldingStrategy: the picker
+ * walks to exactly the planned frontier, the result fits the budget, pins/locks
+ * are honored, and the same `planControlledFrontier` the replay harness measures
+ * is what the picker reaches.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { Picker } from '../../src/adaptive/picker.js';
+import { SummaryTree } from '../../src/adaptive/summary-tree.js';
+import { renderLayout } from '../../src/adaptive/render-offsets.js';
+import { planControlledFrontier } from '../../src/adaptive/kv-control.js';
+import { KvStableStrategy } from '../../src/adaptive/strategies/kv-stable.js';
+import { buildChronicleWithChain } from './harness.js';
+const BUDGET = (totalBudget, slack = 0.1) => ({
+    totalBudget,
+    targetBudget: totalBudget * (1 - slack),
+    slack,
+});
+function inputsOf(ch) {
+    return {
+        chunks: ch.chunks, summaries: ch.summaries, recallPairTokens: ch.recallPairTokens,
+        headTokens: 0, tailTokens: 0, headChunkIds: new Set(), tailChunkIds: new Set(),
+    };
+}
+function sameMap(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const [k, v] of a)
+        if (b.get(k) !== v)
+            return false;
+    return true;
+}
+test('kv-stable strategy: picker walks to exactly the planned frontier and fits budget', () => {
+    const ch = buildChronicleWithChain({
+        chunkCount: 48, tokensPerChunk: 1000, mergeThreshold: 6, recallPairTokens: 200,
+    });
+    const inputs = inputsOf(ch);
+    const tree = new SummaryTree(inputs);
+    const budget = BUDGET(15_000); // targetBudget 13_500
+    // Independent reference plan (same policy the strategy uses internally).
+    let now = 0;
+    for (const c of inputs.chunks)
+        if (c.sequence > now)
+            now = c.sequence;
+    const plan = planControlledFrontier(inputs, tree, {
+        previous: new Map(), foldAtTokens: budget.totalBudget, expandAtTokens: budget.targetBudget,
+        targetTokens: budget.targetBudget, windowTokens: budget.totalBudget, rawZone: new Set(), now, mergeThreshold: 6,
+    });
+    const strategy = new KvStableStrategy(inputs, {});
+    const result = new Picker(strategy).run(inputs, budget);
+    assert.ok(sameMap(result.finalResolutions, plan.resolutions), 'picker reaches the planned frontier');
+    assert.ok(result.finalTokens <= budget.totalBudget, `fits hard wall: ${result.finalTokens} ≤ 15000`);
+    assert.equal(renderLayout(inputs, tree, result.finalResolutions).totalTokens, result.finalTokens);
+});
+test('kv-stable strategy: converges to null and leaves a small budget untouched', () => {
+    const ch = buildChronicleWithChain({ chunkCount: 8, tokensPerChunk: 500, mergeThreshold: 6, recallPairTokens: 200 });
+    const inputs = inputsOf(ch); // 4k raw
+    const result = new Picker(new KvStableStrategy(inputs, {})).run(inputs, BUDGET(100_000));
+    for (const c of inputs.chunks) {
+        assert.equal(result.finalResolutions.get(c.id), 0, 'nothing folded under a generous budget');
+    }
+});
+test('kv-stable strategy: pinned chunks stay raw, locked chunks keep their resolution', () => {
+    const ch = buildChronicleWithChain({ chunkCount: 48, tokensPerChunk: 1000, mergeThreshold: 6, recallPairTokens: 200 });
+    ch.chunks[2].pinned = true; // old → would otherwise fold
+    ch.chunks[5].lockedByAgent = true;
+    ch.chunks[5].currentResolution = 1; // frozen at L1
+    const inputs = inputsOf(ch);
+    const result = new Picker(new KvStableStrategy(inputs, {})).run(inputs, BUDGET(15_000));
+    assert.equal(result.finalResolutions.get(ch.chunks[2].id), 0, 'pinned chunk stays raw');
+    assert.equal(result.finalResolutions.get(ch.chunks[5].id), 1, 'locked chunk keeps its resolution');
+});
+test('kv-stable strategy: a tighter reach cap holds the deep prefix raw (shallower divergence)', () => {
+    const ch = buildChronicleWithChain({ chunkCount: 60, tokensPerChunk: 1000, mergeThreshold: 6, recallPairTokens: 200 });
+    const inputs = inputsOf(ch);
+    const budget = BUDGET(20_000);
+    const tight = new Picker(new KvStableStrategy(inputs, { reachTokens: 8_000 })).run(inputs, budget);
+    const wide = new Picker(new KvStableStrategy(inputs, { reachTokens: 60_000 })).run(inputs, budget);
+    // Deepest level among the oldest third of chunks: a tight reach can't fold
+    // that far back, so the deep prefix stays shallower (more raw) than with wide.
+    const ordered = [...inputs.chunks].sort((a, b) => a.sequence - b.sequence);
+    const oldThird = ordered.slice(0, 20);
+    const deepest = (r) => Math.max(...oldThird.map((c) => r.finalResolutions.get(c.id) ?? 0));
+    assert.ok(deepest(tight) <= deepest(wide), `tight reach keeps the deep prefix shallower (${deepest(tight)} ≤ ${deepest(wide)})`);
+});
+//# sourceMappingURL=kv-stable-strategy.test.js.map

package/dist/test/adaptive/kv-stable-strategy.test.js.map

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

package/dist/test/adaptive/pin-at-level.test.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Tests for V2 dynamic pins — pin-at-level-k and pin-max-level
+ * (`docs/best-fit-frontier-resolution.md` §7). These extend the classic
+ * pin-as-raw with a fold-depth bound honored by the KV-stable controller:
+ *
+ *  - `fixedLevels` (ProtectedRange.level): the chunk is fixed at EXACTLY level k
+ *    — neither un-folded shallower (even under generous budget) nor folded
+ *    deeper (even under budget pressure);
+ *  - `pinCaps` (ProtectedRange.maxLevel): a HARD cap on fold depth — the chunk
+ *    may render raw..k but never deeper, enforced in normal AND emergency
+ *    shedding, and a carried resolution deeper than the cap is un-folded to it;
+ *  - level clamps to the deepest produced level (can't render at a missing L_k);
+ *  - the KvStableStrategy walks the picker to a pin-at-k target.
+ */
+export {};
+//# sourceMappingURL=pin-at-level.test.d.ts.map

package/dist/test/adaptive/pin-at-level.test.d.ts.map

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

package/dist/test/adaptive/pin-at-level.test.js

@@ -0,0 +1,133 @@
+/**
+ * Tests for V2 dynamic pins — pin-at-level-k and pin-max-level
+ * (`docs/best-fit-frontier-resolution.md` §7). These extend the classic
+ * pin-as-raw with a fold-depth bound honored by the KV-stable controller:
+ *
+ *  - `fixedLevels` (ProtectedRange.level): the chunk is fixed at EXACTLY level k
+ *    — neither un-folded shallower (even under generous budget) nor folded
+ *    deeper (even under budget pressure);
+ *  - `pinCaps` (ProtectedRange.maxLevel): a HARD cap on fold depth — the chunk
+ *    may render raw..k but never deeper, enforced in normal AND emergency
+ *    shedding, and a carried resolution deeper than the cap is un-folded to it;
+ *  - level clamps to the deepest produced level (can't render at a missing L_k);
+ *  - the KvStableStrategy walks the picker to a pin-at-k target.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { SummaryTree } from '../../src/adaptive/summary-tree.js';
+import { planControlledFrontier } from '../../src/adaptive/kv-control.js';
+import { Picker } from '../../src/adaptive/picker.js';
+import { KvStableStrategy } from '../../src/adaptive/strategies/kv-stable.js';
+import { buildChronicleWithChain } from './harness.js';
+function inputsOf(ch) {
+    return {
+        chunks: ch.chunks, summaries: ch.summaries, recallPairTokens: ch.recallPairTokens,
+        headTokens: 0, tailTokens: 0, headChunkIds: new Set(), tailChunkIds: new Set(),
+    };
+}
+// 90 chunks × 1000t = 90k raw; mergeThreshold 6 → 15 L1s → 2 L2s (max level 2).
+// c-0000 has an L1 and an L2 ancestor.
+function session() {
+    const ch = buildChronicleWithChain({ chunkCount: 90, tokensPerChunk: 1000, mergeThreshold: 6, recallPairTokens: 200 });
+    const inputs = inputsOf(ch);
+    return { ch, inputs, tree: new SummaryTree(inputs) };
+}
+const NOW = 89;
+test('pin-at-level-k: fixed at exactly k under BOTH generous and tight budgets', () => {
+    const { tree, inputs } = session();
+    const pinned = 'c-0000';
+    // Group-consistent pin: the whole L2 node covering c-0000 is fixed at L2 (an
+    // L2 recall pair is atomic over its range — this is what the strategy expands
+    // a single-chunk pin-at-k into).
+    const node = tree.ancestorAt(pinned, 2);
+    const fixedLevels = new Map(node.leafChunkIds.map((id) => [id, 2]));
+    const outside = 'c-0040'; // in the OTHER L2 group → free to move
+    assert.ok(!node.leafChunkIds.includes(outside), 'neighbor is outside the pinned node');
+    // Generous budget → the controller un-folds everything toward raw to use
+    // headroom. The pinned node must stay at L2 (NOT un-folded to raw).
+    const loose = planControlledFrontier(inputs, tree, {
+        previous: new Map(fixedLevels),
+        foldAtTokens: 200_000, expandAtTokens: 200_000, targetTokens: 200_000,
+        windowTokens: 200_000, rawZone: new Set(), fixedLevels, now: NOW, mergeThreshold: 6,
+    });
+    assert.equal(loose.resolutions.get(pinned), 2, 'pinned held at L2 under generous budget (not un-folded)');
+    assert.equal(loose.resolutions.get(outside), 0, 'un-pinned old chunk un-folds to raw');
+    // Tight budget → the controller folds the middle deep. The pinned node must
+    // still be EXACTLY L2 (not folded deeper — no L3 exists — and not shallower).
+    const tight = planControlledFrontier(inputs, tree, {
+        previous: new Map(),
+        foldAtTokens: 12_000, expandAtTokens: 0, targetTokens: 12_000,
+        windowTokens: 90_000, rawZone: new Set(), fixedLevels, now: NOW, mergeThreshold: 6,
+    });
+    assert.equal(tight.resolutions.get(pinned), 2, 'pinned fixed at L2 under tight budget');
+});
+test('pin-at-level clamps to the deepest produced level (no phantom L_k)', () => {
+    const { tree, inputs } = session();
+    const pinned = 'c-0000';
+    // Ask for L5, which does not exist (max is L2) → clamp to L2.
+    const r = planControlledFrontier(inputs, tree, {
+        previous: new Map(),
+        foldAtTokens: 12_000, expandAtTokens: 0, targetTokens: 12_000,
+        windowTokens: 90_000, rawZone: new Set(), fixedLevels: new Map([[pinned, 5]]),
+        now: NOW, mergeThreshold: 6,
+    });
+    assert.equal(r.resolutions.get(pinned), 2, 'clamped to the deepest available level (L2)');
+});
+test('pin-max-level: a HARD fold-depth cap, enforced even under the W emergency', () => {
+    const { tree, inputs } = session();
+    const capped = 'c-0006'; // in the second L1 group (L1-1 → L2-0)
+    const pinCaps = new Map([[capped, 1]]); // never fold deeper than L1
+    // Very tight target: folding everything to L1 (15 groups × 200 = 3000t) does
+    // NOT fit, so the controller must fold to L2 — forcing the deepest available
+    // level. The capped chunk must still never exceed L1 (a pin is hard-protected).
+    const r = planControlledFrontier(inputs, tree, {
+        previous: new Map(),
+        foldAtTokens: 1_500, expandAtTokens: 0, targetTokens: 1_200,
+        windowTokens: 2_000, rawZone: new Set(), pinCaps, now: NOW, mergeThreshold: 6,
+    });
+    assert.ok((r.resolutions.get(capped) ?? 0) <= 1, `capped chunk never folds past L1 (got L${r.resolutions.get(capped)})`);
+    // An un-capped neighbor in a DIFFERENT L2 group is free to fold to L2 under
+    // the same pressure (a chunk sharing the capped chunk's L2 node would be held
+    // by group-consistency, which is correct — so pick one outside it).
+    assert.ok((r.resolutions.get('c-0040') ?? 0) >= 2, 'un-capped neighbor folds deeper');
+});
+test('pin-max-level un-folds a carried resolution deeper than the cap (on pin-add)', () => {
+    const { tree, inputs } = session();
+    const capped = 'c-0006';
+    // F_prev has it deep at L2; adding maxLevel:1 must un-fold it to L1 immediately,
+    // even though the render is comfortably under budget (dead band).
+    const r = planControlledFrontier(inputs, tree, {
+        previous: new Map([[capped, 2]]),
+        foldAtTokens: 200_000, expandAtTokens: 0, targetTokens: 200_000,
+        windowTokens: 200_000, rawZone: new Set(), pinCaps: new Map([[capped, 1]]),
+        now: NOW, mergeThreshold: 6,
+    });
+    assert.equal(r.resolutions.get(capped), 1, 'carried L2 clamped down to the L1 cap at plan start');
+});
+test('KvStableStrategy walks the picker to a pin-at-level-k target', () => {
+    const { ch, inputs } = session();
+    // Pin c-0000 at L2 via the PickerChunk field the strategy reads.
+    const target = ch.chunks.find((c) => c.id === 'c-0000');
+    target.pinLevel = 2;
+    target.currentResolution = 0; // starts raw → must be raised to L2
+    const picker = new Picker(new KvStableStrategy(inputs));
+    const result = picker.run(inputs, { totalBudget: 12_000, targetBudget: 10_000, slack: 0 });
+    assert.equal(result.finalResolutions.get('c-0000'), 2, 'picker walked the pinned chunk to exactly L2');
+});
+test('pinned-at-level render survives a full budget sweep (no oscillation)', () => {
+    const { tree, inputs } = session();
+    const pinned = 'c-0000';
+    const l1 = tree.ancestorAt(pinned, 1);
+    const fixedLevels = new Map(l1.leafChunkIds.map((id) => [id, 1]));
+    let prev = new Map();
+    for (const budget of [12_000, 40_000, 90_000, 40_000, 12_000]) {
+        const r = planControlledFrontier(inputs, tree, {
+            previous: prev,
+            foldAtTokens: budget, expandAtTokens: budget * 0.9, targetTokens: budget * 0.9,
+            windowTokens: 90_000, rawZone: new Set(), fixedLevels, now: NOW, mergeThreshold: 6,
+        });
+        assert.equal(r.resolutions.get(pinned), 1, `pinned held at L1 at budget ${budget}`);
+        prev = r.resolutions;
+    }
+});
+//# sourceMappingURL=pin-at-level.test.js.map

package/dist/test/adaptive/pin-at-level.test.js.map

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

package/dist/test/adaptive/render-offsets.test.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Tests for render-offsets — the rendered-unit layout + KV-cost accounting.
+ *
+ * Two things matter:
+ *  1. `renderLayout().totalTokens` must equal the picker's own computeTokens
+ *     model (parity), so the KV term is computed over the real render.
+ *  2. KV cost must be position-aware: a change deep in the old prefix costs far
+ *     more than a change near the tail — the whole reason for the term.
+ */
+export {};
+//# sourceMappingURL=render-offsets.test.d.ts.map

package/dist/test/adaptive/render-offsets.test.d.ts.map

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

package/dist/test/adaptive/render-offsets.test.js

@@ -0,0 +1,85 @@
+/**
+ * Tests for render-offsets — the rendered-unit layout + KV-cost accounting.
+ *
+ * Two things matter:
+ *  1. `renderLayout().totalTokens` must equal the picker's own computeTokens
+ *     model (parity), so the KV term is computed over the real render.
+ *  2. KV cost must be position-aware: a change deep in the old prefix costs far
+ *     more than a change near the tail — the whole reason for the term.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { Picker } from '../../src/adaptive/picker.js';
+import { FlatProfileStrategy } from '../../src/adaptive/strategies/flat-profile.js';
+import { SummaryTree } from '../../src/adaptive/summary-tree.js';
+import { renderLayout, kvCost, earliestDivergenceIndex, } from '../../src/adaptive/render-offsets.js';
+import { buildChronicleWithChain } from './harness.js';
+const BUDGET = (totalBudget, slack = 0.1) => ({
+    totalBudget,
+    targetBudget: totalBudget * (1 - slack),
+    slack,
+});
+function inputsOf(ch) {
+    // Explicit empty head/tail. (computeHeadTail force-includes one tail chunk
+    // even at tailTokens:0, which would add the tail block to the recomputed
+    // suffix and muddy the position-aware assertion below.)
+    return {
+        chunks: ch.chunks,
+        summaries: ch.summaries,
+        recallPairTokens: ch.recallPairTokens,
+        headTokens: 0,
+        tailTokens: 0,
+        headChunkIds: new Set(),
+        tailChunkIds: new Set(),
+    };
+}
+function frontier(ids, level) {
+    return new Map(ids.map((id) => [id, level]));
+}
+test('render-offsets: totalTokens matches the picker computeTokens model (parity)', () => {
+    const ch = buildChronicleWithChain({
+        chunkCount: 36, tokensPerChunk: 1000, mergeThreshold: 6, recallPairTokens: 200,
+    });
+    const inputs = inputsOf(ch);
+    const result = new Picker(new FlatProfileStrategy()).run(inputs, BUDGET(10_000));
+    assert.ok(result.applied.length > 0, 'expected the picker to fold something');
+    const tree = new SummaryTree(inputs);
+    const layout = renderLayout(inputs, tree, result.finalResolutions);
+    assert.equal(layout.totalTokens, result.finalTokens);
+});
+test('render-offsets: kvCost is zero for an unchanged frontier', () => {
+    const ch = buildChronicleWithChain({
+        chunkCount: 36, tokensPerChunk: 1000, mergeThreshold: 6, recallPairTokens: 200,
+    });
+    const inputs = inputsOf(ch);
+    const tree = new SummaryTree(inputs);
+    const layout = renderLayout(inputs, tree, new Map());
+    assert.equal(kvCost(layout, layout), 0);
+});
+test('render-offsets: deep-old change costs more than a near-tail change (position-aware)', () => {
+    const ch = buildChronicleWithChain({
+        chunkCount: 36, tokensPerChunk: 1000, mergeThreshold: 6, recallPairTokens: 200,
+    });
+    const inputs = inputsOf(ch);
+    const tree = new SummaryTree(inputs);
+    const allRaw = renderLayout(inputs, tree, new Map());
+    const foldOldest = renderLayout(inputs, tree, frontier(['c-0000', 'c-0001', 'c-0002', 'c-0003', 'c-0004', 'c-0005'], 1));
+    const foldNewest = renderLayout(inputs, tree, frontier(['c-0030', 'c-0031', 'c-0032', 'c-0033', 'c-0034', 'c-0035'], 1));
+    const costOld = kvCost(allRaw, foldOldest);
+    const costNew = kvCost(allRaw, foldNewest);
+    assert.ok(costNew < costOld, `near-tail (${costNew}) must cost less than deep-old (${costOld})`);
+    assert.equal(costNew, 200, 'near-tail fold recomputes only the new recall pair');
+});
+test('render-offsets: earliestDivergenceIndex + kvCost prefix semantics', () => {
+    const u = (kind, key, tokens, offset) => ({ kind, key, tokens, offset });
+    const a = [u('head', 'head', 10, 0), u('raw', 'x', 5, 10), u('raw', 'y', 5, 15)];
+    const same = [u('head', 'head', 10, 0), u('raw', 'x', 5, 10), u('raw', 'y', 5, 15)];
+    assert.equal(earliestDivergenceIndex(a, same), -1);
+    const prefix = [u('head', 'head', 10, 0), u('raw', 'x', 5, 10)]; // strict prefix of a
+    assert.equal(earliestDivergenceIndex(a, prefix), 2);
+    assert.equal(kvCost({ units: a, totalTokens: 20 }, { units: prefix, totalTokens: 15 }), 0);
+    const diff = [u('head', 'head', 10, 0), u('raw', 'z', 5, 10), u('raw', 'y', 5, 15)];
+    assert.equal(earliestDivergenceIndex(a, diff), 1);
+    assert.equal(kvCost({ units: a, totalTokens: 20 }, { units: diff, totalTokens: 20 }), 10); // 20 − offset@1
+});
+//# sourceMappingURL=render-offsets.test.js.map

package/dist/test/adaptive/render-offsets.test.js.map

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

package/dist/test/adaptive/summary-tree.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Tests for SummaryTree — the structural view the V2 best-fit DP walks.
+ */
+export {};
+//# sourceMappingURL=summary-tree.test.d.ts.map

package/dist/test/adaptive/summary-tree.test.d.ts.map

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

package/dist/test/adaptive/summary-tree.test.js

@@ -0,0 +1,72 @@
+/**
+ * Tests for SummaryTree — the structural view the V2 best-fit DP walks.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { SummaryTree, nodeTokens } from '../../src/adaptive/summary-tree.js';
+import { MockChronicle, buildChronicleWithChain } from './harness.js';
+function inputsOf(chronicle) {
+    const ht = chronicle.computeHeadTail({ headTokens: 0, tailTokens: 0 });
+    return {
+        chunks: chronicle.chunks,
+        summaries: chronicle.summaries,
+        recallPairTokens: chronicle.recallPairTokens,
+        ...ht,
+    };
+}
+test('summary-tree: two L1s, no L2 — roots are the L1 summaries', () => {
+    const ch = buildChronicleWithChain({
+        chunkCount: 12,
+        tokensPerChunk: 100,
+        mergeThreshold: 6,
+        recallPairTokens: 200,
+    });
+    const tree = new SummaryTree(inputsOf(ch));
+    assert.equal(tree.ancestorAt('c-0000', 1)?.id, 'L1-0');
+    assert.equal(tree.ancestorAt('c-0000', 2), null, 'no L2 produced');
+    assert.equal(tree.maxLevel('c-0000'), 1);
+    assert.deepEqual(tree.leavesUnder('L1-0'), [
+        'c-0000', 'c-0001', 'c-0002', 'c-0003', 'c-0004', 'c-0005',
+    ]);
+    assert.equal(tree.recallTokens('L1-0'), 200);
+    const roots = tree.roots();
+    assert.deepEqual(roots.map((r) => (r.kind === 'summary' ? r.id : r.chunkId)), ['L1-0', 'L1-1']);
+    const l1 = tree.summary('L1-0');
+    const kids = tree.children(l1);
+    assert.equal(kids.length, 6);
+    assert.ok(kids.every((k) => k.kind === 'leaf'));
+    assert.equal(nodeTokens(l1), 200);
+    assert.equal(nodeTokens(kids[0]), 100);
+});
+test('summary-tree: full L1→L2 chain — single L2 root with summary children', () => {
+    const ch = buildChronicleWithChain({
+        chunkCount: 36,
+        tokensPerChunk: 100,
+        mergeThreshold: 6,
+        recallPairTokens: 200,
+    });
+    const tree = new SummaryTree(inputsOf(ch));
+    assert.equal(tree.ancestorAt('c-0000', 1)?.id, 'L1-0');
+    assert.equal(tree.ancestorAt('c-0000', 2)?.id, 'L2-0');
+    assert.equal(tree.maxLevel('c-0000'), 2);
+    const roots = tree.roots();
+    assert.equal(roots.length, 1);
+    assert.equal(roots[0].kind, 'summary');
+    assert.equal(roots[0].id, 'L2-0');
+    assert.equal(tree.leavesUnder('L2-0').length, 36);
+    const kids = tree.children(tree.summary('L2-0'));
+    assert.equal(kids.length, 6);
+    assert.ok(kids.every((k) => k.kind === 'summary'));
+});
+test('summary-tree: an uncovered leaf is its own root at level 0', () => {
+    const ch = new MockChronicle({ mergeThreshold: 6, recallPairTokens: 200 });
+    ch.addChunk({ id: 'a', rawTokens: 100 });
+    ch.addChunk({ id: 'b', rawTokens: 100 });
+    ch.produceL1(['a']); // only 'a' is covered
+    const tree = new SummaryTree(inputsOf(ch));
+    assert.equal(tree.maxLevel('b'), 0);
+    assert.equal(tree.ancestorAt('b', 1), null);
+    const rootKeys = tree.roots().map((r) => (r.kind === 'summary' ? r.id : r.chunkId));
+    assert.deepEqual(rootKeys, ['L1-0', 'b']); // ordered by source sequence
+});
+//# sourceMappingURL=summary-tree.test.js.map

package/dist/test/adaptive/summary-tree.test.js.map

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

package/dist/test/image-strip-render-stats.test.d.ts

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

package/dist/test/image-strip-render-stats.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-strip-render-stats.test.d.ts","sourceRoot":"","sources":["../../test/image-strip-render-stats.test.ts"],"names":[],"mappings":""}