feat(event): refuse subevents that escape the parent interval

ARCHITECTURE.md

@@ -61,6 +61,7 @@ boundaries above remain the target modular MSA architecture.
 | `tepp_simulation` | known-truth temporal/event data generation |
 | `validation_core` | RMSE, bias, coverage, graph, and Monte Carlo metrics |
 | `tepp_api` | versioned DTO, schema, and export contracts |
+| `subevent_containment` | subevent event-time intervals must stay inside the parent |
 | `prediction_contradiction` | Allen promotion gate: `before`/`after` stay contradictory; `meets`/`met_by` stay unsupported; coverage is required before unmatched predicted mass may be authorized for promotion |
 | `provider_receipt` | provider-disclosure field-code receipts; source text and identity are not disclosable |
 | `operational_log` | operational logs; `try_record` is the only recording API; source text and source identity are not loggable; `persistence_postgres` `audit_event` inserts call the same gate |

CHANGELOG.md

@@ -6,6 +6,7 @@ All notable changes to TEPP are documented here. The format follows Keep a Chang
 
 ### Added
 
+- `subevent_containment` parent-window gate: a half-open subevent interval that starts before or ends after its parent cannot attach; recovered containment flags match known truth at a higher computed rate than accepting every child (ADR 0003).
 - `prediction_contradiction` promotion gate: `temporal_core` Allen classification refuses `before`/`after` as contradiction and `meets`/`met_by` as unsupported adjacency; `refuse_promotion` and `require_observed_coverage` refuse partial overlap that leaves unmatched predicted mass; `refuse_contradiction_or_adjacency` is the weaker contradiction/adjacency filter only; evidence available after the knowledge cutoff is ineligible. Label agreement is not RMSE recovery (ADR 0002, ADR 0016). Canonical docs name the crate, not a pull-request number, as the landable authority; `scripts/validate_documentation.py` fail-closes on `landable coverage gate is PR #N` and inverted or paraphrased forms (`PR #N is the landable coverage gate`, `the landable gate is PR #N`, `coverage-authority landing PR #N`, `merge PR #N as the coverage-authority`) including drafts #93, #94, #97, #101, #102, #104, #108, #109, #111, and #112. The hourly queue lock also fail-closes when those drafts are omitted from Keep-unmerged sentences, when a Keep-unmerged sentence is negated, or when the naruon live-HTTP *subject* is not PR #107 with #87 and #105 kept unmerged.
 - `provider_receipt` disclosure audit: a receipt records purpose and field codes sent to a model provider; source text, source identity, and blanket PII masking fail closed; recovered field codes match known truth at a higher computed rate than a collapsed set (ADR 0009).
 - `tepp_api` corpus-split leakage-audit manifest v1: cutoff exclusion counts, relation-component and partition digests, governed link-kind vocabulary, and a canonical `SHA-256` that binds to `corpus_split_manifest` without exporting source text.

Cargo.toml

@@ -11,6 +11,7 @@ members = [
     "crates/tepp_simulation",
     "crates/validation_core",
     "crates/tepp_api",
+    "crates/subevent_containment",
     "crates/prediction_contradiction",
     "crates/provider_receipt",
     "crates/operational_log",
@@ -34,6 +35,7 @@ default-members = [
     "crates/tepp_simulation",
     "crates/validation_core",
     "crates/tepp_api",
+    "crates/subevent_containment",
     "crates/prediction_contradiction",
     "crates/provider_receipt",
     "crates/operational_log",

README.md

@@ -38,6 +38,7 @@ crates/corpus_split
 crates/tepp_simulation
 crates/validation_core
 crates/tepp_api
+crates/subevent_containment
 crates/prediction_contradiction
 crates/provider_receipt
 crates/operational_log

crates/subevent_containment/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "subevent_containment"
+description = "Subevent intervals must stay inside the parent event interval."
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+homepage.workspace = true
+readme.workspace = true
+keywords.workspace = true
+categories.workspace = true
+publish = false
+
+[lints]
+workspace = true

crates/subevent_containment/src/error.rs

@@ -0,0 +1,46 @@
+//! Fail-closed subevent-containment errors.
+
+use std::fmt;
+
+/// A fail-closed subevent-containment error.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[non_exhaustive]
+pub enum SubeventContainmentError {
+    /// The subevent interval is not inside the parent interval.
+    SubeventEscapesParent,
+    /// An interval or recovery slice was empty, inverted, or length-mismatched.
+    InvalidIntervalPayload,
+}
+
+impl fmt::Display for SubeventContainmentError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let message = match self {
+            Self::SubeventEscapesParent => "subevent interval escapes the parent event",
+            Self::InvalidIntervalPayload => "invalid subevent-containment payload",
+        };
+        formatter.write_str(message)
+    }
+}
+
+impl std::error::Error for SubeventContainmentError {}
+
+#[cfg(test)]
+mod tests {
+    use super::SubeventContainmentError;
+
+    #[test]
+    fn error_messages_are_stable() {
+        for (error, message) in [
+            (
+                SubeventContainmentError::SubeventEscapesParent,
+                "subevent interval escapes the parent event",
+            ),
+            (
+                SubeventContainmentError::InvalidIntervalPayload,
+                "invalid subevent-containment payload",
+            ),
+        ] {
+            assert_eq!(error.to_string(), message);
+        }
+    }
+}

crates/subevent_containment/src/interval.rs

@@ -0,0 +1,133 @@
+//! Half-open event-time intervals and parent containment.
+
+use crate::SubeventContainmentError;
+
+/// One half-open event-time interval `[start, end)` in seconds.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct EventInterval {
+    start_seconds: i64,
+    end_seconds: i64,
+}
+
+impl EventInterval {
+    /// Construct a half-open interval with a strictly positive length.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`SubeventContainmentError::InvalidIntervalPayload`] when
+    /// `end_seconds` is not greater than `start_seconds`.
+    pub const fn new(
+        start_seconds: i64,
+        end_seconds: i64,
+    ) -> Result<Self, SubeventContainmentError> {
+        if end_seconds <= start_seconds {
+            return Err(SubeventContainmentError::InvalidIntervalPayload);
+        }
+        Ok(Self {
+            start_seconds,
+            end_seconds,
+        })
+    }
+
+    /// Inclusive start bound in seconds.
+    #[must_use]
+    pub const fn start_seconds(self) -> i64 {
+        self.start_seconds
+    }
+
+    /// Exclusive end bound in seconds.
+    #[must_use]
+    pub const fn end_seconds(self) -> i64 {
+        self.end_seconds
+    }
+}
+
+/// Return whether `child` lies entirely inside `parent`.
+///
+/// # Errors
+///
+/// This function is infallible for validated intervals and exists to keep the
+/// public comparison surface explicit.
+#[allow(clippy::unnecessary_wraps)]
+pub fn interval_contains(
+    parent: EventInterval,
+    child: EventInterval,
+) -> Result<bool, SubeventContainmentError> {
+    Ok(child.start_seconds >= parent.start_seconds && child.end_seconds <= parent.end_seconds)
+}
+
+/// Refuse to attach a subevent that escapes the parent interval.
+///
+/// # Errors
+///
+/// Returns [`SubeventContainmentError::SubeventEscapesParent`] when the child
+/// is not contained.
+pub fn refuse_escaped_subevent(
+    parent: EventInterval,
+    child: EventInterval,
+) -> Result<(), SubeventContainmentError> {
+    if interval_contains(parent, child)? {
+        return Ok(());
+    }
+    Err(SubeventContainmentError::SubeventEscapesParent)
+}
+
+/// Fraction of recovered containment flags that match known truth.
+///
+/// # Errors
+///
+/// Returns [`SubeventContainmentError::InvalidIntervalPayload`] when either
+/// slice is empty or the lengths differ.
+pub fn containment_recovery_rate(
+    truth: &[bool],
+    decided: &[bool],
+) -> Result<f64, SubeventContainmentError> {
+    if truth.is_empty() || truth.len() != decided.len() {
+        return Err(SubeventContainmentError::InvalidIntervalPayload);
+    }
+    let mut matches = 0_u32;
+    for (truth_flag, decided_flag) in truth.iter().zip(decided) {
+        if truth_flag == decided_flag {
+            matches += 1;
+        }
+    }
+    Ok(f64::from(matches) / truth.len() as f64)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        EventInterval, containment_recovery_rate, interval_contains, refuse_escaped_subevent,
+    };
+    use crate::SubeventContainmentError;
+
+    #[test]
+    fn local_branches_cover_containment_and_payloads() {
+        let parent = EventInterval::new(10, 40).expect("parent");
+        let inside = EventInterval::new(15, 30).expect("inside");
+        assert_eq!(parent.start_seconds(), 10);
+        assert_eq!(parent.end_seconds(), 40);
+        assert!(interval_contains(parent, inside).expect("inside"));
+        refuse_escaped_subevent(parent, inside).expect("contained");
+        let early = EventInterval::new(0, 20).expect("early");
+        assert!(!interval_contains(parent, early).expect("early"));
+        assert_eq!(
+            refuse_escaped_subevent(parent, early),
+            Err(SubeventContainmentError::SubeventEscapesParent)
+        );
+        assert_eq!(
+            EventInterval::new(4, 4),
+            Err(SubeventContainmentError::InvalidIntervalPayload)
+        );
+        let matched = containment_recovery_rate(&[true], &[true]).expect("rate");
+        assert!((matched - 1.0).abs() < f64::EPSILON);
+        assert_eq!(
+            containment_recovery_rate(&[], &[]),
+            Err(SubeventContainmentError::InvalidIntervalPayload)
+        );
+        assert_eq!(
+            containment_recovery_rate(&[true], &[]),
+            Err(SubeventContainmentError::InvalidIntervalPayload)
+        );
+    }
+}

crates/subevent_containment/src/lib.rs

@@ -0,0 +1,21 @@
+#![forbid(unsafe_code)]
+#![deny(missing_docs)]
+#![allow(clippy::cast_precision_loss)]
+//! Subevent intervals must stay inside the parent event interval.
+//!
+//! A subevent is part of a versioned event instance. Its event-time interval
+//! cannot start before or end after the parent (ADR 0003).
+
+mod error;
+mod interval;
+
+/// Fail-closed subevent-containment errors.
+pub use error::SubeventContainmentError;
+/// One half-open event-time interval.
+pub use interval::EventInterval;
+/// Fraction of recovered containment flags that match known truth.
+pub use interval::containment_recovery_rate;
+/// Return whether a child interval lies entirely inside a parent interval.
+pub use interval::interval_contains;
+/// Refuse to attach a subevent that escapes the parent interval.
+pub use interval::refuse_escaped_subevent;

crates/subevent_containment/tests/containment_contract.rs

@@ -0,0 +1,79 @@
+//! A subevent cannot escape its parent event-time interval.
+
+use subevent_containment::{
+    EventInterval, SubeventContainmentError, containment_recovery_rate, interval_contains,
+    refuse_escaped_subevent,
+};
+
+fn interval(start: i64, end: i64) -> EventInterval {
+    EventInterval::new(start, end).expect("interval")
+}
+
+#[test]
+fn escaped_subevents_cannot_attach_to_the_parent() {
+    let parent = interval(10, 40);
+    let inside = interval(15, 30);
+    let early = interval(0, 20);
+    let late = interval(30, 50);
+    assert!(interval_contains(parent, inside).expect("inside"));
+    refuse_escaped_subevent(parent, inside).expect("contained");
+    assert!(!interval_contains(parent, early).expect("early"));
+    assert_eq!(
+        refuse_escaped_subevent(parent, early),
+        Err(SubeventContainmentError::SubeventEscapesParent)
+    );
+    assert_eq!(
+        refuse_escaped_subevent(parent, late),
+        Err(SubeventContainmentError::SubeventEscapesParent)
+    );
+}
+
+#[test]
+fn recovered_containment_matches_known_truth_better_than_accepting_all() {
+    let parent = interval(10, 40);
+    let children = [interval(15, 30), interval(0, 20), interval(12, 18)];
+    let truth = [true, false, true];
+    let recovered = [
+        interval_contains(parent, children[0]).expect("c0"),
+        interval_contains(parent, children[1]).expect("c1"),
+        interval_contains(parent, children[2]).expect("c2"),
+    ];
+    let collapsed = [true, true, true];
+    let recovered_rate = containment_recovery_rate(&truth, &recovered).expect("recovered");
+    let collapsed_rate = containment_recovery_rate(&truth, &collapsed).expect("collapsed");
+    let expected = {
+        let mut matches = 0_u32;
+        for (truth_flag, decided_flag) in truth.iter().zip(recovered.iter()) {
+            if truth_flag == decided_flag {
+                matches += 1;
+            }
+        }
+        f64::from(matches) / f64::from(u32::try_from(truth.len()).expect("len"))
+    };
+    assert!((recovered_rate - expected).abs() < f64::EPSILON);
+    assert!(recovered_rate > collapsed_rate);
+}
+
+#[test]
+fn empty_or_invalid_interval_payloads_fail_closed() {
+    assert_eq!(
+        EventInterval::new(10, 10),
+        Err(SubeventContainmentError::InvalidIntervalPayload)
+    );
+    assert_eq!(
+        EventInterval::new(10, 9),
+        Err(SubeventContainmentError::InvalidIntervalPayload)
+    );
+    assert_eq!(
+        containment_recovery_rate(&[], &[]),
+        Err(SubeventContainmentError::InvalidIntervalPayload)
+    );
+    assert_eq!(
+        containment_recovery_rate(&[true], &[]),
+        Err(SubeventContainmentError::InvalidIntervalPayload)
+    );
+    assert_eq!(
+        containment_recovery_rate(&[true, false], &[true]),
+        Err(SubeventContainmentError::InvalidIntervalPayload)
+    );
+}

crates/subevent_containment/tests/crate_contract.rs

@@ -0,0 +1,7 @@
+//! Integration contract for the `subevent_containment` package identity.
+
+#[test]
+fn package_identity_is_stable() {
+    let observed = std::hint::black_box(env!("CARGO_PKG_NAME"));
+    assert_eq!(observed, "subevent_containment");
+}

docs/TRACEABILITY.md

@@ -13,7 +13,7 @@ The full APA 7th standards/literature register remains `docs/research/standards-
 | six distinct clocks and uncertain intervals | PRD; ADR 0002; ISO 24617-1:2012; Hobbs & Pan (2017) | merged PR #8 `temporal_core` on protected main; PR #5 historical lineage only | implemented-main |
 | Allen relation algebra/bounded closure | ADR 0002; Allen (1983) | merged PR #9 `temporal_core` path-consistency on protected main | implemented-main |
 | forward-only transition subgraph | PRD; ADR 0002/0003 | `relation_graph` on protected main | implemented-main |
-| event ontology/evidence mentions | PRD; ADR 0003 | `event_core` mention/instance separation on protected main; `persistence_postgres` mention SQL implemented-main refuses mention-as-instance; event-instance SQL (#39 implemented-main) refuses inverted windows; Brier calibration on the active PR; full intelligence stack remaining | partial |
+| event ontology/evidence mentions | PRD; ADR 0003 | `event_core` mention/instance separation on protected main; `subevent_containment` parent-window gate on the active PR; event-instance SQL implemented-main; full intelligence stack remaining | active-PR |
 | time-varying cross-classified multiple membership | PRD; ADR 0003 | `membership_core` network on protected main; multilevel estimators remaining | partial |
 | leakage-safe availability/cutoff snapshots | PRD; ADR 0002/0013 | `corpus_split` on protected main | implemented-main |
 | recovery metrics (RMSE, bias, coverage, graph, temporal order, Monte Carlo SE gates) | PRD; Test Strategy; ADR 0007/0014 | `validation_core` on protected main (PR #19); SE-aware Monte Carlo gates included | implemented-main |

docs/adr/0003-relational-event-multiple-membership.md

@@ -1,6 +1,7 @@
 # ADR 0003 — Relational event ontology and time-varying multiple membership
 
 **Decision status:** Accepted  
+**Implementation maturity:** active-PR — subevent parent-window containment in `subevent_containment` on the active PR; multilevel estimators remain accepted-target  
 **Implementation maturity:** partial — membership network, event mention/instance separation, and Kish ESS implemented-main; nested ICC with cross-classified/multiple-membership refusal is this increment; full multilevel/MMMC estimators and remaining persistence remain accepted-target  
 **Implementation maturity:** partial — membership network and event mention/instance separation are implemented-main; typed relation graph with forward-only transitions is implemented-main. Multilevel psychometric estimators remain accepted-target. Remaining persistence details follow ADR 0013 and [`docs/TRACEABILITY.md`](../TRACEABILITY.md).  
 **Implementation maturity:** partial — membership network and event mention/instance separation implemented-main; typed relation graph with forward-only transitions implemented-main; multilevel estimators and persistence remain accepted-target

docs/adr/README.md

@@ -11,6 +11,7 @@ Read [`ADR_POLICY.md`](ADR_POLICY.md) first. **Decision status and implementatio
 | [0003](0003-relational-event-multiple-membership.md) | Relational event ontology and time-varying cross-classified multiple membership | Accepted | partial | Membership network/roles and forward-only relation graph are implemented-main; multilevel estimators remain accepted-target. This is an ontology/membership contract, not a statistical REM paper. ADR 0016 owns event-intelligence tasks. |
 | [0001](0001-rust-first-modular-msa.md) | Rust-first numerical core and CPU `f64` reference | Accepted | partial | Workspace foundation is implemented-main; checkpoint-versus-estimator authority is `checkpoint_authority` on the active PR. ADR 0011 owns cross-service/MSA authority; 0001 retains numerical/backend authority. |
 | [0002](0002-six-clock-temporal-semantics.md) | Six-clock temporal semantics and fail-closed historical leakage prevention | Accepted | active-PR | Unmerged PR #8 is the canonical Task 3 replacement implementing typed clocks/intervals against the current protected-main lineage; conflicted PR #5 is superseded lineage. Later graph/split enforcement remains target work. |
+| [0003](0003-relational-event-multiple-membership.md) | Relational event ontology and time-varying cross-classified multiple membership | Accepted | active-PR | Subevent parent-window containment in `subevent_containment` on the active PR; multilevel estimators remain accepted-target. |
 | [0003](0003-relational-event-multiple-membership.md) | Relational event ontology and time-varying cross-classified multiple membership | Accepted | partial | Membership network/roles and Kish ESS are implemented-main; this increment adds nested ICC with fail-closed cross-classified/multiple-membership refusal. Full multilevel/MMMC estimators, graph ontology, and remaining persistence stay accepted-target. ADR 0016 owns event-intelligence tasks. |
 | [0004](0004-shared-multilingual-latent-space.md) | One shared multilingual latent space with explicit invariance status | Accepted | accepted-target | ADR 0012 owns the full topic-estimator/backend/global-topic contract. |
 | [0005](0005-posterior-esem-dsem.md) | Posterior-aware ESEM/DSEM and valid compositional coordinates | Accepted | active-PR | Within/between decomposition in `longitudinal_core` on the active PR; remaining ESEM/DSEM fit remains accepted-target. ADR 0012 owns the upstream topic/network contract. |