alkblobs 0.2.2

Content-addressed blob storage: multi-hash put/get/verify store with pluggable backends, transport- and protocol-agnostic
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160

//! The invariant backlog — store-api.md §Invariants' seven entries
//! registered as the rows-to-grow table (README §The invariant
//! backlog is the normative statement; this module is its in-code
//! registry, which waves 2-6 grow rows against).
//!
//! Each entry traces to the store-api.md invariant numbering (INV-1
//! through INV-7 mirror §Invariants 1-7) and carries the pinning text
//! the row stamps will cite. A suite row that does not trace to an
//! entry here is not a conformance row; a new property needs a backlog
//! entry and its stamp first.
//!
//! The column plan: mem is the contract-reference engine (ADR-011 §2)
//! — wave 2 lands its column first, every other engine's rows mirror
//! it, and additions to mem's column propagate to all others (INV-7).

#![allow(dead_code)]

/// One backlog entry: an invariant of store-api.md §Invariants, its
/// planned row family, the pinning texts its row stamps cite, and the
/// first column to land it.
pub struct Invariant {
    /// `INV-<n>` — mirrors the n-th item of store-api.md §Invariants.
    pub id: &'static str,
    /// One-line restatement of the invariant as specced.
    pub invariant: &'static str,
    /// The planned row family — what wave-grown rows assert (README
    /// table's "Row family" column).
    pub row_family: &'static str,
    /// The pinning texts the rows' stamps cite (spec §/ADR §; the
    /// README table's "Pinning text" column, split by citation).
    pub pins: &'static [&'static str],
    /// The first column and wave to land the family (README table's
    /// last column).
    pub first_column: &'static str,
}

/// The backlog, in store-api.md §Invariants order.
pub const BACKLOG: [Invariant; 7] = [
    Invariant {
        id: "INV-1",
        invariant: "whole-blob put/get round-trips byte-identical under the canonical \
                    derivation — both tiers, both put paths, every shipped engine",
        row_family: "one round-trip family over the content matrix (put paths and tiers \
                     loop in-body; the git-interop test remains the derivation's source \
                     of truth)",
        pins: &[
            "store-api.md §Invariants 1",
            "ADR-002 (canonical derivation)",
            "ADR-003 (both put paths, dispatch)",
            "ADR-007/008/009/011 (the shipped engines)",
            "ADR-018 (the git-object family's preimage-identity put seam)",
        ],
        first_column: "wave 2 — mem (kv tier), then local (large tier)",
    },
    Invariant {
        id: "INV-2",
        invariant: "dedup: putting identical content twice (same or different path) is \
                    one pool entry",
        row_family: "one dedup row, same-path and different-path legs",
        pins: &[
            "store-api.md §Invariants 2",
            "ADR-003 (whole-value put is CAS first-writer-wins)",
            "ADR-005 (re-put refcounts the existing entry)",
            "ADR-018 (the family's dedup-by-oid)",
        ],
        first_column: "wave 2 — mem",
    },
    Invariant {
        id: "INV-3",
        invariant: "stage hygiene: any failure mid-put leaves zero stage files; any \
                    success leaves exactly one committed entry",
        row_family: "one exact-count hygiene family over both put paths and both failure \
                    modes (explicit discard, failed commit)",
        pins: &[
            "store-api.md §Invariants 3",
            "ADR-010 §1 (the staged-put contract: commit publishes, every failure path \
             discards)",
            "ADR-003 (stage-then-commit-rename)",
        ],
        first_column: "wave 2 — mem (degenerate kv stage) and local (the stage form)",
    },
    Invariant {
        id: "INV-4",
        invariant: "sweep safety: with correct liveness registered sweep counts are \
                    exact; with aborting sources sweep deletes nothing",
        row_family: "one single-node exact-count family (happy + abort shapes); the fleet \
                    form is its own engine-gated row family running under \
                    `--all-features`",
        pins: &[
            "store-api.md §Invariants 4",
            "ADR-005 (delete windows, abort-as-data)",
            "ADR-008 (the engine-gated fleet form)",
            "ADR-012 §1/§4/§6.7 (sweep shape, GC-state host, executor-of-window ruling)",
            "ADR-013 §2 (the sweep lease's semantics)",
        ],
        first_column: "wave 2 — mem (in-process protocol); the fleet form first runs in \
                       wave 6",
    },
    Invariant {
        id: "INV-5",
        invariant: "`list()` correctness is observable only through GC",
        row_family: "list-correctness rows assert through sweep outcomes (exact counts), \
                     never by comparing enumerated lists directly",
        pins: &[
            "store-api.md §Invariants 5",
            "ADR-003 (`list()` complete and well-formed by contract)",
            "ADR-005 (GC's live-set diff rides `list()`)",
        ],
        first_column: "wave 2 — mem",
    },
    Invariant {
        id: "INV-6",
        invariant: "`stat`/`size` on any engine returns the entry length without fetching \
                    content",
        row_family: "one stat-discipline family per engine column",
        pins: &[
            "store-api.md §Invariants 6",
            "ADR-008 (the trait `size` probe discipline)",
            "ADR-009 (pg-lo's companion-row probe)",
            "ADR-018 §Decision 3 (the family entries' stored-preimage stat semantic)",
        ],
        first_column: "wave 2 — mem",
    },
    Invariant {
        id: "INV-7",
        invariant: "engine-conformance uniformity: every engine's bodies pass the same \
                    contract suite mem (the reference engine) passes",
        row_family: "the meta-gate — a column's green run against mem's rows is the \
                     assertion; no separate uniformity test exists",
        pins: &[
            "store-api.md §Invariants 7",
            "ADR-010 §1 (one trait, every engine, same suite)",
            "ADR-011 §2 (mem's contract-reference role)",
        ],
        first_column: "wave 2 — mem (its column defines the required set)",
    },
];

/// The backlog's traceability gate: entries mirror store-api.md
/// §Invariants' numbering in order, and every entry's fields are
/// populated. The harness's tests call this; a violation is a
/// registry-editing mistake, not a runtime event.
pub fn assert_traceable() {
    for (position, entry) in BACKLOG.iter().enumerate() {
        assert_eq!(
            entry.id,
            format!("INV-{}", position + 1),
            "backlog order mirrors store-api.md §Invariants"
        );
        assert!(!entry.invariant.is_empty());
        assert!(!entry.row_family.is_empty());
        assert!(!entry.pins.is_empty(), "{} must pin its behavior", entry.id);
        assert!(!entry.first_column.is_empty());
    }
}

/// Look a backlog entry up by its `INV-n` id.
pub fn invariant_by_id(id: &str) -> Option<&'static Invariant> {
    BACKLOG.iter().find(|entry| entry.id == id)
}