[Wired4ncer]

Slice 1 of #23: the persistence layer, so that enrolment has somewhere to write spk_ct and #21 has something to read back. Nothing here accepts a request yet; the API and the arming service are the next slice.

What is in it

storage/ — the §3 schema in SQLite: secure_delete=ON, WAL, foreign keys with cascade, day-precision timestamps, no event table (I3). The capability token is minted once and only sha256(token) is stored. spk_ct / label_ct / dest_ct are AEAD under k_store with the column's purpose and the tenant id as associated data, so a ciphertext cannot be read as another column or moved between watches.

The item state machine is enforced by the store, not trusted to the caller: arm only from arming; activate only from armed and only once a routed channel has a confirmed test-fire (I5). Store is also the matching loop's WatchIndex, so tests/test_store.py runs the real Matcher on the file.

One state added to the sketch — armed, between arming and active. The baseline scan finishing and the user confirming the test-fire are minutes to days apart, and a coin spent in between is still a spend the block path must fold in; so armed and paused items are tracked but not alertable. Architecture §3 has the reasoning.

crypto/ — ChaCha20-Poly1305 (RFC 8439), hand-rolled under the #3 policy and checked against the RFC's own vectors (§2.5.2, §2.8.2, A.3, A.5). ChaCha20 moves here from channels/nostr/; a shim keeps the old import working. No new dependency.

What the tests measure rather than assume

The important ones read the database file's raw bytes after the connection closes: the script, label, destination and token are absent from the file; the keyed hash is present; a purge leaves neither the ciphertext nor the token hash behind.

Review

Independently reviewed before this PR was opened. Three findings fixed in the second commit, each reproduced first:

1. add_outpoint after a concurrent purge_watch raised a foreign-key error out of the block path (INSERT OR IGNORE does not cover FK failures) and nothing above Subscriber.run catches it — one tenant purging at the wrong instant stopped every tenant's watcher. The same window with stop_item left a stopped item owning a coin that would later match OUTGOING. The insert is now conditional on the item existing and being tracked.
2. The docs prescribed "replay missed blocks, then arm". Against this index that is a no-op — an arming item is invisible. The order is arm first, then replay, for that item only, serialised with the live block path. Corrected before Enrolment API, capability tokens, and the ARMING state machine #23 builds on it.
3. Smaller: BadTransition for pause/resume from the wrong state; a newer schema version is refused rather than re-stamped; the VACUUM in purge_watch recorded as a known-equivalent mutation (unobservable while secure_delete is on); the threads test renamed to what it actually checks.

Not addressed, noted for the next slice: watch.status (grace/stopped) is not consulted by the index and nothing sets it yet.

Second review (2026-09-24)

A second review after opening found two more defects, both reproduced before fixing; four rounds of independent review of the fixes, each SHIP.

1. A purge left the tenant's data in -wal. The token hash and spk_ct stayed in the write-ahead log for as long as the connection was open, which in a running service is always; the purge test only looked after close. purge_watch now ends with VACUUM + wal_checkpoint(TRUNCATE) and raises PurgeIncomplete if another connection blocks either -- at once, not after a 5 s busy wait with the store's lock held. finish_purge() is the retry (a second purge_watch cannot be: the rows are gone). Only SQLITE_BUSY/SQLITE_LOCKED are retryable; any other error propagates as itself. The test now also reads the file with the connection open.
2. Ids were reissued after a purge. Plain INTEGER PRIMARY KEY hands out the highest id again once its row is deleted, so the next tenant got the purged tenant's watch, item and channel ids -- and an id still held in memory by the block path or a delivery would resolve to the wrong tenant, or decrypt the wrong tenant's destination. watch, watch_item, channel and outbox are AUTOINCREMENT now. The cost is sqlite_sequence, a count of ids ever issued; §3 records it.

Also: journal_mode=WAL is checked rather than assumed, and store.py now states the one remaining gap -- outside a purge, a deleted row's old page (a spent coin's outpoint_hmac, later a completed outbox row) stays in -wal until the log wraps. Keyed hashes, not ciphertexts.

Numbers

505 tests. 30 mutations for the new modules, all caught, none recorded as survivors; 106 in the sweep. The VACUUM mutation is caught only because a test sees that it ran -- what it cleans beyond secure_delete is still untested, and the mutation is named to say so.

🤖 Generated with Claude Code

[Wired4ncer]

Independent review — fix two things before merge

Reviewed at 44587b1. All 500 tests pass against this branch's own source. The ChaCha20-Poly1305 transcription matches RFC 8439 on reading, and it is checked against the RFC vectors. The state machine, the add_outpoint race fix, the armed state and the "arm first, then replay" order all hold up. The docs changes match the code.

1. Purged data stays on disk while the connection is open

After purge_watch, the -wal file still holds the purged tenant's token hash and spk_ct. Reproduced with the connection still open: both present, WAL at 156,592 bytes. They only go away when the last connection closes and SQLite deletes the WAL. A long-running service rarely closes it.

test_purge_removes_the_tenant_and_the_bytes reads the bytes only after Store is closed, so it cannot see this.

Fix: after the VACUUM in purge_watch (store.py:235), run PRAGMA wal_checkpoint(TRUNCATE) and check that its busy column is 0. Verified: the WAL goes to 0 bytes and neither value remains in the file. The test should also read the bytes before closing.

2. Row ids are reused after a purge

watch, watch_item and channel use INTEGER PRIMARY KEY without AUTOINCREMENT, so SQLite reuses the highest id once that row is deleted. Reproduced: purge watch 2 (item 1), create a new watch, and it gets watch id 2 and item id 1 again.

Why it matters:

• The add_outpoint docstring already says the loop can hold an item id while the API thread purges it. That id can now belong to another tenant. The status IN (tracked) guard only helps while the new item is still arming.
• A delivery holding an old channel id would call channel_dest and decrypt the new tenant's destination. That sends one tenant's alert to another tenant.
• The AAD binds each ciphertext to a tenant id, and that binding is weaker when ids are not unique over time.

Fix: add AUTOINCREMENT to those three tables. Verified that it stops reuse. Side effect: sqlite_sequence then stores how many rows were ever created, which roughly tells how many tenants the service has had. That is probably acceptable, but it belongs in §3.

Minor (fine as follow-ups)

• Swaps within one tenant. The AAD is purpose + watch_id only, so someone with write access to the file could swap spk_ct/label_ct between two items of the same tenant, or dest_ct between its channels. Nothing ties spk_ct to spk_hmac either. Adding the item or channel id to the AAD closes it. The PR only claims per-tenant binding, so this is not a false claim.
• Lengths are visible. Ciphertext length shows plaintext length. For spk_ct that shows the script type (22 vs 34 bytes); for label_ct, the label length. Pad before sealing if that matters for the threat model.
• CONTRIBUTING, "no transitive requirements". True on CPython, but pyzmq requires cffi on PyPy (implementation_name == "pypy").
• Mutation count. The PR body says 20 mutations were added and the first commit message says 18. The CI comment's 96 comes from the tool and is right.