pointlock_store/lib.rs
1//! # pointlock-store
2//!
3//! RunLog + Checkpoint persistence (SQLite WAL via rusqlite,
4//! `synchronous=FULL`) and the content-addressed evidence area.
5//!
6//! Authoritative design documents:
7//! - `docs/design/07-subflow-checkpoint-resume-repair.md` §3 (checkpoint
8//! model, DDL, the four materialization moments, the actionIntent WAL
9//! transaction discipline, file-before-row-before-log, the
10//! rebuild-checkpoint self-check)
11//! - `docs/design/00-architecture-spine.md` §6.1 (RunLog) / §6.6
12//! (CheckpointView)
13//!
14//! ## Shape of the API
15//!
16//! - [`Store`] — the single-writer handle: [`Store::open`],
17//! [`Store::begin_run`], [`Store::append_event`] (seq allocation, insert,
18//! and checkpoint materialization in one transaction),
19//! [`Store::write_action_intent`] (the WAL entry whose committed return
20//! gates provider dispatch), [`Store::submit_human_response`] (the
21//! single-writer arbitration of human responses — first response wins,
22//! deadline judged by the store-receipt clock, shape-validated per
23//! purpose/mode; 06 §4.3), [`Store::put_evidence`] /
24//! [`Store::link_evidence`], and the read side ([`Store::events`],
25//! [`Store::run_meta`], [`Store::run_status`],
26//! [`Store::materialized_checkpoint`]).
27//! - [`WriterLease`] — the advisory per-run writer lease (07 §3.3 rule
28//! 5): a non-blocking exclusive `flock` every writing segment takes
29//! before its first append; a held lease IS writer liveness, a free
30//! lease under a `running` status IS a crash residue.
31//! - [`fold_checkpoint`] — the deterministic pure fold
32//! `(RunMeta, events) → CheckpointView + RunStatus`, exposed separately
33//! so it is directly testable; [`Store::rebuild_checkpoint`] and
34//! [`Store::verify_checkpoint`] (materialized == rebuilt, I1's runtime
35//! self-check) are thin wrappers over it.
36//!
37//! Append-only is structural: no API updates or deletes `run_log` rows
38//! (07 §3.3 rule 4 — re-judgement appends a new `verdictRecorded` carrying
39//! `supersedes`; old events never move).
40//!
41//! The projection read side (R14, spine §10.2) homes in [`projection`]:
42//! the five renderer-agnostic DTO families + their query layer — the only
43//! contract any renderer (or `pointlock locate`) consumes.
44
45pub mod error;
46pub mod fold;
47pub mod lease;
48pub mod projection;
49pub mod store;
50
51pub use error::{FoldError, HumanResponseRejection, StoreError};
52pub use fold::{FoldedRun, RunMeta, RunStatus, fold_checkpoint};
53pub use lease::WriterLease;
54pub use store::{EvidenceMeta, EvidencePut, IntentDispatch, NewRun, RunListEntry, Store};