# DS4 Context Engine 0.3.5

Status: published as stable on npm under `latest`; annotated tag `v0.3.5` points to validated release commit `8b1d5f4`.

## Added since 0.3.4

Bounded compaction optimizations, enabled by default when DS4 custom compaction is enabled:

- **`compaction.directUpdate=true`**: one validated previous-summary plus new-source request when the complete sanitized prompt fits. The immutable `task-state` node retains predecessor edges, transitive source IDs and a source hash bound to both inputs. Oversized updates retain hierarchical segmentation/aggregation; no synthetic segment or source truncation is introduced.
- **`compaction.inputBudget="summary"`**: use the calibrated hard input limit rather than the ordinary context fill target, additionally capped by model context minus safety margin and actual summary output headroom. Configured/model hard limits and calibration remain authoritative; ordinary context planning is unchanged.
- **`compaction.maxConcurrentSegments=2`** (integer 1–2): overlap only independent segment requests. Node identities, sources, graph edges and usage follow source order, never completion order. Failure or cancellation stops scheduling, aborts siblings and drains every started worker before Pi fallback; no partial graph is installed. Aggregation stays ordered and bounded.
- **Metadata-only diagnostics**: `/context compaction` reports path, effective provider/model, full-update prompt size, logical calls, concurrency, retries and monotonic wall timings for preparation, generation, aggregation, persistence and total DS4 hook duration. Timings are process-local, exclude native fallback, and are not persisted in canonical JSONL.

Transport documentation now explicitly distinguishes **three total attempts** from three retries; runtime transport policy is unchanged.

See [compaction controls](../COMPACTION.md#latency-controls) and [ADR-061](../ADR/061-compaction-latency.md).

## Compatibility and limitations

Pi cut points, atomic tool exchanges, summary validation and bounded exact-value repair, privacy classification, immutable provenance and JSONL rebuild remain in place. Schema-v2 compaction metadata reuses the existing `task-state` kind. Pi JSONL remains canonical and append-only; SQLite remains disposable/rebuildable at schema `15`.

Unchanged contracts: `ds4-context-config-v1`, `runtime-adapter-v1`, `ds4-context-persistence-tool-v1`, `ds4-context-persistence-result-v1`. The new configuration keys are additive; absent keys use the new defaults. The five optional portable tools/features introduced in 0.3.4 remain default-off. Pi stays pinned to `0.84.3`; Node.js remains `>=22.19.0`. No dependency upgrade, live database maintenance or Pi upgrade is part of this release.

Mock-provider tests establish call counts, bounded overlap and deterministic safety properties, not real-provider speedups, semantic equivalence or a guaranteed compaction duration. A larger prompt may take longer to process. Rate-limit errors are not transport-retried; providers with restrictive concurrency should use `maxConcurrentSegments=1`. Cancellation is cooperative: accepted work may still be billed and providers ignoring abort may delay settlement. Linux validation does not establish Windows execution correctness.

## Update and configure

Install the exact coordinated package and **fully restart Pi** to load its matching compiled core:

```bash
pi install npm:ds4-context-engine@0.3.5
```

No extra opt-in is needed for the three new defaults when DS4 and custom compaction are enabled. Inspect configuration and subsequent compaction diagnostics with:

```text
/context config show
/context compaction
```

For a legacy-path comparison in a trusted project:

```text
/context config set compaction.directUpdate false
/context config set compaction.inputBudget context
/context config set compaction.maxConcurrentSegments 1
/reload
```

Use `true`, `summary`, and `2` to restore the new defaults. Add `--global` to each `set` for agent-directory configuration; trusted project settings take precedence. Disabling DS4 custom compaction still delegates to Pi.

## Package policy and validation

All three packages use `0.3.5`: `ds4-context-core`, `ds4-context-reference-adapter`, `ds4-context-engine`. Both adapters depend exactly on `ds4-context-core@0.3.5`. Publication is manual in that order under npm's stable `latest` tag. GitHub Actions remains validation-only with OIDC and package-write permissions denied.

Candidate validation on Node.js `26.5.1`, from a sanitized release source with a fresh `npm ci`:

- `npm run check`: **80 files / 508 tests passed**, including exact full-prompt budget boundaries, direct-update evidence/privacy, immutable graph rebuild, out-of-order segments, abort/failure drainage and transport retry cancellation.
- `npm run quality:compare`: passed; frozen-corpus candidate score `0.9875` versus baseline `0.808156`. This is a planner corpus, not a real-provider summary-quality comparison.
- `npm run schema:context-persistence`: passed, `1266` bytes / `317` estimated tokens (limits `1500` / `320`).
- `npm run latency:check` against freshly installed exact `ds4-context-core@0.1.2`: passed; disabled-planning p95 ratio `0.903863`, maximum `1.1`. This is not a compaction/provider latency measurement.
- `npm run pack:check`: passed in a clean consumer, core **235 files**, reference adapter **7**, engine **87**, including isolated offline Pi extension startup and registry scenarios.
- All three `npm pack --dry-run --json` inventories and `git diff --check` passed. Tarball inventories exclude sessions, databases, credentials, test state and `.serena/`.
- Manifests, exact core dependencies, lockfile and runtime version constants are synchronized. The lockfile contains only coordinated version changes; no dependency upgrade was performed.

Pre-existing local `allowScripts` additions and `.serena/` are excluded from release commits and public packages.

The final clean committed worktree repeated fresh `npm ci`, all **508 tests**, clean-consumer package verification and tarball inspection successfully. Validation-only CI run [`33970061602`](https://github.com/Alucard24/ds4-context-engine/actions/runs/33970061602) on `8b1d5f4` passed both Node `22.19.0` and `24.x`, including the full suite and package checks.

## Registry verification and release

Published manually as `alucard_24`, in dependency order, from reviewed tarballs built in the clean committed worktree:

- `ds4-context-core@0.3.5`: shasum `71105c666a8c88f1abfe5ba3efefe63fc32bba74`;
- `ds4-context-reference-adapter@0.3.5`: shasum `8eca29472ea4721606d947818eba0aa53a6c6f63`;
- `ds4-context-engine@0.3.5`: shasum `304b61c21e28f89e82edbee39880210c2c9dc868`.

`npm run registry:check -- 0.3.5` passed: fresh exact-version installation, matching adapter/core dependencies, public core exports, compiled reference conformance, packaged quality corpus, storage CLI usage probe and isolated offline Pi extension startup. Registry SHA-1 and SHA-512 integrity values match the local tarballs for all three packages.

The immediate first post-publication install returned `ETARGET` for the engine. Once exact-version registry metadata was available, verification was repeated with npm `prefer-online` and passed; no package was republished or tag moved.

Verified dist-tags for all three: `latest=0.3.5`, `beta=0.3.0-beta.3`, `alpha=0.3.0-alpha.5`, `rc=0.2.0-rc.1`.

Annotated tag `v0.3.5` targets `8b1d5f4`, the tested/published source. This post-publication evidence update is documentation-only.

GitHub Release: https://github.com/Alucard24/ds4-context-engine/releases/tag/v0.3.5