[fence 1/9] libsql-server: document the namespace fence contract

[tszymczyszyn-shopify]

Parked (2026-10-14). We are not pursuing this stack for now, so please do not review or merge it. The existing per-namespace block_writes and block_reads settings, together with operator checks, cover what we need today. The branches stay up for reference.

If we need more server support later, the likely follow-ups are small, separate changes: refusing replication and /dump while reads are blocked, a conditional POST /config, and block flags at namespace creation.

---

Adds docs/NAMESPACE_FENCE.md, the contract for the operation-owned namespace fence: state model and permission matrix, admin API, durable state, outcome codes and their mapping per protocol, write admission and positive drain, source read fence, target lifecycle, restart and failure semantics, deployment and compatibility, and observability.

It started as the final version of the document from the source PR, landed first so the design can be reviewed before any code; two follow-up commits bring it up to date with the rebase onto #53 and with review. The code pieces that follow implement it; none of them edits the document.

Review focus

The state model (section 3), the outcome codes (section 6), and the deployment/compatibility rules (section 13). Agreeing on these first makes the rest of the stack a check against the contract.

Since the first version: the import API names the shared dump importers (rebase onto #53), and from review the section 3.3 matrix now matches section 3.2 and transition.rs, section 13.5 states the cross-namespace lock order for fork, section 9.1 describes the unfenced SQL read fast path, and section 17 no longer claims every test is in one change.

Commits

• libsql-server: document namespace fence contract
• docs: point the fence import API at the dump importers (rebase onto libsql-server: make namespace creation all-or-nothing (stacked on #51) #53)
• docs: complete the fence contract from review (review)

Stack

Part 1 of 9, based on tszymczyszyn/atomic-namespace-create. The stack sits on #53 (tszymczyszyn/atomic-namespace-create), which sits on #51: review and land #51 → #53 → #41 → … → #49 bottom-up, restacking after each squash or rebase merge.

The first version of these PRs carried #35's fence diff unchanged on v0.9.30-shopify-patches. On 2026-10-13 the stack was rebased onto #53 (how the conflicts were resolved is summarised in a comment on #41) and gained the commits marked above.

• [fence 1/9] libsql-server: document the namespace fence contract #41 [fence 1/9] libsql-server: document the namespace fence contract (this PR)
• [fence 2/9] libsql-server: fence model, durable state and fail-closed recovery #42 [fence 2/9] libsql-server: fence model, durable state and fail-closed recovery
• [fence 3/9] libsql-server: fence controller, WAL write gate and positive source drain #43 [fence 3/9] libsql-server: fence controller, WAL write gate and positive source drain
• [fence 4/9] libsql-server: source read fence for SQL, dump and replication streams #44 [fence 4/9] libsql-server: source read fence for SQL, dump and replication streams
• [fence 5/9] libsql-server: migration target lifecycle and import capability #45 [fence 5/9] libsql-server: migration target lifecycle and import capability
• [fence 6/9] libsql-server: namespace fence admin API and lifecycle interlocks #46 [fence 6/9] libsql-server: namespace fence admin API and lifecycle interlocks
• [fence 7/9] libsql-server: typed fence outcomes across protocols #47 [fence 7/9] libsql-server: typed fence outcomes across protocols
• [fence 8/9] libsql-server: replica servers honour the replicated fence #48 [fence 8/9] libsql-server: replica servers honour the replicated fence
• [fence 9/9] libsql-server: fence operations: provenance, adoption, metrics #49 [fence 9/9] libsql-server: fence operations: provenance, adoption, metrics

[tszymczyszyn-shopify]

Rebased the fence stack (#41–#49) onto #53 (tszymczyszyn/atomic-namespace-create at bb446259f6), so the namespace fence and the streaming dump importer / atomic namespace creation can land together. This PR's base is now that branch. Intended merge order: #51 → #53 → #41 → … → #49.

How the conflicts were resolved:

• Namespace creation. Generic create and fork keep libsql-server: make namespace creation all-or-nothing (stacked on #51) #53's Reservation; creating a quarantined migration target keeps its single metastore transaction. The fence's checks (check_available, check_lifecycle) now run inside Reservation::acquire, under the name's entry lock, so they cannot go stale; fork still holds the source's transition lock.
• One read-only lookup. The fence's MetaStore::lookup() replaces libsql-server: make namespace creation all-or-nothing (stacked on #51) #53's existing_handle(); MetaStore::handle() is fallible everywhere.
• One dump loader. ImportSession loads through namespace::dump_import (buffered by default). New ImportSession::load_dump_with(kind, cfg, stream) can select the memory-bounded streaming importer and returns its statistics.
• Both clean-ups stay. Discard (undo a creation that failed) and forget_unstored (forget a lazy creation the fence refused) do different things and are kept separate.

New commits (everything else is the original commits replayed):

• [fence 1/9] libsql-server: document the namespace fence contract #41 docs: point the fence import API at the dump importers
• [fence 5/9] libsql-server: migration target lifecycle and import capability #45 let the dump importers run on any connection, refuse a migration target over a reserved name, test streaming imports into a quarantined target
• [fence 6/9] libsql-server: namespace fence admin API and lifecycle interlocks #46 leave names with fence state alone when undoing a creation

Local verification (macOS): cargo fmt --check clean; cargo check --all-targets --all-features for libsql-server/libsql_replication with no new warnings; lib tests at every PR head; the nextest integration suite gives the same result as the stack before the rebase.

[tszymczyszyn-shopify]

Closing. This stack is parked; the note at the top of the description explains why. The branch is kept at 761a904e39, so this PR can be reopened if an automated mover or concurrent moves make an operation-owned fence necessary.