dsh-context-compression-improved 0.4.0-beta.1 → 0.5.0

package/CHANGELOG.md

@@ -1,134 +1,195 @@
-# Changelog
-
-All notable changes use this file. The project follows semantic versioning after `0.1.0`.
-
-## Unreleased (compat/0.1.5)
-
-### Changed
-
-- The runtime package is merged into the selector package: one install brings the whole
-  stack, the repository root is the install surface (`name`, `main`, `types`, `exports` with
-  `./pruner` and `./invariant`, `dependencies`, `dsh`), and the toolchain, scripts and CI were
-  swept to the single package. The verified estimator-catalog registration (dual prefix, guarded
-  two-channel activation, per-request service resolution, visible lifecycle lines) was replayed
-  onto this line with a host-side guard; the settings schema that `ab2175a` had downgraded to
-  `z.any()` is restored, so the daily Custom defaults are published again.
-- Adapt to the official DeepSeek Harness `v0.1.5-rc.2` on this branch. All `@deepseek-ai/dsh-*` dev dependencies and the pinned e2e host set move from `0.1.1-rc.2` to `0.1.5-rc.2` (cordis `4.0.2`, schemastery `3.18.2`), including the new split packages (`dsh-session-projection`, `dsh-session-persistence`, `dsh-atomic-write`, `dsh-home-paths`, `dsh-sandbox`, and related) and the `dsh-client-store` client stack.
-- Surface replace operations now use the v3 `startSeq`/`endSeq` shape with branded `SessionSeq` values; `compaction/prune` manifests keep the durable `start`/`end` fields. Events are resolved from surface nodes by seq lookup instead of array indexing.
-- The client bundle no longer imports the removed `@deepseek-ai/dsh-client-runtime`: settings types now come from `@deepseek-ai/dsh-client-ui-settings` and the session hooks merge from `@deepseek-ai/dsh-client-ui-session`. `engines.dsh >=0.1.5-alpha.1 <0.2.0-0` is declared in both package manifests and `dsh.plugin.json`.
-- Harness 0.1.5 no longer exposes the session `agentPreset` to the browser, so the client can no longer detect Minimal-only sessions; the selector stays selectable and the old unavailable banner is unreachable.
-- Test batteries updated for 0.1.5 semantics: cordis plugin starts require `.await()`, the Token Meter requires a mounted `SessionProjectionRegistry`, assistant events carry `stream: []`, and settings namespaces are plain strings.
-
-### Fixed
-
-- The estimator card no longer demands an API key on the Harness host channel. Selecting the host channel shows the live provider/model dropdowns, names the route that would actually run (explicit override, else the session default), and renders neither a key field nor a second manual model input: the base URL, the model text field, and the write-only key belong to the direct endpoint channel alone.
-- `presetOptions` writes are path-addressed. Writing the whole section replaced it, so touching any second estimator field (a provider, a model, an endpoint) deleted `estimatorMode` and every sibling override — silently switching the estimator back off while the panel still reported a successful save. Each field now writes only itself, `undefined` clears exactly the field it names, and the confirmation read validates the same field set instead of the mode alone.
-- New coverage: `packages/selector/tests/preset-options-write.client.spec.ts` (path-scoped writes, sibling preservation, explicit clears, no-op patches, uncommitted-write reporting) and `packages/selector/tests/estimator-channel.client.spec.tsx` (per-channel fields, catalog dropdowns, manual fallback).
-
-
-### Added
-
-- New `tokenpilot-inspired` profile: a TokenPilot-paper-inspired capability matrix layered on the Balanced thresholds, selected explicitly from the settings UI; every pre-existing profile keeps a byte-identical resolved policy (enforced by a captured-baseline golden test).
-- Byte-identical repeated tool-result dedup: an oversized repeat is replaced with a pointer to the first occurrence's append-only original event (`dedupe-pointer`), with a per-session SHA-256 index (2,048-entry insertion-order eviction, hash+seq metadata only).
-- No-net-savings guard: replacements whose text is not smaller than the original are rejected even when the exact tokenizer reports a token saving.
-- Recovery exemption: recovery-tool output is permanently exempt from every reduction pass via a unified per-session exemption set, preventing compress-restore oscillation.
-- Auto Compact summary locator: after `compaction/end`, the landed summary checkpoint gains an Exact Sources block (shadowed seq range, spill files, touched files) so summarized-away details stay recoverable; skipped when it would locate nothing concrete.
-- Read-state semantics: a historical read whose file was later mutated is `superseded` and takes the small whole-result placeholder; optional error/warn/info clustering of omitted lines is appended to historical placeholders.
-- Optional residual-utility estimator (three channels: off / Harness host model / direct OpenAI-compatible endpoint) with per-session exponential backoff, strict timeout, advisory-only verdicts consumed by the next pressure pass, and numeric-only `estimator-outcome` audits. The estimator card appears only while the new profile is selected; the API key is write-only in settings and never enters the frozen policy, audits, or logs.
-- New audit records: `summary-locator` and `estimator-outcome`; the rewrite record covers dedup via the `dedupe-pointer` reducer. Audit field allowlists are unchanged.
-- Simplified Chinese and English copy for the new profile and estimator card; unit and golden coverage under `packages/runtime/tests/tokenpilot/`.
-
-- Orthogonal code-skeleton compression gate (`codeSkeleton.enabled`, default off): the first exposure of an oversized fresh source-code tool result can keep an imports-and-declarations skeleton with bodies elided and error lines preserved, falling back to the original head pruning. The gate is independent of every profile and gated on exact tokenizer measurement.
-- Settings-UI toggle for the gate in the selector settings section, with Simplified Chinese and English copy.
-- Browser/runtime decode parity for the new section, confirm-on-write contract tests for `saveCodeSkeleton`, and a full-document parity matrix extension.
-
-### Changed
-
-- Added an ESLint flat-config baseline (`pnpm lint`, enforced in CI) and a `pnpm test:watch` TDD loop; removed dead imports and hardened two error paths surfaced by the lint baseline.
-- This repository is now maintained as an improved fork of `WilliamShi666/dsh-context-compression-selector`; documentation ships in English, Simplified Chinese, Japanese, and Korean.
-
-## 0.1.0 - 2026-09-03
-
-### Added
-
-- Stable release of DeepSeek V4 Flash Vision tokenizer integration for `deepseek-v4-flash-vision-exp`, including exact text counting and bounded image-token estimates.
-- User-configurable model-driven Auto Compact threshold in the selector settings section.
-- Auto Compact threshold linkage for each standard profile's History / micro-compact watermarks and related compression parameters.
-
-### Changed
-
-- The threshold editor now uses one direct numeric input; the slider and fixed quick-value buttons were removed.
-- Runtime session-event access supports both the established Harness `events` accessor and the newer `snapshotEvents()` public API.
-
-## 0.1.0-beta.4 - 2026-09-02
-
-### Fixed
-
-- Support the official DeepSeek Harness `dsh-v0.1.2-alpha.5` public API while retaining compatibility with the existing `0.1.1-rc.2` peer range. The plugin now owns the two small immutable-value helpers that the newer Harness no longer exports, and uses the same public `context-compression` namespace literal accepted by both Settings implementations. No Harness core code is modified.
-
-## 0.1.0-beta.3 - 2026-09-01
-
-### Scope
-
-This is a staged release. Exact **text-class** token counting for `deepseek-v4-flash-vision-exp`, best-effort bounded **vision-class image** estimates, and the Auto Compact threshold/UI/audit work are delivered. Exact image measurement remains **BLOCKED upstream**: the current measurement seam exposes neither the adapter's projected request-image dimensions nor the absolute serialized position, so estimates cannot be promoted to `exact-tokenizer`.
-
-### Added
-
-- DeepSeek V4 Flash Vision support for `deepseek-v4-flash-vision-exp` via a separately bundled official tokenizer pinned at `deepseek-ai/DeepSeek-V4-Flash-Vision-Exp` revision `6821d6ad3681a4b137b066b76094fa82ebd0a380`. Text, reasoning, tool-call arguments, and pure-text tool results are counted exactly; image-bearing tool-result candidates stay fail-open.
-- Vision image-token arithmetic ported line-by-line from the official `inference/image_processor.py` (patch size 14, downsample 3, 384-token cap, min pixels 147456, 8:1 aspect clamp, and position-dependent alignment padding), validated against golden fixtures generated by executing the official Python implementation. Valid intrinsic dimensions now produce `tokenizer-estimate` at the midpoint of all four alignment residues with a 384-token per-image upper bound; malformed or unevaluable dimensions use a documented 256-token fallback. Mixed text/image surfaces aggregate exact text and estimated images without promoting them to exact.
-- `autoCompact.thresholdPercent` setting (default 80, integer 50–90, step 1) with one shared validation contract across the settings UI, the persisted schema, and the runtime resolver. The editor lives inside the context-compression selector settings section.
-- Standard-profile History linkage to the Auto Compact watermark: `A = floor(C × a)` rescales the History trigger, minimum reclaim, and recent-token tail; `D = floor(A × 0.875)` replaces the fixed 0.7 capacity-pressure ratio as the micro-compact last-chance gate; one batch must justify its cache break by pulling the complete request back below the deadline. Defaults at 80% reproduce the previous numbers exactly.
-- The preset overlay writes the saved threshold into the generated `compaction-basic` composition as `thresholdRatio` (with `retainRatio` pinned at 0.16) and, from the same read, into the plugin runtime's deployment config as `autoCompactThresholdPercent`, so one standing generation never runs Auto Compact and micro compact on two different thresholds. Any generation-identity change — threshold, source, or module paths, including equal-length ones — produces a new standing composition generation. Deterministic identity-derived stamps use an 8-hex whole-second window; equal-prefix identities can collide in that first window on a coarse filesystem, so the overlay observes the staging file's real `mtimeMs+size` key and escalates to later hash windows before the atomic rename. Content, permissions, and the final unique stamp are complete before publication; already-running sessions keep their frozen policy.
-- `policy-resolved` audits now record the Auto Compact coordination facts (threshold percent, `A`, `D`, parameter source — including `deployment-override`/`mixed` when deployment config replaces linked History watermarks), the routed provider/model, and the bundled tokenizer identity.
-- Persisted settings reject present-but-invalid sections (`profile: null`, `custom: null`, own-property `undefined`) before any schema default can absorb them; a malformed stored document freezes the session losslessly (`profile: off`, audited as `settingsInvalidFallback: lossless-off`) instead of silently enabling the lossy Balanced default. The browser decoder applies the same rule and canonicalizes legacy Custom v1/v2 documents to the same v3 document the runtime resolver produces.
-- The History planner returns a discriminated outcome, and `component-evaluation` audits distinguish the full skip taxonomy: `below-profile-trigger`, `below-micro-deadline`, `exact-tokenizer-unavailable`, `no-safe-candidates` (only recovery-tool output or already-cleared results), `protected-working-set` (everything inside the protected tail), `insufficient-reclaim` and `cannot-reach-deadline-target` (with the reached/required token numbers), `adaptive-cost-rejected`, and `recovery-tool-unavailable`.
-
-### Known limitations
-
-- Images never claim exact counts. The official expansion depends on the absolute prompt position (system prompt, chat-template framing, adapter image handles) and on the adapter's final request-image projection (including per-route `imagePixelBudget`/`imageDetail` overrides and byte-cap reprojection), none of which is exposed through the current measurement seam. Intrinsic/default estimates may therefore differ materially from provider accounting. Upstream capability requests remain projected request-image dimensions and the absolute serialized position exposed to token-meter extensions.
-- History skips the whole batch whenever any tool-result candidate lacks an exact count, including image-bearing candidates, even though sibling text candidates are individually exact.
-- Custom remains manual token mode; its History parameters do not follow the Auto Compact watermark.
-- A vision token breakdown UI is not shipped; image estimates and the intrinsic alignment diagnostic are available on the measured token view, while lossy rewrite proofs still require exact counts.
-
-### Deferred
-
-- Audit `modality` field and the tokenizer artifact SHA-256 inside audit records (the audits already carry the routed provider/model and tokenizer identity).
-- Publishing the (now complete) runtime skip-reason taxonomy as a user-facing documentation table.
-- Custom-profile display of the A/D watermarks and an above-D warning; Custom remains fully manual.
-- Vision token breakdown UI and promotion of image estimates to exact measurement.
-
-## 0.1.0-beta.2 - 2026-08-28
-
-### Fixed
-
-- Resolve the official DeepSeek V4 Flash tokenizer route so Fresh and Aggregate can evaluate tool results for the supported V4 models.
-- Run Cache Strict History at the real request boundary once its configured capacity-pressure condition is met; trigger the capacity condition at 70% routed-context utilization.
-- Disable Harness-native head/middle/tail tool-result pruning whenever a selector profile is active, leaving the selector as the sole tool-result compactor.
-
-### Changed
-
-- Protect the newest 10 agent tool calls and a 64,000-token tool-result tail window before History/microcompact rewrites older results.
-
-## 0.1.0-beta.1 - 2026-08-27
-
-### Added
-
-- One-install DeepSeek Harness Product Bundle backed by a separate exact-version runtime package.
-- Web profile selector with preset-stable settings and an explicit built-in Minimal exception.
-- Fresh, Aggregate, routine/capacity-aware History, Native tool-result pruning, and default-off Custom TailTrim.
-- Standard-event TailTrim protocol using `compaction/prune` plus recoverable `user/message` replacement.
-- Plugin-owned `context_compression_retrieve` recovery tool.
-- Structured, content-free policy, evaluation, rewrite, failure, and Native auto-compact audit records.
-- Pinned official DeepSeek V4 tokenizer assets with runtime SHA-256 validation and upstream license.
-- Public-API component E2E, preset/Minimal, and parent/fork/spawn cache-prefix regression tests.
-
-### Compatibility
-
-- Verified against DeepSeek Harness `dsh-v0.1.1-rc.2` public packages.
-- Exact tokenizer mapping is currently limited to `deepseek-v4-flash` and `deepseek-v4-pro`.
-
-### Known limitations
-
-- Adaptive ordinary History fails closed when public request-level route/cache evidence is incomplete; capacity pressure remains a separate safety override.
-- Cache-prefix tests prove native fork inheritance and identical serialized prefixes, not a provider-specific cache allocation or a guaranteed DeepSeek cache hit.
-- Settings snapshots and first-exposure decisions are process-local to the mounted runtime.
+# Changelog
+
+All notable changes use this file. The project follows semantic versioning after `0.1.0`.
+
+## 0.5.0 - 2026-09-20
+
+### Added
+
+- Advisory relevance advisor (statistics and suggestions only, default off): at every turn
+  boundary a fire-and-forget pass summarizes the session's tail-task semantics from the
+  most recent `todo/write` event (falling back to recent user text), incrementally scores
+  historical tool-result candidates for content-and-comment relevance against the current
+  task, and computes a prefix-decay figure (character-pressure-weighted mean relevance).
+  Low-relevance old segments are marked `recertified` as suggestions for later
+  history-aggressiveness decisions — nothing this round consumes them, and advisor output
+  can never suppress, delay, or rewrite any reduction that would land (pinned by a
+  dedicated invariant test). Configure through the `presetOptions.advisor*` settings keys
+  (`advisorMode` `''|'host'|'direct'`, default `''`; the direct channel reuses the
+  estimator endpoint; `SideChannel` gained an optional overrides parameter so the
+  estimator's transport is shared without sharing its configuration). Observability: new
+  `advisor-outcome` audit records (content-free, one per phase: summary / scoring / decay)
+  and a read-only `GET .../advisor-report?sessionId=` HTTP route (opt-in deployment flag
+  `advisorReportRoute`, mirroring the review routes). Client UI is intentionally absent
+  this round.
+
+## 0.4.0 - 2026-09-20
+
+### Fixed
+
+- The plugin no longer depends on the routed model id: every planning gate now decides on
+  the character basis (Unicode code points via `characterPressure` / `pressureCost`) instead
+  of exact tokenizer counts, so a route without a bundled tokenizer (the live
+  `deepseek-flash`) lands rewrites again instead of silently skipping. Token thresholds keep
+  their names and values (converted at the documented 4.0 chars/token convention, frozen
+  profile baseline untouched); token figures become telemetry, labelled honestly by the new
+  `measurementBasis` field on rewrite audit records (`exact-tokenizer` vs `characters`,
+  with `tokenizerId: 'characters'` / `tokenizerRevision: 'chars-per-token-4.0'` when derived).
+  Rollback: `git revert 7a1972a` restores the exact-tokenizer gates as a single unit; confirm
+  no later change re-introduced a model-id split that relies on this commit first.
+
+### Added
+
+- Batch-level benefit pricing (R1): a review pass is priced as ONE merged mutation — the
+  tail KV-cache refill penalty is paid once per batch instead of per candidate, so real
+  batches (5×50k with a 64k tail) reach the auto band instead of all dropping.
+- Original-event line mapping (R9a): terminal normalization returns folded lines that each
+  carry their 1-based original-event line number; `retrieve` reads raw events, so printed
+  ranges resolve to the right lines.
+- Document skeleton and universal prose keep (R8/R8b): structured documents keep headings,
+  section first/last lines, list starts and table headers; every other non-code text keeps
+  head AND tail with an R9 line-range marker (prose was previously head-only truncated).
+- Two-tier search folding (R10, fixes D8): a lossless per-file L1 locator plus a
+  water-filled L2 content quota.
+- Non-adjacent frequency folding (R11): separated exact repeats (up to 8.37% of large
+  results) fold to first occurrence plus one counted marker.
+- Long-string placeholders (R12): base64/hex/UUID blobs become length summaries with a
+  16-char recognition prefix.
+- Two-stage HTML reduction (R13, fixes D9): `html-slim` then `html-skeleton`, line-aligned
+  so original line numbers survive.
+- R9b anchors: contiguous masks cite original line ranges, scatter masks report
+  `lines 1-N scanned, K kept`, and every retrieve hint carries a pasteable
+  `{"ref":…,"start_line":N,"max_lines":80}`.
+- Document census: omitted-document summaries list section headings instead of a constant
+  `0 error, 0 warn, N info` histogram.
+
+## 0.3.1 - 2026-09-18
+
+### Changed
+
+- The runtime package is merged into the selector package: one install brings the whole
+  stack, the repository root is the install surface (`name`, `main`, `types`, `exports` with
+  `./pruner` and `./invariant`, `dependencies`, `dsh`), and the toolchain, scripts and CI were
+  swept to the single package. The verified estimator-catalog registration (dual prefix, guarded
+  two-channel activation, per-request service resolution, visible lifecycle lines) was replayed
+  onto this line with a host-side guard; the settings schema that `ab2175a` had downgraded to
+  `z.any()` is restored, so the daily Custom defaults are published again.
+- Adapt to the official DeepSeek Harness `v0.1.5-rc.2` on this branch. All `@deepseek-ai/dsh-*` dev dependencies and the pinned e2e host set move from `0.1.1-rc.2` to `0.1.5-rc.2` (cordis `4.0.2`, schemastery `3.18.2`), including the new split packages (`dsh-session-projection`, `dsh-session-persistence`, `dsh-atomic-write`, `dsh-home-paths`, `dsh-sandbox`, and related) and the `dsh-client-store` client stack.
+- Surface replace operations now use the v3 `startSeq`/`endSeq` shape with branded `SessionSeq` values; `compaction/prune` manifests keep the durable `start`/`end` fields. Events are resolved from surface nodes by seq lookup instead of array indexing.
+- The client bundle no longer imports the removed `@deepseek-ai/dsh-client-runtime`: settings types now come from `@deepseek-ai/dsh-client-ui-settings` and the session hooks merge from `@deepseek-ai/dsh-client-ui-session`. `engines.dsh >=0.1.5-alpha.1 <0.2.0-0` is declared in both package manifests and `dsh.plugin.json`.
+- Harness 0.1.5 no longer exposes the session `agentPreset` to the browser, so the client can no longer detect Minimal-only sessions; the selector stays selectable and the old unavailable banner is unreachable.
+- Test batteries updated for 0.1.5 semantics: cordis plugin starts require `.await()`, the Token Meter requires a mounted `SessionProjectionRegistry`, assistant events carry `stream: []`, and settings namespaces are plain strings.
+
+### Fixed
+
+- The estimator card no longer demands an API key on the Harness host channel. Selecting the host channel shows the live provider/model dropdowns, names the route that would actually run (explicit override, else the session default), and renders neither a key field nor a second manual model input: the base URL, the model text field, and the write-only key belong to the direct endpoint channel alone.
+- `presetOptions` writes are path-addressed. Writing the whole section replaced it, so touching any second estimator field (a provider, a model, an endpoint) deleted `estimatorMode` and every sibling override — silently switching the estimator back off while the panel still reported a successful save. Each field now writes only itself, `undefined` clears exactly the field it names, and the confirmation read validates the same field set instead of the mode alone.
+- New coverage: `packages/selector/tests/preset-options-write.client.spec.ts` (path-scoped writes, sibling preservation, explicit clears, no-op patches, uncommitted-write reporting) and `packages/selector/tests/estimator-channel.client.spec.tsx` (per-channel fields, catalog dropdowns, manual fallback).
+
+
+### Added
+
+- New `tokenpilot-inspired` profile: a TokenPilot-paper-inspired capability matrix layered on the Balanced thresholds, selected explicitly from the settings UI; every pre-existing profile keeps a byte-identical resolved policy (enforced by a captured-baseline golden test).
+- Byte-identical repeated tool-result dedup: an oversized repeat is replaced with a pointer to the first occurrence's append-only original event (`dedupe-pointer`), with a per-session SHA-256 index (2,048-entry insertion-order eviction, hash+seq metadata only).
+- No-net-savings guard: replacements whose text is not smaller than the original are rejected even when the exact tokenizer reports a token saving.
+- Recovery exemption: recovery-tool output is permanently exempt from every reduction pass via a unified per-session exemption set, preventing compress-restore oscillation.
+- Auto Compact summary locator: after `compaction/end`, the landed summary checkpoint gains an Exact Sources block (shadowed seq range, spill files, touched files) so summarized-away details stay recoverable; skipped when it would locate nothing concrete.
+- Read-state semantics: a historical read whose file was later mutated is `superseded` and takes the small whole-result placeholder; optional error/warn/info clustering of omitted lines is appended to historical placeholders.
+- Optional residual-utility estimator (three channels: off / Harness host model / direct OpenAI-compatible endpoint) with per-session exponential backoff, strict timeout, advisory-only verdicts consumed by the next pressure pass, and numeric-only `estimator-outcome` audits. The estimator card appears only while the new profile is selected; the API key is write-only in settings and never enters the frozen policy, audits, or logs.
+- New audit records: `summary-locator` and `estimator-outcome`; the rewrite record covers dedup via the `dedupe-pointer` reducer. Audit field allowlists are unchanged.
+- Simplified Chinese and English copy for the new profile and estimator card; unit and golden coverage under `packages/runtime/tests/tokenpilot/`.
+
+- Orthogonal code-skeleton compression gate (`codeSkeleton.enabled`, default off): the first exposure of an oversized fresh source-code tool result can keep an imports-and-declarations skeleton with bodies elided and error lines preserved, falling back to the original head pruning. The gate is independent of every profile and gated on exact tokenizer measurement.
+- Settings-UI toggle for the gate in the selector settings section, with Simplified Chinese and English copy.
+- Browser/runtime decode parity for the new section, confirm-on-write contract tests for `saveCodeSkeleton`, and a full-document parity matrix extension.
+
+### Changed
+
+- Added an ESLint flat-config baseline (`pnpm lint`, enforced in CI) and a `pnpm test:watch` TDD loop; removed dead imports and hardened two error paths surfaced by the lint baseline.
+- This repository is now maintained as an improved fork of `WilliamShi666/dsh-context-compression-selector`; documentation ships in English, Simplified Chinese, Japanese, and Korean.
+
+## 0.1.0 - 2026-09-03
+
+### Added
+
+- Stable release of DeepSeek V4 Flash Vision tokenizer integration for `deepseek-v4-flash-vision-exp`, including exact text counting and bounded image-token estimates.
+- User-configurable model-driven Auto Compact threshold in the selector settings section.
+- Auto Compact threshold linkage for each standard profile's History / micro-compact watermarks and related compression parameters.
+
+### Changed
+
+- The threshold editor now uses one direct numeric input; the slider and fixed quick-value buttons were removed.
+- Runtime session-event access supports both the established Harness `events` accessor and the newer `snapshotEvents()` public API.
+
+## 0.1.0-beta.4 - 2026-09-02
+
+### Fixed
+
+- Support the official DeepSeek Harness `dsh-v0.1.2-alpha.5` public API while retaining compatibility with the existing `0.1.1-rc.2` peer range. The plugin now owns the two small immutable-value helpers that the newer Harness no longer exports, and uses the same public `context-compression` namespace literal accepted by both Settings implementations. No Harness core code is modified.
+
+## 0.1.0-beta.3 - 2026-09-01
+
+### Scope
+
+This is a staged release. Exact **text-class** token counting for `deepseek-v4-flash-vision-exp`, best-effort bounded **vision-class image** estimates, and the Auto Compact threshold/UI/audit work are delivered. Exact image measurement remains **BLOCKED upstream**: the current measurement seam exposes neither the adapter's projected request-image dimensions nor the absolute serialized position, so estimates cannot be promoted to `exact-tokenizer`.
+
+### Added
+
+- DeepSeek V4 Flash Vision support for `deepseek-v4-flash-vision-exp` via a separately bundled official tokenizer pinned at `deepseek-ai/DeepSeek-V4-Flash-Vision-Exp` revision `6821d6ad3681a4b137b066b76094fa82ebd0a380`. Text, reasoning, tool-call arguments, and pure-text tool results are counted exactly; image-bearing tool-result candidates stay fail-open.
+- Vision image-token arithmetic ported line-by-line from the official `inference/image_processor.py` (patch size 14, downsample 3, 384-token cap, min pixels 147456, 8:1 aspect clamp, and position-dependent alignment padding), validated against golden fixtures generated by executing the official Python implementation. Valid intrinsic dimensions now produce `tokenizer-estimate` at the midpoint of all four alignment residues with a 384-token per-image upper bound; malformed or unevaluable dimensions use a documented 256-token fallback. Mixed text/image surfaces aggregate exact text and estimated images without promoting them to exact.
+- `autoCompact.thresholdPercent` setting (default 80, integer 50–90, step 1) with one shared validation contract across the settings UI, the persisted schema, and the runtime resolver. The editor lives inside the context-compression selector settings section.
+- Standard-profile History linkage to the Auto Compact watermark: `A = floor(C × a)` rescales the History trigger, minimum reclaim, and recent-token tail; `D = floor(A × 0.875)` replaces the fixed 0.7 capacity-pressure ratio as the micro-compact last-chance gate; one batch must justify its cache break by pulling the complete request back below the deadline. Defaults at 80% reproduce the previous numbers exactly.
+- The preset overlay writes the saved threshold into the generated `compaction-basic` composition as `thresholdRatio` (with `retainRatio` pinned at 0.16) and, from the same read, into the plugin runtime's deployment config as `autoCompactThresholdPercent`, so one standing generation never runs Auto Compact and micro compact on two different thresholds. Any generation-identity change — threshold, source, or module paths, including equal-length ones — produces a new standing composition generation. Deterministic identity-derived stamps use an 8-hex whole-second window; equal-prefix identities can collide in that first window on a coarse filesystem, so the overlay observes the staging file's real `mtimeMs+size` key and escalates to later hash windows before the atomic rename. Content, permissions, and the final unique stamp are complete before publication; already-running sessions keep their frozen policy.
+- `policy-resolved` audits now record the Auto Compact coordination facts (threshold percent, `A`, `D`, parameter source — including `deployment-override`/`mixed` when deployment config replaces linked History watermarks), the routed provider/model, and the bundled tokenizer identity.
+- Persisted settings reject present-but-invalid sections (`profile: null`, `custom: null`, own-property `undefined`) before any schema default can absorb them; a malformed stored document freezes the session losslessly (`profile: off`, audited as `settingsInvalidFallback: lossless-off`) instead of silently enabling the lossy Balanced default. The browser decoder applies the same rule and canonicalizes legacy Custom v1/v2 documents to the same v3 document the runtime resolver produces.
+- The History planner returns a discriminated outcome, and `component-evaluation` audits distinguish the full skip taxonomy: `below-profile-trigger`, `below-micro-deadline`, `exact-tokenizer-unavailable`, `no-safe-candidates` (only recovery-tool output or already-cleared results), `protected-working-set` (everything inside the protected tail), `insufficient-reclaim` and `cannot-reach-deadline-target` (with the reached/required token numbers), `adaptive-cost-rejected`, and `recovery-tool-unavailable`.
+
+### Known limitations
+
+- Images never claim exact counts. The official expansion depends on the absolute prompt position (system prompt, chat-template framing, adapter image handles) and on the adapter's final request-image projection (including per-route `imagePixelBudget`/`imageDetail` overrides and byte-cap reprojection), none of which is exposed through the current measurement seam. Intrinsic/default estimates may therefore differ materially from provider accounting. Upstream capability requests remain projected request-image dimensions and the absolute serialized position exposed to token-meter extensions.
+- History skips the whole batch whenever any tool-result candidate lacks an exact count, including image-bearing candidates, even though sibling text candidates are individually exact.
+- Custom remains manual token mode; its History parameters do not follow the Auto Compact watermark.
+- A vision token breakdown UI is not shipped; image estimates and the intrinsic alignment diagnostic are available on the measured token view, while lossy rewrite proofs still require exact counts.
+
+### Deferred
+
+- Audit `modality` field and the tokenizer artifact SHA-256 inside audit records (the audits already carry the routed provider/model and tokenizer identity).
+- Publishing the (now complete) runtime skip-reason taxonomy as a user-facing documentation table.
+- Custom-profile display of the A/D watermarks and an above-D warning; Custom remains fully manual.
+- Vision token breakdown UI and promotion of image estimates to exact measurement.
+
+## 0.1.0-beta.2 - 2026-08-28
+
+### Fixed
+
+- Resolve the official DeepSeek V4 Flash tokenizer route so Fresh and Aggregate can evaluate tool results for the supported V4 models.
+- Run Cache Strict History at the real request boundary once its configured capacity-pressure condition is met; trigger the capacity condition at 70% routed-context utilization.
+- Disable Harness-native head/middle/tail tool-result pruning whenever a selector profile is active, leaving the selector as the sole tool-result compactor.
+
+### Changed
+
+- Protect the newest 10 agent tool calls and a 64,000-token tool-result tail window before History/microcompact rewrites older results.
+
+## 0.1.0-beta.1 - 2026-08-27
+
+### Added
+
+- One-install DeepSeek Harness Product Bundle backed by a separate exact-version runtime package.
+- Web profile selector with preset-stable settings and an explicit built-in Minimal exception.
+- Fresh, Aggregate, routine/capacity-aware History, Native tool-result pruning, and default-off Custom TailTrim.
+- Standard-event TailTrim protocol using `compaction/prune` plus recoverable `user/message` replacement.
+- Plugin-owned `context_compression_retrieve` recovery tool.
+- Structured, content-free policy, evaluation, rewrite, failure, and Native auto-compact audit records.
+- Pinned official DeepSeek V4 tokenizer assets with runtime SHA-256 validation and upstream license.
+- Public-API component E2E, preset/Minimal, and parent/fork/spawn cache-prefix regression tests.
+
+### Compatibility
+
+- Verified against DeepSeek Harness `dsh-v0.1.1-rc.2` public packages.
+- Exact tokenizer mapping is currently limited to `deepseek-v4-flash` and `deepseek-v4-pro`.
+
+### Known limitations
+
+- Adaptive ordinary History fails closed when public request-level route/cache evidence is incomplete; capacity pressure remains a separate safety override.
+- Cache-prefix tests prove native fork inheritance and identical serialized prefixes, not a provider-specific cache allocation or a guaranteed DeepSeek cache hit.
+- Settings snapshots and first-exposure decisions are process-local to the mounted runtime.

package/CHANGELOG.zh.md

@@ -1,36 +1,64 @@
-# 更新日志（fork 新增条目）
-
-> 完整历史（含上游 0.1.0 及更早版本）见 [CHANGELOG.md](CHANGELOG.md)。本文件只翻译本 fork 的新增条目。 · [English](CHANGELOG.md) · [日本語](CHANGELOG.ja.md) · [한국어](CHANGELOG.ko.md)
-
-## Unreleased（compat/0.1.5 分支）
-
-### Changed
-
-- runtime 包并入 selector 包：一次安装即可获得完整栈，仓库根目录即为安装面
-  （`name`、`main`、`types`、`exports`（含 `./pruner`、`./invariant`）、`dependencies`、`dsh`），
-  工具链、脚本与 CI 一并收敛为单包。已真机验证的 estimator-catalog 路由注册（双前缀、受保护的
-  双通道激活、按请求解析服务、可检索的生命周期日志）重放到本线，并新增宿主侧守门；`ab2175a`
-  降级为 `z.any()` 的 settings schema 已还原，每日 Custom 默认值重新下发。
-- 在本分支适配官方 DeepSeek Harness `v0.1.5-rc.2`。全部 `@deepseek-ai/dsh-*` 开发依赖与 e2e 官方宿主清单从 `0.1.1-rc.2` 升至 `0.1.5-rc.2`（cordis `4.0.2`、schemastery `3.18.2`），含新的拆分包（`dsh-session-projection`、`dsh-session-persistence`、`dsh-atomic-write`、`dsh-home-paths`、`dsh-sandbox` 等）与 `dsh-client-store` 客户端栈。
-- Surface 替换操作改用 v3 的 `startSeq`/`endSeq` 形状与品牌化 `SessionSeq`；`compaction/prune` 清单保留持久化的 `start`/`end` 字段。surface node 事件改为按 seq 查找而非数组下标。
-- 客户端 bundle 不再引用已移除的 `@deepseek-ai/dsh-client-runtime`：settings 类型改自 `@deepseek-ai/dsh-client-ui-settings`，会话 hooks 合并自 `@deepseek-ai/dsh-client-ui-session`。两份 package manifest 与 `dsh.plugin.json` 声明 `engines.dsh >=0.1.5-alpha.1 <0.2.0-0`。
-- Harness 0.1.5 不再向浏览器暴露会话 `agentPreset`，客户端无法再识别 Minimal 会话；选择器保持可选，旧的不可用横幅不再出现。
-- 测试套件按 0.1.5 语义更新：cordis 插件启动需要 `.await()`，Token Meter 需要预先挂载 `SessionProjectionRegistry`，assistant 事件携带 `stream: []`，settings 命名空间为普通字符串。
-
-### 修复
-
-- 估计器卡片在 Harness 宿主通道上不再要求 API Key。选择宿主通道后只显示实时供应商/模型下拉框，并标出当前真正生效的路由（显式覆盖优先，否则跟随会话默认模型）；既不显示密钥输入框，也不再有第二个手填模型输入——端点地址、模型文本框与只写密钥均只属于直连端点通道。
-- `presetOptions` 改为按路径写入。此前整段写入会替换整个分节，导致再改动估计器的任何一个字段（供应商、模型、端点）都会删掉 `estimatorMode` 及其余全部覆盖值——估计器被静默关回关闭状态，而面板却报告保存成功。现在每个字段只写自己，`undefined` 只清除指名的那一个字段，且 confirm-on-write 校验的是同一组字段而非仅校验通道。
-- 新增回归覆盖：`packages/selector/tests/preset-options-write.client.spec.ts`（按路径写入、保留同级字段、显式清除、空改动不写、未提交写入的报错）与 `packages/selector/tests/estimator-channel.client.spec.tsx`（各通道字段、目录下拉框、手填回退）。
-
-
-### 新增
-
-- 正交的代码骨架压缩门（`codeSkeleton.enabled`，默认关闭）：超大源码类工具结果首次曝光时，可保留导入与声明的骨架——省略函数体并保留错误行——失败时回退到原头部裁剪。这道门独立于所有 Profile，且以精确 tokenizer 测量为前提。
-- 选择器设置区内新增该门的开关，附简体中文与英文文案。
-- 新增段的浏览器/运行时解码对齐测试、`saveCodeSkeleton` 的 confirm-on-write 契约测试，以及全文档 parity 矩阵扩展。
-
-### 变更
-
-- 新增 ESLint 平铺配置基线（`pnpm lint`，CI 同步强制）与 `pnpm test:watch` TDD 环路；清理死导入，并修复 lint 基线暴露的两处错误处理路径。
-- 本仓库现为 `WilliamShi666/dsh-context-compression-selector` 的改进版 fork；文档提供英、简中、日、韩四种语言。
+# 更新日志（fork 新增条目）
+
+> 完整历史（含上游 0.1.0 及更早版本）见 [CHANGELOG.md](CHANGELOG.md)。本文件只翻译本 fork 的新增条目。 · [English](CHANGELOG.md) · [日本語](CHANGELOG.ja.md) · [한국어](CHANGELOG.ko.md)
+
+## 0.5.0 - 2026-09-20
+
+### Added
+
+- 建议型相关度 advisor（仅统计与建议，默认关闭）：每个 turn 边界以 fire-and-forget 方式
+  运行一次 pass——从最近的 `todo/write` 事件总结尾部任务语义（无 todolist 时回退到最近
+  用户文本）、对历史 tool-result 候选做"内容+注释语义 ↔ 当前任务"的增量相关度打分、并
+  计算前缀腐化度（prefix-decay，按 characterPressure 加权的相关度均值取反）。低相关的
+  旧段标记为 `recertified`，仅作为后续 history 激进化的建议输入——本轮没有任何决策路径
+  消费它，且 advisor 输出绝不抑制、延迟或改写任何本应落地的 reduction（有专项不变量测试
+  钉死）。经 `presetOptions.advisor*` settings 键配置（`advisorMode` `''|'host'|'direct'`，
+  默认 `''`；direct 通道复用 estimator 端点；`SideChannel` 新增可选 overrides 参数，
+  共享传输层而不共享配置）。可观测性：新增 `advisor-outcome` 审计记录（content-free，
+  每阶段一条：summary / scoring / decay）与只读 HTTP 路由
+  `GET .../advisor-report?sessionId=`（部署级 opt-in 开关 `advisorReportRoute`，与 review
+  路由同骨架）。本轮刻意不提供客户端 UI。
+
+## 0.4.0 - 2026-09-20
+
+### Fixed
+
+- 插件不再依赖路由 model id：全部规划闸门改按字符基准决策（Unicode code points，
+  经 `characterPressure` / `pressureCost`），不再以 exact tokenizer 计数为前提，
+  因此未内建 tokenizer 的路由（线上 `deepseek-flash`）重新能落地改写而不是静默跳过。
+  token 阈值键名与数值全部保留（按既有 4.0 字符/token 约定换算，冻结 profile 基线零改动）；
+  token 数值降级为遥测，由 rewrite 审计记录新增的 `measurementBasis` 字段如实区分
+  （`exact-tokenizer` 与 `characters`，派生时写 `tokenizerId: 'characters'` /
+  `tokenizerRevision: 'chars-per-token-4.0'`）。回滚：确认无后续改动依赖本提交后再执行
+  `git revert 7a1972a` 整体恢复旧闸门。
+
+### Changed
+
+- runtime 包并入 selector 包：一次安装即可获得完整栈，仓库根目录即为安装面
+  （`name`、`main`、`types`、`exports`（含 `./pruner`、`./invariant`）、`dependencies`、`dsh`），
+  工具链、脚本与 CI 一并收敛为单包。已真机验证的 estimator-catalog 路由注册（双前缀、受保护的
+  双通道激活、按请求解析服务、可检索的生命周期日志）重放到本线，并新增宿主侧守门；`ab2175a`
+  降级为 `z.any()` 的 settings schema 已还原，每日 Custom 默认值重新下发。
+- 在本分支适配官方 DeepSeek Harness `v0.1.5-rc.2`。全部 `@deepseek-ai/dsh-*` 开发依赖与 e2e 官方宿主清单从 `0.1.1-rc.2` 升至 `0.1.5-rc.2`（cordis `4.0.2`、schemastery `3.18.2`），含新的拆分包（`dsh-session-projection`、`dsh-session-persistence`、`dsh-atomic-write`、`dsh-home-paths`、`dsh-sandbox` 等）与 `dsh-client-store` 客户端栈。
+- Surface 替换操作改用 v3 的 `startSeq`/`endSeq` 形状与品牌化 `SessionSeq`；`compaction/prune` 清单保留持久化的 `start`/`end` 字段。surface node 事件改为按 seq 查找而非数组下标。
+- 客户端 bundle 不再引用已移除的 `@deepseek-ai/dsh-client-runtime`：settings 类型改自 `@deepseek-ai/dsh-client-ui-settings`，会话 hooks 合并自 `@deepseek-ai/dsh-client-ui-session`。两份 package manifest 与 `dsh.plugin.json` 声明 `engines.dsh >=0.1.5-alpha.1 <0.2.0-0`。
+- Harness 0.1.5 不再向浏览器暴露会话 `agentPreset`，客户端无法再识别 Minimal 会话；选择器保持可选，旧的不可用横幅不再出现。
+- 测试套件按 0.1.5 语义更新：cordis 插件启动需要 `.await()`，Token Meter 需要预先挂载 `SessionProjectionRegistry`，assistant 事件携带 `stream: []`，settings 命名空间为普通字符串。
+
+### 修复
+
+- 估计器卡片在 Harness 宿主通道上不再要求 API Key。选择宿主通道后只显示实时供应商/模型下拉框，并标出当前真正生效的路由（显式覆盖优先，否则跟随会话默认模型）；既不显示密钥输入框，也不再有第二个手填模型输入——端点地址、模型文本框与只写密钥均只属于直连端点通道。
+- `presetOptions` 改为按路径写入。此前整段写入会替换整个分节，导致再改动估计器的任何一个字段（供应商、模型、端点）都会删掉 `estimatorMode` 及其余全部覆盖值——估计器被静默关回关闭状态，而面板却报告保存成功。现在每个字段只写自己，`undefined` 只清除指名的那一个字段，且 confirm-on-write 校验的是同一组字段而非仅校验通道。
+- 新增回归覆盖：`packages/selector/tests/preset-options-write.client.spec.ts`（按路径写入、保留同级字段、显式清除、空改动不写、未提交写入的报错）与 `packages/selector/tests/estimator-channel.client.spec.tsx`（各通道字段、目录下拉框、手填回退）。
+
+
+### 新增
+
+- 正交的代码骨架压缩门（`codeSkeleton.enabled`，默认关闭）：超大源码类工具结果首次曝光时，可保留导入与声明的骨架——省略函数体并保留错误行——失败时回退到原头部裁剪。这道门独立于所有 Profile，且以精确 tokenizer 测量为前提。
+- 选择器设置区内新增该门的开关，附简体中文与英文文案。
+- 新增段的浏览器/运行时解码对齐测试、`saveCodeSkeleton` 的 confirm-on-write 契约测试，以及全文档 parity 矩阵扩展。
+
+### 变更
+
+- 新增 ESLint 平铺配置基线（`pnpm lint`，CI 同步强制）与 `pnpm test:watch` TDD 环路；清理死导入，并修复 lint 基线暴露的两处错误处理路径。
+- 本仓库现为 `WilliamShi666/dsh-context-compression-selector` 的改进版 fork；文档提供英、简中、日、韩四种语言。

package/README.ja.md

@@ -47,7 +47,7 @@
 
 ## インストール
 
-ソースからビルドしてインストールします（本フォークはまだ npm に公開していません。内部パッケージ名は意図的にアップストリームのままです）：
+ソースからビルドしてインストールします —— 本フォークは npm にも `dsh-context-compression-improved` として公開済みです（dist-tag `dsh-0.1.5`）。内部パッケージ名は意図的にアップストリームのままです：
 
 ```sh
 git clone https://github.com/drscrewdriver/dsh-context-compression-improved.git

package/README.ko.md

@@ -47,7 +47,7 @@
 
 ## 설치
 
-소스에서 빌드하여 설치합니다이포크는 아직 npm에 게시되지 않았습니다. 내부 패키지 이름은 의도적으로 업스트림과 동일하게 유지됩니다):
+소스에서 빌드하여 설치합니다 —— 이 포크는 npm에도 `dsh-context-compression-improved`로 게시되어 있습니다(dist-tag `dsh-0.1.5`). 내부 패키지 이름은 의도적으로 업스트림과 동일하게 유지됩니다:
 
 ```sh
 git clone https://github.com/drscrewdriver/dsh-context-compression-improved.git

package/README.md

@@ -47,7 +47,7 @@ Choose a compression profile, set the Auto Compact trigger level, and toggle cod
 
 ## Install
 
-Build and install from source (this fork is not yet published to npm; the internal package names intentionally stay upstream's):
+Build and install from source — the fork is also published to npm as `dsh-context-compression-improved` (dist-tag `dsh-0.1.5`). The internal package names intentionally stay upstream's:
 
 ```sh
 git clone https://github.com/drscrewdriver/dsh-context-compression-improved.git

package/README.zh.md

@@ -47,7 +47,7 @@
 
 ## 安装
 
-从源码构建并安装（本 fork 尚未发布 npm 包；内部包名有意保持与上游一致）：
+从源码构建并安装 —— 本 fork 亦已发布到 npm，包名为 `dsh-context-compression-improved`（dist-tag `dsh-0.1.5`）；内部包名有意保持与上游一致：
 
 ```sh
 git clone https://github.com/drscrewdriver/dsh-context-compression-improved.git

package/docs/installation.ja.md

@@ -2,8 +2,8 @@
 
 > [English](installation.md) · [中文](installation.zh.md) · [日本語](installation.ja.md) · [한국어](installation.ko.md)
 
-このガイドではソースからフォークをインストールします。フォークはまだ npm に公開されておらず、
-パッケージ名は意図的に上流と同一です（`dsh-context-compression-improved` の単一パッケージで、
+このガイドではソースからフォークをインストールします。フォークは npm にも公開済みです（dist-tag
+`dsh-0.1.5`）。パッケージ名は意図的に上流と同一です（`dsh-context-compression-improved` の単一パッケージで、
 以前は別パッケージだった runtime も同梱されます）。
 
 ## 前提条件

package/docs/installation.ko.md

@@ -2,8 +2,8 @@
 
 > [English](installation.md) · [中文](installation.zh.md) · [日本語](installation.ja.md) · [한국어](installation.ko.md)
 
-이 가이드는 소스에서 포크를 설치합니다. 포크는 아직 npm에 게시되지 않았으며, 패키지 이름은
-의도적으로 업스트림과 동일합니다(`dsh-context-compression-improved` 단일 패키지이며,
+이 가이드는 소스에서 포크를 설치합니다. 포크는 npm에도 게시되어 있습니다(dist-tag
+`dsh-0.1.5`). 패키지 이름은 의도적으로 업스트림과 동일합니다(`dsh-context-compression-improved` 단일 패키지이며,
 예전에 별도 패키지였던 runtime이 함께 포함됩니다).
 
 ## 사전 요구 사항