[puretensor]

Originally stacked on #9, which is now merged; this branch is rebased onto main and holds only its own two commits.

• index_vault holds an fcntl lock on <db>.lock for the whole run. A puremind index that overlaps another run is refused with StoreError (a RuntimeError, which the CLI reports cleanly). A puremind watch run waits for the other run to finish and then checks the model again, so a watch on an old model cannot write its vectors into an index rebuilt for another model.
• A changed vault root (another vault, or the same one moved) needs --rebuild. The rebuild first has the model embed a test passage, then clears the old rows and records the new root in one transaction before embedding. A model that cannot load leaves the index as it was.
• Purge debt is recorded in the same transaction as each replace or delete. It is cleared only after compaction and a successful checkpoint, and only if the generation has not changed.
• The lock reports a read-only index as read-only, opens its sidecar with O_NOFOLLOW, and turns other open or lock errors into a StoreError that names the lock file.

Tests: full suite: 729 passed, 6 skipped (Linux, Python 3.12). ruff 0.17.1 is clean.

🤖 Generated with Claude Code

[puretensor]

Verdict: fix, then merge.

What I examined. I read the lock, vault-switch and purge-debt changes against the code. Three independent reviews (correctness, safety, integration) examined the PR, including mutation probes. All three core claims hold:

• index runs are serialised by flock;
• the vault switch clears the rows and records the new root in one transaction;
• purge debt is written with each replace or delete, and cleared only after a successful checkpoint while the generation is unchanged.

Stack. #9 merged with its lint fixes. I retargeted this PR to main and rebased only its own commit onto main (clean), so the inherited ruff failure is gone. The commit subject now uses the repo's v0.2.0: form.

Fixed in a8e1f35:

• A --rebuild for a vault at another path cleared the index before checking that the model could run. A model that could not load left the index empty, where v0.2.0: bound search queries, record the embedding window, refresh unchanged stats, lock the inbox #9 had kept it. The rebuild now embeds the test passage first, as a model change already does, so the old rows and the recorded root survive. New test: test_a_model_that_cannot_run_does_not_cost_a_moved_vault_its_index.
• puremind watch ended at once if its first run met the lock. A later refused run dropped its change until the 10-minute rescan. Watch runs now wait for the other run, then check the model again, so the stale-model protection still applies. puremind index is still refused. New tests cover both the waiting run and the watch command.
• A read-only index failed with a raw PermissionError on <db>.lock. The lock now reports the read-only store first, opens its sidecar with O_NOFOLLOW (matching the inbox lock), and turns other open or lock errors into a StoreError that names the lock file. Tests added for both.
• The README and CHANGELOG now describe the watch-waits behaviour, and say that a rebuild for a moved vault empties the index after checking the model. The PR body is corrected.

Dismissed:

• When the indexer calls clear() without vault_root, a mutation of that survived the tests. It has no safety impact, because the root is set right after, under the same lock.
• After a purging run the WAL keeps a few KB of metadata while a connection is open. This is a documented trade-off, and the canary tests confirm no note text remains.

Tests:

• Full suite: 729 passed, 6 skipped (Linux, Python 3.12).
• ruff 0.17.1: clean.
• gitleaks over the branch: no leaks.
• Five mutation probes, one undoing each fix: all caught.
• The lock and vault tests passed 10 times in a row.
• CI on a8e1f35 is green on every job (macOS and Ubuntu, Python 3.11 to 3.14, mcp 1.x, lowest dependencies, installed wheel). "real models" is skipped, as it runs only on schedule or dispatch.