# DS4 Context Engine 0.3.1

Status: published 2026-09-04 as stable, printed under the npm `latest` dist-tag.

This release adds the opt-in dedicated compaction model and per-request reasoning control on top of the 0.3.0 stable candidate. It carries forward 0.3.0 without changing canonical records, SQLite schema, runtime contracts, retention limits, privacy policy, compaction validation, or fallback semantics.

## Added since 0.3.0

- **Dedicated compaction model** (`compaction.model.provider` / `compaction.model.id`, opt-in):
  - when absent, compaction keeps using the active session model exactly as before, including preflight budget, segmentation, sanitization, and record provenance;
  - when present, the model is resolved once per compaction through Pi's model registry and used uniformly for the input budget, segmentation, sanitization, segment/aggregate requests, and the `provider`/`model` provenance of summary records;
  - automatic fallback with a `compaction.dedicated_model_fallback` warning when the model is not registered, has no configured authentication, or does not accept text input: a configuration mistake can never block compaction, and the hook still returns the session-model path;
  - the resolved model is recorded in diagnostics as `compaction.dedicated_model` at `debug`.
- **Summary reasoning control** (`compaction.summary.thinking`, default `off`):
  - applies only to summary requests, never to normal session traffic;
  - `off` (default) leaves the request shape unchanged from 0.3.0;
  - levels `minimal`/`low`/`medium`/`high`/`xhigh`/`max` map per API: `thinkingEnabled`/`effort` for `anthropic-messages`, `samplingParams.reasoning_effort` for OpenAI-compatible APIs (`openai-responses`, `openai-completions`, `azure-openai-responses`, `openai-codex-responses`);
  - unsupported APIs ignore the option without errors; `xhigh`/`max` clamp to the highest supported effort where the API has no equivalent.
- Configuration validation in the loader recognizes the two opt-in object paths and rejects malformed provider/id tokens or unknown thinking levels, generating a `configuration ignored` warning and leaving the default config in force.
- Coordinated package versions moved to `0.3.1`.

There are no functional storage-format or provider-path changes relative to 0.3.0.

## Safety and compatibility

Unchanged from 0.3.0: Pi JSONL remains canonical and append-only; SQLite remains disposable and rebuildable; physical maintenance remains explicit, offline, local-TTY-only, and unavailable to model-callable tools; every `context_persistence` write still requires a fresh positive local UI decision.

Compatibility remains unchanged:

- SQLite schema: `15`;
- configuration: `ds4-context-config-v1` (two opt-in object keys added; default shape and all existing keys unchanged);
- runtime adapter: `runtime-adapter-v1`;
- persistence tool: `ds4-context-persistence-tool-v1`;
- persistence result: `ds4-context-persistence-result-v1`;
- Pi: `0.84.3`;
- Node.js: `>=22.19.0`.

## Package/version policy

The coordinated version is `0.3.1` for:

```text
ds4-context-core
ds4-context-reference-adapter
ds4-context-engine
```

Both adapters depend exactly on `ds4-context-core@0.3.1`. Publication uses npm's default `latest` tag for all three packages: `latest` now resolves to `0.3.1` (previously `0.3.0`), `beta` remains `0.3.0-beta.3`, `alpha` remains `0.3.0-alpha.5`, and `rc` remains `0.2.0-rc.1`. GitHub Actions remains validation-only with OIDC and package-write permissions denied.

## Candidate validation

Local candidate verification on Node.js `26.5.1`:

- `npm run check`: 70 files and 352 tests passed (including five new dedicated-model/thinking integration tests and the thinking-mapping unit tests).
- `npm run quality:compare`: candidate quality versus the frozen baseline passed.
- `npm run schema:context-persistence`: within the 1,500 / 320 absolute and relative limits.
- `npm run latency:check` against the frozen baseline passed.
- `npm run pack:check` and `npm pack --dry-run --json` for all three packages passed with no forbidden local/session/storage paths.
- `git diff --check` passed; the only pre-existing untracked path is `.serena/`, which is excluded from commits and package inventories.
- Version, exact core dependencies, package-lock entries, extension constant, and reference-adapter constant are synchronized to `0.3.1`.

Validation-only CI is recorded below with the release commit. Exact registry verification and the annotated tag are recorded after execution.

## Registry evidence

Exact post-publication verification passed for all three `0.3.1` packages on 2026-09-04. The clean registry consumer verified exact adapter/core dependencies, public core exports, compiled reference-adapter conformance, packaged quality corpus, packaged Pi extension startup, and the installed `ds4-context-storage` CLI declaration, shim, and usage probe.

Published package shasums:

```text
ds4-context-core:              94607bb735653da5ce533a502d45edd5b323242e
ds4-context-reference-adapter: ff0257ccb7614f7cf068b9b0dff912a91594f66d
ds4-context-engine:            623beaac038053e48dcb0f2e3f49587e48206490
```

For all three packages, npm `latest` now resolves to `0.3.1`, `beta` remains `0.3.0-beta.3`, `alpha` remains `0.3.0-alpha.5`, and `rc` remains `0.2.0-rc.1`.

## Documentation

- [`../COMPACTION.md`](../COMPACTION.md)
- [`../RELEASING.md`](../RELEASING.md)
- [`0.3.0.md`](0.3.0.md)