fix(parser): canonical ABI for flags<N> (LS-A-20) (#157)

parser::convert_wp_defined_type mapped Component-Model flags<N> to
ComponentValType::Record(N × Bool), so downstream canonical-ABI
helpers computed flat=N, size=N bytes, align=1.

Spec for flags<N>:
- flat_count = ceil(N/32) i32 storage words
- size = ceil(N/8) padded to power-of-2 storage class
- align ∈ {1, 2, 4} from the storage class

Concrete impact: flags<17> as a parameter had flat=17 in meld but
flat=1 per spec. Resolver's params-ptr threshold fires at >16, so meld
flipped into params-ptr calling convention while producer kept the
flat path. Smaller N (flags<9>) produced wrong size (9 vs 2) and wrong
alignment.

Bug existed since the Flags arm was added (~2026-03-09), ~2 months
multiple releases. Wasm validator doesn't catch it because the
truncated layout is internally consistent within meld's pipeline.

Fix:
- New ComponentValType::Flags(Vec<String>) variant
- Parser's Flags arm produces it directly
- Explicit Flags arms in flat_count / canonical_abi_align /
  canonical_abi_size_unpadded / flat_byte_size /
  collect_return_area_type_slots / cabi_size_align /
  flat_component_val_type_resolved / resolve_component_val_type
- u32::div_ceil(32) for word count (overflow-safe, Rust 1.73+ stable
  API; replaces (n + 31) / 32 which clippy now flags)

Tests (2 new):
- ls_a_20_flags_canonical_abi_matches_spec (N=1/8/9/17/32/33)
- ls_a_20_flags_parser_produces_flags_variant (wat round-trip)

LS-A-20 added to safety/stpa/loss-scenarios.yaml under UCA-P-10 with
approved status. Discovered by the post-v0.8.0 Mythos delta-pass on
parser.rs.

Refs: LS-A-20 (UCA-P-10, H-4, H-4.1)

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: avrabe

CHANGELOG.md

@@ -49,6 +49,23 @@ All notable changes to this project will be documented in this file.
   is the right structural mitigation), but the output is now
   reproducible across runs.
 
+- **`flags<N>` canonical ABI silently modeled as `Record<N × Bool>`**
+  (LS-A-20, UCA-P-10, H-4 / H-4.1). `parser.rs::convert_wp_defined_type`
+  mapped a Component-Model `flags<N>` to `Record(N × Bool)`, so the
+  downstream canonical-ABI helpers (`flat_count`,
+  `canonical_abi_size_unpadded`, `canonical_abi_align`, etc.) computed
+  flat=N, size=N bytes, align=1. The spec requires flat=ceil(N/32) i32
+  words, size=ceil(N/8) padded to power-of-2 storage class, align ∈
+  {1, 2, 4}. A function taking `flags<17>` crossed meld's params-ptr
+  threshold (`total_flat_params > 16`) while the producer kept on the
+  flat path — silent calling-convention mismatch between fused and
+  composed paths. Bug shipped since March 2026 (~2 months, multiple
+  releases). Fix adds `ComponentValType::Flags(Vec<String>)` variant,
+  has the parser produce it directly, and adds explicit Flags arms to
+  every canonical-ABI function that walks ComponentValType. Regression
+  pinned by `ls_a_20_flags_canonical_abi_matches_spec` (covers
+  N=1/8/9/17/32/33) and `ls_a_20_flags_parser_produces_flags_variant`.
+
 ### Added
 
 - **Mythos delta-pass CI gate** (`.github/workflows/mythos-gate.yml`,

meld-core/src/adapter/fact.rs

@@ -178,6 +178,18 @@ pub(crate) fn cabi_size_align(ty: &crate::parser::ComponentValType) -> (u32, u32
             let body = align_up(1, align) + max_size;
             (align_up(body, align), align)
         }
+        CVT::Flags(names) => {
+            // flags<N>: ceil(N/8) bytes padded to power-of-2 storage
+            // class; align ∈ {1, 2, 4} per LS-A-20.
+            let n = names.len() as u32;
+            if n <= 8 {
+                (1, 1)
+            } else if n <= 16 {
+                (2, 2)
+            } else {
+                (4u32.saturating_mul(n.div_ceil(32)), 4)
+            }
+        }
         CVT::Own(_) | CVT::Borrow(_) | CVT::Type(_) => (4, 4),
     }
 }

meld-core/src/component_wrap.rs

@@ -2342,7 +2342,9 @@ pub(crate) fn resolve_component_val_type(
                 })
                 .collect(),
         ),
-        CVT::Primitive(_) | CVT::String | CVT::Own(_) | CVT::Borrow(_) => ty.clone(),
+        CVT::Primitive(_) | CVT::String | CVT::Own(_) | CVT::Borrow(_) | CVT::Flags(_) => {
+            ty.clone()
+        }
     }
 }
 
@@ -2454,6 +2456,13 @@ fn flat_component_val_type_resolved(
         parser::ComponentValType::Own(_) | parser::ComponentValType::Borrow(_) => {
             vec![wasm_encoder::ValType::I32]
         }
+        parser::ComponentValType::Flags(names) => {
+            // flags<N> flattens to ceil(N/32) i32 storage words per
+            // canonical ABI (LS-A-20).
+            let n = names.len() as u32;
+            let words = n.div_ceil(32);
+            vec![ValType::I32; words as usize]
+        }
     }
 }
 

meld-core/src/parser.rs

@@ -405,6 +405,17 @@ pub enum ComponentValType {
     List(Box<ComponentValType>),
     FixedSizeList(Box<ComponentValType>, u32),
     Record(Vec<(String, ComponentValType)>),
+    /// Component-Model `flags<N>`. The vector stores the flag names (for
+    /// diagnostics); only the count `N = names.len()` participates in the
+    /// canonical-ABI layout calculations (`flat_count = ceil(N/32)`,
+    /// `size = ceil(N/8)` padded, `align` from storage class).
+    ///
+    /// Prior to LS-A-20, flags<N> was modelled as `Record<N × Bool>`,
+    /// which made the canonical-ABI layout calculations return N for
+    /// flat count, N bytes for size, and 1 for align — a silent
+    /// divergence from the spec that crossed the `total_flat_params > 16`
+    /// params-ptr threshold for any flags<17+> argument.
+    Flags(Vec<String>),
     Variant(Vec<(String, Option<ComponentValType>)>),
     Tuple(Vec<ComponentValType>),
     Option(Box<ComponentValType>),
@@ -1455,6 +1466,11 @@ impl ParsedComponent {
             ComponentValType::FixedSizeList(elem, len) => {
                 self.flat_byte_size(elem).saturating_mul(*len)
             }
+            ComponentValType::Flags(names) => {
+                // flats[ceil(N/32)] i32 storage words = 4 bytes each.
+                let n = names.len() as u32;
+                4u32.saturating_mul(n.div_ceil(32))
+            }
             ComponentValType::Own(_) | ComponentValType::Borrow(_) => 4,
         }
     }
@@ -1792,6 +1808,22 @@ impl ParsedComponent {
                     is_pointer_pair: false,
                 });
             }
+            ComponentValType::Flags(names) => {
+                // flags<N>: ceil(N/8) bytes padded to its storage class.
+                let n = names.len() as u32;
+                let size = if n <= 8 {
+                    1
+                } else if n <= 16 {
+                    2
+                } else {
+                    4u32.saturating_mul(n.div_ceil(32))
+                };
+                out.push(ReturnAreaSlot {
+                    byte_offset: base,
+                    byte_size: size,
+                    is_pointer_pair: false,
+                });
+            }
         }
     }
 
@@ -2569,6 +2601,11 @@ impl ParsedComponent {
             ComponentValType::FixedSizeList(elem, len) => {
                 self.flat_count(elem).saturating_mul(*len)
             }
+            ComponentValType::Flags(names) => {
+                // flags<N> flattens to ceil(N/32) i32 storage words per
+                // the Component Model canonical ABI.
+                (names.len() as u32).div_ceil(32)
+            }
             ComponentValType::Own(_) | ComponentValType::Borrow(_) => 1,
         }
     }
@@ -2630,6 +2667,21 @@ impl ParsedComponent {
                 }
                 4
             }
+            ComponentValType::Flags(names) => {
+                // flags<N>: align to the smallest power-of-two storage
+                // class that holds N bits. Per the Component Model
+                // canonical ABI: N≤8 → 1, N≤16 → 2, else 4 (32-bit
+                // storage classes; flags<33+> uses an array of i32
+                // which still aligns to 4).
+                let n = names.len() as u32;
+                if n <= 8 {
+                    1
+                } else if n <= 16 {
+                    2
+                } else {
+                    4
+                }
+            }
             ComponentValType::Own(_) | ComponentValType::Borrow(_) => 4,
         }
     }
@@ -2717,6 +2769,25 @@ impl ParsedComponent {
                     .unwrap_or(0);
                 align_up(ds, max_case_align).saturating_add(ok_s.max(err_s))
             }
+            ComponentValType::Flags(names) => {
+                // flags<N>: ceil(N/8) bytes, packed in the smallest
+                // storage class. Per Component Model canonical ABI:
+                //   N≤8:  1 byte
+                //   N≤16: 2 bytes (1 u16)
+                //   N≤32: 4 bytes (1 u32)
+                //   N≤64: 8 bytes (2 u32s)
+                //   etc.
+                // Storage scales as ceil(N/32) i32 words past N=32.
+                let n = names.len() as u32;
+                if n <= 8 {
+                    1
+                } else if n <= 16 {
+                    2
+                } else {
+                    // 4 bytes per i32 word; ceil(N/32) words.
+                    4u32.saturating_mul(n.div_ceil(32))
+                }
+            }
             ComponentValType::Type(idx) => {
                 if let Some(ct) = self.get_type_definition(*idx)
                     && let ComponentTypeKind::Defined(inner) = &ct.kind
@@ -3000,18 +3071,13 @@ fn convert_wp_defined_type(dt: &wasmparser::ComponentDefinedType) -> ComponentTy
             ))
         }
         wasmparser::ComponentDefinedType::Flags(names) => {
-            // Flags are represented as a record of bools in the canonical ABI.
-            // For flat counting and pointer analysis, we use a record representation.
-            ComponentTypeKind::Defined(ComponentValType::Record(
-                names
-                    .iter()
-                    .map(|name| {
-                        (
-                            name.to_string(),
-                            ComponentValType::Primitive(PrimitiveValType::Bool),
-                        )
-                    })
-                    .collect(),
+            // flags<N> has its own canonical-ABI lowering — packed into
+            // `ceil(N/32)` i32 storage words, NOT a record of N bools.
+            // Use the dedicated `ComponentValType::Flags` variant so the
+            // canonical-ABI helpers compute the correct flat count,
+            // size, and alignment (LS-A-20).
+            ComponentTypeKind::Defined(ComponentValType::Flags(
+                names.iter().map(|n| n.to_string()).collect(),
             ))
         }
         wasmparser::ComponentDefinedType::FixedLengthList(ty, len) => ComponentTypeKind::Defined(
@@ -4258,4 +4324,107 @@ mod tests {
         assert_eq!(super::align_up(u32::MAX, 8), !7u32);
         assert_eq!(super::align_up(u32::MAX - 3, 8), !7u32);
     }
+
+    // ---------------------------------------------------------------
+    // LS-A-20 — flags<N> canonical ABI silently modeled as Record<Bool>
+    //
+    // Prior to the fix, convert_wp_defined_type mapped Flags(names) to
+    // ComponentValType::Record(names × Bool), so flat_count = N,
+    // canonical_abi_size_unpadded = N, canonical_abi_align = 1 — wrong
+    // for any N where ceil(N/32) ≠ N or N ≥ 9 (storage alignment).
+    // ---------------------------------------------------------------
+
+    fn empty_parsed_for_flags() -> ParsedComponent {
+        ParsedComponent {
+            name: None,
+            core_modules: vec![],
+            imports: vec![],
+            exports: vec![],
+            types: vec![],
+            instances: vec![],
+            canonical_functions: vec![],
+            sub_components: vec![],
+            component_aliases: vec![],
+            component_instances: vec![],
+            core_entity_order: vec![],
+            component_func_defs: vec![],
+            component_instance_defs: vec![],
+            component_type_defs: vec![],
+            original_size: 0,
+            original_hash: String::new(),
+            depth_0_sections: vec![],
+            p3_async_features: vec![],
+        }
+    }
+
+    fn flags_ty(n: usize) -> ComponentValType {
+        ComponentValType::Flags((0..n).map(|i| format!("f{i}")).collect())
+    }
+
+    #[test]
+    fn ls_a_20_flags_canonical_abi_matches_spec() {
+        let pc = empty_parsed_for_flags();
+        // flags<1>: flat=1 size=1 align=1
+        assert_eq!(pc.flat_count(&flags_ty(1)), 1);
+        assert_eq!(pc.canonical_abi_size_unpadded(&flags_ty(1)), 1);
+        assert_eq!(pc.canonical_abi_align(&flags_ty(1)), 1);
+        // flags<8>: flat=1 size=1 align=1
+        assert_eq!(pc.flat_count(&flags_ty(8)), 1);
+        assert_eq!(pc.canonical_abi_size_unpadded(&flags_ty(8)), 1);
+        assert_eq!(pc.canonical_abi_align(&flags_ty(8)), 1);
+        // flags<9>: flat=1 size=2 align=2  (crosses byte boundary)
+        assert_eq!(pc.flat_count(&flags_ty(9)), 1);
+        assert_eq!(pc.canonical_abi_size_unpadded(&flags_ty(9)), 2);
+        assert_eq!(pc.canonical_abi_align(&flags_ty(9)), 2);
+        // flags<17>: flat=1 size=4 align=4  (THE bug-trigger case;
+        // pre-fix returned flat=17 which crosses the params-ptr
+        // threshold at >16 in resolver.rs)
+        assert_eq!(pc.flat_count(&flags_ty(17)), 1);
+        assert_eq!(pc.canonical_abi_size_unpadded(&flags_ty(17)), 4);
+        assert_eq!(pc.canonical_abi_align(&flags_ty(17)), 4);
+        // flags<32>: flat=1 size=4 align=4
+        assert_eq!(pc.flat_count(&flags_ty(32)), 1);
+        assert_eq!(pc.canonical_abi_size_unpadded(&flags_ty(32)), 4);
+        // flags<33>: flat=2 size=8 align=4  (spills to 2 i32 words)
+        assert_eq!(pc.flat_count(&flags_ty(33)), 2);
+        assert_eq!(pc.canonical_abi_size_unpadded(&flags_ty(33)), 8);
+        assert_eq!(pc.canonical_abi_align(&flags_ty(33)), 4);
+    }
+
+    #[test]
+    fn ls_a_20_flags_parser_produces_flags_variant() {
+        // The wasmparser-bridge convert_wp_defined_type must now produce
+        // ComponentValType::Flags (not Record<Bool>) for `(flags ...)`
+        // declarations. We exercise via the wat round-trip pattern used
+        // elsewhere in this file.
+        let wat = r#"
+        (component
+          (type $f (flags "a" "b" "c" "d" "e" "f" "g" "h" "i"
+                          "j" "k" "l" "m" "n" "o" "p" "q"))
+          (core module $m (func (export "run") (param i32)))
+          (core instance (instantiate $m))
+        )
+        "#;
+        let bytes = match wat::parse_str(wat) {
+            Ok(b) => b,
+            Err(e) => {
+                eprintln!("skipping: wat crate cannot parse flags syntax: {e}");
+                return;
+            }
+        };
+        let comp = ComponentParser::new()
+            .parse(&bytes)
+            .expect("parse should succeed");
+        let flags_ty = comp.types.iter().find_map(|t| match &t.kind {
+            ComponentTypeKind::Defined(v @ ComponentValType::Flags(_)) => Some(v.clone()),
+            _ => None,
+        });
+        assert!(
+            flags_ty.is_some(),
+            "(flags ...) must parse to ComponentValType::Flags, not \
+             Record<Bool>"
+        );
+        // And verify flat_count is 1, not 17.
+        assert_eq!(comp.flat_count(&flags_ty.unwrap()), 1);
+    }
 }

safety/stpa/loss-scenarios.yaml

@@ -1001,6 +1001,61 @@ loss-scenarios:
     status: approved
     priority: high
 
+  - id: LS-A-20
+    title: flags<N> canonical ABI silently modeled as Record<N × Bool>
+    uca: UCA-P-10
+    hazards: [H-4, H-4.1]
+    type: inadequate-control-algorithm
+    scenario: >
+      `meld-core/src/parser.rs::convert_wp_defined_type` (the
+      `Flags(names) =>` arm at lines 3002-3015) mapped a Component-
+      Model `flags<N>` to `ComponentValType::Record(N × Bool)`. The
+      downstream canonical-ABI helpers (`flat_count`,
+      `canonical_abi_size_unpadded`, `canonical_abi_align`,
+      `flat_byte_size`, `collect_return_area_type_slots`,
+      `cabi_size_align` in adapter/fact.rs, and the wrapper's
+      `flat_component_val_type_resolved`) then computed
+      record-of-bool layouts: flat=N, size=N bytes, align=1.
+
+      The Component-Model canonical ABI for `flags<N>` is
+      fundamentally different: `flat = ceil(N/32)` i32 storage words,
+      `size = ceil(N/8)` padded to its storage class (1/2/4/8/...
+      bytes), `align ∈ {1, 2, 4}` from the power-of-2 storage class.
+
+      Concrete impact: a function taking `flags<17>` as a parameter
+      has flat_count=1 (one i32) per spec, but meld computed 17
+      flat values. The resolver's "params-ptr threshold" check fires
+      at `total_flat_params > 16` — meld would flip into the
+      params-ptr calling convention for the same function the
+      producer kept on the flat path, mismatching call conventions
+      between fused and composed paths. Smaller N values (e.g.
+      flags<9>) produced wrong size (9 bytes vs spec's 2) and wrong
+      align (1 vs spec's 2), so adjacent fields in records
+      mis-aligned.
+
+      The bug existed since the Flags arm was added in commit
+      d7a5ddb (2026-03-09, ~2 months and multiple releases). Wasm
+      validator does not catch it because the truncated layout is
+      internally consistent within meld's own pipeline; the
+      divergence only surfaces when the fused output is called by a
+      caller that lowered against the spec.
+
+      Fix: add a `ComponentValType::Flags(Vec<String>)` variant
+      (preserving names for diagnostics), have the parser produce it
+      directly, and add explicit Flags arms to every canonical-ABI
+      function that walks ComponentValType. The arms compute the
+      spec-correct flat / size / align values directly from the
+      flag count.
+    causal-factors:
+      - "Flags was modelled as a Record of Bools as a simplification \
+        at parser bridge time, no helper recognised the special-case canonical-ABI layout"
+      - "No upstream test exercised flags<N> for any N that exposed the divergence"
+      - "Bug shape matches UCA-P-10 ('unrecognized types mapped to Other'): \
+        a structurally valid type misclassified at the parse boundary, propagating \
+        wrong layout decisions to downstream code generators"
+    status: approved
+    priority: high
+
   # ==========================================================================
   # Merger scenario (discovered during gap analysis)
   # ==========================================================================