ds4-context-engine 0.4.6 → 0.4.7

package/README.md

@@ -16,7 +16,7 @@ bounded active context with provenance
 Pi provider
 ```
 
-> **Project status:** The coordinated `0.4.0` release adds `storage.scope: "agent" | "project"`, now defaulting to per-project SQLite projections with shared token calibration in the agent database (opt out with `storage.scope: "agent"`). The opt-in BPE estimation and bounded auto-tuning from `0.3.10` keep `chars-v1` and disabled auto-tuning as their defaults. The bounded compaction controls from `0.3.9` remain in place; canonical history, SQLite schema 16 and runtime contracts are unchanged. Pi remains pinned to `0.84.3`. Patch `0.4.1` states the contiguous-span rule for compaction summaries in the summarizer prompt while leaving validation strictness, the eight-bullet repair bound and every provider-facing default unchanged. Patch `0.4.2` adds class-only diagnostics for rejected exact-value spans: the existing `custom_fallback` warning carries `unsupportedSpanClasses` as class names and counters, never span text, with validation, repair bounds and provider-facing defaults unchanged. Patch `0.4.3` makes those diagnostics interpretable: every distinct span receives the cheap transformed-form lookups before the bounded near-miss analysis starts, each near-miss candidate may spend only an equal share of what remains, and spans that were not analysed report `not-classified-length`, `not-classified-partial` or `not-classified-budget` instead of `no-near-miss`. Patch `0.4.4` accepts a backticked exact value whose canonical JSON-escaped rendering is literally present in the evidence — the decoded rendering a summarizer produces when it quotes serialized JSON — while absent values, the reverse escape direction, span composition and single-character variants stay rejected; the diagnostics probe budget rises from 4000 to 24000 evidence-source scans. Patch `0.4.5` grades the summarizer quoting fallback: the prompt requires one contiguous excerpt per backticked span, tells the model to backtick only the fragments that are themselves contiguous or to keep the fact as ordinary text without backticks instead of composing a span, and reserves bullet omission for facts with no support in the evidence; diagnostics split composition into `composed-adjacent-present` (both parts next to each other in one source, so the span may be a re-rendering of a contiguous region) and `composed-two-present-parts` (parts found at unrelated positions), with validation strictness, the eight-bullet and 25% repair bounds and every provider-facing default unchanged. Patch `0.4.6` makes an engine/core artifact mismatch visible instead of a missing function: the core exports `CORE_VERSION` and the engine verifies at session start and at every compaction attempt that the loaded core matches its own version and exposes the entry points it calls, so a core rebuilt under a running Pi — which a `/reload` does not pick up — reports one actionable line, keeps the DS4 compaction layer inert instead of failing mid-generation, and never blocks Pi; validation strictness, repair bounds and every provider-facing default stay unchanged. See the [0.4.6 release record](docs/releases/0.4.6.md), the [0.4.5 release record](docs/releases/0.4.5.md), the [0.4.4 release record](docs/releases/0.4.4.md), the [0.4.3 release record](docs/releases/0.4.3.md), the [0.4.2 release record](docs/releases/0.4.2.md), the [0.4.1 release record](docs/releases/0.4.1.md) and the [0.4.0 release record](docs/releases/0.4.0.md), [ADR 067](docs/ADR/067-core-version-guard.md), [ADR 066](docs/ADR/066-quoting-downgrade-and-span-adjacency.md), [ADR 065](docs/ADR/065-exact-value-escaped-equivalence.md), [ADR 064](docs/ADR/064-per-project-databases-with-shared-calibration.md) and [model-awareness validation](docs/MODEL_AWARENESS.md).
+> **Project status:** The coordinated `0.4.0` release adds `storage.scope: "agent" | "project"`, now defaulting to per-project SQLite projections with shared token calibration in the agent database (opt out with `storage.scope: "agent"`). The opt-in BPE estimation and bounded auto-tuning from `0.3.10` keep `chars-v1` and disabled auto-tuning as their defaults. The bounded compaction controls from `0.3.9` remain in place; canonical history, SQLite schema 16 and runtime contracts are unchanged. Pi remains pinned to `0.84.3`. Patch `0.4.1` states the contiguous-span rule for compaction summaries in the summarizer prompt while leaving validation strictness, the eight-bullet repair bound and every provider-facing default unchanged. Patch `0.4.2` adds class-only diagnostics for rejected exact-value spans: the existing `custom_fallback` warning carries `unsupportedSpanClasses` as class names and counters, never span text, with validation, repair bounds and provider-facing defaults unchanged. Patch `0.4.3` makes those diagnostics interpretable: every distinct span receives the cheap transformed-form lookups before the bounded near-miss analysis starts, each near-miss candidate may spend only an equal share of what remains, and spans that were not analysed report `not-classified-length`, `not-classified-partial` or `not-classified-budget` instead of `no-near-miss`. Patch `0.4.4` accepts a backticked exact value whose canonical JSON-escaped rendering is literally present in the evidence — the decoded rendering a summarizer produces when it quotes serialized JSON — while absent values, the reverse escape direction, span composition and single-character variants stay rejected; the diagnostics probe budget rises from 4000 to 24000 evidence-source scans. Patch `0.4.5` grades the summarizer quoting fallback: the prompt requires one contiguous excerpt per backticked span, tells the model to backtick only the fragments that are themselves contiguous or to keep the fact as ordinary text without backticks instead of composing a span, and reserves bullet omission for facts with no support in the evidence; diagnostics split composition into `composed-adjacent-present` (both parts next to each other in one source, so the span may be a re-rendering of a contiguous region) and `composed-two-present-parts` (parts found at unrelated positions), with validation strictness, the eight-bullet and 25% repair bounds and every provider-facing default unchanged. Patch `0.4.6` makes an engine/core artifact mismatch visible instead of a missing function: the core exports `CORE_VERSION` and the engine verifies at session start and at every compaction attempt that the loaded core matches its own version and exposes the entry points it calls, so a core rebuilt under a running Pi — which a `/reload` does not pick up — reports one actionable line, keeps the DS4 compaction layer inert instead of failing mid-generation, and never blocks Pi; validation strictness, repair bounds and every provider-facing default stay unchanged. Patch `0.4.7` stops the recurrent fail-closed fallback at its source: when the summarizer re-renders a value the evidence holds in another form — JSON-escaped or unescaped, collapsed whitespace, stripped typographic characters, or two parts adjacent in one source — the repair retracts only the backticks and keeps the fact, so those spans no longer consume the eight-bullet bound; invented values, unrelated compositions, one-character deviations, case changes and unanalysed spans keep the existing fail-closed bullet removal, validation strictness is unchanged, and both effects are recorded as counters (`unsupported-exact-bullets-pruned`, `unsupported-exact-spans-unquoted`). See the [0.4.7 release record](docs/releases/0.4.7.md), the [0.4.6 release record](docs/releases/0.4.6.md), the [0.4.5 release record](docs/releases/0.4.5.md), the [0.4.4 release record](docs/releases/0.4.4.md), the [0.4.3 release record](docs/releases/0.4.3.md), the [0.4.2 release record](docs/releases/0.4.2.md), the [0.4.1 release record](docs/releases/0.4.1.md) and the [0.4.0 release record](docs/releases/0.4.0.md), [ADR 068](docs/ADR/068-downgrade-rendering-equivalent-spans.md), [ADR 067](docs/ADR/067-core-version-guard.md), [ADR 066](docs/ADR/066-quoting-downgrade-and-span-adjacency.md), [ADR 065](docs/ADR/065-exact-value-escaped-equivalence.md), [ADR 064](docs/ADR/064-per-project-databases-with-shared-calibration.md) and [model-awareness validation](docs/MODEL_AWARENESS.md).
 
 **Current compaction defaults:** `compaction.directUpdate=true`, `compaction.inputBudget="context"`, `compaction.segmentTargetTokens=30000`, `compaction.maxRequestInputTokens=64000`, `compaction.maxOperationInputTokens=2000000`, `compaction.maxConcurrentSegments=2`. Every DS4 provider attempt is bounded by the effective request limit, and the operation limit includes retries; `inputBudget="summary"` remains an explicit throughput-oriented opt-in. Existing compaction/master switches still apply. See [latency controls and compatibility](docs/COMPACTION.md#latency-controls). No real-provider speedup is claimed from mock tests. The five optional editing/reading/artifact/job features introduced in `0.3.4` remain default-off.
 
@@ -515,6 +515,7 @@ scripts             package and release-readiness checks
 - [Roadmap 0.2.0](docs/ROADMAP_0.2.0.md)
 - [Release process](docs/RELEASING.md)
 - [0.2.0 release readiness](docs/RELEASE_READINESS_0.2.0.md)
+- [0.4.7 release notes](docs/releases/0.4.7.md)
 - [0.4.6 release notes](docs/releases/0.4.6.md)
 - [0.4.5 release notes](docs/releases/0.4.5.md)
 - [0.4.4 release notes](docs/releases/0.4.4.md)

package/docs/ADR/068-downgrade-rendering-equivalent-spans.md

@@ -0,0 +1,75 @@
+# 068 — Downgrade rendering-equivalent spans instead of spending the bullet budget
+
+**Date:** 2026-09-27
+**Status:** Accepted
+**Related:** [065](065-exact-value-escaped-equivalence.md), [066](066-quoting-downgrade-and-span-adjacency.md), [067](067-core-version-guard.md)
+
+## Context
+
+Five coordinated releases reduced, but never removed, the recurrent
+`compaction.custom_fallback` with `unsupported-exact-value;
+repair=too-many-bullets`. The affected-bullet series from production was 30/20 →
+23/19 → 19/15 → 17/11 → 16/12, and the class-only reports attributed the majority
+of the rejected spans to rendering or composition, never to invention:
+`escaped-form-present` 11 of 16 in the first interpretable run, then composition
+9 of 14 with 2 one-character deviations, 2 absences and 1 over-length span in the
+next.
+
+Each patch removed one class — escaped equivalence in 0.4.4, prompt grading in
+0.4.5 — while the bound stayed exhausted by the remaining ones. The repair was
+treating a *re-rendered* value exactly like an *invented* one: it deleted whole
+bullets, and beyond eight bullets it refused to repair at all and handed the
+session to Pi. The information in those spans is present in the evidence; only
+the verbatim surface form is not. Discarding a supported fact, or failing, is the
+wrong response to a rendering difference.
+
+## Decision
+
+- Validation is unchanged. A backticked value is still accepted only when it
+  occurs literally in the evidence or as its canonical JSON-escaped rendering.
+  Nothing that was rejected before becomes an accepted exact value.
+- The bounded repair splits the rejected spans into two groups.
+  - **Rendering-equivalent** — `escaped-form-present`, `unescaped-form-present`,
+    `whitespace-collapsed-present`, `typographic-variant-present`,
+    `composed-adjacent-present`: DS4 removes only the two backticks. The text
+    stays, the fact stays, the exact-value claim is retracted, and the result is
+    re-validated. This applies deterministically the ladder the 0.4.5 prompt asks
+    the model to follow, instead of depending on the model complying.
+  - **Everything else** — `single-deletion-present`,
+    `composed-two-present-parts`, `case-variant-present`, `no-near-miss` and
+    every `not-classified-*`: the existing fail-closed treatment, whole-bullet
+    removal within the eight-bullet and 25% bounds, otherwise fallback to Pi.
+- The excluded relations are excluded because prose would hide a wrong claim
+  rather than a re-rendered one: a case change can alter an identifier, a
+  one-character deviation is indistinguishable from a wrong value, and
+  `composed-two-present-parts` is precisely the association the evidence does not
+  contain ([ADR 066](066-quoting-downgrade-and-span-adjacency.md)).
+  `not-classified-*` means *not analysed*, which is not evidence of support, so
+  those spans stay fail-closed as well.
+- The eight-bullet and 25% bounds are not raised. They now count only the bullets
+  that still need removal, because a downgraded span costs no bullet.
+- Both effects are recorded as counters, never as span text:
+  `unsupported-exact-bullets-pruned` for removed bullets and
+  `unsupported-exact-spans-unquoted` for downgraded spans.
+
+## Consequences
+
+- The dominant production failure mode no longer consumes the bullet bound. In
+  the core fixtures, twelve affected bullets now downgrade to plain text and
+  validate, where the same input previously answered `too-many-bullets`; the
+  integration fixture with eleven affected bullets completes with
+  `validationStatus: "warning"` instead of Pi compacting the session.
+- Fail-closed survives where it matters. An invented value keeps the
+  bullet-removal path, and the same eleven-bullet fixture still answers
+  `repair=too-many-bullets` when the evidence holds the two parts at unrelated
+  positions rather than next to each other.
+- The repair now consumes the class analysis, which is bounded and deterministic
+  but budget-limited (default 24000 evidence-source scans). A span left
+  unanalysed is never downgraded.
+- A downgraded value is still *stated* as prose: DS4 stops asserting exactness it
+  cannot verify, but it does not delete the fact. That is the deliberate trade —
+  a fact with a possibly imperfect surface form beats losing the fact or losing
+  the whole compaction — and it is visible in the recorded counters.
+- The `UnsupportedSpanClassReport` documentation no longer claims the relations
+  are observation-only: they now select the repair treatment. Validation still
+  never consults them.

package/docs/ADR/README.md

@@ -71,5 +71,6 @@ The initial decisions from the development plan are accepted:
 | [065](065-exact-value-escaped-equivalence.md) | Accept canonical JSON-escaped exact values in compaction summary validation | Accepted |
 | [066](066-quoting-downgrade-and-span-adjacency.md) | Grade the summarizer quoting fallback and separate adjacent from unrelated span composition | Accepted |
 | [067](067-core-version-guard.md) | Detect an engine/core artifact mismatch before compaction runs | Accepted |
+| [068](068-downgrade-rendering-equivalent-spans.md) | Downgrade rendering-equivalent spans instead of spending the bullet budget | Accepted |
 
 Each decision will receive a dedicated record when implementation pressure introduces alternatives or consequences not already covered by the development plan.

package/docs/COMPACTION.md

@@ -32,11 +32,11 @@ Fan-out and fan-in are bounded to 32 segment requests, 64 aggregate requests, an
 ## Critical Exact Values
 ```
 
-Every section must occur once, in order, and contain content or `- None`. DS4 replaces each unique `Files Read` and `Files Modified` section with one exact path per bullet from Pi's sanitized file-operation inventory before validation; missing or duplicate sections still fail. Backticked exact values must occur literally in the serialized segment source, ordered child-summary content, or those known file-operation paths, either as written or in the canonical JSON-escaped rendering of the value. A decoded value whose encoded text is present in the evidence is accepted ([ADR 065](ADR/065-exact-value-escaped-equivalence.md)); the reverse direction — an escaped span whose raw form is present — remains unsupported and is reported as `unescaped-form-present`. A bounded unsupported exact-value bullet is removed as a whole and recorded as a validation warning; unsupported prose, more than eight affected bullets, or removal above 25% still fails closed to Pi. The prompt requires every backticked span to be one contiguous excerpt copied as-is and forbids assembling one span from separately supported values (a setting name with its value, a path with a line range, a command with its flags), and it gives the model a cheaper alternative than composing: backtick only the fragments that are themselves contiguous with the joining text outside the backticks, or write the value as ordinary text without backticks, keeping the bullet. A bullet is omitted only when the fact itself has no support in the evidence ([ADR 066](ADR/066-quoting-downgrade-and-span-adjacency.md)). Every segment is validated independently against only its own sanitized source and deterministic file inventory. Every aggregate is validated independently against only the sanitized content of its ordered children and cumulative deterministic file inventory. A direct update is validated against both the sanitized previous summary and new source, plus cumulative sanitized file evidence; previous-summary-only exact values remain valid evidence. Custom focus instructions are not factual evidence. Any unrepaired failure prevents the whole graph batch from being installed.
+Every section must occur once, in order, and contain content or `- None`. DS4 replaces each unique `Files Read` and `Files Modified` section with one exact path per bullet from Pi's sanitized file-operation inventory before validation; missing or duplicate sections still fail. Backticked exact values must occur literally in the serialized segment source, ordered child-summary content, or those known file-operation paths, either as written or in the canonical JSON-escaped rendering of the value. A decoded value whose encoded text is present in the evidence is accepted ([ADR 065](ADR/065-exact-value-escaped-equivalence.md)); the reverse direction — an escaped span whose raw form is present — remains unsupported and is reported as `unescaped-form-present`. A bounded unsupported exact-value bullet is removed as a whole and recorded as a validation warning, unless every rejected span in it is *rendering-equivalent*: when the evidence holds the same information in a different rendering — JSON-escaped or unescaped, collapsed whitespace, stripped typographic characters, or two parts adjacent in one source — the repair retracts only the two backticks and keeps the text, so the fact survives and the exact-value claim does not ([ADR 068](ADR/068-downgrade-rendering-equivalent-spans.md)). Unsupported prose, more than eight bullets that still need removal, or removal above 25% still fails closed to Pi. The prompt requires every backticked span to be one contiguous excerpt copied as-is and forbids assembling one span from separately supported values (a setting name with its value, a path with a line range, a command with its flags), and it gives the model a cheaper alternative than composing: backtick only the fragments that are themselves contiguous with the joining text outside the backticks, or write the value as ordinary text without backticks, keeping the bullet. A bullet is omitted only when the fact itself has no support in the evidence ([ADR 066](ADR/066-quoting-downgrade-and-span-adjacency.md)). Every segment is validated independently against only its own sanitized source and deterministic file inventory. Every aggregate is validated independently against only the sanitized content of its ordered children and cumulative deterministic file inventory. A direct update is validated against both the sanitized previous summary and new source, plus cumulative sanitized file evidence; previous-summary-only exact values remain valid evidence. Custom focus instructions are not factual evidence. Any unrepaired failure prevents the whole graph batch from being installed.
 
 An unrepaired exact-value failure reports only the stage, issue code, categorical repair status, unsupported-span count, and affected-bullet count. Repair statuses distinguish an unsupported location, more than eight bullets, removal above 25%, and an unexpected invalid second validation. The disputed text is intentionally absent from logs, UI notifications, and diagnostics because it may contain sensitive source material.
 
-The same failure carries a class-only span report on the fallback warning (`unsupportedSpanClasses`): rejected-span count, affected bullets, length buckets, character shapes (spaces, backslashes, escape sequences, separators, quotes, typographic characters, JSON punctuation), and how each distinct span relates to the evidence — escaped or unescaped rendering, collapsed whitespace, case or typographic variant, one-character deletion, two separately present values joined into one span — adjacent in one source with nothing but joining punctuation and spaces between them (`composed-adjacent-present`) or found at unrelated positions (`composed-two-present-parts`) — or no near-miss (every applicable lookup ran and found nothing). The adjacency question separates a join that re-renders a contiguous evidence region from an association the evidence never contains: a joiner gap holds no letters, digits or line breaks, so two parts on separate lines are not adjacent. The report contains class names and counters only, never span text, and the classifier is observation-only: it cannot change validation, repair bounds, or the fail-closed decision. It exists to separate a summarizer that invents values from one whose rendering or composition rules differ from the validation domain, which require opposite fixes. The first production report produced by the 0.4.4 diagnostics attributed 9 of 14 rejected spans to composition, 2 to a one-character deviation, 2 to absence and 1 to the length limit, with no rendering class left at all.
+The same failure carries a class-only span report on the fallback warning (`unsupportedSpanClasses`): rejected-span count, affected bullets, length buckets, character shapes (spaces, backslashes, escape sequences, separators, quotes, typographic characters, JSON punctuation), and how each distinct span relates to the evidence — escaped or unescaped rendering, collapsed whitespace, case or typographic variant, one-character deletion, two separately present values joined into one span — adjacent in one source with nothing but joining punctuation and spaces between them (`composed-adjacent-present`) or found at unrelated positions (`composed-two-present-parts`) — or no near-miss (every applicable lookup ran and found nothing). The adjacency question separates a join that re-renders a contiguous evidence region from an association the evidence never contains: a joiner gap holds no letters, digits or line breaks, so two parts on separate lines are not adjacent. The report contains class names and counters only, never span text, and validation never consults the classifier; the repair uses the same relations to decide which spans are downgraded instead of spending a bullet on them, which is why the eight-bullet bound counts only removals. It exists to separate a summarizer that invents values from one whose rendering or composition rules differ from the validation domain, which require opposite fixes. The first production report produced by the 0.4.4 diagnostics attributed 9 of 14 rejected spans to composition, 2 to a one-character deviation, 2 to absence and 1 to the length limit, with no rendering class left at all.
 
 Three relations mark spans that were *not* analysed, and they must never be read as invention. `not-classified-length` means the span exceeds the near-miss length limit (96 characters); `not-classified-partial` means its share of the budget ran out; `not-classified-budget` means the shared budget was already exhausted. To keep the histogram interpretable, transformed-form lookups cover every distinct span before any near-miss analysis starts, and each near-miss candidate may spend only an equal share of what remains (at least 32 lookups, never more than the budget left). The report also carries `spansClassifiedCheap` (span occurrences attributed by a transformed-form relation), `corpusSources`, `probeBudget` and `probesUsed`, so a run can be read without guessing how much of the budget was consumed. The shared budget defaults to 24000 evidence-source scans, where one lookup scans every corpus source once. `escaped-form-present` is not expected in reports from 0.4.4 on: validation accepts the canonical escaped rendering and the classifier consumes the same predicate, so such spans no longer reach it; the class stays in the taxonomy for compatibility. `classificationComplete` is false when the shared budget or a per-span share stopped an analysis; a `not-classified-length` span does not clear it, because that limit is deterministic rather than a resource shortfall.
 

package/docs/releases/0.4.6.md

@@ -129,9 +129,24 @@ repair bounds or the fail-closed decision changes
 
 ## Publication and registry verification
 
-Published manually in dependency order: `ds4-context-core@0.4.6`, then
-`ds4-context-reference-adapter@0.4.6`, then `ds4-context-engine@0.4.6`, all with
-the default `latest` tag, after `npm run pack:check` on the same commit, followed
-by `npm run registry:check -- 0.4.6` with a fresh npm cache, the annotated tag
-`v0.4.6` and the GitHub Release. No session data, credentials, provider payloads
-or prompt text were read or written while preparing this release.
+Published manually in dependency order from `92912a1`: `ds4-context-core@0.4.6`,
+then `ds4-context-reference-adapter@0.4.6`, then `ds4-context-engine@0.4.6`, all
+with the default `latest` tag, after `npm run pack:check` on the same commit.
+
+The first two `npm run registry:check -- 0.4.6` attempts, each with a fresh npm
+cache, failed with `ETARGET No matching version found for
+ds4-context-core@0.4.6` — the known registry propagation delay after a publish,
+not a packaging fault. Once both `npm view ds4-context-core@0.4.6 version` and
+`npm view ds4-context-engine@0.4.6 version` resolved, the check reported
+"Verified all DS4 registry packages at exact version 0.4.6": all three packages
+install in a clean consumer, the exact adapter/core dependencies resolve, the
+public core and KV exports import, the compiled reference conformance and
+packaged quality corpus run, the `ds4-context-storage` CLI shim responds, and the
+published Pi extension starts against isolated offline RPC state. 
+`npm view <package> dist-tags.latest` resolves to 0.4.6 for all three packages.
+
+Annotated tag `v0.4.6` and the GitHub Release were created from `92912a1`: 
+<https://github.com/Alucard24/ds4-context-engine/releases/tag/v0.4.6>. No session
+data, credentials, provider payloads or prompt text were read or written while
+preparing this release, and no provider call is involved in the release
+procedure.

package/docs/releases/0.4.7.md

@@ -0,0 +1,135 @@
+# Release 0.4.7 — Downgrade rendering-equivalent spans instead of spending the bullet budget
+
+**Coordinated packages:** `ds4-context-core`, `ds4-context-reference-adapter`, and `ds4-context-engine` 0.4.7.
+**Implementation commit:** `1483bce`.
+
+## Summary
+
+Behaviour patch that removes the source of the recurrent fail-closed fallback.
+Until 0.4.6 the repair treated a re-rendered exact value exactly like an invented
+one: it deleted whole bullets, and beyond eight affected bullets it refused to
+repair at all and handed the session to Pi. The class reports had shown for four
+releases that this was the common case — rendering and composition, not
+invention. The repair now retracts only the backticks of a span whose information
+the evidence holds in another rendering, keeps the text and the fact, and
+re-validates. Invented values, unrelated compositions, one-character deviations,
+case changes and unanalysed spans keep the existing fail-closed bullet removal.
+Validation strictness, the eight-bullet and 25% bounds, the fail-closed fallback,
+SQLite schema 16, canonical JSONL history and every provider-facing default are
+unchanged.
+
+## Changes
+
+- `packages/core/src/compaction/summary-contract.ts`:
+  - `RENDERING_EQUIVALENT_RELATIONS` names the relations that mean "the evidence
+    holds this information in a different rendering": `escaped-form-present`,
+    `unescaped-form-present`, `whitespace-collapsed-present`,
+    `typographic-variant-present` and `composed-adjacent-present`.
+  - Deliberately excluded, because prose would hide a wrong claim rather than a
+    re-rendered one: `case-variant-present` (a case change can alter an
+    identifier), `single-deletion-present` (a one-character deviation is
+    indistinguishable from a wrong value), `composed-two-present-parts` (the
+    evidence never contains that association) and every `not-classified-*`
+    relation (*not analysed* is not evidence of support).
+  - `downgradeRenderingEquivalentSpans` removes the two backticks of each
+    rendering-equivalent span, byte-range based and applied after the bullet
+    removals so every span is matched at its final position.
+  - `analyzeUnsupportedExactValueBullets` partitions the rejected spans, applies
+    the unchanged bounds to the ones that still need removal, and reports the
+    new counters. `ExactValuePruneResult` and `ExactValuePruneAttempt` gained
+    `downgradedSpans`, and the attempt status gained `downgraded` and
+    `unrepairable`.
+  - The span classifier is no longer described as observation-only: it is
+    `analyzeSpanClasses` internally, and its relations now also select the repair
+    treatment. Validation still never consults them, and the public
+    `classifyUnsupportedExactValueSpans` report is unchanged.
+- `src/pi-adapter/summary-generator.ts`: the repair outcome is recorded as counts
+  only — `unsupported-exact-bullets-pruned` for removed bullets and the new
+  `unsupported-exact-spans-unquoted` for retracted quotes.
+- `tests/unit/summary-contract.test.ts`: five cases — a composed span with parts
+  adjacent in one source is downgraded and the summary still validates; a span
+  whose whitespace-collapsed and JSON-unescaped renderings are present is
+  downgraded too; unrelated compositions and one-character deviations still cost
+  their bullet; twelve affected bullets downgrade where the same summary without
+  the adjacent rendering still answers `too-many-bullets`; a mixed summary
+  removes only the one bullet that needs it and downgrades the other nine.
+- `tests/integration/compaction.test.ts`: eleven affected bullets complete the
+  compaction with `validationStatus: "warning"` and
+  `validationIssueCodes: ["unsupported-exact-spans-unquoted"]` instead of falling
+  back, and the same fixture with the two parts at unrelated positions still
+  returns `repair=too-many-bullets` with Pi compacting the session.
+- `docs/COMPACTION.md`, `docs/ADR/068-downgrade-rendering-equivalent-spans.md`
+  and the ADR index record the decision.
+
+## Why
+
+The affected-bullet series from production was 30/20 → 23/19 → 19/15 → 17/11 →
+16/12, every run ending in `compaction.custom_fallback` with
+`unsupported-exact-value; repair=too-many-bullets`. The class-only reports
+attributed the rejected spans to rendering or composition in every interpretable
+run: `escaped-form-present` 11 of 16 in the first, then composition 9 of 14 with
+2 one-character deviations, 2 absences and 1 over-length span in the second.
+`no-near-miss` — the class that means invention — was the smallest in both.
+
+Each earlier patch removed one class (escaped equivalence in 0.4.4, prompt
+grading in 0.4.5) while the bound stayed exhausted by the rest, so the fallback
+persisted. The information in those spans was present all along; only the
+verbatim surface form was not, and discarding a supported fact — or losing the
+compaction — is the wrong response to a rendering difference. The repair now
+applies deterministically the ladder the 0.4.5 prompt asks the model to follow,
+instead of depending on the model complying
+([ADR 068](ADR/068-downgrade-rendering-equivalent-spans.md)).
+
+## Privacy and safety
+
+- Only the backticks are removed. Span text is never logged, notified or
+  persisted in diagnostics: the recorded effects are two counters, and the
+  failure path keeps the class-only report.
+- No provider call is added: the downgrade happens after generation, on text the
+  model already produced.
+- The downgraded text is sanitized output that already passed privacy handling;
+  removing backticks does not change its classification.
+
+## Compatibility and persistence
+
+- No configuration key is added or changed. `downgradedSpans` is additive on the
+  repair result, and `unsupported-exact-spans-unquoted` is a new issue code in
+  the recorded node details.
+- The eight-bullet and 25% bounds are not raised: they now count only the bullets
+  that still need removal. A span downgraded in place consumes no bullet.
+- SQLite schema 16, migrations, the Pi JSONL boundary, tool contracts and the
+  reference adapter's public surface are untouched.
+
+## Measured scope and limitations
+
+- Verified by fixtures, not yet by a natural production failure: the first real
+  `compaction.custom_fallback` (or its absence) after updating the failing host
+  remains the end-to-end confirmation.
+- The fallback is still possible — deliberately — when more than eight bullets
+  contain genuinely unsupported spans or when removal would exceed 25% of the
+  summary. Those are the cases where the evidence does not hold the information.
+- A downgraded value is still stated, as prose. DS4 stops asserting exactness it
+  cannot verify but does not delete the fact, and the counters make the trade
+  visible.
+- The repair now consumes the bounded class analysis (default 24000
+  evidence-source scans). A span left unanalysed is never downgraded, so budget
+  exhaustion keeps the previous fail-closed behaviour.
+- `case-variant-present` is intentionally not downgraded, so summaries that only
+  differ by letter case still take the bullet-removal path. If production reports
+  show that class dominating, that is the next measured decision.
+
+## Validation
+
+- `npm run check` on the release commit: builds, `tsc --noEmit`, and
+  **100 test files / 649 tests passed** (7 new: 5 unit cases for the repair rule
+  and 2 integration cases, one of which pins the unchanged fallback on unrelated
+  composition).
+- `npm run pack:check` in a clean consumer: `ds4-context-core@0.4.7`
+  (251 files), `ds4-context-reference-adapter@0.4.7` (7 files) and
+  `ds4-context-engine@0.4.7` (110 files).
+- `npm run quality:compare`: candidate `task-weighted-v0.2-candidate` 0.9875
+  against the frozen baseline `static-ranking-v0.1` 0.808156, unchanged.
+- `npm run schema:context-persistence` (`passed: true`).
+- No provider calls are involved. `jev_verify` is not available in this
+  environment (project verification disabled), so the checks above were run
+  directly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ds4-context-engine",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Non-destructive, provider-independent context management for Pi.",
   "type": "module",
   "license": "MIT",
@@ -63,7 +63,7 @@
     ]
   },
   "dependencies": {
-    "ds4-context-core": "0.4.6",
+    "ds4-context-core": "0.4.7",
     "js-tiktoken": "1.0.21"
   },
   "peerDependencies": {

package/src/pi-adapter/summary-generator.ts

@@ -10,7 +10,9 @@ import {
   classifyUnsupportedExactValueSpans,
   groundSummaryFileSections,
   validateSummary,
+  type ExactValuePruneResult,
   type SummaryValidationInput,
+  type SummaryValidationIssue,
   type SummaryValidationResult,
   type UnsupportedSpanClassReport,
 } from "ds4-context-core/compaction/summary-contract";
@@ -336,14 +338,7 @@ export async function generateValidatedSummary(
         content = pruned.content;
         validation = {
           status: "warning",
-          issues: [
-            ...repairedValidation.issues,
-            {
-              code: "unsupported-exact-bullets-pruned",
-              severity: "warning",
-              message: `Removed ${pruned.removedBullets} bullet(s) containing unsupported exact values`,
-            },
-          ],
+          issues: [...repairedValidation.issues, ...exactRepairIssues(pruned)],
         };
       } else {
         validation = repairedValidation;
@@ -370,6 +365,30 @@ export async function generateValidatedSummary(
   return { content, validation, usage: sumUsage([...retryUsages, response.usage]) };
 }
 
+/**
+ * Record what the exact-value repair did, as counts only: the disputed spans
+ * never reach logs, notifications or diagnostics because they may contain
+ * sensitive source material.
+ */
+function exactRepairIssues(repair: ExactValuePruneResult): SummaryValidationIssue[] {
+  const issues: SummaryValidationIssue[] = [];
+  if (repair.removedBullets > 0) {
+    issues.push({
+      code: "unsupported-exact-bullets-pruned",
+      severity: "warning",
+      message: `Removed ${repair.removedBullets} bullet(s) containing unsupported exact values`,
+    });
+  }
+  if (repair.downgradedSpans > 0) {
+    issues.push({
+      code: "unsupported-exact-spans-unquoted",
+      severity: "warning",
+      message: `Retracted the quoting of ${repair.downgradedSpans} exact value(s) whose evidence rendering differs`,
+    });
+  }
+  return issues;
+}
+
 export function sumUsage(usages: readonly Usage[]): Usage {
   const sum = (read: (usage: Usage) => number): number => usages.reduce((total, usage) => total + read(usage), 0);
   const hasReasoning = usages.some((usage) => usage.reasoning !== undefined);

package/src/pi-adapter/version.ts

@@ -1,4 +1,4 @@
-export const EXTENSION_VERSION = "0.4.6";
+export const EXTENSION_VERSION = "0.4.7";
 export const SUPPORTED_PI_VERSION = "0.84.3";
 export const OBSERVER_PLANNER_VERSION = "observer-model-aware-v1";
 export const PLANNER_VERSION = "managed-learned-ranking-v1";