icydb_core/model/
field.rs

1//! Module: model::field
2//! Responsibility: runtime field metadata and storage-decode contracts.
3//! Does not own: planner-wide query semantics or row-container orchestration.
4//! Boundary: field-level runtime schema surface used by storage and planning layers.
5
6use crate::{traits::RuntimeValueKind, types::EntityTag, value::Value};
7use std::cmp::Ordering;
8
9///
10/// FieldStorageDecode
11///
12/// FieldStorageDecode captures how one persisted field payload must be
13/// interpreted at structural decode boundaries.
14/// Semantic `FieldKind` alone is not always authoritative for persisted decode:
15/// some fields intentionally store raw `Value` payloads even when their planner
16/// shape is narrower.
17///
18
19#[derive(Clone, Copy, Debug, Eq, PartialEq)]
20pub enum FieldStorageDecode {
21    /// Decode the persisted field payload according to semantic `FieldKind`.
22    ByKind,
23    /// Decode the persisted field payload directly into `Value`.
24    Value,
25}
26
27///
28/// ScalarCodec
29///
30/// ScalarCodec identifies the canonical binary leaf encoding used for one
31/// scalar persisted field payload.
32/// These codecs are fixed-width or span-bounded by the surrounding row slot
33/// container; they do not perform map/array/value dispatch.
34///
35
36#[derive(Clone, Copy, Debug, Eq, PartialEq)]
37pub enum ScalarCodec {
38    Blob,
39    Bool,
40    Date,
41    Duration,
42    Float32,
43    Float64,
44    Int64,
45    Principal,
46    Subaccount,
47    Text,
48    Timestamp,
49    Uint64,
50    Ulid,
51    Unit,
52}
53
54///
55/// LeafCodec
56///
57/// LeafCodec declares whether one persisted field payload uses a dedicated
58/// scalar codec or falls back to structural leaf decoding.
59/// The row container consults this metadata before deciding whether a slot can
60/// stay on the scalar fast path.
61///
62
63#[derive(Clone, Copy, Debug, Eq, PartialEq)]
64pub enum LeafCodec {
65    Scalar(ScalarCodec),
66    StructuralFallback,
67}
68
69///
70/// EnumVariantModel
71///
72/// EnumVariantModel carries structural decode metadata for one generated enum
73/// variant payload.
74/// Runtime structural decode uses this to stay on the field-kind contract for
75/// enum payloads instead of falling back to generic untyped structural decode.
76///
77
78#[derive(Clone, Copy, Debug)]
79pub struct EnumVariantModel {
80    /// Stable schema variant tag.
81    pub(crate) ident: &'static str,
82    /// Declared payload kind when this variant carries data.
83    pub(crate) payload_kind: Option<&'static FieldKind>,
84    /// Persisted payload decode contract for the carried data.
85    pub(crate) payload_storage_decode: FieldStorageDecode,
86}
87
88impl EnumVariantModel {
89    /// Build one enum variant structural decode descriptor.
90    #[must_use]
91    pub const fn new(
92        ident: &'static str,
93        payload_kind: Option<&'static FieldKind>,
94        payload_storage_decode: FieldStorageDecode,
95    ) -> Self {
96        Self {
97            ident,
98            payload_kind,
99            payload_storage_decode,
100        }
101    }
102
103    /// Return the stable schema variant tag.
104    #[must_use]
105    pub const fn ident(&self) -> &'static str {
106        self.ident
107    }
108
109    /// Return the declared payload kind when this variant carries data.
110    #[must_use]
111    pub const fn payload_kind(&self) -> Option<&'static FieldKind> {
112        self.payload_kind
113    }
114
115    /// Return the persisted payload decode contract for this variant.
116    #[must_use]
117    pub const fn payload_storage_decode(&self) -> FieldStorageDecode {
118        self.payload_storage_decode
119    }
120}
121
122///
123/// FieldModel
124///
125/// Runtime field metadata surfaced by macro-generated `EntityModel` values.
126///
127/// This is the smallest unit consumed by predicate validation, planning,
128/// and executor-side plan checks.
129///
130
131#[derive(Debug)]
132pub struct FieldModel {
133    /// Field name as used in predicates and indexing.
134    pub(crate) name: &'static str,
135    /// Runtime type shape (no schema-layer graph nodes).
136    pub(crate) kind: FieldKind,
137    /// Whether the field may persist an explicit `NULL` payload.
138    pub(crate) nullable: bool,
139    /// Persisted field decode contract used by structural runtime decoders.
140    pub(crate) storage_decode: FieldStorageDecode,
141    /// Leaf payload codec used by slot readers and writers.
142    pub(crate) leaf_codec: LeafCodec,
143    /// Insert-time generation contract admitted on reduced SQL write lanes.
144    pub(crate) insert_generation: Option<FieldInsertGeneration>,
145    /// Auto-managed write contract emitted for derive-owned system fields.
146    pub(crate) write_management: Option<FieldWriteManagement>,
147}
148
149///
150/// FieldInsertGeneration
151///
152/// FieldInsertGeneration declares whether one runtime field may be synthesized
153/// by the reduced SQL insert boundary when the user omits that field.
154/// This stays separate from typed-Rust `Default` behavior so write-time
155/// generation remains an explicit schema contract.
156///
157
158#[derive(Clone, Copy, Debug, Eq, PartialEq)]
159pub enum FieldInsertGeneration {
160    /// Generate one fresh `Ulid` value at insert time.
161    Ulid,
162    /// Generate one current wall-clock `Timestamp` value at insert time.
163    Timestamp,
164}
165
166///
167/// FieldWriteManagement
168///
169/// FieldWriteManagement declares whether one runtime field is owned by the
170/// write boundary during insert or update synthesis.
171/// This keeps auto-managed system fields explicit in schema/runtime metadata
172/// instead of relying on literal field names in write paths.
173///
174
175#[derive(Clone, Copy, Debug, Eq, PartialEq)]
176pub enum FieldWriteManagement {
177    /// Fill only on insert when the row is first created.
178    CreatedAt,
179    /// Refresh on insert and every update.
180    UpdatedAt,
181}
182
183impl FieldModel {
184    /// Build one generated runtime field descriptor.
185    ///
186    /// This constructor exists for derive/codegen output and trusted test
187    /// fixtures. Runtime planning and execution treat `FieldModel` values as
188    /// build-time-validated metadata.
189    #[must_use]
190    #[doc(hidden)]
191    pub const fn generated(name: &'static str, kind: FieldKind) -> Self {
192        Self::generated_with_storage_decode_and_nullability(
193            name,
194            kind,
195            FieldStorageDecode::ByKind,
196            false,
197        )
198    }
199
200    /// Build one runtime field descriptor with an explicit persisted decode contract.
201    #[must_use]
202    #[doc(hidden)]
203    pub const fn generated_with_storage_decode(
204        name: &'static str,
205        kind: FieldKind,
206        storage_decode: FieldStorageDecode,
207    ) -> Self {
208        Self::generated_with_storage_decode_and_nullability(name, kind, storage_decode, false)
209    }
210
211    /// Build one runtime field descriptor with an explicit decode contract and nullability.
212    #[must_use]
213    #[doc(hidden)]
214    pub const fn generated_with_storage_decode_and_nullability(
215        name: &'static str,
216        kind: FieldKind,
217        storage_decode: FieldStorageDecode,
218        nullable: bool,
219    ) -> Self {
220        Self::generated_with_storage_decode_nullability_and_write_policies(
221            name,
222            kind,
223            storage_decode,
224            nullable,
225            None,
226            None,
227        )
228    }
229
230    /// Build one runtime field descriptor with an explicit decode contract, nullability,
231    /// and insert-time generation contract.
232    #[must_use]
233    #[doc(hidden)]
234    pub const fn generated_with_storage_decode_nullability_and_insert_generation(
235        name: &'static str,
236        kind: FieldKind,
237        storage_decode: FieldStorageDecode,
238        nullable: bool,
239        insert_generation: Option<FieldInsertGeneration>,
240    ) -> Self {
241        Self::generated_with_storage_decode_nullability_and_write_policies(
242            name,
243            kind,
244            storage_decode,
245            nullable,
246            insert_generation,
247            None,
248        )
249    }
250
251    /// Build one runtime field descriptor with explicit insert-generation and
252    /// write-management policies.
253    #[must_use]
254    #[doc(hidden)]
255    pub const fn generated_with_storage_decode_nullability_and_write_policies(
256        name: &'static str,
257        kind: FieldKind,
258        storage_decode: FieldStorageDecode,
259        nullable: bool,
260        insert_generation: Option<FieldInsertGeneration>,
261        write_management: Option<FieldWriteManagement>,
262    ) -> Self {
263        Self {
264            name,
265            kind,
266            nullable,
267            storage_decode,
268            leaf_codec: leaf_codec_for(kind, storage_decode),
269            insert_generation,
270            write_management,
271        }
272    }
273
274    /// Return the stable field name.
275    #[must_use]
276    pub const fn name(&self) -> &'static str {
277        self.name
278    }
279
280    /// Return the runtime type-kind descriptor.
281    #[must_use]
282    pub const fn kind(&self) -> FieldKind {
283        self.kind
284    }
285
286    /// Return whether the persisted field contract permits explicit `NULL`.
287    #[must_use]
288    pub const fn nullable(&self) -> bool {
289        self.nullable
290    }
291
292    /// Return the persisted field decode contract.
293    #[must_use]
294    pub const fn storage_decode(&self) -> FieldStorageDecode {
295        self.storage_decode
296    }
297
298    /// Return the persisted leaf payload codec.
299    #[must_use]
300    pub const fn leaf_codec(&self) -> LeafCodec {
301        self.leaf_codec
302    }
303
304    /// Return the reduced-SQL insert-time generation contract for this field.
305    #[must_use]
306    pub const fn insert_generation(&self) -> Option<FieldInsertGeneration> {
307        self.insert_generation
308    }
309
310    /// Return the write-boundary management contract for this field.
311    #[must_use]
312    pub const fn write_management(&self) -> Option<FieldWriteManagement> {
313        self.write_management
314    }
315
316    /// Validate one runtime value against this field's persisted storage contract.
317    ///
318    /// This is the model-owned compatibility gate used before row bytes are
319    /// emitted. It intentionally checks storage compatibility, not query
320    /// predicate compatibility, so `FieldStorageDecode::Value` can accept
321    /// open-ended structured payloads while still enforcing outer collection
322    /// shape, decimal scale, and deterministic set/map ordering.
323    pub(crate) fn validate_runtime_value_for_storage(&self, value: &Value) -> Result<(), String> {
324        if matches!(value, Value::Null) {
325            if self.nullable() {
326                return Ok(());
327            }
328
329            return Err("required field cannot store null".into());
330        }
331
332        let accepts = match self.storage_decode() {
333            FieldStorageDecode::Value => {
334                value_storage_kind_accepts_runtime_value(self.kind(), value)
335            }
336            FieldStorageDecode::ByKind => {
337                by_kind_storage_kind_accepts_runtime_value(self.kind(), value)
338            }
339        };
340        if !accepts {
341            return Err(format!(
342                "field kind {:?} does not accept runtime value {value:?}",
343                self.kind()
344            ));
345        }
346
347        ensure_decimal_scale_matches(self.kind(), value)?;
348        ensure_text_max_len_matches(self.kind(), value)?;
349        ensure_value_is_deterministic_for_storage(self.kind(), value)
350    }
351}
352
353// Resolve the canonical leaf codec from semantic field kind plus storage
354// contract. Fields that intentionally persist as `Value` or that still require
355// recursive payload decoding remain on the shared structural fallback.
356const fn leaf_codec_for(kind: FieldKind, storage_decode: FieldStorageDecode) -> LeafCodec {
357    if matches!(storage_decode, FieldStorageDecode::Value) {
358        return LeafCodec::StructuralFallback;
359    }
360
361    match kind {
362        FieldKind::Blob => LeafCodec::Scalar(ScalarCodec::Blob),
363        FieldKind::Bool => LeafCodec::Scalar(ScalarCodec::Bool),
364        FieldKind::Date => LeafCodec::Scalar(ScalarCodec::Date),
365        FieldKind::Duration => LeafCodec::Scalar(ScalarCodec::Duration),
366        FieldKind::Float32 => LeafCodec::Scalar(ScalarCodec::Float32),
367        FieldKind::Float64 => LeafCodec::Scalar(ScalarCodec::Float64),
368        FieldKind::Int => LeafCodec::Scalar(ScalarCodec::Int64),
369        FieldKind::Principal => LeafCodec::Scalar(ScalarCodec::Principal),
370        FieldKind::Subaccount => LeafCodec::Scalar(ScalarCodec::Subaccount),
371        FieldKind::Text { .. } => LeafCodec::Scalar(ScalarCodec::Text),
372        FieldKind::Timestamp => LeafCodec::Scalar(ScalarCodec::Timestamp),
373        FieldKind::Uint => LeafCodec::Scalar(ScalarCodec::Uint64),
374        FieldKind::Ulid => LeafCodec::Scalar(ScalarCodec::Ulid),
375        FieldKind::Unit => LeafCodec::Scalar(ScalarCodec::Unit),
376        FieldKind::Relation { key_kind, .. } => leaf_codec_for(*key_kind, storage_decode),
377        FieldKind::Account
378        | FieldKind::Decimal { .. }
379        | FieldKind::Enum { .. }
380        | FieldKind::Int128
381        | FieldKind::IntBig
382        | FieldKind::List(_)
383        | FieldKind::Map { .. }
384        | FieldKind::Set(_)
385        | FieldKind::Structured { .. }
386        | FieldKind::Uint128
387        | FieldKind::UintBig => LeafCodec::StructuralFallback,
388    }
389}
390
391///
392/// RelationStrength
393///
394/// Explicit relation intent for save-time referential integrity.
395///
396
397#[derive(Clone, Copy, Debug, Eq, PartialEq)]
398pub enum RelationStrength {
399    Strong,
400    Weak,
401}
402
403///
404/// FieldKind
405///
406/// Minimal runtime type surface needed by planning, validation, and execution.
407///
408/// This is aligned with `Value` variants and intentionally lossy: it encodes
409/// only the shape required for predicate compatibility and index planning.
410///
411
412#[derive(Clone, Copy, Debug)]
413pub enum FieldKind {
414    // Scalar primitives
415    Account,
416    Blob,
417    Bool,
418    Date,
419    Decimal {
420        /// Required schema-declared fractional scale for decimal fields.
421        scale: u32,
422    },
423    Duration,
424    Enum {
425        /// Fully-qualified enum type path used for strict filter normalization.
426        path: &'static str,
427        /// Declared per-variant payload decode metadata.
428        variants: &'static [EnumVariantModel],
429    },
430    Float32,
431    Float64,
432    Int,
433    Int128,
434    IntBig,
435    Principal,
436    Subaccount,
437    Text {
438        /// Optional schema-declared maximum Unicode scalar count for text fields.
439        max_len: Option<u32>,
440    },
441    Timestamp,
442    Uint,
443    Uint128,
444    UintBig,
445    Ulid,
446    Unit,
447
448    /// Typed relation; `key_kind` reflects the referenced key type.
449    /// `strength` encodes strong vs. weak relation intent.
450    Relation {
451        /// Fully-qualified Rust type path for diagnostics.
452        target_path: &'static str,
453        /// Stable external name used in storage keys.
454        target_entity_name: &'static str,
455        /// Stable runtime identity used on hot execution paths.
456        target_entity_tag: EntityTag,
457        /// Data store path where the target entity is persisted.
458        target_store_path: &'static str,
459        key_kind: &'static Self,
460        strength: RelationStrength,
461    },
462
463    // Collections
464    List(&'static Self),
465    Set(&'static Self),
466    /// Deterministic, unordered key/value collection.
467    ///
468    /// Map fields are persistable and patchable, but not queryable or indexable.
469    Map {
470        key: &'static Self,
471        value: &'static Self,
472    },
473
474    /// Structured (non-atomic) value.
475    /// Queryability here controls whether predicates may target this field,
476    /// not whether it may be stored or updated.
477    Structured {
478        queryable: bool,
479    },
480}
481
482impl FieldKind {
483    #[must_use]
484    pub const fn value_kind(&self) -> RuntimeValueKind {
485        match self {
486            Self::Account
487            | Self::Blob
488            | Self::Bool
489            | Self::Date
490            | Self::Duration
491            | Self::Enum { .. }
492            | Self::Float32
493            | Self::Float64
494            | Self::Int
495            | Self::Int128
496            | Self::IntBig
497            | Self::Principal
498            | Self::Subaccount
499            | Self::Text { .. }
500            | Self::Timestamp
501            | Self::Uint
502            | Self::Uint128
503            | Self::UintBig
504            | Self::Ulid
505            | Self::Unit
506            | Self::Decimal { .. }
507            | Self::Relation { .. } => RuntimeValueKind::Atomic,
508            Self::List(_) | Self::Set(_) => RuntimeValueKind::Structured { queryable: true },
509            Self::Map { .. } => RuntimeValueKind::Structured { queryable: false },
510            Self::Structured { queryable } => RuntimeValueKind::Structured {
511                queryable: *queryable,
512            },
513        }
514    }
515
516    /// Returns `true` if this field shape is permitted in
517    /// persisted or query-visible schemas under the current
518    /// determinism policy.
519    ///
520    /// This shape-level check is structural only; query-time policy
521    /// enforcement (for example, map predicate fencing) is applied at
522    /// query construction and validation boundaries.
523    #[must_use]
524    pub const fn is_deterministic_collection_shape(&self) -> bool {
525        match self {
526            Self::Relation { key_kind, .. } => key_kind.is_deterministic_collection_shape(),
527
528            Self::List(inner) | Self::Set(inner) => inner.is_deterministic_collection_shape(),
529
530            Self::Map { key, value } => {
531                key.is_deterministic_collection_shape() && value.is_deterministic_collection_shape()
532            }
533
534            _ => true,
535        }
536    }
537
538    /// Return true when this planner-frozen grouped field kind can stay on the
539    /// borrowed grouped-key probe path without owned canonical materialization.
540    #[must_use]
541    pub(crate) fn supports_group_probe(&self) -> bool {
542        match self {
543            Self::Enum { variants, .. } => variants.iter().all(|variant| {
544                variant
545                    .payload_kind()
546                    .is_none_or(Self::supports_group_probe)
547            }),
548            Self::Relation { key_kind, .. } => key_kind.supports_group_probe(),
549            Self::List(_)
550            | Self::Set(_)
551            | Self::Map { .. }
552            | Self::Structured { .. }
553            | Self::Unit => false,
554            Self::Account
555            | Self::Blob
556            | Self::Bool
557            | Self::Date
558            | Self::Decimal { .. }
559            | Self::Duration
560            | Self::Float32
561            | Self::Float64
562            | Self::Int
563            | Self::Int128
564            | Self::IntBig
565            | Self::Principal
566            | Self::Subaccount
567            | Self::Text { .. }
568            | Self::Timestamp
569            | Self::Uint
570            | Self::Uint128
571            | Self::UintBig
572            | Self::Ulid => true,
573        }
574    }
575
576    /// Match one runtime value against this field kind contract.
577    ///
578    /// This is the shared recursive field-kind acceptance boundary used by
579    /// persisted-row encoding, mutation-save validation, and aggregate field
580    /// extraction.
581    #[must_use]
582    pub(crate) fn accepts_value(&self, value: &Value) -> bool {
583        match (self, value) {
584            (Self::Account, Value::Account(_))
585            | (Self::Blob, Value::Blob(_))
586            | (Self::Bool, Value::Bool(_))
587            | (Self::Date, Value::Date(_))
588            | (Self::Decimal { .. }, Value::Decimal(_))
589            | (Self::Duration, Value::Duration(_))
590            | (Self::Enum { .. }, Value::Enum(_))
591            | (Self::Float32, Value::Float32(_))
592            | (Self::Float64, Value::Float64(_))
593            | (Self::Int, Value::Int(_))
594            | (Self::Int128, Value::Int128(_))
595            | (Self::IntBig, Value::IntBig(_))
596            | (Self::Principal, Value::Principal(_))
597            | (Self::Subaccount, Value::Subaccount(_))
598            | (Self::Text { .. }, Value::Text(_))
599            | (Self::Timestamp, Value::Timestamp(_))
600            | (Self::Uint, Value::Uint(_))
601            | (Self::Uint128, Value::Uint128(_))
602            | (Self::UintBig, Value::UintBig(_))
603            | (Self::Ulid, Value::Ulid(_))
604            | (Self::Unit, Value::Unit)
605            | (Self::Structured { .. }, Value::List(_) | Value::Map(_)) => true,
606            (Self::Relation { key_kind, .. }, value) => key_kind.accepts_value(value),
607            (Self::List(inner) | Self::Set(inner), Value::List(items)) => {
608                items.iter().all(|item| inner.accepts_value(item))
609            }
610            (Self::Map { key, value }, Value::Map(entries)) => {
611                if Value::validate_map_entries(entries.as_slice()).is_err() {
612                    return false;
613                }
614
615                entries.iter().all(|(entry_key, entry_value)| {
616                    key.accepts_value(entry_key) && value.accepts_value(entry_value)
617                })
618            }
619            _ => false,
620        }
621    }
622}
623
624// `FieldStorageDecode::ByKind` follows the same literal compatibility rule as
625// the schema predicate layer without routing the storage model through
626// `db::schema`. Structured field kinds are intentionally not accepted here;
627// fields that persist open-ended structured payloads use
628// `FieldStorageDecode::Value` instead.
629fn by_kind_storage_kind_accepts_runtime_value(kind: FieldKind, value: &Value) -> bool {
630    match (kind, value) {
631        (FieldKind::Relation { key_kind, .. }, value) => {
632            by_kind_storage_kind_accepts_runtime_value(*key_kind, value)
633        }
634        (FieldKind::List(inner) | FieldKind::Set(inner), Value::List(items)) => items
635            .iter()
636            .all(|item| by_kind_storage_kind_accepts_runtime_value(*inner, item)),
637        (
638            FieldKind::Map {
639                key,
640                value: value_kind,
641            },
642            Value::Map(entries),
643        ) => {
644            if Value::validate_map_entries(entries.as_slice()).is_err() {
645                return false;
646            }
647
648            entries.iter().all(|(entry_key, entry_value)| {
649                by_kind_storage_kind_accepts_runtime_value(*key, entry_key)
650                    && by_kind_storage_kind_accepts_runtime_value(*value_kind, entry_value)
651            })
652        }
653        (FieldKind::Structured { .. }, _) => false,
654        _ => kind.accepts_value(value),
655    }
656}
657
658// `FieldStorageDecode::Value` fields persist an opaque runtime `Value` envelope,
659// so `FieldKind::Structured` must stay open-ended while outer collection/map
660// shapes still enforce the recursive structure the model owns.
661fn value_storage_kind_accepts_runtime_value(kind: FieldKind, value: &Value) -> bool {
662    match (kind, value) {
663        (FieldKind::Structured { .. }, _) => true,
664        (FieldKind::Relation { key_kind, .. }, value) => {
665            value_storage_kind_accepts_runtime_value(*key_kind, value)
666        }
667        (FieldKind::List(inner) | FieldKind::Set(inner), Value::List(items)) => items
668            .iter()
669            .all(|item| value_storage_kind_accepts_runtime_value(*inner, item)),
670        (
671            FieldKind::Map {
672                key,
673                value: value_kind,
674            },
675            Value::Map(entries),
676        ) => {
677            if Value::validate_map_entries(entries.as_slice()).is_err() {
678                return false;
679            }
680
681            entries.iter().all(|(entry_key, entry_value)| {
682                value_storage_kind_accepts_runtime_value(*key, entry_key)
683                    && value_storage_kind_accepts_runtime_value(*value_kind, entry_value)
684            })
685        }
686        _ => kind.accepts_value(value),
687    }
688}
689
690// Enforce fixed decimal scales through nested collection/map shapes before a
691// field-level runtime value is persisted.
692fn ensure_decimal_scale_matches(kind: FieldKind, value: &Value) -> Result<(), String> {
693    if matches!(value, Value::Null) {
694        return Ok(());
695    }
696
697    match (kind, value) {
698        (FieldKind::Decimal { scale }, Value::Decimal(decimal)) => {
699            if decimal.scale() != scale {
700                return Err(format!(
701                    "decimal scale mismatch: expected {scale}, found {}",
702                    decimal.scale()
703                ));
704            }
705
706            Ok(())
707        }
708        (FieldKind::Relation { key_kind, .. }, value) => {
709            ensure_decimal_scale_matches(*key_kind, value)
710        }
711        (FieldKind::List(inner) | FieldKind::Set(inner), Value::List(items)) => {
712            for item in items {
713                ensure_decimal_scale_matches(*inner, item)?;
714            }
715
716            Ok(())
717        }
718        (
719            FieldKind::Map {
720                key,
721                value: map_value,
722            },
723            Value::Map(entries),
724        ) => {
725            for (entry_key, entry_value) in entries {
726                ensure_decimal_scale_matches(*key, entry_key)?;
727                ensure_decimal_scale_matches(*map_value, entry_value)?;
728            }
729
730            Ok(())
731        }
732        _ => Ok(()),
733    }
734}
735
736// Enforce bounded text length through nested collection/map shapes before a
737// field-level runtime value is persisted.
738fn ensure_text_max_len_matches(kind: FieldKind, value: &Value) -> Result<(), String> {
739    if matches!(value, Value::Null) {
740        return Ok(());
741    }
742
743    match (kind, value) {
744        (FieldKind::Text { max_len: Some(max) }, Value::Text(text)) => {
745            let len = text.chars().count();
746            if len > max as usize {
747                return Err(format!(
748                    "text length exceeds max_len: expected at most {max}, found {len}"
749                ));
750            }
751
752            Ok(())
753        }
754        (FieldKind::Relation { key_kind, .. }, value) => {
755            ensure_text_max_len_matches(*key_kind, value)
756        }
757        (FieldKind::List(inner) | FieldKind::Set(inner), Value::List(items)) => {
758            for item in items {
759                ensure_text_max_len_matches(*inner, item)?;
760            }
761
762            Ok(())
763        }
764        (
765            FieldKind::Map {
766                key,
767                value: map_value,
768            },
769            Value::Map(entries),
770        ) => {
771            for (entry_key, entry_value) in entries {
772                ensure_text_max_len_matches(*key, entry_key)?;
773                ensure_text_max_len_matches(*map_value, entry_value)?;
774            }
775
776            Ok(())
777        }
778        _ => Ok(()),
779    }
780}
781
782// Enforce the canonical persisted ordering rules for set/map shapes before one
783// field-level runtime value becomes row bytes.
784fn ensure_value_is_deterministic_for_storage(kind: FieldKind, value: &Value) -> Result<(), String> {
785    match (kind, value) {
786        (FieldKind::Set(_), Value::List(items)) => {
787            for pair in items.windows(2) {
788                let [left, right] = pair else {
789                    continue;
790                };
791                if Value::canonical_cmp(left, right) != Ordering::Less {
792                    return Err("set payload must already be canonical and deduplicated".into());
793                }
794            }
795
796            Ok(())
797        }
798        (FieldKind::Map { .. }, Value::Map(entries)) => {
799            Value::validate_map_entries(entries.as_slice()).map_err(|err| err.to_string())?;
800
801            if !Value::map_entries_are_strictly_canonical(entries.as_slice()) {
802                return Err("map payload must already be canonical and deduplicated".into());
803            }
804
805            Ok(())
806        }
807        _ => Ok(()),
808    }
809}
810
811///
812/// TESTS
813///
814
815#[cfg(test)]
816mod tests {
817    use crate::{
818        model::field::{FieldKind, FieldModel},
819        value::Value,
820    };
821
822    static BOUNDED_TEXT: FieldKind = FieldKind::Text { max_len: Some(3) };
823
824    #[test]
825    fn text_max_len_accepts_unbounded_text() {
826        let field = FieldModel::generated("name", FieldKind::Text { max_len: None });
827
828        assert!(
829            field
830                .validate_runtime_value_for_storage(&Value::Text("Ada Lovelace".into()))
831                .is_ok()
832        );
833    }
834
835    #[test]
836    fn text_max_len_counts_unicode_scalars_not_bytes() {
837        let field = FieldModel::generated("name", BOUNDED_TEXT);
838
839        assert!(
840            field
841                .validate_runtime_value_for_storage(&Value::Text("ééé".into()))
842                .is_ok()
843        );
844        assert!(
845            field
846                .validate_runtime_value_for_storage(&Value::Text("éééé".into()))
847                .is_err()
848        );
849    }
850
851    #[test]
852    fn text_max_len_recurses_through_collections() {
853        static TEXT_LIST: FieldKind = FieldKind::List(&BOUNDED_TEXT);
854        static TEXT_MAP: FieldKind = FieldKind::Map {
855            key: &BOUNDED_TEXT,
856            value: &BOUNDED_TEXT,
857        };
858
859        let list_field = FieldModel::generated("names", TEXT_LIST);
860        let map_field = FieldModel::generated("labels", TEXT_MAP);
861
862        assert!(
863            list_field
864                .validate_runtime_value_for_storage(&Value::List(vec![
865                    Value::Text("Ada".into()),
866                    Value::Text("Bob".into()),
867                ]))
868                .is_ok()
869        );
870        assert!(
871            list_field
872                .validate_runtime_value_for_storage(&Value::List(vec![Value::Text("Grace".into())]))
873                .is_err()
874        );
875        assert!(
876            map_field
877                .validate_runtime_value_for_storage(&Value::Map(vec![(
878                    Value::Text("key".into()),
879                    Value::Text("val".into()),
880                )]))
881                .is_ok()
882        );
883        assert!(
884            map_field
885                .validate_runtime_value_for_storage(&Value::Map(vec![(
886                    Value::Text("long".into()),
887                    Value::Text("val".into()),
888                )]))
889                .is_err()
890        );
891    }
892}
icydb_core/model/field.rs

icydb_core/model/
field.rs
