Skip to main content

qualia_core_db/container_10d/
axis_role.rs

1//! Normative axis-role taxonomy for the `.10d` container header.
2//!
3//! Each of the ten tensor axes `[q, v, w, x, y, z, t, alpha, mu, sigma]` is
4//! declared in the header with one of the roles below. The taxonomy is the
5//! prerequisite for honest queryability: a `COORDINATE` participates in
6//! distance, a `SELECTOR` is excluded from every distance sum, and a `CARRIER`
7//! is the in-band provenance lane. `mu` carries a dual role (it is both a
8//! measured coordinate and the provenance carrier) and so gets its own variant
9//! `CoordinateCarrier`.
10//!
11//! **Status: PROPOSED, not yet frozen.** Timothy Charles Holborn confirmed the
12//! Option A assignment on 2026-07-04 as the baseline to encode, but the
13//! taxonomy is not normatively frozen in the `.10d` v1 spec until the P0.7
14//! conformance vectors land. The parser in [`crate::container_10d::header`]
15//! accepts any non-`Undefined` assignment today; a future task can tighten it
16//! to reject deviations from the frozen table once blessed.
17//!
18//! **t vs μ Reconciliation (T67, resolved 2026-08-19):**
19//!
20//! The earlier disagreement between this file and
21//! `crates/qualia-core-db/src/tensor/mod.rs` has been reconciled:
22//!
23//! - **`t`** = **Coordinate Time** — the 4th dimension of spacetime. It is
24//!   a `Coordinate` axis that participates in distance queries alongside
25//!   `x`, `y`, `z`, `α`, `σ`. It is NOT the provenance carrier. The
26//!   earlier "Provenance Ledger" label on `t` in `tensor/mod.rs` was
27//!   incorrect and has been corrected.
28//!
29//! - **`μ`** = **Provenance Weight / Carrier** — epistemic metadata lane.
30//!   It is the `CoordinateCarrier`: a dual-role axis that is both a
31//!   measured coordinate AND the in-band provenance carrier. This is
32//!   distinct from `t` (coordinate time). The provenance/consent lane
33//!   is `μ`, not `t`.
34//!
35//! - These are different concepts that happen to both be associated with
36//!   the 10th lane position. The 10D tensor has lanes for pose/query;
37//!   the 10D epistemic manifold has lanes for attention/epistemic geometry.
38//!
39//! Cross-reference: T14 (name the two tens) and T15 (resolve t vs μ).
40//!
41//! Reference: `docs/plans/native-computational-geometry.md` §4.1, and the
42//! execution plan's ⚑ "Axis-role taxonomy sign-off" curation datum.
43
44/// Canonical axis order — matches the `Tensor10D` field order exactly so a
45/// `Tensor10D` can be reinterpreted as ten `f32` lanes in this order without
46/// re-shuffling. Index `i` here is index `i` into `axis_roles` in the header
47/// and into the `folded_axes` bitmask of [`super::metric_check`].
48///
49/// The three spectral/epistemic axes use their normative Greek letters (`α`,
50/// `μ`, `σ`) — the vocabulary the `.10d` spec and the AGENTS.md bit layout
51/// define — not ASCII substitutes. The `Tensor10D` Rust struct fields are
52/// named `alpha`/`mu`/`sigma` (Rust identifier convention), but the normative
53/// axis names in the header, error messages, and this table are `α`/`μ`/`σ`.
54pub const AXIS_ORDER: [&str; 10] = ["q", "v", "w", "x", "y", "z", "t", "α", "μ", "σ"];
55
56/// Axis indices for the seven COORDINATE lanes (the ones that may participate
57/// in distance). `μ` is included here because it is a coordinate in addition
58/// to being the carrier.
59pub const COORDINATE_AXES: [usize; 7] = [3, 4, 5, 6, 7, 8, 9]; // x,y,z,t,α,μ,σ
60
61/// Axis indices for the three SELECTOR lanes (excluded from every distance sum).
62pub const SELECTOR_AXES: [usize; 3] = [0, 1, 2]; // q,v,w
63
64/// Index of `μ` — the dual-role coordinate + provenance carrier.
65pub const MU_AXIS: usize = 8;
66
67/// The role a single tensor axis plays in the `.10d` distance/query model.
68///
69/// Encoded as a `u8` in the header's `axis_roles[10]` array. `Undefined` is the
70/// sentinel the parser rejects — a header with any axis left undefined fails
71/// closed (the "missing-or-undefined axis role" acceptance gate).
72#[repr(u8)]
73#[derive(Debug, Clone, Copy, PartialEq, Eq)]
74pub enum AxisRole {
75    /// Sentinel for "no role assigned". The parser rejects any header carrying
76    /// this value — every axis must declare a concrete role.
77    Undefined = 0,
78    /// Excluded from every distance sum. `q`, `v`, `w`.
79    Selector = 1,
80    /// Participates in distance. `x`, `y`, `z`, `t`, `α`, `σ`.
81    Coordinate = 2,
82    /// In-band provenance lane only (not a coordinate). Reserved for a future
83    /// taxonomy where `μ` is carrier-only; not used by the proposed table.
84    Carrier = 3,
85    /// Dual-role: a `COORDINATE` that is also the in-band provenance `CARRIER`.
86    /// This is `μ`'s role under the proposed Option A taxonomy — it preserves
87    /// the foundational promise that provenance/consent can exert geometric
88    /// proximity or weight during queries.
89    CoordinateCarrier = 4,
90}
91
92impl AxisRole {
93    /// True if this role participates in distance (pure coordinate or the
94    /// dual-role coordinate+carrier).
95    #[inline]
96    pub const fn is_coordinate(self) -> bool {
97        matches!(self, AxisRole::Coordinate | AxisRole::CoordinateCarrier)
98    }
99
100    /// True if this role carries the provenance lane.
101    #[inline]
102    pub const fn is_carrier(self) -> bool {
103        matches!(self, AxisRole::Carrier | AxisRole::CoordinateCarrier)
104    }
105
106    /// Decode a raw `u8` back to an `AxisRole`, or `None` if the value is not a
107    /// defined variant. Used by the parser.
108    #[inline]
109    pub const fn from_u8(raw: u8) -> Option<AxisRole> {
110        match raw {
111            0 => Some(AxisRole::Undefined),
112            1 => Some(AxisRole::Selector),
113            2 => Some(AxisRole::Coordinate),
114            3 => Some(AxisRole::Carrier),
115            4 => Some(AxisRole::CoordinateCarrier),
116            _ => None,
117        }
118    }
119}
120
121/// The proposed (not-yet-frozen) normative axis-role table, indexed by
122/// `AXIS_ORDER`. This is the Option A assignment Timothy confirmed on
123/// 2026-07-04:
124///
125/// - `q, v, w` → `Selector`
126/// - `x, y, z, t, α, σ` → `Coordinate`
127/// - `μ` → `CoordinateCarrier` (dual-role: coordinate + provenance carrier)
128///
129/// The header's `axis_roles` field is initialised from this table by
130/// [`super::header::Container10dHeader::proposed`].
131pub const PROPOSED_AXIS_ROLES: [AxisRole; 10] = [
132    AxisRole::Selector,          // q
133    AxisRole::Selector,          // v
134    AxisRole::Selector,          // w
135    AxisRole::Coordinate,        // x
136    AxisRole::Coordinate,        // y
137    AxisRole::Coordinate,        // z
138    AxisRole::Coordinate,        // t
139    AxisRole::Coordinate,        // α
140    AxisRole::CoordinateCarrier, // μ
141    AxisRole::Coordinate,        // σ
142];
143
144#[cfg(test)]
145mod tests {
146    use super::*;
147
148    #[test]
149    fn proposed_table_matches_option_a_confirmation() {
150        // q,v,w are selectors
151        for &i in &SELECTOR_AXES {
152            assert_eq!(
153                PROPOSED_AXIS_ROLES[i],
154                AxisRole::Selector,
155                "axis {} should be Selector",
156                AXIS_ORDER[i]
157            );
158        }
159        // x,y,z,t,α,σ are pure coordinates
160        for &i in &[3usize, 4, 5, 6, 7, 9] {
161            assert_eq!(
162                PROPOSED_AXIS_ROLES[i],
163                AxisRole::Coordinate,
164                "axis {} should be Coordinate",
165                AXIS_ORDER[i]
166            );
167        }
168        // μ is the dual-role coordinate+carrier
169        assert_eq!(PROPOSED_AXIS_ROLES[MU_AXIS], AxisRole::CoordinateCarrier);
170        assert!(PROPOSED_AXIS_ROLES[MU_AXIS].is_coordinate());
171        assert!(PROPOSED_AXIS_ROLES[MU_AXIS].is_carrier());
172    }
173
174    #[test]
175    fn axis_role_round_trips_through_u8() {
176        for raw in 0u8..=4 {
177            let role = AxisRole::from_u8(raw).expect("0..=4 are defined");
178            assert_eq!(role as u8, raw);
179        }
180        assert!(AxisRole::from_u8(5).is_none());
181        assert!(AxisRole::from_u8(255).is_none());
182    }
183
184    #[test]
185    fn coordinate_axes_cover_seven_lanes_including_mu() {
186        assert_eq!(COORDINATE_AXES.len(), 7);
187        assert!(
188            COORDINATE_AXES.contains(&MU_AXIS),
189            "mu is a coordinate under Option A"
190        );
191    }
192
193    #[test]
194    fn t67_reconciled_comment_present() {
195        // T67: verify the reconciled comment block is present in this file.
196        let source = include_str!("axis_role.rs");
197        assert!(
198            source.contains("t vs μ Reconciliation"),
199            "missing reconciliation header"
200        );
201        assert!(
202            source.contains("Coordinate Time"),
203            "missing t = Coordinate Time"
204        );
205        assert!(
206            source.contains("Provenance Weight / Carrier"),
207            "missing μ = provenance carrier"
208        );
209        assert!(source.contains("T67"), "missing T67 cross-reference");
210    }
211
212    #[test]
213    fn t67_tensor10d_comments_reconciled() {
214        // T67: verify the Tensor10D field comments in tensor/mod.rs are reconciled.
215        let source = include_str!("../tensor/mod.rs");
216        assert!(
217            source.contains("Coordinate Time"),
218            "tensor/mod.rs t field not reconciled"
219        );
220        assert!(
221            source.contains("Provenance Weight / Carrier"),
222            "tensor/mod.rs mu field not reconciled"
223        );
224        assert!(
225            source.contains("T67"),
226            "tensor/mod.rs missing T67 cross-reference"
227        );
228        // The t field should be labeled "Coordinate Time" in its doc comment.
229        let t_idx = source.find("pub t: f32").unwrap();
230        let before_t = &source[..t_idx];
231        assert!(
232            before_t.contains("Coordinate Time"),
233            "tensor/mod.rs t field doc should say 'Coordinate Time'"
234        );
235    }
236}