feat: store exact bytes in fixed arrays

Author: SebastienGllmt

cddl-matrix/roadmap.toml

@@ -149,7 +149,6 @@ entries = [
   "matrix.heterogeneous-array.occurrence-bounds",
   "matrix.open-array.optional-adjacency",
   "matrix.heterogeneous-array.atomic-bounds-handover",
-  "matrix.fixed-bytes.static-representation",
   "matrix.fixed-array.static-representation",
   "shared-carrier-delivery-requirements",
   "matrix.inline-group-occurrence-carrier",
@@ -685,29 +684,6 @@ verification_md = '''Probe h'cafe', b64'yv4=', h'CAFE', and a raw UTF-8 control
 due_action_md = '''Perform the ordered closeout actions only after fresh evidence satisfies the external predicate and the verification succeeds; otherwise retain the closeout and its accommodations.
 '''
 
-[[record]]
-id = "matrix.fixed-bytes.static-representation"
-title = "Fixed-byte representation optimization"
-
-[record.payload]
-kind = "work"
-body_md = '''### Fixed-byte representation optimization
-
-`bytes .size 32` can map to `[u8; 32]`: the representation itself carries the constraint. The
-`uint .size 1` → `u8` mapping is the shipped precedent, independently of the `TryFrom` door, which
-stays as the ergonomic entry point.
-
-'''
-work_state = "ready"
-work_intent = "optimize"
-work_kind = "optimization"
-risk = "wrong_public_api"
-acceptance_md = '''Map an exact bytes .size N value to [u8; N], retain TryFrom as the ergonomic entry point, and cover Rust, wasm, JSON, component, cross-crate, matrix, fixed-member, and recombination surfaces without changing fixed-array campaign identity.
-'''
-priority_band = "normal"
-priority_rationale_md = '''The exact byte-array representation carries its length invariant statically and has the shipped uint .size 1 to u8 precedent, while remaining an independent optimization.
-'''
-
 [[record]]
 id = "matrix.fixed-bytes.validator-corroboration"
 title = "When a rust `cddl` release fixes fixed-byte CBOR validation (README gap #17)"
@@ -2595,11 +2571,6 @@ source = "matrix.extern-execution-multifile"
 kind = "parent_of"
 target = "matrix.multifile.extern-shape-coverage"
 
-[[relation]]
-source = "matrix.fixed-array.static-representation"
-kind = "complements"
-target = "matrix.fixed-bytes.static-representation"
-
 [[relation]]
 source = "matrix.fixed-map-key-kinds"
 kind = "related"
@@ -2610,11 +2581,6 @@ source = "matrix.fixed-map-key-kinds"
 kind = "related"
 target = "matrix.nint-capability"
 
-[[relation]]
-source = "matrix.heterogeneous-array.occurrence-bounds"
-kind = "parent_of"
-target = "matrix.fixed-bytes.static-representation"
-
 [[relation]]
 source = "matrix.heterogeneous-array.occurrence-bounds"
 kind = "parent_of"

docs/docs/command_line_flags.mdx

@@ -210,7 +210,7 @@ cddl-codegen --input=example --output=export --binary-wrappers true
 :::info `--no-synthesized-rust-collection-aliases`
 Suppresses emission of Rust `pub type` aliases for generator-**synthesized** collection wrappers — currently a table rule's auto-named keys-list, e.g. `pub type FooList = Vec<Foo>;` minted for `tbl = { * foo => uint }`. Off by default.
 
-Rule-declared aliases are never suppressed, even when structurally transparent: an explicitly authored `foo_list = [* foo]` or `signature = bytes .size 32` is a human-written name and always stays. The suppression is emission-only — generated code references collections structurally (`Vec<Foo>`), never through the alias, so no field type or serialization changes, and the crate still compiles. Wasm-side wrappers and aliases are untouched.
+Rule-declared aliases are never suppressed, even when structurally transparent: an explicitly authored `foo_list = [* foo]` or `payload = bytes` is a human-written name and always stays. The suppression is emission-only — generated code references collections structurally (`Vec<Foo>`), never through the alias, so no field type or serialization changes, and the crate still compiles. Wasm-side wrappers and aliases are untouched. An exact byte rule such as `signature = bytes .size 32` is not this case: it is a checked wrapper whose native inner carrier is `[u8; 32]`.
 
 This is a flag rather than a default change because it removes public API (the crate's own synthesized aliases, not just extern-element ones) that existing consumers may depend on.
 

docs/docs/component_differences.mdx

@@ -64,6 +64,11 @@ There are **no wrapper classes** on this face. An array field is `list<t>`, a ma
 gaps second; the borrow-parameter rule above covers the ownership half, and WIT's type system has
 neither of the gaps (nested lists, lists of handles and nested `option`s are all expressible).
 
+An exact `bytes .size N` remains `list<u8>` in WIT even though native storage is `[u8; N]`.
+Direct constructors retain their loose list door; an optional or nested list/table position converts
+each list at the consuming boundary and returns the native `RangeCheck` through its `result` on a
+wrong length. Getters make the reverse array-to-list projection.
+
 The consequence is that **constraints move from the type to the door**. A `[+ t]` non-empty,
 bounded, or `@duplicates reject` **set** all despecialize to a plain `list<…>`, so the invariant
 is re-checked where the list is *consumed*: the constructor or setter returns

docs/docs/current_capacities.mdx

@@ -104,7 +104,12 @@ sidebar_position: 3
 > group `A`. Rename either symbol to avoid the collision. The scoped-symbol provenance grid needed
 > to remove this limitation is tracked in the matrix roadmap.
 
-* Length bounds - `foo = bytes .size (0..32)`
+* Length bounds - `foo = bytes .size (0..32)`. An **exact** byte window (`bytes .size N`,
+  including zero) is stored as `[u8; N]`; non-exact byte windows remain `Vec<u8>`. Constructors
+  deliberately accept a `Vec<u8>` and return `RangeCheck` on a wrong length before atomically
+  converting it to the static carrier. JSON follows the same invariant, including exact schema
+  cardinality. This is specific to byte strings: exact homogeneous CDDL array occurrences still
+  use their existing collection carriers.
 * Type-enforced homogeneous collections - bare `[* T]` maps to `Vec<T>` and `[+ T]` / `1* T` to `NonEmptyVec<T>`; every other supported array occurrence window maps to `BoundedVec<T, MIN, MAX>`, except `@duplicates reject`, which maps to `BoundedOrderedSet<T, MIN, MAX>` and enforces both order-preserving uniqueness and bounds at one door. A unique-key table maps `{ * K => V }` to a loose map, `{ + K => V }` to `NonEmptyMap<K, V>`, and every other window (including omitted exact-once) to `BoundedMap<K, V, MIN, MAX>`. A preserve table uses `PairMap` / `NonEmptyPairMap` for those loose forms and `BoundedPairMap<K, V, MIN, MAX>` for every other window; duplicate keys count separately and retain entry order. The bounded carriers route loose API, CBOR, JSON, wasm, and component input through their `TryFrom` door and expose no mutable carrier. See [Output format](output_format#non-empty-containers).
 * Integer width via `.size` - `u = uint .size 1` maps to `u8`, `uint .size 8` to `u64`, etc. `.size` on a signed `int` is **rejected gracefully**: per the spec semantics clarified by the RFC author ([cbor-wg/cddl#32](https://github.com/cbor-wg/cddl/issues/32)), `int = uint / nint` and a control distributes over the choice with `.size` undefined (never-matching) on `nint`, so `int .size N` means exactly the `uint .size N` window `0...(256**N)` — a signed `i{8N}` reading would mis-enforce it in both directions, and the aligned unsigned reading is spelled `uint .size N` directly. If you mean an N-byte signed integer, use the explicit range (e.g. `-9223372036854775808..9223372036854775807` maps to `i64`), which is fully supported.
 * Value ranges - integer (`foo = -10..3`, `bar = int .le 10`) and float (`f = 0.5..10.5`, `g = float64 .lt 10.5`) windows are both enforced (float checks are NaN-safe; see the range note below for the boundaries)

docs/docs/examples.mdx

@@ -269,7 +269,7 @@ pub struct Limitations {
     pub u_64: u64,
     pub i_8: i8,
     pub i_64: i64,
-    pub hash32: Vec<u8>,
+    pub hash32: [u8; 32],
     pub bounded: String,
 }
 
@@ -283,8 +283,24 @@ impl Limitations {
         i_64: i64,
         hash32: Vec<u8>,
         bounded: String,
-    ) -> Self {
-        Self {
+    ) -> Result<Self, DeserializeError> {
+        let hash32: [u8; 32] =
+            hash32
+                .try_into()
+                .map_err(|bytes: Vec<u8>| DeserializeFailure::RangeCheck {
+                    found: bytes.len() as i128,
+                    min: Some(32),
+                    max: Some(32),
+                })?;
+        if bounded.len() < 10 || bounded.len() > 20 {
+            return Err(DeserializeFailure::RangeCheck {
+                found: bounded.len() as i128,
+                min: Some(10),
+                max: Some(20),
+            }
+            .into());
+        }
+        Ok(Self {
             u_8,
             u_16,
             u_32,
@@ -293,7 +309,7 @@ impl Limitations {
             i_64,
             hash32,
             bounded,
-        }
+        })
     }
 }
 ```
@@ -1150,4 +1166,3 @@ impl TypeChoice {
 
 
 
-

docs/docs/wasm_differences.mdx

@@ -128,7 +128,10 @@ rather than bare vectors.
 
 Secondarily, the wrapper also covers element types `wasm_bindgen` can't put in a bare `Vec` at all:
 `Vec<bool>` (no `VectorIntoWasmAbi` for bool) and doubly-nested types like `Vec<Vec<T>>` (which
-includes any array of byte strings, since `bytes` is already `Vec<u8>`).
+includes any array of byte strings, since a non-exact `bytes` value is already `Vec<u8>`).
+An exact `bytes .size N` is `[u8; N]` in Rust but still crosses wasm as a `Vec<u8>`: getters copy
+the array into that list, while a direct constructor may keep the loose list door and collection
+`add`/`insert` paths return `JsError` if their stored-carrier handover finds a wrong length.
 
 Text arrays do **not** get a list wrapper: `wasm_bindgen` exposes `Vec<String>` directly (a JS
 string array, in both parameter and return position), and strings are **copied** at the boundary,