Roadmap and Releases

• Releases are receipt-gated, not calendar-gated. There is no sprint cadence and no scheduled ship date. A default changes when a measurement says it should, and the measurement ships with it — including the measurements that cost something.
• The canonical record is CHANGELOG.md. Every default flip there carries its receipt path, its caveat, and its opt-back-in line. This page is the reading order, not a replacement.
• The forward plan is docs/ROADMAP.md — the sequencing layer that says which track a piece of work sits under.
• Install from PyPI: pip install cymatix-context. Released versions are git-tagged (v0.9.0, v0.8.6, …) on the repository.
• This wiki documents 0.9.1, which is in flight at the time of writing. Each item below carries its PR or issue number.

0.9.1 — in flight

Five threads. One moves the retrieval defaults, one changes what a fresh ingest produces, and the rest are additive or ship off.

Wave-1 ranking flip (#407)

• The one default change in the release. On the 829k bed at full needle power, gold-document delivery moves 0.555 → 0.630 (+43 / −8 paired), recall@12 0.651 → 0.681, median gold rank 3 → 2, with zero question-type regressions.
• It ships as a single named commit so git revert is a one-step rollback, and the post-flip repository cymatix.toml was verified field-identical to the measured arm config.
• The cross-shard merge constant deliberately stays at 60 — that surface was never measured, and is annotated as unmeasured in code rather than flipped on faith.
• The full receipt, the bed identity, and why 0.630 is not a successor to the shipped-defaults 0.565 row are on Benchmarks and Receipts.

Two new knobs, both shipped off (#409, #412)

• [budget] min_delivered_docs (default 0 = byte-identical legacy behavior). At floor 12 the receipts measure delivery 0.630 → 0.668 with zero losses, and per-needle ranking bases byte-identical — a pure delivery change. The flip was deliberately not taken: the benchmark measures delivery, not answer quality under a wider seat count, and twelve full-length documents per window costs real tokens. The answer-quality lane has to run before the default moves.
• [ingestion] entity_autolink_hub_cutoff (default 0 = off, pinned byte-identical by test). On a hub-heavy 289k-document bed it takes the mean per-link call from 210.5 ms to 0.62 ms — roughly 340×. The default stays 0 because the edge delta is real: the graph that comes out is a different graph, so the knob ships opt-in with the receipt attached. Flip conditions live on #411.

Tagger v2 (#413) — a behavior change with a version bump

• The CPU ingest tagger now rejects entities containing newlines or tabs, plus email/MIME header field names, x-* extension headers, and MIME transport artifacts. On a 2,000-file EnronQA sample that is −16.7% entity-graph rows and zero multi-line entities, with document ids unchanged.
• This is a comparability break by design. Tags are part of the bed-content digest, so TAGGER_VERSION = 2 is declared in the tagger, recorded in every bed manifest, and added to the BASELINES rules. Every bed built before 2026-08-30 is tagger_version = 1 — internally valid, but not cross-comparable with a v2 bed.
• There is no backfill script on purpose: stripping entities in place would produce hybrid v1/v2 beds. v2 beds are fresh builds.
• Origin issue: #410.

Lexicon Tier 2 and the docs pass

• Tier 2 aliases (#419) land on every operator-facing surface — [compressor] / [knowledge_store] config sections, retrieval_tokens / max_docs_per_turn keys, CYMATIX_STORE_PATH, cymatix document get, --max-docs, GET /documents/{id}, canonical cymatix_document_* MCP tools. Additive only; every legacy spelling keeps working, with legacy winning on collision. This closes the long-deferred R4 phase (#87).
• Tier 3 — the wire surface — was deliberately not taken. See #417 and the Lexicon.
• Documentation: this wiki (also rendered at https://cymatixcontext.com/wiki/), docs/ROSETTA.md retired to a stub pointing at Lexicon, a repo-wide software-term prose sweep, and a shorter README that hands depth to the wiki.

0.9.0 (2026-08-20) — the post-flip release

The release where the shipped default retrieval path became fully algorithmic. Five encoder-related defaults flipped off, each behind its own receipt.

Every one of these is one config line to opt back in. The receipts and their caveats are on Benchmarks and Receipts; the per-knob view is on Configuration.

The two disclosures shipped with the release notes, not after them:

• The know surface never fires at shipped defaults (#287). Max confidence lands around 0.28 against an emit_floor of 0.45, and the lexical_dense_agree calibration feature is structurally dead on the neural-free path. The failure direction is fail-safe — 0% false-KNOW — but it means the confidence scalar is not a usable trust signal today; rely on found / reason. See Agent Contract.
• The dense-off default carries a measured p50 latency regression (#374): ×2.5–2.6 slower at 100k fragments, shrinking to ×1.09–1.38 at the 829k operating point. Dense was load-bearing as a latency device — its ANN gate capped the candidate list feeding splice. The named mitigation, a lex-branch candidate cap, has not landed.

Also in 0.9.0: [budget] neutralize_control_tags flipped on (assembly-time escaping of forged <cymatix: control tags, gated on a 141/141 byte-identical-window receipt), a startup warning for a non-loopback bind with an empty admin_token, the MCP 2.x migration, and the #219 slice-5 config honesty pass that removed five knobs with zero runtime readers.

Earlier releases

Full entries, including the pre-0.7 line, are in CHANGELOG.md. The vocabulary shift these releases are often confused with — biology terms to software terms — is a separate story, told on Lexicon.

What is deferred, and where it is tracked

• The 0.9.x deferral ledger is the comment dated 2026-08-19 on the v0.9.0 release-gate issue #377. That comment is the sequencing record for the work 0.9.0 knowingly did not do — the know-gate recalibration (#287), the sharded structural gap (#275), the retrieval-profile layer (#205), and the rest. Read it before proposing that something be picked up; it usually says why it was not.
• The entity_graph layer ships on and has never been ablated on the delivered basis. It sits on the retrieval-layer ledger as a REMOVE-CANDIDATE, and the arm is still owed.
• The sharded path trails the unsharded engine by roughly 31pp recall@10 and 30pp MRR on the xl bed (#275). Prefer unsharded for accuracy-sensitive corpora; the gap is disclosed, not fixed.
• Open and named, as of 0.9.1:

How releases work here

• Versioning is MAJOR.MINOR.PATCH, but the number alone will not tell you whether an upgrade is safe. 0.8.5 was a deliberate breaking change shipped as a patch-level bump — called out as breaking in the changelog, with a pin instruction. Read the changelog entry, not the digits.
• No formal cadence. Nothing ships to a date. The gate is a receipt, and when the receipt says a change is null or negative the change does not ship — the wave-2 COVER-walk arm in this same 0.9.x window was killed by its own receipt.
• Defaults move separately from features. A knob and its default flip are different pull requests: the knob ships default-inert with a test pinning byte-identical legacy behavior, and the flip is its own receipt-gated change. Both #409 and #412 in 0.9.1 are knobs whose flips were not taken.
• Disclosures ship with the release, not after it. If a flip costs latency, or a surface silently stops working at defaults, it goes in the release notes next to the win.
• Comparability rules are part of the release contract. tagger_version and ingest concurrency (ingest_c) are bed identity; a receipt measured on one bed does not license a claim about another. See Benchmarks and Receipts.

Go deeper

• CHANGELOG.md — every release entry with its receipt paths, caveats, and opt-back-in lines
• docs/ROADMAP.md — the forward-planning doc: live tracks, issue triage, and the cross-box data pipeline
• docs/benchmarks/BASELINES.md — the bed-identity and receipt ledger every number above is anchored to
• #377 — the v0.9.0 release gate, whose 2026-08-19 comment is the 0.9.x deferral ledger
• https://pypi.org/project/cymatix-context/ — released versions
• Next: Benchmarks and Receipts · Configuration · Lexicon · Home