Skip to main content

qualia_core_db/container_10d/
manifold_identity_v2.rs

1//! `.10d` v2 manifold identity and typed-field manifest codec.
2//!
3//! The `MID2` section is integrated with the v2 outer `.10d` section table and
4//! sits beside independently versioned mesh, node, topology, material, and
5//! field payloads. Existing v1 containers remain readable and are never
6//! rewritten unless a caller explicitly opts into the v2 section.
7//!
8//! The identity record keeps three concepts distinct:
9//!
10//! - `StableEntityId` is an opaque stored continuity handle. This codec does
11//!   not verify its issuer or global uniqueness and never derives it from content.
12//!   Qualified referent resolution belongs to native graph/authority mechanisms.
13//! - Tensor10D coordinates are explicit identity-bearing address/state under
14//!   the declared profile, domain, and coordinate convention. Their fixed
15//!   order is `[q, v, w, x, y, z, t, α, μ, σ]`, matching `Tensor10D`.
16//! - `IntegrityIndexDigest` is an optional external digest/index hint. It is
17//!   not an entity identifier, is not computed here, and is not used to resolve
18//!   identity.
19//!
20//! Field records are typed references into other sections of the enclosing
21//! container. Built-in field kinds include electromagnetic field (EMF) as one
22//! peer among scalar, vector, tensor, and spectral fields. Extension encoding
23//! and decoding both require an explicit allow-list; unknown kinds fail closed.
24//! The owning field schema validates kind-specific payload semantics after
25//! this envelope layer checks section identity and byte ranges.
26//! Encoding is little-endian, deterministic, caller-buffered, allocation-free,
27//! and requires field records in ascending stable `field_id` order.
28
29/// Exact axis order for the ten `coordinates` lanes in this section version.
30pub const MANIFOLD_IDENTITY_V2_AXIS_ORDER: [&str; 10] =
31    ["q", "v", "w", "x", "y", "z", "t", "α", "μ", "σ"];
32
33pub const MANIFOLD_IDENTITY_V2_MAGIC: [u8; 4] = *b"MID2";
34pub const MANIFOLD_IDENTITY_V2_VERSION: u16 = 2;
35pub const MANIFOLD_IDENTITY_V2_HEADER_SIZE: usize = 112;
36pub const MANIFOLD_IDENTITY_V2_FIELD_RECORD_SIZE: usize = 48;
37pub const MANIFOLD_IDENTITY_V2_MAX_FIELDS: usize = 256;
38pub const MANIFOLD_IDENTITY_V2_MAX_BYTES: usize = MANIFOLD_IDENTITY_V2_HEADER_SIZE
39    + MANIFOLD_IDENTITY_V2_MAX_FIELDS * MANIFOLD_IDENTITY_V2_FIELD_RECORD_SIZE;
40
41const FLAG_HAS_EXTERNAL_DIGEST: u8 = 1;
42
43pub const FIELD_KIND_SCALAR: u16 = 0x0001;
44pub const FIELD_KIND_VECTOR: u16 = 0x0002;
45pub const FIELD_KIND_TENSOR: u16 = 0x0003;
46pub const FIELD_KIND_SPECTRAL: u16 = 0x0004;
47/// Electromagnetic field data. This is a typed field kind, not a manifold or
48/// container format of its own.
49pub const FIELD_KIND_ELECTROMAGNETIC: u16 = 0x0100;
50/// Existing NRM1/FRM1 per-vertex surface frames, unitless FieldSidecar range.
51pub const FIELD_KIND_SURFACE_FRAMES: u16 = 0x0200;
52/// Existing MRP1 mixed-schema morph targets in a FieldSidecar range. unit_id=0:
53/// position deltas inherit mesh coordinates; normal/tangent deltas are unitless.
54pub const FIELD_KIND_MORPH_TARGETS: u16 = 0x0201;
55/// POET Geometry-Topology Complex (`GTOP`: `PoetGeometryHeader` + `M` `HarbouredGraphHeader`s).
56pub const FIELD_KIND_GEOMETRY_TOPOLOGY_COMPLEX: u16 = 0x0300;
57// Registry additions preserve MID2 layout. Older readers reject unsupported kinds
58// unless their explicit supported-extension allow-list admits these semantics.
59pub const BUILTIN_FIELD_KINDS: [u16; 8] = [
60    FIELD_KIND_SCALAR,
61    FIELD_KIND_VECTOR,
62    FIELD_KIND_TENSOR,
63    FIELD_KIND_SPECTRAL,
64    FIELD_KIND_ELECTROMAGNETIC,
65    FIELD_KIND_SURFACE_FRAMES,
66    FIELD_KIND_MORPH_TARGETS,
67    FIELD_KIND_GEOMETRY_TOPOLOGY_COMPLEX,
68];
69
70/// Canonical `(kind, name)` table for built-in MID2 field kinds.
71pub const BUILTIN_FIELD_KIND_NAMES: [(u16, &str); 8] = [
72    (FIELD_KIND_SCALAR, "scalar"),
73    (FIELD_KIND_VECTOR, "vector"),
74    (FIELD_KIND_TENSOR, "tensor"),
75    (FIELD_KIND_SPECTRAL, "spectral"),
76    (FIELD_KIND_ELECTROMAGNETIC, "electromagnetic"),
77    (FIELD_KIND_SURFACE_FRAMES, "surface_frames"),
78    (FIELD_KIND_MORPH_TARGETS, "morph_targets"),
79    (
80        FIELD_KIND_GEOMETRY_TOPOLOGY_COMPLEX,
81        "geometry_topology_complex",
82    ),
83];
84
85/// Opaque stored continuity identifier. Issuer and uniqueness are not verified
86/// by this codec. Its bytes are never interpreted as a digest.
87#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
88pub struct StableEntityId(pub [u8; 16]);
89
90/// Optional externally computed digest/index aid. It is kept in a distinct
91/// type and field so it cannot become the entity identity by codec convention.
92#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
93pub struct IntegrityIndexDigest(pub [u8; 16]);
94
95/// Manifold identity/profile declaration for one stable entity.
96#[derive(Debug, Clone, Copy, PartialEq)]
97pub struct ManifoldIdentityV2 {
98    pub entity_id: StableEntityId,
99    /// Stable profile registry identifier; not the entity identity.
100    pub profile_id: u64,
101    /// Declared manifold/domain registry identifier.
102    pub domain_id: u64,
103    /// Declared interpretation and unit convention registry identifier.
104    pub coordinate_convention_id: u64,
105    /// Values in [`MANIFOLD_IDENTITY_V2_AXIS_ORDER`].
106    pub coordinates: [f32; 10],
107    /// Optional digest supplied by the enclosing asset/index pipeline.
108    pub external_digest: Option<IntegrityIndexDigest>,
109}
110
111impl ManifoldIdentityV2 {
112    /// Compare stored handles only; equality does not establish universal
113    /// referent equivalence or issuer authority. Qualified resolution and
114    /// split/merge lineage remain graph/authority responsibilities.
115    pub fn resolves_same_entity(&self, other: &Self) -> bool {
116        self.entity_id == other.entity_id
117    }
118
119    /// Compare the declared manifold address/state independently of entity
120    /// continuity or digest. Coordinates use canonical numeric equality;
121    /// the codec normalizes either signed zero to positive zero.
122    pub fn has_same_manifold_address(&self, other: &Self) -> bool {
123        self.profile_id == other.profile_id
124            && self.domain_id == other.domain_id
125            && self.coordinate_convention_id == other.coordinate_convention_id
126            && self
127                .coordinates
128                .iter()
129                .zip(other.coordinates.iter())
130                .all(|(left, right)| left == right)
131    }
132}
133
134/// Typed reference to a payload in another section of the outer `.10d`
135/// envelope. A zero `payload_section_id` is allowed only for an empty
136/// declaration that has no attached sample payload yet.
137#[derive(Debug, Clone, Copy, PartialEq, Eq)]
138pub struct TypedFieldRecord {
139    /// Stable field declaration identifier, unique and ascending per manifest.
140    pub field_id: u64,
141    /// Built-in kind or an extension kind admitted by the decoder allow-list.
142    pub kind: u16,
143    /// Reserved for future field semantics; must be zero in v2.
144    pub flags: u16,
145    /// Unit/convention registry identifier; zero means unitless or unspecified.
146    pub unit_id: u64,
147    /// Section identifier in the outer `.10d` envelope.
148    pub payload_section_id: u32,
149    /// Byte range within the referenced section.
150    pub payload_offset: u64,
151    pub payload_length: u64,
152}
153
154impl Default for TypedFieldRecord {
155    fn default() -> Self {
156        Self {
157            field_id: 0,
158            kind: 0,
159            flags: 0,
160            unit_id: 0,
161            payload_section_id: 0,
162            payload_offset: 0,
163            payload_length: 0,
164        }
165    }
166}
167
168#[derive(Debug, Clone, Copy, PartialEq, Eq)]
169pub enum ManifestV2Error {
170    TooShort { got: usize, need: usize },
171    BadMagic,
172    UnsupportedVersion(u16),
173    BadHeaderSize(u16),
174    BadTotalLength { declared: u32, actual: usize },
175    TooManyFields { got: usize, max: usize },
176    CoordinateCount(u8),
177    UnknownFlags(u8),
178    NonZeroAbsentDigest,
179    ZeroEntityId,
180    ZeroDeclarationId { field: &'static str },
181    NonFiniteCoordinate { axis: usize },
182    NonCanonicalCoordinate { axis: usize },
183    OutputTooSmall { needed: usize, have: usize },
184    InvalidFieldId,
185    InvalidFieldKind,
186    UnsupportedFieldKind(u16),
187    InvalidFieldFlags(u16),
188    FieldsNotStrictlySorted,
189    NonZeroReserved { field_index: usize },
190    InvalidPayloadReference { field_index: usize },
191    PayloadRangeOverflow { field_index: usize },
192    LengthOverflow,
193}
194
195/// Encode built-in field kinds into a caller-owned buffer. Extension kinds
196/// require the explicit allow-list form so successful writes are readable by
197/// the same registered schema.
198pub fn encode_manifold_identity_v2(
199    identity: &ManifoldIdentityV2,
200    fields: &[TypedFieldRecord],
201    out: &mut [u8],
202) -> Result<usize, ManifestV2Error> {
203    encode_manifold_identity_v2_with_extensions(identity, fields, &[], out)
204}
205
206/// Encode with an explicit extension-kind allow-list. Inputs must already use
207/// canonical ascending `field_id` order; sorting is intentionally not
208/// performed because this boundary must not allocate or rewrite caller data.
209/// Validation and size checks finish before output is modified.
210pub fn encode_manifold_identity_v2_with_extensions(
211    identity: &ManifoldIdentityV2,
212    fields: &[TypedFieldRecord],
213    supported_extension_kinds: &[u16],
214    out: &mut [u8],
215) -> Result<usize, ManifestV2Error> {
216    validate_identity(identity)?;
217    let needed = encoded_len(fields.len())?;
218    if out.len() < needed {
219        return Err(ManifestV2Error::OutputTooSmall {
220            needed,
221            have: out.len(),
222        });
223    }
224    validate_fields(fields, supported_extension_kinds)?;
225
226    let mut header = [0u8; MANIFOLD_IDENTITY_V2_HEADER_SIZE];
227    header[0..4].copy_from_slice(&MANIFOLD_IDENTITY_V2_MAGIC);
228    put_u16(&mut header, 4, MANIFOLD_IDENTITY_V2_VERSION);
229    put_u16(&mut header, 6, MANIFOLD_IDENTITY_V2_HEADER_SIZE as u16);
230    put_u32(&mut header, 8, needed as u32);
231    put_u16(&mut header, 12, fields.len() as u16);
232    header[14] = MANIFOLD_IDENTITY_V2_AXIS_ORDER.len() as u8;
233    if let Some(digest) = identity.external_digest {
234        header[15] = FLAG_HAS_EXTERNAL_DIGEST;
235        header[96..112].copy_from_slice(&digest.0);
236    }
237    header[16..32].copy_from_slice(&identity.entity_id.0);
238    put_u64(&mut header, 32, identity.profile_id);
239    put_u64(&mut header, 40, identity.domain_id);
240    put_u64(&mut header, 48, identity.coordinate_convention_id);
241    for (index, value) in identity.coordinates.iter().enumerate() {
242        put_u32(
243            &mut header,
244            56 + index * 4,
245            if *value == 0.0 { 0 } else { value.to_bits() },
246        );
247    }
248    out[..MANIFOLD_IDENTITY_V2_HEADER_SIZE].copy_from_slice(&header);
249
250    let mut offset = MANIFOLD_IDENTITY_V2_HEADER_SIZE;
251    for field in fields {
252        encode_field_record(
253            field,
254            &mut out[offset..offset + MANIFOLD_IDENTITY_V2_FIELD_RECORD_SIZE],
255        );
256        offset += MANIFOLD_IDENTITY_V2_FIELD_RECORD_SIZE;
257    }
258    Ok(needed)
259}
260
261/// Decode a v2 manifest without allocating. Parsed field records are copied to
262/// caller storage only after the entire section has passed validation. Built-in
263/// kinds are always recognized; extensions require explicit allow-list entries.
264pub fn decode_manifold_identity_v2(
265    bytes: &[u8],
266    supported_extension_kinds: &[u16],
267    out_fields: &mut [TypedFieldRecord],
268) -> Result<(ManifoldIdentityV2, usize), ManifestV2Error> {
269    if bytes.len() < MANIFOLD_IDENTITY_V2_HEADER_SIZE {
270        return Err(ManifestV2Error::TooShort {
271            got: bytes.len(),
272            need: MANIFOLD_IDENTITY_V2_HEADER_SIZE,
273        });
274    }
275    if bytes[0..4] != MANIFOLD_IDENTITY_V2_MAGIC {
276        return Err(ManifestV2Error::BadMagic);
277    }
278    let version = get_u16(bytes, 4);
279    if version != MANIFOLD_IDENTITY_V2_VERSION {
280        return Err(ManifestV2Error::UnsupportedVersion(version));
281    }
282    let header_size = get_u16(bytes, 6);
283    if header_size as usize != MANIFOLD_IDENTITY_V2_HEADER_SIZE {
284        return Err(ManifestV2Error::BadHeaderSize(header_size));
285    }
286    let declared = get_u32(bytes, 8);
287    let field_count = get_u16(bytes, 12) as usize;
288    let needed = encoded_len(field_count)?;
289    if declared as usize != bytes.len() || needed != bytes.len() {
290        return Err(ManifestV2Error::BadTotalLength {
291            declared,
292            actual: bytes.len(),
293        });
294    }
295    if bytes[14] as usize != MANIFOLD_IDENTITY_V2_AXIS_ORDER.len() {
296        return Err(ManifestV2Error::CoordinateCount(bytes[14]));
297    }
298    let flags = bytes[15];
299    if flags & !FLAG_HAS_EXTERNAL_DIGEST != 0 {
300        return Err(ManifestV2Error::UnknownFlags(flags));
301    }
302    let external_digest = if flags & FLAG_HAS_EXTERNAL_DIGEST != 0 {
303        let mut digest = [0u8; 16];
304        digest.copy_from_slice(&bytes[96..112]);
305        Some(IntegrityIndexDigest(digest))
306    } else {
307        if bytes[96..112].iter().any(|byte| *byte != 0) {
308            return Err(ManifestV2Error::NonZeroAbsentDigest);
309        }
310        None
311    };
312
313    let mut entity_bytes = [0u8; 16];
314    entity_bytes.copy_from_slice(&bytes[16..32]);
315    let mut coordinates = [0.0f32; 10];
316    for (index, coordinate) in coordinates.iter_mut().enumerate() {
317        *coordinate = f32::from_bits(get_u32(bytes, 56 + index * 4));
318        if *coordinate == 0.0 && coordinate.to_bits() != 0 {
319            return Err(ManifestV2Error::NonCanonicalCoordinate { axis: index });
320        }
321    }
322    let identity = ManifoldIdentityV2 {
323        entity_id: StableEntityId(entity_bytes),
324        profile_id: get_u64(bytes, 32),
325        domain_id: get_u64(bytes, 40),
326        coordinate_convention_id: get_u64(bytes, 48),
327        coordinates,
328        external_digest,
329    };
330    validate_identity(&identity)?;
331
332    if out_fields.len() < field_count {
333        return Err(ManifestV2Error::OutputTooSmall {
334            needed: field_count,
335            have: out_fields.len(),
336        });
337    }
338    let records = &bytes[MANIFOLD_IDENTITY_V2_HEADER_SIZE..];
339    validate_encoded_fields(records, field_count, supported_extension_kinds)?;
340    for (index, target) in out_fields.iter_mut().take(field_count).enumerate() {
341        let start = index * MANIFOLD_IDENTITY_V2_FIELD_RECORD_SIZE;
342        *target =
343            decode_field_record(&records[start..start + MANIFOLD_IDENTITY_V2_FIELD_RECORD_SIZE]);
344    }
345    Ok((identity, field_count))
346}
347
348/// Checked exact encoded length, bounded by the v2 manifest's field limit.
349pub fn encoded_len(field_count: usize) -> Result<usize, ManifestV2Error> {
350    if field_count > MANIFOLD_IDENTITY_V2_MAX_FIELDS {
351        return Err(ManifestV2Error::TooManyFields {
352            got: field_count,
353            max: MANIFOLD_IDENTITY_V2_MAX_FIELDS,
354        });
355    }
356    field_count
357        .checked_mul(MANIFOLD_IDENTITY_V2_FIELD_RECORD_SIZE)
358        .and_then(|n| n.checked_add(MANIFOLD_IDENTITY_V2_HEADER_SIZE))
359        .filter(|n| *n <= MANIFOLD_IDENTITY_V2_MAX_BYTES && *n <= u32::MAX as usize)
360        .ok_or(ManifestV2Error::LengthOverflow)
361}
362
363fn validate_identity(identity: &ManifoldIdentityV2) -> Result<(), ManifestV2Error> {
364    if identity.entity_id.0.iter().all(|byte| *byte == 0) {
365        return Err(ManifestV2Error::ZeroEntityId);
366    }
367    for (field, value) in [
368        ("profile_id", identity.profile_id),
369        ("domain_id", identity.domain_id),
370        (
371            "coordinate_convention_id",
372            identity.coordinate_convention_id,
373        ),
374    ] {
375        if value == 0 {
376            return Err(ManifestV2Error::ZeroDeclarationId { field });
377        }
378    }
379    for (axis, value) in identity.coordinates.iter().enumerate() {
380        if !value.is_finite() {
381            return Err(ManifestV2Error::NonFiniteCoordinate { axis });
382        }
383    }
384    Ok(())
385}
386
387fn validate_fields(
388    fields: &[TypedFieldRecord],
389    supported_extension_kinds: &[u16],
390) -> Result<(), ManifestV2Error> {
391    if fields.len() > MANIFOLD_IDENTITY_V2_MAX_FIELDS {
392        return Err(ManifestV2Error::TooManyFields {
393            got: fields.len(),
394            max: MANIFOLD_IDENTITY_V2_MAX_FIELDS,
395        });
396    }
397    let mut previous = 0u64;
398    for (index, field) in fields.iter().enumerate() {
399        if field.field_id == 0 {
400            return Err(ManifestV2Error::InvalidFieldId);
401        }
402        if index != 0 && field.field_id <= previous {
403            return Err(ManifestV2Error::FieldsNotStrictlySorted);
404        }
405        previous = field.field_id;
406        if field.kind == 0 {
407            return Err(ManifestV2Error::InvalidFieldKind);
408        }
409        if !is_known_kind(field.kind, supported_extension_kinds) {
410            return Err(ManifestV2Error::UnsupportedFieldKind(field.kind));
411        }
412        if field.flags != 0 {
413            return Err(ManifestV2Error::InvalidFieldFlags(field.flags));
414        }
415        validate_payload_reference(field, index)?;
416    }
417    Ok(())
418}
419
420fn validate_encoded_fields(
421    records: &[u8],
422    field_count: usize,
423    extensions: &[u16],
424) -> Result<(), ManifestV2Error> {
425    let mut previous = 0u64;
426    for index in 0..field_count {
427        let start = index * MANIFOLD_IDENTITY_V2_FIELD_RECORD_SIZE;
428        let record = &records[start..start + MANIFOLD_IDENTITY_V2_FIELD_RECORD_SIZE];
429        let field = decode_field_record(record);
430        if field.field_id == 0 {
431            return Err(ManifestV2Error::InvalidFieldId);
432        }
433        if index != 0 && field.field_id <= previous {
434            return Err(ManifestV2Error::FieldsNotStrictlySorted);
435        }
436        previous = field.field_id;
437        if field.kind == 0 {
438            return Err(ManifestV2Error::InvalidFieldKind);
439        }
440        if !is_known_kind(field.kind, extensions) {
441            return Err(ManifestV2Error::UnsupportedFieldKind(field.kind));
442        }
443        if field.flags != 0 {
444            return Err(ManifestV2Error::InvalidFieldFlags(field.flags));
445        }
446        if get_u32(record, 24) != 0 || get_u32(record, 44) != 0 {
447            return Err(ManifestV2Error::NonZeroReserved { field_index: index });
448        }
449        validate_payload_reference(&field, index)?;
450    }
451    Ok(())
452}
453
454fn validate_payload_reference(
455    field: &TypedFieldRecord,
456    index: usize,
457) -> Result<(), ManifestV2Error> {
458    if field.payload_section_id == 0 {
459        if field.payload_offset != 0 || field.payload_length != 0 {
460            return Err(ManifestV2Error::InvalidPayloadReference { field_index: index });
461        }
462    } else if field
463        .payload_offset
464        .checked_add(field.payload_length)
465        .is_none()
466    {
467        return Err(ManifestV2Error::PayloadRangeOverflow { field_index: index });
468    }
469    Ok(())
470}
471
472fn is_known_kind(kind: u16, extensions: &[u16]) -> bool {
473    BUILTIN_FIELD_KINDS.contains(&kind) || extensions.contains(&kind)
474}
475
476fn encode_field_record(field: &TypedFieldRecord, out: &mut [u8]) {
477    put_u64(out, 0, field.field_id);
478    put_u16(out, 8, field.kind);
479    put_u16(out, 10, field.flags);
480    put_u64(out, 12, field.unit_id);
481    put_u32(out, 20, field.payload_section_id);
482    put_u32(out, 24, 0);
483    put_u64(out, 28, field.payload_offset);
484    put_u64(out, 36, field.payload_length);
485    put_u32(out, 44, 0);
486}
487
488fn decode_field_record(bytes: &[u8]) -> TypedFieldRecord {
489    TypedFieldRecord {
490        field_id: get_u64(bytes, 0),
491        kind: get_u16(bytes, 8),
492        flags: get_u16(bytes, 10),
493        unit_id: get_u64(bytes, 12),
494        payload_section_id: get_u32(bytes, 20),
495        payload_offset: get_u64(bytes, 28),
496        payload_length: get_u64(bytes, 36),
497    }
498}
499
500fn put_u16(out: &mut [u8], offset: usize, value: u16) {
501    out[offset..offset + 2].copy_from_slice(&value.to_le_bytes());
502}
503
504fn put_u32(out: &mut [u8], offset: usize, value: u32) {
505    out[offset..offset + 4].copy_from_slice(&value.to_le_bytes());
506}
507
508fn put_u64(out: &mut [u8], offset: usize, value: u64) {
509    out[offset..offset + 8].copy_from_slice(&value.to_le_bytes());
510}
511
512fn get_u16(bytes: &[u8], offset: usize) -> u16 {
513    u16::from_le_bytes([bytes[offset], bytes[offset + 1]])
514}
515
516fn get_u32(bytes: &[u8], offset: usize) -> u32 {
517    u32::from_le_bytes([
518        bytes[offset],
519        bytes[offset + 1],
520        bytes[offset + 2],
521        bytes[offset + 3],
522    ])
523}
524
525fn get_u64(bytes: &[u8], offset: usize) -> u64 {
526    u64::from_le_bytes([
527        bytes[offset],
528        bytes[offset + 1],
529        bytes[offset + 2],
530        bytes[offset + 3],
531        bytes[offset + 4],
532        bytes[offset + 5],
533        bytes[offset + 6],
534        bytes[offset + 7],
535    ])
536}
537
538#[cfg(test)]
539#[path = "manifold_identity_v2_tests.rs"]
540mod tests;