trox 0.2.1

Immutable source-authored localization values and deterministic bundle runtime
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
use serde::{Deserialize, Serialize};
use std::collections::{BTreeMap, BTreeSet};
use unicode_normalization::UnicodeNormalization;

use crate::TroxValueError;
use crate::canonical::{short_id, signature, signature_hex};
use crate::value::{LocalizedStringWire, identity_id_pair};

/// Maximum number of selector levels permitted in a message pattern.
pub const MAX_SELECTOR_DEPTH: usize = 16;
/// Maximum number of branches permitted on one selector.
pub const MAX_SELECTOR_BRANCHES: usize = 256;
/// Maximum number of nodes permitted in one message pattern tree.
pub const MAX_PATTERN_NODES: usize = 4096;
/// Maximum number of placeholder arguments permitted in one message.
pub const MAX_ARGUMENTS: usize = 256;
/// Maximum number of expanded translation rows permitted for one message entry.
pub const MAX_EXPANDED_ROWS: usize = 4096;
/// Largest integer that has an exact representation in the wire format's number model.
pub const MAX_SAFE_INTEGER: u64 = 9_007_199_254_740_991;

/// Major and minor version of a Trox wire value.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Version {
    /// Wire format major version.
    pub major: u32,
    /// Wire format minor version.
    pub minor: u32,
}

impl Version {
    /// Version 1.0 of the Trox wire format.
    pub const V1: Self = Self { major: 1, minor: 0 };
    /// Version 1.1 of the Trox wire format.
    pub const V1_1: Self = Self { major: 1, minor: 1 };

    pub(crate) fn is_supported_v1(self) -> bool {
        self.major == 1 && self.minor <= 1
    }
}

/// Locale-independent fields used to derive a message's stable identity.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct IdentityDescriptor {
    /// Version of the identity canonicalization rules.
    pub identity_version: u32,
    /// Optional stable identifier distinguishing semantically different uses of the same text.
    pub meaning: Option<String>,
    /// Source-authored message pattern.
    pub pattern: Pattern,
}

/// Locale-independent source pattern for a message.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "lowercase", deny_unknown_fields)]
pub enum Pattern {
    /// A text leaf, which may contain named placeholders.
    Text {
        /// Source text for the leaf.
        text: String,
    },
    /// A cardinal-plural selector.
    Plural {
        /// Canonically ordered exact and category branches.
        branches: Vec<NumericBranch>,
    },
    /// An ordinal-plural selector.
    Ordinal {
        /// Canonically ordered exact and category branches.
        branches: Vec<NumericBranch>,
    },
    /// A stable semantic selector.
    Select {
        /// Ordered conditional branches followed by an otherwise branch.
        branches: Vec<SelectIdentityBranch>,
    },
}

/// One branch of a cardinal or ordinal numeric selector.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct NumericBranch {
    /// Exact value or plural category selecting this branch.
    pub key: NumericBranchKey,
    /// Pattern rendered when the branch is selected.
    pub pattern: Pattern,
}

/// Identity-bearing key for a numeric selector branch.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(untagged, deny_unknown_fields)]
pub enum NumericBranchKey {
    /// An exact non-negative integer match.
    Exact {
        /// Integer that selects this branch.
        exact: u64,
    },
    /// A cardinal plural-category match.
    Plural {
        /// CLDR cardinal category that selects this branch.
        plural: PluralCategory,
    },
    /// An ordinal plural-category match.
    Ordinal {
        /// CLDR ordinal category that selects this branch.
        ordinal: PluralCategory,
    },
}

impl NumericBranchKey {
    pub(crate) fn exact(&self) -> Option<u64> {
        match self {
            Self::Exact { exact } => Some(*exact),
            _ => None,
        }
    }

    pub(crate) fn category(&self) -> Option<PluralCategory> {
        match self {
            Self::Plural { plural } => Some(*plural),
            Self::Ordinal { ordinal } => Some(*ordinal),
            Self::Exact { .. } => None,
        }
    }
}

/// Identity-bearing branch of a stable semantic selector.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "role", rename_all = "lowercase", deny_unknown_fields)]
pub enum SelectIdentityBranch {
    /// A branch associated with a runtime key stored in the selector record.
    When {
        /// Pattern rendered when the corresponding key matches.
        pattern: Pattern,
    },
    /// Final fallback branch when no key matches.
    Otherwise {
        /// Pattern rendered when no conditional branch matches.
        pattern: Pattern,
    },
}

impl SelectIdentityBranch {
    pub(crate) fn pattern(&self) -> &Pattern {
        match self {
            Self::When { pattern } | Self::Otherwise { pattern } => pattern,
        }
    }
}

/// CLDR plural category used by cardinal and ordinal patterns.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum PluralCategory {
    /// The `zero` category.
    Zero,
    /// The `one` category.
    One,
    /// The `two` category.
    Two,
    /// The `few` category.
    Few,
    /// The `many` category.
    Many,
    /// The required catch-all `other` category.
    Other,
}

impl PluralCategory {
    /// Categories in their canonical wire ordering.
    pub const CANONICAL: [Self; 6] = [
        Self::Zero,
        Self::One,
        Self::Two,
        Self::Few,
        Self::Many,
        Self::Other,
    ];

    /// Returns the lowercase CLDR spelling of this category.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Zero => "zero",
            Self::One => "one",
            Self::Two => "two",
            Self::Few => "few",
            Self::Many => "many",
            Self::Other => "other",
        }
    }
}

/// Runtime key used to select a semantic branch.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]
#[serde(untagged)]
pub enum SelectorKey {
    /// Stable application-defined string key.
    String(String),
    /// Boolean selector key.
    Boolean(bool),
}

impl SelectorKey {
    pub(crate) fn validate(&self) -> Result<(), TroxValueError> {
        if let Self::String(value) = self {
            validate_stable_id(value, "selector key")?;
        }
        Ok(())
    }
}

/// Runtime selector input paired with its path in the identity pattern.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "lowercase", deny_unknown_fields)]
pub enum SelectorRecord {
    /// Runtime value for a cardinal-plural selector.
    Plural {
        /// Branch-index path from the pattern root to the selector.
        path: Vec<usize>,
        /// Non-negative integer being selected.
        value: u64,
    },
    /// Runtime value for an ordinal-plural selector.
    Ordinal {
        /// Branch-index path from the pattern root to the selector.
        path: Vec<usize>,
        /// Non-negative integer being selected.
        value: u64,
    },
    /// Runtime value and branch keys for a semantic selector.
    Select {
        /// Branch-index path from the pattern root to the selector.
        path: Vec<usize>,
        /// Keys corresponding to the pattern's ordered `when` branches.
        branch_keys: Vec<SelectorKey>,
        /// Runtime key being selected.
        value: SelectorKey,
    },
}

impl SelectorRecord {
    /// Returns the branch-index path from the pattern root to this selector.
    pub fn path(&self) -> &[usize] {
        match self {
            Self::Plural { path, .. } | Self::Ordinal { path, .. } | Self::Select { path, .. } => {
                path
            }
        }
    }
}

/// Validated, stable identifier for an application term.
#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize)]
#[serde(transparent)]
pub struct TermId(String);

impl<'de> Deserialize<'de> for TermId {
    fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
        let value = String::deserialize(deserializer)?;
        Self::try_new(value).map_err(serde::de::Error::custom)
    }
}

impl TermId {
    /// Creates a term ID, panicking when `value` is not a valid stable ID.
    ///
    /// Use [`Self::try_new`] when the ID originates outside source code.
    pub fn new(value: impl Into<String>) -> Self {
        let value = value.into();
        if let Err(error) = validate_stable_id(&value, "term ID") {
            panic!("TROX_ASSERT {error}");
        }
        Self(value)
    }

    /// Creates a term ID after validating its stable-ID syntax.
    pub fn try_new(value: impl Into<String>) -> Result<Self, TroxValueError> {
        let value = value.into();
        validate_stable_id(&value, "term ID")?;
        Ok(Self(value))
    }

    /// Returns the validated string representation of this term ID.
    pub fn as_str(&self) -> &str {
        &self.0
    }
}

/// Reference to a term, optionally specifying a form and count.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct TermArgument {
    /// Referenced application term.
    pub term_id: TermId,
    /// Stable term form requested from the bundle.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub form: Option<String>,
    /// Count supplied to a numbered term form.
    #[serde(skip_serializing_if = "Option::is_none")]
    pub number: Option<u64>,
}

/// Runtime value bound to a named placeholder.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "lowercase", deny_unknown_fields)]
pub enum Argument {
    /// User- or application-provided text.
    Text {
        /// Text value inserted at resolution time.
        value: String,
    },
    /// Finite number formatted according to the target locale.
    Number {
        /// Numeric value inserted at resolution time.
        value: f64,
    },
    /// Boolean rendered as a scalar value.
    Boolean {
        /// Boolean value inserted at resolution time.
        value: bool,
    },
    /// Bundle-authorized term reference.
    Term {
        /// Referenced application term.
        term_id: TermId,
        /// Stable term form requested from the bundle.
        #[serde(skip_serializing_if = "Option::is_none")]
        form: Option<String>,
        /// Count supplied to a numbered term form.
        #[serde(skip_serializing_if = "Option::is_none")]
        number: Option<u64>,
    },
    /// Atomic localized value embedded without exposing its source text to translators.
    Opaque {
        /// Complete wire representation of the atomic nested value.
        value: Box<LocalizedStringWire>,
    },
}

/// Coarse placeholder category used to compare source and translated rows.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ArgumentKind {
    /// Text, number, or boolean value.
    Scalar,
    /// Term reference.
    Term,
    /// Atomic nested localized value.
    Opaque,
}

/// Source-authored contract for one visible placeholder binding.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(tag = "kind", rename_all = "lowercase", deny_unknown_fields)]
pub enum ArgumentSchema {
    /// Text, finite number, or boolean runtime value.
    Scalar,
    /// Atomic localized value.
    Opaque,
    /// Project term with an exact form and number-presence contract.
    Term {
        /// Requested named form, or the term default when omitted.
        #[serde(default, skip_serializing_if = "Option::is_none")]
        form: Option<String>,
        /// Whether the term binding requires a cardinal number.
        number: bool,
    },
}

/// Conversion contract used by [`crate::tx_args!`] to borrow application values.
pub trait IntoArgument {
    /// Converts the borrowed value into an owned Trox argument.
    fn to_argument(&self) -> Argument;
}

impl Argument {
    /// Converts a borrowed application value into an owned argument.
    pub fn from_borrowed<T: IntoArgument + ?Sized>(value: &T) -> Self {
        value.to_argument()
    }

    /// Returns the coarse category of this argument.
    pub fn kind(&self) -> ArgumentKind {
        match self {
            Self::Text { .. } | Self::Number { .. } | Self::Boolean { .. } => ArgumentKind::Scalar,
            Self::Term { .. } => ArgumentKind::Term,
            Self::Opaque { .. } => ArgumentKind::Opaque,
        }
    }
}

impl IntoArgument for String {
    fn to_argument(&self) -> Argument {
        Argument::Text {
            value: self.clone(),
        }
    }
}
impl IntoArgument for str {
    fn to_argument(&self) -> Argument {
        Argument::Text {
            value: self.to_owned(),
        }
    }
}
impl<T: IntoArgument + ?Sized> IntoArgument for &T {
    fn to_argument(&self) -> Argument {
        (*self).to_argument()
    }
}
impl IntoArgument for bool {
    fn to_argument(&self) -> Argument {
        Argument::Boolean { value: *self }
    }
}

macro_rules! scalar_integer {
    ($($ty:ty),* $(,)?) => {$(
        impl IntoArgument for $ty {
            fn to_argument(&self) -> Argument { Argument::Number { value: *self as f64 } }
        }
    )*};
}
scalar_integer!(i8, i16, i32, u8, u16, u32);

impl IntoArgument for TroxNumber {
    fn to_argument(&self) -> Argument {
        Argument::Number { value: self.0 }
    }
}
impl IntoArgument for TermArgument {
    fn to_argument(&self) -> Argument {
        Argument::Term {
            term_id: self.term_id.clone(),
            form: self.form.clone(),
            number: self.number,
        }
    }
}

/// Finite floating-point scalar accepted by the Trox wire model.
#[derive(Debug, Clone, Copy, PartialEq)]
pub struct TroxNumber(f64);

impl TroxNumber {
    /// Validates and normalizes a floating-point scalar.
    pub fn new(value: f64) -> Result<Self, TroxValueError> {
        if !value.is_finite() {
            return Err(TroxValueError::new(
                "trox.invalid-number",
                "Trox numbers must be finite",
            ));
        }
        Ok(Self(if value == 0.0 { 0.0 } else { value }))
    }

    /// Returns the validated numeric value.
    pub fn get(self) -> f64 {
        self.0
    }
}

/// Non-negative safe integer accepted by selectors and numbered terms.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct TroxInteger(u64);

impl TroxInteger {
    /// Validates that `value` does not exceed 2^53 - 1.
    pub fn new(value: u64) -> Result<Self, TroxValueError> {
        if value > MAX_SAFE_INTEGER {
            return Err(TroxValueError::new(
                "trox.invalid-selector-number",
                "selector integer exceeds 2^53 - 1",
            ));
        }
        Ok(Self(value))
    }
    /// Returns the validated integer value.
    pub fn get(self) -> u64 {
        self.0
    }
}

impl From<u8> for TroxInteger {
    fn from(value: u8) -> Self {
        Self(value.into())
    }
}
impl From<u16> for TroxInteger {
    fn from(value: u16) -> Self {
        Self(value.into())
    }
}
impl From<u32> for TroxInteger {
    fn from(value: u32) -> Self {
        Self(value.into())
    }
}

pub(crate) fn validate_stable_id(value: &str, label: &str) -> Result<(), TroxValueError> {
    let valid = !value.is_empty()
        && value.len() <= 96
        && value.is_ascii()
        && value.as_bytes()[0].is_ascii_lowercase()
        && !value.ends_with(['.', '-'])
        && value.split(['.', '-']).all(|part| {
            !part.is_empty()
                && part
                    .bytes()
                    .all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit())
        });
    if valid {
        Ok(())
    } else {
        Err(TroxValueError::new(
            "trox.invalid-stable-id",
            format!("invalid {label} `{value}`"),
        ))
    }
}

pub(crate) fn validate_placeholder_name(value: &str) -> bool {
    !value.is_empty()
        && value.len() <= 64
        && value.is_ascii()
        && value.as_bytes()[0].is_ascii_lowercase()
        && value.split('_').all(|part| {
            !part.is_empty()
                && part
                    .bytes()
                    .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit())
        })
}

pub(crate) fn validate_nfc(value: &str, label: &str) -> Result<(), TroxValueError> {
    if value.nfc().eq(value.chars()) {
        Ok(())
    } else {
        Err(TroxValueError::new(
            "trox.non-nfc",
            format!("{label} must be NFC"),
        ))
    }
}

pub(crate) fn placeholders(text: &str) -> Result<BTreeSet<String>, TroxValueError> {
    validate_nfc(text, "source text")?;
    let mut names = BTreeSet::new();
    let bytes = text.as_bytes();
    let mut index = 0;
    while index < bytes.len() {
        match bytes[index] {
            b'{' if bytes.get(index + 1) == Some(&b'{') => index += 2,
            b'}' if bytes.get(index + 1) == Some(&b'}') => index += 2,
            b'{' => {
                let rest = &text[index + 1..];
                let Some(end) = rest.find('}') else {
                    return Err(TroxValueError::new("trox.invalid-braces", "unclosed `{`"));
                };
                let name = &rest[..end];
                if !validate_placeholder_name(name) {
                    return Err(TroxValueError::new(
                        "trox.invalid-placeholder",
                        format!("invalid placeholder `{{{name}}}`"),
                    ));
                }
                names.insert(name.to_owned());
                index += end + 2;
            }
            b'}' => return Err(TroxValueError::new("trox.invalid-braces", "unmatched `}`")),
            _ => index += 1,
        }
    }
    Ok(names)
}

pub(crate) fn validate_identity(identity: &IdentityDescriptor) -> Result<(), TroxValueError> {
    if identity.identity_version != 1 {
        return Err(TroxValueError::new(
            "trox.identity-version",
            "identity version must be 1",
        ));
    }
    if let Some(meaning) = &identity.meaning {
        validate_stable_id(meaning, "meaning")?;
    }
    let mut count = 0;
    validate_pattern(&identity.pattern, 0, &mut count)
}

fn validate_pattern(
    pattern: &Pattern,
    depth: usize,
    count: &mut usize,
) -> Result<(), TroxValueError> {
    *count += 1;
    if *count > MAX_PATTERN_NODES {
        return Err(TroxValueError::new(
            "trox.pattern-limit",
            "pattern exceeds 4,096 nodes",
        ));
    }
    if depth > MAX_SELECTOR_DEPTH {
        return Err(TroxValueError::new(
            "trox.selector-depth",
            "pattern exceeds 16 nested selectors",
        ));
    }
    match pattern {
        Pattern::Text { text } => {
            placeholders(text)?;
        }
        Pattern::Plural { branches } | Pattern::Ordinal { branches } => {
            if branches.is_empty() || branches.len() > MAX_SELECTOR_BRANCHES {
                return Err(TroxValueError::new(
                    "trox.branch-limit",
                    "numeric selector must have 1..=256 branches",
                ));
            }
            let is_ordinal = matches!(pattern, Pattern::Ordinal { .. });
            let mut has_other = false;
            let mut previous: Option<(u8, u64)> = None;
            for branch in branches {
                let order = match &branch.key {
                    NumericBranchKey::Exact { exact } => {
                        if *exact > MAX_SAFE_INTEGER {
                            return Err(TroxValueError::new(
                                "trox.invalid-selector-number",
                                "exact branch integer exceeds 2^53 - 1",
                            ));
                        }
                        (0, *exact)
                    }
                    NumericBranchKey::Plural { plural } if !is_ordinal => (
                        1,
                        PluralCategory::CANONICAL
                            .iter()
                            .position(|category| category == plural)
                            .unwrap() as u64,
                    ),
                    NumericBranchKey::Ordinal { ordinal } if is_ordinal => (
                        1,
                        PluralCategory::CANONICAL
                            .iter()
                            .position(|category| category == ordinal)
                            .unwrap() as u64,
                    ),
                    _ => {
                        return Err(TroxValueError::new(
                            "trox.branch-kind",
                            "numeric branch key kind differs from selector",
                        ));
                    }
                };
                if previous.is_some_and(|prior| prior >= order) {
                    return Err(TroxValueError::new(
                        "trox.branch-order",
                        "numeric branches are duplicate or noncanonical",
                    ));
                }
                previous = Some(order);
                has_other |= branch.key.category() == Some(PluralCategory::Other);
                validate_pattern(&branch.pattern, depth + 1, count)?;
            }
            if !has_other {
                return Err(TroxValueError::new(
                    "trox.missing-other",
                    "plural and ordinal selectors require `other`",
                ));
            }
        }
        Pattern::Select { branches } => {
            if branches.is_empty() || branches.len() > MAX_SELECTOR_BRANCHES {
                return Err(TroxValueError::new(
                    "trox.branch-limit",
                    "select must have 1..=256 branches",
                ));
            }
            if !matches!(
                branches.last(),
                Some(SelectIdentityBranch::Otherwise { .. })
            ) {
                return Err(TroxValueError::new(
                    "trox.missing-otherwise",
                    "select requires a final `otherwise`",
                ));
            }
            if branches[..branches.len() - 1]
                .iter()
                .any(|branch| matches!(branch, SelectIdentityBranch::Otherwise { .. }))
            {
                return Err(TroxValueError::new(
                    "trox.otherwise-order",
                    "otherwise must appear exactly once at the end",
                ));
            }
            for branch in branches {
                validate_pattern(branch.pattern(), depth + 1, count)?;
            }
        }
    }
    Ok(())
}

fn collect_placeholders(
    pattern: &Pattern,
    target: &mut BTreeSet<String>,
) -> Result<(), TroxValueError> {
    match pattern {
        Pattern::Text { text } => target.extend(placeholders(text)?),
        Pattern::Plural { branches } | Pattern::Ordinal { branches } => {
            for branch in branches {
                collect_placeholders(&branch.pattern, target)?;
            }
        }
        Pattern::Select { branches } => {
            for branch in branches {
                collect_placeholders(branch.pattern(), target)?;
            }
        }
    }
    Ok(())
}

pub(crate) fn validate_arguments(
    pattern: &Pattern,
    arguments: &BTreeMap<String, Argument>,
) -> Result<(), TroxValueError> {
    if arguments.len() > MAX_ARGUMENTS {
        return Err(TroxValueError::new(
            "trox.argument-limit",
            "message exceeds 256 arguments",
        ));
    }
    let mut expected = BTreeSet::new();
    collect_placeholders(pattern, &mut expected)?;
    let actual: BTreeSet<_> = arguments.keys().cloned().collect();
    if expected != actual {
        return Err(TroxValueError::new(
            "trox.argument-mismatch",
            format!("placeholder bindings differ: expected {expected:?}, got {actual:?}"),
        ));
    }
    for argument in arguments.values() {
        match argument {
            Argument::Text { value } => validate_nfc(value, "argument text")?,
            Argument::Number { value } if !value.is_finite() => {
                return Err(TroxValueError::new(
                    "trox.invalid-number",
                    "argument number is not finite",
                ));
            }
            Argument::Term {
                term_id,
                form,
                number,
            } => {
                validate_stable_id(term_id.as_str(), "term ID")?;
                if let Some(form) = form {
                    validate_stable_id(form, "term form")?;
                }
                if number.is_some_and(|value| value > MAX_SAFE_INTEGER) {
                    return Err(TroxValueError::new(
                        "trox.invalid-selector-number",
                        "term number exceeds 2^53 - 1",
                    ));
                }
            }
            Argument::Opaque { value } => {
                if value.format != "trox-localized-string" || !value.version.is_supported_v1() {
                    return Err(TroxValueError::new(
                        "trox.invalid-opaque-wire",
                        "opaque value has an invalid format or version",
                    ));
                }
                if !matches!(value.identity.pattern, Pattern::Text { .. })
                    || !value.arguments.is_empty()
                    || !value.selectors.is_empty()
                {
                    return Err(TroxValueError::new(
                        "trox.non-atomic-opaque",
                        "opaque value must be a text leaf without arguments or selectors",
                    ));
                }
                validate_identity(&value.identity)?;
                validate_arguments(&value.identity.pattern, &value.arguments)?;
                validate_selectors(&value.identity.pattern, &value.selectors)?;
                let ids = identity_id_pair(&value.identity)?;
                if value.entry_id != ids.0 || value.source_signature != ids.1 {
                    return Err(TroxValueError::new(
                        "trox.identity-mismatch",
                        "opaque value identity hash does not match its wire IDs",
                    ));
                }
                let contract = crate::value::contract_signature(
                    &value.identity,
                    &crate::value::schemas_from_arguments(&value.arguments),
                )
                .map_err(|error| TroxValueError::new("trox.contract", error.to_string()))?;
                if value
                    .contract_signature
                    .as_deref()
                    .is_some_and(|value| value != contract)
                    || (value.version == Version::V1_1 && value.contract_signature.is_none())
                {
                    return Err(TroxValueError::new(
                        "trox.contract-mismatch",
                        "opaque value contract signature does not match its arguments",
                    ));
                }
            }
            _ => {}
        }
    }
    Ok(())
}

pub(crate) fn validate_argument_schemas(
    pattern: &Pattern,
    arguments: &BTreeMap<String, ArgumentSchema>,
) -> Result<(), TroxValueError> {
    if arguments.len() > MAX_ARGUMENTS {
        return Err(TroxValueError::new(
            "trox.argument-limit",
            "message exceeds 256 arguments",
        ));
    }
    let mut expected = BTreeSet::new();
    collect_placeholders(pattern, &mut expected)?;
    let actual: BTreeSet<_> = arguments.keys().cloned().collect();
    if expected != actual {
        return Err(TroxValueError::new(
            "trox.argument-mismatch",
            format!("placeholder declarations differ: expected {expected:?}, got {actual:?}"),
        ));
    }
    for schema in arguments.values() {
        if let ArgumentSchema::Term {
            form: Some(form), ..
        } = schema
        {
            validate_stable_id(form, "term form")?;
        }
    }
    Ok(())
}

pub(crate) fn validate_selectors(
    pattern: &Pattern,
    selectors: &[SelectorRecord],
) -> Result<(), TroxValueError> {
    let mut expected = Vec::new();
    collect_selector_paths(pattern, &mut Vec::new(), &mut expected);
    expected.sort_by(|left, right| left.0.cmp(&right.0));
    let actual: Vec<_> = selectors
        .iter()
        .map(|record| {
            (
                record.path().to_vec(),
                match record {
                    SelectorRecord::Plural { .. } => "plural",
                    SelectorRecord::Ordinal { .. } => "ordinal",
                    SelectorRecord::Select { .. } => "select",
                },
            )
        })
        .collect();
    let expected_paths: Vec<_> = expected
        .iter()
        .map(|(path, kind, _)| (path.clone(), *kind))
        .collect();
    if expected_paths != actual {
        return Err(TroxValueError::new(
            "trox.selector-records",
            format!("selector records differ: expected {expected_paths:?}, got {actual:?}"),
        ));
    }
    for (record, (_, _, select_branches)) in selectors.iter().zip(expected) {
        match record {
            SelectorRecord::Plural { value, .. } | SelectorRecord::Ordinal { value, .. }
                if *value > MAX_SAFE_INTEGER =>
            {
                return Err(TroxValueError::new(
                    "trox.invalid-selector-number",
                    "selector integer exceeds 2^53 - 1",
                ));
            }
            SelectorRecord::Select {
                branch_keys, value, ..
            } => {
                if branch_keys.len() != select_branches {
                    return Err(TroxValueError::new(
                        "trox.selector-records",
                        "select branch key count differs from when branch count",
                    ));
                }
                value.validate()?;
                let mut unique = BTreeSet::new();
                for key in branch_keys {
                    key.validate()?;
                    if !unique.insert(key) {
                        return Err(TroxValueError::new(
                            "trox.duplicate-selector-key",
                            "select branch keys must be unique",
                        ));
                    }
                }
                if branch_keys
                    .iter()
                    .any(|key| std::mem::discriminant(key) != std::mem::discriminant(value))
                {
                    return Err(TroxValueError::new(
                        "trox.selector-key-type",
                        "select keys must have one JSON type",
                    ));
                }
            }
            _ => {}
        }
    }
    Ok(())
}

fn collect_selector_paths(
    pattern: &Pattern,
    path: &mut Vec<usize>,
    target: &mut Vec<(Vec<usize>, &'static str, usize)>,
) {
    match pattern {
        Pattern::Text { .. } => {}
        Pattern::Plural { branches } | Pattern::Ordinal { branches } => {
            target.push((
                path.clone(),
                if matches!(pattern, Pattern::Ordinal { .. }) {
                    "ordinal"
                } else {
                    "plural"
                },
                0,
            ));
            for (index, branch) in branches.iter().enumerate() {
                path.push(index);
                collect_selector_paths(&branch.pattern, path, target);
                path.pop();
            }
        }
        Pattern::Select { branches } => {
            target.push((path.clone(), "select", branches.len().saturating_sub(1)));
            for (index, branch) in branches.iter().enumerate() {
                path.push(index);
                collect_selector_paths(branch.pattern(), path, target);
                path.pop();
            }
        }
    }
}

/// Derives the canonical short entry ID and full source signature for an identity.
pub fn identity_ids(identity: &IdentityDescriptor) -> Result<(String, String), TroxValueError> {
    validate_identity(identity)?;
    identity_id_pair(identity)
}

/// Derives the canonical short row ID for an expansion descriptor.
pub fn expansion_row_id<T: Serialize>(expansion: &T) -> Result<String, TroxValueError> {
    let bytes = signature(expansion)
        .map_err(|error| TroxValueError::new("trox.expansion", error.to_string()))?;
    Ok(short_id("row1_", &bytes))
}

/// Derives the full revision ID for a serializable bundle revision value.
pub fn revision_id<T: Serialize>(revision: &T) -> Result<String, TroxValueError> {
    Ok(format!(
        "rev1_{}",
        signature_hex(revision)
            .map_err(|error| TroxValueError::new("trox.revision", error.to_string()))?
    ))
}