fix(storage): stop answering AlreadyExists for a chunk whose file has gone

[grumbach]

A client PUT is checked against what the node already holds before any payment is verified: handle_put_inner calls ChunkStore::holds_verified, and a true is answered AlreadyExists straight away, ahead of the capacity check, the closeness gate and verify_payment.

holds_verified could create the chunk it was asked about. In its file-store match, the arm after "bytes identical" was Ok(_), which also caught Ok(None): the index still named the chunk, but its file was gone. The read drops that index entry, and the arm then called FileStore::repair with the offered bytes. On Unix the repair publishes through a temporary and a rename, so it recreates the file, puts the index entry back, and holds_verified returns true. The result: a PUT carrying no payment for a chunk whose file had vanished was stored and answered AlreadyExists, with no payment check, no closeness check, and no replication fan-out. Off Unix the repair opens the existing file without create, so there it fails, returns false, and leaves the key marked wrong.

It needs a file that has vanished while the index still names it: a file removed outside the node, or one caught between its unlink and its index removal by a corruption cleanup, or by a delete whose caller was cancelled. A remote client cannot produce that state, the offered bytes are always hash-checked, and clients pay before they PUT, so no client loses money. It is still a pre-payment write of a chunk the node did not hold, and it contradicts what holds_verified is documented to answer.

The fix

An Ok(None) arm of its own. It writes nothing:

• If the legacy environment still holds exactly the offered bytes, the node does hold the chunk (a copied chunk normally stays in LMDB until it is deleted or the environment is retired). The answer is true, and the key goes back into the legacy-only set, the same thing get already does when it falls back to LMDB for a missing file.
• Otherwise the answer is false, and the offer goes through the ordinary path, which checks capacity, closeness and payment before put publishes it.

The Ok(Some(_)) repair arm for a file that is present with the wrong bytes is unchanged, as is the legacy-only branch above it.

Left as it is: when LMDB holds different bytes under the key and a paid PUT then fails in the file store, put files the key as legacy-only, because LMDB reports an existing key as a duplicate without comparing bytes. That is put's existing behaviour for any such key, the client gets StorageFailed, and the copier drops the key when it finds the legacy bytes wrong. Closing it would add an LMDB read to every duplicate dual write.

Linear issue

Closes V2-1259

Risk tier

• T0 — docs / tooling / CI / pure UX-output. Repo CI only.
• T1 — client-only, no network-facing behavior change. CI + prod compat smoke.
• T2 — node/client logic with behavioral surface, no protocol/format/economics change. Dev testnet + ADR.
• T3 — protocol / storage format / payments / routing. T2 evidence + adversarial testing.

Compatibility

• Wire: none.
• Storage: none. No format change; the only store state that behaves differently is a chunk whose file is missing while the index still names it.
• API: none.

Semver impact

• breaking
• feature
• fix

Test evidence

Local, on 31fcbae plus this branch (macOS, APFS):

• cargo test --lib: 1089 passed, 0 failed.
• cargo fmt --all --check, cargo clippy --all-features --all-targets -- -D clippy::panic -D clippy::unwrap_used -D clippy::expect_used, RUSTDOCFLAGS=--deny=warnings cargo doc --no-deps and RUSTFLAGS="-D warnings" cargo build --release --no-default-features: all clean.

Test	What it catches
a_chunk_whose_file_has_gone_is_not_written_back_by_the_check	no legacy environment: file removed under an indexed chunk, holds_verified must answer false, write nothing, and leave put able to publish it as new
a_chunk_whose_file_has_gone_is_still_held_while_the_legacy_environment_has_it	a copied chunk whose file is removed: true, no file written, key back in the legacy-only set
a_chunk_whose_file_has_gone_is_not_held_on_wrong_legacy_bytes	the same, with different bytes under the key in LMDB: false, no file written, key not requeued
test_put_for_a_chunk_whose_file_has_gone_is_not_already_exists	the handler: an unpaid PUT for such a chunk is refused by the payment check, not answered AlreadyExists, and nothing is written

Mutation-checked: with the old Ok(_) arm restored, all four fail (the handler test gets AlreadyExists). With Ok(None) => false and no legacy lookup, only the legacy-held test fails. With a legacy lookup that accepts any bytes, only the wrong-bytes test fails. The existing a_damaged_chunk_is_repaired_from_the_copy_being_offered and a_legacy_only_chunk_with_wrong_bytes_is_replaced_by_the_offer pass either way. The file-vanished tests discriminate on Unix, where the old repair recreated the file; CI's Linux and macOS jobs run them.

Not covered: a dev testnet run. The state needs a file removed underneath a running node.

The same arm is on rc-2026.9.2 (src/storage/chunk_store.rs, holds_verified).

New dependency

none

ADR

https://github.com/WithAutonomi/ant-node/blob/31fcbae2688a1d81008ef1b57fe09eda4b13817b/docs/adr/ADR-0014-file-based-chunk-store-and-lmdb-retirement.md

Mitigation / rollback

Revert the commit. The only behaviour that changes back is the answer for a chunk whose file is missing while the index still names it.