feat(membership): refuse customer-competitor overlap

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 |
+| `role_contradiction` | customer and competitor cannot occupy the same group |
 
 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
 
+- `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).
 - `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).
 - `persistence_postgres` concurrent document-write stress: atomic revise `DO` block that requires exactly one open `system_to` close, SQLSTATE mapping onto `ConcurrentWriteConflict` / `DuplicateDocumentRecord`, and live multi-session insert/revise/append-only proofs. No new migration number.
 - `tepp_api` naruon HTTP interchange: versioned `https` POST contracts for analysis-run create and modular export authorization that refuse table-access URLs, review/Copilot credential headers, reserved standard-header redefinition, principal-only export idempotency keys, and lexical inference claims (ADR 0011).

Cargo.toml

@@ -11,6 +11,7 @@ members = [
     "crates/tepp_simulation",
     "crates/validation_core",
     "crates/tepp_api",
+    "crates/role_contradiction",
 ]
 default-members = [
     "crates/evidence_core",
@@ -23,6 +24,7 @@ default-members = [
     "crates/tepp_simulation",
     "crates/validation_core",
     "crates/tepp_api",
+    "crates/role_contradiction",
 ]
 
 [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/role_contradiction
 ```
 
 ## Local verification

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");
+}