Skip to content

Commit e622b7f

Browse files
committed
mc-module: compartment coverage resolution (contiguity guard + folded/new split)
Two settled, handshake-independent pieces of the slice-4d-m0 spine, pure over the chronological compartment list. resolve_coverage validates the compartments tile the covered ordinal range with NO gap, then reports the coverage end (last compartment's end_message + end_message_id, the m0+m1 coverage anchor). A gap is FAIL-LOUD: a set covering 1-10 then 20-30 errors rather than silently taking last.end as coverage, which would drop messages 11-19 from the tail (covered by no compartment, neither summarized nor carried -- an unrecoverable loss). This is the Oracle's contiguity finding (ask #1), same fail-loud-at-the-boundary discipline as the reduction-conflict guard. An overlap fails too (the historian emits contiguous non-overlapping ranges, so either is corruption). partition_by_folded_seq splits the compartments into folded-into-m0 (sequence <= folded_seq) and riding-m1 (sequence > folded_seq, rendered at P1) -- the two-watermark m0/m1 divider. folded_seq 0 (bootstrap) makes everything new; folded_seq at the max folds all. These feed the branch rewrite (which is held on the input-contract handshake pin); they're isolated and tested now so the rewrite composes settled, verified parts. 84 tests green.
1 parent a947472 commit e622b7f

2 files changed

Lines changed: 185 additions & 0 deletions

File tree

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
//! Compartment coverage resolution: the contiguity-validated fold cut + the
2+
//! folded-vs-new partition for the m0/m1 split.
3+
//!
4+
//! Pure over a chronological compartment list (the order
5+
//! [`mc_store::McStore::load_compartments`] returns). Two settled, handshake-independent
6+
//! pieces of the slice-4d-m0 spine:
7+
//! - [`resolve_coverage`] validates the compartments TILE the covered ordinal range
8+
//! with no gap, then reports the coverage end (last compartment's end_message /
9+
//! end_message_id) — the m0+m1 coverage anchor. A gap is FAIL-LOUD: silently taking
10+
//! `last.end` as coverage would drop the gap's raw messages from the tail (they are
11+
//! neither summarized nor carried), an unrecoverable loss.
12+
//! - [`partition_by_folded_seq`] splits the compartments into the set already inside m0
13+
//! (`sequence <= folded_seq`) and the new ones riding m1 at P1 (`sequence > folded_seq`).
14+
15+
use mc_store::StoredCompartment;
16+
17+
/// The coverage summary of a contiguous compartment set: the latest sequence, the
18+
/// terminal covered ordinal, and the boundary message id (the cache anchor).
19+
#[derive(Debug, Clone, PartialEq, Eq)]
20+
pub struct CompartmentCoverage {
21+
/// The highest compartment `sequence` in the set.
22+
pub max_sequence: i64,
23+
/// The last compartment's `end_message` — the m0+m1 coverage end ordinal (the
24+
/// tail-trim point: items with a greater ordinal are the live tail).
25+
pub coverage_end_ordinal: u64,
26+
/// The last compartment's `end_message_id` — the cache/revert anchor.
27+
pub boundary_id: String,
28+
}
29+
30+
/// A non-contiguous compartment set: a gap between two consecutive compartments would
31+
/// drop raw messages from the tail if coverage advanced past it.
32+
#[derive(Debug, Clone, PartialEq, Eq)]
33+
pub struct CoverageGap {
34+
/// The earlier compartment's end ordinal.
35+
pub prev_end: i64,
36+
/// The later compartment's start ordinal (expected `prev_end + 1`).
37+
pub next_start: i64,
38+
}
39+
40+
impl std::fmt::Display for CoverageGap {
41+
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
42+
write!(
43+
f,
44+
"compartment coverage gap: a compartment ends at ordinal {} but the next starts at {} (expected {}); messages {}..{} are covered by no compartment",
45+
self.prev_end,
46+
self.next_start,
47+
self.prev_end + 1,
48+
self.prev_end + 1,
49+
self.next_start - 1
50+
)
51+
}
52+
}
53+
54+
/// Validate the compartments tile contiguously and report the coverage summary. None
55+
/// when the set is empty (nothing covered). Errors on the FIRST gap found.
56+
///
57+
/// Contiguity rule: for consecutive compartments (chronological), the later one must
58+
/// start exactly one ordinal past the earlier one's end (`next.start == prev.end + 1`).
59+
/// An overlap (`next.start <= prev.end`) or a gap (`next.start > prev.end + 1`) both fail
60+
/// — the historian emits contiguous non-overlapping ranges, so either is corruption.
61+
pub fn resolve_coverage(
62+
compartments: &[StoredCompartment],
63+
) -> Result<Option<CompartmentCoverage>, CoverageGap> {
64+
let Some(first) = compartments.first() else {
65+
return Ok(None);
66+
};
67+
let mut prev = first;
68+
for next in &compartments[1..] {
69+
if next.start_message != prev.end_message + 1 {
70+
return Err(CoverageGap {
71+
prev_end: prev.end_message,
72+
next_start: next.start_message,
73+
});
74+
}
75+
prev = next;
76+
}
77+
let last = compartments.last().expect("non-empty checked above");
78+
Ok(Some(CompartmentCoverage {
79+
max_sequence: compartments.iter().map(|c| c.sequence).max().unwrap_or(0),
80+
coverage_end_ordinal: last.end_message.max(0) as u64,
81+
boundary_id: last.end_message_id.clone(),
82+
}))
83+
}
84+
85+
/// Split the compartments into (folded-into-m0, riding-m1): `sequence <= folded_seq`
86+
/// are inside the frozen m0 baseline; `sequence > folded_seq` are the new compartments
87+
/// the m1 delta renders at P1 until the next HARD folds them. Preserves chronological
88+
/// order in each half.
89+
pub fn partition_by_folded_seq(
90+
compartments: &[StoredCompartment],
91+
folded_seq: i64,
92+
) -> (Vec<&StoredCompartment>, Vec<&StoredCompartment>) {
93+
compartments.iter().partition(|c| c.sequence <= folded_seq)
94+
}
95+
96+
#[cfg(test)]
97+
mod tests {
98+
use super::*;
99+
100+
fn comp(seq: i64, start: i64, end: i64, end_id: &str) -> StoredCompartment {
101+
StoredCompartment {
102+
sequence: seq,
103+
start_message: start,
104+
end_message: end,
105+
end_message_id: end_id.to_string(),
106+
title: format!("c{seq}"),
107+
content: "x".into(),
108+
p1: Some("x".into()),
109+
importance: 50,
110+
..Default::default()
111+
}
112+
}
113+
114+
#[test]
115+
fn empty_set_has_no_coverage() {
116+
assert_eq!(resolve_coverage(&[]), Ok(None));
117+
}
118+
119+
#[test]
120+
fn contiguous_set_reports_last_as_coverage() {
121+
let comps = vec![
122+
comp(1, 1, 10, "m10"),
123+
comp(2, 11, 20, "m20"),
124+
comp(3, 21, 30, "m30"),
125+
];
126+
let cov = resolve_coverage(&comps).unwrap().unwrap();
127+
assert_eq!(cov.max_sequence, 3);
128+
assert_eq!(cov.coverage_end_ordinal, 30);
129+
assert_eq!(cov.boundary_id, "m30");
130+
}
131+
132+
#[test]
133+
fn single_compartment_is_its_own_coverage() {
134+
let cov = resolve_coverage(&[comp(1, 1, 9, "m9")]).unwrap().unwrap();
135+
assert_eq!(cov.max_sequence, 1);
136+
assert_eq!(cov.coverage_end_ordinal, 9);
137+
assert_eq!(cov.boundary_id, "m9");
138+
}
139+
140+
#[test]
141+
fn a_gap_fails_loud() {
142+
// covers 1-10 then 20-30 → messages 11-19 covered by nothing → must error
143+
let comps = vec![comp(1, 1, 10, "m10"), comp(2, 20, 30, "m30")];
144+
let err = resolve_coverage(&comps).unwrap_err();
145+
assert_eq!(err.prev_end, 10);
146+
assert_eq!(err.next_start, 20);
147+
assert!(err.to_string().contains("messages 11..19"), "{err}");
148+
}
149+
150+
#[test]
151+
fn an_overlap_fails_loud() {
152+
// next starts at 8 but prev ended at 10 → overlap → not contiguous tiling
153+
let comps = vec![comp(1, 1, 10, "m10"), comp(2, 8, 15, "m15")];
154+
assert!(resolve_coverage(&comps).is_err());
155+
}
156+
157+
#[test]
158+
fn partition_splits_at_folded_seq() {
159+
let comps = vec![
160+
comp(1, 1, 10, "m10"),
161+
comp(2, 11, 20, "m20"),
162+
comp(3, 21, 30, "m30"),
163+
];
164+
let (folded, new) = partition_by_folded_seq(&comps, 1);
165+
assert_eq!(
166+
folded.iter().map(|c| c.sequence).collect::<Vec<_>>(),
167+
vec![1]
168+
);
169+
assert_eq!(
170+
new.iter().map(|c| c.sequence).collect::<Vec<_>>(),
171+
vec![2, 3]
172+
);
173+
174+
// folded_seq 0 (bootstrap) → everything is new (rides m1 until first fold)
175+
let (folded0, new0) = partition_by_folded_seq(&comps, 0);
176+
assert!(folded0.is_empty());
177+
assert_eq!(new0.len(), 3);
178+
179+
// folded_seq at/past the max → nothing new (all folded)
180+
let (folded_all, new_all) = partition_by_folded_seq(&comps, 3);
181+
assert_eq!(folded_all.len(), 3);
182+
assert!(new_all.is_empty());
183+
}
184+
}

‎crates/mc-module/src/lib.rs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@
1616
1717
#![forbid(unsafe_code)]
1818

19+
pub mod compartment_coverage;
1920
pub mod decay_render;
2021
pub mod memory_render;
2122
pub mod project_docs;

0 commit comments

Comments
 (0)