diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 5060d3cd..70ce2863 100644 --- a/ARCHITECTURE.md +++ b/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 | diff --git a/CHANGELOG.md b/CHANGELOG.md index d663bf79..ae79cdec 100644 --- a/CHANGELOG.md +++ b/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). diff --git a/Cargo.lock b/Cargo.lock index 656738e2..71115706 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -870,6 +870,10 @@ version = "0.8.2" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "92daf443525c4cce67b150400bc2316076100ce0b3686209eb8cf3c31612e6f0" +[[package]] +name = "location_membership" +version = "0.1.0" + [[package]] name = "lock_api" version = "0.4.14" diff --git a/Cargo.toml b/Cargo.toml index 02c29288..ad4ed3ac 100644 --- a/Cargo.toml +++ b/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", diff --git a/crates/location_membership/Cargo.toml b/crates/location_membership/Cargo.toml new file mode 100644 index 00000000..dc2accc6 --- /dev/null +++ b/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 diff --git a/crates/location_membership/src/error.rs b/crates/location_membership/src/error.rs new file mode 100644 index 00000000..a5dd8d88 --- /dev/null +++ b/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); + } + } +} diff --git a/crates/location_membership/src/kind.rs b/crates/location_membership/src/kind.rs new file mode 100644 index 00000000..74f2a4e9 --- /dev/null +++ b/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 { + 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 { + 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) + ); + } +} diff --git a/crates/location_membership/src/lib.rs b/crates/location_membership/src/lib.rs new file mode 100644 index 00000000..0cd6ab48 --- /dev/null +++ b/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; diff --git a/crates/location_membership/tests/crate_contract.rs b/crates/location_membership/tests/crate_contract.rs new file mode 100644 index 00000000..6bb28db8 --- /dev/null +++ b/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"); +} diff --git a/crates/location_membership/tests/location_membership_contract.rs b/crates/location_membership/tests/location_membership_contract.rs new file mode 100644 index 00000000..81560054 --- /dev/null +++ b/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) + ); +} diff --git a/docs/TRACEABILITY.md b/docs/TRACEABILITY.md index b05bf311..41661e40 100644 --- a/docs/TRACEABILITY.md +++ b/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 | diff --git a/docs/adr/0003-relational-event-multiple-membership.md b/docs/adr/0003-relational-event-multiple-membership.md index 4501fa69..abb44063 100644 --- a/docs/adr/0003-relational-event-multiple-membership.md +++ b/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 diff --git a/docs/research/location-membership-identity.md b/docs/research/location-membership-identity.md new file mode 100644 index 00000000..0f1edf81 --- /dev/null +++ b/docs/research/location-membership-identity.md @@ -0,0 +1,37 @@ +# Location is not entity identity or language (doctoring) + +## Scope + +`location_membership` keeps geographic and market assignments as +time-varying multiple-membership structure. Location is not permanent +entity identity and is not a language channel. Recovery is the computed +share of recovered kinds that match known truth. + +This slice does not persist memberships, allocate migration `0008`, or +replace `membership_core`, `membership_target`, or `episode_membership`. + +## Authority + +### Normative TEPP contract + +- `docs/adr/0003-relational-event-multiple-membership.md` — authors, + departments, organizations, customers, partners, competitors, + projects, opportunity pools, templates, languages, locations, and + episodes form cross-classified, time-varying, multiple-membership + assignments. Location is a membership target, not an immutable entity + class. + +### Supporting literature + +Browne, Goldstein, and Rasbash (2001) treat classification units as +distinct membership structures. Jones (1991) models people and places +as separate levels; collapsing place into entity identity or language +destroys that cross-classification. + +Browne, W. J., Goldstein, H., & Rasbash, J. (2001). Multiple membership +multiple classification (MMMC) models. *Statistical Modelling, 1*(2), +103–124. https://doi.org/10.1177/1471082X0100100202 + +Jones, K. (1991). Specifying and estimating multi-level models for +geographical research. *Transactions of the Institute of British +Geographers, 16*(2), 148–160. https://doi.org/10.2307/622612 diff --git a/docs/research/multilevel-multiple-membership-measurement.md b/docs/research/multilevel-multiple-membership-measurement.md index 3b529b53..4a8c6ecd 100644 --- a/docs/research/multilevel-multiple-membership-measurement.md +++ b/docs/research/multilevel-multiple-membership-measurement.md @@ -2,7 +2,7 @@ ## Claim boundary -TEPP documents and events may simultaneously belong to authors, departments, customers, partners, competitors, projects, opportunity pools, templates, languages, and event episodes. Treating documents as independent atoms produces atomistic fallacy, overstates independent information and the effective sample size estimated under independence, and can leak related units across validation splits (ADR 0003; AGENTS.md §6). +TEPP documents and events may simultaneously belong to authors, departments, customers, partners, competitors, projects, opportunity pools, templates, languages, locations, and event episodes. Treating documents as independent atoms produces atomistic fallacy, overstates independent information and the effective sample size estimated under independence, and can leak related units across validation splits (ADR 0003; AGENTS.md §6). ## Implemented foundation diff --git a/docs/research/standards-and-literature.md b/docs/research/standards-and-literature.md index e6783f0a..776cd3d1 100644 --- a/docs/research/standards-and-literature.md +++ b/docs/research/standards-and-literature.md @@ -16,7 +16,11 @@ Fox, J.-P., & Glas, C. A. W. (2001). Bayesian estimation of a multilevel IRT mod Marsh, H. W., Morin, A. J. S., Parker, P. D., & Kaur, G. (2014). Exploratory structural equation modeling: An integration of the best features of exploratory and confirmatory factor analysis. *Annual Review of Clinical Psychology, 10*, 85–110. https://doi.org/10.1146/annurev-clinpsy-032813-153700 -TEPP applies these sources to construct definition, score interpretation, reliability, validity evidence, uncertainty, consequences, longitudinal invariance, ESEM cross-loadings, and DSEM. Topic outputs are treated as fallible indicators or components only after their construct role is evaluated. `psychometric_fit` recovers those cross-loadings and event-time lagged paths on a CPU `f64` OLS path; see `docs/research/esem-dsem-fit.md`. +Browne, W. J., Goldstein, H., & Rasbash, J. (2001). Multiple membership multiple classification (MMMC) models. *Statistical Modelling, 1*(2), 103–124. https://doi.org/10.1177/1471082X0100100202 + +Jones, K. (1991). Specifying and estimating multi-level models for geographical research. *Transactions of the Institute of British Geographers, 16*(2), 148–160. https://doi.org/10.2307/622612 + +TEPP applies these sources to construct definition, score interpretation, reliability, validity evidence, uncertainty, consequences, longitudinal invariance, ESEM cross-loadings, and DSEM. Topic outputs are treated as fallible indicators or components only after their construct role is evaluated. Location and market assignments remain multiple-membership classifications; they are not permanent entity identity and not language channels (Browne et al., 2001; Jones, 1991). ## Structural, correlated, dynamic, relational, and multilingual topic models diff --git a/scripts/check_workspace_contract.py b/scripts/check_workspace_contract.py index 1f7a7043..07a71efc 100644 --- a/scripts/check_workspace_contract.py +++ b/scripts/check_workspace_contract.py @@ -23,6 +23,7 @@ "tepp_simulation", "validation_core", "tepp_api", + "location_membership", "prompt_source", "corpus_background", "modality_source", diff --git a/tests/quality/test_check_docstrings.py b/tests/quality/test_check_docstrings.py index 8f86cbff..46cbb158 100644 --- a/tests/quality/test_check_docstrings.py +++ b/tests/quality/test_check_docstrings.py @@ -27,6 +27,7 @@ def test_live_repository_is_documented(self) -> None: sources = docstrings.rust_sources(REPOSITORY_ROOT) crate_roots = sorted(REPOSITORY_ROOT.glob("crates/*/src/lib.rs")) + self.assertEqual(len(crate_roots), 11) self.assertEqual(len(crate_roots), len(contract.EXPECTED_CRATES)) self.assertEqual(len(crate_roots), 11) self.assertEqual(len(crate_roots), len(contract.EXPECTED_CRATES))