qualia_core_db/storage_driver/ranges/mod.rs
1//! Canonical native range staging (QBS11 phase B), not verified durability.
2//!
3//! Contract written before implementation:
4//! - MmapDriver::create_range_staging consumes a private non-Copy StagingCharge
5//! from the EXISTING CustodyQuota. No copied caps/new quota/root registry.
6//! - The token charges the complete explicit u64 allowance before any staging
7//! filesystem mutation. Its root is borrowed; it does not retain a mutable
8//! quota borrow, so several admitted attempts can coexist. Zero attempt IDs
9//! and allowances refuse; every charge survives failure, close, drop/unwind.
10//! - RangeLimits contains separate u64 payload/proof/checkpoint ceilings.
11//! Checked positive sum must fit the charge; individual zero ceilings are
12//! allowed. File lengths grow only through bounded writes, not preallocation.
13//! - Only exact constant data filenames payload/proof/checkpoint are used inside one
14//! private TempDir created under the same canonical existing MmapDriver root.
15//! A create-only 64-byte .owner control marker binds magic/version, zero
16//! reserved bytes and the exact admitted 32-byte attempt ID. Marker/filesystem
17//! control overhead is host-covered, outside the three data-byte ceilings,
18//! matching existing quota semantics for head/lock/filesystem overhead.
19//! create_new, Unix0600 (directory0700), Windows share_mode(0), and retained
20//! File::try_lock are used. Linux locks are explicitly cooperative only.
21//! - read_exact_at/write_exact_at use caller slices, checked u64 offset+length,
22//! and actual File seek/read_exact/write_all. No whole-value read or mmap.
23//! Sparse/zero reads are bytes only and never imply verified availability.
24//! - sync_file observes actual File::sync_all return. No method returns a
25//! DurableVerifiedRange, atomic publication, serving permission or financial
26//! receipt. Windows directory power-loss durability remains unqualified.
27//! - Success close drops all file handles before TempDir::close. Cleanup errors
28//! return a private cleanup-pending owner retaining path/root/charge for retry.
29//! Explicit recursive retry first verifies the absolute owned child remains
30//! within the resolved canonical parent, rejects links/reparse points, and
31//! verifies the exact bounded ownership marker before recursive deletion.
32//! Native partial cleanup may remove the marker first. ONLY after a cleanup
33//! started from verified ownership then failed, scoped recovery rechecks the
34//! canonical child and restores the internally derived marker with create_new
35//! if absent. Any existing marker must validate exactly and is never overwritten.
36//! Initial missing/malformed marker refusal never enables restoration.
37//! A missing/malformed/replaced marker retains pending ownership and disarms
38//! TempDir automatic cleanup. This is host-protected namespace ownership,
39//! not marker authentication against an actor allowed to replace that root.
40//! Drop/unwind closes handles then uses the same child/marker guard. Because
41//! Drop cannot return pending ownership, any refused/failed cleanup leaves
42//! charged uncertain artifacts; explicit close preserves retry diagnostics.
43//! A creation failure before a valid marker exists also retains pending
44//! ownership rather than bypassing marker validation. Host protected-root
45//! namespace stability is required between validation and cleanup. Quota is
46//! never refunded. No directory scan or arbitrary-path cleanup API exists.
47//! - Host owns protected root ACL/ancestor/locality, authenticated usage freshness,
48//! aggregate quota lease, resource-stage/policy/deadline checks and worker drain.
49//! Root/backend mutation errors can leave uncertain bytes, never durable success.
50
51pub mod recovery;
52mod session;
53mod types;
54pub use session::RangeSession;
55pub use types::*;
56
57#[cfg(test)]
58mod tests;