Skip to main content

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;