feat(cli): migrate a Postgres relay into LMDB, with resume, verify and a reported throughput - #1125

…page at a time

…urce carries them

…ifest

Two static findings, both from round 4.

`write_manifest` renamed its temporary file without syncing the contents or
the directory, so a power loss could leave `migration-manifest.json` as a name
pointing at truncated JSON. `read_manifest` refuses that, and the refusal of a
target that holds rows without a manifest then blocks the store it describes -
the operator's only way forward is a discard. The file is now synced before
the rename and the directory after it, and ADR 0012 D5 says so instead of
claiming only "a temporary file and a rename".

`RowSum::add` added its four words independently, dropping the carry between
them, while the ADR documents the checksum as the sum modulo 2^256. Copy and
verify agreed with each other so nothing was wrong in practice, but a checker
written from the document computed a different number. The carry now crosses
the word boundary - the loop runs from index 3 to 0 because limb 0 is the most
significant - and three unit tests pin it: a wrap carrying upward, a full wrap
to zero, and the ordering. The first two fail against the independent add.

`a_failed_run_reports_migration_failed_and_exits_1` also took 60 s: with
nothing on port 1 the connection is refused at once, but the pool still
retried to the acquire timeout. `DB_ACQUIRE_CONNECTION_TIMEOUT=1000` takes the
suite from 60.04 s to 2.29 s.

The resume check opened the store read-only to decide whether it was there.
heed keeps its environment registered for the life of the process, so the
writable open that follows answered `BadOpenOptions` - the probe refusing a
resume exactly when the store it wanted existed. It is the store's file that
is asked about now, which is what `data.mdb` means and what verify already
used, so nothing is opened and nothing is registered.

Nothing in the suite could see it: the one resume test that runs the command
fails on the source before the store is opened. `the_resume_check_leaves_the
_store_openable` drives the check and the writable open in one process, in
the order the run performs them; with the probe in place it fails
`an environment is already opened with different options`, and with the file
check it passes.

Three more from the same round:

- the documented checksum now has a golden value, computed outside the crate
  from one row's bytes on D4's framing (`len32 | key | canonical`, summed
  modulo 2^256). Removing the length prefix from `add` turns it red; the unit
  tests only ever pinned the carry.
- "verify creates nothing" was false: a read-only LMDB open recreates
  `lock.mdb` beside `data.mdb` (measured), and refuses a directory it cannot
  write it in. The comment and ADR 0012 now say what it does.
- the nine-name refusal had no fixture with the right count and a wrong name,
  so a count check would have passed it. One is added.

`open_existing` also stops carrying its own `#[allow(unsafe_code)]`: both
openers go through `LmdbEnv::open_with`, so the crate keeps the single
audited boundary its CLAUDE.md names. Its doc comment repeated the false
premise about dropping the handle freeing the path, as did the test comment
that dropped one for that reason.

`fe2823d`'s `phoenix@ricardocabral.go` stays as it is: it is published, no
ruleset requires signatures, and rewriting a branch a lens has read costs
more than the typo.

Asking about the store by its file tells a missing store from a present one,
not a store this run wrote from one truncated or written by something else
that still has a `data.mdb`: the copy would add the remaining rows to a table
that never held the ones the manifest counts and report success over a store
missing them. A table the manifest counts rows for must now hold at least one,
which is one read per counted table. Verify would have caught it, but only if
someone ran it.

Two documents still described the probe round 6 removed: ADR 0012's D5 said
the run "opens that store read-only first", and `backend.rs`'s `NO_LOCK` bullet
claimed no env flags are passed and the crate never touches the lock file.
`open_existing` passes `READ_ONLY`, and a read-only open recreates `lock.mdb`.
The guarantee is unchanged; its evidence is now accurate.

The six criterion-bearing branches the code lens could not see fail now can:
each was inverted and each turned tests red - the complete-manifest branches in
`run` and `migrate_with` (2 and 12 failures), the occupancy guard (5), the
manifest write (1), the skip of finished tables (11). The sixth, the report
sequence in `lmdb/metadata.rs`, turned nothing red, which was a real gap: a
migrated report with id 7 left the next `create` returning 1. It now has a test
that fails `left: 1, right: 8` when the comparison is inverted.

The manifest was created 0644 under a 022 umask and records the last key written per table.
For `invite_codes` that key is the invite code itself - a bearer credential NIP-43 accepts -
and the store's own files are heed's 0600, so the manifest was the world-readable copy of a
secret it was the only copy of. It is now created exclusively at 0600, which closes a second
hole with the same flag: a planted symlink at `migration-manifest.json.tmp` used to be written
through and renamed into place. Anything at the temporary path is removed first and the file is
then created with `create_new`, so a second plant fails instead of being followed.

Nothing inspected the target either. A group- or world-writable target lets another local user
pre-place `<target>/lmdb/data.mdb` and read the whole dataset out of a file they own; a symlinked
target sends the copy somewhere the operator did not name. Both are refused before anything is
opened, and the summary now prints the store the copy landed in.

Each of the three is proved red by the fix's absence: the manifest test fails on mode 0644 and on
the followed link, and both target tests fail on their message when the refusal is removed.

`.gitignore` gains root-anchored `/lmdb/` and `/migration-manifest.json`: `--target .` writes the
dataset into a public repository's working tree.

ADR 0012 also stops saying heed opens with no environment flags - the verify opener passes
`READ_ONLY` - and records the manifest's mode and the target refusal.

The run named none of the three things an operator needs when it goes wrong.

The source: `PostgresBackend::from_env` falls back to `postgres@localhost:5432/postgres` when
nothing is set, so an unconfigured run dialled whatever a local server held, and with nothing
listening it waited out the pool's 60 s acquire timeout (measured: exactly 60.00 s, "pool timed
out while waiting for an open connection"). The setting is now read and named first - `DB_URI`,
else `DB_HOST`/`DB_NAME`, with the password dropped - and one row is read before the copy so an
unreachable host is reported as the database it could not reach.

The store: the summary's `Store:` line is canonicalised, so a target reached through a link shows
the directory the copy actually landed in, and a `--target` that is a file is named as one
instead of failing on `Not a directory (os error 20)`.

The way back: the help says a re-run resumes and that deleting the manifest starts a new copy,
and the refusal of a store the manifest counts rows for repeats it.

`micros` and the `i32` key flip now live in one feature-free module, `crate::keys`, with
`lmdb::encoding` re-exporting them and `postgres::migration` using the same inverse. They were
restated three times, each with a comment explaining it had to compile without the other driver;
a divergence there is a false checksum mismatch after a full copy has already run.

Each guard is proved by its absence: without the source naming the test waits 60 s and fails on
the pool message; without the canonicalise the link test reports the argument; without the
password drop the credential is printed; without the help text the test has nothing to find.

`without_password` removed the userinfo's password and left everything else, so a URI that
carries the credential as a query parameter - `?password=secret` - was printed whole into the
error that reaches stderr and any captured log. The query string is now dropped as well, not
matched against credential-shaped keys: a percent-encoded key ends a name-based check, and the
description exists to identify the source, which the host and database already do.

Proved by absence: with the query left in, the test prints
`postgres://127.0.0.1:1/nostream?password=secret&sslmode=require` verbatim.

The description kept the user name after the password went. AC19 asks for the host and
database, a role is neither, and an identifier carried into a message that does not need it is a
smaller copy of the problem the redaction was written to fix. The userinfo, the query string
and the fragment all go; a permission error still names the role, because the server's own
message says it.

Three findings, none of them from a test that existed before it.

A replica that is offline must not stop a cutover. `from_env` dials the replica when
`READ_REPLICA_ENABLED=true` and fails when it cannot reach it, which is right for the relay and
wrong for a one-shot copy that reads the master and nothing else. `master_only_from_env` reads
the master settings and none of the replica ones; the test proves it by pairing a zero replica
count - which makes `from_env` refuse before it dials - with the master-only opener, which then
fails on the connection instead.

The help promised a restart that the tool refuses: "delete `migration-manifest.json` to start a
new copy" leaves a store that holds rows and no manifest, which is exactly the shape `migrate_with`
declines to copy over. It now says a fresh `--target` is what starting over takes, or both gone
together.

The store directory is created 0700 rather than at the umask's mercy. On a host with umask 002
`create_dir_all` leaves the dataset group-writable, which is a wider audience than heed's 0600
files - and is refused by the migration's own target check on the next run, so the tool would
decline its own store.

All three are proved by absence: the master-only test fails with `READ_REPLICAS must be at
least 1` when the opener reads the replica settings, the help test has nothing to find when the
sentence is the old one, and the directory test reads 0755 when the builder takes the umask.

The target check read the directory's type and permission bits and stopped there. An owner can
replace a directory between that check and the open whatever its bits say, so a copy running as
root over a predictable path in a shared directory follows the replacement into files the other
user can read - which is the redirect the mode check was meant to close.

The owner is compared with the process's effective uid. `std::fs` exposes a file's owner but
not the caller's, and this crate runs on Linux, so the uid comes from `/proc/self/status` rather
than a new dependency for one integer. When `/proc` cannot say, the mode check is what stands.

Proved by absence: the refusal is measured against uid 0 on a directory this process owns, and
removing the branch makes that test fail. It cannot be measured end to end here because making a
directory belong to another user needs root.

The ownership test passed `Some(0)` and expected a refusal, which holds only when the test
process is not root. A suite running as root creates a root-owned tempdir, the check correctly
allows it, and `expect_err` fails - so the test would have broken `cargo test --workspace
--all-features` in a root-run container while proving nothing about the code.

It now reads the directory's own owner and passes a different uid, which is the property the
refusal is about.

… or fails fast

Five contract misses from the frozen-head lenses.

The target gate inspected `<target>` and `<target>/lmdb` and never `data.mdb`, which `is_file()`
and LMDB both follow: a link there sent `--verify` through it into `mdb_env_open` and heed wrote
`lock.mdb` beside whatever it resolved to. The gate now reads the file's own metadata and refuses
a symlink (proved by a unit test that plants one), a non-regular file, and a foreign owner.

`without_credentials` returned any string without `://` untouched, so
`postgres:alice:secret@127.0.0.1:1/nostream` - the shape libpq accepts - printed the password.
The query, the fragment and everything up to the last `@` now go before the scheme test.

The source pool dialled eagerly, so an unreachable host spent the pool's sixty-second acquire
timeout before the probe could say anything (measured: 60.003 s, red proof). It is built lazy
and the probe bounds the wait with `MIGRATION_CONNECT_BUDGET_MS` (10 s); at the shipped setting
the same source now fails in 10.00 s, and the test asserts the clock rather than shortening the
setting.

The store path has one home: `open_existing` and `data_dir` both call `store_dir`, and
`data_dir` regained the doc comment the insertion had taken.

And the false remedy is gone from all three places it survived - the help (round 10), the
refusal string and the test that pinned it, and ADR 0012. Deleting the manifest does not restart
a half-filled store; a fresh `--target` does, or the manifest and the store removed together.

…ore_dir

`1fc47e5`'s message said both openers call `store_dir`; only the writable one did. That made
`store_dir`'s "one home for the shape" false and left the branch record asserting a fix the tree
lacked, so the correction is to make the claim true rather than to rewrite a published message.
`open_existing` now calls `store_dir` too, and three docs stop saying things the code does not:

- `master_only_from_env` no longer reads as a constructor that dials. It builds a lazy pool, so
  `Ok` means the settings parse, not that the server answers; the copy's probe is what waits.
- `MIGRATION_CONNECT_BUDGET_MS` is the probe's *default*, not the longest a migration waits:
  `DB_ACQUIRE_CONNECTION_TIMEOUT` overrides it, and later batches use the pool's own acquire
  timeout.
- `store_dir`'s paragraph is left as written, because the two openers now make it true.

…t a host

Two confirmations, both right, both about the same habit: the code trusted something the
shipped configuration does not provide.

The probe read the source through the pool, so sqlx retried a refused socket until the pool's
acquire timeout. With `DB_ACQUIRE_CONNECTION_TIMEOUT=60000` - the value `deploy/env.example`,
`SETUP.md` and `CONFIGURATION.md` all ship - that was 60 013 ms and the pool's sentence, byte
for byte what the branch printed before the first AC19 fix. And even the fast path never printed
the reason: the pool's message was always what surfaced. It is one direct connection now, bounded
by `MIGRATION_CONNECT_CAP_MS` (10 s) whatever the pool is told, so a refused port answers at once
with `error communicating with database: Connection refused (os error 111)` and a black-holed
host is capped rather than silent. Red proof: without the direct attempt the same test takes
60.017 s and the clock assertion fails.

A schemeless `DB_URI` is now refused before anything is dialled. sqlx parses one as a URL with no
base: the opaque path becomes the database name and the host falls back to localhost, so the copy
dials the wrong server and a failure echoes the string back - with the password in it - as
`database "alice:secret@host:5432/db" does not exist`. Redacting the message was never enough.
The test that asserted the redaction is now a refusal test, and it fails without the check.

The constant is named for what it is: a cap, not a budget, because the operator's setting lowers
it rather than the other way round.

The refusal for a hostless `DB_URI` was too strict and too loud.

Too strict: it read the authority alone, so `postgres:///?host=/var/run/postgresql&dbname=nostream`
and `postgres:///?hostaddr=127.0.0.1` were refused - both shapes sqlx dials, and the only ones a
Postgres behind a Unix socket offers. A relay backed by a socket could no longer be migrated at
all, which is a regression introduced by the fix for a leak. The rule now refuses a string with no
`://` at all, and accepts an empty authority when the query names `host` or `hostaddr`. Red proof:
with the authority-only rule the two new tests fail and the message reads
`not a URL with a host (postgres:///)`.

Too loud: the refusal echoed the value after `without_credentials`, which strips userinfo and a
query - and a libpq keyword string has neither, so `DB_URI="host=… password=s3cret"` printed the
password. The refusal now names the shape and neither shape's value. Red proof: with the echo
restored the new test finds `s3cret` in stderr.

The clock test's comment is corrected to what it proves. A refused port answers in milliseconds
whatever the bound is, so inverting `.min(cap)` leaves it green; the message and the fast path are
what it tests, and `#1122` carries the cap's duration on a host that drops packets.

Measured against sqlx's own parser: `postgres:/`, `postgres://` and `postgres:////` all parse to
`host=localhost`, and the empty string does not parse at all. The check refuses the first three,
which is stricter than sqlx by design - a cutover that guesses which server to copy from is worse
than one that stops. The test records the divergence and the reason, so nobody later "fixes" it
back to sqlx's behaviour.

Red proof: with the shape check made permissive, `postgres://` is dialled and the test fails with
`could not read the source at postgres:// … Connection refused` - it went looking for a server it
was never told about.

The sentence closing the previous doc defect wrote `postgres://` with two opposite meanings: the
paragraph above refuses it, and the list of what is accepted meant the scheme. It now names
`postgres` and `postgresql`, so the two sentences cannot disagree.