menuconform 0.1.0

data/lib/menuconform/solver.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Menuconform
+  # Cart solver: answers, per item, whether a valid cart exists (CART-001),
+  # whether the item's own defaults violate its constraints (CART-002), whether
+  # any valid cart totals above zero (CART-003), and whether equivalent carts
+  # can price differently (CART-004).
+  #
+  # Exactness notes:
+  # - Satisfiability is exact for groups of up to 14 options (subset
+  #   enumeration over distinct-count and total-unit constraints, with
+  #   recursive option selectability); beyond 14 it falls back to greedy
+  #   bounds, which can only over-report satisfiability (no false CART-001).
+  # - Max-total is a greedy upper approximation using each option's highest
+  #   resolvable price: CART-003 (max <= 0) therefore never false-positives.
+  # - CART-004 is a deterministic reachability scan, not a random fuzzer: it is
+  #   complete for the same-modifier-different-price class of ambiguity.
+  # - Items whose nesting is cyclic (STRUCT-005) are skipped entirely.
+  # - Groups a rule can't reason about (dangling refs) are skipped — STRUCT-002
+  #   owns those.
+  class Solver
+    EXACT_ENUM_LIMIT = 14
+
+    def initialize(menu)
+      @menu = menu
+    end
+
+    def findings
+      out = []
+      @menu.items_by_id.each_value do |item|
+        next if @menu.depth_info(item)[:cyclic]
+        unless item_satisfiable?(item)
+          out << Finding.new("CART-001", "item", item["id"],
+                             "no selection satisfies this item's modifier constraints — it cannot be ordered")
+          next
+        end
+        unless defaults_valid?(item)
+          out << Finding.new("CART-002", "item", item["id"],
+                             "the pre-selected defaults violate this item's own group constraints")
+        end
+        max = max_total(item)
+        if max <= 0
+          out << Finding.new("CART-003", "item", item["id"],
+                             "no valid cart totals above zero (maximum reachable total: #{max})")
+        end
+      end
+      out + ambiguities
+    end
+
+    # --- CART-001 -----------------------------------------------------------
+
+    def item_satisfiable?(item)
+      @menu.attached_group_ids(item).uniq.all? { |gid| group_satisfiable?(gid, []) }
+    end
+
+    def group_satisfiable?(gid, stack)
+      g = @menu.groups_by_id[gid]
+      return true if g.nil?          # dangling ref: STRUCT-002 owns it
+      return false if stack.include?(gid) # cycle: conservatively uncompletable
+
+      selectable = existing_options(g).select do |o|
+        (o["child_modifier_group_ids"] || []).all? { |c| group_satisfiable?(c, stack + [gid]) }
+      end
+      feasible_selection_exists?(g, selectable)
+    end
+
+    def feasible_selection_exists?(g, selectable)
+      min_sel = [g["min_select"] || 0, 0].max
+      max_sel = g["max_select"] || selectable.size
+      min_tu = g["min_total_units"]
+      max_tu = g["max_total_units"]
+
+      return false if min_sel > max_sel
+      # Empty selection is a valid answer for an optional group.
+      return true if min_sel.zero? && (min_tu.nil? || min_tu <= 0)
+      return false if selectable.empty? || min_sel > selectable.size
+
+      ranges = selectable.map { |o| unit_range(o) }
+      if ranges.size <= EXACT_ENUM_LIMIT
+        (1..(2**ranges.size - 1)).any? do |mask|
+          k = mask.digits(2).sum
+          next false if k < min_sel || k > max_sel
+          lo = 0
+          hi = 0
+          ranges.each_with_index do |r, i|
+            next if mask[i].zero?
+            lo += r[0]
+            hi += r[1]
+          end
+          (max_tu.nil? || lo <= max_tu) && (min_tu.nil? || hi >= min_tu)
+        end
+      else
+        # Greedy bounds: can only over-report satisfiability.
+        (min_sel..[max_sel, ranges.size].min).any? do |k|
+          lo = ranges.map(&:first).min(k).sum
+          hi = ranges.map(&:last).max(k).sum
+          (max_tu.nil? || lo <= max_tu) && (min_tu.nil? || hi >= min_tu)
+        end
+      end
+    end
+
+    # --- CART-002 -----------------------------------------------------------
+
+    # Defaults are invalid only when they VIOLATE constraints (exceed maxima or
+    # per-option quantity bounds). A required group with no default is normal:
+    # the agent completes the selection.
+    def defaults_valid?(item)
+      queue = @menu.attached_group_ids(item).dup
+      seen = Set.new
+      until queue.empty?
+        gid = queue.shift
+        next if seen.include?(gid)
+        seen << gid
+        g = @menu.groups_by_id[gid]
+        next unless g
+        defaults = existing_options(g).select { |o| (o["default_quantity"] || 0).positive? }
+        max_sel = g["max_select"]
+        return false if !max_sel.nil? && defaults.size > max_sel
+        max_tu = g["max_total_units"]
+        return false if !max_tu.nil? && defaults.sum { |o| o["default_quantity"] } > max_tu
+        defaults.each do |o|
+          return false if o["default_quantity"] > (o["max_quantity"] || 1)
+          min_q = o["min_quantity"] || 0
+          return false if min_q.positive? && o["default_quantity"] < min_q
+          queue.concat(o["child_modifier_group_ids"] || [])
+        end
+      end
+      true
+    end
+
+    # --- CART-003 -----------------------------------------------------------
+
+    IDENTITY = ->(p) { p }
+
+    def max_total(item)
+      total = item["price"]
+      (item["modifier_group_ids"] || []).uniq.each { |gid| total += max_contribution(gid, [], IDENTITY) }
+      slots = item["slots"] || []
+      unless slots.empty?
+        case item["slot_pricing"]
+        when "proportional"
+          slots.each do |s|
+            # Rounded half away from zero, per unit — the pinned IR semantics.
+            scale = ->(p) { (p * s["fraction"]).round }
+            (s["modifier_group_ids"] || []).uniq.each { |gid| total += max_contribution(gid, [], scale) }
+          end
+        when "max_slot"
+          # Charged as if the most expensive slot's selections applied to the
+          # whole item: each distinct group counts once, unscaled.
+          slots.flat_map { |s| s["modifier_group_ids"] || [] }.uniq.each do |gid|
+            total += max_contribution(gid, [], IDENTITY)
+          end
+        else # full_price
+          slots.each do |s|
+            (s["modifier_group_ids"] || []).uniq.each { |gid| total += max_contribution(gid, [], IDENTITY) }
+          end
+        end
+      end
+      total
+    end
+
+    def max_contribution(gid, stack, transform)
+      g = @menu.groups_by_id[gid]
+      return 0 if g.nil? || stack.include?(gid)
+
+      selectable = existing_options(g).select do |o|
+        (o["child_modifier_group_ids"] || []).all? { |c| group_satisfiable?(c, stack + [gid]) }
+      end
+      min_sel = [g["min_select"] || 0, 0].max
+      max_sel = g["max_select"] || selectable.size
+      return 0 if selectable.empty? || min_sel > max_sel || min_sel > selectable.size
+
+      budget = g["max_total_units"] || Float::INFINITY
+      candidates = selectable.map do |o|
+        unit = transform.call(max_unit_price(o))
+        range = unit_range(o)
+        units = unit.positive? ? range[1] : range[0]
+        kids = (o["child_modifier_group_ids"] || []).sum { |c| max_contribution(c, stack + [gid], transform) }
+        { unit: unit, units: units, kids: kids, value: (unit * units) + kids }
+      end.sort_by { |c| -c[:value] }
+
+      chosen = []
+      used = 0
+      candidates.each do |c|
+        forced = chosen.size < min_sel
+        break if !forced && chosen.size >= max_sel
+        next unless forced || c[:value].positive?
+        units = [c[:units], budget - used].min
+        units = 1 if forced && units < 1
+        next if units < 1
+        chosen << { unit: c[:unit], units: units, kids: c[:kids] }
+        used += units
+      end
+
+      chosen.sum { |c| (c[:unit] * c[:units]) + c[:kids] } - included_discount(g, chosen)
+    end
+
+    # Free-quantity discount applied to a chosen selection (pricing semantics,
+    # not choice): included_counting units = free units by allocation order;
+    # options = whole cheapest/most-expensive selected options free. Negative
+    # unit prices never benefit from a free slot.
+    def included_discount(g, chosen)
+      inc = g["included_quantity"] || 0
+      return 0 unless inc.positive?
+      allocation = g["included_allocation"] || "cheapest_first"
+      if (g["included_counting"] || "units") == "options"
+        ordered = chosen.sort_by { |c| c[:unit] }
+        ordered.reverse! if allocation == "most_expensive_first"
+        ordered.first(inc).sum { |c| [c[:unit], 0].max * c[:units] }
+      else
+        units = chosen.flat_map { |c| Array.new(c[:units]) { c[:unit] } }.sort
+        units.reverse! if allocation == "most_expensive_first"
+        units.first(inc).sum { |u| [u, 0].max }
+      end
+    end
+
+    # --- CART-004 -----------------------------------------------------------
+
+    # Two carts selecting the same (modifier, quantity) multiset must price
+    # identically. They can't when one modifier is reachable on the same item
+    # through links with different price signatures.
+    def ambiguities
+      out = []
+      @menu.items_by_id.each_value do |item|
+        signatures = Hash.new { |h, k| h[k] = Set.new }
+        @menu.reachable_group_ids(item).sort.each do |gid|
+          g = @menu.groups_by_id[gid]
+          existing_options(g).each do |o|
+            m = @menu.modifiers_by_id[o["modifier_id"]]
+            base = o.key?("price_override") ? o["price_override"] : m["price"]
+            cond = (o["conditional_prices"] || []).map { |c| [c["when_modifier_id"], c["price"]] }.sort
+            signatures[o["modifier_id"]] << [base, cond]
+          end
+        end
+        signatures.each do |mid, sigs|
+          next if sigs.size <= 1
+          out << Finding.new("CART-004", "item", item["id"],
+                             "modifier #{mid} is reachable at #{sigs.size} different prices on this item — " \
+                             "equivalent carts price differently")
+        end
+      end
+      out
+    end
+
+    private
+
+    def existing_options(g)
+      (g["options"] || []).select { |o| @menu.modifiers_by_id.key?(o["modifier_id"]) }
+    end
+
+    # [min units if selected, max units] for one option.
+    def unit_range(o)
+      max_q = o["max_quantity"] || 1
+      [[[o["min_quantity"] || 0, 1].max, max_q].min, max_q]
+    end
+
+    def max_unit_price(o)
+      m = @menu.modifiers_by_id[o["modifier_id"]]
+      base = o.key?("price_override") ? o["price_override"] : m["price"]
+      ([base] + (o["conditional_prices"] || []).map { |c| c["price"] }).max
+    end
+  end
+end

data/lib/menuconform/ucp_exporter.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Menuconform
+  # Exports a Menu IR document to the shopping catalog shapes of the pinned
+  # UCP spec (product / variant / product_option / price), reporting what the
+  # export loses as EXPORT- findings.
+  #
+  # The pinned draft's catalog model is retail-shaped: a product carries
+  # enumerable fixed-price variants defined by option combinations. A food
+  # menu maps onto that only where an item's price is fully determined by
+  # required single-select groups (sizes) — those become product options and
+  # variants. Everything else has no UCP home today:
+  # - optional / multi-select / quantity-bearing / nested modifier groups,
+  #   conditional prices, included quantities -> EXPORT-002 (dropped; the
+  #   modifier model is stashed in the non-standard `metadata` extension)
+  # - half/half slots, allergens, min_age, dietary (degraded to free tags),
+  #   availability windows, timed suspensions -> EXPORT-002
+  # - items whose price depends on a group that can't be a variant axis, or
+  #   whose variant space exceeds the enumeration cap -> EXPORT-001 (the item
+  #   cannot exist under the pinned draft)
+  #
+  # EXPORT- findings surface only through this stage (`menuconform export`),
+  # never through `check`: the check score judges the menu data, not the
+  # current gaps of the UCP draft.
+  class UcpExporter
+    UCP_SPEC_PIN = "2026-08-25"
+    DEFAULT_VARIANT_CAP = 50
+
+    def initialize(catalog:, variant_cap: DEFAULT_VARIANT_CAP)
+      @catalog = catalog
+      @variant_cap = variant_cap
+    end
+
+    # Returns { artifact: Hash, findings: [Finding] } (severities stamped).
+    def call(doc, reference_time: Time.now.utc)
+      menu = Menu.new(doc, reference_time: reference_time)
+      findings = []
+      products = []
+
+      findings << finding("EXPORT-002", "menu", doc["name"] || "(unnamed)",
+                          "menu-level service windows have no UCP catalog construct; agents will not know the ordering hours") if present?(doc["availability"])
+      findings << finding("EXPORT-002", "menu", doc["name"] || "(unnamed)",
+                          "special_hours (holiday/date exceptions) have no UCP catalog construct") if present?(doc["special_hours"])
+      menu.categories_by_id.each_value do |c|
+        next unless present?(c["availability"])
+        findings << finding("EXPORT-002", "category", c["id"],
+                            "category availability windows (dayparts) have no UCP catalog construct")
+      end
+
+      menu.items_by_id.each_value do |item|
+        product, item_findings = export_item(menu, item)
+        findings.concat(item_findings)
+        products << product if product
+      end
+
+      artifact = {
+        "ucp_spec_version" => UCP_SPEC_PIN,
+        "generated_by" => "menuconform #{VERSION}",
+        "catalog" => { "products" => products }
+      }
+      { artifact: artifact, findings: findings.each { |f| f.severity = @catalog.severity(f.rule) } }
+    end
+
+    private
+
+    def export_item(menu, item)
+      findings = []
+      axes = []
+      dropped = []
+      blockers = []
+
+      (item["modifier_group_ids"] || []).uniq.each do |gid|
+        g = menu.groups_by_id[gid]
+        next unless g # dangling: STRUCT-002's problem
+        if variant_axis?(menu, g)
+          axes << g
+        else
+          required = (g["min_select"] || 0).positive? || (g["min_total_units"] || 0).positive?
+          if required && priced_options?(menu, g)
+            blockers << gid
+          else
+            dropped << gid
+          end
+        end
+      end
+      slot_gids = (item["slots"] || []).flat_map { |s| s["modifier_group_ids"] || [] }.uniq
+      slot_gids.each do |gid|
+        g = menu.groups_by_id[gid]
+        blockers << gid if g && ((g["min_select"] || 0).positive? || (g["min_total_units"] || 0).positive?) && priced_options?(menu, g)
+      end
+
+      unless blockers.empty?
+        findings << finding("EXPORT-001", "item", item["id"],
+                            "price depends on selections in #{blockers.join(', ')}, which cannot become fixed-price " \
+                            "variants under the pinned UCP catalog model — this item cannot be represented")
+        return [nil, findings]
+      end
+
+      variant_count = axes.reduce(1) { |acc, g| acc * axis_options(menu, g).size }
+      if variant_count > @variant_cap
+        findings << finding("EXPORT-001", "item", item["id"],
+                            "#{variant_count} variants would be needed to enumerate the required selections " \
+                            "(cap #{@variant_cap}) — the configuration space does not fit UCP's variant model")
+        return [nil, findings]
+      end
+
+      findings.concat(lossiness_findings(menu, item, dropped, slot_gids))
+      [build_product(menu, item, axes), findings]
+    end
+
+    # A group can be a variant axis when exactly one option must be chosen and
+    # the choice fully determines its price contribution: no per-option
+    # quantities, no child groups, no conditional prices.
+    def variant_axis?(menu, g)
+      return false unless g["min_select"] == 1 && g["max_select"] == 1
+      return false if (g["min_total_units"] || 0) > 1
+      opts = axis_options(menu, g)
+      return false if opts.empty?
+      opts.all? do |o|
+        (o["max_quantity"] || 1) == 1 &&
+          (o["child_modifier_group_ids"] || []).empty? &&
+          (o["conditional_prices"] || []).empty?
+      end
+    end
+
+    def axis_options(menu, g)
+      (g["options"] || []).select { |o| menu.modifiers_by_id.key?(o["modifier_id"]) }
+    end
+
+    def priced_options?(menu, g)
+      axis_options(menu, g).any? { |o| resolved_price(menu, o) != 0 }
+    end
+
+    def resolved_price(menu, option)
+      option.key?("price_override") ? option["price_override"] : menu.modifiers_by_id[option["modifier_id"]]["price"]
+    end
+
+    def build_product(menu, item, axes)
+      currency = menu.doc["currency"]
+      combos = axes.reduce([[]]) do |acc, g|
+        acc.flat_map { |combo| axis_options(menu, g).map { |o| combo + [[g, o]] } }
+      end
+
+      variants = combos.map do |combo|
+        amount = item["price"] + combo.sum { |(_, o)| resolved_price(menu, o) }
+        labels = combo.map { |(_, o)| menu.modifiers_by_id[o["modifier_id"]]["name"] }
+        v = {
+          "id" => ([item["id"]] + combo.map { |(_, o)| o["modifier_id"] }).join("~"),
+          "title" => labels.empty? ? item["name"] : "#{item['name']} — #{labels.join(' / ')}",
+          "description" => description_of(item),
+          "price" => { "amount" => amount, "currency" => currency }
+        }
+        unless combo.empty?
+          v["options"] = combo.map do |(g, o)|
+            { "name" => g["name"], "label" => menu.modifiers_by_id[o["modifier_id"]]["name"], "id" => o["modifier_id"] }
+          end
+        end
+        v["availability"] = { "available" => false, "status" => "out_of_stock" } unless orderable?(menu, item)
+        v
+      end
+
+      amounts = variants.map { |v| v["price"]["amount"] }
+      product = {
+        "id" => item["id"],
+        "title" => item["name"],
+        "description" => description_of(item),
+        "price_range" => {
+          "min" => { "amount" => amounts.min, "currency" => currency },
+          "max" => { "amount" => amounts.max, "currency" => currency }
+        },
+        "variants" => variants
+      }
+      unless axes.empty?
+        product["options"] = axes.map do |g|
+          { "name" => g["name"],
+            "values" => axis_options(menu, g).map { |o| { "id" => o["modifier_id"], "label" => menu.modifiers_by_id[o["modifier_id"]]["name"] } } }
+        end
+      end
+      product["tags"] = item["dietary"] if item["dietary"]&.any?
+      metadata = metadata_stash(item)
+      product["metadata"] = metadata unless metadata.empty?
+      product
+    end
+
+    def lossiness_findings(menu, item, dropped, slot_gids)
+      out = []
+      id = item["id"]
+      unless dropped.empty?
+        out << finding("EXPORT-002", "item", id,
+                       "modifier group(s) #{dropped.join(', ')} have no UCP catalog construct — agents cannot customize this item")
+      end
+      if item["slots"]&.any?
+        out << finding("EXPORT-002", "item", id,
+                       "half/half slot construct (#{slot_gids.join(', ')}) has no UCP representation; fractional pricing semantics are lost")
+      end
+      if item["allergens"]
+        out << finding("EXPORT-002", "item", id,
+                       "allergen declarations survive only in the non-standard metadata extension — agents filtering by allergen will not see them")
+      end
+      if item["min_age"]
+        out << finding("EXPORT-002", "item", id,
+                       "min_age #{item['min_age']} has no catalog field; age gating is left to checkout-time policy")
+      end
+      if item["dietary"]&.any?
+        out << finding("EXPORT-002", "item", id,
+                       "dietary claims degraded to free-text tags (no defined vocabulary in the pinned draft)")
+      end
+      if present?(item["availability"])
+        out << finding("EXPORT-002", "item", id,
+                       "item availability windows have no UCP catalog construct")
+      end
+      if item["suspended_until"]
+        out << finding("EXPORT-002", "item", id,
+                       "timed suspension mapped to a bare out_of_stock flag; the automatic recovery time is lost")
+      end
+      out
+    end
+
+    def metadata_stash(item)
+      stash = {}
+      stash["allergens"] = item["allergens"] if item["allergens"]
+      stash["min_age"] = item["min_age"] if item["min_age"]
+      stash["availability"] = item["availability"] if present?(item["availability"])
+      stash.empty? ? {} : { "menuconform" => stash }
+    end
+
+    def orderable?(menu, item)
+      return false if item["active"] == false
+      raw = item["suspended_until"]
+      return true unless raw
+      t = begin
+        Time.iso8601(raw)
+      rescue ArgumentError
+        nil
+      end
+      t.nil? || t <= menu.reference_time
+    end
+
+    def description_of(entity)
+      { "plain" => entity["description"] || entity["name"] || "" }
+    end
+
+    def present?(value)
+      !value.nil? && !value.empty?
+    end
+
+    def finding(rule, type, id, message)
+      Finding.new(rule, type, id, message)
+    end
+  end
+end

data/lib/menuconform/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Menuconform
+  VERSION = "0.1.0"
+end

data/lib/menuconform.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require_relative "menuconform/version"
+require_relative "menuconform/finding"
+require_relative "menuconform/catalog"
+require_relative "menuconform/menu"
+require_relative "menuconform/rules/struct_rules"
+require_relative "menuconform/rules/conflict_rules"
+require_relative "menuconform/rules/price_rules"
+require_relative "menuconform/rules/avail_rules"
+require_relative "menuconform/rules/name_rules"
+require_relative "menuconform/rules/allergen_rules"
+require_relative "menuconform/rules/age_rules"
+require_relative "menuconform/importers"
+require_relative "menuconform/solver"
+require_relative "menuconform/rules/cart_rules"
+require_relative "menuconform/scorer"
+require_relative "menuconform/ucp_exporter"
+require_relative "menuconform/report"
+require_relative "menuconform/engine"
+
+module Menuconform
+end

data/rules/catalog.json

@@ -0,0 +1,38 @@
+{
+  "rules_version": "0.1.0",
+  "note": "Registry stub covering the rules referenced by fixtures 01/02/12 plus reserved core IDs. Rule IDs are stable forever: never renumber, never reuse. Descriptions/fix_hints are written for a restaurant ops / POS product audience. Engine logic lands days 3-8.",
+  "rules": [
+    { "id": "STRUCT-001", "severity": "error", "title": "Document fails IR schema validation", "description": "The menu document does not conform to the Menu IR JSON Schema (shape/type errors).", "fix_hint": "Fix the export or importer mapping so the document matches schema/menu_ir.schema.json; all other checks need a loadable document." },
+    { "id": "STRUCT-002", "severity": "error", "title": "Dangling reference", "description": "An ID is referenced (modifier_group_ids, option modifier_id, child_modifier_group_ids, category item_ids, conditional when_modifier_id) but no entity with that ID exists.", "fix_hint": "The referenced record was deleted or renamed in the POS without updating what points at it. Remove the reference or restore the record." },
+    { "id": "STRUCT-003", "severity": "error", "title": "Duplicate ID", "description": "Two entities in the same collection share an ID; references to it are ambiguous.", "fix_hint": "Deduplicate in the source system; an agent cannot tell which record it is ordering." },
+    { "id": "STRUCT-004", "severity": "warn", "title": "Orphan entity", "description": "An entity is defined but nothing references it.", "fix_hint": "Usually a leftover from a deleted menu section. Remove it, or reattach it if it was meant to be live." },
+    { "id": "STRUCT-005", "severity": "error", "title": "Modifier nesting deeper than 6", "description": "A chain of nested modifier groups exceeds depth 6 from the item; no major ordering platform supports this.", "fix_hint": "Flatten the deepest choices into their parent group." },
+    { "id": "STRUCT-006", "severity": "warn", "title": "Modifier nesting deeper than 4", "description": "Nesting depth 5-6 is exportable but degrades agent and diner experience; only depth up to 4 is common (pizza size/crust/topping/side).", "fix_hint": "Consider flattening: deep question chains cause abandoned agent carts." },
+    { "id": "STRUCT-007", "severity": "warn", "title": "Item not in any category", "description": "The item exists but no category lists it, so no agent or diner can discover it.", "fix_hint": "Add it to a category or remove it." },
+    { "id": "STRUCT-008", "severity": "warn", "title": "Empty category", "description": "A category lists no items.", "fix_hint": "Remove the category or fill it; empty sections read as broken menus to agents." },
+    { "id": "PRICE-001", "severity": "error", "title": "Negative item price", "description": "An item has a negative base price.", "fix_hint": "Set a real price; negative-price placeholder/test items must not reach a live menu." },
+    { "id": "PRICE-002", "severity": "warn", "title": "Incomplete conditional-price matrix", "description": "An option has conditional prices for some, but not all, options of its trigger group (e.g. topping priced for Small and Large but the menu also has X-Large). Unmatched selections silently fall back to the base price.", "fix_hint": "Add the missing matrix entries — this is the classic 'new size added, topping table not updated' undercharge." },
+    { "id": "PRICE-003", "severity": "error", "title": "Negative line total reachable", "description": "Some valid selection makes the item's total negative (a discounting modifier exceeds the item price).", "fix_hint": "Cap the discount modifier or raise the base price; a negative line breaks checkout math downstream." },
+    { "id": "AVAIL-001", "severity": "error", "title": "Availability contradicts parent scope", "description": "An item's windows never overlap its category's (or the menu's) windows, so it is never actually orderable despite having a schedule.", "fix_hint": "Align the item's schedule with its category, or move it to a category served during those hours." },
+    { "id": "AVAIL-002", "severity": "warn", "title": "Declared never-available", "description": "An entity has an explicit empty availability list.", "fix_hint": "If it is retired, remove it; if it should sell, give it real windows." },
+    { "id": "AVAIL-003", "severity": "warn", "title": "Indefinite suspension", "description": "suspended_until is more than a year in the future — effectively deleted via 86ing.", "fix_hint": "86 is for outages, not retirement. Deactivate or remove the record instead." },
+    { "id": "CONFLICT-001", "severity": "error", "title": "min exceeds max", "description": "A group's min_select exceeds max_select (or min_total_units exceeds max_total_units); no selection can satisfy it.", "fix_hint": "Fix the bounds; every item using this group is unorderable." },
+    { "id": "CONFLICT-002", "severity": "error", "title": "Required group with no options", "description": "A group requires a selection but offers no options.", "fix_hint": "Add options or make the group optional." },
+    { "id": "CONFLICT-003", "severity": "error", "title": "Defaults violate group constraints", "description": "The pre-selected defaults exceed the group's maxima (or fall short of minima).", "fix_hint": "Adjust default selections; agents start from defaults and will submit invalid carts." },
+    { "id": "CONFLICT-004", "severity": "warn", "title": "Included quantity exceeds group maximum", "description": "included_quantity is larger than what the group allows to be selected, so part of the 'free' allowance can never be used.", "fix_hint": "Align included_quantity with the group's max; mismatches confuse price expectations." },
+    { "id": "CONFLICT-005", "severity": "error", "title": "Invalid conditional-price trigger", "description": "conditional_prices reference options that are not all in one single-select (max_select 1) group attached to the same item, so the matched price is ambiguous.", "fix_hint": "Key conditional prices off exactly one single-choice group (typically the size group)." },
+    { "id": "NAME-001", "severity": "error", "title": "Empty name", "description": "A customer-facing entity has an empty or whitespace-only name.", "fix_hint": "Name it; agents cannot present or disambiguate a blank option." },
+    { "id": "NAME-002", "severity": "warn", "title": "Duplicate names in scope", "description": "Two entities in the same scope share a name (case-insensitive).", "fix_hint": "Merge the duplicates or differentiate the names; agents ordering 'Diet Coke' pick one at random." },
+    { "id": "NAME-003", "severity": "warn", "title": "POS junk in customer-facing name", "description": "The name carries back-of-house tokens (86, DNU, DO NOT USE, TEST, zzz) or POS abbreviation style.", "fix_hint": "Customer-facing names should read like a menu, not a kitchen printer tape." },
+    { "id": "ALLERGEN-001", "severity": "info", "title": "Missing allergen data", "description": "A food item declares no allergen information at all.", "fix_hint": "Declare contains/may_contain (an explicit empty list is a declaration); agents increasingly filter by allergen and skip unlabeled items." },
+    { "id": "ALLERGEN-002", "severity": "warn", "title": "Contradictory allergen declaration", "description": "The same allergen appears in both contains and may_contain.", "fix_hint": "Pick one: 'contains' and 'may contain' are different legal statements." },
+    { "id": "AGE-001", "severity": "error", "title": "Age-restricted product without min_age", "description": "An entity whose name/type indicates alcohol (or another age-restricted product) has no min_age.", "fix_hint": "Set min_age (21 for US alcohol); without it an agent may sell alcohol without age verification." },
+    { "id": "AGE-002", "severity": "warn", "title": "Age-restricted item in kids-oriented category", "description": "An age-restricted or alcohol-indicative item is listed in a category aimed at children.", "fix_hint": "Almost always a miscategorization; move the item." },
+    { "id": "CART-001", "severity": "error", "title": "No valid cart exists", "description": "The cart solver found no selection satisfying all of the item's constraints — the item cannot be ordered at all.", "fix_hint": "See the accompanying CONFLICT/STRUCT findings on this item's groups; fixing those usually resolves this." },
+    { "id": "CART-002", "severity": "error", "title": "Default cart invalid", "description": "The item's pre-selected defaults do not satisfy its own constraints; agents starting from defaults submit invalid carts.", "fix_hint": "Fix the default selections on the flagged groups." },
+    { "id": "CART-003", "severity": "error", "title": "No positive price reachable", "description": "No valid selection yields a total greater than zero.", "fix_hint": "Give the item a price or priced required options; zero/negative lines fail downstream checkout." },
+    { "id": "CART-004", "severity": "warn", "title": "Pricing ambiguity", "description": "The fuzzer found two equivalent selections with different totals, or unstable totals under slot/included-quantity interaction.", "fix_hint": "Review the flagged groups' pricing semantics; ambiguous totals become chargebacks." },
+    { "id": "EXPORT-001", "severity": "error", "title": "Construct cannot be exported", "description": "A construct in this menu has no representation at all under the pinned UCP draft.", "fix_hint": "See the finding detail for the construct and the suggested restructure." },
+    { "id": "EXPORT-002", "severity": "warn", "title": "Lossy export", "description": "A construct exports to the pinned UCP draft only with degraded semantics (the lossy-construct list).", "fix_hint": "Review what the agent-facing menu will lose; restructure if the loss is customer-visible." }
+  ]
+}