blockworx/doc_ng/

mod.rs

//! The commit log: the document's only authoritative representation.
//!
//! A document is an append-only history of typed ops. Everything else —
//! the editor's document state, routed geometry, spatial indexes — is
//! derived from it and can be thrown away and rebuilt. That inversion is
//! what makes several people editing at once tractable: histories
//! compose, whereas two documents can only overwrite each other.
//!
//! The layering is strictly one-way:
//!
//! ```text
//! commit log  ──fold──▶  document  ──solve──▶  derived  ──▶  caches
//! ```
//!
//! Order comes from a **process, not a protocol**: one server accepts
//! commits and assigns each the next [`Rev`](rev::Rev), so the total order
//! on writes is arrival order and no client participates in establishing
//! it. That is the whole of the concurrency design, and it is why there
//! are no clocks, no actor ids, no content-addressed history, and no
//! merge/repair pass here.
//!
//! Five rules keep it honest, and every one of them is load-bearing:
//!
//! 1. **All state is last-write-wins registers, creates, and tombstones.**
//!    The merge is `max` over [`WriteOrder`](write_order::WriteOrder) —
//!    associative, commutative, idempotent — which is what lets a client
//!    re-fold its unacknowledged commits above a moving confirmed head and
//!    reach the answer the server will. An op that does not reduce to
//!    those three breaks it.
//! 2. **The fold is pure, and it is the only writer.**
//!    [`try_apply`](document::Document::try_apply) folds into a *new*
//!    document, so a refused commit cannot leave a partial write behind
//!    and consumes no rev. No I/O, no clock, no randomness, and no
//!    re-running of the logic that produced an op — ids are minted before
//!    an op is recorded, never during replay.
//! 3. **Nothing derived is ever stored in the log.** Solver output cannot
//!    be merged, so it must be recomputable instead.
//! 4. **Unknown encodings are refused, never skipped.** Half-loading a log
//!    written by a newer build forks the document silently. The decode
//!    boundary is also a trust boundary in production — the server
//!    deserializes payloads from arbitrary clients — so values arriving
//!    through it are range-checked and refused, never clamped.
//! 5. **Global invariants are ingress preconditions, not repairs.** One
//!    apply point means a cycle or a dangling reference can be refused
//!    before it is sequenced, rather than voided after the fact.
//!
//! A prediction is a different type from the authority's copy
//! ([`Provisional`](rev::Provisional) against
//! [`Confirmed`](rev::Confirmed)), because a prediction's rev is scratch
//! that every rebuild re-mints, and reporting or storing one as a log
//! position would be a lie the compiler can prevent.
//!
//! Per-kind structure is generated, not transcribed: one field list per
//! entity in [`block_model`] expands through the `entity!` macro to the
//! struct, its total init, its update vocabulary, and the
//! [`Entity`](entity::Entity) impl — so a register cannot exist without a
//! way to write it, and neither can drift from the other.
//!
//! See `docs/collab-architecture.md` for the design,
//! `docs/doc-ng-design-notes.md` for why each piece is shaped as it is,
//! and `docs/collab-migration-playbook.md` for how the editor is being
//! moved onto it.

pub mod block_model;
pub mod commit;
pub mod document;
pub mod encode;
pub mod entity;
#[cfg(test)]
pub mod fixtures;
pub mod geometry;
pub mod hash;
pub mod id;
pub mod opcode;
pub mod reconcile;
pub mod register;
pub mod rev;
pub mod session;
pub mod values;
pub mod write_order;