Skip to main content

kizz_store/
lib.rs

1// Copyright (c) 2026 Sakura Industries LLC.
2//
3// SPDX-License-Identifier: AGPL-3.0-only
4
5//! The kizz cache: its location, its lock file, and the store of typed records.
6//!
7//! * [`location`]: the cache is `KIZZ_CACHE_DIR` when set, otherwise
8//!   `$XDG_CACHE_HOME/kizz`, otherwise `~/.cache/kizz`.
9//! * [`lock`]: one process at a time holds `kizz.lock` in the cache directory, and any
10//!   other waits and says what it is waiting for.
11//! * [`store`]: the records live in `SurrealKV`, embedded, in the `db` directory of the
12//!   cache, as CBOR encoded with `minicbor`; the store starts no thread of its own.
13//! * [`identity`]: the stamp of the machine and user that the cache belongs to, which the
14//!   store writes into a new database and compares on every later open.
15//! * [`records`]: the record families, their key layout, and their typed records.
16//! * [`step`]: the contents of step records: the step specification, the observations
17//!   with their path states, and how the step ended.
18//! * [`machine`]: the machine state that each step record keeps, and how the parts that a
19//!   step names are compared and shown.
20//! * [`explanation`]: the contents of explanations: why a step ran, or that it was
21//!   cached, as the step-position records keep them for `kizz why`.
22
23pub mod explanation;
24pub mod identity;
25pub mod location;
26pub mod lock;
27pub mod machine;
28pub mod records;
29pub mod step;
30pub mod store;
31
32pub use explanation::{
33    BuildId, ChangedInput, EnvChange, Explanation, ModuleChange, ModuleChangeKind, Reason,
34    SelfInflicted, TaskLabel, Verdict, Writer,
35};
36pub use identity::{
37    CacheIdentity, IdentityDifference, IdentityKey, IdentityPart, identity_differences_text,
38};
39pub use location::{LocationError, cache_dir, cache_dir_from_env};
40pub use lock::{CacheLock, LOCK_FILE_NAME, LockDetails, LockError, LockOptions};
41pub use machine::{
42    DiskRecord, FileSystemRecord, KernelRecord, LimitRecord, MachineChange, MachinePart,
43    MachineStateRecord, MemoryRecord, machine_changes, machine_changes_text,
44};
45pub use records::{
46    Family, LastWriter, LearnedOrder, ModuleHash, PathKey, PositionKey, Record, RecordKey,
47    SchemaKey, SchemaVersion, StepKey, StepPosition, TaskId, TaskRecord, WrittenBy, database_key,
48    path_prefix,
49};
50pub use step::{
51    AccessBits, Attribute, Attributes, Capture, Change, ChangedRead, Connection, ContentHash,
52    Difference, DirEntry, EntryKind, FileMeta, Listing, MAX_LISTED_NAMES, NotCachedReason,
53    Observation, Owner, PERMISSION_BITS, PathState, ProgramPath, RecordedOutput, RunReason,
54    SpecialKind, StepExit, StepRecord, StepSpecRecord, Times, changed_reads_text, connections_text,
55    permission_bits, system_call_numbers,
56};
57pub use store::{
58    DATABASE_DIR, EntryCounts, Inventory, SCHEMA_VERSION, STALL_THRESHOLD, Store, StoreError, Txn,
59};