comisai 1.0.45 → 1.0.46

package/node_modules/@comis/agent/dist/context-engine/lcd-fresh-tail-bound.js

@@ -1,21 +1,21 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Fresh-tail size bounding for the LCD `dag` assembler (B-8 + Issue-1).
+ * Fresh-tail size bounding for the LCD `dag` assembler.
  *
- * The fresh tail ships UNCONDITIONALLY (A1/A3) and the dag path runs neither
+ * The fresh tail ships UNCONDITIONALLY and the dag path runs neither
  * the observation masker nor the dead-content evictor (pipeline-only), so a
  * turn whose last steps carry a huge tool output — or a huge user/assistant
- * message (the Issue-1 session brick: one over-window message rides the fresh
+ * message (the session brick: one over-window message rides the fresh
  * tail forever) — would overflow the model window before any budget pass sees
  * it. This module bounds each oversized fresh-tail message via the shared
  * {@link createToolResultSizeGuard} factories (head+tail+honest marker — NOT
  * hand-rolled), with the per-message cap derived from the turn's
  * `availableHistoryTokens` (see {@link computeFreshTailCapChars}).
  *
- * Invariant reconciliation (the lcd-assembler call site enumerates A1/A2/A3):
- * the guards are referential no-ops below the cap; only text CONTENT shrinks
- * (no message removed/reordered, no `toolCallId` touched, non-text blocks
- * pass through); the LCD store keeps the full content losslessly so the
+ * Invariant reconciliation (the lcd-assembler call site enumerates the full
+ * list): the guards are referential no-ops below the cap; only text CONTENT
+ * shrinks (no message removed/reordered, no `toolCallId` touched, non-text
+ * blocks pass through); the LCD store keeps the full content losslessly so the
  * masked region stays `ctx_expand`-recoverable.
  *
  * Extracted from lcd-assembler.ts to keep that file under the 800-line cap.
@@ -27,7 +27,7 @@ import { createToolResultSizeGuard, } from "../safety/tool-result-size-guard.js"
 import { factoredMessageTokens } from "./factored-message-tokens.js";
 import { computeFloorOutputHeadroom } from "./output-headroom.js";
 /**
- * B-8: the single shared tool-result size guard for the dag assembler's fresh-tail
+ * The single shared tool-result size guard for the dag assembler's fresh-tail
  * bounding. Built ONCE at module scope (stateless factory) so each
  * `transformContext` reuses it. The default head+tail+marker config is fine; the
  * honest lossless-recovery suffix is appended to the marker via `toolHint` per call
@@ -37,7 +37,7 @@ import { computeFloorOutputHeadroom } from "./output-headroom.js";
  */
 const FRESH_TAIL_TOOL_RESULT_GUARD = createToolResultSizeGuard();
 /**
- * Issue-1 (small-model e2e 2026-06-12 UC-3): the sibling guard for oversized
+ * The sibling guard for oversized
  * USER/ASSISTANT messages in the fresh tail. Same head+tail+honest-marker
  * masking as the tool-result guard, with message-appropriate marker wording
  * (the default marker's "reduce output size (use --max-lines, …)" remedy is
@@ -52,26 +52,26 @@ const FRESH_TAIL_MESSAGE_GUARD = createToolResultSizeGuard({
     truncationMarker: "\n[... ${removed} chars of this oversized message truncated to fit the model's context window.${hint}]\n",
 });
 /**
- * Issue-1: the fraction of the turn's `availableHistoryTokens` (H = W − S − O −
+ * The fraction of the turn's `availableHistoryTokens` (H = W − S − O −
  * M − R) one fresh-tail message may occupy. Computing the cap from H — not the
  * raw window — is what makes the bound sufficient: H already nets out the
  * system/tool prompt (S), the output reservation (O), and the safety margins
  * (M+R), so a bounded message can never push `S + freshTail` past the
  * pre-flight's `effectiveWindow − outputHeadroom` bound on its own. (A cap of
- * `0.8 × effectiveWindowChars` alone would NOT be: on the live 32K small
- * window, 0.8 × W ≈ 26K tokens + S ≈ 7K still exceeded the window.)
+ * `0.8 × effectiveWindowChars` alone would NOT be: on a 32K small
+ * window, 0.8 × W ≈ 26K tokens + S ≈ 7K still exceeds the window.)
  */
 const FRESH_TAIL_MESSAGE_CAP_HISTORY_FRACTION = 0.8;
 /**
- * Issue-1: the cap FLOOR. When H collapses to ~0 (everything reserved — a tiny
+ * The cap FLOOR. When H collapses to ~0 (everything reserved — a tiny
  * window, or S eating the whole budget) the H-derived cap would bound EVERY
  * fresh-tail message down to the guard's head+tail residue, shredding normal
  * small messages that were never the problem (the fresh tail ships
  * unconditionally BY DESIGN even when H = 0, and the pre-flight is the
  * authority on whether the result fits). Below this floor the head+tail+marker
  * masking saves almost nothing anyway, and a floor-sized message (~3.4K tokens
- * at the 3.5 ratio) was already over ANY window where H ≈ 0 — so for sub-floor
- * messages the behavior is byte-identical to pre-Issue-1.
+ * at the 3.5 ratio) is already over ANY window where H ≈ 0 — so for sub-floor
+ * messages the floor changes nothing.
  */
 const FRESH_TAIL_MESSAGE_CAP_FLOOR_CHARS = 12_000;
 /**
@@ -84,27 +84,27 @@ const FRESH_TAIL_MESSAGE_CAP_FLOOR_CHARS = 12_000;
 const FRESH_TAIL_BOUND_RECOVERY_HINT = "the full content is preserved losslessly in the LCD store and is recoverable";
 /**
  * The per-message char cap for this turn's fresh-tail bounding:
- * `max(FLOOR, min(B-8 constant, 0.8 × H in chars))`. For frontier/mid H is
- * huge, so the cap degrades to the historical 100K-char B-8 constant —
- * byte-identical behavior there.
+ * `max(FLOOR, min(absolute per-result constant, 0.8 × H in chars))`. For
+ * frontier/mid H is huge, so the cap degrades to the absolute 100K-char
+ * {@link LCD_FRESH_TAIL_MAX_TOOL_RESULT_CHARS} constant.
  */
 export function computeFreshTailCapChars(availableHistoryTokens) {
     return Math.max(FRESH_TAIL_MESSAGE_CAP_FLOOR_CHARS, Math.min(LCD_FRESH_TAIL_MAX_TOOL_RESULT_CHARS, Math.floor(availableHistoryTokens * FRESH_TAIL_MESSAGE_CAP_HISTORY_FRACTION * CHARS_PER_TOKEN_RATIO)));
 }
 /**
- * B-8 + Issue-1: bound oversized messages inside the unconditional fresh tail.
+ * Bound oversized messages inside the unconditional fresh tail.
  * Pure + non-mutating — for each fresh-tail message whose total TEXT exceeds
  * `cap`, run the matching shared {@link createToolResultSizeGuard} factory
  * (head+tail+honest marker) and return a NEW message carrying the truncated
- * content; every message that fits passes through REFERENTIALLY unchanged (A1
- * preserved for what fits). The guard's marker carries the lossless-recovery
- * hint via `toolHint`, so the model is honestly told the full content is
- * recoverable.
+ * content; every message that fits passes through REFERENTIALLY unchanged
+ * (verbatim fidelity preserved for what fits). The guard's marker carries the
+ * lossless-recovery hint via `toolHint`, so the model is honestly told the
+ * full content is recoverable.
  *
  * Covered roles:
- *  - `toolResult` (the original B-8 class — huge file reads / command dumps),
+ *  - `toolResult` (huge file reads / command dumps),
  *    via the default-marker guard;
- *  - `user` / `assistant` (the Issue-1 session-brick class — one pasted
+ *  - `user` / `assistant` (the session-brick class — one pasted
  *    document larger than the effective window), via the message-marker
  *    guard. String-shorthand content is bounded by round-tripping through a
  *    single text block and restored to string shape.
@@ -112,7 +112,7 @@ export function computeFreshTailCapChars(availableHistoryTokens) {
  * Only text CONTENT shrinks here — no message is removed/reordered, no
  * `toolCallId` is touched, and non-text blocks (toolCall, image, …) pass
  * through the guard untouched — so the later `sanitizeToolUseResultPairing`
- * (A2) still re-pairs every result with its `tool_use`.
+ * still re-pairs every result with its `tool_use`.
  *
  * @param freshTail - the verbatim fresh-tail slice (the last N steps of the live array)
  * @param cap - the per-message char cap from {@link computeFreshTailCapChars}
@@ -136,14 +136,14 @@ export function boundFreshTailMessages(freshTail, cap) {
         if (isTextMessage && typeof content === "string") {
             const result = guard.truncateIfNeeded([{ type: "text", text: content }], cap, FRESH_TAIL_BOUND_RECOVERY_HINT);
             if (!result.truncated)
-                return m; // fits below the cap — byte-identical (A1).
+                return m; // fits below the cap — byte-identical.
             boundedMessages++;
             charsRemoved += (result.metadata?.originalChars ?? 0) - (result.metadata?.truncatedChars ?? 0);
             return { ...m, content: result.content[0]?.text ?? "" };
         }
         // A toolResult with non-array content (string shorthand / absent) cannot carry
         // an oversized text-block payload through the guard's block API — leave it
-        // verbatim (A1). The guard only bounds array-of-blocks content.
+        // verbatim. The guard only bounds array-of-blocks content.
         if (!Array.isArray(content))
             return m;
         // The guard's `toolHint` carries the honest lossless-recovery marker suffix (not
@@ -151,7 +151,7 @@ export function boundFreshTailMessages(freshTail, cap) {
         // recoverability of the masked content is).
         const result = guard.truncateIfNeeded(content, cap, FRESH_TAIL_BOUND_RECOVERY_HINT);
         if (!result.truncated)
-            return m; // fits below the cap — byte-identical (A1).
+            return m; // fits below the cap — byte-identical.
         if (isToolResult)
             boundedResults++;
         else
@@ -168,26 +168,26 @@ function roleOf(m) {
     return m.role;
 }
 /**
- * ISSUE #1 (2026-06-22): bound the PROTECTED fresh tail's TOTAL tokens to
+ * Bound the PROTECTED fresh tail's TOTAL tokens to
  * `residualTokens` by dropping the OLDEST whole STEP at a time, keeping the newest
  * contiguous run that fits. The fresh tail ships UNCONDITIONALLY (the eviction cannot
- * trim it), and {@link boundFreshTailMessages} (B-8) bounds only individual oversized
+ * trim it), and {@link boundFreshTailMessages} bounds only individual oversized
  * MESSAGES — not the SUM across turns — so on a tiny window where the system prompt
  * dominates, a handful of small recent turns accumulate past the residual and overflow
- * the window (the live nano failure: freshTail grew 1438→2369→3488…→exhaust). This
- * enforces the total directly.
+ * the window (the observed nano failure mode: freshTail grows 1438→2369→3488…→exhaust).
+ * This enforces the total directly.
  *
  * Operates on the ALREADY per-message-bounded fresh tail (call AFTER
- * boundFreshTailMessages) so a single oversized message B-8 shrank to fit is counted at
- * its bounded size, NOT dropped (Issue1-A/D). ALWAYS keeps the LAST step (the current
+ * boundFreshTailMessages) so a single oversized message the per-message guard shrank
+ * to fit is counted at its bounded size, NOT dropped. ALWAYS keeps the LAST step (the current
  * live turn ships even when it alone exceeds the residual — the pre-flight then degrades
  * it honestly as oversized_input, never silently). A STEP is a leading non-`toolResult`
  * message plus its immediately-following `toolResult`s (mirrors
  * lcd-budget-eviction.groupIntoSteps / freshTailBoundaryIndex) so a tool_use/tool_result
  * pair is never split. Pure: reads the input, returns a NEW array (or the same ref when
- * nothing is dropped — the A1 no-op for everything that fits).
+ * nothing is dropped — a verbatim no-op for everything that fits).
  *
- * @param freshTail - the per-message-bounded fresh-tail messages (B-8 output).
+ * @param freshTail - the per-message-bounded fresh-tail messages ({@link boundFreshTailMessages} output).
  * @param residualTokens - the room the protected tail may occupy (≈ window − S − floorHeadroom − preamble).
  * @returns the newest contiguous fresh-tail steps that fit (≥ the last step).
  */
@@ -202,12 +202,13 @@ export function boundFreshTailTotalToResidual(freshTail, residualTokens) {
     }
     if (stepStarts.length <= 1)
         return freshTail; // one step (or all toolResults) — keep whole.
-    // ISSUE #3 (2026-06-22): measure with the SAME factored estimator the pre-flight uses
+    // Measure with the SAME factored estimator the pre-flight uses
     // (factoredMessageTokens) — NOT estimateMessageTokens (4:1). Estimator PARITY means the
     // bound enforced here EQUALS the pre-flight's measure for ANY system-prompt size, so no
     // fudge factor is needed on the residual (the caller passes the exact pre-flight residual).
-    // Pre-fix the 4:1↔3.5:1 gap scaled with the residual: on a small S (large residual) the
-    // bounded tail still measured over the bound at the pre-flight's ratio → exhaustion.
+    // With mismatched estimators the 4:1↔3.5:1 gap scales with the residual: on a small S
+    // (large residual) the bounded tail still measures over the bound at the pre-flight's
+    // ratio → exhaustion.
     const tokensFrom = (from) => {
         let sum = 0;
         for (let i = from; i < freshTail.length; i++) {
@@ -222,25 +223,26 @@ export function boundFreshTailTotalToResidual(freshTail, residualTokens) {
         s++;
     }
     if (s === 0)
-        return freshTail; // nothing dropped — A1 no-op (same reference).
+        return freshTail; // nothing dropped — verbatim no-op (same reference).
     return freshTail.slice(stepStarts[s]);
 }
 /**
- * ISSUE #1/#3/#3b: compute the protected-fresh-tail residual and trim the tail to it.
+ * Compute the protected-fresh-tail residual and trim the tail to it.
  *
  * The residual = effectiveWindow − systemTokens − FLOOR output headroom − preamble. The
  * floor headroom comes from {@link computeFloorOutputHeadroom} with the model's ACTUAL
- * reasoningStyle — the IDENTICAL value the pre-flight throws against (#3b: a native model
+ * reasoningStyle — the IDENTICAL value the pre-flight throws against (a native model
  * reserves the native "low" floor incl. the reasoning reserve; under-counting it ships a
  * tail the pre-flight exhausts on). The trim measures with the SAME factored estimator the
- * pre-flight uses (#3: estimator parity, no fudge). Frontier/mid: an Infinite window → the
- * residual is undefined → returns the tail UNCHANGED (no-op → byte-identical, LOCKED #2).
+ * pre-flight uses (estimator parity, no fudge). Frontier/mid: an Infinite window → the
+ * residual is undefined → returns the tail UNCHANGED (no-op → byte-identical, the locked
+ * frontier/mid contract).
  *
  * Owns the diagnostic DEBUG (`step:lcd-freshtail-bound`) so the assembler body stays thin
  * and the residual inputs (reasoningStyle / floorHeadroom / residual / before+after factored
- * sizes) are one-read visible — the obs-excellence loop for this bug class.
+ * sizes) are one-read visible from a single log line.
  *
- * @param freshTail - the per-message-bounded (B-8) fresh-tail messages.
+ * @param freshTail - the per-message-bounded fresh-tail messages.
  * @param ctx - window/S/reasoningStyle/preamble + logging context.
  * @returns the trimmed fresh tail (or the same reference on a no-op).
  */
@@ -252,8 +254,8 @@ export function boundProtectedFreshTail(freshTail, ctx) {
     const before = freshTail.reduce((s, m) => s + factoredMessageTokens(m), 0);
     const bounded = boundFreshTailTotalToResidual(freshTail, residual);
     const after = bounded.reduce((s, m) => s + factoredMessageTokens(m), 0);
-    // INSTRUMENTATION (lead's mandate, 2026-06-22): after 5 test-green/live-fail cycles,
-    // log the EXACT trim mechanics on EVERY call so the next live re-test SHOWS why the
+    // INSTRUMENTATION: log the EXACT trim mechanics on EVERY call so a live
+    // investigation SHOWS why the
     // protected tail is/isn't trimmed — not a hypothesis. Per-step factored sizes +
     // kept/dropped counts disambiguate the 4 candidate causes (giant step / wrong residual
     // / preamble / keep-last-too-much). `roleOf` mirrors the function's own grouping so the

package/node_modules/@comis/agent/dist/context-engine/lcd-leaf-summarizer.d.ts

@@ -1,5 +1,5 @@
 /**
- * LCD leaf summarization unit (Phase 129, C1).
+ * LCD leaf summarization unit.
  *
  * Two pure-ish responsibilities, both proven by a STUB summarizer (no network):
  *
@@ -14,25 +14,25 @@
  *  2. {@link summarizeLeafChunk} — run the mandatory 3-level escalation
  *     (normal → aggressive → deterministic truncation) that ALWAYS reduces
  *     tokens or falls back deterministically. The structural model is
- *     `compactWithFallback` (`llm-compaction.ts:545-607`), but C1 ADDS a
- *     per-level token-reduction assertion (LOSSLESS-CLAW §5: "If output > input,
- *     retry aggressive then truncate") and a BOUNDED Level-3 output (a count-only
+ *     `compactWithFallback` (`llm-compaction.ts:545-607`), but this unit ADDS a
+ *     per-level token-reduction assertion (if output > input, retry aggressive
+ *     then truncate) and a BOUNDED Level-3 output (a count-only
  *     note prefixed with `LEAF_FALLBACK_SUMMARY_MARKER`, capped at
  *     `LEAF_FALLBACK_TARGET_TOKENS`) — the guaranteed-shrink terminator. The
  *     ladder is FINITE (Level 1 ≤ 1+COMPACTION_MAX_RETRIES attempts → Level 2 one
  *     attempt → Level 3 deterministic); it never loops without a floor.
  *
  * The LLM summarizer is INJECTED as ONE function ({@link LeafSummarizer}) so
- * Phase 132 can wrap it with spend governance / a circuit breaker by swapping a
- * single seam (the binding constraint; the Security DoS row T-129-08). 129 calls
- * it inline and non-fatally: an error at Levels 1+2 is caught (WARN, errorKind
+ * the production wiring can wrap it with spend governance / a circuit breaker
+ * by swapping a single seam (the binding DoS-containment constraint). This unit
+ * calls it inline and non-fatally: an error at Levels 1+2 is caught (WARN, errorKind
  * `dependency`) and the pass falls through to the deterministic Level 3 — it
  * NEVER throws out of the pass.
  *
  * Architecture cut (agent↛memory): this file imports ONLY the agent-side token
  * estimators + the escalation constants; it NEVER imports `@comis/memory`. It
  * also NEVER logs `chunkMessages` content or the summary `content` — ids, counts,
- * level, and durations only (AGENTS.md §2.2; T-129-10). It reads NO wall clock of
+ * level, and durations only (AGENTS.md §2.2). It reads NO wall clock of
  * its own — the leaf time-range (`earliestAt`/`latestAt`) is derived purely from
  * the injected `LeafChunkItem.createdAt` values, so there is no globals-gate
  * surface here (the caller's injected clock stamps timestamps upstream).
@@ -50,11 +50,11 @@ import type { SecurityPinMarkers } from "./security-context-pinner.js";
  * (`estimateMessageTokens` of a 1–4-char user string), so a chunk must be ≥ 2
  * tokens for any non-empty summary to be strictly smaller. A 1-token chunk is
  * already trivially tiny — there is nothing to gain — so the caller skips the
- * pass entirely (WR-01) rather than emitting a degenerate empty/larger fallback.
+ * pass entirely rather than emitting a degenerate empty/larger fallback.
  */
 export declare const MIN_SHRINKABLE_LEAF_CHUNK_TOKENS = 2;
 /**
- * B-4 (260605-ney): the fraction of a chunk's rendered shrink ceiling used as the
+ * The fraction of a chunk's rendered shrink ceiling used as the
  * EFFECTIVE summarize target. The configured `reserveTokens` (= `leafTargetTokens`
  * / `condensedTargetTokens`) can EXCEED a small chunk — telling the model to write
  * a summary larger than what it compresses → a guaranteed non-reduction → the
@@ -66,7 +66,7 @@ export declare const MIN_SHRINKABLE_LEAF_CHUNK_TOKENS = 2;
  */
 export declare const SHRINK_TARGET_FRACTION = 0.5;
 /**
- * Compute the self-consistent shrink bounds for a chunk (B-4, 260605-ney). Shared
+ * Compute the self-consistent shrink bounds for a chunk. Shared
  * by {@link summarizeLeafChunk} and `summarizeCondensedChunk` (the rule of three
  * is met — both summarizers need the identical bounding).
  *
@@ -74,9 +74,9 @@ export declare const SHRINK_TARGET_FRACTION = 0.5;
  *
  *  - `shrinkCeilingTokens` — the accept-test ceiling, measured the SAME way the
  *    candidate summary is (`estimateMessageTokens` of a user string = 4:1 prose):
- *    `ceil(renderedChars / CHARS_PER_TOKEN)`. The prior code compared a 4:1-prose
- *    candidate against the chunk's MIXED-ratio STORED `tokenCount` (3:1 structured
- *    / 4:1 text) — inconsistent units. This makes the comparison like-for-like.
+ *    `ceil(renderedChars / CHARS_PER_TOKEN)`. Comparing a 4:1-prose candidate
+ *    against the chunk's MIXED-ratio STORED `tokenCount` (3:1 structured
+ *    / 4:1 text) would be inconsistent units; this keeps the comparison like-for-like.
  *    NOTE: the STORED Σ `tokenCount` remains the BUDGET / before-size / floor
  *    authority everywhere else (utilization, eviction, the deterministic Level-3
  *    note + its strict ceiling) — only the accept-test ceiling moves here.
@@ -100,9 +100,10 @@ export declare function computeShrinkBounds(renderedChars: number, configuredRes
  * and creation timestamp. Keeping the chunk-selection input as a plain array of
  * these (rather than reaching into a store) keeps {@link selectLeafChunk} pure.
  *
- * Token authority (Pitfall 2): the caller sources `tokens` from the STORED
- * `LcdMessage.tokenCount` for store-sourced history (which counts F3 thinking)
- * and from `estimateMessageTokens` only for live/fresh-tail messages.
+ * Token authority: the caller sources `tokens` from the STORED
+ * `LcdMessage.tokenCount` for store-sourced history (which counts persisted
+ * thinking/reasoning blocks) and from `estimateMessageTokens` only for
+ * live/fresh-tail messages.
  */
 export interface LeafChunkItem {
     /** Stable message id (the LCD `lcd_messages.id`) — covered by the leaf. */
@@ -150,7 +151,7 @@ export interface LeafSummarizeOptions {
     depth?: number;
 }
 /**
- * The ONE injected summarizer seam. Production (Phase 132) supplies a function
+ * The ONE injected summarizer seam. Production supplies a function
  * that wraps the SDK `generateSummary` behind spend governance + a circuit
  * breaker; unit tests inject a deterministic stub (no network). Returns the raw
  * summary string (may be too large — the ladder re-checks size and escalates).
@@ -160,8 +161,8 @@ export type LeafSummarizer = (messages: AgentMessage[], opts: LeafSummarizeOptio
  * The minimal model-capabilities snapshot the compaction chain resolves
  * (`id`/`provider`/`contextWindow`/`reasoning`). A plain value object with NO
  * reference back to `session.agent.state` — so it can be captured once at the
- * afterTurn boundary and safely read by a DEFERRED (C4) pass that runs AFTER
- * `session.dispose()` (WR-04). `getModel()` returns this shape.
+ * afterTurn boundary and safely read by a DEFERRED pass that runs AFTER
+ * `session.dispose()`. `getModel()` returns this shape.
  */
 export interface CompactionModelSnapshot {
     id?: string;
@@ -171,24 +172,25 @@ export interface CompactionModelSnapshot {
 }
 /**
  * Dependencies for the leaf summarizer. Mirrors the `CompactionLayerDeps`-style
- * getters (`getModel` / `getApiKey` / `overrideModel`) so Phase 132 can reuse the
- * same resolution chain; the LLM call itself lives behind {@link LeafSummarizer}.
+ * getters (`getModel` / `getApiKey` / `overrideModel`) so the production wiring
+ * can reuse the same resolution chain; the LLM call itself lives behind
+ * {@link LeafSummarizer}.
  */
 export interface LeafSummarizerDeps {
     /** Structured logger (ids/counts/level/durations only — never content). */
     logger: ComisLogger;
-    /** The injected summarizer (the 132 spend-governance seam). */
+    /** The injected summarizer (the spend-governance seam). */
     summarize: LeafSummarizer;
     /** Getter for the current model's capabilities (for capability reads — NOT the
      *  LLM model arg; the SDK generateSummary needs a real Model, see getRealModel). */
     getModel: () => CompactionModelSnapshot;
     /**
-     * B-5: the REAL pi-ai `Model<any>` for the PRIMARY summarizer path.
+     * The REAL pi-ai `Model<any>` for the PRIMARY summarizer path.
      * `generateSummary` needs a real Model (with the provider-client runtime it
      * invokes), NOT the 4-field {@link CompactionModelSnapshot} (which throws at
      * call time). Sourced from the executor's already-resolved model
      * (pi-executor.ts `resolvedModel` → setupContextEngine `params.resolvedModel`),
-     * captured at setup time BEFORE `session.dispose()` so the WR-04 deferred (C4)
+     * captured at setup time BEFORE `session.dispose()` so the deferred
      * pass — which runs post-dispose — still resolves a real Model. Typed `unknown`
      * end-to-end; the single sanctioned `as any` cast lives at the generateSummary
      * call site (the opaque-SDK Model<any>).
@@ -196,12 +198,12 @@ export interface LeafSummarizerDeps {
     getRealModel: () => unknown;
     /** Getter for the current model's provider API key. */
     getApiKey: () => Promise<string>;
-    /** Optional cheaper override model + key for the leaf pass. INT-W1:
+    /** Optional cheaper override model + key for the leaf pass.
      *  `servedWindow` is the provider-served context window binding THIS override
      *  model — provider-gated AT THE WIRING SITE (executor-context-engine-setup)
-     *  against the Phase-176 `servedContextWindow` pair: set ONLY when the
+     *  against the `servedContextWindow` pair: set ONLY when the
      *  override resolved onto the SAME `providers.entries` key the boot probe
-     *  measured (WR-02 space discipline — config keys, never `model.provider`,
+     *  measured (compared in config-key space, never `model.provider`,
      *  which the registry alias fallback can rename). Riding ON the candidate
      *  model preserves the provider binding structurally: the value can only
      *  ever clamp the model it travels with — a cloud `operationModels.compaction`
@@ -211,14 +213,14 @@ export interface LeafSummarizerDeps {
         getApiKey: () => Promise<string>;
         servedWindow?: number;
     };
-    /** INT-W1: the provider-served context window binding the PRIMARY
+    /** The provider-served context window binding the PRIMARY
      *  (`getRealModel`) summarizer — `windowProvenance.served`, i.e. already
      *  gated `servedContextWindow.providerKey === resolvedProviderKey` by the
-     *  executor reconcile (pi-executor WR-02), so it binds exactly the model
+     *  executor reconcile, so it binds exactly the model
      *  `getRealModel()` returns. A plain number captured at setup time
-     *  (dispose-safe on the WR-04 deferred path). Absent ⇒ no served truth for
+     *  (dispose-safe on the deferred path). Absent ⇒ no served truth for
      *  the primary (non-Ollama provider, probe off/failed, or provider mismatch)
-     *  — the configured window governs, byte-identical pre-INT-W1 behavior. */
+     *  — the configured window governs. */
     primaryServedWindow?: number;
     /** The agent's capability class. Defaults to "frontier" (unchanged behavior). */
     capabilityClass?: CapabilityClass;
@@ -266,23 +268,24 @@ export interface LeafSummaryResult {
  * messages up to the cap, then walks forward past a trailing assistant
  * `tool_use` and its `toolResult`s (never crossing the fresh-tail boundary).
  *
- * S4: if `pinnedMessageIds` is provided, chunks containing ANY pinned message
+ * If `pinnedMessageIds` is provided, chunks containing ANY pinned message
  * are skipped entirely — pinned messages are NEVER selected as eviction candidates.
  *
  * @param history - the evictable history items (seq order, oldest first)
  * @param freshTailSteps - the number of trailing STEPS protected from eviction
  * @param leafChunkTokens - the chunk token cap
- * @param pinnedMessageIds - S4: message ids that must never be selected for eviction
+ * @param pinnedMessageIds - message ids that must never be selected for eviction
  * @returns the selected chunk, or `undefined` when nothing is evictable
  */
 export declare function selectLeafChunk(history: LeafChunkItem[], freshTailSteps: number, leafChunkTokens: number, pinnedMessageIds?: Set<string>): LeafChunk | undefined;
 /**
  * Summarize a leaf chunk via the mandatory 3-level escalation. ALWAYS returns a
  * summary whose token count is STRICTLY LESS than the chunk's token count (the
- * C1 invariant) — accepting an LLM summary only when it actually reduces, and
- * otherwise falling through to the deterministic, bounded Level-3 truncation.
+ * strict-shrink invariant) — accepting an LLM summary only when it actually
+ * reduces, and otherwise falling through to the deterministic, bounded Level-3
+ * truncation.
  *
- * B-4 (260605-ney): the EFFECTIVE summarize target is bounded below the chunk's
+ * The EFFECTIVE summarize target is bounded below the chunk's
  * rendered shrink ceiling ({@link computeShrinkBounds}) so the model is never asked
  * to write more than it compresses (the spurious-floor fix), and the accept-test
  * ceiling is the RENDERED 4:1 measure — self-consistent with the candidate's units.
@@ -300,11 +303,12 @@ export declare function summarizeLeafChunk(chunkItems: LeafChunkItem[], deps: Le
 }): Promise<LeafSummaryResult>;
 /**
  * Construct the PRODUCTION {@link LeafSummarizer} — the seam that wraps the SDK
- * `generateSummary`. Phase 132 swaps THIS factory's output for a spend-governed /
- * circuit-broken variant; 129 calls `generateSummary` directly. The override
+ * `generateSummary`. The production wiring swaps THIS factory's output for a
+ * spend-governed / circuit-broken variant; the bare factory calls
+ * `generateSummary` directly. The override
  * model + key are used when {@link LeafSummarizerDeps.overrideModel} is present
  * (a cheaper compaction model resolved by the operation-model chain), else the
- * primary REAL model (`getRealModel`) + `getApiKey` (B-5 — a real pi-ai
+ * primary REAL model (`getRealModel`) + `getApiKey` (a real pi-ai
  * `Model<any>`, never the 4-field snapshot). Mirrors `compactWithFallback`'s call shape
  * (`llm-compaction.ts:561`); the 8th param threads `previousSummary` for
  * continuity. The function may return a too-large string — the escalation ladder
@@ -316,16 +320,16 @@ export declare function summarizeLeafChunk(chunkItems: LeafChunkItem[], deps: Le
  */
 export declare function buildLeafSummarizeFn(deps: Pick<LeafSummarizerDeps, "getRealModel" | "getApiKey" | "overrideModel">): LeafSummarizer;
 /**
- * SUM-03: wraps a primary {@link LeafSummarizer} with an ordered fallback list.
+ * Wraps a primary {@link LeafSummarizer} with an ordered fallback list.
  *
  * On primary failure, tries each fallback in sequence (ordered by the caller's
  * `fallbacks` array). Only when ALL providers in the list are exhausted does the
  * wrapper throw the last error — so the per-tenant circuit breaker that wraps the
  * OUTER spend-governed seam records exactly ONE failure per exhausted-list event
- * (Pitfall 4 in 171-RESEARCH: throw-last, not throw-per-provider).
+ * (throw-last, not throw-per-provider).
  *
  * Content-free: logs `providerIndex`, `totalProviders`, and `errorKind: "dependency"`
- * only — NEVER message content, summary text, or provider credentials (T-171-09).
+ * only — NEVER message content, summary text, or provider credentials.
  *
  * @param primary - the primary LeafSummarizer (already spend-governed by the outer seam)
  * @param fallbacks - ordered list of fallback LeafSummarizer callables