oxedyne/fe2o3 — fe2o3

3.0 KiB, 20 runs

created by r1870400018:17507, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1	//! Version control whose unit of history is the operation, carrying signed
2	//! provenance.
3	//!
4	//! A conventional version control system records states and recovers intent by
5	//! comparing them: it stores what the tree looked like before and after, and a
6	//! diff is computed later, as a guess. Here the intent is the record. A whole
7	//! edit -- create this file, replace this run of bytes with these -- is one
8	//! operation, named, appended, and signed. What the author meant is preserved
9	//! rather than reconstructed, and who wrote it can be checked rather than
10	//! taken on trust.
11	//!
12	//! # Layout
13	//!
14	//! - [`id`] names operations: a replica identifier and that replica's counter,
15	//! with a compact varint encoding. Above it sit the names for content, which
16	//! are arithmetic over an operation identifier rather than minted.
17	//! - [`op`] is the operation vocabulary, an enum, together with the header that
18	//! names an operation and records the frontier it was written against.
19	//! Everything that speaks about bytes speaks about them by name.
20	//! - [`log`] is the append-only log, with a per-replica monotonic counter guard
21	//! and a causal one: an operation may not arrive before its parents.
22	//! - [`envelope`] binds a record's bytes to a public key and a signature.
23	//! - [`seq`] is the convergent sequence: it consumes the operation vocabulary
24	//! directly and renders a file's bytes from an operation set.
25	//! - [`segment`] is the durable form of a run of operations, read incrementally
26	//! and checked with a hasher the caller brings.
27	//! - [`fastexport`] parses git's fast-import stream, which is the one interface
28	//! git keeps for foreign consumers of a repository.
29	//! - [`gitexport`] emits it, so a history written here becomes a git repository
30	//! without this crate ever learning what a packfile is.
31	//! - [`diff`] recovers the edit between two versions of a file's bytes, for the
32	//! author who worked in a filesystem rather than in an editor and so has no
33	//! intent to record.
34	//! - [`sync`] brings two logs into agreement: a peer-symmetric state machine
35	//! over typed messages, which delivers causal closures and never subsets.
36	//!
37	//! # A pure primitive
38	//!
39	//! Nothing here does I/O, opens a socket, touches a filesystem or reads a
40	//! clock. Hashing, key material and transport belong to the caller, reached
41	//! through the interoperability traits in `oxedyne_fe2o3_iop_hash` and
42	//! `oxedyne_fe2o3_iop_crypto`, so the choice of algorithm is never made on the
43	//! caller's behalf. That discipline is also what keeps the crate portable: it
44	//! compiles for `wasm32-unknown-unknown` unchanged, so the same history logic
45	//! runs in a browser and on a server without a second implementation.
46	//!
47	//! [Written with AI entirely](https://need2know.ai/entirely-ai/code)\
48	//! Anthropic Claude
49
50	#![forbid(unsafe_code)]
51
52	pub mod diff;
53	pub mod envelope;
54	pub mod fastexport;
55	pub mod gitexport;
56	pub mod id;
57	pub mod log;
58	pub mod op;
59	pub mod segment;
60	pub mod seq;
61	pub mod sync;
62
63	#[cfg(test)]
64	mod test_support;