feat(membership): refuse customer-competitor overlap

ARCHITECTURE.md

@@ -63,6 +63,7 @@ boundaries above remain the target modular MSA architecture.
 | `event_core` | event instances, mentions, 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 |
 | `persistence_postgres` | PostgreSQL repositories and migrations |
 | `corpus_split` | cutoff-safe, relation-aware partitioning |
 | `tepp_simulation` | known-truth temporal/event data generation |

CHANGELOG.md

@@ -66,6 +66,7 @@ All notable changes to TEPP are documented here. The format follows Keep a Chang
 - `psychometric_core` posterior-aware structural input gates: construct classification, refusal of raw-proportion Pearson/OLS, explicit ALR-versus-ILR geometry boundaries, CPU `f64` OLS recovery, posterior-draw loading point-estimate averaging without Rubin uncertainty claims, invariance-gated latent-mean comparison, and causal-heuristic refusal (ADR 0005 first production slice; no new migration).
 ### Added
 
+- `role_contradiction` identity gate: customer and competitor cannot occupy the same group; recovered commercial-role labels match known truth at a higher computed rate than collapsing every role to customer (ADR 0003).
 - `episode_membership` identity gate: a document's episode membership cannot
   start before or end after the episode event-time interval; recovered
   containment flags are compared with known truth (ADR 0003).

Cargo.toml

@@ -53,6 +53,7 @@ members = [
     "crates/episode_membership",
     "crates/compute_backend",
     "crates/membership_target",
+    "crates/role_contradiction",
     "crates/analysis_engine",
     "crates/topic_measurement",
     "crates/psychometric_core",
@@ -69,7 +70,6 @@ default-members = [
     "crates/tepp_simulation",
     "crates/validation_core",
     "crates/tepp_api",
-
     "crates/location_membership",
     "crates/prompt_source",
     "crates/corpus_background",
@@ -110,6 +110,7 @@ default-members = [
     "crates/episode_membership",
     "crates/compute_backend",
     "crates/membership_target",
+    "crates/role_contradiction",
     "crates/analysis_engine",
     "crates/topic_measurement",
     "crates/psychometric_core",

crates/role_contradiction/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "role_contradiction"
+description = "Customer and competitor cannot occupy the same group at once."
+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/role_contradiction/src/error.rs

@@ -0,0 +1,55 @@
+//! Fail-closed role-contradiction errors.
+
+use std::fmt;
+
+/// A fail-closed role-contradiction error.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[non_exhaustive]
+pub enum RoleContradictionError {
+    /// Customer and competitor were assigned in the same group.
+    CustomerCompetitorOverlap,
+    /// A contextual role was treated as a permanent entity class.
+    RoleIsNotEntityClass,
+    /// A recovery slice was empty or length-mismatched.
+    InvalidRolePayload,
+}
+
+impl fmt::Display for RoleContradictionError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let message = match self {
+            Self::CustomerCompetitorOverlap => {
+                "customer and competitor cannot occupy the same group"
+            }
+            Self::RoleIsNotEntityClass => "contextual role is not an entity class",
+            Self::InvalidRolePayload => "invalid role-contradiction payload",
+        };
+        formatter.write_str(message)
+    }
+}
+
+impl std::error::Error for RoleContradictionError {}
+
+#[cfg(test)]
+mod tests {
+    use super::RoleContradictionError;
+
+    #[test]
+    fn error_messages_are_stable() {
+        for (error, message) in [
+            (
+                RoleContradictionError::CustomerCompetitorOverlap,
+                "customer and competitor cannot occupy the same group",
+            ),
+            (
+                RoleContradictionError::RoleIsNotEntityClass,
+                "contextual role is not an entity class",
+            ),
+            (
+                RoleContradictionError::InvalidRolePayload,
+                "invalid role-contradiction payload",
+            ),
+        ] {
+            assert_eq!(error.to_string(), message);
+        }
+    }
+}

crates/role_contradiction/src/lib.rs

@@ -0,0 +1,24 @@
+#![forbid(unsafe_code)]
+#![deny(missing_docs)]
+#![allow(clippy::cast_precision_loss)]
+//! Customer and competitor cannot occupy the same group at once.
+//!
+//! Customer, partner, and competitor are time-varying roles, not permanent
+//! entity classes. A customer/competitor pair in one group fails closed
+//! (ADR 0003).
+
+mod error;
+mod role;
+
+/// Fail-closed role-contradiction errors.
+pub use error::RoleContradictionError;
+/// Fraction of recovered contextual roles that match known truth.
+pub use role::identity_recovery_rate;
+/// Refuse a contradictory customer/competitor pair in one group.
+pub use role::refuse_contradictory_roles;
+/// Refuse to treat a contextual role as a permanent entity class.
+pub use role::refuse_role_as_entity_class;
+/// Return whether two roles contradict in the same group.
+pub use role::roles_contradict;
+/// Closed vocabulary of commercial roles that can change over time.
+pub use role::ContextualRole;

crates/role_contradiction/src/role.rs

@@ -0,0 +1,177 @@
+//! Contextual commercial roles that are not permanent entity classes.
+
+use crate::RoleContradictionError;
+
+/// Closed vocabulary of commercial roles that can change over time.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ContextualRole {
+    /// Customer role in one commercial context.
+    Customer,
+    /// Partner role in one commercial context.
+    Partner,
+    /// Competitor role in one commercial context.
+    Competitor,
+}
+
+impl ContextualRole {
+    /// Return the stable wire role name.
+    #[must_use]
+    pub const fn wire_name(self) -> &'static str {
+        match self {
+            Self::Customer => "customer",
+            Self::Partner => "partner",
+            Self::Competitor => "competitor",
+        }
+    }
+
+    /// Parse a stable wire role name.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`RoleContradictionError::InvalidRolePayload`] for unrecognized
+    /// names.
+    pub fn from_wire_name(name: &str) -> Result<Self, RoleContradictionError> {
+        match name {
+            "customer" => Ok(Self::Customer),
+            "partner" => Ok(Self::Partner),
+            "competitor" => Ok(Self::Competitor),
+            _ => Err(RoleContradictionError::InvalidRolePayload),
+        }
+    }
+}
+
+/// Return whether two roles contradict in the same group.
+///
+/// Customer and competitor cannot occupy the same group. Partner may coexist
+/// with either role (coopetition or a customer-partner) without rewriting
+/// entity identity.
+#[must_use]
+pub const fn roles_contradict(left: ContextualRole, right: ContextualRole) -> bool {
+    matches!(
+        (left, right),
+        (ContextualRole::Customer, ContextualRole::Competitor)
+            | (ContextualRole::Competitor, ContextualRole::Customer)
+    )
+}
+
+/// Refuse a contradictory customer/competitor pair in one group.
+///
+/// # Errors
+///
+/// Returns [`RoleContradictionError::CustomerCompetitorOverlap`] when the pair
+/// is customer and competitor. Compatible pairs succeed.
+pub fn refuse_contradictory_roles(
+    left: ContextualRole,
+    right: ContextualRole,
+) -> Result<(), RoleContradictionError> {
+    if roles_contradict(left, right) {
+        return Err(RoleContradictionError::CustomerCompetitorOverlap);
+    }
+    Ok(())
+}
+
+/// Refuse to treat a contextual role as a permanent entity class.
+///
+/// # Errors
+///
+/// Always returns [`RoleContradictionError::RoleIsNotEntityClass`].
+pub fn refuse_role_as_entity_class(_role: ContextualRole) -> Result<(), RoleContradictionError> {
+    Err(RoleContradictionError::RoleIsNotEntityClass)
+}
+
+/// Fraction of recovered contextual roles that match known truth.
+///
+/// # Errors
+///
+/// Returns [`RoleContradictionError::InvalidRolePayload`] when either slice is
+/// empty or the lengths differ.
+pub fn identity_recovery_rate(
+    truth: &[ContextualRole],
+    decided: &[ContextualRole],
+) -> Result<f64, RoleContradictionError> {
+    if truth.is_empty() || truth.len() != decided.len() {
+        return Err(RoleContradictionError::InvalidRolePayload);
+    }
+    let mut matches = 0_u32;
+    for (truth_role, decided_role) in truth.iter().zip(decided) {
+        if truth_role == decided_role {
+            matches += 1;
+        }
+    }
+    Ok(f64::from(matches) / truth.len() as f64)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{
+        identity_recovery_rate, refuse_contradictory_roles, refuse_role_as_entity_class,
+        roles_contradict, ContextualRole,
+    };
+    use crate::RoleContradictionError;
+
+    #[test]
+    fn local_branches_cover_pairs_payloads_and_wire_names() {
+        assert!(roles_contradict(
+            ContextualRole::Customer,
+            ContextualRole::Competitor
+        ));
+        assert!(roles_contradict(
+            ContextualRole::Competitor,
+            ContextualRole::Customer
+        ));
+        assert!(!roles_contradict(
+            ContextualRole::Customer,
+            ContextualRole::Partner
+        ));
+        assert!(!roles_contradict(
+            ContextualRole::Partner,
+            ContextualRole::Competitor
+        ));
+        assert!(!roles_contradict(
+            ContextualRole::Customer,
+            ContextualRole::Customer
+        ));
+        assert_eq!(
+            refuse_contradictory_roles(ContextualRole::Customer, ContextualRole::Competitor),
+            Err(RoleContradictionError::CustomerCompetitorOverlap)
+        );
+        assert_eq!(
+            refuse_contradictory_roles(ContextualRole::Competitor, ContextualRole::Customer),
+            Err(RoleContradictionError::CustomerCompetitorOverlap)
+        );
+        refuse_contradictory_roles(ContextualRole::Customer, ContextualRole::Partner)
+            .expect("compatible");
+        refuse_contradictory_roles(ContextualRole::Partner, ContextualRole::Competitor)
+            .expect("coopetition");
+        for role in [
+            ContextualRole::Customer,
+            ContextualRole::Partner,
+            ContextualRole::Competitor,
+        ] {
+            assert_eq!(
+                ContextualRole::from_wire_name(role.wire_name()).expect("round-trip"),
+                role
+            );
+            assert_eq!(
+                refuse_role_as_entity_class(role),
+                Err(RoleContradictionError::RoleIsNotEntityClass)
+            );
+        }
+        assert_eq!(
+            ContextualRole::from_wire_name("organization"),
+            Err(RoleContradictionError::InvalidRolePayload)
+        );
+        let matched =
+            identity_recovery_rate(&[ContextualRole::Customer], &[ContextualRole::Customer])
+                .expect("rate");
+        assert!((matched - 1.0).abs() < f64::EPSILON);
+        assert_eq!(
+            identity_recovery_rate(&[], &[]),
+            Err(RoleContradictionError::InvalidRolePayload)
+        );
+        assert_eq!(
+            identity_recovery_rate(&[ContextualRole::Customer], &[]),
+            Err(RoleContradictionError::InvalidRolePayload)
+        );
+    }
+}

crates/role_contradiction/tests/crate_contract.rs

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