menuconform 0.1.0

data/lib/menuconform/engine.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "json_schemer"
+
+module Menuconform
+  # Runs a Menu IR document through schema validation and all implemented rules.
+  # Severities always come from the rule catalog. reference_time is the only
+  # time input (AVAIL-003 suspension horizon) — inject it for reproducible runs.
+  class Engine
+    ROOT = File.expand_path("../..", __dir__)
+    DEFAULT_SCHEMA = File.join(ROOT, "schema", "menu_ir.schema.json")
+    DEFAULT_CATALOG = File.join(ROOT, "rules", "catalog.json")
+
+    RULES = [
+      Rules::StructRules,
+      Rules::ConflictRules,
+      Rules::PriceRules,
+      Rules::AvailRules,
+      Rules::NameRules,
+      Rules::AllergenRules,
+      Rules::AgeRules,
+      Rules::CartRules
+    ].freeze
+
+    attr_reader :catalog
+
+    def initialize(schema_path: DEFAULT_SCHEMA, catalog_path: DEFAULT_CATALOG)
+      @schemer = JSONSchemer.schema(JSON.parse(File.read(schema_path, encoding: "UTF-8")))
+      @catalog = Catalog.load(catalog_path)
+    end
+
+    # doc: parsed IR document (Hash). Returns [Finding].
+    def run(doc, reference_time: Time.now.utc)
+      schema_errors = @schemer.validate(doc).to_a
+      unless schema_errors.empty?
+        detail = schema_errors.first(3).map { |e| "#{e['data_pointer']} #{e['error']}" }.join("; ")
+        return [with_severity(Finding.new("STRUCT-001", "menu", doc["name"] || "(unnamed)",
+                                          "document fails IR schema validation: #{detail}"))]
+      end
+
+      menu = Menu.new(doc, reference_time: reference_time)
+      RULES.flat_map { |rule| rule.call(menu) }
+           .map { |f| with_severity(f) }
+           .sort_by { |f| [f.rule, f.entity_type, f.entity_id.to_s] }
+    end
+
+    # Full analysis: findings + score + enriched report.
+    def analyze(doc, reference_time: Time.now.utc)
+      Report.new(
+        doc: doc,
+        findings: run(doc, reference_time: reference_time),
+        catalog: @catalog,
+        reference_time: reference_time
+      )
+    end
+
+    private
+
+    def with_severity(finding)
+      finding.severity = @catalog.severity(finding.rule)
+      finding
+    end
+  end
+end

data/lib/menuconform/finding.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Menuconform
+  # One conformance finding. Severity is filled in by the engine from the rule
+  # catalog so rule implementations can never disagree with the published catalog.
+  class Finding
+    attr_reader :rule, :entity_type, :entity_id, :message
+    attr_accessor :severity
+
+    def initialize(rule, entity_type, entity_id, message)
+      @rule = rule
+      @entity_type = entity_type
+      @entity_id = entity_id
+      @message = message
+    end
+
+    def to_h
+      {
+        "rule" => rule,
+        "severity" => severity,
+        "entity" => { "type" => entity_type, "id" => entity_id },
+        "message" => message
+      }
+    end
+  end
+end

data/lib/menuconform/importers/base.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Menuconform
+  module Importers
+    # An importer turns one source-system export into a Menu IR document.
+    # Contract: #call(source, config:) -> Result. Importers NEVER raise on
+    # semantically broken menus (that's the rule engine's job) — they raise
+    # Importers::SourceError only when the input isn't recognizably the
+    # expected source format at all. Vendor field mappings belong in the
+    # importer's JSON config (config/importers/<name>.json), not in code.
+    class SourceError < StandardError; end
+
+    Result = Struct.new(:doc, :notes, keyword_init: true)
+
+    class Base
+      def self.format_name
+        raise NotImplementedError
+      end
+
+      def initialize
+        @notes = []
+      end
+
+      private
+
+      # "12.5" / 12.5 / 1250 -> integer minor units. Sources that already use
+      # minor units pass integers through untouched; decimal strings and
+      # floats are treated as major units (dollars) and scaled by 100.
+      def to_minor_units(value, field: nil)
+        case value
+        when Integer then value
+        when Float then (value * 100).round
+        when String
+          if value.match?(/\A-?\d+\z/)
+            value.to_i
+          elsif value.match?(/\A-?\d*\.\d+\z/)
+            (value.to_f * 100).round
+          else
+            note("unparseable money value #{value.inspect}#{" in #{field}" if field}; using 0")
+            0
+          end
+        when nil then 0
+        else
+          note("unparseable money value #{value.inspect}#{" in #{field}" if field}; using 0")
+          0
+        end
+      end
+
+      def to_id(value)
+        value.to_s
+      end
+
+      # Stash unmapped-but-useful source data under x_ extension keys so
+      # nothing is silently dropped.
+      def stash(entity, key, value)
+        entity["x_#{key}"] = value unless value.nil?
+      end
+
+      def note(message)
+        @notes << message unless @notes.include?(message)
+      end
+    end
+  end
+end

data/lib/menuconform/importers/ncr_menu.rb

@@ -0,0 +1,322 @@
+# frozen_string_literal: true
+
+module Menuconform
+  module Importers
+    # NCR Voyix Menu API importer — v2 menu-details payload (nep-service-version
+    # 2A:1 / 2:1 response shape: submenus / menuItems / salesItems / linkGroups /
+    # linkedItems / modifierCodes / itemCustomModifiers).
+    #
+    # Mapping decisions (see the field study in the day 10-11 notes):
+    # - salesItems -> IR items; menuItems are a display layer (a menu item
+    #   fronting several sales items = sizes) — flattened, with the grouping
+    #   stashed in x_menu_item_id / x_default_variant.
+    # - linkGroups -> modifier groups. NCR minQuantity/maxQuantity count UNITS
+    #   -> min/max_total_units; maxDistinctQuantity -> max_select; NCR has no
+    #   distinct-minimum, so min_select is always 0. freeQuantity ->
+    #   included_quantity (allocation order is undocumented at NCR; config
+    #   decides, default cheapest_first).
+    # - Aloha price levels surface as prices[].linkGroupId (group-scoped
+    #   prices) -> per-link price_override.
+    # - Nesting lives on the linkedItem entity (linkGroupIds) -> lowered onto
+    #   every option link (entity-level to link-level).
+    # - itemCustomModifiers carry per-ITEM defaults; the IR default is per
+    #   link, so a default is set only when every parent of the group agrees.
+    # - Lossy constructs (modifier-code price multipliers, step quantities,
+    #   itemFactor weights, scheduled prices, promotions/quick combos) are
+    #   stashed under x_ keys and reported as import notes.
+    class NcrMenu < Base
+      DAY_MAP = {
+        "MONDAY" => "mon", "TUESDAY" => "tue", "WEDNESDAY" => "wed",
+        "THURSDAY" => "thu", "FRIDAY" => "fri", "SATURDAY" => "sat", "SUNDAY" => "sun"
+      }.freeze
+
+      def self.format_name = "ncr-menu"
+
+      def call(source, config: {})
+        @config = config || {}
+        raise SourceError, "expected a JSON object (NCR menu-details payload)" unless source.is_a?(Hash)
+        if source.key?("subMenus") || source.key?("quickCombos")
+          raise SourceError, "this looks like an NCR Menu API v1 payload; only the v2 shape is supported " \
+                             "(re-export with nep-service-version 2A:1)"
+        end
+        unless source["salesItems"].is_a?(Array) && source["linkGroups"].is_a?(Array)
+          raise SourceError, "not recognizable as an NCR Menu API v2 menu-details payload " \
+                             "(missing salesItems/linkGroups collections)"
+        end
+
+        @source = source
+        @modifiers_by_id = index_by_id(source["linkedItems"] || [])
+        @mod_codes_by_id = index_by_id(source["modifierCodes"] || [])
+        @menu_item_info = build_menu_item_info
+        @group_parents = build_group_parents
+        @icm_defaults = build_icm_defaults
+        note("NCR has no distinct-option minimum; min_select is 0 everywhere and unit minimums map to min_total_units")
+
+        doc = {
+          "ir_version" => "0.2",
+          "name" => source["displayName"] || "NCR Menu",
+          "currency" => currency,
+          "timezone" => timezone,
+          "availability" => windows(source["availability"]),
+          "source" => { "system" => "ncr-menu-v2", "importer" => "menuconform #{VERSION} ncr-menu importer" },
+          "categories" => (source["submenus"] || []).map { |sm| category_for(sm) },
+          "items" => (source["salesItems"] || []).map { |si| item_for(si) },
+          "modifier_groups" => (source["linkGroups"] || []).map { |lg| group_for(lg) },
+          "modifiers" => (source["linkedItems"] || []).map { |li| modifier_for(li) }
+        }.reject { |_, v| v.nil? }
+
+        Result.new(doc: doc, notes: @notes)
+      end
+
+      private
+
+      def timezone
+        tz = @config["timezone"]
+        note("NCR payloads carry no timezone; defaulting to UTC — set the importer config 'timezone' to the site's IANA zone") if tz.nil?
+        tz || "UTC"
+      end
+
+      def currency
+        raw = ((@source["salesItems"] || []) + (@source["linkedItems"] || []))
+              .flat_map { |e| e["prices"] || [] }.filter_map { |p| p["currency"] }.uniq
+        mapped = raw.filter_map { |c| (@config["currency_map"] || {})[c] }.uniq
+        note("multiple currencies in source (#{raw.join(', ')}); using #{mapped.first}") if mapped.size > 1
+        unmapped = raw.reject { |c| (@config["currency_map"] || {}).key?(c) }
+        note("unmapped currency label(s) #{unmapped.join(', ')}; using #{@config['default_currency'] || 'USD'}") unless unmapped.empty?
+        mapped.first || @config["default_currency"] || "USD"
+      end
+
+      # NCR v2: no availability records = always available (the INVERSE of the
+      # IR's empty-array-means-never) — so absence maps to omission, never [].
+      def windows(av)
+        return nil if av.nil? || av.empty?
+        av.filter_map do |a|
+          day = DAY_MAP[a["dayOfWeek"]]
+          next note("unknown dayOfWeek #{a['dayOfWeek'].inspect}; record dropped") && nil unless day
+          { "days" => [day], "start" => hhmm(a["startTime"], "00:00"), "end" => hhmm(a["endTime"], "24:00") }
+        end
+      end
+
+      def hhmm(value, fallback)
+        return fallback unless value.is_a?(String) && value.match?(/\A\d{2}:\d{2}/)
+        value[0, 5]
+      end
+
+      def category_for(sm)
+        c = { "id" => to_id(sm["id"]), "name" => sm["displayName"] || sm["posName"] || "" }
+        c["description"] = sm["description"] if sm["description"]
+        item_ids = idlist(sm["menuItemIds"]).flat_map { |mid| @menu_item_info.dig(mid, :sales_item_ids) || [] }
+        c["item_ids"] = item_ids
+        w = windows(sm["availability"])
+        c["availability"] = w if w
+        c
+      end
+
+      def item_for(si)
+        it = {
+          "id" => to_id(si["id"]),
+          "name" => si["displayName"] || si["posName"] || "",
+          "price" => base_price_minor(si)
+        }
+        it["active"] = false if si["available"] == false
+        groups = idlist(si["linkGroupIds"])
+        it["modifier_group_ids"] = groups unless groups.empty?
+        decorate_shared!(it, si)
+        mi = @menu_item_info.values.find { |info| info[:sales_item_ids].include?(it["id"]) }
+        if mi
+          stash(it, "menu_item_id", mi[:id])
+          stash(it, "default_variant", true) if mi[:default_id] == it["id"]
+          it["availability"] = mi[:windows] if mi[:windows]
+        end
+        it
+      end
+
+      def modifier_for(li)
+        m = {
+          "id" => to_id(li["id"]),
+          "name" => li["displayName"] || li["posName"] || "",
+          "price" => base_price_minor(li)
+        }
+        m["active"] = false if li["available"] == false
+        decorate_shared!(m, li)
+        m
+      end
+
+      def group_for(lg)
+        r = lg["restriction"] || {}
+        g = {
+          "id" => to_id(lg["id"]),
+          "name" => lg["displayName"] || lg["posName"] || "",
+          "min_select" => 0,
+          "max_select" => r["maxDistinctQuantity"]
+        }
+        g["min_total_units"] = r["minQuantity"] if r["minQuantity"]
+        g["max_total_units"] = r["maxQuantity"] if r.key?("maxQuantity")
+        if (fq = r["freeQuantity"])&.positive?
+          g["included_quantity"] = fq
+          g["included_counting"] = "units"
+          g["included_allocation"] = @config["included_allocation"] || "cheapest_first"
+          note("NCR does not document freeQuantity allocation order; assuming #{g['included_allocation']} (importer config)")
+        end
+        %w[perLinkedItemFreeQuantity perLinkedItemStepQuantity].each do |k|
+          next unless r[k]
+          stash(g, k.gsub(/([A-Z])/) { "_#{$1.downcase}" }.sub(/\A_/, ""), r[k])
+          note("#{k} has no IR construct; stashed as extension data")
+        end
+        g["options"] = (lg["linkedItemReferences"] || []).map { |ref| option_for(lg, ref, r) }
+        g
+      end
+
+      def option_for(lg, ref, group_restriction)
+        mid = to_id(ref.dig("linkedItemId", "id"))
+        lr = ref["restriction"] || {}
+        o = { "modifier_id" => mid }
+
+        max_q = lr["maxQuantity"] || group_restriction["perLinkedItemMaxQuantity"]
+        if max_q.nil?
+          max_q = @config["per_option_max_fallback"] || 99
+          note("per-option maximum is unbounded in NCR; capped at #{max_q} (importer config per_option_max_fallback)")
+        end
+        o["max_quantity"] = max_q
+        min_q = lr["minQuantity"] || group_restriction["perLinkedItemMinQuantity"]
+        o["min_quantity"] = min_q if min_q&.positive?
+
+        po = group_scoped_price(mid, to_id(lg["id"]))
+        o["price_override"] = po if po
+
+        li = @modifiers_by_id[mid]
+        children = li ? idlist(li["linkGroupIds"]) : []
+        unless children.empty?
+          o["child_modifier_group_ids"] = children
+          note("NCR nests groups on the modifier entity; lowered onto each option link")
+        end
+
+        o["default_quantity"] = 1 if unanimous_default?(to_id(lg["id"]), mid)
+
+        codes = idlist(ref["modifierCodeIds"]).filter_map { |cid| @mod_codes_by_id[cid] }
+        unless codes.empty?
+          stash(o, "modifier_codes", codes.map { |c| c["displayName"] || c["modifierCode"] })
+          if codes.any? { |c| c["priceMultiplier"] && c["priceMultiplier"] != 1 }
+            note("prep-code price multipliers (e.g. Extra = 2x) are not expanded; totals for multiplied prep codes are not modeled")
+          end
+        end
+        stash(o, "item_factor", ref["itemFactor"]) if ref["itemFactor"] && ref["itemFactor"] != 1
+        %w[freeQuantity stepQuantity].each do |k|
+          next unless lr[k]
+          stash(o, "ncr_#{k.gsub(/([A-Z])/) { "_#{$1.downcase}" }}", lr[k])
+          note("per-option #{k} has no IR construct; stashed as extension data")
+        end
+        o
+      end
+
+      # --- pricing ------------------------------------------------------------
+
+      def active_prices(entity)
+        (entity["prices"] || []).select { |p| p["status"].nil? || p["status"] == "ACTIVE" }
+      end
+
+      def base_price_minor(entity)
+        rows = active_prices(entity).select { |p| p["linkGroupId"].nil? }
+        base = rows.find { |p| p["basePrice"] } || rows.first
+        note("#{entity['id']}: multiple simultaneous base prices; using the first (scheduled prices are not modeled)") if rows.count { |p| p["basePrice"] } > 1
+        value = base&.[]("price") || entity["currentPrice"]
+        note("#{entity['id']}: no usable price; defaulting to 0") if value.nil?
+        to_minor_units(value, field: entity["id"])
+      end
+
+      def group_scoped_price(modifier_id, group_id)
+        li = @modifiers_by_id[modifier_id]
+        return nil unless li
+        row = active_prices(li).find { |p| p["linkGroupId"] == group_id }
+        row && to_minor_units(row["price"], field: "#{modifier_id}@#{group_id}")
+      end
+
+      # --- defaults (itemCustomModifiers) ------------------------------------
+
+      def build_icm_defaults
+        map = Hash.new { |h, k| h[k] = Set.new }
+        (@source["itemCustomModifiers"] || []).each do |icm|
+          next unless icm["include"] || icm["autoAdd"]
+          key = [to_id(icm.dig("linkGroupId", "id")), to_id(icm.dig("linkedItemId", "id"))]
+          map[key] << to_id(icm.dig("parentItemId", "id"))
+        end
+        map
+      end
+
+      def build_group_parents
+        parents = Hash.new { |h, k| h[k] = Set.new }
+        ((@source["salesItems"] || []) + (@source["linkedItems"] || [])).each do |entity|
+          idlist(entity["linkGroupIds"]).each { |gid| parents[gid] << to_id(entity["id"]) }
+        end
+        parents
+      end
+
+      def unanimous_default?(group_id, modifier_id)
+        defaulted = @icm_defaults[[group_id, modifier_id]]
+        return false if defaulted.empty?
+        all_parents = @group_parents[group_id]
+        if all_parents.subset?(defaulted)
+          true
+        else
+          note("default for #{modifier_id} in #{group_id} differs per parent item (#{defaulted.size}/#{all_parents.size} parents); " \
+               "IR defaults are per link — default dropped")
+          false
+        end
+      end
+
+      # --- shared decoration --------------------------------------------------
+
+      def decorate_shared!(entity_ir, entity)
+        cal = calories(entity["nutritionFactsData"])
+        entity_ir["calories"] = cal if cal
+        ext = {}
+        ext["product_id"] = entity["productId"].to_s if entity["productId"]
+        ext["reference_id"] = entity["referenceId"].to_s if entity["referenceId"]
+        ext["external_id"] = entity["externalId"].to_s if entity["externalId"]
+        entity_ir["external_ids"] = ext unless ext.empty?
+        stash(entity_ir, "pos_name", entity["posName"]) if entity["posName"] && entity["posName"] != entity_ir["name"]
+        stash(entity_ir, "tags", entity["tags"]) if entity["tags"]&.any?
+      end
+
+      def calories(nutrition)
+        attr = nutrition&.dig("nutritionAttributes")&.find { |a| a["nutritionType"] == "CALORIES" }
+        return nil unless attr
+        if (range = attr["rangeValue"])
+          out = { "lower" => range["min"].to_i }
+          out["upper"] = range["max"].to_i if range["max"]
+          out
+        elsif attr["value"]
+          { "lower" => attr["value"].round }
+        end
+      end
+
+      # --- structure helpers --------------------------------------------------
+
+      def build_menu_item_info
+        (@source["menuItems"] || []).to_h do |mi|
+          sales = (mi["menuItemResourceTypes"] || []).select { |rt| rt["type"] == "SALES_ITEM" }
+                                                     .map { |rt| to_id(rt["id"]) }
+          skipped = (mi["menuItemResourceTypes"] || []).count { |rt| rt["type"] == "PROMOTION" }
+          note("menu item #{mi['id']} fronts #{skipped} promotion(s); promotions/quick combos have no IR construct and are skipped") if skipped.positive?
+          [to_id(mi["id"]), {
+            id: to_id(mi["id"]),
+            sales_item_ids: sales,
+            default_id: mi.dig("menuItemDefaultItem", "salesItemId", "id")&.to_s,
+            windows: windows(mi["availability"])
+          }]
+        end
+      end
+
+      def index_by_id(collection)
+        collection.to_h { |e| [to_id(e["id"]), e] }
+      end
+
+      # Accepts NCR's two reference list shapes: ["id"] and [{"id" => "id"}].
+      def idlist(list)
+        (list || []).map { |e| e.is_a?(Hash) ? to_id(e["id"]) : to_id(e) }
+      end
+    end
+
+    register(NcrMenu)
+  end
+end

data/lib/menuconform/importers.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "importers/base"
+
+module Menuconform
+  # Registry of source-format importers. Each importer registers itself under
+  # a CLI-facing format name (e.g. "ncr-menu"); default mapping config lives
+  # in config/importers/<format>.json and can be overridden per run.
+  module Importers
+    CONFIG_DIR = File.join(File.expand_path("../..", __dir__), "config", "importers")
+
+    @registry = {}
+
+    class << self
+      def register(klass)
+        @registry[klass.format_name] = klass
+      end
+
+      def names = @registry.keys.sort
+
+      def build(format)
+        klass = @registry[format]
+        raise SourceError, "unknown import format #{format.inspect} (known: #{names.join(', ')})" unless klass
+        klass.new
+      end
+
+      def default_config(format)
+        path = File.join(CONFIG_DIR, "#{format.tr('-', '_')}.json")
+        File.exist?(path) ? JSON.parse(File.read(path, encoding: "UTF-8")) : {}
+      end
+
+      # One-call convenience: source hash -> Result with IR doc.
+      def import(format, source, config: nil)
+        Importers.build(format).call(source, config: config || default_config(format))
+      end
+    end
+  end
+end
+
+require_relative "importers/ncr_menu"

data/lib/menuconform/menu.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Menuconform
+  # Read-only wrapper around a schema-valid Menu IR document. Provides the
+  # indexes and graph traversals the rules share. Tolerates semantically broken
+  # menus (dangling refs, duplicate ids, cycles) by design — reporting those is
+  # the rules' job, so every accessor here must stay total.
+  class Menu
+    attr_reader :doc, :reference_time
+
+    def initialize(doc, reference_time: Time.now.utc)
+      @doc = doc
+      @reference_time = reference_time
+    end
+
+    def categories = @doc["categories"] || []
+    def items = @doc["items"] || []
+    def modifier_groups = @doc["modifier_groups"] || []
+    def modifiers = @doc["modifiers"] || []
+
+    # First definition wins on duplicate ids; duplicates are reported by STRUCT-003.
+    def items_by_id = @items_by_id ||= index_first(items)
+    def groups_by_id = @groups_by_id ||= index_first(modifier_groups)
+    def modifiers_by_id = @modifiers_by_id ||= index_first(modifiers)
+    def categories_by_id = @categories_by_id ||= index_first(categories)
+
+    # { "item" => [dup ids], "modifier_group" => [...], ... }
+    def duplicate_ids
+      @duplicate_ids ||= {
+        "category" => dups(categories),
+        "item" => dups(items),
+        "modifier_group" => dups(modifier_groups),
+        "modifier" => dups(modifiers)
+      }
+    end
+
+    # Groups attached directly to the item (depth 1), including slot groups.
+    def attached_group_ids(item)
+      (item["modifier_group_ids"] || []) +
+        (item["slots"] || []).flat_map { |s| s["modifier_group_ids"] || [] }
+    end
+
+    # Every existing group reachable from the item through option-level nesting.
+    def reachable_group_ids(item)
+      seen = Set.new
+      frontier = attached_group_ids(item)
+      until frontier.empty?
+        nxt = []
+        frontier.each do |gid|
+          g = groups_by_id[gid]
+          next if g.nil? || seen.include?(gid)
+          seen << gid
+          (g["options"] || []).each { |o| nxt.concat(o["child_modifier_group_ids"] || []) }
+        end
+        frontier = nxt
+      end
+      seen
+    end
+
+    # { max_depth: Integer, cyclic: Boolean } — depth counted item->group = 1.
+    def depth_info(item)
+      cyclic = false
+      depth_of = lambda do |gid, path|
+        g = groups_by_id[gid]
+        return 0 if g.nil?
+        if path.include?(gid)
+          cyclic = true
+          return 0
+        end
+        child_ids = (g["options"] || []).flat_map { |o| o["child_modifier_group_ids"] || [] }
+        1 + child_ids.map { |cid| depth_of.call(cid, path + [gid]) }.max.to_i
+      end
+      max = attached_group_ids(item).map { |gid| depth_of.call(gid, []) }.max.to_i
+      { max_depth: max, cyclic: cyclic }
+    end
+
+    # Group ids referenced anywhere (items, slots, option children).
+    def referenced_group_ids
+      @referenced_group_ids ||= begin
+        refs = Set.new
+        items.each { |it| attached_group_ids(it).each { |gid| refs << gid } }
+        modifier_groups.each do |g|
+          (g["options"] || []).each { |o| (o["child_modifier_group_ids"] || []).each { |gid| refs << gid } }
+        end
+        refs
+      end
+    end
+
+    # Modifier ids referenced anywhere (options, conditional-price triggers).
+    def referenced_modifier_ids
+      @referenced_modifier_ids ||= begin
+        refs = Set.new
+        modifier_groups.each do |g|
+          (g["options"] || []).each do |o|
+            refs << o["modifier_id"]
+            (o["conditional_prices"] || []).each { |cp| refs << cp["when_modifier_id"] }
+          end
+        end
+        refs
+      end
+    end
+
+    # modifier id -> [group ids whose options include it]
+    def groups_containing_modifier
+      @groups_containing_modifier ||= begin
+        map = Hash.new { |h, k| h[k] = [] }
+        groups_by_id.each_value do |g|
+          (g["options"] || []).each { |o| map[o["modifier_id"]] << g["id"] }
+        end
+        map
+      end
+    end
+
+    # Yields every (group, option-with-conditional-prices, trigger context) pair
+    # in item context, deduped per (group, option). Trigger context is one of:
+    #   { status: :fallback }              no trigger group reachable — legal
+    #   { status: :valid, group: <group> } single reachable max_select:1 group
+    #   { status: :invalid }               multi-select or spanning trigger
+    # Options with a dangling when_modifier_id are skipped (STRUCT-002 owns those).
+    def each_conditional_context
+      seen = Set.new
+      items_by_id.each_value do |item|
+        reach = reachable_group_ids(item)
+        reach.each do |gid|
+          g = groups_by_id[gid]
+          (g["options"] || []).each do |o|
+            cps = o["conditional_prices"] || []
+            next if cps.empty?
+            key = [gid, o["modifier_id"]]
+            next if seen.include?(key)
+            when_ids = cps.map { |cp| cp["when_modifier_id"] }
+            next if when_ids.any? { |w| !modifiers_by_id.key?(w) }
+            trigger_gids = when_ids.flat_map { |w| groups_containing_modifier[w] }
+                                   .select { |tg| reach.include?(tg) }.uniq
+            next if trigger_gids.empty? # fallback pricing; nothing to check
+            seen << key
+            if trigger_gids.size == 1 && groups_by_id[trigger_gids.first]["max_select"] == 1
+              yield g, o, { status: :valid, group: groups_by_id[trigger_gids.first] }
+            else
+              yield g, o, { status: :invalid }
+            end
+          end
+        end
+      end
+    end
+
+    # Cheapest possible price for one unit of this option, over base price,
+    # link override, and all conditional prices.
+    def resolved_min_price(option)
+      mod = modifiers_by_id[option["modifier_id"]]
+      return 0 if mod.nil?
+      base = option.key?("price_override") ? option["price_override"] : mod["price"]
+      ([base] + (option["conditional_prices"] || []).map { |cp| cp["price"] }).min
+    end
+
+    private
+
+    def index_first(collection)
+      collection.each_with_object({}) { |e, h| h[e["id"]] ||= e }
+    end
+
+    def dups(collection)
+      collection.map { |e| e["id"] }.tally.select { |_, c| c > 1 }.keys
+    end
+  end
+end