macrame/integrity/
mod.rs

1pub(crate) mod audit;
2pub(crate) mod rebuild;
3pub(crate) mod shadow;
4
5pub use audit::audit_current;
6pub use rebuild::{rebuild_current, RebuildReport};
7pub use shadow::{ShadowOutcome, ShadowStep};
8
9/// The latest-belief projection of `links` — **the single definition** (T0.2).
10///
11/// [Doctrine VI](../../docs/architecture/s0-s3-foundations.md) says
12/// `links_current` must equal this at all times: one row per interval key
13/// `(source_id, target_id, edge_type, valid_from)`, the one with the greatest
14/// `recorded_at`. `rebuild_current` makes it so and `audit_current` checks it.
15///
16/// It lived in both files, byte-for-byte, until 0.6.0. That is the failure class
17/// [D-035](../../docs/architecture/s13-decision-register.md#d-035) exists to
18/// prevent — a rule stated twice is a rule that can disagree with itself — and
19/// it had a second consequence nobody had named: the audit that `rebuild_within`
20/// ran on itself was, in effect, a runtime check that the two copies still
21/// agreed, paid on every archive, under the archive's write lock, forever. With
22/// one definition that check is tautological by construction rather than by
23/// assumption, which is what made it safe to stop paying for it (D-077).
24///
25/// `rn` is not projected: callers select the eight ledger columns.
26///
27/// # It is a generator, and the restriction goes *inside* (0.15.3, D-245)
28///
29/// Three callers want the projection of a *part* of `links` — the shadow
30/// rebuild's chunk, its catch-up pass, and the archive's keyed repair — and
31/// all three want the restriction inside the subquery. Outside it the window
32/// still ranks every partition in the table and the restricted query costs
33/// what the whole rebuild costs: correct, and pointless, which is the kind of
34/// thing only a benchmark finds. `projection_where` is therefore the one
35/// definition and [`latest_belief_projection`] is its unrestricted case;
36/// `shadow.rs` carried its own copy of this shape until 0.15.3, which is
37/// [D-035](../../docs/architecture/s13-decision-register.md#d-035)'s failure
38/// class sitting in the file whose header explains that failure class.
39pub(crate) fn projection_where(clause: &str) -> String {
40    format!(
41        r#"
42    SELECT source_id, target_id, edge_type, valid_from,
43           valid_to, weight, properties, recorded_at, branch_id
44    FROM (
45        SELECT source_id, target_id, edge_type, valid_from,
46               valid_to, weight, properties, recorded_at, branch_id,
47               ROW_NUMBER() OVER (
48                   PARTITION BY source_id, target_id, edge_type, valid_from, branch_id
49                   ORDER BY recorded_at DESC
50               ) AS rn
51        FROM links
52        WHERE {clause}
53    ) WHERE rn = 1
54"#
55    )
56}
57
58/// The projection of the whole table: [`projection_where`] with a clause that
59/// admits every row.
60///
61/// `1 = 1` rather than an `Option<&str>` arm that omits the `WHERE`, because a
62/// generator with two shapes is two things to keep true and SQLite discards a
63/// constant-true term before it plans anything. `audit_current` and
64/// `rebuild_within` are its callers, and both compare or insert whole tables.
65pub(crate) fn latest_belief_projection() -> String {
66    projection_where("1 = 1")
67}
macrame/integrity/mod.rs

macrame/integrity/
mod.rs
