@animalabs/context-manager 0.5.4 → 0.5.9

package/dist/src/adaptive/kv-control.js

@@ -1,38 +1,50 @@
 /**
- * KV-stable context controller (see `docs/kv-stable-context-control.md`).
+ * KV-stable context controller — the rev 5.0 single-path solve
+ * (see `docs/adaptive-resolution-design.md` §13; supersedes the two-path
+ * fold-within-reach + emergency design of §12, and the older prose in
+ * `docs/kv-stable-context-control.md` where they conflict).
  *
- * A receding-horizon policy that replaces the `value − λ·KVcost` solve. One
- * objective — minimize real billed recompute — under a constraint hierarchy with
- * a single hard wall (the physical window W) and shaped soft constraints
- * (flat zone, perturbation cap, pins/saliency, operating budget). State (the
- * carried frontier + the persistent cache) makes it a controller, not a
- * per-turn solve.
+ * One algorithm per turn, one hard constraint:
  *
- * This prototype uses a hysteresis band [LW, HW] as the controllable operating
- * point on the cost↔continuity frontier:
- *   - append every turn; if rendered tokens exceed HW, shed down to ≤ LW;
- *     otherwise do nothing (pure append → zero perturbation, full cache hit);
- *   - shed oldest-first, leveled (L1 groups, then L2, then L3), each chunk
- *     capped by the saliency field (log-age + flat zone + pins) — base-k
- *     grouping driven by budget, not a fixed clock;
- *   - W is the only hard wall; if folding everything to its cap can't fit under
- *     W, escalate (don't thrash).
+ *   minimize    relevance_loss(F) + perturbation(F, F_prev)   [lexicographic]
+ *   subject to  render(F) ≤ W            — the only physics
+ *               perturbation(F, F_prev) ≤ P   — trust region; overridable
+ *
+ * - The IDEAL CUT is built from scratch each turn by pure relevance: fold in
+ *   salience-then-age priority order, level by level, under the soft shape
+ *   prior (`foldDepthCap`), past it if W demands, never past the hard
+ *   protections (flat zone / pins / locked); then pack youngest-first back
+ *   toward the target. Age/salience-monotone by construction.
+ * - PERTURBATION is exact, not modeled: `kvCost` — the tokens the provider
+ *   will re-read from the earliest layout divergence to the end.
+ * - P (`reachTokens`, re-priced) is a TRUST REGION on per-turn divergence,
+ *   not a spatial eligibility gate. Within it the solver adopts the ideal;
+ *   beyond it it adopts the ideal's newest changes only (suffix adoption —
+ *   perturbation is prefix-based, so partial adoption is exactly a suffix
+ *   cut) and converges over turns, receding-horizon style.
+ * - OVERRIDES (same code path, recorded on the plan, logged by the caller):
+ *   'bootstrap' (no carried frontier — nothing to preserve), 'infeasible'
+ *   (nothing within P fits under W), 'quality-gap' (the best plan within P
+ *   is certifiably bad vs the ideal). There is no emergency path.
  *
  * Pure and deterministic.
  */
 import { SummaryTree } from './summary-tree.js';
-import { renderLayout } from './render-offsets.js';
+import { renderLayout, kvCost } from './render-offsets.js';
 import { placeMarkers, CacheStore } from './kv-cache-sim.js';
 /** Provider price multipliers relative to base input tokens (Anthropic-ish). */
 export const PRICE = { miss: 1.0, cacheRead: 0.1, cacheWrite: 1.25 };
-/** Deepest fold level the saliency field will ever allow. */
-export const MAX_FOLD_LEVEL = 3;
+/** Safety ceiling on saliency fold depth. The *effective* cap is
+ *  `maxAvailableLevel(tree)` (fold only as deep as summaries actually exist),
+ *  which every caller passes in; this constant is just a high sane upper bound so
+ *  L4/L5/… are allowed as the merge pipeline builds them — never a pin at L3. */
+export const MAX_FOLD_LEVEL = 8;
 /**
  * Per-chunk maximum fold depth from the saliency field: flat zone and pins are
  * raw (0); otherwise log-age banded against the base-k geometry. The "finest
  * requirement wins" — this is the cap the shedder may not exceed.
  */
-export function foldDepthCap(chunk, now, flatZone, flatZoneChunks, mergeThreshold) {
+export function foldDepthCap(chunk, now, flatZone, flatZoneChunks, mergeThreshold, maxLevel = MAX_FOLD_LEVEL) {
     if (chunk.pinned || flatZone.has(chunk.id))
         return 0;
     const age = Math.max(0, now - chunk.sequence);
@@ -40,47 +52,174 @@ export function foldDepthCap(chunk, now, flatZone, flatZoneChunks, mergeThreshol
     if (ratio < 1)
         return 0; // just outside the flat zone → still raw
     const band = Math.floor(Math.log(ratio) / Math.log(Math.max(2, mergeThreshold))) + 1;
-    return Math.max(0, Math.min(MAX_FOLD_LEVEL, band));
+    return Math.max(0, Math.min(maxLevel, band));
+}
+/** Deepest summary level that actually exists in the tree (0 if none). The
+ *  fold depth is bounded by this — NOT a hardcoded constant — so the controller
+ *  uses L4/L5… summaries when production has built them (else it floors at L3 and
+ *  refuses deeper summaries that exist; cf. the lab L3-floor-with-L4-present). */
+function maxAvailableLevel(tree) {
+    let m = 0;
+    for (const s of tree.allSummaries())
+        if (s.level > m)
+            m = s.level;
+    return m;
+}
+/** Per-chunk salience: the coefficient on information loss (design §13.3).
+ *  Defaults to 1. Lower = folds earlier and costs less when folded (code-heavy /
+ *  tool-output / externalized content). Never overrides hard protections. */
+function salienceOf(c) {
+    const s = c.salience;
+    if (s === undefined || !Number.isFinite(s))
+        return 1;
+    return Math.min(1, Math.max(0, s));
+}
+/**
+ * Salience-weighted MISALLOCATION loss of a frontier: Σ salience(c) ·
+ * max(0, level(c) − shapeCap(c)) over foldable chunks — the excess fold depth
+ * beyond what the relevance shape prior (log-age band) would assign. Zero for
+ * any cut that folds nothing deeper than its prior; positive exactly where
+ * fidelity is spent in the wrong place. Recency-aware by construction (the
+ * cap grows with age), so an INVERTED profile — recent content deep, ancient
+ * content fine — scores high even when a naive Σ level would tie it with the
+ * correct gradient. Used only to compare cuts of the same tree (quality-gap
+ * tests, §13.4).
+ */
+function relevanceLoss(F, ordered, rawZone, caps) {
+    let loss = 0;
+    for (const c of ordered) {
+        if (rawZone.has(c.id))
+            continue;
+        const lvl = F.get(c.id) ?? 0;
+        if (lvl <= 0)
+            continue;
+        const cap = Math.max(0, caps.get(c.id) ?? 0);
+        if (lvl > cap)
+            loss += salienceOf(c) * (lvl - cap);
+    }
+    return loss;
 }
 /**
- * Deepen `frontier` in place to bring rendered tokens ≤ `target`, leveled
- * (L1 groups, then L2, then L3) and oldest-first *within the reach window*. A
- * chunk is editable this turn only if the raw tokens newer than it are <
- * `reachTokens` — this bounds the divergence depth (and thus the per-turn KV
- * perturbation) to ≈ reach. Each chunk is bounded by its saliency cap;
- * flat-zone/pinned chunks (cap 0) are never touched.
+ * Incremental token accounting for whole-group fold/unfold moves.
  *
- * `reachTokens` is the soft cap P; `windowTokens` is the hard wall W. If folding
- * within reach can't fit under W, reach is lifted (emergency) and folding
- * continues to caps — yielding P minimally to keep W. Returns final tokens.
+ * `renderLayout` is O(n); calling it per accepted fold makes the ideal-cut
+ * construction O(n·folds) ≈ O(n²) — seconds on a 4k-chunk store, paid on
+ * EVERY compile under the single-path solve. The ledger tracks rendered units
+ * (raw shards / recall pairs) as a multiset keyed exactly like renderLayout's
+ * units, so a group fold/unfold is O(group) and `tokens` stays equal to
+ * `renderLayout(...).totalTokens` for the same frontier (both share the
+ * "missing ancestor → raw" fallback; siblings share one recall unit).
  */
-function shedToTarget(frontier, inputs, tree, ordered, caps, target, reachTokens, windowTokens) {
-    // Raw tokens strictly newer than each chunk (its distance from the live end).
-    const newerTokens = new Map();
-    let acc = 0;
-    for (let i = ordered.length - 1; i >= 0; i--) {
-        newerTokens.set(ordered[i].id, acc);
-        acc += ordered[i].rawTokens;
+class TokenLedger {
+    tree;
+    inputs;
+    unitTokens = new Map(); // unitKey → tokens
+    unitRefs = new Map(); // unitKey → leaf count
+    tokens = 0;
+    constructor(tree, inputs, ordered, F) {
+        this.tree = tree;
+        this.inputs = inputs;
+        this.tokens = inputs.headTokens + inputs.tailTokens;
+        for (const c of ordered) {
+            if (inputs.headChunkIds.has(c.id) || inputs.tailChunkIds.has(c.id))
+                continue;
+            const { key, tokens } = this.unitFor(c, F.get(c.id) ?? 0);
+            this.addRef(key, tokens);
+        }
     }
-    const foldWithinReach = (reach) => {
-        for (let level = 1; level <= MAX_FOLD_LEVEL; level++) {
-            for (const c of ordered) {
-                // oldest-first within reach
-                if ((newerTokens.get(c.id) ?? 0) >= reach)
-                    continue;
-                if ((frontier.get(c.id) ?? 0) >= level)
+    /** Unit identity + cost for a leaf at a level — mirrors renderLayout. */
+    unitFor(c, level) {
+        const effective = c.pinned ? 0 : level;
+        if (effective > 0) {
+            const ancestor = this.tree.ancestorAt(c.id, effective);
+            if (ancestor)
+                return { key: `recall:${ancestor.id}`, tokens: ancestor.recallTokens };
+        }
+        return { key: `raw:${c.id}`, tokens: c.rawTokens };
+    }
+    addRef(key, tokens) {
+        const refs = this.unitRefs.get(key) ?? 0;
+        if (refs === 0) {
+            this.unitTokens.set(key, tokens);
+            this.tokens += tokens;
+        }
+        this.unitRefs.set(key, refs + 1);
+    }
+    dropRef(key) {
+        const refs = this.unitRefs.get(key) ?? 0;
+        if (refs <= 1) {
+            this.unitRefs.delete(key);
+            this.tokens -= this.unitTokens.get(key) ?? 0;
+            this.unitTokens.delete(key);
+        }
+        else {
+            this.unitRefs.set(key, refs - 1);
+        }
+    }
+    /** Move one leaf from `fromLevel` to `toLevel`. Callers move whole groups
+     *  (every leaf of the target node), which keeps units exact. */
+    move(c, byId, fromLevel, toLevel) {
+        if (this.inputs.headChunkIds.has(c.id) || this.inputs.tailChunkIds.has(c.id))
+            return;
+        void byId;
+        this.dropRef(this.unitFor(c, fromLevel).key);
+        const next = this.unitFor(c, toLevel);
+        this.addRef(next.key, next.tokens);
+    }
+}
+/**
+ * Build the IDEAL CUT from scratch — pure relevance, no P anywhere (§13.4).
+ *
+ * Fold order is (salience ascending, then oldest-first), level by level, so the
+ * profile is salience/age-monotone by construction: with uniform salience it
+ * reduces to the classic oldest-first shed. Two phases against the shape prior:
+ *   A. fold under the soft `caps` (log-age shape + pin caps) until ≤ target;
+ *   B. if still over W, keep folding past the shape caps (never past the
+ *      hard-protected −1 sentinel or a pin cap) — the prior is a relevance
+ *      shaper, never a feasibility wall;
+ *   C. pack: un-fold youngest-first back toward `target` (accept-if-fit), so
+ *      headroom is spent on the most recent foldable content.
+ * Ends projected to a valid group-consistent tree cut.
+ */
+function relevanceCut(inputs, tree, ordered, base, caps, pinCaps, rawZone, immovable, frozen, fixedLevels, target, windowTokens, maxFoldLevel) {
+    const F = new Map(base);
+    const byId = new Map(ordered.map((c) => [c.id, c]));
+    // Fold priority: cheapest information first — ascending salience, then oldest.
+    const priority = [...ordered].sort((a, b) => {
+        const sa = salienceOf(a);
+        const sb = salienceOf(b);
+        if (sa !== sb)
+            return sa - sb;
+        return a.sequence - b.sequence;
+    });
+    // Incremental accounting: O(group) per move instead of O(n) renderLayout.
+    const _tl = typeof process !== 'undefined' && process.env?.KV_TIMING ? Date.now() : 0;
+    const ledger = new TokenLedger(tree, inputs, ordered, F);
+    if (_tl)
+        console.error(`[kv-timing] ledger-init ${Date.now() - _tl}ms tokens=${ledger.tokens}`);
+    const foldPass = (ignoreShapeCaps, stopAt) => {
+        for (let level = 1; level <= maxFoldLevel; level++) {
+            for (const c of priority) {
+                if (ledger.tokens <= stopAt)
+                    return true;
+                if ((F.get(c.id) ?? 0) >= level)
                     continue;
                 const ancestor = tree.ancestorAt(c.id, level);
                 if (!ancestor)
                     continue; // summary not produced yet → can't fold here
-                // Group-consistency + reach: fold the WHOLE group to `level` only if
-                // every covered leaf permits it (cap ≥ level) and is within reach. The
-                // picker raises whole groups, so a partially-eligible group would be an
-                // unreachable target (it oscillates). A uniform fold keeps the frontier
-                // group-consistent and the picker convergent.
+                // Group-atomicity: fold the WHOLE group to `level` only if every
+                // covered leaf permits it. Hard protections (−1 sentinel: flat zone /
+                // pins / locked) always block; pin-max-level always blocks past its
+                // bound; the soft shape cap blocks only in phase A.
                 let eligible = true;
                 for (const leafId of ancestor.leafChunkIds) {
-                    if ((caps.get(leafId) ?? 0) < level || (newerTokens.get(leafId) ?? 0) >= reach) {
+                    const cap = caps.get(leafId) ?? 0;
+                    const pinCap = pinCaps.get(leafId);
+                    if (pinCap !== undefined && level > pinCap) {
+                        eligible = false;
+                        break;
+                    }
+                    if (ignoreShapeCaps ? cap < 0 : cap < level) {
                         eligible = false;
                         break;
                     }
@@ -88,80 +227,186 @@ function shedToTarget(frontier, inputs, tree, ordered, caps, target, reachTokens
                 if (!eligible)
                     continue;
                 for (const leafId of ancestor.leafChunkIds) {
-                    if ((frontier.get(leafId) ?? 0) < level)
-                        frontier.set(leafId, level);
+                    const leaf = byId.get(leafId);
+                    const from = F.get(leafId) ?? 0;
+                    if (from < level) {
+                        if (leaf)
+                            ledger.move(leaf, byId, from, level);
+                        F.set(leafId, level);
+                    }
                 }
-                if (renderLayout(inputs, tree, frontier).totalTokens <= target)
+                if (ledger.tokens <= stopAt)
                     return true;
             }
         }
         return false;
     };
-    foldWithinReach(reachTokens);
-    let tokens = renderLayout(inputs, tree, frontier).totalTokens;
-    // Hard wall: yield the reach cap (P) only as far as needed to keep under W.
-    if (tokens > windowTokens) {
-        foldWithinReach(Infinity);
-        tokens = renderLayout(inputs, tree, frontier).totalTokens;
+    // Phase A: fold under the shape prior toward the target.
+    if (ledger.tokens > target)
+        foldPass(false, target);
+    // Phase B: the prior yields to W (only hard protections stand).
+    if (ledger.tokens > windowTokens)
+        foldPass(true, target);
+    // Phase C: pack youngest-first back toward the target (skip if infeasible).
+    if (ledger.tokens <= windowTokens && ledger.tokens < target) {
+        for (let level = maxFoldLevel; level >= 1 && ledger.tokens < target; level--) {
+            for (let oi = ordered.length - 1; oi >= 0; oi--) {
+                if (ledger.tokens >= target)
+                    break;
+                const c = ordered[oi]; // youngest-first
+                if ((F.get(c.id) ?? 0) !== level)
+                    continue;
+                if (rawZone.has(c.id) || immovable.has(c.id))
+                    continue;
+                const node = tree.ancestorAt(c.id, level);
+                if (!node)
+                    continue;
+                let eligible = true;
+                for (const leafId of node.leafChunkIds) {
+                    if ((F.get(leafId) ?? 0) !== level || rawZone.has(leafId) || immovable.has(leafId)) {
+                        eligible = false;
+                        break;
+                    }
+                }
+                if (!eligible)
+                    continue;
+                const before = ledger.tokens;
+                for (const leafId of node.leafChunkIds) {
+                    const leaf = byId.get(leafId);
+                    if (leaf)
+                        ledger.move(leaf, byId, level, level - 1);
+                    F.set(leafId, level - 1);
+                }
+                // Accept an un-fold that lands PAST the target when it still gets
+                // CLOSER to it (and stays under W). Merge groups are coarse quanta
+                // (8-15k on production trees); accept-only-if-under-target strands
+                // real headroom un-spent whenever every remaining quantum overshoots
+                // (mythos 2026-07-12: 134k rendered of a 183.6k hard budget). The
+                // target stays the attractor — W stays the only wall (§13.2).
+                const nt = ledger.tokens;
+                const accept = nt <= windowTokens && Math.abs(nt - target) < Math.abs(before - target);
+                if (!accept) {
+                    // moves away from the target (or breaches W) → revert
+                    for (const leafId of node.leafChunkIds) {
+                        const leaf = byId.get(leafId);
+                        if (leaf)
+                            ledger.move(leaf, byId, level - 1, level);
+                        F.set(leafId, level);
+                    }
+                }
+            }
+        }
     }
-    return tokens;
+    const _tp = typeof process !== 'undefined' && process.env?.KV_TIMING ? Date.now() : 0;
+    projectToValidCut(F, tree, ordered, frozen, fixedLevels);
+    if (_tp)
+        console.error(`[kv-timing] cut-projection ${Date.now() - _tp}ms`);
+    // One authoritative render at the end (the ledger tracks it exactly, but the
+    // projection may have moved leaves — recompute once, not per move).
+    const tokens = renderLayout(inputs, tree, F).totalTokens;
+    return { F, tokens };
 }
 /**
- * Raise `frontier` resolution in place (UN-fold toward raw) to fill up to
- * `target`, leveled (L3→L2, L2→L1, L1→raw) and **youngest-first within the reach
- * window** — the mirror image of `shedToTarget`. Un-folding is a prefix
- * perturbation too, so it obeys the same reach cap (bounded divergence) and only
- * lowers whole groups (group-consistent → the picker reaches it via `lower`
- * ops). Youngest-first spends the budget on the most recent foldable content
- * (highest value, shallowest divergence). Stops before exceeding `target`.
- * rawZone/frozen chunks are never touched. Returns final tokens.
+ * Partial adoption of the ideal under the trust region (§13.4): keep `prev`
+ * before a boundary sequence, take `ideal` at and after it. Perturbation is
+ * prefix-based, so the cheapest partial plans are exactly the suffix cuts;
+ * binary-search the oldest boundary whose perturbation stays ≤ P (perturbation
+ * is monotone non-increasing as the boundary moves newer). Each candidate is
+ * projected to a valid cut before costing (mixing two cuts can bisect a group).
  */
-function expandToTarget(frontier, inputs, tree, ordered, target, reachTokens, rawZone, frozen) {
-    const newerTokens = new Map();
-    let acc = 0;
-    for (let i = ordered.length - 1; i >= 0; i--) {
-        newerTokens.set(ordered[i].id, acc);
-        acc += ordered[i].rawTokens;
+function suffixAdopt(inputs, tree, ordered, prev, prevLayout, ideal, frozen, fixedLevels, P) {
+    const changedSeqs = [];
+    for (const c of ordered) {
+        if ((prev.get(c.id) ?? 0) !== (ideal.get(c.id) ?? 0))
+            changedSeqs.push(c.sequence);
     }
-    let tokens = renderLayout(inputs, tree, frontier).totalTokens;
-    for (let level = MAX_FOLD_LEVEL; level >= 1 && tokens < target; level--) {
-        for (let oi = ordered.length - 1; oi >= 0; oi--) {
-            if (tokens >= target)
-                break;
-            const c = ordered[oi]; // youngest-first
-            if ((frontier.get(c.id) ?? 0) !== level)
-                continue;
-            if (rawZone.has(c.id) || frozen.has(c.id))
-                continue;
-            if ((newerTokens.get(c.id) ?? 0) >= reachTokens)
-                continue;
-            const node = tree.ancestorAt(c.id, level);
-            if (!node)
+    const build = (boundary) => {
+        const F = new Map(prev);
+        for (const c of ordered) {
+            if (c.sequence >= boundary)
+                F.set(c.id, ideal.get(c.id) ?? 0);
+        }
+        projectToValidCut(F, tree, ordered, frozen, fixedLevels);
+        const layout = renderLayout(inputs, tree, F);
+        return { F, layout, pert: kvCost(prevLayout, layout) };
+    };
+    if (changedSeqs.length === 0) {
+        const layout = renderLayout(inputs, tree, new Map(prev));
+        return { F: new Map(prev), tokens: layout.totalTokens, perturbation: 0 };
+    }
+    // Binary search: smallest index (oldest boundary) with perturbation ≤ P.
+    let lo = 0;
+    let hi = changedSeqs.length; // hi = adopt nothing (pert 0, always feasible)
+    let best = build(Number.MAX_SAFE_INTEGER);
+    let bestIdx = hi;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        const cand = build(changedSeqs[mid]);
+        if (cand.pert <= P) {
+            best = cand;
+            bestIdx = mid;
+            hi = mid;
+        }
+        else {
+            lo = mid + 1;
+        }
+    }
+    void bestIdx;
+    return { F: best.F, tokens: best.layout.totalTokens, perturbation: best.pert };
+}
+/**
+ * Project a per-chunk frontier onto the nearest VALID TREE CUT (group-consistent).
+ *
+ * A leaf folded to level k renders as part of its L_k ancestor node, and that
+ * node is atomic over its whole covered range — so EVERY leaf under it must share
+ * level k, or the node is unrenderable. The picker walks group-atomic raise/lower
+ * ops, so a frontier that folds only SOME leaves under a node is an unreachable
+ * target: it raises the group (over-folding a sibling), lowers it (under-folding
+ * another), forever — non-convergence (the wedge this fixes).
+ *
+ * Frontiers seeded per-chunk from the carried `previous` frontier can violate
+ * this: as a summary group accretes new raw leaves over turns while older leaves
+ * stay folded, its leaves end up at mixed levels. shed/expand only re-consolidate
+ * groups they actively move; a mixed group sitting in the budget dead-band passes
+ * through untouched. This pass repairs it.
+ *
+ * Shallowest-first: where a group disagrees, UN-fold the folded leaves one level
+ * toward raw (preserving continuity), cascading until every folded leaf's group
+ * is unanimous. Monotone (only lowers) → terminates. Any budget breach from the
+ * extra raw is re-folded whole-group by the shed pass that runs afterward.
+ *
+ * Pinned (`fixedLevels`) and frozen (locked) leaves are already made
+ * group-consistent by the caller (pin-at-level fixes a whole node's leaves), so
+ * they are held here rather than lowered.
+ */
+function projectToValidCut(F, tree, ordered, frozen, fixedLevels) {
+    const maxPasses = (ordered.length + 1) * (maxAvailableLevel(tree) + 2);
+    let changed = true;
+    let pass = 0;
+    while (changed && pass++ < maxPasses) {
+        changed = false;
+        for (const c of ordered) {
+            const lvl = F.get(c.id) ?? 0;
+            if (lvl <= 0)
                 continue;
-            // Lower the WHOLE group to level-1 only if every covered leaf is at this
-            // level and within reach (group-consistent + reach-bounded).
-            let eligible = true;
-            for (const leafId of node.leafChunkIds) {
-                if ((frontier.get(leafId) ?? 0) !== level ||
-                    rawZone.has(leafId) || frozen.has(leafId) ||
-                    (newerTokens.get(leafId) ?? 0) >= reachTokens) {
-                    eligible = false;
-                    break;
+            if (frozen.has(c.id) || fixedLevels.has(c.id))
+                continue; // held; consistent by construction
+            const node = tree.ancestorAt(c.id, lvl);
+            let unanimous = node != null;
+            if (node) {
+                for (const leafId of node.leafChunkIds) {
+                    if ((F.get(leafId) ?? 0) !== lvl) {
+                        unanimous = false;
+                        break;
+                    }
                 }
             }
-            if (!eligible)
-                continue;
-            for (const leafId of node.leafChunkIds)
-                frontier.set(leafId, level - 1);
-            const nt = renderLayout(inputs, tree, frontier).totalTokens;
-            if (nt <= target)
-                tokens = nt; // accept the un-fold
-            else
-                for (const leafId of node.leafChunkIds)
-                    frontier.set(leafId, level); // overshoot → revert
+            if (!unanimous) {
+                F.set(c.id, lvl - 1);
+                changed = true;
+            } // un-fold one level (shallowest-first)
         }
     }
-    return tokens;
 }
 /** Earliest source sequence whose resolution changed `prev → next`. */
 function earliestChangedSequence(prev, next, ordered) {
@@ -199,56 +444,176 @@ function rawTailSet(ordered, tailTokens) {
     return s;
 }
 const EMPTY_SET = new Set();
+const EMPTY_LEVEL_MAP = new Map();
 /**
- * Plan one turn's frontier under the controller policy — shared by the replay
- * harness (`replayControlled`) and `KvStableStrategy`. Carries F_prev forward,
- * holds the raw zone raw and the frozen set fixed, then drives the rendered size
- * toward `targetTokens` from EITHER side, both bounded by the `reachTokens`
- * divergence cap (KV-continuity preserving in both directions):
- *   - over `foldAtTokens`  → deepen, oldest-first, under the log-age saliency
- *     caps, yielding the reach cap only as needed to stay under the hard wall W;
- *   - under `expandAtTokens` → un-fold, youngest-first, to use budget headroom.
- * The [expandAt, foldAt] dead band leaves F_prev untouched (zero perturbation)
- * when already in range. Pure and deterministic.
+ * Plan one turn's frontier — the rev 5.0 single-path solve (§13.4), shared by
+ * the replay harness (`replayControlled`) and `KvStableStrategy`.
+ *
+ *   1. Build the IDEAL CUT from scratch (pure relevance; W the only wall).
+ *   2. No carried frontier → adopt it (bootstrap; P not applicable).
+ *   3. Carried frontier in the [expandAt, foldAt] dead band with a small
+ *      quality gap → hold it (zero perturbation). A LARGE gap falls through:
+ *      a stuck misallocated profile self-heals instead of fossilizing.
+ *   4. Ideal within the trust region P (exact kvCost) → adopt it.
+ *   5. Otherwise adopt the ideal's newest changes only (suffix adoption) if
+ *      that fits W and is not certifiably bad; else adopt the ideal and record
+ *      the override ('infeasible' / 'quality-gap').
+ *
+ * There is no emergency path and no spatial eligibility gate: cache continuity
+ * is priced (and bounded by P) — never a reason a chunk can't move.
+ * Pure and deterministic.
  */
 export function planControlledFrontier(inputs, tree, p) {
     const ordered = [...inputs.chunks].sort((a, b) => a.sequence - b.sequence);
     const frozen = p.frozen ?? EMPTY_SET;
+    const fixedLevels = p.fixedLevels ?? EMPTY_LEVEL_MAP;
+    const pinCaps = p.pinCaps ?? EMPTY_LEVEL_MAP;
     const mergeThreshold = p.mergeThreshold ?? 6;
-    const reach = p.reachTokens ?? p.windowTokens;
+    const P = p.reachTokens ?? p.windowTokens;
     const expandAt = p.expandAtTokens ?? p.targetTokens;
-    const F = new Map();
+    const gapRatio = p.qualityGapRatio ?? 0.35;
+    // Fold as deep as the tree actually goes (L4/L5… when produced), not a constant.
+    const maxFoldLevel = maxAvailableLevel(tree);
+    // Immovable = never folded OR un-folded by the solve: the locked (frozen)
+    // set plus V2 pin-at-level-k chunks (held at their fixed level).
+    const immovable = new Set(frozen);
+    for (const id of fixedLevels.keys())
+        immovable.add(id);
+    // Base = the non-negotiable part of every cut: raw zone raw, pins at their
+    // level, frozen at their carried resolution. Everything else starts raw here;
+    // the carried frontier and the ideal cut both build on this base.
+    const base = new Map();
     for (const c of ordered) {
-        if (p.rawZone.has(c.id))
-            F.set(c.id, 0);
-        else if (frozen.has(c.id))
-            F.set(c.id, p.previous.get(c.id) ?? c.currentResolution);
-        else
-            F.set(c.id, p.previous.get(c.id) ?? 0);
+        if (p.rawZone.has(c.id)) {
+            base.set(c.id, 0);
+        }
+        else if (fixedLevels.has(c.id)) {
+            // Pin-at-k: fix to exactly k, clamped to the deepest produced level for
+            // this chunk (can't render at a level whose summary doesn't exist yet).
+            const k = Math.max(0, fixedLevels.get(c.id));
+            base.set(c.id, k === 0 ? 0 : Math.min(k, tree.maxLevel(c.id)));
+        }
+        else if (frozen.has(c.id)) {
+            base.set(c.id, p.previous.get(c.id) ?? c.currentResolution);
+        }
+        else {
+            base.set(c.id, 0);
+        }
+    }
+    // Carried frontier (F_prev with the base enforced): what is actually
+    // rendered right now, and the reference for perturbation.
+    const carried = new Map(base);
+    let carriedNonEmpty = false;
+    for (const c of ordered) {
+        if (p.rawZone.has(c.id) || fixedLevels.has(c.id) || frozen.has(c.id))
+            continue;
+        // Enforce a pin-max-level immediately: un-fold anything carried deeper than
+        // its cap down to the cap (shallower summaries — its ancestors — are
+        // guaranteed to exist). The intended divergence cost of tightening a pin.
+        let lvl = p.previous.get(c.id) ?? 0;
+        const cap = pinCaps.get(c.id);
+        if (cap !== undefined && lvl > cap)
+            lvl = Math.max(0, cap);
+        carried.set(c.id, lvl);
     }
-    let tokens = renderLayout(inputs, tree, F).totalTokens;
-    const before = tokens;
-    let folded = false;
-    let expanded = false;
-    let escalated = false;
-    if (tokens > p.foldAtTokens) {
-        const flatZoneChunks = p.rawZone.size;
-        const caps = new Map();
+    for (const v of p.previous.values()) {
+        if (v !== 0) {
+            carriedNonEmpty = true;
+            break;
+        }
+    }
+    projectToValidCut(carried, tree, ordered, frozen, fixedLevels);
+    const carriedLayout = renderLayout(inputs, tree, carried);
+    const carriedTokens = carriedLayout.totalTokens;
+    // Shape prior: soft per-chunk depth caps (log-age band + pin caps), with the
+    // −1 sentinel marking the hard-protected set (never folded by anything).
+    const flatZoneChunks = p.rawZone.size;
+    const caps = new Map();
+    for (const c of ordered) {
+        let cap;
+        if (p.rawZone.has(c.id) || immovable.has(c.id)) {
+            cap = -1; // hard-protected sentinel: never folded, W notwithstanding
+        }
+        else {
+            cap = foldDepthCap(c, p.now, p.rawZone, flatZoneChunks, mergeThreshold, maxFoldLevel);
+            const pinCap = pinCaps.get(c.id);
+            if (pinCap !== undefined)
+                cap = Math.min(cap, Math.max(0, pinCap));
+        }
+        caps.set(c.id, cap);
+    }
+    // 1. The ideal cut — pure relevance, no P anywhere.
+    const _t0 = typeof process !== 'undefined' && process.env?.KV_TIMING ? Date.now() : 0;
+    const ideal = relevanceCut(inputs, tree, ordered, base, caps, pinCaps, p.rawZone, immovable, frozen, fixedLevels, p.targetTokens, p.windowTokens, maxFoldLevel);
+    if (_t0)
+        console.error(`[kv-timing] relevanceCut ${Date.now() - _t0}ms idealTokens=${ideal.tokens}`);
+    const idealLayout = renderLayout(inputs, tree, ideal.F);
+    const idealLoss = relevanceLoss(ideal.F, ordered, p.rawZone, caps);
+    const gapCeiling = gapRatio * Math.max(1, idealLoss);
+    const flags = (F) => {
+        let folded = false;
+        let expanded = false;
         for (const c of ordered) {
-            caps.set(c.id, p.rawZone.has(c.id) || frozen.has(c.id)
-                ? 0
-                : foldDepthCap(c, p.now, p.rawZone, flatZoneChunks, mergeThreshold));
+            const prev = carried.get(c.id) ?? 0;
+            const next = F.get(c.id) ?? 0;
+            if (next > prev)
+                folded = true;
+            else if (next < prev)
+                expanded = true;
+            if (folded && expanded)
+                break;
         }
-        tokens = shedToTarget(F, inputs, tree, ordered, caps, p.targetTokens, reach, p.windowTokens);
-        folded = tokens !== before; // a real fold only if it actually changed the render
-        if (tokens > p.windowTokens)
-            escalated = true;
+        return { folded, expanded };
+    };
+    const adoptIdeal = (override) => ({
+        resolutions: ideal.F,
+        tokens: ideal.tokens,
+        ...flags(ideal.F),
+        escalated: ideal.tokens > p.windowTokens,
+        perturbation: kvCost(carriedLayout, idealLayout),
+        ...(override ? { override } : {}),
+    });
+    // 2. Bootstrap: nothing carried → nothing to preserve; pure relevance solve.
+    if (!carriedNonEmpty && p.previous.size === 0)
+        return adoptIdeal('bootstrap');
+    // 3. Dead band with self-heal: hold the carried frontier only when it is
+    //    feasible, in band, AND not certifiably misallocated.
+    const carriedLoss = relevanceLoss(carried, ordered, p.rawZone, caps);
+    const inBand = carriedTokens <= p.foldAtTokens && carriedTokens >= expandAt;
+    if (inBand && carriedTokens <= p.windowTokens && carriedLoss - idealLoss <= gapCeiling) {
+        return {
+            resolutions: carried,
+            tokens: carriedTokens,
+            ...flags(carried), // vs itself → both false unless projection moved it
+            escalated: false,
+            perturbation: 0,
+        };
     }
-    else if (tokens < expandAt) {
-        tokens = expandToTarget(F, inputs, tree, ordered, p.targetTokens, reach, p.rawZone, frozen);
-        expanded = tokens !== before; // a real un-fold only if it actually changed
+    // 4. Within the trust region → adopt the ideal outright.
+    const idealPert = kvCost(carriedLayout, idealLayout);
+    if (idealPert <= P)
+        return adoptIdeal();
+    // 5. Suffix adoption: the ideal's newest changes only, within P.
+    const partial = suffixAdopt(inputs, tree, ordered, carried, carriedLayout, ideal.F, frozen, fixedLevels, P);
+    const partialLoss = relevanceLoss(partial.F, ordered, p.rawZone, caps);
+    // Progress guard: when a shed is REQUIRED (carried over foldAt), a partial
+    // plan that neither reaches the band nor moves at all is not acceptable —
+    // an under-folded profile scores zero misallocation loss, so the quality
+    // gap alone cannot reject "do nothing forever". (P below the physical floor
+    // — the tail that any fold must invalidate — lands here and overrides.)
+    const mustShed = carriedTokens > p.foldAtTokens;
+    const madeProgress = !mustShed || partial.tokens <= p.foldAtTokens || partial.perturbation > 0;
+    if (partial.tokens <= p.windowTokens && partialLoss - idealLoss <= gapCeiling && madeProgress) {
+        return {
+            resolutions: partial.F,
+            tokens: partial.tokens,
+            ...flags(partial.F),
+            escalated: false,
+            perturbation: partial.perturbation,
+        };
     }
-    return { resolutions: F, tokens, folded, expanded, escalated };
+    // Trust region priced out: feasibility or quality demands the ideal.
+    return adoptIdeal(partial.tokens > p.windowTokens ? 'infeasible' : 'quality-gap');
 }
 /**
  * Run the controller over a session (the exported PickerInputs snapshot) as