feat(relation): refuse citation edges as state transitions

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 |
+| `citation_edge` | citation, revision, translation, and retrospective edges are not state transitions |
 
 No crate exposes placeholder production behavior in Task 1. This prevents an
 empty façade from becoming a de facto public API before its invariants and tests

CHANGELOG.md

@@ -6,6 +6,7 @@ All notable changes to TEPP are documented here. The format follows Keep a Chang
 
 ### Added
 
+- `citation_edge` provenance gate: citation, translation, revision, and retrospective-report edges may point to the past but cannot become input-process-outcome transitions; recovered kinds match known truth at a higher computed rate than collapsing every edge to citation (ADR 0002/0003).
 - `tepp_api` adaptive orchestration router (ADR 0010): versioned `direct`/`verify`/`committee`/`conductor`/`abstain` selection from CPU `f64` risk, ambiguity, evidence, and token-budget inputs; recorded stages, recursion, decomposition, access lists, and role-specific reasoning effort; fail-closed document-controlled policy/access/credentials; LLM plans remain proposals under deterministic statistical authority; comparable-budget ablation requires a direct baseline; credential-free contextual-orchestrator binding. Live NIM HTTP remains accepted-target.
 - `tepp_api` purpose-bound provider-payload minimization: time-bounded `PurposeGrant` evaluation, fail-closed expired/not-yet-valid/inverted/cross-tenant/impossible-calendar denial, semantic UTC calendar validation, refusal to copy identity mappings into model-provider payloads or ordinary logs, preservation of opaque analytical identifiers and membership roles (no blanket PII mask), a separately authorized scientific re-identification path, and an internally bound FIPS 180-4 SHA-256 audit digest appended through `ReidentificationAuditSink` before disclosure.
 - `persistence_postgres` backup/restore integrity: restored snapshots stay unusable until tenant, canonical `SHA-256`, knowledge-cutoff eligibility, temporal window order, and append-only triggers revalidate; SQL probes raise `restore integrity failed` (ADR 0013).

Cargo.toml

@@ -11,6 +11,7 @@ members = [
     "crates/tepp_simulation",
     "crates/validation_core",
     "crates/tepp_api",
+    "crates/citation_edge",
 ]
 default-members = [
     "crates/evidence_core",
@@ -23,6 +24,7 @@ default-members = [
     "crates/tepp_simulation",
     "crates/validation_core",
     "crates/tepp_api",
+    "crates/citation_edge",
 ]
 
 [workspace.package]

README.md

@@ -7,7 +7,7 @@ implemented in Rust.
 ## Current implementation state
 
 This branch establishes the Task 1 Rust workspace and quality-gate foundation.
-The ten bounded crates compile independently but intentionally expose no
+The eleven bounded crates compile independently but intentionally expose no
 placeholder production APIs. Domain behavior begins in Task 2 with immutable
 evidence identifiers and source records.
 
@@ -22,6 +22,7 @@ crates/corpus_split
 crates/tepp_simulation
 crates/validation_core
 crates/tepp_api
+crates/citation_edge
 ```
 
 ## Local verification

crates/citation_edge/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "citation_edge"
+description = "Citation and retrospective edges cannot become reverse state transitions."
+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/citation_edge/src/error.rs

@@ -0,0 +1,48 @@
+//! Fail-closed citation-edge errors.
+
+use std::fmt;
+
+/// A fail-closed citation-edge error.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[non_exhaustive]
+pub enum CitationEdgeError {
+    /// A provenance edge was treated as a state transition.
+    ProvenanceIsNotTransition,
+    /// A kind slice was empty or length-mismatched.
+    InvalidEdgePayload,
+}
+
+impl fmt::Display for CitationEdgeError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let message = match self {
+            Self::ProvenanceIsNotTransition => {
+                "citation or retrospective edges are not state transitions"
+            }
+            Self::InvalidEdgePayload => "invalid citation-edge payload",
+        };
+        formatter.write_str(message)
+    }
+}
+
+impl std::error::Error for CitationEdgeError {}
+
+#[cfg(test)]
+mod tests {
+    use super::CitationEdgeError;
+
+    #[test]
+    fn error_messages_are_stable() {
+        for (error, message) in [
+            (
+                CitationEdgeError::ProvenanceIsNotTransition,
+                "citation or retrospective edges are not state transitions",
+            ),
+            (
+                CitationEdgeError::InvalidEdgePayload,
+                "invalid citation-edge payload",
+            ),
+        ] {
+            assert_eq!(error.to_string(), message);
+        }
+    }
+}

crates/citation_edge/src/kind.rs

@@ -0,0 +1,79 @@
+//! Provenance kinds that may point to the past.
+
+use crate::CitationEdgeError;
+
+/// Closed vocabulary of provenance edges that are not state transitions.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ProvenanceKind {
+    /// A citation of earlier evidence.
+    Citation,
+    /// A translation of an earlier document.
+    Translation,
+    /// A revision of an earlier document.
+    Revision,
+    /// A retrospective report about an earlier event.
+    RetrospectiveReport,
+}
+
+/// Refuse to treat a provenance edge as a forward state transition.
+///
+/// # Errors
+///
+/// Always returns [`CitationEdgeError::ProvenanceIsNotTransition`].
+pub fn refuse_provenance_as_transition(_kind: ProvenanceKind) -> Result<(), CitationEdgeError> {
+    Err(CitationEdgeError::ProvenanceIsNotTransition)
+}
+
+/// Fraction of recovered provenance kinds that match known truth.
+///
+/// # Errors
+///
+/// Returns [`CitationEdgeError::InvalidEdgePayload`] when either slice is
+/// empty or the lengths differ.
+pub fn edge_kind_recovery_rate(
+    truth: &[ProvenanceKind],
+    decided: &[ProvenanceKind],
+) -> Result<f64, CitationEdgeError> {
+    if truth.is_empty() || truth.len() != decided.len() {
+        return Err(CitationEdgeError::InvalidEdgePayload);
+    }
+    let mut matches = 0_u32;
+    for (truth_kind, decided_kind) in truth.iter().zip(decided) {
+        if truth_kind == decided_kind {
+            matches += 1;
+        }
+    }
+    Ok(f64::from(matches) / truth.len() as f64)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{ProvenanceKind, edge_kind_recovery_rate, refuse_provenance_as_transition};
+    use crate::CitationEdgeError;
+
+    #[test]
+    fn local_branches_cover_all_kinds_and_payloads() {
+        for kind in [
+            ProvenanceKind::Citation,
+            ProvenanceKind::Translation,
+            ProvenanceKind::Revision,
+            ProvenanceKind::RetrospectiveReport,
+        ] {
+            assert_eq!(
+                refuse_provenance_as_transition(kind),
+                Err(CitationEdgeError::ProvenanceIsNotTransition)
+            );
+        }
+        let truth = [ProvenanceKind::Citation, ProvenanceKind::Revision];
+        let matched = edge_kind_recovery_rate(&truth, &truth).expect("rate");
+        assert!((matched - 1.0).abs() < f64::EPSILON);
+        assert_eq!(
+            edge_kind_recovery_rate(&[], &[]),
+            Err(CitationEdgeError::InvalidEdgePayload)
+        );
+        assert_eq!(
+            edge_kind_recovery_rate(&truth, &[]),
+            Err(CitationEdgeError::InvalidEdgePayload)
+        );
+    }
+}

crates/citation_edge/src/lib.rs

@@ -0,0 +1,19 @@
+#![forbid(unsafe_code)]
+#![deny(missing_docs)]
+#![allow(clippy::cast_precision_loss)]
+//! Citation and retrospective edges cannot become reverse state transitions.
+//!
+//! Provenance edges may point to earlier event time. They never become
+//! input-process-outcome transitions (ADR 0002/0003).
+
+mod error;
+mod kind;
+
+/// Fail-closed citation-edge errors.
+pub use error::CitationEdgeError;
+/// Closed vocabulary of provenance edges that are not state transitions.
+pub use kind::ProvenanceKind;
+/// Fraction of recovered provenance kinds that match known truth.
+pub use kind::edge_kind_recovery_rate;
+/// Refuse to treat a provenance edge as a forward state transition.
+pub use kind::refuse_provenance_as_transition;

crates/citation_edge/tests/crate_contract.rs

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

crates/citation_edge/tests/edge_kind_contract.rs

@@ -0,0 +1,72 @@
+//! Citation and retrospective edges cannot be promoted to state transitions.
+
+use citation_edge::{
+    CitationEdgeError, ProvenanceKind, edge_kind_recovery_rate, refuse_provenance_as_transition,
+};
+
+#[test]
+fn provenance_kinds_cannot_become_state_transitions() {
+    assert_eq!(
+        refuse_provenance_as_transition(ProvenanceKind::Citation),
+        Err(CitationEdgeError::ProvenanceIsNotTransition)
+    );
+    assert_eq!(
+        refuse_provenance_as_transition(ProvenanceKind::Translation),
+        Err(CitationEdgeError::ProvenanceIsNotTransition)
+    );
+    assert_eq!(
+        refuse_provenance_as_transition(ProvenanceKind::Revision),
+        Err(CitationEdgeError::ProvenanceIsNotTransition)
+    );
+    assert_eq!(
+        refuse_provenance_as_transition(ProvenanceKind::RetrospectiveReport),
+        Err(CitationEdgeError::ProvenanceIsNotTransition)
+    );
+}
+
+#[test]
+fn recovered_kinds_match_known_truth_better_than_a_transition_collapse() {
+    let truth = [
+        ProvenanceKind::Citation,
+        ProvenanceKind::Translation,
+        ProvenanceKind::Revision,
+    ];
+    let recovered = truth;
+    let collapsed = [
+        ProvenanceKind::Citation,
+        ProvenanceKind::Citation,
+        ProvenanceKind::Citation,
+    ];
+    let recovered_rate = edge_kind_recovery_rate(&truth, &recovered).expect("recovered");
+    let collapsed_rate = edge_kind_recovery_rate(&truth, &collapsed).expect("collapsed");
+    let expected = {
+        let mut matches = 0_u32;
+        for (truth_kind, decided_kind) in truth.iter().zip(recovered.iter()) {
+            if truth_kind == decided_kind {
+                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_mismatched_kind_payloads_fail_closed() {
+    assert_eq!(
+        edge_kind_recovery_rate(&[], &[]),
+        Err(CitationEdgeError::InvalidEdgePayload)
+    );
+    assert_eq!(
+        edge_kind_recovery_rate(&[ProvenanceKind::Citation], &[]),
+        Err(CitationEdgeError::InvalidEdgePayload)
+    );
+    assert_eq!(
+        edge_kind_recovery_rate(
+            &[ProvenanceKind::Citation, ProvenanceKind::Revision],
+            &[ProvenanceKind::Citation]
+        ),
+        Err(CitationEdgeError::InvalidEdgePayload)
+    );
+}

docs/TRACEABILITY.md

@@ -12,7 +12,7 @@ The full APA 7th standards/literature register remains `docs/research/standards-
 | Rust workspace/quality foundation | ADR 0007 | workspace/CI/repository contract | implemented-main |
 | six distinct clocks and uncertain intervals | PRD; ADR 0002 | PR #8 `temporal_core` on protected main; PR #5 historical only | implemented-main |
 | Allen relation algebra/bounded closure | ADR 0002; temporal research | 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 |
+| forward-only transition subgraph | PRD; ADR 0002/0003 | `relation_graph` on protected main; `citation_edge` provenance-vs-transition gate on the active PR | active-PR |
 | 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; full intelligence stack remaining | partial |
 | 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 |

docs/adr/0002-six-clock-temporal-semantics.md

@@ -1,7 +1,7 @@
 # ADR 0002 — Six-clock temporal semantics and leakage prevention
 
 **Decision status:** Accepted  
-**Implementation maturity:** active-PR — unmerged PR #8 is the canonical replacement implementing typed clocks/intervals against the current protected-main lineage; superseded/conflicted PR #5 is historical lineage only; downstream transition/split enforcement remains accepted-target  
+**Implementation maturity:** active-PR — provenance-vs-transition gate in `citation_edge` on the active PR; remaining graph/split enforcement stays accepted-target  
 **Date:** 2026-08-05  
 **Supersedes:** None. ADR 0013 owns persistence/split representation; ADR 0016 owns event-intelligence reasoning above these temporal primitives.
 

docs/adr/README.md

@@ -7,7 +7,7 @@ Read [`ADR_POLICY.md`](ADR_POLICY.md) first. **Decision status and implementatio
 | ADR | Decision | Decision status | Implementation maturity | Clarification / supersession |
 |---|---|---|---|---|
 | [0001](0001-rust-first-modular-msa.md) | Rust-first numerical core and CPU `f64` reference | Accepted | partial | 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. |
+| [0002](0002-six-clock-temporal-semantics.md) | Six-clock temporal semantics and fail-closed historical leakage prevention | Accepted | active-PR | Provenance-vs-transition gate in `citation_edge` on the active PR; remaining graph/split enforcement stays accepted-target. |
 | [0003](0003-relational-event-multiple-membership.md) | Relational event ontology and time-varying cross-classified multiple membership | Accepted | partial | Weighted time-varying membership network/roles are active-PR (PR #12); full multilevel estimators, graph ontology, and persistence remain 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 | accepted-target | Downstream psychometric authority; upstream topic/network model is clarified by ADR 0012. |

docs/research/citation-not-transition.md

@@ -0,0 +1,31 @@
+# Citation edges are not state transitions (doctoring)
+
+## Scope
+
+`citation_edge` keeps citation, translation, revision, and retrospective
+report edges out of the forward state-transition vocabulary. Recovery is
+the computed share of recovered kinds that match known truth.
+
+This slice does not persist the graph, implement Allen composition, or
+replace `relation_graph`.
+
+## Authority
+
+### Normative TEPP contract
+
+- `docs/adr/0002-six-clock-temporal-semantics.md` — forward
+  state-transition and input-process-outcome edges never move backward
+  in event time; citation and retrospective edges may point to the past
+  but never become reverse state transitions.
+- `docs/adr/0003-relational-event-multiple-membership.md` — typed
+  relations distinguish transition from provenance.
+
+### Supporting literature
+
+Allen (1983) classifies interval relations; it does **not** authorize
+treating a bibliographic citation as a `causes` or `intervenes_on`
+transition.
+
+Allen, J. F. (1983). Maintaining knowledge about temporal intervals.
+*Communications of the ACM, 26*(11), 832–843.
+https://doi.org/10.1145/182.358434

docs/research/standards-and-literature.md

@@ -96,6 +96,8 @@ Moreau, L., & Missier, P. (Eds.). (2013). *PROV-DM: The PROV data model*. World
 
 TEPP separates stable record identity, content equality, exact text location, wire representation, authorization, and provenance. JSON wire records are explicit versioned DTOs with unknown-field rejection and reconstruct through domain validation. `SHA-256` detects content substitution but is not treated as proof of origin, authority, or chain of custody.
 
+Allen, J. F. (1983). Maintaining knowledge about temporal intervals. *Communications of the ACM, 26*(11), 832–843. https://doi.org/10.1145/182.358434. Interval relations inform `citation_edge`; they do not make a citation a state transition.
+
 ## Privacy lifecycle, retention, and legal hold
 
 European Union. (2016). *Regulation (EU) 2016/679 of the European Parliament and of the Council of 27 April 2016 on the protection of natural persons with regard to the processing of personal data and on the free movement of such data (General Data Protection Regulation)*. Official Journal of the European Union, L 119, 1–88. https://eur-lex.europa.eu/eli/reg/2016/679/oj

docs/validation/temporal-event-foundation.md

@@ -23,6 +23,7 @@ This report tracks exact-head scientific and engineering evidence required befor
 | Truth corpora / manifests | `tepp_simulation` | implemented-main | — | deterministic generator tests | Task 10 / PR #18 |
 | Recovery metrics | `validation_core` | implemented-main | — | RMSE/bias/coverage/MC gates | Task 11 / PR #19 |
 | Versioned API/export contracts | `tepp_api` | implemented-main | naruon HTTP interchange | unknown-field/version/limit + naruon HTTPS interchange tests | Task 12 / PR #21; live HTTP service remaining |
+| Provenance-vs-transition gate | `citation_edge` | active-PR | this PR | recovered kind rate vs citation collapse | ADR 0002/0003 |
 | Purpose-bound provider payloads | `tepp_api` | implemented-main | provider-payload minimization | expired/not-yet-valid/inverted/cross-tenant/impossible-calendar grant, mapping refusal, audited elevated re-id replay | ADR 0009; `docs/research/provider-payload-minimization.md` |
 | Adaptive orchestration router | `tepp_api` | accepted-target | active PR | mode selection, document-control denial, ablation, credential-free bind | ADR 0010; `docs/research/adaptive-orchestration-router.md` |
 | CWL modular connectors | `docs/connectors/*` | implemented-main | — | contract docs + examples | PR #22; live HTTP ports remaining |

scripts/check_workspace_contract.py

@@ -23,6 +23,7 @@
     "tepp_simulation",
     "validation_core",
     "tepp_api",
+    "citation_edge",
 )
 
 REQUIRED_CI_SNIPPETS: tuple[str, ...] = (