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}