menuconform 0.1.0

data/lib/menuconform/report.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Menuconform
+  # Machine-readable conformance report: score, breakdown, and findings
+  # enriched with catalog titles and fix hints. Contains no wall-clock
+  # timestamp of its own — reference_time is the only time input, and it is
+  # stated so the report is reproducible.
+  class Report
+    attr_reader :doc, :findings, :catalog, :reference_time
+
+    def initialize(doc:, findings:, catalog:, reference_time:)
+      @doc = doc
+      @findings = findings
+      @catalog = catalog
+      @reference_time = reference_time
+    end
+
+    def score_breakdown = @score_breakdown ||= Scorer.score(findings)
+    def score = score_breakdown["score"]
+
+    def to_h
+      {
+        "menuconform_version" => VERSION,
+        "rules_version" => catalog.rules_version,
+        "reference_time" => reference_time.utc.iso8601,
+        "menu" => {
+          "name" => doc["name"],
+          "ir_version" => doc["ir_version"],
+          "currency" => doc["currency"],
+          "timezone" => doc["timezone"]
+        },
+        "score" => score,
+        "score_breakdown" => score_breakdown.except("score"),
+        "severity_counts" => severity_counts,
+        "findings" => findings.map { |f| enrich(f) }
+      }
+    end
+
+    def to_json(*args)
+      JSON.pretty_generate(to_h, *args)
+    end
+
+    private
+
+    def severity_counts
+      base = { "error" => 0, "warn" => 0, "info" => 0 }
+      findings.each_with_object(base) { |f, h| h[f.severity] += 1 }
+    end
+
+    def enrich(finding)
+      entry = catalog.entry(finding.rule)
+      finding.to_h.merge(
+        "title" => entry["title"],
+        "fix_hint" => entry["fix_hint"]
+      )
+    end
+  end
+end

data/lib/menuconform/rules/age_rules.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Menuconform
+  module Rules
+    # AGE-001..002. AGE-001 is a name heuristic by necessity: menus don't label
+    # alcohol, which is exactly the problem. The exclusion list guards the known
+    # soda/dessert traps (root beer, ginger ale, rum raisin); keep both lists
+    # tight — a false 'unlabeled alcohol' error costs the report credibility.
+    module AgeRules
+      ALCOHOL = /\b(margarita|mojito|daiquiri|sangria|mimosa|bellini|negroni|martini|cocktail|
+                    beer|lager|ale|ipa|stout|porter|pilsner|hefeweizen|
+                    wine|chardonnay|merlot|cabernet|riesling|rose\s+all\s+day|prosecco|champagne|
+                    whiskey|whisky|bourbon|scotch|vodka|tequila|mezcal|rum|gin|brandy|cognac|
+                    liqueur|sake|soju|cider|hard\s+seltzer)\b/xi
+      EXCLUSIONS = /root\s+beer|ginger\s+ale|ginger\s+beer|birch\s+beer|butter\s*beer|
+                    rum\s+(raisin|cake)|beer\s*battered|beer\s*cheese|
+                    non.?alcoholic|alcohol.?free|virgin|0\.0/xi
+      KIDS_CATEGORY = /\bkids?\b|\bchild(ren)?\b|\bjunior\b|\blittle\b/i
+
+      module_function
+
+      def call(menu)
+        unlabeled_alcohol(menu) + kids_category_conflicts(menu)
+      end
+
+      def alcohol_indicative?(name)
+        n = name || ""
+        n.match?(ALCOHOL) && !n.match?(EXCLUSIONS)
+      end
+
+      def unlabeled_alcohol(menu)
+        check = lambda do |entity, type|
+          return nil if entity["min_age"] || !alcohol_indicative?(entity["name"])
+          Finding.new("AGE-001", type, entity["id"],
+                      "name '#{entity['name']}' indicates alcohol but no min_age is set")
+        end
+        menu.items_by_id.each_value.filter_map { |it| check.call(it, "item") } +
+          menu.modifiers_by_id.each_value.filter_map { |m| check.call(m, "modifier") }
+      end
+
+      def kids_category_conflicts(menu)
+        out = {}
+        menu.categories_by_id.each_value do |c|
+          next unless (c["name"] || "").match?(KIDS_CATEGORY)
+          (c["item_ids"] || []).each do |iid|
+            it = menu.items_by_id[iid]
+            next unless it
+            next unless it["min_age"] || alcohol_indicative?(it["name"])
+            out[iid] ||= Finding.new("AGE-002", "item", iid,
+                                     "age-restricted or alcohol-indicative item listed in kids-oriented category #{c['id']}")
+          end
+        end
+        out.values
+      end
+    end
+  end
+end

data/lib/menuconform/rules/allergen_rules.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Menuconform
+  module Rules
+    # ALLERGEN-001..002. An explicit empty contains list is a declaration
+    # ("we state this has none of the big-9") and satisfies ALLERGEN-001;
+    # only a wholly absent allergens object is an enrichment gap.
+    module AllergenRules
+      module_function
+
+      def call(menu)
+        missing(menu) + contradictions(menu)
+      end
+
+      def missing(menu)
+        menu.items_by_id.each_value.filter_map do |it|
+          next if it.key?("allergens")
+          Finding.new("ALLERGEN-001", "item", it["id"], "no allergen information declared")
+        end
+      end
+
+      def contradictions(menu)
+        check = lambda do |entity, type|
+          a = entity["allergens"]
+          return nil unless a
+          both = (a["contains"] || []) & (a["may_contain"] || [])
+          return nil if both.empty?
+          Finding.new("ALLERGEN-002", type, entity["id"],
+                      "#{both.join(', ')} declared in both contains and may_contain")
+        end
+        menu.items_by_id.each_value.filter_map { |it| check.call(it, "item") } +
+          menu.modifiers_by_id.each_value.filter_map { |m| check.call(m, "modifier") }
+      end
+    end
+  end
+end

data/lib/menuconform/rules/avail_rules.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Menuconform
+  module Rules
+    # AVAIL-001..003. Weekly-window math: windows expand to minute intervals over
+    # a 10080-minute week; end < start wraps past midnight; '24:00' is end-of-day.
+    # Date bounds (start_date/end_date) are ignored for overlap checks in this
+    # release — AVAIL-001 reasons about the recurring weekly pattern only.
+    module AvailRules
+      DAYS = %w[mon tue wed thu fri sat sun].freeze
+      WEEK_MINUTES = 7 * 1440
+      SUSPENSION_HORIZON_SECONDS = 365 * 24 * 3600
+
+      module_function
+
+      def call(menu)
+        contradictions(menu) + declared_never(menu) + indefinite_suspensions(menu)
+      end
+
+      def contradictions(menu)
+        out = []
+        menu_windows = menu.doc["availability"]
+
+        menu.categories_by_id.each_value do |c|
+          next unless present?(c["availability"]) && present?(menu_windows)
+          next if overlap?(c["availability"], menu_windows)
+          out << Finding.new("AVAIL-001", "category", c["id"],
+                             "category windows never overlap the menu's windows")
+        end
+
+        menu.items_by_id.each_value do |it|
+          next unless present?(it["availability"])
+          contexts = menu.categories.select { |c| (c["item_ids"] || []).include?(it["id"]) }
+                         .map { |c| present?(c["availability"]) ? c["availability"] : menu_windows }
+          contexts = [menu_windows] if contexts.empty?
+          contexts = contexts.select { |w| present?(w) }
+          next if contexts.empty? # nothing to contradict
+          next if contexts.any? { |w| overlap?(it["availability"], w) }
+          out << Finding.new("AVAIL-001", "item", it["id"],
+                             "item windows never overlap its category/menu windows — never orderable")
+        end
+        out
+      end
+
+      def declared_never(menu)
+        out = []
+        menu.categories_by_id.each_value do |c|
+          out << Finding.new("AVAIL-002", "category", c["id"], "availability is an explicit empty list") if c["availability"] == []
+        end
+        menu.items_by_id.each_value do |it|
+          out << Finding.new("AVAIL-002", "item", it["id"], "availability is an explicit empty list") if it["availability"] == []
+        end
+        out
+      end
+
+      def indefinite_suspensions(menu)
+        horizon = menu.reference_time + SUSPENSION_HORIZON_SECONDS
+        check = lambda do |entity, type|
+          raw = entity["suspended_until"]
+          return nil unless raw
+          t = begin
+            Time.iso8601(raw)
+          rescue ArgumentError
+            nil
+          end
+          return nil unless t && t > horizon
+          Finding.new("AVAIL-003", type, entity["id"],
+                      "suspended_until #{raw} is more than a year past the reference time — retirement via 86")
+        end
+        menu.items_by_id.each_value.filter_map { |it| check.call(it, "item") } +
+          menu.modifiers_by_id.each_value.filter_map { |m| check.call(m, "modifier") }
+      end
+
+      def present?(windows)
+        !windows.nil? && !windows.empty?
+      end
+
+      def overlap?(windows_a, windows_b)
+        ints_a = intervals(windows_a)
+        ints_b = intervals(windows_b)
+        ints_a.any? { |a| ints_b.any? { |b| a[0] < b[1] && b[0] < a[1] } }
+      end
+
+      def intervals(windows)
+        windows.flat_map do |w|
+          days = w["days"] || DAYS
+          s = minute_of_day(w["start"])
+          e = minute_of_day(w["end"])
+          days.flat_map do |d|
+            di = DAYS.index(d)
+            next [] if di.nil? || s.nil? || e.nil?
+            base = di * 1440
+            if e > s
+              [[base + s, base + e]]
+            elsif e < s # wraps past midnight into the next day
+              nxt = ((di + 1) % 7) * 1440
+              [[base + s, base + 1440], [nxt, nxt + e]].reject { |i| i[0] == i[1] }
+            else
+              [] # zero-length window
+            end
+          end
+        end
+      end
+
+      def minute_of_day(hhmm)
+        return nil unless hhmm.is_a?(String) && hhmm.match?(/\A\d{2}:\d{2}\z/)
+        h, m = hhmm.split(":").map(&:to_i)
+        (h * 60) + m
+      end
+    end
+  end
+end

data/lib/menuconform/rules/cart_rules.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Menuconform
+  module Rules
+    # CART-001..004, produced by the cart solver (see Menuconform::Solver).
+    module CartRules
+      module_function
+
+      def call(menu)
+        Solver.new(menu).findings
+      end
+    end
+  end
+end

data/lib/menuconform/rules/conflict_rules.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Menuconform
+  module Rules
+    # CONFLICT-001..005: statically unsatisfiable or ambiguous constraints.
+    module ConflictRules
+      module_function
+
+      def call(menu)
+        out = []
+        menu.groups_by_id.each_value do |g|
+          out.concat(group_findings(g))
+        end
+        menu.each_conditional_context do |g, o, trigger|
+          next unless trigger[:status] == :invalid
+          out << Finding.new("CONFLICT-005", "modifier_group", g["id"],
+                             "option #{o['modifier_id']} has conditional prices whose trigger " \
+                             "is not a single max_select:1 group attached to the same item")
+        end
+        out
+      end
+
+      def group_findings(g)
+        out = []
+        min = g["min_select"] || 0
+        max = g["max_select"]
+        min_units = g["min_total_units"]
+        max_units = g["max_total_units"]
+        options = g["options"] || []
+
+        if (!max.nil? && min > max) || (min_units && !max_units.nil? && min_units > max_units)
+          out << Finding.new("CONFLICT-001", "modifier_group", g["id"],
+                             "minimum exceeds maximum (min_select #{min} / max_select #{max.inspect}, " \
+                             "min_total_units #{min_units.inspect} / max_total_units #{max_units.inspect})")
+        end
+        if min.positive? && options.empty?
+          out << Finding.new("CONFLICT-002", "modifier_group", g["id"],
+                             "requires #{min} selection(s) but offers no options")
+        end
+        out.concat(default_findings(g, options, max, max_units))
+        out.concat(included_findings(g, max, max_units))
+        out
+      end
+
+      def default_findings(g, options, max, max_units)
+        defaults = options.select { |o| (o["default_quantity"] || 0).positive? }
+        default_units = defaults.sum { |o| o["default_quantity"] }
+        problems = []
+        problems << "#{defaults.size} default option(s) exceed max_select #{max}" if !max.nil? && defaults.size > max
+        problems << "#{default_units} default unit(s) exceed max_total_units #{max_units}" if !max_units.nil? && default_units > max_units
+        defaults.each do |o|
+          mq = o["max_quantity"] || 1
+          problems << "option #{o['modifier_id']} defaults to #{o['default_quantity']} but max_quantity is #{mq}" if o["default_quantity"] > mq
+        end
+        return [] if problems.empty?
+        [Finding.new("CONFLICT-003", "modifier_group", g["id"], problems.join("; "))]
+      end
+
+      def included_findings(g, max, max_units)
+        inc = g["included_quantity"] || 0
+        return [] unless inc.positive?
+        cap = g["included_counting"] == "options" ? max : max_units
+        return [] if cap.nil? || inc <= cap
+        [Finding.new("CONFLICT-004", "modifier_group", g["id"],
+                     "included_quantity #{inc} exceeds the group maximum (#{cap})")]
+      end
+    end
+  end
+end

data/lib/menuconform/rules/name_rules.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Menuconform
+  module Rules
+    # NAME-001..003: naming quality of customer-facing entities.
+    module NameRules
+      JUNK_TOKENS = /\b(86|dnu|do not use|do not sell|test|void|zzz+)\b/i
+
+      module_function
+
+      def call(menu)
+        empty_names(menu) + duplicate_names(menu) + junk_names(menu)
+      end
+
+      def each_named_entity(menu)
+        menu.categories_by_id.each_value { |e| yield e, "category" }
+        menu.items_by_id.each_value { |e| yield e, "item" }
+        menu.groups_by_id.each_value { |e| yield e, "modifier_group" }
+        menu.modifiers_by_id.each_value { |e| yield e, "modifier" }
+      end
+
+      def empty_names(menu)
+        out = []
+        each_named_entity(menu) do |e, type|
+          next unless (e["name"] || "").strip.empty?
+          out << Finding.new("NAME-001", type, e["id"], "name is empty or whitespace-only")
+        end
+        out
+      end
+
+      # Scopes: item names within one category; modifier names within one group.
+      # Every occurrence after the first (in listing order) is flagged.
+      def duplicate_names(menu)
+        out = {}
+        menu.categories_by_id.each_value do |c|
+          seen = {}
+          (c["item_ids"] || []).each do |iid|
+            it = menu.items_by_id[iid]
+            next unless it
+            key = normalize(it["name"])
+            next if key.empty?
+            if seen.key?(key) && seen[key] != iid
+              out[["item", iid]] ||= Finding.new("NAME-002", "item", iid,
+                                                 "name duplicates '#{seen[key]}' in category #{c['id']} (case-insensitive)")
+            else
+              seen[key] ||= iid
+            end
+          end
+        end
+        menu.groups_by_id.each_value do |g|
+          seen = {}
+          (g["options"] || []).each do |o|
+            m = menu.modifiers_by_id[o["modifier_id"]]
+            next unless m
+            key = normalize(m["name"])
+            next if key.empty?
+            if seen.key?(key) && seen[key] != m["id"]
+              out[["modifier", m["id"]]] ||= Finding.new("NAME-002", "modifier", m["id"],
+                                                         "name duplicates '#{seen[key]}' in group #{g['id']} (case-insensitive)")
+            else
+              seen[key] ||= m["id"]
+            end
+          end
+        end
+        out.values
+      end
+
+      def junk_names(menu)
+        out = []
+        each_named_entity(menu) do |e, type|
+          name = e["name"] || ""
+          next if name.strip.empty? || !name.match?(JUNK_TOKENS)
+          out << Finding.new("NAME-003", type, e["id"],
+                             "customer-facing name '#{name}' carries back-of-house tokens")
+        end
+        out
+      end
+
+      def normalize(name)
+        (name || "").strip.downcase
+      end
+    end
+  end
+end

data/lib/menuconform/rules/price_rules.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module Menuconform
+  module Rules
+    # PRICE-001..003. PRICE-003 uses a conservative static under-approximation of
+    # the minimum reachable total (depth-1 groups only, included_quantity ignored,
+    # cheapest conditional price assumed): it can miss negative totals hidden in
+    # nested groups, but a total it reports as negative genuinely is reachable-
+    # negative under those assumptions. The day 7-8 cart solver supersedes it for
+    # exact analysis.
+    module PriceRules
+      module_function
+
+      def call(menu)
+        negative_prices(menu) + incomplete_matrices(menu) + negative_totals(menu)
+      end
+
+      def negative_prices(menu)
+        menu.items_by_id.each_value.filter_map do |it|
+          next unless it["price"].negative?
+          Finding.new("PRICE-001", "item", it["id"], "item price #{it['price']} is negative")
+        end
+      end
+
+      def incomplete_matrices(menu)
+        out = []
+        menu.each_conditional_context do |g, o, trigger|
+          next unless trigger[:status] == :valid
+          covered = (o["conditional_prices"] || []).map { |cp| cp["when_modifier_id"] }
+          all = (trigger[:group]["options"] || []).map { |t| t["modifier_id"] }
+          missing = all - covered
+          next if missing.empty?
+          out << Finding.new("PRICE-002", "modifier_group", g["id"],
+                             "option #{o['modifier_id']} conditional-price matrix does not cover " \
+                             "#{missing.join(', ')} in trigger group #{trigger[:group]['id']} " \
+                             "(falls back to base price)")
+        end
+        out
+      end
+
+      def negative_totals(menu)
+        menu.items_by_id.each_value.filter_map do |it|
+          next if it["price"].negative? # PRICE-001 already anchors this item
+          min_total = it["price"] + menu.attached_group_ids(it).uniq.sum do |gid|
+            g = menu.groups_by_id[gid]
+            g ? min_group_contribution(menu, g) : 0
+          end
+          next unless min_total.negative?
+          Finding.new("PRICE-003", "item", it["id"],
+                      "a valid selection can drive the total to #{min_total}")
+        end
+      end
+
+      # Cheapest satisfying contribution of one group: forced picks take the
+      # cheapest options; beyond the minimum, only negative-priced options are
+      # added, within max_select / max_total_units / per-option max_quantity.
+      def min_group_contribution(menu, group)
+        options = (group["options"] || []).select { |o| menu.modifiers_by_id.key?(o["modifier_id"]) }
+        min_sel = [group["min_select"] || 0, 0].max
+        max_sel = group["max_select"] || options.size
+        return 0 if options.empty? || min_sel > max_sel || min_sel > options.size
+
+        budget = group["max_total_units"] || Float::INFINITY
+        candidates = options.map do |o|
+          unit_price = menu.resolved_min_price(o)
+          units = if unit_price.negative?
+                    o["max_quantity"] || 1
+                  else
+                    [o["min_quantity"] || 0, 1].max
+                  end
+          { price: unit_price, units: units, cost: unit_price * units }
+        end.sort_by { |c| c[:cost] }
+
+        total = 0
+        used_units = 0.0
+        selected = 0
+        candidates.each do |c|
+          forced = selected < min_sel
+          break if !forced && selected >= max_sel
+          next unless forced || c[:cost].negative?
+          units = [c[:units], budget - used_units].min
+          units = 1 if forced && units < 1
+          next if units < 1
+          total += c[:price] * units
+          used_units += units
+          selected += 1
+        end
+        total
+      end
+    end
+  end
+end

data/lib/menuconform/rules/struct_rules.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Menuconform
+  module Rules
+    # STRUCT-002..008. STRUCT-001 (schema validity) runs in the engine before
+    # any rule sees the document.
+    module StructRules
+      module_function
+
+      def call(menu)
+        dangling_refs(menu) + duplicate_ids(menu) + orphans(menu) +
+          nesting_depth(menu) + uncategorized_items(menu) + empty_categories(menu)
+      end
+
+      def dangling_refs(menu)
+        out = {}
+        add = lambda do |type, id, missing, what|
+          out[[type, id, missing]] ||=
+            Finding.new("STRUCT-002", type, id, "references #{what} #{missing}, which is not defined")
+        end
+        menu.categories.each do |c|
+          (c["item_ids"] || []).each do |iid|
+            add.call("category", c["id"], iid, "item") unless menu.items_by_id.key?(iid)
+          end
+        end
+        menu.items.each do |it|
+          menu.attached_group_ids(it).each do |gid|
+            add.call("item", it["id"], gid, "modifier group") unless menu.groups_by_id.key?(gid)
+          end
+        end
+        menu.modifier_groups.each do |g|
+          (g["options"] || []).each do |o|
+            add.call("modifier_group", g["id"], o["modifier_id"], "modifier") unless menu.modifiers_by_id.key?(o["modifier_id"])
+            (o["child_modifier_group_ids"] || []).each do |cgid|
+              add.call("modifier_group", g["id"], cgid, "child modifier group") unless menu.groups_by_id.key?(cgid)
+            end
+            (o["conditional_prices"] || []).each do |cp|
+              wid = cp["when_modifier_id"]
+              add.call("modifier_group", g["id"], wid, "conditional-price trigger modifier") unless menu.modifiers_by_id.key?(wid)
+            end
+          end
+        end
+        out.values
+      end
+
+      def duplicate_ids(menu)
+        menu.duplicate_ids.flat_map do |type, ids|
+          ids.map { |id| Finding.new("STRUCT-003", type, id, "more than one #{type} entry shares this id") }
+        end
+      end
+
+      # Orphan groups and modifiers. Items get STRUCT-007 instead.
+      def orphans(menu)
+        out = []
+        menu.groups_by_id.each_value do |g|
+          next if menu.referenced_group_ids.include?(g["id"])
+          out << Finding.new("STRUCT-004", "modifier_group", g["id"], "defined but referenced by nothing")
+        end
+        menu.modifiers_by_id.each_value do |m|
+          next if menu.referenced_modifier_ids.include?(m["id"])
+          out << Finding.new("STRUCT-004", "modifier", m["id"], "defined but referenced by nothing")
+        end
+        out
+      end
+
+      def nesting_depth(menu)
+        menu.items_by_id.each_value.filter_map do |it|
+          info = menu.depth_info(it)
+          if info[:cyclic]
+            Finding.new("STRUCT-005", "item", it["id"], "modifier group nesting contains a cycle")
+          elsif info[:max_depth] > 6
+            Finding.new("STRUCT-005", "item", it["id"], "modifier group nesting depth #{info[:max_depth]} exceeds 6")
+          elsif info[:max_depth] > 4
+            Finding.new("STRUCT-006", "item", it["id"], "modifier group nesting depth #{info[:max_depth]} exceeds 4")
+          end
+        end
+      end
+
+      def uncategorized_items(menu)
+        listed = menu.categories.flat_map { |c| c["item_ids"] || [] }.to_set
+        menu.items_by_id.each_value.filter_map do |it|
+          next if listed.include?(it["id"])
+          Finding.new("STRUCT-007", "item", it["id"], "not listed in any category")
+        end
+      end
+
+      def empty_categories(menu)
+        menu.categories_by_id.each_value.filter_map do |c|
+          next unless (c["item_ids"] || []).empty?
+          Finding.new("STRUCT-008", "category", c["id"], "category lists no items")
+        end
+      end
+    end
+  end
+end

data/lib/menuconform/scorer.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Menuconform
+  # The published SPEC §7 scoring formula. Pure function of the findings and
+  # the weights below — same findings, same rules version, same score.
+  module Scorer
+    WEIGHTS = { "error" => 5.0, "warn" => 2.0, "info" => 0.5 }.freeze
+    PER_RULE_CAP = 15.0
+    CART_CAP_RULES = %w[CART-001 CART-002 CART-003].freeze
+    CART_CAP = 49
+    SCHEMA_CAP_RULE = "STRUCT-001"
+    SCHEMA_CAP = 59
+
+    module_function
+
+    # findings: [Finding] with severities set. Returns a breakdown hash.
+    def score(findings)
+      deductions = findings.group_by(&:rule).sort.map do |rule, group|
+        severity = group.first.severity
+        raw_points = group.size * WEIGHTS.fetch(severity)
+        points = [raw_points, PER_RULE_CAP].min
+        {
+          "rule" => rule,
+          "severity" => severity,
+          "count" => group.size,
+          "points" => points,
+          "capped" => raw_points > PER_RULE_CAP
+        }
+      end
+
+      raw = 100.0 - deductions.sum { |d| d["points"] }
+      capped = [raw, 0.0].max
+
+      hard_caps = []
+      if findings.any? { |f| CART_CAP_RULES.include?(f.rule) } && capped > CART_CAP
+        hard_caps << { "reason" => "cart-blocking findings present (CART-001/002/003)", "cap" => CART_CAP }
+        capped = CART_CAP
+      end
+      if findings.any? { |f| f.rule == SCHEMA_CAP_RULE } && capped > SCHEMA_CAP
+        hard_caps << { "reason" => "document fails schema validation (STRUCT-001)", "cap" => SCHEMA_CAP }
+        capped = SCHEMA_CAP
+      end
+
+      {
+        "score" => capped.round, # Ruby rounds half away from zero: half-up for our range
+        "base" => 100,
+        "deductions" => deductions,
+        "raw_score" => raw,
+        "hard_caps" => hard_caps
+      }
+    end
+  end
+end