ds4-context-engine 0.4.4 → 0.4.6

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. See 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 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. 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).
 
 **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,9 @@ 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.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)
 - [0.4.3 release notes](docs/releases/0.4.3.md)
 - [0.4.2 release notes](docs/releases/0.4.2.md)
 - [0.4.1 release notes](docs/releases/0.4.1.md)

package/docs/ADR/066-quoting-downgrade-and-span-adjacency.md

@@ -0,0 +1,77 @@
+# 066 — Grade the summarizer quoting fallback and separate adjacent from unrelated span composition
+
+**Date:** 2026-09-27
+**Status:** Accepted
+**Related:** [061](061-compaction-latency.md), [065](065-exact-value-escaped-equivalence.md)
+
+## Context
+
+Compaction summary validation is fail-closed: a backticked exact value must occur
+literally in the evidence, and a bounded repair removes at most eight whole
+affected bullets. Production sessions kept failing closed with
+`compaction.custom_fallback`, `unsupported-exact-value`, `repair=too-many-bullets`
+and 30/20, 23/19, 19/15, 17/11, then 16/12 unsupported spans and affected
+bullets.
+
+The class-only report (§ 0.4.2–0.4.3) made the next observed run interpretable,
+and ADR 065 removed 11 of its 16 spans as JSON-escape renderings. The production
+report produced by 0.4.4 — 14 spans across 14 bullets, `spansClassifiedCheap: 0`,
+`probesUsed: 11671` of 24000, `classificationComplete: true` — closed the
+remaining attribution:
+
+| Relation | Count |
+| --- | --- |
+| `composed-two-present-parts` | 9 |
+| `no-near-miss` | 2 |
+| `single-deletion-present` | 2 |
+| `not-classified-length` | 1 |
+
+No rendering class remained, so the escape path was exhausted; the dominant
+residual cause is span composition, which is exactly what the 0.4.1 prompt rule
+forbids. That rule is present in the prompt that produced the report and the
+model still composes, which is why another repetition of the prohibition was not
+the fix.
+
+Composition mixes two situations that need opposite treatments. When the two
+parts sit next to each other in one source, the span is a re-rendering of a
+contiguous evidence region — the same shape of problem ADR 065 solved for
+escapes. When the parts are found at unrelated positions, the span is an
+association the evidence never contains, and accepting it would let a
+plausible-looking but false pairing (`path: wrong-range`) through validation.
+
+The prompt offered the model exactly one escape hatch from composing: omit the
+whole bullet. Discarding a fact is expensive, so composing was the cheaper
+choice. The instrumented evidence cannot by itself tell which composition kind
+occurs, because the classifier only established that both parts are present
+somewhere.
+
+## Decision
+
+1. The summarizer prompt keeps the prohibition but replaces the single drastic
+   fallback with a graded ladder: backtick only the fragments that are themselves
+   contiguous, with the joining text outside the backticks; if no fragment is
+   contiguous on its own, write the value as ordinary text without backticks and
+   keep the bullet; omit the bullet only when the fact itself has no support in
+   the evidence.
+2. Diagnostics split the composition class: `composed-adjacent-present` when one
+   corpus source holds the two parts with nothing but joining punctuation and
+   spaces between them (at most the span's own separator length plus two
+   characters, and no letters, digits or line breaks), and
+   `composed-two-present-parts` otherwise. Both are class-only, bounded, and
+   observation-only.
+3. The eight-bullet repair bound and the 25% removal bound are unchanged. A
+   larger unsupported set still fails closed to Pi default compaction: pruning
+   more of a summary than the operator accepts is not a fallback remedy.
+
+## Consequences
+
+- The ladder can reduce the number of backticked exact values in a summary. That
+  is a change in what the model chooses to quote, not in what validation accepts:
+  the contract, the repair bounds and the fail-closed decision are untouched.
+- The effect on the observed fallback is not verified by this change. The next
+  production report decides whether composition persists, and the new adjacency
+  class says whether a rendering-normalization rule on the ADR 065 pattern is
+  even possible: `composed-adjacent-present` is the only class for which it could
+  be safe, while `composed-two-present-parts` must never be accepted.
+- No configuration key, no SQLite migration, no schema change, and no
+  provider-facing default change.

package/docs/ADR/067-core-version-guard.md

@@ -0,0 +1,73 @@
+# 067 — Detect an engine/core artifact mismatch before compaction runs
+
+**Date:** 2026-09-27
+**Status:** Accepted
+**Related:** [`docs/RELEASING.md`](../RELEASING.md)
+
+## Context
+
+A machine reported, right after a Pi `/reload`:
+
+```text
+Warning: DS4 compaction unavailable; using Pi default.
+(0 , _summaryContract.classifyUnsupportedExactValueSpans) is not a function
+```
+
+The message was read as an installation mismatch, but every artifact on disk was
+current: `packages/core/dist/compaction/summary-contract.js` in the checkout and
+the npm-installed `ds4-context-core@0.4.3` both export the symbol (the core is
+ESM, so the export is an `export function` declaration, not an
+`exports.<name>` assignment). No stale file existed.
+
+The remaining explanation is process-local module state. Pi loads extension
+sources through jiti (`dist/core/extensions/loader.js`) and re-imports the
+extension entry when its cache generation changes — which is what `/reload`
+does — while modules that were already evaluated for that process, including the
+`ds4-context-core` dependency, keep their loaded instance. An extension source
+newer than the core module instance it resolved therefore calls a symbol that
+the cached core does not have. The failure costs the whole compaction attempt and
+reports a symptom (`is not a function`) that points at DS4 rather than at the
+process state.
+
+## Decision
+
+- `packages/core/src/version.ts` exports `CORE_VERSION`, bumped with the two
+  adapters by the coordinated release process.
+- `src/pi-adapter/core-compatibility.ts` inspects the engine↔core contract at
+  runtime: version equality plus the presence of the core entry points this
+  extension calls (`buildSummaryPrompt`,
+  `classifyUnsupportedExactValueSpans`). The inspection is a pure function, so
+  it is testable without a broken installation.
+- The guard runs on session start — so a `/reload` reports the state
+  immediately, before any compaction is attempted — and again as the first
+  statement of the guarded compaction attempt.
+- On a mismatch the engine logs `runtime.core_incompatible`, notifies once with
+  a single-line actionable message, sets the runtime `lastError`, and **does not
+  create the compaction coordinator**: DS4 compaction stays inert, `/context
+  compaction` reports `enabled: false` with the reason, and Pi compacting with
+  its own default is the only behaviour left rather than a half-finished DS4
+  run.
+- The guard never throws from the extension load path: Pi treats an extension
+  load error as fatal (`main.js` exits with code 1), so a stale core must not
+  prevent Pi from starting.
+- The message carries both remedies in order: rebuild the checkout
+  (`npm ci && npm run build:core && npm run build:adapters`) or update the
+  installed package (`pi update --extensions`), then **restart Pi**, because a
+  `/reload` keeps the already-loaded core module.
+
+## Consequences
+
+- A stale core no longer surfaces as `... is not a function`; it surfaces as one
+  line naming both versions, the missing entry point and the exact command to
+  run.
+- `CORE_VERSION` must stay imported from the package root. A *missing file* is a
+  module-resolution failure, while a *missing named export* of an existing module
+  arrives as `undefined` through the CommonJS interop Pi uses for extension
+  sources — which is the only form the guard can inspect.
+- Version equality is strict, which matches the synchronized versioning rule:
+  after a version bump the core must be rebuilt before the extension is used.
+- The guard detects and bounds the failure; it does not invalidate the module
+  cache. A rebuilt core still requires a restarted Pi process, and `/reload`
+  alone remains insufficient for core changes. Shipping the extension as a
+  self-contained artifact would remove that dependency, and is left as a
+  separate packaging decision.

package/docs/ADR/README.md

@@ -69,5 +69,7 @@ The initial decisions from the development plan are accepted:
 | [063](063-fts-rowid-key-mappings.md) | Resolve FTS key deletes through rowid mapping tables | Accepted |
 | [064](064-per-project-databases-with-shared-calibration.md) | Split project state into per-project databases and keep token calibration shared | 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 |
 
 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,16 +32,18 @@ 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 explicitly asks the model to omit a bullet whose complete backticked span cannot be copied verbatim, and to keep every backticked span one contiguous excerpt rather than joining separately supported values (a setting name with its value, a path with a line range, a command with its flags). 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; 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.
 
 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, or no near-miss (every applicable lookup ran and found nothing). 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 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.
 
 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.
 
 ## Provenance and recovery
 
+The engine checks its own contract with the loaded core at session start and at the start of every compaction attempt: `CORE_VERSION` must equal the extension version and the core entry points the extension calls must be present. Because Pi loads extension sources from TypeScript but keeps dependency modules loaded for the life of the process, a core rebuilt under a running Pi stays stale in memory and a `/reload` is not enough to pick it up; without the check the first missing export surfaced as `... is not a function` deep inside generation. A mismatch now logs `runtime.core_incompatible`, notifies once with the versions and the failing entry point, and leaves the compaction coordinator uncreated, so `/context compaction` reports `enabled: false` with that reason and Pi's own compaction is the only behaviour left. The guard is detection only: it never changes validation, repair bounds or the fail-closed decision, and it never throws while the extension is loading, because Pi treats an extension load error as fatal ([ADR 067](ADR/067-core-version-guard.md)).
+
 `CompactionEntry.details` contains cumulative `readFiles` and `modifiedFiles` plus:
 
 - summary and contract versions;

package/docs/releases/0.4.4.md

@@ -85,3 +85,19 @@ TypeScript builds and root typecheck), deterministic `npm run quality:compare`
 (`passed: true`), and `npm run pack:check` in a clean consumer for all three
 packages at 0.4.4 (247 core files, 7 reference-adapter files, 103 extension
 files). No provider calls are involved in this release procedure.
+
+## Publication and registry verification
+
+Published manually in dependency order from `10f0e0c`: `ds4-context-core@0.4.4`,
+then `ds4-context-reference-adapter@0.4.4`, then `ds4-context-engine@0.4.4`, all
+with the default `latest` tag, after `npm run pack:check` on the same commit.
+
+The first seven `npm run registry:check -- 0.4.4` attempts failed while the
+published metadata was still propagating; the eighth, some minutes later,
+reported "Verified all DS4 registry packages at exact version 0.4.4". For all
+three packages `npm view <package> dist-tags.latest` resolves to 0.4.4.
+
+Annotated tag `v0.4.4` and the GitHub Release were created from `10f0e0c`. No
+provider calls are involved in this release procedure; the classifier runs only
+after a validation failure has already been decided, and no session data,
+credentials, or provider payloads were read or written while preparing it.

package/docs/releases/0.4.5.md

@@ -0,0 +1,145 @@
+# Release 0.4.5 — Graded quoting fallback and adjacent-vs-unrelated composition
+
+**Coordinated packages:** `ds4-context-core`, `ds4-context-reference-adapter`, and `ds4-context-engine` 0.4.5.
+**Implementation commit:** `91a700a`.
+
+## Summary
+
+Behavior and diagnostics patch. The compaction summarizer prompt no longer
+forces an all-or-nothing choice between quoting a composite span and dropping the
+bullet: it now tells the model to backtick only the fragments that are themselves
+contiguous, and otherwise to keep the fact as ordinary text without backticks.
+The diagnostics report separates `composed-adjacent-present` — the two parts sit
+next to each other in one evidence source with nothing but joining punctuation
+and spaces between them — from `composed-two-present-parts`, where the parts are
+found at unrelated positions. Validation strictness, the eight-bullet and 25%
+repair bounds, the 25% removal bound, the fail-closed fallback to Pi default
+compaction, the SQLite schema and every provider-facing default are unchanged.
+
+## Changes
+
+- `packages/core/src/compaction/summary-contract.ts`:
+  - `buildSummaryPrompt` replaces the single "omit the whole bullet" escape with a
+    graded ladder: keep every backticked span one contiguous excerpt; when the
+    complete value is not one contiguous excerpt, backtick only the fragments
+    that are themselves contiguous with the joining text outside the backticks;
+    if no fragment is contiguous on its own, write the value as ordinary text
+    without backticks and keep the bullet; omit the bullet only when the fact
+    itself has no support in the evidence. The prohibition on assembling a span
+    from separately present values is unchanged and now carries the explicit
+    counter-examples (`a setting name with its value`, `a path with a line
+    range`, `a command with its flags`).
+  - The diagnostics classifier adds the relation `composed-adjacent-present`. A
+    composition is adjacent when one corpus source holds the two parts with at
+    most the span's own separator length plus two characters between them, in a
+    gap that contains no letters, digits or line breaks — so two parts on
+    separate lines are not adjacent. Adjacency lookups are bounded
+    (`MAX_ADJACENT_JOIN_PROBES` 8 per span, `MAX_JOIN_OCCURRENCES` 64
+    occurrences per source) and cost the same budget unit as every other lookup.
+  - `composed-two-present-parts` keeps its meaning for non-adjacent joins; both
+    classes are class-only and observation-only.
+- `tests/unit/summary-contract.test.ts`: prompt assertions follow the new
+  wording, plus two cases that pin the sub-classification — a JSON-rendered pair
+  (`{"compaction.model": "deepseek-flash"}` against
+  `compaction.model: deepseek-flash`) reports `composed-adjacent-present`, and
+  the same span against a source holding the two parts on separate lines reports
+  `composed-two-present-parts`.
+- `docs/COMPACTION.md`: the summary contract and the diagnostics section.
+- `docs/ADR/066-quoting-downgrade-and-span-adjacency.md` records the decision.
+
+## Why
+
+The class-only report added in 0.4.2, made interpretable in 0.4.3 and re-budgeted
+in 0.4.4, produced its first fully analysed production run: 14 rejected spans
+across 14 bullets, `spansClassifiedCheap: 0`, `probesUsed: 11671` of 24000,
+`classificationComplete: true`, `trigger: manual`.
+
+| Relation | Count |
+| --- | --- |
+| `composed-two-present-parts` | 9 |
+| `no-near-miss` | 2 |
+| `single-deletion-present` | 2 |
+| `not-classified-length` | 1 |
+
+No rendering class remained, so ADR 065 exhausted the escape path. The dominant
+residual cause is composition — the exact conduct the 0.4.1 prompt rule forbids —
+and that rule was in the prompt this model ran with, so repeating the prohibition
+was not the fix. The remaining hypothesis is the cost asymmetry: composing was
+the only alternative to discarding a whole fact. This release removes that
+asymmetry and, at the same time, adds the one measurement that decides whether a
+safe acceptance rule can ever exist for composition: adjacent joins are
+contiguous evidence regions the span re-rendered, while unrelated joins are
+associations the evidence never contains, and only the first kind could be
+accepted on the ADR 065 pattern.
+
+The eight-bullet repair bound is deliberately untouched. It was the mechanism
+that turned 14 affected bullets into a total fallback, and an explicit operator
+decision on 2026-09-27 kept it: removing invalid bullets without a count limit
+could silently delete a large share of a summary, and with these counts the 25%
+removal bound would likely refuse as well, so the change would not reliably end
+the fallback.
+
+## Privacy and safety
+
+- The report stays class-only. The new relation is one more fixed class name; no
+  span text, fragment text, evidence text or hash of either is added to logs,
+  warnings, or errors.
+- The prompt change alters what the model is instructed to quote. It does not
+  change what validation accepts, the repair bounds, the fail-closed decision, or
+  the privacy path; no provider call, network access or configuration change is
+  involved in this release.
+- Fewer backticked spans is a possible outcome of the ladder. That is a rendering
+  choice made by the summarizer, not a validator relaxation: an unsupported
+  backticked value is still rejected exactly as before.
+
+## Compatibility and persistence
+
+- No migrations, no schema change (still 16), no new configuration key, and no
+  change to any provider-facing default.
+- The report shape is additive: `composed-adjacent-present` is a new key in
+  `relations`, and existing readers keep working. A reader that previously saw
+  only `composed-two-present-parts` will now see the adjacent cases split out.
+- `chars-v1` remains the default estimator, `modelAwareness.autoTune` and DS4
+  native continuation stay disabled, `storage.scope` keeps its `project` default.
+
+## Measured scope and limitations
+
+The effect on the observed fallback is not verified in a real session by this
+release. The change is a prompt instruction, so the outcome depends on the
+summarizer model's compliance: 0.4.1 already showed that a prohibition alone is
+not followed. Expected observations for the next production compaction:
+
+| Observation | Reading |
+| --- | --- |
+| `compaction.custom_fallback` absent | the graded fallback ended the composition |
+| composition still present, mostly `composed-adjacent-present` | composition persists and a rendering-normalization rule is technically possible |
+| composition still present, mostly `composed-two-present-parts` | composition persists and no acceptance rule can be safe; only the summarizer model, its reasoning level or the repair policy remain |
+| fewer backticked values overall | the ladder worked, with the expected rendering cost in the summary |
+
+## Validation
+
+On Node 26.5.1 the release passed `npm run check` (99 Vitest files, 634 tests,
+TypeScript builds and root typecheck), deterministic `npm run quality:compare`
+(candidate `0.9875` against baseline `0.808156`), `npm run schema:context-persistence`
+(`passed: true`), and `npm run pack:check` in a clean consumer for all three
+packages at 0.4.5 (247 core files, 7 reference-adapter files, 104 extension
+files). No provider calls are involved in this release procedure.
+
+## Publication and registry verification
+
+Published manually in dependency order from `2366c98`: `ds4-context-core@0.4.5`,
+then `ds4-context-reference-adapter@0.4.5`, then `ds4-context-engine@0.4.5`, all
+with the default `latest` tag, after `npm run pack:check` on the same commit.
+
+`npm run registry:check -- 0.4.5`, run with a fresh npm cache, reported
+"Verified all DS4 registry packages at exact version 0.4.5" on the first
+attempt: 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. For all three packages
+`npm view <package> dist-tags.latest` resolves to 0.4.5.
+
+Annotated tag `v0.4.5` and the GitHub Release were created from `2366c98`. No
+provider calls are involved in this release procedure; no session data,
+credentials, or provider payloads were read or written while preparing it.

package/docs/releases/0.4.6.md

@@ -0,0 +1,137 @@
+# Release 0.4.6 — Detect an engine/core artifact mismatch before compaction runs
+
+**Coordinated packages:** `ds4-context-core`, `ds4-context-reference-adapter`, and `ds4-context-engine` 0.4.6.
+**Implementation commit:** `225078f`.
+
+## Summary
+
+Diagnostic and packaging patch. The core now exports `CORE_VERSION` and the
+extension verifies, at session start and at the beginning of every compaction
+attempt, that the core it actually loaded matches its own version and exposes the
+entry points it calls. A mismatch — typically a core rebuilt in a checkout while
+Pi kept the previously loaded module instance, which a `/reload` does not
+replace — no longer surfaces deep inside summary generation as
+`(0 , _summaryContract.x) is not a function`. It reports one actionable line,
+keeps the DS4 compaction layer inert instead of failing mid-generation, and
+leaves Pi compacting with its own default. Validation strictness, the
+eight-bullet and 25% repair bounds, the fail-closed fallback, the SQLite schema,
+canonical JSONL history and every provider-facing default are unchanged.
+
+## Changes
+
+- `packages/core/src/version.ts` (new): `CORE_VERSION`, re-exported from the core
+  package root and bumped with the two adapters by the coordinated release
+  process.
+- `src/pi-adapter/core-compatibility.ts` (new): `inspectCoreCompatibility`
+  (pure), `coreCompatibilityIssues` (real probe), `coreCompatibilityMessage` and
+  `assertCoreCompatibility`. The probe compares `CORE_VERSION` with
+  `EXTENSION_VERSION` and checks that `buildSummaryPrompt` and
+  `classifyUnsupportedExactValueSpans` are functions, naming the exact missing
+  entry point.
+- `src/extension/runtime.ts`: session start runs the probe once. On a mismatch it
+  logs `runtime.core_incompatible`, notifies a single line and sets the runtime
+  `lastError`; the compaction coordinator is then not created, so `/context
+  compaction` reports `enabled: false` with that reason instead of a half-run
+  batch. `RuntimeDependencies` gained an optional `coreCompatibility` seam for
+  tests.
+- `src/pi-adapter/compaction-coordinator.ts`: the same guard runs as the first
+  statement of the guarded compaction attempt, so the existing coordinator catch
+  turns it into the ordinary `compaction.custom_fallback` warning. The
+  coordinator gained an optional `checkCoreCompatibility` seam.
+- `tests/unit/core-compatibility.test.ts` (new, 6 cases): synchronized core
+  accepted, older version named on both sides, missing `CORE_VERSION` reported,
+  missing entry point named instead of an `is not a function`, single-line remedy,
+  and the real probe passing against the core this repository resolves.
+- `tests/unit/compaction-optimizations.test.ts`: a simulated stale core reaches
+  `beforeCompact` as a fallback warning with no provider call.
+- `tests/integration/extension.test.ts`: with a simulated stale core, session
+  start warns with the remedy, `/context compaction` diagnostics report
+  `enabled: false` and the reason, and the compaction hook stays inert.
+- `docs/COMPACTION.md`, `docs/ADR/067-core-version-guard.md` and the ADR index
+  record the decision.
+
+## Why
+
+A production machine reported, immediately after a Pi `/reload`:
+
+```text
+Warning: DS4 compaction unavailable; using Pi default.
+(0 , _summaryContract.classifyUnsupportedExactValueSpans) is not a function
+```
+
+Every artifact on disk was current: the checkout's `packages/core/dist` and the
+npm-installed `ds4-context-core@0.4.3` both export the symbol. Pi loads extension
+sources through jiti and re-imports the extension entry when its cache generation
+changes, while modules already evaluated for that process keep their loaded
+instance, so an extension source newer than the core module it resolved calls a
+symbol the loaded core does not have. The failure consumed the whole compaction
+attempt and pointed at DS4 rather than at the process state.
+
+The guard converts that class of mismatch into a single line that names both
+versions, the missing entry point and the two remedies — rebuild the checkout
+(`npm ci && npm run build:core && npm run build:adapters`) or update the installed
+package (`pi update --extensions`) — followed by the step that actually makes a
+rebuilt core visible: restart Pi. It is deliberately not on the extension load
+path, because Pi treats an extension load error as fatal and a stale core must
+never keep Pi from starting, and it is detection only: nothing about validation,
+repair bounds or the fail-closed decision changes
+([ADR 067](ADR/067-core-version-guard.md)).
+
+## Privacy and safety
+
+- The guard reads module state only: two version strings and the presence of two
+  exported functions. It never reads session JSONL, the SQLite projection,
+  credentials, provider payloads or prompt text, and the message contains no
+  session content.
+- `runtime.core_incompatible` and the fallback warning carry the same message
+  that the user sees; no span text, file content or provider data is logged.
+- No provider call is introduced by this release, and none was made to prepare
+  it.
+
+## Compatibility and persistence
+
+- No configuration key is added or default changed. `CORE_VERSION` is additive;
+  a core older than 0.4.6 simply fails the version probe, which is what the guard
+  reports.
+- SQLite schema 16, migrations, the Pi JSONL boundary, tool contracts and the
+  reference adapter's public surface are untouched.
+- Version equality is strict because the three packages are released in lockstep:
+  after bumping versions, the core must be rebuilt before the extension runs.
+
+## Measured scope and limitations
+
+- Detection only. The guard cannot invalidate Pi's module cache: on a machine
+  whose running Pi already holds a stale core, the next `/reload` reports the
+  mismatch and disables the DS4 compaction layer, and the DS4 core in that
+  process is only replaced by restarting Pi.
+- The guard covers the entry points the extension already calls. A future core
+  symbol the engine starts requiring must be added to `REQUIRED_CORE_EXPORTS`
+  (or fail through the version check when versions differ).
+- Shipping the extension as a self-contained artifact would remove the
+  process-cache dependency entirely; that packaging decision is left open in
+  ADR 067.
+
+## Validation
+
+- `npm run check` on the release commit: builds, `tsc --noEmit`, and
+  **100 test files / 642 tests passed** (8 new tests: 6 unit guard cases, 1
+  coordinator case, 1 extension integration case).
+- `npm run pack:check` in a clean consumer: `ds4-context-core@0.4.6`
+  (251 files), `ds4-context-reference-adapter@0.4.6` (7 files) and
+  `ds4-context-engine@0.4.6` (108 files).
+- `npm run quality:compare`: candidate `task-weighted-v0.2-candidate` 0.9875
+  against the frozen baseline `static-ranking-v0.1` 0.808156, unchanged from
+  0.4.5.
+- `npm run schema:context-persistence` (`passed: true`).
+- No provider calls are involved in this release procedure. `jev_verify` is not
+  available in this environment (project verification disabled), so the checks
+  above were run directly.
+
+## 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.

package/package.json

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

package/src/extension/index.ts

@@ -27,6 +27,7 @@ export function registerDs4ContextEngine(
     ...(dependencies.idGenerator ? { idGenerator: dependencies.idGenerator } : {}),
     ...(dependencies.logSink ? { logSink: dependencies.logSink } : {}),
     ...(dependencies.embeddingPort ? { embeddingPort: dependencies.embeddingPort } : {}),
+    ...(dependencies.coreCompatibility ? { coreCompatibility: dependencies.coreCompatibility } : {}),
   });
 
   const continuationStream = createOpenAIResponsesContinuationStream({

package/src/extension/runtime.ts

@@ -31,6 +31,11 @@ import {
   type SessionCompactFailedLike,
   type SummaryGraphDiagnostics,
 } from "../pi-adapter/compaction-coordinator.ts";
+import {
+  coreCompatibilityIssues,
+  coreCompatibilityMessage,
+  type CoreCompatibilityIssue,
+} from "../pi-adapter/core-compatibility.ts";
 import {
   NativeContinuationManager,
   type NativeContinuationAttempt,
@@ -224,6 +229,8 @@ export interface RuntimeDependencies {
   logSink?: (line: string) => void;
   /** Optional runtime-owned embedding provider; required for configured remote models. */
   embeddingPort?: EmbeddingPort;
+  /** Test seam for the engine↔core guard; defaults to the real module probe. */
+  coreCompatibility?: () => readonly CoreCompatibilityIssue[];
 }
 
 interface PreparedPrivacyContext {
@@ -489,6 +496,7 @@ export class Ds4ContextRuntime {
     recordedAt: number;
   }> = [];
   private lastError?: string;
+  private coreIncompatibilityMessage?: string;
   private logger: Logger = silentLogger;
   private readonly now: () => number;
   private readonly idGenerator: () => string;
@@ -547,6 +555,7 @@ export class Ds4ContextRuntime {
     this.artifactManager = undefined;
     this.lastArtifacts = disabledArtifactDiagnostics();
     this.compaction = undefined;
+    this.coreIncompatibilityMessage = undefined;
     this.observation = undefined;
     this.session = this.snapshotCanonicalSession(ctx);
 
@@ -650,34 +659,47 @@ export class Ds4ContextRuntime {
       }
       this.initializeMemory(ctx);
       this.initializeArtifacts(ctx);
-      this.compaction = new CompactionCoordinator({
-        config: this.config,
-        database: this.database,
-        sessionId: this.session.sessionId,
-        persisted: Boolean(this.session.sessionFile),
-        logger: this.logger,
-        now: this.now,
-        idGenerator: this.idGenerator,
-        syncSessionIndex: (context) => {
-          this.syncSessionIndex(context);
-        },
-        latestManifest: () => this.lastManifest,
-        resolveModelBudget: (model) => {
-          const resolved = this.resolveModelPolicy(model);
-          return {
-            budget: resolved.budget,
-            recentTailTokens: resolved.awareness.limits.recentTailTokens,
-          };
-        },
-        sanitizeContent: (text, provider) => this.privacyEngine?.sanitizeText(text, provider).value ?? text,
-        classifyContent: (text, provider) => {
-          const sanitized = this.privacyEngine?.sanitizeText(text, provider);
-          return sanitized
-            ? { value: sanitized.value, classification: sanitized.classification }
-            : { value: text, classification: "normal" };
-        },
-      });
-      this.compaction.initialize(ctx.sessionManager.getEntries());
+      // Pi re-imports extension sources on /reload but keeps already-loaded
+      // dependency modules, so a core rebuilt under a running Pi stays stale in
+      // memory. Report that instead of leaving compaction to fail on a missing
+      // export, and skip only the compaction layer.
+      const coreIssues = (this.dependencies.coreCompatibility ?? coreCompatibilityIssues)();
+      if (coreIssues.length > 0) {
+        const message = coreCompatibilityMessage(coreIssues);
+        this.coreIncompatibilityMessage = message;
+        this.lastError = message;
+        this.logger.warn("runtime.core_incompatible", { error: message });
+        if (ctx.hasUI) ctx.ui.notify(`DS4 Context Engine: ${message}`, "warning");
+      } else {
+        this.compaction = new CompactionCoordinator({
+          config: this.config,
+          database: this.database,
+          sessionId: this.session.sessionId,
+          persisted: Boolean(this.session.sessionFile),
+          logger: this.logger,
+          now: this.now,
+          idGenerator: this.idGenerator,
+          syncSessionIndex: (context) => {
+            this.syncSessionIndex(context);
+          },
+          latestManifest: () => this.lastManifest,
+          resolveModelBudget: (model) => {
+            const resolved = this.resolveModelPolicy(model);
+            return {
+              budget: resolved.budget,
+              recentTailTokens: resolved.awareness.limits.recentTailTokens,
+            };
+          },
+          sanitizeContent: (text, provider) => this.privacyEngine?.sanitizeText(text, provider).value ?? text,
+          classifyContent: (text, provider) => {
+            const sanitized = this.privacyEngine?.sanitizeText(text, provider);
+            return sanitized
+              ? { value: sanitized.value, classification: sanitized.classification }
+              : { value: text, classification: "normal" };
+          },
+        });
+      }
+      this.compaction?.initialize(ctx.sessionManager.getEntries());
 
       this.phase = this.config.context.mode;
       this.setStatus(ctx, `DS4 ctx: ${this.config.context.mode}`);
@@ -3501,6 +3523,13 @@ export class Ds4ContextRuntime {
   }
 
   private getCompactionDiagnostics(ctx: ExtensionContext): CompactionDiagnostics {
+    if (this.coreIncompatibilityMessage) {
+      return {
+        ...defaultCompactionDiagnostics(this.config),
+        enabled: false,
+        lastError: this.coreIncompatibilityMessage,
+      };
+    }
     return this.compaction?.diagnostics(ctx) ?? defaultCompactionDiagnostics(this.config);
   }
 

package/src/pi-adapter/compaction-coordinator.ts

@@ -29,6 +29,7 @@ import {
   type PreparedCompactionSource,
   type PreparedCompactionSourceSlice,
 } from "./compaction-adapter.ts";
+import { assertCoreCompatibility } from "./core-compatibility.ts";
 import { buildCompactionAtomicGroups } from "ds4-context-core/compaction/segmentation";
 import { estimateMessageTokens } from "ds4-context-core/core/token-estimator";
 import { adaptiveRecentTailLimit } from "ds4-context-core/planner/context-planner";
@@ -195,6 +196,11 @@ interface CompactionCoordinatorDependencies {
     text: string,
     provider: string,
   ) => { value: string; classification: PrivacyClassification };
+  /**
+   * Engine↔core compatibility guard. Defaults to `assertCoreCompatibility`; the
+   * seam exists so tests can simulate a stale core artifact.
+   */
+  checkCoreCompatibility?: () => void;
 }
 
 type MutableCompactionState = Omit<
@@ -238,8 +244,11 @@ export class CompactionCoordinator {
   private proactiveRequested = false;
   private lastProactiveLeafId?: string;
   private readonly graphRecords = new Map<string, SummaryRecord>();
+  private readonly checkCoreCompatibility: () => void;
 
-  constructor(private readonly dependencies: CompactionCoordinatorDependencies) {}
+  constructor(private readonly dependencies: CompactionCoordinatorDependencies) {
+    this.checkCoreCompatibility = dependencies.checkCoreCompatibility ?? assertCoreCompatibility;
+  }
 
   initialize(entries: readonly SessionEntry[]): void {
     if (!this.dependencies.database || !this.dependencies.persisted) return;
@@ -308,6 +317,10 @@ export class CompactionCoordinator {
     };
 
     try {
+      // A stale core module (a core rebuilt under a running Pi keeps its cached
+      // instance there) would otherwise fail later as a missing function deep in
+      // generation; this catch turns the guard message into the ordinary fallback.
+      this.checkCoreCompatibility();
       const { source, inputBudgetTokens, requestInputLimitTokens, wholePlan, directPlan, segmentPlans } = await measure("preparationMs", () => {
         if (event.signal.aborted) throw new Error("Compaction summary generation aborted");
         this.dependencies.syncSessionIndex(ctx);

package/src/pi-adapter/core-compatibility.ts

@@ -0,0 +1,98 @@
+import { CORE_VERSION } from "ds4-context-core";
+import {
+  buildSummaryPrompt,
+  classifyUnsupportedExactValueSpans,
+} from "ds4-context-core/compaction/summary-contract";
+import { EXTENSION_VERSION } from "./version.ts";
+
+/**
+ * Runtime guard for the engine↔core contract.
+ *
+ * Pi loads this extension from TypeScript source while `ds4-context-core` is a
+ * prebuilt package resolved through normal module resolution. When those two
+ * artifacts drift apart — a checkout that pulled new sources without rebuilding
+ * `packages/core/dist`, or an npm update that moved only one of the two packages
+ * — the extension keeps loading, and the first missing core export surfaces deep
+ * inside compaction as `(0, _summaryContract.x) is not a function`, which reads
+ * like a DS4 bug instead of an installation problem.
+ *
+ * The guard is deliberately kept off the load path: Pi treats an extension load
+ * failure as fatal (`process.exit(1)`), so throwing at module scope would block
+ * the whole runtime. It runs on the compaction path instead, where the mismatch
+ * already breaks the run, and where the coordinator turns the thrown message
+ * into the ordinary "DS4 compaction unavailable; using Pi default" warning.
+ *
+ * `CORE_VERSION` is imported from the package root rather than a new subpath so
+ * that a stale core without the marker still resolves: a missing *file* would be
+ * a module-resolution failure, while a missing named export simply arrives as
+ * `undefined` through Pi's CommonJS interop.
+ */
+
+export interface CoreCompatibilityIssue {
+  kind: "version" | "export";
+  detail: string;
+}
+
+/** Pure inspection, so the guard is testable without a broken installation. */
+export function inspectCoreCompatibility(input: {
+  extensionVersion: string;
+  coreVersion: unknown;
+  requiredExports: readonly (readonly [string, unknown])[];
+}): CoreCompatibilityIssue[] {
+  const issues: CoreCompatibilityIssue[] = [];
+  if (typeof input.coreVersion !== "string" || input.coreVersion.length === 0) {
+    issues.push({
+      kind: "version",
+      detail:
+        `the resolved ds4-context-core does not export CORE_VERSION, so it predates ${input.extensionVersion}`,
+    });
+  } else if (input.coreVersion !== input.extensionVersion) {
+    issues.push({
+      kind: "version",
+      detail:
+        `ds4-context-core resolves to ${input.coreVersion} while DS4 Context Engine is ${input.extensionVersion}`,
+    });
+  }
+  for (const [name, value] of input.requiredExports) {
+    if (typeof value !== "function") {
+      issues.push({
+        kind: "export",
+        detail: `ds4-context-core does not export ${name}()`,
+      });
+    }
+  }
+  return issues;
+}
+
+/**
+ * Core entry points this extension calls. Extend this list whenever the engine
+ * starts requiring a newer core symbol; `CORE_VERSION` equality already covers
+ * whole-artifact drift, and these probes name the exact missing symbol.
+ */
+const REQUIRED_CORE_EXPORTS: readonly (readonly [string, unknown])[] = [
+  ["buildSummaryPrompt", buildSummaryPrompt],
+  ["classifyUnsupportedExactValueSpans", classifyUnsupportedExactValueSpans],
+];
+
+export function coreCompatibilityIssues(): CoreCompatibilityIssue[] {
+  return inspectCoreCompatibility({
+    extensionVersion: EXTENSION_VERSION,
+    coreVersion: CORE_VERSION,
+    requiredExports: REQUIRED_CORE_EXPORTS,
+  });
+}
+
+/** Single-line message: it is appended to the existing fallback notification. */
+export function coreCompatibilityMessage(
+  issues: readonly CoreCompatibilityIssue[],
+): string {
+  return `${issues.map((issue) => issue.detail).join("; ")}. Fix: rebuild the checkout `
+    + "(\"npm ci && npm run build:core && npm run build:adapters\") or update the installed package "
+    + "(\"pi update --extensions\"), then restart Pi: a /reload can keep the old core module cached.";
+}
+
+/** Throws an actionable error instead of a downstream `is not a function`. */
+export function assertCoreCompatibility(): void {
+  const issues = coreCompatibilityIssues();
+  if (issues.length > 0) throw new Error(coreCompatibilityMessage(issues));
+}

package/src/pi-adapter/version.ts

@@ -1,4 +1,4 @@
-export const EXTENSION_VERSION = "0.4.4";
+export const EXTENSION_VERSION = "0.4.6";
 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";