cairntir

v1.7.0 Release Acceptance

Status: accepted for publication Prepared: 2026-08-13 Target: v1.7.0 Origin: external upgrade review of 1.4.1 → 1.6.2 against a live 3,586-drawer store (Jarvis, for Lou), 2026-08-11

Why a MINOR

By the Release Cadence tiebreak — if a user would need to read the changelog to know what changed, it is a MINOR — two changes qualify:

• The model cache moves from fastembed’s ambient default to cairntir_home()/models, so the ONNX model downloads once more.
• cairntir reindex now refuses a store containing drawers wider than the embedder window, where it previously succeeded and silently truncated them.

Everything else is a fix. This is not a patch.

No reindex required

The embedding space is unchanged from 1.5.0: same model, same 512 dimensions, same embedding_space_id. Only the location of the cached model file changes. The live store was checked before tagging and reports state=verified dim=512, so no migration or reindex is part of this upgrade.

Automated acceptance

• full test suite — 685 passed, 83.13% coverage
• opt-in semantic eval — 3 passed, including the rewritten test_the_window_covers_the_whole_live_corpus
• Ruff lint and format — clean, 107 files
• mypy strict — clean, 51 source files
• silent-exception scanner — clean
• release tag check (scripts/check_release_tags.py) — clean
• landed commitments — 114 across 6 documents
• seam guards — 8 declared, all exercised on both sides
• store health — clean
• strict MkDocs build — clean
• sdist and wheel build — cairntir-1.7.0.tar.gz, cairntir-1.7.0-py3-none-any.whl
• isolated wheel install, redirected Windows help, bundled-recipe smoke
• CI green on the full matrix (ubuntu/macos/windows × py3.11/3.12/3.13), 14/14 checks on both #64 and #65

Live store evidence

Read before tagging, without writing:

db            : %LOCALAPPDATA%\cairntir\cairntir.db
model cache   : %LOCALAPPDATA%\cairntir\models
drawers       : 425   wings: 24
longest drawer: #239  8,924 chars  2,377 tokens
headroom      : 3.45x (window 8,192)
over window   : 0 drawers
index state   : verified  dim=512

The rewritten window test measures this store with the real tokenizer rather than comparing two literals. Note that 2,377 tokens matches the constant the old test froze — the literal was accurate for this store, which is precisely why the test stayed green while being false on the reviewer’s 3,586-drawer corpus, where the longest drawer is 6,414 tokens and the true headroom is 1.28x.

Isolated wheel smoke

Fresh venv, wheel installed from dist/, run from outside the source tree:

• cairntir version → cairntir 1.7.0
• cairntir --help redirected to a file → exit 0, 60 lines, no cp1252 crash (the Windows encoding regression fixed in 1.2.0 stays fixed)
• cairntir recipe-list → all three bundled recipes resolved from site-packages/cairntir/recipes/bundled/: codeglass, decision-replay, signal-reader

Two fixes were confirmed by the install itself. The model downloaded into the new anchored cache at %LOCALAPPDATA%\cairntir\models\, proving the cache relocation, and the directory it created is models--xenova--jina-embeddings-v2-small-en — direct confirmation of the provenance finding that the declared jinaai/… identifier resolves to a third-party re-conversion.

Known limits

• One unexplained stderr line. The very first invocation of the freshly created smoke venv, run from inside the source tree, emitted UnicodeDecodeError: 'charmap' codec can't decode byte 0x8f to stderr while printing the correct version to stdout. It did not reproduce across four subsequent attempts, including one with the update-check cache deleted to force a cold PyPI check, and it never appears outside the source tree. Cause unidentified. Recorded rather than explained away; if it recurs, start with the update-notifier thread, whose exception handling catches OSError, URLError, JSONDecodeError and TimeoutError but not UnicodeDecodeError.
• Model weights remain unpinned. ModelSource has no revision field, so the download takes the upstream repository’s HEAD and integrity checking is size-only. Two machines provisioned a month apart can hold different weights under the same model name. Closing this needs a fastembed API that does not exist yet; the exposure is documented on PRODUCTION_MODEL.
• Operational items not performed. Cairntir was disabled for the entire development session at the maintainer’s request — removed from both MCP scopes and the server process killed — because the editable install means a running server holds the code under repair. So the live MCP health check, the Codex/Cursor restarts, and the three-host smoke were not run for this release. Automated adapter coverage is the fallback, as the checklist allows. Nothing from the session was written to the store; it must be caught up from CLAUDE.md and this changelog.

Publication

Tag v1.7.0 pushed to trigger trusted publishing. Confirm the GitHub Release, the PyPI upload, and both provenance attestations before considering the release done. If a tag push creates no workflow run, check https://www.githubstatus.com before suspecting the workflow — that was the cause in 1.4.1, and the escape hatch is gh workflow run release.yml --ref v1.7.0, which is legitimate because the publish jobs gate on the ref being a tag.

PyPI’s aggregate /pypi/cairntir/json lags the per-version endpoint by minutes. Checking only the aggregate immediately after publishing produces a false “publish failed” verdict. Confirm with /pypi/cairntir/1.7.0/json.

This site is open source. Improve this page.