vole_document/
lib.rs

1//! # VOLE-Document
2//!
3//! A persistent procedural document runtime with byte-exact reconstruction.
4//!
5//! The governing invariants of the exact profile are:
6//!
7//! ```text
8//! materialize(descriptor)  == original_bytes
9//! materialize(field_root)  == original_bytes
10//! ```
11//!
12//! Parsing, semantic equivalence, canonicalization, or a successful round trip
13//! through a document writer are **not** substitutes for this invariant.
14//!
15//! ## Layered representation
16//!
17//! ```text
18//! source bytes X
19//!     -> deterministic format analysis (advisory; never destructive)
20//!     -> bounded reconstruction hypothesis
21//!     -> Document Reconstruction Algebra program + parameters + typed residuals
22//!     -> typed entropy channels / rANS entropy-seed capsules
23//!     -> canonical .voldoc descriptor
24//!     -> bounded deterministic materializer
25//!     -> X exactly
26//! ```
27//!
28//! rANS is the *entropy substrate beneath* the representation. It is not the
29//! procedural model, and an integer state is not a magic seed: a complete
30//! decoder-entry capsule carries model, state, renormalization payload, counts,
31//! and integrity.
32//!
33//! ## Persistent procedural field (Phase 11)
34//!
35//! From Phase 11 the persisted document is also a **queryable procedural field**
36//! (feature `field`, on by default; see the `field` module): a content-addressed,
37//! immutable procedural **seed DAG**, a bounded hierarchical observation index,
38//! a typed observation API with provenance and `EXPLAIN`/`EXPLAIN ANALYZE`, and
39//! selective late materialization. A narrow observation resolves its minimum
40//! dependency closure (and, when warm, never opens the descriptor); the exact
41//! original bytes always rematerialize, including after the source is deleted and
42//! across process restarts. The exactness path (`materialize`) never depends on
43//! the field, a cache, an index, or any search process.
44//!
45//! See `PROJECT_STATE.md` for the mechanism ledger, `FINDINGS.md` for the
46//! authoritative measured results, `docs/adr/` for the decisions, and `SPEC.md`
47//! for the wire format.
48
49#![forbid(unsafe_code)]
50
51pub mod accounting;
52pub mod adapter;
53pub mod codec;
54pub mod container;
55pub mod dra;
56pub mod encode;
57pub mod entropy;
58pub mod error;
59#[cfg(feature = "field")]
60pub mod field;
61pub mod integrity;
62pub mod limits;
63pub mod materialize;
64pub mod store;
65
66pub use error::{Error, ErrorClass, Result};
67pub use limits::Limits;
68
69/// The exactness profile mandated for the archival path.
70///
71/// Only `EXACT_BYTES` is normative. Canonical and semantic profiles are
72/// deliberately absent until they can be named and measured separately.
73pub const EXACTNESS_PROFILE_EXACT_BYTES: u8 = 0;
74
75/// Identifier for the opaque source-format class.
76pub const SOURCE_FORMAT_OPAQUE: u8 = 0;
77
78/// Identifier for the PDF source-format class.
79///
80/// A descriptor declaring this class is still bound by the exact profile: its
81/// program must reconstruct the original PDF bytes exactly. The class records
82/// only how the source was analyzed, never a license to alter it.
83pub const SOURCE_FORMAT_PDF: u8 = 1;
vole_document/lib.rs

vole_document/
lib.rs
