feat(membership): refuse location as entity identity or language

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 |
+| `location_membership` | location is not entity identity and not a language channel |
 | `prompt_source` | prompt boilerplate is not unique latent content and not stopword deletion |
 | `corpus_background` | corpus-background wording is not unique latent content and not stopword deletion |
 | `modality_source` | non-lexical modality is not unique latent content and not stopword deletion |

CHANGELOG.md

@@ -6,6 +6,7 @@ All notable changes to TEPP are documented here. The format follows Keep a Chang
 
 ### Added
 
+- `location_membership` identity gate: geographic and market assignments are time-varying memberships, not permanent entity identity and not language channels; recovered location kinds match known truth at a higher computed rate than collapsing every assignment to entity identity (ADR 0003).
 - `prompt_source` identity gate: instruction and prompt boilerplate is not unique latent content and is not erased by a stopword list; `identity_recovery_rate` reports exact kind matches, with a contract test comparing correct recovery with an all-unique collapse on a mixed known-truth fixture (ADR 0004/0012).
 - `corpus_background` identity gate: corpus-level background wording is not unique latent content and is not erased by a stopword list; recovered background kinds match known truth at a higher computed rate than collapsing every token to unique content (ADR 0004/0012).
 - `modality_source` identity gate: non-lexical modality is not unique latent content and is not erased by a stopword list; recovered modality kinds match known truth at a higher computed rate than collapsing every token to unique content (ADR 0004/0012).

Cargo.toml

@@ -11,6 +11,7 @@ members = [
     "crates/tepp_simulation",
     "crates/validation_core",
     "crates/tepp_api",
+    "crates/location_membership",
     "crates/prompt_source",
     "crates/corpus_background",
     "crates/modality_source",
@@ -60,6 +61,7 @@ default-members = [
     "crates/tepp_simulation",
     "crates/validation_core",
     "crates/tepp_api",
+    "crates/location_membership",
     "crates/prompt_source",
     "crates/corpus_background",
     "crates/modality_source",

crates/location_membership/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "location_membership"
+description = "Location is a time-varying market membership, not entity identity or language."
+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/location_membership/src/error.rs

@@ -0,0 +1,55 @@
+//! Fail-closed location-membership errors.
+
+use std::fmt;
+
+/// A fail-closed location-membership error.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[non_exhaustive]
+pub enum LocationMembershipError {
+    /// Location membership was treated as permanent entity identity.
+    LocationIsNotEntityIdentity,
+    /// Location membership was treated as a language channel.
+    LocationIsNotLanguageChannel,
+    /// A recovery slice was empty or length-mismatched.
+    InvalidLocationPayload,
+}
+
+impl fmt::Display for LocationMembershipError {
+    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
+        let message = match self {
+            Self::LocationIsNotEntityIdentity => {
+                "location membership is not permanent entity identity"
+            }
+            Self::LocationIsNotLanguageChannel => "location membership is not a language channel",
+            Self::InvalidLocationPayload => "invalid location-membership payload",
+        };
+        formatter.write_str(message)
+    }
+}
+
+impl std::error::Error for LocationMembershipError {}
+
+#[cfg(test)]
+mod tests {
+    use super::LocationMembershipError;
+
+    #[test]
+    fn error_messages_are_stable() {
+        for (error, message) in [
+            (
+                LocationMembershipError::LocationIsNotEntityIdentity,
+                "location membership is not permanent entity identity",
+            ),
+            (
+                LocationMembershipError::LocationIsNotLanguageChannel,
+                "location membership is not a language channel",
+            ),
+            (
+                LocationMembershipError::InvalidLocationPayload,
+                "invalid location-membership payload",
+            ),
+        ] {
+            assert_eq!(error.to_string(), message);
+        }
+    }
+}

crates/location_membership/src/kind.rs

@@ -0,0 +1,143 @@
+//! Location membership versus entity identity and language.
+
+use crate::LocationMembershipError;
+
+/// Closed vocabulary of location-related membership treatments.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum LocationKind {
+    /// Time-varying market or place membership.
+    Location,
+    /// Permanent entity identity under role assignments.
+    EntityIdentity,
+    /// Language community or locale channel.
+    LanguageChannel,
+}
+
+impl LocationKind {
+    /// Return the stable wire kind name.
+    #[must_use]
+    pub const fn wire_name(self) -> &'static str {
+        match self {
+            Self::Location => "location",
+            Self::EntityIdentity => "entity_identity",
+            Self::LanguageChannel => "language_channel",
+        }
+    }
+
+    /// Parse a stable wire kind name.
+    ///
+    /// # Errors
+    ///
+    /// Returns [`LocationMembershipError::InvalidLocationPayload`] for
+    /// unrecognized names.
+    pub fn from_wire_name(name: &str) -> Result<Self, LocationMembershipError> {
+        match name {
+            "location" => Ok(Self::Location),
+            "entity_identity" => Ok(Self::EntityIdentity),
+            "language_channel" => Ok(Self::LanguageChannel),
+            _ => Err(LocationMembershipError::InvalidLocationPayload),
+        }
+    }
+}
+
+/// Refuse to treat location membership as permanent entity identity.
+///
+/// # Errors
+///
+/// Returns [`LocationMembershipError::LocationIsNotEntityIdentity`] when
+/// `kind` is [`LocationKind::Location`].
+pub fn refuse_location_as_entity_identity(
+    kind: LocationKind,
+) -> Result<(), LocationMembershipError> {
+    match kind {
+        LocationKind::Location => Err(LocationMembershipError::LocationIsNotEntityIdentity),
+        LocationKind::EntityIdentity | LocationKind::LanguageChannel => Ok(()),
+    }
+}
+
+/// Refuse to treat location membership as a language channel.
+///
+/// # Errors
+///
+/// Returns [`LocationMembershipError::LocationIsNotLanguageChannel`] when
+/// `kind` is [`LocationKind::Location`].
+pub fn refuse_location_as_language_channel(
+    kind: LocationKind,
+) -> Result<(), LocationMembershipError> {
+    match kind {
+        LocationKind::Location => Err(LocationMembershipError::LocationIsNotLanguageChannel),
+        LocationKind::EntityIdentity | LocationKind::LanguageChannel => Ok(()),
+    }
+}
+
+/// Fraction of recovered location kinds that match known truth.
+///
+/// # Errors
+///
+/// Returns [`LocationMembershipError::InvalidLocationPayload`] when either
+/// slice is empty or the lengths differ.
+pub fn identity_recovery_rate(
+    truth: &[LocationKind],
+    decided: &[LocationKind],
+) -> Result<f64, LocationMembershipError> {
+    if truth.is_empty() || truth.len() != decided.len() {
+        return Err(LocationMembershipError::InvalidLocationPayload);
+    }
+    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::{
+        LocationKind, identity_recovery_rate, refuse_location_as_entity_identity,
+        refuse_location_as_language_channel,
+    };
+    use crate::LocationMembershipError;
+
+    #[test]
+    fn local_branches_cover_kinds_payloads_and_wire_names() {
+        assert_eq!(
+            refuse_location_as_entity_identity(LocationKind::Location),
+            Err(LocationMembershipError::LocationIsNotEntityIdentity)
+        );
+        assert_eq!(
+            refuse_location_as_language_channel(LocationKind::Location),
+            Err(LocationMembershipError::LocationIsNotLanguageChannel)
+        );
+        refuse_location_as_entity_identity(LocationKind::EntityIdentity).expect("entity");
+        refuse_location_as_entity_identity(LocationKind::LanguageChannel).expect("language");
+        refuse_location_as_language_channel(LocationKind::EntityIdentity).expect("entity");
+        refuse_location_as_language_channel(LocationKind::LanguageChannel).expect("language");
+        for kind in [
+            LocationKind::Location,
+            LocationKind::EntityIdentity,
+            LocationKind::LanguageChannel,
+        ] {
+            assert_eq!(
+                LocationKind::from_wire_name(kind.wire_name()).expect("round-trip"),
+                kind
+            );
+        }
+        assert_eq!(
+            LocationKind::from_wire_name("project"),
+            Err(LocationMembershipError::InvalidLocationPayload)
+        );
+        let matched = identity_recovery_rate(&[LocationKind::Location], &[LocationKind::Location])
+            .expect("rate");
+        assert!((matched - 1.0).abs() < f64::EPSILON);
+        assert_eq!(
+            identity_recovery_rate(&[], &[]),
+            Err(LocationMembershipError::InvalidLocationPayload)
+        );
+        assert_eq!(
+            identity_recovery_rate(&[LocationKind::Location], &[]),
+            Err(LocationMembershipError::InvalidLocationPayload)
+        );
+    }
+}

crates/location_membership/src/lib.rs

@@ -0,0 +1,22 @@
+#![forbid(unsafe_code)]
+#![deny(missing_docs)]
+#![allow(clippy::cast_precision_loss)]
+//! Location is a time-varying market membership, not entity identity.
+//!
+//! Geographic and market assignments stay explicit multiple-membership
+//! structure. They are not permanent entity classes and are not language
+//! channels (ADR 0003).
+
+mod error;
+mod kind;
+
+/// Fail-closed location-membership errors.
+pub use error::LocationMembershipError;
+/// Closed vocabulary of location-related membership treatments.
+pub use kind::LocationKind;
+/// Fraction of recovered location kinds that match known truth.
+pub use kind::identity_recovery_rate;
+/// Refuse to treat location membership as permanent entity identity.
+pub use kind::refuse_location_as_entity_identity;
+/// Refuse to treat location membership as a language channel.
+pub use kind::refuse_location_as_language_channel;

crates/location_membership/tests/crate_contract.rs

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

crates/location_membership/tests/location_membership_contract.rs

@@ -0,0 +1,67 @@
+//! Location is not entity identity and not a language channel.
+
+use location_membership::{
+    LocationKind, LocationMembershipError, identity_recovery_rate,
+    refuse_location_as_entity_identity, refuse_location_as_language_channel,
+};
+
+#[test]
+fn location_cannot_become_entity_identity_or_language() {
+    assert_eq!(
+        refuse_location_as_entity_identity(LocationKind::Location),
+        Err(LocationMembershipError::LocationIsNotEntityIdentity)
+    );
+    assert_eq!(
+        refuse_location_as_language_channel(LocationKind::Location),
+        Err(LocationMembershipError::LocationIsNotLanguageChannel)
+    );
+    refuse_location_as_entity_identity(LocationKind::EntityIdentity).expect("entity");
+    refuse_location_as_language_channel(LocationKind::LanguageChannel).expect("language");
+}
+
+#[test]
+fn recovered_kinds_match_known_truth_better_than_an_entity_collapse() {
+    let truth = [
+        LocationKind::Location,
+        LocationKind::EntityIdentity,
+        LocationKind::LanguageChannel,
+    ];
+    let recovered = truth;
+    let collapsed = [
+        LocationKind::EntityIdentity,
+        LocationKind::EntityIdentity,
+        LocationKind::EntityIdentity,
+    ];
+    let recovered_rate = identity_recovery_rate(&truth, &recovered).expect("recovered");
+    let collapsed_rate = identity_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!(
+        identity_recovery_rate(&[], &[]),
+        Err(LocationMembershipError::InvalidLocationPayload)
+    );
+    assert_eq!(
+        identity_recovery_rate(&[LocationKind::Location], &[]),
+        Err(LocationMembershipError::InvalidLocationPayload)
+    );
+    assert_eq!(
+        identity_recovery_rate(
+            &[LocationKind::Location, LocationKind::EntityIdentity],
+            &[LocationKind::Location]
+        ),
+        Err(LocationMembershipError::InvalidLocationPayload)
+    );
+}

docs/TRACEABILITY.md

@@ -14,7 +14,7 @@ The full APA 7th standards/literature register remains `docs/research/standards-
 | 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; `copy_identity` copy-versus-source identity on the active PR | partial |
 | 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; `inferred_status` inferred-versus-observed identity on the active PR; multilevel estimators remaining | partial |
+| time-varying cross-classified multiple membership | PRD; ADR 0003 | `membership_core` network on protected main; `location_membership` location-versus-entity/language identity on the active PR; 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 |
 | PostgreSQL bitemporal/lineage persistence | ADR 0013; Architecture/ERD | `persistence_postgres` on protected main as before; `revision_order` later-revision system-time gate on the active PR; remaining physical ERD constraints | partial |

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:** partial — membership network and event mention/instance separation implemented-main; location-versus-entity/language identity in `location_membership` on the active PR; typed relation graph with forward-only transitions active-PR; multilevel estimators and persistence remain accepted-target  
 **Implementation maturity:** partial — membership network and event mention/instance separation implemented-main; copy-versus-source identity in `copy_identity` on the active PR; typed relation graph with forward-only transitions active-PR; multilevel estimators and persistence remain accepted-target  
 **Implementation maturity:** partial — membership network and event mention/instance separation implemented-main; summary-versus-source identity in `summarizes_edge` on the active PR; typed relation graph with forward-only transitions active-PR; multilevel estimators and persistence remain accepted-target  
 **Implementation maturity:** partial — membership network and event mention/instance separation implemented-main; typed relation graph with forward-only transitions implemented-main; IPO event-time order in `outcome_order` on the active PR; multilevel estimators and persistence remain accepted-target