Fold span grounding into EventMention (#170 / GAP-007)

ARCHITECTURE.md

@@ -60,7 +60,7 @@ boundaries above remain the target modular MSA architecture.
 | `semantic_core` | span-grounded semantic units; language is not identity |
 | `location_membership` | location is not entity identity and not a language channel |
 | `temporal_core` | typed clocks, intervals, and temporal reasoning |
-| `event_core` | event instances, mentions, roles, provenance, and CHRONOS occurrence-prediction calibration |
+| `event_core` | event instances, span-grounded `EventMention` (the only constructible mention type), roles, provenance, and CHRONOS occurrence-prediction calibration |
 | `relation_graph` | typed relations and forward-transition validation |
 | `membership_core` | time-varying cross-classified multiple membership, Kish ESS, nested ICC with non-nested refusal |
 | `role_contradiction` | customer and competitor cannot occupy the same group |

CHANGELOG.md

@@ -39,6 +39,7 @@ All notable changes to TEPP are documented here. The format follows Keep a Chang
 - `psychometric_core` recovers the Driver, Oud, and Voelkle (2017, p. 16 `MANIFESTMEANSstd`; Table 2, p. 12; footnote 4; Eq. 5, p. 5; 2017-era ctsem `summary.ctsemFit.R`; JSS PDF re-opened 2026-08-25T11:32Z from https://www.jstatsoft.org/index.php/jss/article/download/v077i05/1104) scalar standardised manifest mean on current main after `0ce16e8` restored the pre-consolidation unstandardised slice. Page 16 prints standardised matrices with the suffix `std` when appropriate. Footnote 4 standardises using only the relevant variance, not the total. Table 2 names `MANIFESTMEANS` `τ` the `n.manifest × 1` matrix of manifest means and `MANIFESTVAR` `Θ` the residual covariance of the indicators. The relevant variance for that named measurement intercept is residual `θ`, not total observed `Var(y) = λ² Var(η) + θ`. The 2017-era source forms unstandardised `MANIFESTMEANS` and does not form a `MANIFESTMEANSstd` matrix; the scalar map is `τ / √θ` after strictly positive `θ`. A zero mean is exactly zero. Zero `θ` has no positive SD and fails closed. A non-event clock fails closed. `MANIFESTMEANS` does not require stable `a < 0`. `θ / θ = 1` recovers the same number when `τ = √θ` and remains a distinct named quantity. `τ / √(λ² Var(η) + θ)` uses total observed variance and is not this residual map. Meredith (1993) remains unread (Unpaywall 2026-08-25T11:32Z: `is_oa: false`, 0 locations; OpenAlex closed; Springer `content/pdf` is a 3038-byte HTML stub). Mislevy (1991, *Psychometrika, 56*, 177–196) remains unread (Unpaywall 2026-08-25T11:32Z: `is_oa: false`, 0 locations). Still not a Kalman filter, not a matrix `expm`, not ESEM estimation, not DSEM, and not ctsem estimation.
 - `psychometric_core` recovers the Driver, Oud, and Voelkle (2017, p. 16 `CINTstd`; Eq. 1, p. 4; Table 2, p. 12; footnote 4; §7.1, pp. 18–19; JSS PDF re-opened 2026-08-25T11:43Z from https://www.jstatsoft.org/index.php/jss/article/download/v077i05/1104) scalar standardised continuous intercept on current main after consolidation dropped the pre-consolidation `κ / √p` slice. Page 16 prints standardised matrices with the suffix `std` when appropriate. Footnote 4 standardises using only the relevant variance, not the total. Table 2 names `κ` `CINT`. The relevant variance for that process intercept is within-subject `asymDIFFUSION` `p = −q / (2 a)`, not total `trait + p + added`. Form strictly positive `p` first, then `κ / √p`. A zero intercept is exactly zero after that positive SD. Zero `q` has no positive process SD and fails closed. Lasting `p` requires stable `a < 0`. A non-event clock fails closed. `(-κ / a) / √p` is `asymCINTstd` and is not this continuous intercept. `A^{-1}[e^{A Δt} − I] κ / √p` is `discreteCINTstd` and depends on the event interval. `κ / √(trait + p + added)` uses the total and is not this residual map. `TRAITVAR` is not the standardisation variance. Meredith (1993) remains unread (Unpaywall 2026-08-25T11:43Z: `is_oa: false`; Springer `content/pdf` is a 3038-byte HTML stub). Mislevy (1991) remains unread on the same terms. Still not a Kalman filter, not a matrix `expm`, not ESEM estimation, not DSEM, and not ctsem estimation.
 - Operator-gap register refreshed against protected main `c482ccea` (#239): workspace version 0.2.0, 57 crates, queue at seven open PRs with exact-head SHAs, issues #156/#168/#175 closed, GAP-009 advanced to estimator-core-plus-repairs with Leiden consensus remaining, GAP-001/GAP-012/GAP-017 closed on protected main, and a new Post-#239 state note recording both the estimator repairs and the non-release status of the version bump. Supersedes #236 whose base predated #239.
+- `event_core` `EventMention` is the only constructible mention type and must be span-grounded: it cites one exact `SourceSpan`, document identity, six-clock evidence, extractor/model version, and proposed/reviewed status, and the surface is the document substring at that span. Exact-extent precision/recall recover known ACE extents with occupancy RMSE 0 versus whole-document RMSE 1; reviewed status and TDT/CHRONOS detections still cannot promote an instance. Interval consistency, persistence, and exports remain later #170 work.
 - Restored protected-main gate integrity after the consolidation merges: hourly-scheduler prompt-contract tests now assert the gap-baseline-derived task contract (Gap ID naming, no invented weights) instead of stale increment-specific tokens, the operator-gap register inventory matches the live 33-PR queue, `evidence_core::image_unit` non-image/empty-subtype refusals and `load_union_branch_totals` valid-record accumulation have exact coverage, and the README crate fence plus duplicate registry entries stay deduped.
 - Branch-coverage diagnostics on the post-consolidation head exposed two uncovered outcomes in `evidence_core::image_unit` (`is_image_media_type_token` non-image prefix and empty-subtype refusals), one uncovered authored line (the strip-prefix refusal), and lost valid-record coverage for `load_union_branch_totals`; exact red-to-green cases now cover the non-image/empty-subtype data URIs and per-coordinate True/False accumulation.
 - Repaired post-consolidation merge fallout that left protected `main` red: restored the lost `return True` in the `check_coverage.py` match-guard branch, removed the shadowed duplicate `load_union_branch_totals` and `_is_multiline_match_guard` definitions plus duplicate workspace-crate entries (`episode_membership`, `analysis_engine`) from the contract tuple and Cargo member arrays, split two union-fused four-tuples back into `(variant, message)` pairs in the `event_core` error table, repaired the fused `identity_recovery_rate` body in `episode_membership::window`, deduplicated the checked-arithmetic eligible-count block in `analysis_engine`, fixed four-argument `unit()` test call sites, rebalanced the README crate-list fence around all 54 unique crates, and deduplicated the `location_membership`/`validation_core`/`tepp_api` architecture-table rows. Also documents private `PLAUSIBLE_IMAGE_MEDIA_TYPES` so `cargo doc -D warnings` passes.

DOCUMENTATION.md

@@ -44,6 +44,8 @@ TEPP's approved PRD v0.4 and implementation plan are the primary product baselin
 | Rubin total-variance doctoring | [`docs/research/rubin-total-variance.md`](docs/research/rubin-total-variance.md) |
 | Strong-invariance latent-mean doctoring | [`docs/research/strong-invariance-latent-means.md`](docs/research/strong-invariance-latent-means.md) |
 | Mention-confidence Brier doctoring | [`docs/research/mention-confidence-brier.md`](docs/research/mention-confidence-brier.md) |
+| Span-grounded mention extent doctoring | [`docs/research/span-grounded-mentions.md`](docs/research/span-grounded-mentions.md) |
+| Span-grounded mention numeric provenance | [`docs/doctoring/span-grounded-mentions.md`](docs/doctoring/span-grounded-mentions.md) |
 | Event-intelligence status-gate doctoring | [`docs/research/event-intelligence-status-gates.md`](docs/research/event-intelligence-status-gates.md) |
 | TDT link-detection precision/recall doctoring | [`docs/research/event-link-detection-calibration.md`](docs/research/event-link-detection-calibration.md) |
 | First-story detection FAR/miss doctoring | [`docs/research/first-story-detection-calibration.md`](docs/research/first-story-detection-calibration.md) |
@@ -61,6 +63,8 @@ TEPP's approved PRD v0.4 and implementation plan are the primary product baselin
 | Relation absence is not negative evidence | [`docs/research/relation-absence-not-negative.md`](docs/research/relation-absence-not-negative.md) |
 | Adaptive orchestration router doctoring | [`docs/research/adaptive-orchestration-router.md`](docs/research/adaptive-orchestration-router.md) |
 | Mention-confidence Brier doctoring | [`docs/research/mention-confidence-brier.md`](docs/research/mention-confidence-brier.md) |
+| Span-grounded mention extent doctoring | [`docs/research/span-grounded-mentions.md`](docs/research/span-grounded-mentions.md) |
+| Span-grounded mention numeric provenance | [`docs/doctoring/span-grounded-mentions.md`](docs/doctoring/span-grounded-mentions.md) |
 | Event-intelligence status-gate doctoring | [`docs/research/event-intelligence-status-gates.md`](docs/research/event-intelligence-status-gates.md) |
 | Stopword-deletion doctoring | [`docs/research/stopword-deletion.md`](docs/research/stopword-deletion.md) |
 | Topic log-ratio coordinate doctoring | [`docs/research/topic-logratio-coordinates.md`](docs/research/topic-logratio-coordinates.md) |
@@ -131,6 +135,8 @@ TEPP's approved PRD v0.4 and implementation plan are the primary product baselin
 | Actions workflow fleet audit | [`docs/operations/ACTIONS_WORKFLOW_FLEET.md`](docs/operations/ACTIONS_WORKFLOW_FLEET.md) |
 | Actions fleet research doctoring | [`docs/research/actions-workflow-fleet.md`](docs/research/actions-workflow-fleet.md) |
 | Mention-confidence Brier doctoring | [`docs/research/mention-confidence-brier.md`](docs/research/mention-confidence-brier.md) |
+| Span-grounded mention extent doctoring | [`docs/research/span-grounded-mentions.md`](docs/research/span-grounded-mentions.md) |
+| Span-grounded mention numeric provenance | [`docs/doctoring/span-grounded-mentions.md`](docs/doctoring/span-grounded-mentions.md) |
 | Event-intelligence status-gate doctoring | [`docs/research/event-intelligence-status-gates.md`](docs/research/event-intelligence-status-gates.md) |
 | VRAM budget / GPU fallback doctoring | [`docs/research/vram-budget-types.md`](docs/research/vram-budget-types.md) |
 | Causal-identification gate doctoring | [`docs/research/causal-identification-gate.md`](docs/research/causal-identification-gate.md) |

crates/event_core/src/error.rs

@@ -56,6 +56,16 @@ pub enum EventError {
     PredictionIsNotEventInstance,
     /// An unknown occurrence-truth label was supplied.
     UnknownOccurrenceTruth,
+    /// A span-grounded mention was treated as an event instance.
+    SpanMentionIsNotEventInstance,
+    /// Mention availability is after the knowledge cutoff.
+    MentionIneligibleAtCutoff,
+    /// The extractor or model version was empty or whitespace-only.
+    EmptyExtractorVersion,
+    /// The mention span does not belong to the supplied document.
+    MentionSpanDocumentMismatch,
+    /// An unknown mention-review status name was supplied.
+    UnknownMentionReviewStatus,
 }
 
 impl fmt::Display for EventError {
@@ -94,6 +104,11 @@ impl fmt::Display for EventError {
             Self::UnknownStoryBoundaryLabel => "unknown story boundary label",
             Self::PredictionIsNotEventInstance => "CHRONOS prediction is not an event instance",
             Self::UnknownOccurrenceTruth => "unknown occurrence truth label",
+            Self::SpanMentionIsNotEventInstance => "span-grounded mention is not an event instance",
+            Self::MentionIneligibleAtCutoff => "mention availability is after the knowledge cutoff",
+            Self::EmptyExtractorVersion => "empty extractor version",
+            Self::MentionSpanDocumentMismatch => "mention span does not belong to the document",
+            Self::UnknownMentionReviewStatus => "unknown mention review status",
         };
         formatter.write_str(message)
     }
@@ -106,6 +121,7 @@ mod tests {
     use super::EventError;
 
     #[test]
+    #[allow(clippy::too_many_lines)]
     fn error_messages_are_stable() {
         for (error, message) in [
             (
@@ -199,6 +215,23 @@ mod tests {
                 EventError::UnknownOccurrenceTruth,
                 "unknown occurrence truth label",
             ),
+            (
+                EventError::SpanMentionIsNotEventInstance,
+                "span-grounded mention is not an event instance",
+            ),
+            (
+                EventError::MentionIneligibleAtCutoff,
+                "mention availability is after the knowledge cutoff",
+            ),
+            (EventError::EmptyExtractorVersion, "empty extractor version"),
+            (
+                EventError::MentionSpanDocumentMismatch,
+                "mention span does not belong to the document",
+            ),
+            (
+                EventError::UnknownMentionReviewStatus,
+                "unknown mention review status",
+            ),
         ] {
             assert_eq!(error.to_string(), message);
         }

crates/event_core/src/lib.rs

@@ -4,15 +4,15 @@
 //!
 //! TEPP separates **fallible event mentions** grounded in evidence from
 //! **versioned event instances** used for temporal state, multilevel membership,
-//! and scientific estimation. Mentions and first-story detections never
-//! silently become instances, and TDT detections and CHRONOS predictions
-//! remain measurement or hypothesis artifacts until independently promoted.
-//! and scientific estimation. Mentions never silently become instances. TDT
-//! detections and CHRONOS predictions remain measurement or hypothesis
-//! artifacts until independently promoted. Track assignments, story
-//! segmentations, CHRONOS schema-slot predictions, and occurrence forecasts
-//! remain measurement or hypothesis artifacts and cannot promote an instance
-//! without an explicit evidence-backed promotion gate.
+//! and scientific estimation. [`EventMention`] is the only constructible
+//! mention type: it cites one exact source extent, document identity,
+//! six-clock evidence, extractor version, and review status, and the surface
+//! form is the document substring at that span. Mentions, first-story
+//! detections, TDT detections, and CHRONOS predictions never silently become
+//! instances. Track assignments, story segmentations, CHRONOS schema-slot
+//! predictions, and occurrence forecasts remain measurement or hypothesis
+//! artifacts and cannot promote an instance without an explicit
+//! evidence-backed promotion gate.
 
 mod confidence;
 mod error;
@@ -27,6 +27,7 @@ mod registry;
 mod role;
 mod schema;
 mod segment;
+mod span_mention;
 mod track;
 
 /// Finite confidence on the closed unit interval.
@@ -81,8 +82,10 @@ pub use link::event_link_recall;
 pub use link::refuse_event_link_as_instance;
 /// Explicit refusal to treat a TDT link as a state transition.
 pub use link::refuse_event_link_as_transition;
-/// Fallible textual event mention.
+/// Fallible textual event mention grounded in one exact source extent.
 pub use mention::EventMention;
+/// Explicit refusal to treat a span-grounded mention as an instance.
+pub use mention::refuse_span_mention_as_instance;
 /// One CHRONOS occurrence forecast that remains hypothetical.
 pub use prediction::ChronosOccurrenceForecast;
 /// Opaque CHRONOS occurrence-prediction identity.
@@ -131,6 +134,14 @@ pub use segment::story_boundary_recall;
 pub use segment::story_pk;
 /// Pevzner–Hearst `WindowDiff` against a known-truth segmentation.
 pub use segment::story_window_diff;
+/// Six-clock evidence bound to one mention.
+pub use span_mention::MentionEvidenceClocks;
+/// Proposed-versus-reviewed mention inspection status.
+pub use span_mention::MentionReviewStatus;
+/// Precision of recovered mention extents against known truth.
+pub use span_mention::mention_span_precision;
+/// Recall of recovered mention extents against known truth.
+pub use span_mention::mention_span_recall;
 /// Assignment of one mention to one hypothesized TDT track.
 pub use track::EventTrackAssignment;
 /// Opaque TDT track identity.