@animalabs/context-manager 0.5.2 → 0.5.4

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

@@ -12,6 +12,12 @@ export { chunkMessage, DEFAULT_CHUNKER_OPTIONS, type ChunkerOptions, type Shard,
 export type { FoldingStrategy, FoldingState, FoldingBudget, FoldOp, ChunkView, ChunkId, ChunkRange, SummaryId, } from './folding-strategy.js';
 export { FlatProfileStrategy } from './strategies/flat-profile.js';
 export { OldestFirstStrategy } from './strategies/oldest-first.js';
+export { KvStableStrategy, type KvStableOptions } from './strategies/kv-stable.js';
+export { SummaryTree, nodeTokens, type TreeNode, type LeafNode, type SummaryNode, } from './summary-tree.js';
+export { renderLayout, kvCost, earliestDivergenceIndex, type RenderLayout, type RenderedUnit, type Frontier, } from './render-offsets.js';
+export { placeMarkers, evaluateCacheHit, CacheStore, MAX_CACHE_MARKERS, type CacheMarker, type CacheHit, type CacheStoreOptions, type CacheReadResult, } from './kv-cache-sim.js';
+export { replaySession, type ReplayOptions, type ReplayStep, type ReplayResult, } from './kv-replay.js';
+export { replayControlled, planControlledFrontier, foldDepthCap, PRICE, MAX_FOLD_LEVEL, type ControlOptions, type ControlStep, type ControlResult, type ControlPlanParams, type ControlPlan, } from './kv-control.js';
 export { Picker, OverBudgetError, type PickerInputs, type PickerResult, type PickerChunk, } from './picker.js';
 export { concatBodyGroups, placeholderRecallText } from './render.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adaptive/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EACL,YAAY,EACZ,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,KAAK,EACV,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,eAAe,EACf,YAAY,EACZ,aAAa,EACb,MAAM,EACN,SAAS,EACT,OAAO,EACP,UAAU,EACV,SAAS,GACV,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAGnE,OAAO,EACL,MAAM,EACN,eAAe,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/adaptive/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EACL,YAAY,EACZ,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,KAAK,EACV,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC;AAGtB,YAAY,EACV,eAAe,EACf,YAAY,EACZ,aAAa,EACb,MAAM,EACN,SAAS,EACT,OAAO,EACP,UAAU,EACV,SAAS,GACV,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAE,KAAK,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAGnF,OAAO,EACL,WAAW,EACX,UAAU,EACV,KAAK,QAAQ,EACb,KAAK,QAAQ,EACb,KAAK,WAAW,GACjB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,YAAY,EACZ,MAAM,EACN,uBAAuB,EACvB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,QAAQ,GACd,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,iBAAiB,EACjB,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,iBAAiB,EACtB,KAAK,eAAe,GACrB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,YAAY,GAClB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,YAAY,EACZ,KAAK,EACL,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,iBAAiB,EACtB,KAAK,WAAW,GACjB,MAAM,iBAAiB,CAAC;AAGzB,OAAO,EACL,MAAM,EACN,eAAe,EACf,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC"}

package/dist/src/adaptive/index.js

@@ -13,6 +13,14 @@ export { chunkMessage, DEFAULT_CHUNKER_OPTIONS, } from './chunker.js';
 // Concrete strategies
 export { FlatProfileStrategy } from './strategies/flat-profile.js';
 export { OldestFirstStrategy } from './strategies/oldest-first.js';
+export { KvStableStrategy } from './strategies/kv-stable.js';
+// Summary tree + rendered-unit accounting (shared substrate)
+export { SummaryTree, nodeTokens, } from './summary-tree.js';
+export { renderLayout, kvCost, earliestDivergenceIndex, } from './render-offsets.js';
+// KV-cache simulation + session replay (provider-cache stability measurement)
+export { placeMarkers, evaluateCacheHit, CacheStore, MAX_CACHE_MARKERS, } from './kv-cache-sim.js';
+export { replaySession, } from './kv-replay.js';
+export { replayControlled, planControlledFrontier, foldDepthCap, PRICE, MAX_FOLD_LEVEL, } from './kv-control.js';
 // Picker
 export { Picker, OverBudgetError, } from './picker.js';
 // Render helpers

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

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adaptive/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,UAAU;AACV,OAAO,EACL,YAAY,EACZ,uBAAuB,GAIxB,MAAM,cAAc,CAAC;AActB,sBAAsB;AACtB,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAEnE,SAAS;AACT,OAAO,EACL,MAAM,EACN,eAAe,GAIhB,MAAM,aAAa,CAAC;AAErB,iBAAiB;AACjB,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEtE,qEAAqE;AACrE,4EAA4E;AAC5E,qEAAqE"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/adaptive/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,UAAU;AACV,OAAO,EACL,YAAY,EACZ,uBAAuB,GAIxB,MAAM,cAAc,CAAC;AActB,sBAAsB;AACtB,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,gBAAgB,EAAwB,MAAM,2BAA2B,CAAC;AAEnF,6DAA6D;AAC7D,OAAO,EACL,WAAW,EACX,UAAU,GAIX,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,YAAY,EACZ,MAAM,EACN,uBAAuB,GAIxB,MAAM,qBAAqB,CAAC;AAE7B,8EAA8E;AAC9E,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,iBAAiB,GAKlB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,aAAa,GAId,MAAM,gBAAgB,CAAC;AACxB,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,YAAY,EACZ,KAAK,EACL,cAAc,GAMf,MAAM,iBAAiB,CAAC;AAEzB,SAAS;AACT,OAAO,EACL,MAAM,EACN,eAAe,GAIhB,MAAM,aAAa,CAAC;AAErB,iBAAiB;AACjB,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEtE,qEAAqE;AACrE,4EAA4E;AAC5E,qEAAqE"}

package/dist/src/adaptive/kv-cache-sim.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Anthropic-style KV cache simulation over a rendered layout.
+ *
+ * Real providers don't cache "the longest byte-identical prefix" for free — the
+ * Anthropic API honors up to FOUR explicit `cache_control` breakpoints, and on
+ * each request reuses the LONGEST previously-marked prefix that is still
+ * byte-identical to the new prompt. Everything after that match is recomputed
+ * at full input price (`docs/best-fit-frontier-resolution.md` §4).
+ *
+ * This module models that discrete-breakpoint behavior, so the playground can
+ * measure the cache hit a real deployment would actually get — not the
+ * idealized ceiling that `render-offsets.kvCost` computes.
+ *
+ *  - `placeMarkers` chooses ≤N breakpoint positions on a layout (the markers we
+ *    attach to THIS render, written into the cache for FUTURE renders to hit).
+ *  - `CacheStore` is a PERSISTENT, content-keyed cache: each `write` records the
+ *    exact bytes of the marked prefixes (as a content hash + write step), and
+ *    they stay live across turns (subject to a TTL). `read` returns the LONGEST
+ *    live stored prefix that is byte-identical to the current render. This is
+ *    the real provider behaviour: a prefix cached many turns ago is still a hit
+ *    today if it hasn't changed — even if intervening turns diverged and the
+ *    frontier later reverted. A single-turn "compare to the previous render"
+ *    check (see `evaluateCacheHit`) cannot model that, so the replay uses the
+ *    store.
+ *
+ * A marker's `unitIndex` is the number of leading rendered units it caches
+ * (so `unitIndex` ∈ [0, units.length]); `offset` is the cumulative tokens of
+ * that prefix. `unitIndex === units.length` caches the whole render (the
+ * pure-append breakpoint).
+ *
+ * Cache identity: two rendered units are byte-identical iff they share
+ * (kind, key) — the same identity `render-offsets` uses — because a recall unit
+ * keyed by a summary id renders that summary's fixed recall pair, a raw unit
+ * keyed by a chunk id renders that chunk verbatim, and head/tail are fixed
+ * blocks. So a content hash over the unit (kind,key) sequence is a faithful,
+ * deterministic stand-in for the cached bytes.
+ *
+ * Pure and deterministic (no Date/random; the store tracks a logical step clock
+ * advanced by the caller).
+ */
+import { type RenderLayout } from './render-offsets.js';
+/** Maximum cache breakpoints the Anthropic API honors. */
+export declare const MAX_CACHE_MARKERS = 4;
+/** A cache breakpoint: caches the first `unitIndex` rendered units (`offset` tokens). */
+export interface CacheMarker {
+    /** Number of leading units cached by this breakpoint (0 … units.length). */
+    unitIndex: number;
+    /** Cumulative tokens of the cached prefix. */
+    offset: number;
+}
+export interface CacheHit {
+    /** Tokens served from cache in `next` (longest matching marked prefix). */
+    cachedTokens: number;
+    /** Tokens recomputed in `next` (everything after the cached prefix). */
+    recomputedTokens: number;
+    /** cachedTokens / next.totalTokens, in [0, 1]. 0 when next is empty. */
+    hitRate: number;
+    /** unitIndex of the winning marker (−1 if no marker matched → full recompute). */
+    markerUnitIndex: number;
+    /** First unit index at which `next` diverges from `prev` (units.length-style;
+     *  equals the identical-prefix length). */
+    divergenceUnits: number;
+}
+/**
+ * Choose ≤`count` cache breakpoints for `layout`. The placement mirrors real
+ * Anthropic usage and the stable solver's structure:
+ *
+ *  - the END of the render (caches everything → a pure-append next turn is a
+ *    full hit) is always included;
+ *  - the stable-prefix seam (`opts.boundaryUnitIndex`, where the frontier was
+ *    frozen vs F_prev) — the most likely longest-surviving prefix under churn;
+ *  - the HEAD boundary (the fixed system block) when present;
+ *  - remaining budget spent on evenly-spaced tail seams.
+ *
+ * Returns distinct markers sorted by `unitIndex` ascending, capped to
+ * `min(count, MAX_CACHE_MARKERS)`.
+ */
+export declare function placeMarkers(layout: RenderLayout, count: number, opts?: {
+    boundaryUnitIndex?: number;
+}): CacheMarker[];
+/**
+ * SINGLE-TURN cache check: score `next` against the breakpoints we placed on the
+ * IMMEDIATELY PRECEDING render `prev`. The cache serves the longest marked
+ * prefix of `prev` that is still byte-identical to `next`; everything after is
+ * recomputed.
+ *
+ * This is a one-step primitive and intentionally has NO memory beyond `prev` —
+ * it cannot model a prefix cached several turns ago surviving an intervening
+ * divergence. For session replay use {@link CacheStore}, which persists entries
+ * across turns. `prevMarkers` must be markers produced from `prev`. On a cold
+ * start pass an empty `prevMarkers` (no cache → full recompute).
+ */
+export declare function evaluateCacheHit(prev: RenderLayout, prevMarkers: readonly CacheMarker[], next: RenderLayout): CacheHit;
+export interface CacheStoreOptions {
+    /** Entries written more than this many steps ago are evicted before a read
+     *  (models the provider TTL). Default Infinity (keep all — the faithful upper
+     *  bound on reuse). */
+    ttlSteps?: number;
+}
+export interface CacheReadResult {
+    /** Tokens served from cache (longest live stored prefix matching `layout`). */
+    cachedTokens: number;
+    /** Units served from cache (the matched prefix length). */
+    cachedUnits: number;
+    /** How many steps ago the winning entry was written (0 = this step, −1 = miss). */
+    ageSteps: number;
+}
+/**
+ * A persistent provider cache. Holds, per cached prefix length, the set of
+ * content hashes ever written at that length and the step each was last
+ * (re)written. `read` finds the longest live stored prefix byte-identical to
+ * the current render; `write` records the current render's breakpoint prefixes;
+ * `tick` advances the logical turn clock used for TTL and age.
+ */
+export declare class CacheStore {
+    private readonly ttl;
+    /** length → (contentHash → last-written step). */
+    private readonly byLength;
+    private step;
+    constructor(opts?: CacheStoreOptions);
+    /** Longest live cached prefix that is byte-identical to `layout`. */
+    read(layout: RenderLayout): CacheReadResult;
+    /** Record the marked prefixes of `layout` as cache entries at the current step. */
+    write(layout: RenderLayout, markers: readonly CacheMarker[]): void;
+    /** Advance the logical turn clock (call once per replay step, after write). */
+    tick(): void;
+}
+//# sourceMappingURL=kv-cache-sim.d.ts.map

package/dist/src/adaptive/kv-cache-sim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv-cache-sim.d.ts","sourceRoot":"","sources":["../../../src/adaptive/kv-cache-sim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEjF,0DAA0D;AAC1D,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,yFAAyF;AACzF,MAAM,WAAW,WAAW;IAC1B,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,QAAQ;IACvB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,gBAAgB,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,kFAAkF;IAClF,eAAe,EAAE,MAAM,CAAC;IACxB;+CAC2C;IAC3C,eAAe,EAAE,MAAM,CAAC;CACzB;AASD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,MAAM,EACb,IAAI,GAAE;IAAE,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAO,GACxC,WAAW,EAAE,CAsBf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,YAAY,EAClB,WAAW,EAAE,SAAS,WAAW,EAAE,EACnC,IAAI,EAAE,YAAY,GACjB,QAAQ,CAqBV;AA8BD,MAAM,WAAW,iBAAiB;IAChC;;2BAEuB;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,+EAA+E;IAC/E,YAAY,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,kDAAkD;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;IACnE,OAAO,CAAC,IAAI,CAAK;gBAEL,IAAI,GAAE,iBAAsB;IAIxC,qEAAqE;IACrE,IAAI,CAAC,MAAM,EAAE,YAAY,GAAG,eAAe;IAkB3C,mFAAmF;IACnF,KAAK,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,SAAS,WAAW,EAAE,GAAG,IAAI;IAclE,+EAA+E;IAC/E,IAAI,IAAI,IAAI;CAUb"}

package/dist/src/adaptive/kv-cache-sim.js.map

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

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

@@ -0,0 +1,152 @@
+/**
+ * KV-stable context controller (see `docs/kv-stable-context-control.md`).
+ *
+ * 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.
+ *
+ * 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).
+ *
+ * Pure and deterministic.
+ */
+import type { ChunkId } from './folding-strategy.js';
+import type { PickerInputs, PickerChunk } from './picker.js';
+import { SummaryTree } from './summary-tree.js';
+/** Provider price multipliers relative to base input tokens (Anthropic-ish). */
+export declare const PRICE: {
+    readonly miss: 1;
+    readonly cacheRead: 0.1;
+    readonly cacheWrite: 1.25;
+};
+/** Deepest fold level the saliency field will ever allow. */
+export declare const MAX_FOLD_LEVEL = 3;
+export interface ControlOptions {
+    /** Physical context window — the ONLY hard wall. */
+    windowTokens: number;
+    /** Operating budget B (< W). High-watermark HW defaults to this. */
+    budgetTokens: number;
+    /** Shed down to this low-watermark when HW is breached. (HW − LW) sets fold
+     *  frequency/amplitude. Default 0.8·budget. */
+    lowWatermark?: number;
+    /** High-watermark; fold is triggered above it. Default = budgetTokens. */
+    highWatermark?: number;
+    /** Per-turn divergence reach: how far back (tokens from the live end) a fold
+     *  may normally edit — the structural perturbation cap P, and the primary
+     *  cost↔continuity knob. Smaller = gentler per-turn KV perturbation (shallow
+     *  divergence) but less efficient compression → more/again folding. Exceeded
+     *  ONLY to avoid the hard wall W. Default = budgetTokens (effectively
+     *  unbounded). */
+    reachTokens?: number;
+    /** Attended window kept raw + stable (the flat zone). */
+    attendedWindowTokens: number;
+    /** Base-k summary grouping (matches mergeThreshold). Default 6. */
+    mergeThreshold?: number;
+    /** Cache breakpoints per turn (1..4). Default 4. */
+    markerCount?: number;
+    /** Approx replay steps (down-sample). Default 120. */
+    targetSteps?: number;
+    /** Cache TTL in steps. Default Infinity. */
+    cacheTtlSteps?: number;
+}
+export interface ControlStep {
+    now: number;
+    numChunks: number;
+    renderedTokens: number;
+    cachedTokens: number;
+    recomputedTokens: number;
+    /** Billed recompute at provider multipliers. */
+    billed: number;
+    /** Prefix churn = recompute beyond genuinely new content (the KV perturbation
+     *  of the attended region). 0 on a pure-append turn. */
+    perturbation: number;
+    /** True when the controller folded this turn (a perturbation event). */
+    folded: boolean;
+    /** True when even full folding could not fit under W (terminal). */
+    escalated: boolean;
+    deepestLevel: number;
+}
+export interface ControlResult {
+    steps: ControlStep[];
+    totalRecomputed: number;
+    totalBilled: number;
+    overallHitRate: number;
+    /** Worst single-turn perturbation (the continuity ceiling). */
+    maxPerturbation: number;
+    /** RMS per-turn perturbation (variance-continuity). */
+    rmsPerturbation: number;
+    /** Count of turns that perturbed the prefix. */
+    foldEvents: number;
+    /** Count of terminal (over-W) turns. */
+    escalations: number;
+}
+/**
+ * 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 declare function foldDepthCap(chunk: PickerChunk, now: number, flatZone: ReadonlySet<ChunkId>, flatZoneChunks: number, mergeThreshold: number): number;
+export interface ControlPlanParams {
+    /** Carried frontier (F_prev). */
+    previous: ReadonlyMap<ChunkId, number>;
+    /** Fold (deepen) when rendered tokens exceed this (high-watermark). */
+    foldAtTokens: number;
+    /** Un-fold (raise toward raw) when rendered tokens are below this
+     *  (low-watermark). Default = targetTokens. The band (foldAt − expandAt) is a
+     *  no-op dead zone that prevents fold↔unfold oscillation. Set below foldAt. */
+    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. */
+    windowTokens: number;
+    /** Per-turn divergence reach (perturbation cap P) — bounds BOTH fold and
+     *  un-fold divergence. Default = windowTokens. */
+    reachTokens?: 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>;
+    /** Newest source sequence — the age reference for the log-age fold caps. */
+    now: number;
+    /** Base-k summary grouping. Default 6. */
+    mergeThreshold?: number;
+}
+export interface ControlPlan {
+    resolutions: Map<ChunkId, number>;
+    tokens: number;
+    /** A fold (deepen) happened this turn. */
+    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). */
+    escalated: boolean;
+}
+/**
+ * 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.
+ */
+export declare function planControlledFrontier(inputs: PickerInputs, tree: SummaryTree, p: ControlPlanParams): ControlPlan;
+/**
+ * Run the controller over a session (the exported PickerInputs snapshot) as
+ * growing history, measuring billed recompute and KV perturbation per turn.
+ */
+export declare function replayControlled(fullInputs: PickerInputs, opts: ControlOptions): ControlResult;
+//# sourceMappingURL=kv-control.d.ts.map

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

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