# DS4 Context Engine 0.5.3

## Changes

- Integrate PR #2 (squash commit `d2519f3`) and follow-up `b8614d0`.
- Add `context.supplementalPlacement` with unchanged default `latest-user`, opt-in `stable-prefix` for all supplements after leading system/developer messages, and opt-in `hybrid` for pin/memory/project at that prefix with retrieval immediately before the newest native user request.
- Map native pin indices, classifications, privacy reasons and supplemental provenance through the same actual planned positions across both insertion points. Ignore source-less supplements without shifting indices.
- Isolate synthetic supplements as independent atomic groups so they cannot absorb a following native assistant/tool prefix, misattribute its provenance or incorrectly consume its budget. Native tool call/result binding and validation remain enforced.
- Preserve native no-user behavior and fail-open fallback, without retaining synthetic supplements in fallback.
- Add regressions for leading roles, two-point mapping, selected/excluded provenance, changing retrieval, no-user inputs, budget fallback, native tool-batch retention and incomplete/orphan selected exchanges. Config tests round-trip all three modes, reject invalid values and cover the default-shape loader requirement. The golden default is `latest-user`.
- Document the trade-offs and limitations in the planner contract and ADR 075.

## Configuration

Save `context.supplementalPlacement` through Pi's configuration interface or in `ds4-context.json`:

```json
{
  "context": {
    "supplementalPlacement": "hybrid"
  }
}
```

`stable-prefix` remains available for installations with unchanged supplements, including the author's local-engine comparison. Existing configurations without this field retain `latest-user`. Fully restart Pi after upgrading to load the matching engine/core artifacts and saved settings.

## Scope and limitations

Stable placement removes one source of prefix divergence; it does not guarantee cache hits or a byte-for-byte request prefix. Memory/project selection, changing blocks, sliding tails, compaction, request options and provider serialization may invalidate the following suffix. The PR author's Strata measurements were not reproduced during this review. No provider calls or source-history rewrites are introduced. Privacy, budgets, schema and default BPE/auto-tuning behavior remain unchanged.

The separate real long-conversation DS4/Pi BPE/auto-tuning objective is not established by these synthetic checks. No new provider budget was requested or used.

## Validation

The pre-version-change source at `b8614d0` passed the acquired local checks and the observed GitHub CI matrix (Node 22.19.0 and 24.x). Synthetic regressions reproduced supplement absorption before the group-isolation fix and passed afterward.

`npm ci` completed on supported Node 22.23.1 with the synchronized 0.5.3 manifests, constants and lockfile. The dev-inclusive installation audit reported six advisories (three moderate and three high); no dependency changes were made.

Final coordinated 0.5.3 verification and publication are pending the required `/jev verification reload` after the version change. The release remains manual-only; CI has no publishing credentials.