@animalabs/context-manager 0.5.4 → 0.5.9

package/dist/src/adaptive/kv-control.d.ts

@@ -1,22 +1,31 @@
 /**
- * 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.
  */
@@ -29,8 +38,11 @@ export declare const PRICE: {
     readonly cacheRead: 0.1;
     readonly cacheWrite: 1.25;
 };
-/** Deepest fold level the saliency field will ever allow. */
-export declare 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 declare const MAX_FOLD_LEVEL = 8;
 export interface ControlOptions {
     /** Physical context window — the ONLY hard wall. */
     windowTokens: number;
@@ -95,7 +107,7 @@ export interface ControlResult {
  * 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 declare function foldDepthCap(chunk: PickerChunk, now: number, flatZone: ReadonlySet<ChunkId>, flatZoneChunks: number, mergeThreshold: number): number;
+export declare function foldDepthCap(chunk: PickerChunk, now: number, flatZone: ReadonlySet<ChunkId>, flatZoneChunks: number, mergeThreshold: number, maxLevel?: number): number;
 export interface ControlPlanParams {
     /** Carried frontier (F_prev). */
     previous: ReadonlyMap<ChunkId, number>;
@@ -107,15 +119,39 @@ export interface ControlPlanParams {
     expandAtTokens?: number;
     /** The attractor both fold and un-fold aim for (soft target). */
     targetTokens: number;
-    /** Hard wall W — fold past the reach cap only to keep under this. */
+    /** Hard wall W — the only hard constraint (§13.2). */
     windowTokens: number;
-    /** Per-turn divergence reach (perturbation cap P) — bounds BOTH fold and
-     *  un-fold divergence. Default = windowTokens. */
+    /** Trust region P on per-turn perturbation, in tokens the provider would
+     *  re-read (exact `kvCost`, not a spatial gate). Within P the solver adopts
+     *  the ideal cut outright; beyond it it adopts the ideal's newest changes
+     *  only (suffix adoption) unless an override fires (§13.4). Default =
+     *  windowTokens (a rendered layout never exceeds W, so the default trust
+     *  region never binds). */
     reachTokens?: number;
+    /** Quality-gap override threshold (§13.4): a plan within P is rejected — and
+     *  the ideal adopted, paying the perturbation — when its relevance loss
+     *  exceeds the ideal's by more than this fraction of the ideal's loss.
+     *  Also bounds how misallocated a dead-band hold may be before the solver
+     *  self-heals. Default 0.35. */
+    qualityGapRatio?: number;
     /** Chunks forced to raw and never folded (flat zone / head / tail / pinned). */
     rawZone: ReadonlySet<ChunkId>;
     /** Chunks kept at their carried resolution and never touched (locked). */
     frozen?: ReadonlySet<ChunkId>;
+    /**
+     * V2 pin-at-level-k: chunks fixed to render at EXACTLY the given fold level
+     * (0 = raw). Held there and never folded or un-folded — the frontier cut
+     * passes through that L_k node. A level deeper than the tree has produced is
+     * clamped to the deepest available. (`ProtectedRange.level`.)
+     */
+    fixedLevels?: ReadonlyMap<ChunkId, number>;
+    /**
+     * V2 pin-max-level: per-chunk HARD cap on fold depth — the chunk may fold no
+     * deeper than this level, enforced in normal AND emergency shedding, and any
+     * carried resolution deeper than the cap is un-folded to it at plan start.
+     * (`ProtectedRange.maxLevel`.)
+     */
+    pinCaps?: ReadonlyMap<ChunkId, number>;
     /** Newest source sequence — the age reference for the log-age fold caps. */
     now: number;
     /** Base-k summary grouping. Default 6. */
@@ -128,20 +164,35 @@ export interface ControlPlan {
     folded: boolean;
     /** An un-fold (raise toward raw, to use budget headroom) happened this turn. */
     expanded: boolean;
-    /** Even full folding under caps could not fit under W (terminal). */
+    /** Even full folding could not fit under W (terminal — production problem). */
     escalated: boolean;
+    /** Exact prefix-invalidation cost of this plan vs the carried frontier:
+     *  tokens the provider will re-read (0 on a hold/pure-append turn). */
+    perturbation: number;
+    /** Set when the trust region P did not bind normally (§13.4). Callers should
+     *  log these loudly (`[kv-escalation]`):
+     *  - 'bootstrap': no carried frontier — pure relevance solve, P not applicable;
+     *  - 'infeasible': nothing within P fits under W — feasibility beats P;
+     *  - 'quality-gap': the best plan within P was certifiably bad vs the ideal. */
+    override?: 'bootstrap' | 'infeasible' | 'quality-gap';
 }
 /**
- * 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 declare function planControlledFrontier(inputs: PickerInputs, tree: SummaryTree, p: ControlPlanParams): ControlPlan;
 /**

package/dist/src/adaptive/kv-control.d.ts.map

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