feat(s4): dual-track data dictionary (Stage S4)

Tasks T043–T052 (US5). One normalized dictionary source feeds both tracks
(Constitution Principle IV).

truefix-dict:
- Normalized dictionary format (authored from the FIX spec; no QuickFIX/J XML
  copied) + parser: fields/types/enums, header/trailer, message required/optional.
- Runtime DataDictionary::validate with toggles (ValidateFieldsHaveValues,
  AllowUnknownMsgFields, ValidateUserDefinedFields, required-field + type/enum +
  field-membership checks) and two rejection layers: session-level (dictionary
  failures) vs business-level (unknown MsgType).
- build.rs codegen: per-version MsgType constants + a content hash; runtime asserts
  its parsed hash equals the generated *_DICT_HASH (proves single source).
- FIXT 1.1 transport/application split with DefaultApplVerID resolution.
- Bundled subset dictionaries: FIX.4.4, FIXT.1.1, FIX.5.0.

truefix-session:
- Optional inbound validation hook (set_dictionary): invalid in-order application
  messages produce a Reject (35=3, SessionRejectReason) or BusinessMessageReject
  (35=j); admin messages are not dictionary-validated. Opt-in, so existing flows
  are unchanged.

Tests: 21 dict tests (parse, 8 toggle cases, rejection layers, FIXT split,
dual-track hash) + 4 session validation-hook tests. 74 workspace tests green;
fmt/clippy -D warnings clean.

Scope note: dictionaries are working subsets and codegen emits MsgType constants +
hash; full per-version breadth and richer typed-message codegen are S7.

Author: zhangjiayin

Cargo.lock

@@ -32,6 +32,7 @@ tracing = "0.1"
 metrics = "0.24"
 async-trait = "0.1"
 truefix-core = { path = "crates/truefix-core" }
+truefix-dict = { path = "crates/truefix-dict" }
 truefix-session = { path = "crates/truefix-session" }
 truefix-transport = { path = "crates/truefix-transport" }
 truefix-config = { path = "crates/truefix-config" }

Cargo.toml

@@ -77,6 +77,14 @@ impl FieldMap {
         })
     }
 
+    /// Iterate the top-level fields (skipping repeating groups), in order.
+    pub fn fields(&self) -> impl Iterator<Item = &Field> {
+        self.members.iter().filter_map(|m| match m {
+            Member::Field(f) => Some(f),
+            Member::Group { .. } => None,
+        })
+    }
+
     /// Internal: ordered members, for the encoder.
     pub(crate) fn members(&self) -> &[Member] {
         &self.members

crates/truefix-core/src/field_map.rs

@@ -8,5 +8,9 @@ repository.workspace = true
 description = "FIX data dictionary: build-time codegen + runtime validation (dual-track)."
 publish = false
 
+[dependencies]
+truefix-core.workspace = true
+thiserror.workspace = true
+
 [lints]
 workspace = true

crates/truefix-dict/Cargo.toml

@@ -0,0 +1,61 @@
+//! Build-time codegen (dual-track, Constitution Principle IV).
+//!
+//! Reads the same normalized dictionary sources the runtime loads, and generates per-version
+//! message-type constants plus a content hash. The runtime asserts its parsed hash equals the
+//! generated one, proving codegen and runtime derive from one source.
+
+use std::env;
+use std::fmt::Write as _;
+use std::fs;
+use std::path::Path;
+
+fn fnv1a(bytes: &[u8]) -> u64 {
+    let mut hash: u64 = 0xcbf2_9ce4_8422_2325;
+    for &b in bytes {
+        hash ^= u64::from(b);
+        hash = hash.wrapping_mul(0x0000_0100_0000_01b3);
+    }
+    hash
+}
+
+fn main() {
+    let manifest = env::var("CARGO_MANIFEST_DIR").expect("CARGO_MANIFEST_DIR");
+    let out_dir = env::var("OUT_DIR").expect("OUT_DIR");
+    let mut code = String::new();
+    code.push_str("// @generated by build.rs from dict-src/normalized — do not edit.\n");
+
+    for (name, file) in [
+        ("FIX44", "FIX44.fixdict"),
+        ("FIXT11", "FIXT11.fixdict"),
+        ("FIX50", "FIX50.fixdict"),
+    ] {
+        let path = Path::new(&manifest).join("dict-src/normalized").join(file);
+        println!("cargo:rerun-if-changed={}", path.display());
+        let bytes = fs::read(&path).unwrap_or_else(|e| panic!("read {}: {e}", path.display()));
+        let hash = fnv1a(&bytes);
+        let _ = writeln!(code, "/// Content hash of the {name} dictionary source.");
+        let _ = writeln!(code, "pub const {name}_DICT_HASH: u64 = {hash};");
+
+        let module = name.to_lowercase();
+        let _ = writeln!(
+            code,
+            "/// Generated MsgType constants for the {name} dictionary."
+        );
+        let _ = writeln!(code, "pub mod {module}_msgs {{");
+        for line in String::from_utf8_lossy(&bytes).lines() {
+            let line = line.trim();
+            if let Some(rest) = line.strip_prefix("message ") {
+                let mut it = rest.split_whitespace();
+                if let (Some(msg_type), Some(msg_name)) = (it.next(), it.next()) {
+                    let ident = msg_name.to_uppercase();
+                    let _ = writeln!(code, "    /// MsgType for {msg_name}.");
+                    let _ = writeln!(code, "    pub const {ident}: &str = {msg_type:?};");
+                }
+            }
+        }
+        let _ = writeln!(code, "}}");
+    }
+
+    let dest = Path::new(&out_dir).join("generated.rs");
+    fs::write(&dest, code).unwrap_or_else(|e| panic!("write generated.rs: {e}"));
+}

crates/truefix-dict/build.rs

@@ -0,0 +1,50 @@
+# TrueFix normalized dictionary — FIX.4.4 (subset).
+# Authored from the FIX 4.4 specification (field numbers/names are protocol facts).
+# Format (one directive per line; '#' comments):
+#   version <BeginString>
+#   field <tag> <Name> <TYPE> [<enumValue> ...]
+#   header <tag> ...
+#   trailer <tag> ...
+#   message <MsgType> <Name> [req:<tag,tag,...>] [opt:<tag,tag,...>]
+version FIX.4.4
+
+field 8 BeginString STRING
+field 9 BodyLength LENGTH
+field 35 MsgType STRING
+field 34 MsgSeqNum SEQNUM
+field 49 SenderCompID STRING
+field 56 TargetCompID STRING
+field 52 SendingTime UTCTIMESTAMP
+field 43 PossDupFlag BOOLEAN
+field 122 OrigSendingTime UTCTIMESTAMP
+field 10 CheckSum STRING
+field 98 EncryptMethod INT 0 1 2 3 4 5 6
+field 108 HeartBtInt INT
+field 141 ResetSeqNumFlag BOOLEAN
+field 112 TestReqID STRING
+field 7 BeginSeqNo SEQNUM
+field 16 EndSeqNo SEQNUM
+field 36 NewSeqNo SEQNUM
+field 123 GapFillFlag BOOLEAN
+field 58 Text STRING
+field 45 RefSeqNum SEQNUM
+field 11 ClOrdID STRING
+field 21 HandlInst CHAR 1 2 3
+field 55 Symbol STRING
+field 54 Side CHAR 1 2 5 6
+field 60 TransactTime UTCTIMESTAMP
+field 38 OrderQty QTY
+field 40 OrdType CHAR 1 2 3 4
+field 44 Price PRICE
+
+header 8 9 35 34 49 56 52 43 122
+trailer 10
+
+message 0 Heartbeat opt:112
+message 1 TestRequest req:112
+message 2 ResendRequest req:7,16
+message 4 SequenceReset req:36 opt:123
+message 5 Logout opt:58
+message A Logon req:98,108 opt:141
+message 3 Reject req:45 opt:58
+message D NewOrderSingle req:11,21,55,54,60,40 opt:38,44

crates/truefix-dict/dict-src/normalized/FIX44.fixdict

@@ -0,0 +1,15 @@
+# TrueFix normalized dictionary — FIX.5.0 application layer (subset).
+# Application messages only; the session layer is provided by FIXT.1.1.
+version FIX.5.0
+
+field 11 ClOrdID STRING
+field 21 HandlInst CHAR 1 2 3
+field 55 Symbol STRING
+field 54 Side CHAR 1 2 5 6
+field 60 TransactTime UTCTIMESTAMP
+field 38 OrderQty QTY
+field 40 OrdType CHAR 1 2 3 4
+field 44 Price PRICE
+field 58 Text STRING
+
+message D NewOrderSingle req:11,21,55,54,60,40 opt:38,44,58

crates/truefix-dict/dict-src/normalized/FIX50.fixdict

@@ -0,0 +1,24 @@
+# TrueFix normalized dictionary — FIXT.1.1 transport (session) layer (subset).
+version FIXT.1.1
+
+field 8 BeginString STRING
+field 9 BodyLength LENGTH
+field 35 MsgType STRING
+field 34 MsgSeqNum SEQNUM
+field 49 SenderCompID STRING
+field 56 TargetCompID STRING
+field 52 SendingTime UTCTIMESTAMP
+field 10 CheckSum STRING
+field 98 EncryptMethod INT 0
+field 108 HeartBtInt INT
+field 141 ResetSeqNumFlag BOOLEAN
+field 1137 DefaultApplVerID STRING
+field 112 TestReqID STRING
+
+header 8 9 35 34 49 56 52
+trailer 10
+
+message 0 Heartbeat opt:112
+message 1 TestRequest req:112
+message 5 Logout
+message A Logon req:98,108,1137

crates/truefix-dict/dict-src/normalized/FIXT11.fixdict

@@ -0,0 +1,57 @@
+//! FIXT 1.1 transport/application dictionary separation.
+//!
+//! Under FIXT 1.1 the session (transport) layer and the application layer use **separate**
+//! dictionaries. The application dictionary is selected per-message by ApplVerID, falling back to
+//! the session's DefaultApplVerID.
+
+use std::collections::BTreeMap;
+
+use crate::model::DataDictionary;
+
+/// A transport dictionary plus one or more application dictionaries keyed by application version.
+#[derive(Debug, Clone)]
+pub struct FixtDictionaries {
+    transport: DataDictionary,
+    applications: BTreeMap<String, DataDictionary>,
+    default_appl_ver_id: Option<String>,
+}
+
+impl FixtDictionaries {
+    /// Create from a transport dictionary; add application dictionaries with
+    /// [`with_application`](Self::with_application).
+    pub fn new(transport: DataDictionary) -> Self {
+        Self {
+            transport,
+            applications: BTreeMap::new(),
+            default_appl_ver_id: None,
+        }
+    }
+
+    /// Register an application dictionary under an application version id (e.g. `"FIX.5.0"`).
+    pub fn with_application(
+        mut self,
+        appl_ver_id: impl Into<String>,
+        dict: DataDictionary,
+    ) -> Self {
+        self.applications.insert(appl_ver_id.into(), dict);
+        self
+    }
+
+    /// Set the DefaultApplVerID used when a message does not carry an explicit ApplVerID.
+    pub fn with_default_appl_ver_id(mut self, appl_ver_id: impl Into<String>) -> Self {
+        self.default_appl_ver_id = Some(appl_ver_id.into());
+        self
+    }
+
+    /// The transport (session-layer) dictionary.
+    pub fn transport(&self) -> &DataDictionary {
+        &self.transport
+    }
+
+    /// Resolve the application dictionary for an explicit `appl_ver_id`, falling back to the
+    /// DefaultApplVerID.
+    pub fn application_for(&self, appl_ver_id: Option<&str>) -> Option<&DataDictionary> {
+        let key = appl_ver_id.or(self.default_appl_ver_id.as_deref())?;
+        self.applications.get(key)
+    }
+}

crates/truefix-dict/src/fixt.rs

@@ -0,0 +1,12 @@
+//! Stable content hash (FNV-1a, 64-bit) used to prove the codegen track and the runtime track
+//! derive from the same dictionary source (Constitution Principle IV). The identical algorithm is
+//! duplicated in `build.rs`.
+
+pub(crate) fn fnv1a(bytes: &[u8]) -> u64 {
+    let mut hash: u64 = 0xcbf2_9ce4_8422_2325;
+    for &b in bytes {
+        hash ^= u64::from(b);
+        hash = hash.wrapping_mul(0x0000_0100_0000_01b3);
+    }
+    hash
+}