billion-context-dsh 0.2.21 → 0.2.23

package/dist/lru.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A size-capped Map that evicts least-recently-used entries once the cap is
+ * reached (issue #113). Recency is refreshed by both get and set. Backs the
+ * engine's per-session caches so idle sessions can be dropped and later
+ * rebuilt from the durable session log instead of accumulating forever.
+ * @module billion-context-dsh/lru
+ */
+/** Default cap for the engine's per-session caches (kernel states, nudge dedup). */
+export declare const DEFAULT_SESSION_CACHE_LIMIT = 512;
+export declare class LruMap<K, V> extends Map<K, V> {
+    private readonly maxEntries;
+    constructor(maxEntries: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): this;
+}

package/dist/messages.d.ts

@@ -20,6 +20,20 @@ import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
  * the actual `text` blocks, so a top-level-only walk would drop every tool
  * result from the projection (and with it the seq's ref assignment, breaking
  * compress boundary resolution). Nested arrays are flattened depth-first.
+ *
+ * Non-text blocks that the provider still bills for render as a deterministic
+ * one-line placeholder instead of vanishing (issue #117). An `image`/`file`
+ * block used to contribute nothing, which silently made a picture-only user
+ * message — or a tool result carrying a screenshot — invisible to the engine:
+ * no ref (so no compress boundary), `hasPlainRef` false (so the range solver
+ * shrank past it and swallowed neighbours), invisible to the kernel's
+ * recent/last-user protection (so the last real user turn could be compressed
+ * away), priced at zero tokens, and absent from search/decompress output. The
+ * host itself projects non-text references to deterministic handle text for
+ * files ("request assembly projects every occurrence to deterministic handle
+ * text", dsh-llm/lib/types/types.d.ts), and this is the same idea one layer
+ * down. Only durable attachment metadata is used, so the placeholder is stable
+ * across turns (cache prefix, summary text, search hits).
  */
 export declare function extractText(content: unknown): string;
 /**
@@ -50,6 +64,17 @@ export declare function buildToolCallIndex(events: readonly SessionEvent[]): Rea
  *                        untagged (`toolName: ''`), never "text".
  * Non-surface events project to nothing.
  */
+/**
+ * B1 summary source framing. A compaction summary is MODEL-WRITTEN text, not
+ * user words — injected as a user/message with the same standing as real input,
+ * which let obligation sentences inside summaries read as user directives and
+ * the model's own guesses read as user commitments. The frame says both things
+ * up front. It is applied at creation (src/region.ts writes the framed blocks
+ * to BOTH durable writes) and again at projection (below) as an idempotent
+ * safety net for legacy blocks written before the feature.
+ */
+export declare const SUMMARY_FRAME_PREFIX = "[Model-written summary \u2014 not user words; re-verify any obligations before relying on them]";
+export declare function withSummaryFramePrefix(text: string): string;
 export declare function projectEvent(event: SessionEvent, toolNames?: ReadonlyMap<string, string>): CoreMessage[];
 /** Project a session's message events into CoreMessage[] in log order. */
 export declare function eventsToCoreMessages(events: readonly SessionEvent[], toolNames?: ReadonlyMap<string, string>): CoreMessage[];
@@ -65,3 +90,78 @@ export declare function surfaceEventsOf(session: Session): SessionEvent[];
 export declare function allLogMessages(session: import('@deepseek-ai/dsh-session').Session): CoreMessage[];
 /** Extract the model-facing text of any surface message event. */
 export declare function extractEventText(event: SessionEvent): string;
+/** Count image/file blocks reachable from a content payload (same walk as extractText). */
+export declare function countAttachmentBlocks(content: unknown): {
+    images: number;
+    files: number;
+};
+/**
+ * Attachments carried by one surface event, walked exactly like
+ * `extractEventText`. Used in two places: the compressible-range rows mark
+ * media-bearing spans, and the callers that already own a token meter price
+ * those spans with the provider-anchored media price instead of the text-only
+ * estimate (issue #117).
+ */
+export declare function attachmentsOfEvent(event: SessionEvent): {
+    images: number;
+    files: number;
+};
+/**
+ * The image/file blocks themselves (not just their counts), in document order.
+ * The compressible-range rows price these with the fixed-heuristic media price
+ * when the meter reports no routed surcharge, so a media-bearing span is never
+ * shown as free (issue #117).
+ */
+export declare function mediaBlocksOfEvent(event: SessionEvent): readonly unknown[];
+/**
+ * Whether a surface user message is a compaction checkpoint node (already
+ * compressed). Defined here (not in region.ts) so the classifier below and
+ * region.ts share ONE implementation.
+ */
+export declare function isCheckpointNode(event: SessionEvent): boolean;
+/**
+ * Injection/authoring classification of one surface event — the ONE shared
+ * classifier for range scanning and the protected-tail scan (never ad-hoc
+ * predicates that drift apart).
+ *
+ * - `real` — genuine conversation content (user turns without an injected
+ *   source, assistant prose/tool-calls, tool results, sub-agent relay rows).
+ *   This is the only class that may win "last real user message" protection
+ *   (minus relay rows, see `isRealUserTurn`).
+ * - `metadata` — the engine's own ephemeral rows: nudge echoes and
+ *   compress-pair replacement stubs. Their content is derived from
+ *   already-visible messages, so folding them into an adjacent real segment
+ *   is zero-loss — this preserves main's behavior for engine-authored rows.
+ * - `checkpoint` — compaction summary nodes (`plugin: 'compact'`).
+ *   Distillation is an explicit act; never folded into any segment.
+ * - `instruction` — host-authored policy/instructions: AGENTS.md injections
+ *   (both host shapes), skill catalogs, and ANY unknown `kind:'plugin'` row.
+ *   Folding these is unsafe (the model would lose live policy text, and the
+ *   host re-injects the current AGENTS.md copy when it disappears — the
+ *   compress → re-inject loop this PR fixes). Unknown plugin names fall here
+ *   deliberately: a future host injection must never silently become
+ *   compressible content.
+ */
+export type SurfaceEventClass = 'real' | 'metadata' | 'checkpoint' | 'instruction';
+/** Plugin names the engine itself authors — safe to fold into real segments. */
+export declare const METADATA_PLUGINS: ReadonlySet<string>;
+/**
+ * True for AGENTS.md instruction rows in BOTH host shapes: the hook shape
+ * (`kind:'agent-instructions'`, form 'instructions') and the baseline shape
+ * (`kind:'plugin'` + plugin 'agent-instructions'). Shared by the newest-row
+ * scan and the range scanner so protection and folding always agree on what
+ * counts as an AGENTS.md row.
+ */
+export declare function isAgentInstructionsRow(event: SessionEvent): boolean;
+export declare function classifySurfaceEvent(event: SessionEvent): SurfaceEventClass;
+/**
+ * Whether an event is a real user turn — the protected-tail criterion. An
+ * injected row (AGENTS.md, skill catalog, nudge echo, tool notice) is real
+ * *content* at most but is never the user speaking: the latest real user
+ * message must keep its protection window even when an injected row lands
+ * after it. The scan this replaces protected "the last non-checkpoint
+ * user/message", which on live sessions is frequently an AGENTS.md injection
+ * row (the host appends it in the same enter batch) — the actual last user
+ * message was left compressible while synthetic output sat safe.
+ */
+export declare function isRealUserTurn(event: SessionEvent): boolean;

package/dist/nudge.d.ts

@@ -5,12 +5,14 @@
  * targets ranges by surface seq rather than by <acp> tags).
  * @module billion-context-dsh/nudge
  */
-import { type CompressionCore, type CoreMessage, type NudgeDecision } from 'acp-kernel';
+import { type CompressionCore, type CompressionState, type ContextBreakdown, type CoreMessage, type NudgeDecision } from 'acp-kernel';
 import { type UserMessage } from '@deepseek-ai/dsh-llm';
 import type { Agent } from '@deepseek-ai/dsh-agent';
 import { AcpStateStore } from './state.ts';
+import { type KernelRangeView, type MediaPriceOf } from './region.ts';
 import { type KernelConfigInput } from './config.ts';
 import { type ResolvedPrompts } from './prompts.ts';
+export declare function stripNudgeGuidance(text: string): string;
 /** Kernel inputs the nudge path shares with the compress tool. */
 export interface NudgeEnvironment extends KernelConfigInput {
     readonly kernel: CompressionCore;
@@ -38,21 +40,65 @@ export interface NudgeOutcome {
 export declare function resolveTokenCount(agent: Agent, coreMessages: CoreMessage[]): number;
 /**
  * Render the compressible-range table as seq refs for the model.
- * Computed directly from the surface (not the kernel's ref map, which can
- * drift and hide large tool results) — see buildCompressibleSeqRanges.
- * UPSTREAM: this self-computation is a labeled workaround for kernel
- * ref-map drift after surface replacements (AGENTS.md rule 11) — drop it and
- * use kernel compressibleRanges once the drift is fixed upstream.
+ *
+ * The spans are the kernel's own (`compressibleRanges`, translated to surface
+ * seqs) with the host guards applied on top — see buildCompressibleSeqRanges.
+ * This function used to self-compute them from the surface as a labeled
+ * `UPSTREAM:` workaround for kernel ref-map drift; that drift is fixed upstream
+ * (acp-kernel #207) and the workaround is gone (rule 11).
+ */
+export declare function rangeTable(session: import('@deepseek-ai/dsh-session').Session, kernelView: KernelRangeView, prompts?: ResolvedPrompts, mediaPriceOf?: MediaPriceOf): string;
+/**
+ * Compute a SURFACE-ONLY context breakdown for display, aligned with
+ * `acp_status` (kernel `buildStatusReport`/`renderOverview`).
+ *
+ * The kernel's own `computeContextBreakdown` (which the nudge text renders)
+ * walks the message array it is fed — and `buildNudge` feeds it the FULL log
+ * (`allLogMessages`, needed so T2/T3 distillation can anchor every block). So
+ * a session with compressed blocks reports HISTORICAL totals there: every
+ * original tool/text message already absorbed into a block is counted again,
+ * e.g. `85.2K tool` for ~8.5K of live tool context. `acp_status` instead feeds
+ * `buildStatusReport` the VISIBLE surface + active-block summaries, so its
+ * breakdown reads the true current context. This function reproduces that
+ * visible-surface reality for the nudge line so the two tools agree.
+ *
+ * Classification replicates kernel `computeContextBreakdown` (tool-call/
+ * tool-result → tool, `system` role → system, `` code `` fence in text →
+ * code, else text) EXCEPT summaries: kernel detects summaries by a
+ * `[Compressed conversation section]` text prefix, which never matches a DSH
+ * checkpoint node (our summary is the plain summary + `compactCheckpointSource`
+ * source marker). We instead count active-block summaries directly from kernel
+ * state (same source `buildStatusReport` uses), and the caller must exclude
+ * checkpoint summary nodes from `messages` (they are not in any block's
+ * `effectiveMessageIds` and would double-count — mirror of `/acp` status's
+ * `isCheckpointNode` exclusion).
+ */
+export declare function computeSurfaceBreakdown(state: CompressionState, messages: readonly CoreMessage[], total: number, growth: number): ContextBreakdown;
+/**
+ * Max emergency nudge injections within a single user turn. Bounds the
+ * positive-feedback loop where an unrelieved ≥emergency-threshold pressure
+ * re-injects a durable emergency nudge on every pre-step forever (issue #108).
+ * Mirrors billion-context-pi commit 414acd1 (cap emergency nudge injections per
+ * user turn). Normal-pressure nudges remain limited to one per turn regardless.
  */
-export declare function rangeTable(session: import('@deepseek-ai/dsh-session').Session, prompts?: ResolvedPrompts): string;
+export declare const EMERGENCY_NUDGE_MAX_PER_TURN = 3;
 /**
  * Decide and build one nudge message for the agent's next pre-step. Returns
- * null when the kernel recommends no nudge or one was already injected for the
- * current turn (emergency nudges always bypass the dedup). Also advances the
- * in-memory kernel state (ref assignment) so the compress tool can resolve
- * seq → mNNNNN refs.
+ * null when the kernel recommends no nudge or the per-turn budget is spent:
+ * normal-pressure nudges fire at most once per user turn, and emergency nudges
+ * are capped at {@link EMERGENCY_NUDGE_MAX_PER_TURN} per user turn so an
+ * unrelieved ≥threshold pressure cannot re-inject a durable nudge on every
+ * pre-step forever (issue #108). Also advances the in-memory kernel state (ref
+ * assignment) so the compress tool can resolve seq → mNNNNN refs.
+ *
+ * `onEmergencyCapHit` (optional) fires when the kernel still wants an
+ * emergency nudge but the per-turn budget is spent — the host uses it to log
+ * why the model stops receiving nudges (issue #108 review).
  */
-export declare function buildNudge(agent: Agent, env: NudgeEnvironment, lastNudgeTurn: Map<string, number>): NudgeOutcome | null;
+export declare function buildNudge(agent: Agent, env: NudgeEnvironment, lastNudgeTurn: Map<string, number>, emergencyNudges: Map<string, {
+    turn: number;
+    count: number;
+}>, onEmergencyCapHit?: () => void): NudgeOutcome | null;
 /**
  * Render the nudge message text. DEFAULT (no `config.prompts.nudge` override)
  * calls the kernel's own `renderNudgeText` — EFFICIENCY_NOTE/EMERGENCY_HEADER,
@@ -66,4 +112,4 @@ export declare function buildNudge(agent: Agent, env: NudgeEnvironment, lastNudg
  * When a host overrides any `prompts.nudge` slot, the template path is used so
  * `config.prompts` keeps full control (custom copy wins over kernel defaults).
  */
-export declare function buildNudgeText(nudge: NudgeDecision, emergency: boolean, session: import('@deepseek-ai/dsh-session').Session, prompts?: ResolvedPrompts): string;
+export declare function buildNudgeText(nudge: NudgeDecision, emergency: boolean, session: import('@deepseek-ai/dsh-session').Session, kernelView: KernelRangeView, prompts?: ResolvedPrompts, mediaPriceOf?: MediaPriceOf): string;

package/dist/presets.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Named presets for the nudge thresholds — how eagerly the model is asked to
+ * compress, in one word instead of three hand-tuned percentages (issue #105).
+ *
+ * A preset is a bundle of the three first-class nudge-threshold knobs
+ * (`nudgeMinContextLimitPct` / `nudgeMaxContextLimitPct` /
+ * `nudgeEmergencyThresholdPct`). It does NOT touch any other knob: `modelContextLimit`,
+ * `autoNudge`, prompts, and the `coreOverrides` escape hatch all stay exactly as
+ * configured. The individual thresholds remain fully available and win over the
+ * preset when both are set — precedence is explicit value > preset > engine
+ * default (applied in `resolveAcpConfig`, src/index.ts), so a partial override
+ * on top of a preset is honored.
+ *
+ * The five tiers form a monotonic spectrum from least to most aggressive
+ * compression. `balanced` reproduces the current out-of-the-box engine defaults
+ * exactly (min 0.45 = kernel default, max 0.70, emergency 0.85), so choosing it
+ * changes nothing relative to today's behavior.
+ *
+ * Presets are set at composition time (`config: { preset: 'efficient' }`).
+ * Runtime hot-reload of the underlying keys rides on issue #75 Phase 1
+ * (`settings.yaml` + `/acp config`); surfacing the `preset` alias through that
+ * same channel is the small follow-up once Phase 1 lands. The two knobs named in
+ * the original request that are NOT first-class engine knobs today — `growthRatio`
+ * (exists in acp-kernel as `nudge.growthRatio`, reachable via `coreOverrides`) and
+ * `protectedLastMessages` (≈ kernel `preserveRecentMessages`) — are deliberately
+ * out of scope here; adopting them as named knobs is an owner decision, not a
+ * preset detail.
+ * @module billion-context-dsh/presets
+ */
+/** The five preset tier names. */
+export type PresetName = 'preserve' | 'relaxed' | 'balanced' | 'efficient' | 'aggressive';
+/** The preset tiers ordered least → most aggressive (for help text / display). */
+export declare const PRESET_NAMES: readonly PresetName[];
+/** One preset tier: a human label plus the three nudge-threshold values it sets. */
+export interface NudgePreset {
+    /** Plain-language one-liner describing the tier's trade-off. */
+    readonly label: string;
+    /** Nudge window lower bound (usage fraction; the threshold gate floor). */
+    readonly nudgeMinContextLimitPct: number;
+    /** Over-limit guarantee line — above this the nudge fires regardless of growth. */
+    readonly nudgeMaxContextLimitPct: number;
+    /** Emergency nudge threshold (bypasses the per-turn dedup). */
+    readonly nudgeEmergencyThresholdPct: number;
+}
+/**
+ * The five tiers. Every row satisfies the kernel invariant
+ * `min ≤ max ≤ emergency` (the kernel only WARNS on the reverse — it never rejects
+ * the config, so `resolveAcpConfig` rejects an inverted merged triple itself), and
+ * all three values move monotonically toward "compress sooner" as you go down
+ * the list. Values are fractions of the context window, not token counts.
+ */
+export declare const PRESETS: Readonly<Record<PresetName, NudgePreset>>;
+/** Type guard: true when `value` is one of the five preset names. */
+export declare function isPresetName(value: unknown): value is PresetName;
+/**
+ * Resolve a preset name to its tier. Throws on an unknown name so a typo in the
+ * composition config fails engine construction loudly (the same fail-fast
+ * contract as prompt-template validation) rather than silently falling back to
+ * the engine defaults.
+ */
+export declare function resolvePreset(name: string): NudgePreset;

package/dist/prompts.d.ts

@@ -22,9 +22,9 @@ export type PromptOverride<T> = {
     [K in keyof T]?: PromptInput;
 };
 export interface NudgePrompts {
-    /** 普通档首句。占位符:{pct} {philosophy} */
+    /** 普通档首句。占位符:{pct}（`{philosophy}` 仍被校验器接受,但 B6 会把渲染出的哲学段摘掉——它只能经系统提示到达模型) */
     normal: string;
-    /** 紧急档首句。占位符:{pct} {philosophy} */
+    /** 紧急档首句。占位符:{pct}（`{philosophy}` 同上) */
     emergency: string;
     /** 指导行（HOW_TO_COMPRESS_RULES）。无占位符 */
     guidance: string;

package/dist/region.d.ts

@@ -12,6 +12,7 @@
  */
 import type { Session, SessionEvent, SessionEventMap } from '@deepseek-ai/dsh-session';
 import { type ContentBlock } from '@deepseek-ai/dsh-llm';
+import { type AcpBlockLedgerPayload } from './block-ledger.ts';
 /** One durable ACP block as rebuilt from the session log. */
 export interface AcpBlockLedgerEntry {
     /** The compaction transaction id (stable block identity). */
@@ -34,6 +35,8 @@ export interface AcpBlockLedgerEntry {
     /** The kernel block's raw direct/effective message ids at creation (recorded since the tier feature; absent for legacy). */
     readonly directMessageIds?: readonly string[];
     readonly effectiveMessageIds?: readonly string[];
+    /** B3: acceptance readings that were already green before compression (absent when the compress call carried none). */
+    readonly verifiedReadings?: readonly string[];
     /** Unix epoch ms of the compaction/summary event. */
     readonly createdAt: number;
 }
@@ -117,33 +120,32 @@ export interface CompactionTransactionInput {
     /** The kernel block's direct/effective message ids (raw CoreMessage ids) — recorded for faithful rehydration. */
     readonly directMessageIds?: readonly string[];
     readonly effectiveMessageIds?: readonly string[];
+    /** B3：压缩前已绿的验收读数（结构化，压缩后仍可读）。 */
+    readonly verifiedReadings?: readonly string[];
 }
+type CompactionSummaryData = SessionEventMap['compaction/summary'];
 /**
- * ACP tier extension fields carried on `compaction/summary` events. The
- * upstream dsh-compaction event type does not know them, so reads and writes
- * go through this precise intersection (never `any`).
+ * Read a `compaction/summary` event's data. The six ACP tier/lineage fields are
+ * no longer top-level members (issue #141): post-fix writers carry them in the
+ * admitted optional `rawOutput` member (decode via {@link decodeAcpBlockLedger}),
+ * while logs written by pre-fix engines still carry them as top-level members —
+ * so the returned type also intersects with {@link AcpBlockLedgerPayload}, letting
+ * readers fall back to the legacy shape. Never `any`.
  */
-export interface AcpCompactionSummaryFields {
-    /** Compression tier (1/2/3) — 1 = message range, 2 = distills tier-1, 3 = distills tier-2. */
-    readonly tier?: 1 | 2 | 3;
-    /** Short block label (kernel `CompressionBlock.topic`) — the acp_status block title. */
-    readonly topic?: string;
-    /** The acp-kernel block id (`bN`) created for this transaction. */
-    readonly kernelBlockId?: string;
-    /** Durable compaction ids of the blocks distilled into this one. */
-    readonly parentBlockIds?: readonly string[];
-    /**
-     * The kernel block's direct message ids (raw CoreMessage ids) at creation —
-     * recorded so a restarted engine rehydrates the SAME coverage (a tier-2
-     * block's coverage is its parents' originals, not the checkpoint node).
-     */
-    readonly directMessageIds?: readonly string[];
-    /** The kernel block's effective message ids (raw CoreMessage ids) at creation. */
-    readonly effectiveMessageIds?: readonly string[];
-}
-type CompactionSummaryData = SessionEventMap['compaction/summary'];
-/** Read a `compaction/summary` event's data including the ACP tier extension fields. */
-export declare function readCompactionSummary(event: SessionEvent): CompactionSummaryData & AcpCompactionSummaryFields;
+export declare function readCompactionSummary(event: SessionEvent): CompactionSummaryData & AcpBlockLedgerPayload;
+/**
+ * B3: read the structured verified readings a compress call recorded for this
+ * block (acceptance checks that were already green before the range was
+ * shadowed — e.g. "t0-fastpath 8/8"). Post-fix writers carry them inside the
+ * admitted `rawOutput` member (AcpBlockLedgerPayload); legacy writers put them
+ * top-level. Absent in either shape → empty array; never throws.
+ */
+export declare function verifiedReadingsOf(event: SessionEvent): string[];
+/**
+ * B1：给摘要块数组的第一个文本块加标源前缀（幂等——已带前缀不重复加）。
+ * 只动文本块，工具/图片块原样保留。
+ */
+export declare function prefixSummaryBlocks(blocks: readonly ContentBlock[]): ContentBlock[];
 /**
  * Run one durable compression transaction. Throws on invalid state; on success
  * the four events are in the log and the surface has one summary node.
@@ -162,7 +164,30 @@ export interface SeqCompressibleRange {
     readonly tokens: number;
     /** Share of messages that are tool messages (tool-call or tool-result), 0-100 — kernel `toolPct` parity. */
     readonly toolPct: number;
+    /** Image blocks reachable inside the span (directly or through a tool result). */
+    readonly images: number;
+    /** File blocks reachable inside the span. */
+    readonly files: number;
 }
+/**
+ * Per-seq provider-anchored price for non-text blocks (see `mediaPriceViaMeter`
+ * in host-tokens.ts). A callback, not a map, so a media-free session never pays
+ * for a meter measurement: the range walk only asks about seqs it already knows
+ * carry an image/file block.
+ */
+export type MediaPriceOf = (seq: number) => number;
+/**
+ * Durable model-free prune: append `compaction/prune` as the shadow price,
+ * then replace the given surface seqs with a user message. dsh-session 0.1.5+
+ * allows only user/message (and system/message) replacements to cite source
+ * events — assistant/message FORBIDS `sourceEventSeqs` because it embeds its
+ * own provider stream — so there is no invisible replacement node anymore:
+ * every hidden span becomes a user message. Callers with meaningful text pass
+ * it (compress call/result hiding keeps the tool outcome visible to the
+ * model); callers without get the fixed prune note. The originals remain in
+ * the append-only log.
+ */
+export declare const PRUNE_NOTE = "(removed by context management)";
 /**
  * Hide one successful `compress` tool's call/result pair after its tool/result
  * has been logged. The durable compaction summary is inserted BEFORE the
@@ -208,18 +233,92 @@ export declare function openToolCallIds(session: Session): Set<string>;
  */
 export declare function deferCompressPairHide(session: Session, callId: string, resultSeq: number, onError?: (error: unknown) => void): void;
 /**
- * Compute compressible spans directly from the surface — independent of the
- * kernel's ref map, which can drift after surface replacements in long
- * sessions and hide large tool results from the nudge range table. Skips the
- * recent protected tail, the last user message, and compaction checkpoints;
- * edges are then balanced through resolveSurfaceRange. Ranges are ordered
- * oldest-first (stable across turns — matches the kernel's `oldest first`).
- * UPSTREAM: this self-computation is a labeled workaround for kernel
- * ref-map drift after surface replacements (AGENTS.md rule 11) — drop it and
- * use kernel compressibleRanges once the drift is fixed upstream.
+ * Newest AGENTS.md instruction row per scope (source file). The host
+ * re-injects a file's instructions when its CURRENT copy is absent from the
+ * surface (deepseek-harness packages/context/agent-instructions presence
+ * gate, index.ts:137/:163 — presence+identity, not payload diff), so
+ * compressing the newest row of a scope makes that file come straight back,
+ * while compressing a STALE copy of the same file is silent. Live-audited
+ * shape (session-f25e4fad): EVERY injection row — baseline and worktree —
+ * carries `source.changes[].scope` = `"<dir>\u0000<file>"` (root
+ * `.\u0000AGENTS.md`, worktree `worktrees/<name>\u0000AGENTS.md`), which is
+ * stable across config tweaks unlike `baselineIdentity`. Tail-scan the log,
+ * group by scope, keep the last seq of each group. O(events), mirrors
+ * indexWatermarkOf. Rows without `changes[]` (legacy shapes) are SKIPPED
+ * entirely: identity is what the host's presence gate needs in order to
+ * re-inject a file, so a scope-less row can never come back and must not be
+ * guarded (the earlier shape gave each its own group, which made every legacy
+ * row a permanent hard-reject — issue #71 review S3).
  */
-export declare function buildCompressibleSeqRanges(session: Session, opts?: {
+export declare function newestInstructionSeqsOf(session: Session): Set<number>;
+/**
+ * Surface seqs NO caller may compress: the CURRENT (newest) injected
+ * agent-instructions row of every scope, restricted to rows still visible on
+ * the surface (one definition of "current" — `newestInstructionSeqsOf`).
+ * `buildCompressibleSeqRanges` never OFFERS them, and both compress entry
+ * points (`handleCompress` in src/tools.ts, `/acp compress` in
+ * src/commands.ts) probe the RESOLVED span against this set and HARD-REJECT a
+ * covering range before the kernel applies it, so nothing durable lands and no
+ * phantom block can exist. This supersedes the earlier F7 draft (warn only):
+ * folding a current copy reclaims nothing — the host re-injects it — so there
+ * is no legitimate outcome to warn about. Deliberately NARROW (issue #71
+ * review F4): only CURRENT agent-instructions rows — the audited loop driver.
+ * Engine-authored metadata rows (nudge echo, compress-pair stub) stay
+ * foldable like main, and STALE copies of the same file stay compressible —
+ * removing them while the newest copy stays visible is the real cleanup.
+ */
+export declare function guardedSurfaceSeqsOf(session: Session): Set<number>;
+/**
+ * The kernel's own view of what can be compressed, as the engine hands it to
+ * the range table: the geometry (`nudge.compressibleRanges`) plus the ref map
+ * that turns a kernel ref back into a surface seq (`state.messageRefs`).
+ *
+ * Structural shapes only, so the engine passes the kernel's own objects
+ * straight through and tests can hand-build a view.
+ */
+export interface KernelRangeView {
+    /** Kernel `recommendedRanges`/`compressibleRanges` entries (oldest first). */
+    readonly ranges: readonly {
+        readonly startRef: string;
+        readonly endRef: string;
+    }[];
+    /** Kernel ref map: `mNNNNN` → our message id (which IS the surface seq). */
+    readonly refs: {
+        readonly byRef: Readonly<Record<string, string>>;
+    };
+}
+/**
+ * Compressible spans in the DSH seq dialect, for the nudge range table.
+ *
+ * The GEOMETRY — which messages group into one compressible span — comes from
+ * the kernel's own ranges (design decision 7: the kernel owns the algorithm).
+ * The kernel splits a group when the next message is a user turn and the group
+ * already holds 3+ messages, and after any protected or already-compressed
+ * message, so a row reads as "roughly one stretch of work" rather than an
+ * arbitrary slice. This function only does the two jobs the kernel cannot:
+ *
+ * 1. Translate refs into surface seqs — DSH has no `<acp>` ref tags; seq is our
+ *    ref (design decision 2).
+ * 2. Apply the host guards on top of the kernel's grouping: injected
+ *    instruction rows split a span and the newest copy of every scope is never
+ *    offered, checkpoints and the surface's system node are not compressible,
+ *    and the recent tail plus the last REAL user turn stay protected (rule 16).
+ *
+ * History — why this used to compute the spans itself. A kernel range's edges
+ * were derived by counting refs, and a surface replacement breaks that
+ * arithmetic: the checkpoint node of a replace lands mid-array carrying a much
+ * higher ref, so ref order and array order diverge and the spans came back
+ * reversed (`end < start`) or lost large tool results entirely. The table was
+ * therefore self-computed from the surface, labeled `UPSTREAM:` and tracked as
+ * issue #38 (rule 11). The pinned kernel segments by ARRAY adjacency instead
+ * (upstream #207) and the drift is gone — measured on a session whose
+ * compressed span sits in the MIDDLE of the surface: every ref resolves to the
+ * right seq, no span crosses the shadowed hole, and the compressed span is
+ * excluded. Rules 3 and 11 are updated with it.
+ */
+export declare function buildCompressibleSeqRanges(session: Session, kernelView: KernelRangeView, opts?: {
     preserveRecent?: number;
+    mediaPriceOf?: MediaPriceOf;
 }): SeqCompressibleRange[];
 /**
  * A compact human-readable description of the current surface for the model:
@@ -280,4 +379,56 @@ export declare function summarySeqOfKernelBlock(session: Session, kernelBlockId:
  * seqs. Cycle-safe (a block can never be its own ancestor).
  */
 export declare function expandShadowedSeqs(session: Session, blockId: string): number[];
+/**
+ * Default decompress page size (#112): a block shadowing hundreds of
+ * messages used to be returned whole in ONE tool result — big enough to
+ * flood the context window or get silently trimmed by the host's
+ * tool-result pruner before the model ever saw the tail. One page per call
+ * keeps every recovery usable; `offset` walks the rest.
+ *
+ * A page is bounded by BOTH this message count and a rendered-character
+ * budget ({@link DEFAULT_DECOMPRESS_PAGE_CHARS}). Count alone was not enough:
+ * the host's `dsh-compaction-tool-result-pruner` (docs/dsh-porting-analysis.md)
+ * trims by CHARACTERS (thresholdChars 8192), so a wide page of long messages
+ * still crossed that line and had its middle dropped. The char bound keeps an
+ * ordinary page under the pruner threshold so it comes back intact; the
+ * message count doubles as a hard ceiling so a pathological `limit` can't
+ * re-open the whole-block flooding half of #112.
+ */
+export declare const DEFAULT_DECOMPRESS_PAGE = 100;
+/**
+ * Rendered-character budget per decompress page (#112). Kept below the host's
+ * tool-result pruner threshold (8192, docs/dsh-porting-analysis.md) with
+ * headroom for the block header, the `[seq N]` prefixes, and the continue hint,
+ * so a normal page survives intact instead of middle-trimmed. Deliberately NOT
+ * tied to acp-kernel's `config.truncate.threshold`: that knob truncates a single
+ * oversized tool output during compression, whereas the host pruner trims our
+ * whole decompress result — different mechanisms, different thresholds.
+ */
+export declare const DEFAULT_DECOMPRESS_PAGE_CHARS = 7000;
+export interface DecompressPage {
+    /** Requested offset floored to >= 0; reported as-is when it lands past the end. */
+    offset: number;
+    /** Limit actually applied (clamped to [1, DEFAULT_DECOMPRESS_PAGE]). */
+    limit: number;
+    /** Total shadowed messages in the block (tier-expanded). */
+    total: number;
+    /** This page's shadowed seqs, in expansion order. */
+    seqs: number[];
+    /** True when no further page follows this one. */
+    exhausted: boolean;
+}
+/**
+ * Slice a block's expanded shadowed-seq list into one page. A page holds at most
+ * `limit` messages AND at most `charBudget` rendered characters, where
+ * `renderLen(seq)` reports each message's on-the-wire length (0 when it carries
+ * no text). Seqs whose original carries no text still occupy a slot, so `offset`
+ * stays a stable continuation index across calls while the log is frozen.
+ * Out-of-range / negative / non-finite values clamp instead of failing (optional
+ * convenience params, not semantic boundaries); non-numeric input falls back to
+ * the default rather than leaking NaN into the result. The first message of the
+ * page is always included even if it alone exceeds the budget, so a walk always
+ * makes progress past a single giant message.
+ */
+export declare function sliceDecompressPage(expanded: number[], offset: number, limit: number, charBudget: number, renderLen: (seq: number) => number): DecompressPage;
 export {};

package/dist/session-events.d.ts

@@ -1,21 +1,28 @@
 /**
  * Cross-version session event access.
  *
- * DSH `0.1.2-alpha` replaced the public `Session.events` getter with explicit
- * `snapshotEvents()` / `eventAt(seq)` methods; rc.6 / 0.1.1-rc.x still expose
- * `events`. Both shapes are feature-detected here so a single build runs on
- * either seam (the engine's peer range keeps `^0.1.0-rc.6 || ^0.1.1-rc.1`).
+ * History: DSH `0.1.2-alpha` replaced the public `Session.events` getter with
+ * explicit `snapshotEvents()` / `eventAt(seq)` methods (only rc.6 /
+ * 0.1.1-rc.x had `events`). Both shapes are feature-detected here; since the
+ * peer floor moved to the 0.1.5 line (`>=0.1.5-alpha.1 <0.1.6-0`, issue #136),
+ * every supported seam exposes the method pair — dsh-session 0.1.5 has no
+ * public `.events` getter — so the `events` fallback is defensive robustness
+ * for foreign or stub handles, not a supported-host path.
  *
- * Semantics match on both sides:
- *  - `events` (rc.6) and `snapshotEvents()` (0.1.2-alpha) both return the
- *    current full log as a stable, cached snapshot (reused until the next
- *    append), with `seq === array index`.
- *  - indexed reads map to `events[seq]` / `eventAt(seq)` with the same
- *    `undefined`-when-absent contract.
+ * Semantics:
+ *  - `snapshotEvents()` returns the current full log as a stable, cached
+ *    snapshot (reused until the next append), with `seq === array index`.
+ *  - indexed reads map to `eventAt(seq)` (or `events[seq]` on the legacy
+ *    shape) with the same `undefined`-when-absent contract.
  * @module billion-context-dsh/session-events
  */
 import type { Session, SessionEvent } from '@deepseek-ai/dsh-session';
 /** All events of a session in log order (seq == array index). */
 export declare function sessionEventsOf(session: Session): readonly SessionEvent[];
-/** The event at one exact seq, or undefined when the log has no such seq. */
+/**
+ * The event at one exact seq, or undefined when the log has no such seq.
+ * Falls back through `sessionEventsOf` (snapshotEvents → events) so a
+ * snapshot-only handle stays readable; yields undefined, never throws,
+ * when a handle exposes neither read method.
+ */
 export declare function eventAtOf(session: Session, seq: number): SessionEvent | undefined;