sql-chatbot-rails 1.0.0

data/lib/sql_chatbot/grammar/primitives.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require "sql_chatbot/grammar/registry"
+
+module SqlChatbot
+  module Grammar
+    module Primitives
+      PREFERRED_DISPLAY_FIELDS = %w[id name title label email].freeze
+
+      # Quote a single SQL identifier — wraps in double quotes and escapes
+      # embedded quotes. Prevents PG reserved-word collisions ("user", "order"
+      # etc.) which silently resolve to functions and corrupt counts.
+      def self.q(name)
+        %("#{name.to_s.gsub('"', '""')}")
+      end
+
+      # Qualified column reference: "table"."column"
+      def self.qc(table, col)
+        "#{q(table)}.#{q(col)}"
+      end
+
+      def self.build(primitive:, entity:, field: nil, which: nil, n: nil, rank_field: nil, direction: nil, group_by: nil)
+        t = q(entity.table)
+        case primitive
+        when :COUNT
+          "SELECT COUNT(*) FROM #{t}"
+        when :LIST
+          "SELECT #{pick_display_fields(entity).map { |c| q(c) }.join(", ")} FROM #{t}"
+        when :SUM
+          require_field!(entity, field, "SUM")
+          "SELECT SUM(#{qc(entity.table, field)}) FROM #{t}"
+        when :AVG
+          require_field!(entity, field, "AVG")
+          "SELECT ROUND(AVG(#{qc(entity.table, field)}), 2) FROM #{t}"
+        when :MIN_MAX
+          require_field!(entity, field, "MIN_MAX")
+          raise "MIN_MAX requires which" unless %i[MIN MAX].include?(which)
+          "SELECT #{which}(#{qc(entity.table, field)}) FROM #{t}"
+        when :TOP_N
+          rank = rank_field || entity.ranking_candidates.first
+          raise "TOP_N requires rankField" unless rank
+          limit = n || 10
+          dir = (direction || "desc").to_s.upcase
+          # V1.3-V: NULLS LAST in both directions. PG default for DESC is
+          # NULLS FIRST, which surfaced a NULL-rank row for 2BN's
+          # "biggest review by rating" — answer LLM rendered "N/A".
+          # NULL rank is never the answer the user wants.
+          "SELECT #{pick_display_fields(entity).map { |c| q(c) }.join(", ")}, #{qc(entity.table, rank)} FROM #{t} ORDER BY #{qc(entity.table, rank)} #{dir} NULLS LAST LIMIT #{limit}"
+        when :RANK
+          raise "RANK requires rankField and groupBy" unless rank_field && group_by
+          "SELECT #{t}.*, DENSE_RANK() OVER (PARTITION BY #{qc(entity.table, group_by)} ORDER BY #{qc(entity.table, rank_field)} DESC) AS rank FROM #{t}"
+        else
+          raise "unknown primitive #{primitive}"
+        end
+      end
+
+      def self.pick_display_fields(entity)
+        present = PREFERRED_DISPLAY_FIELDS.select { |p| entity.fields.key?(p) }
+        return present.map { |p| entity.fields[p].column } if present.any?
+        entity.fields.keys.first(4)
+      end
+
+      def self.require_field!(entity, field, name)
+        raise "#{name} requires field" unless field
+        raise "#{name} field '#{field}' not in entity" unless entity.fields.key?(field.to_s)
+      end
+    end
+  end
+end

data/lib/sql_chatbot/grammar/programmatic_renderer.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+require "sql_chatbot/grammar/count_renderer"
+require "sql_chatbot/grammar/list_renderer"
+
+module SqlChatbot
+  module Grammar
+    # Unified programmatic-renderer registry. Mirror of npm's
+    # programmatic-renderer.ts. The grammar's intent extractor emits a
+    # primitive (COUNT, LIST, TOP_N, …); this module renders the result
+    # deterministically when it can — bypassing the answer-stream LLM
+    # which truncates lists, mis-narrates count=0 as "no records", and
+    # hallucinates empty TOP_N results when the metric is all zero.
+    #
+    # Adding a new primitive renderer (SUM, AVG, MIN_MAX, RANK) means:
+    # write a pure handler and add it to HANDLERS. No new files.
+    module ProgrammaticRenderer
+      def self.try_render(primitive, entity_display_label, rows, rank_field: nil, field: nil, which: nil)
+        return { ok: false } if primitive.nil?
+        handler = HANDLERS[primitive.to_s]
+        return { ok: false } unless handler
+        handler.call(entity_display_label, rows, rank_field, field, which)
+      end
+
+      # COUNT — one row, one numeric `count` column. Delegates to existing
+      # CountRenderer (already in unified shape).
+      HANDLE_COUNT = ->(label, rows, _rank, _field, _which) {
+        CountRenderer.try_render("COUNT", label, rows)
+      }
+
+      # LIST — small result, picks readable label per row. Delegates.
+      HANDLE_LIST = ->(label, rows, _rank, _field, _which) {
+        ListRenderer.try_render("LIST", label, rows)
+      }
+
+      TOPN_THRESHOLD = 10
+      PREFERRED_LABEL_KEYS = %w[title name label subject email username].freeze
+
+      # TOP_N — small ordered result, label + rank value per row. The
+      # Gitea sweep failure: "biggest repo by stars" returned 5 rows with
+      # all num_stars=0; the answer LLM rendered "No matching records."
+      # Programmatic render shows the data deterministically.
+      HANDLE_TOPN = ->(label, rows, rank_field, _field, _which) {
+        next { ok: false } unless rows.is_a?(Array)
+        next { ok: true, text: ProgrammaticRenderer.empty_text(label) } if rows.empty?
+        next { ok: false } if rows.length > TOPN_THRESHOLD
+
+        formatted = []
+        rows.each do |row|
+          next { ok: false } unless row.is_a?(Hash)
+          lbl = ProgrammaticRenderer.pick_row_label(row)
+          break { ok: false } unless lbl
+          rank_value = ProgrammaticRenderer.pick_rank_value(row, rank_field)
+          formatted << { label: lbl, rank: rank_value }
+        end
+        next formatted if formatted.is_a?(Hash) # short-circuit { ok: false }
+
+        label_or_item = label.to_s.empty? ? "item" : label.to_s
+        noun = rows.length == 1 ? CountRenderer.to_singular_label(label_or_item) : CountRenderer.to_plural_label(label_or_item)
+        by_part = rank_field ? " by #{rank_field}" : ""
+        intro = rows.length == 1 ? "Top #{noun}#{by_part}:" : "Top #{rows.length} #{noun}#{by_part}:"
+        lines = formatted.map { |f| f[:rank] ? "- #{f[:label]} (#{f[:rank]})" : "- #{f[:label]}" }.join("\n")
+        { ok: true, text: "#{intro}\n#{lines}" }
+      }
+
+      # SUM / AVG / MIN_MAX — one row, one numeric value. Mirror of TS
+      # handlers in programmatic-renderer.ts (V1.3-P / Fix G).
+      MONEY_HINTS = %w[amount price cost revenue total gross net fee].freeze
+
+      HANDLE_SUM = ->(label, rows, _rank, field, _which) {
+        value = ProgrammaticRenderer.first_aggregate_value(rows)
+        next { ok: false } if value == :no_value
+        formatted = ProgrammaticRenderer.format_aggregate_value(field, value)
+        next { ok: true, text: "No data available to sum." } if formatted.nil?
+        plural = CountRenderer.to_plural_label(label.to_s.empty? ? "item" : label.to_s)
+        { ok: true, text: "Total #{ProgrammaticRenderer.humanize_field(field)} across #{plural}: #{formatted}" }
+      }
+
+      HANDLE_AVG = ->(label, rows, _rank, field, _which) {
+        value = ProgrammaticRenderer.first_aggregate_value(rows)
+        next { ok: false } if value == :no_value
+        formatted = ProgrammaticRenderer.format_aggregate_value(field, value)
+        next { ok: true, text: "No data available to average." } if formatted.nil?
+        plural = CountRenderer.to_plural_label(label.to_s.empty? ? "item" : label.to_s)
+        { ok: true, text: "Average #{ProgrammaticRenderer.humanize_field(field)} across #{plural}: #{formatted}" }
+      }
+
+      HANDLE_MIN_MAX = ->(label, rows, _rank, field, which) {
+        value = ProgrammaticRenderer.first_aggregate_value(rows)
+        next { ok: false } if value == :no_value
+        formatted = ProgrammaticRenderer.format_aggregate_value(field, value)
+        next { ok: true, text: "No data available." } if formatted.nil?
+        plural = CountRenderer.to_plural_label(label.to_s.empty? ? "item" : label.to_s)
+        adj = which.to_s == "MIN" ? "Lowest" : "Highest"
+        { ok: true, text: "#{adj} #{ProgrammaticRenderer.humanize_field(field)} across #{plural}: #{formatted}" }
+      }
+
+      HANDLERS = {
+        "COUNT"   => HANDLE_COUNT,
+        "LIST"    => HANDLE_LIST,
+        "TOP_N"   => HANDLE_TOPN,
+        "SUM"     => HANDLE_SUM,
+        "AVG"     => HANDLE_AVG,
+        "MIN_MAX" => HANDLE_MIN_MAX,
+      }.freeze
+
+      def self.first_aggregate_value(rows)
+        return :no_value unless rows.is_a?(Array) && rows.length == 1
+        row = rows.first
+        return :no_value unless row.is_a?(Hash)
+        return :no_value if row.empty? || row.size > 1
+        row.values.first
+      end
+
+      def self.format_aggregate_value(field, value)
+        return nil if value.nil?
+        n =
+          case value
+          when Numeric then value
+          when String then (value =~ /\A-?\d+(\.\d+)?\z/) ? value.to_f : nil
+          end
+        return nil unless n
+        if looks_like_money?(field)
+          # Format with thousands separators and 2 decimals, prefix $.
+          whole = n.truncate.to_s.reverse.scan(/\d{1,3}/).join(",").reverse
+          decimals = ((n - n.truncate).round(2).abs * 100).round.to_s.rjust(2, "0")
+          "$#{whole}.#{decimals}"
+        else
+          if n == n.to_i
+            n.to_i.to_s.reverse.scan(/\d{1,3}/).join(",").reverse
+          else
+            rounded = (n * 100).round / 100.0
+            whole = rounded.truncate.to_s.reverse.scan(/\d{1,3}/).join(",").reverse
+            frac = ((rounded - rounded.truncate).abs * 100).round.to_s.rjust(2, "0").gsub(/0$/, "")
+            frac.empty? ? whole : "#{whole}.#{frac}"
+          end
+        end
+      end
+
+      def self.looks_like_money?(field)
+        return false if field.nil?
+        f = field.to_s.downcase
+        MONEY_HINTS.any? { |h| f.include?(h) }
+      end
+
+      def self.humanize_field(field)
+        return "value" if field.nil? || field.to_s.empty?
+        field.to_s.tr("_", " ")
+      end
+
+      def self.pick_row_label(row)
+        PREFERRED_LABEL_KEYS.each do |k|
+          v = row[k] || row[k.to_sym]
+          return v.strip if v.is_a?(String) && !v.strip.empty?
+        end
+        row.each do |k, v|
+          next if k.to_s == "id"
+          return v.strip if v.is_a?(String) && !v.strip.empty?
+        end
+        nil
+      end
+
+      def self.pick_rank_value(row, rank_field)
+        if rank_field
+          v = row[rank_field] || row[rank_field.to_s] || row[rank_field.to_sym]
+          return format_scalar(v) if v
+        end
+        row.each do |k, v|
+          next if %w[id count].include?(k.to_s)
+          if v.is_a?(Numeric) || (v.is_a?(String) && v =~ /\A-?\d+(\.\d+)?\z/)
+            return format_scalar(v)
+          end
+        end
+        nil
+      end
+
+      def self.format_scalar(v)
+        return nil if v.nil?
+        return v.to_s if v.is_a?(Numeric)
+        return v if v.is_a?(String)
+        nil
+      end
+
+      # =========================================================
+      # Bug D guard for the LLM SQL path. Mirror of TS
+      # renderEmptyForLlmSql. Hard sweep on 2026-04-28 surfaced
+      # five questions where grammar missed → LLM SQL → 0 rows /
+      # COUNT(*)=0 / NULL aggregate → answer LLM emitted
+      # "No matching records found." even when a shape-aware
+      # programmatic rendering ("There are 0 X.", "No Xs found.")
+      # would be more honest. Returns nil when there *is* data —
+      # caller falls through to the answer LLM.
+      # =========================================================
+
+      COUNT_RE = /SELECT\s+COUNT\s*\(/i
+      AGGREGATE_RE = /SELECT\s+(SUM|AVG|MIN|MAX)\s*\(/i
+      FROM_TABLE_RE = /\bFROM\s+(?:"?[\w$]+"?\s*\.\s*)?"?([\w$]+)"?/i
+
+      def self.render_empty_for_llm_sql(_question, sql, rows)
+        is_count = sql =~ COUNT_RE
+        is_aggregate = sql =~ AGGREGATE_RE
+
+        if is_count && rows.is_a?(Array) && rows.length == 1
+          val = first_scalar(rows[0])
+          n = as_number(val)
+          if n == 0
+            label = entity_from_from(sql)
+            return label ? "There are 0 #{CountRenderer.to_plural_label(label)}." : "There are 0 matching items."
+          end
+          return nil
+        end
+
+        if is_aggregate && rows.is_a?(Array) && rows.length == 1
+          val = first_scalar(rows[0])
+          return "No data available for that question." if val.nil?
+          return nil
+        end
+
+        if rows.is_a?(Array) && rows.empty?
+          label = entity_from_from(sql)
+          return label ? "No #{CountRenderer.to_plural_label(label)} found." : "I didn't find anything matching that — could you rephrase or be more specific?"
+        end
+
+        nil
+      end
+
+      def self.first_scalar(row)
+        return nil unless row.is_a?(Hash) && !row.empty?
+        row.values.first
+      end
+
+      def self.as_number(v)
+        return v if v.is_a?(Numeric)
+        return v.to_i if v.is_a?(String) && v =~ /\A-?\d+\z/
+        nil
+      end
+
+      def self.entity_from_from(sql)
+        m = sql.match(FROM_TABLE_RE)
+        return nil unless m && m[1]
+        m[1].split("_").reject(&:empty?).map { |w| w[0].upcase + w[1..].to_s.downcase }.join(" ")
+      end
+
+      # Shared empty-text helper used by HANDLE_TOPN, ListRenderer, and
+      # render_empty_for_llm_sql so the user-facing string is consistent:
+      # "No <Plural> found." instead of the V1.2 Bug D phrase
+      # "No matching records found." which the user has flagged on the
+      # 2026-04-28 hard sweep as misleading.
+      def self.empty_text(entity_display_label)
+        if entity_display_label && !entity_display_label.to_s.strip.empty?
+          "No #{CountRenderer.to_plural_label(entity_display_label.to_s)} found."
+        else
+          "I didn't find anything matching that — could you rephrase or be more specific?"
+        end
+      end
+    end
+  end
+end

data/lib/sql_chatbot/grammar/registry.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "time"
+
+module SqlChatbot
+  module Grammar
+    Entity = Struct.new(:name, :table, :display_label, :row_count, :primary_key,
+                        :timestamps, :fields, :scopes, :associations, :ranking_candidates,
+                        :implicit_filters,
+                        keyword_init: true) do
+      def initialize(**kwargs)
+        super(
+          name: kwargs[:name],
+          table: kwargs[:table],
+          display_label: kwargs[:display_label] || kwargs[:name]&.capitalize,
+          row_count: kwargs[:row_count] || 0,
+          primary_key: kwargs[:primary_key] || "id",
+          timestamps: kwargs[:timestamps] || {},
+          fields: kwargs[:fields] || {},
+          scopes: kwargs[:scopes] || {},
+          associations: kwargs[:associations] || {},
+          ranking_candidates: kwargs[:ranking_candidates] || [],
+          implicit_filters: kwargs[:implicit_filters] || []
+        )
+      end
+    end
+
+    # WHERE clauses appended to every SELECT for an entity. Two sources feed
+    # this list:
+    #   - Schema detection: e.g. `deleted_at` → `{ column: "deleted_at", expr: "IS NULL", source: :soft_delete }`
+    #   - Developer config (`default_filters`): e.g. MSP convention `*.status != 3`.
+    # The compiler emits each entry as `"<table>"."<column>" <expr>` and skips
+    # any entry whose column is already referenced in the generated SQL.
+    ImplicitFilter = Struct.new(:column, :expr, :source, keyword_init: true)
+
+    Field = Struct.new(:column, :type, :nullable, :enum_values, :fk_to,
+                       :user_facing_label, :searchable, keyword_init: true)
+
+    Scope = Struct.new(:name, :where_clause, :param_slots, keyword_init: true)
+
+    Association = Struct.new(:name, :kind, :target_entity, :join_clause,
+                             :through_entity, keyword_init: true)
+
+    class Registry
+      attr_reader :entities, :aliases, :version, :generated_at, :framework
+
+      def initialize(framework:, entities: {}, aliases: {})
+        @framework = framework
+        @entities = entities
+        @aliases = aliases
+        @version = 1
+        @generated_at = Time.now.utc.iso8601
+      end
+
+      def find_entity(name)
+        @entities[name.to_s]
+      end
+
+      def resolve_alias(term)
+        return @aliases[term.to_s] if @aliases.key?(term.to_s)
+        return term.to_s if @entities.key?(term.to_s)
+        nil
+      end
+    end
+  end
+end

data/lib/sql_chatbot/grammar/sanity_check.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module SqlChatbot
+  module Grammar
+    # Post-execution sanity check for grammar-generated SQL.
+    #
+    # Catches "plausible but wrong" results where the SQL ran without error
+    # but the value disagrees with the registry's known row count. Concrete
+    # case: Gitea's `user` reserved-word table returned 1 instead of 9.
+    module SanityCheck
+      # Returns { ok: true } when result matches expectations,
+      # or { ok: false, reason: "..." } when there's a mismatch.
+      def self.check_count(primitive, entity, result_rows)
+        return { ok: true } unless primitive.to_s == "COUNT"
+        return { ok: true } unless result_rows.is_a?(Array) && result_rows.length == 1
+
+        row = result_rows.first
+        v = row.is_a?(Hash) ? row.values.first : nil
+        got = Integer(v.to_s) rescue nil
+        return { ok: true } unless got
+
+        expected = entity.row_count.to_i
+        # Trust the registry only when it has a non-trivial value.
+        # Tables with reltuples == 0 might just be stats-stale.
+        return { ok: true } if expected <= 5
+
+        if got < expected / 3 || got > expected * 3
+          return {
+            ok: false,
+            reason: "count_mismatch: SQL returned #{got}, registry has ~#{expected} rows in #{entity.table}",
+          }
+        end
+        { ok: true }
+      end
+    end
+  end
+end

data/lib/sql_chatbot/grammar/template_compiler.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+require "sql_chatbot/grammar/registry"
+require "sql_chatbot/grammar/primitives"
+require "sql_chatbot/grammar/modifiers"
+
+module SqlChatbot
+  module Grammar
+    module TemplateCompiler
+      def self.compile(intent, registry)
+        return { ok: false, reason: "unmatched: #{intent[:reason]}" } if intent[:status].to_s == "unmatched"
+
+        entity_name = registry.aliases[intent[:entity]] || intent[:entity]
+        entity = registry.entities[entity_name]
+        return { ok: false, reason: "entity '#{intent[:entity]}' not in registry" } unless entity
+
+        begin
+          modifiers = Array(intent[:modifiers])
+          primitive_sym = intent[:primitive].to_s
+          rank_field = intent[:rank_field]
+          limit_n    = intent[:n]
+
+          # V1.3-K shape-repair pass — three real-world LLM emit-fidelity issues
+          # captured during the 2026-04-28 hard sweep. Mirror of TS
+          # `normalizeIntentShape` in template-compiler.ts.
+          modifiers = normalize_intent_shape(modifiers, entity)
+
+          # TOP_N / MIN_MAX express the rank/field through an `order_by`
+          # modifier when the LLM phrases it that way ("biggest repo by stars"
+          # → primitive=TOP_N + order_by(num_stars,desc)). Lift the
+          # modifier's field into the primitive slot and drop it so the
+          # compiler doesn't emit ORDER BY twice (which produces a Postgres
+          # syntax error and silently pushes the question to the LLM
+          # fallback path). Write the lifted values back to the intent so
+          # downstream consumers (programmatic renderer) can read the
+          # canonical rank_field/field regardless of which surface the LLM
+          # emitted.
+          field    = intent[:field]
+          which    = intent[:which]
+          direction = intent[:direction]
+          if primitive_sym == "TOP_N" || primitive_sym == "MIN_MAX"
+            order_mod = modifiers.find { |m| (m[:kind] || m["kind"]).to_s == "order_by" }
+            if order_mod
+              lifted_field = order_mod[:field] || order_mod["field"]
+              raw_dir      = order_mod[:direction] || order_mod["direction"] || order_mod[:op] || order_mod["op"] || "desc"
+              if primitive_sym == "TOP_N"
+                rank_field ||= lifted_field
+                # V1.3-U: pass through the lifted direction so "smallest X"
+                # becomes ASC, mirroring TS liftOrderByForRank.
+                direction ||= raw_dir.to_s.downcase
+              else
+                field ||= lifted_field
+                which ||= raw_dir.to_s.downcase == "asc" ? :MIN : :MAX
+              end
+              modifiers = modifiers.reject { |m| m.equal?(order_mod) }
+            end
+            limit_mod = modifiers.find { |m| (m[:kind] || m["kind"]).to_s == "limit" }
+            if limit_mod && primitive_sym == "TOP_N"
+              limit_n ||= limit_mod[:value] || limit_mod["value"]
+              modifiers = modifiers.reject { |m| m.equal?(limit_mod) }
+            end
+            intent[:rank_field] = rank_field
+            intent[:field]      = field
+            intent[:which]      = which
+            intent[:direction]  = direction
+            intent[:modifiers]  = modifiers
+            intent[:n]          = limit_n
+          end
+
+          sql = Primitives.build(
+            primitive:  intent[:primitive],
+            entity:     entity,
+            field:      field,
+            which:      which,
+            n:          limit_n,
+            rank_field: rank_field,
+            direction:  direction,
+            group_by:   intent[:group_by]
+          )
+
+          modifiers.each do |m|
+            sql = Modifiers.apply(sql, m, entity)
+          end
+
+          sql = with_implicit_filters(sql, entity)
+
+          unless sql =~ /LIMIT \d+/i || primitive_sym == "COUNT" || sql =~ /COUNT\(/i
+            sql = "#{sql} LIMIT 100"
+          end
+
+          { ok: true, sql: sql }
+        rescue => e
+          { ok: false, reason: e.message }
+        end
+      end
+
+      # Append every implicit WHERE clause for this entity. Two sources land
+      # in the same list: schema-detected soft-delete columns and developer-
+      # declared `default_filters`. A clause is skipped when its column is
+      # already referenced in the generated SQL — explicit user filters always
+      # win over the implicit default.
+      def self.with_implicit_filters(sql, entity)
+        filters = Array(entity.respond_to?(:implicit_filters) ? entity.implicit_filters : nil)
+        return sql if filters.empty?
+
+        to_apply = filters.reject { |f| column_already_filtered?(sql, entity.table, f.column) }
+        return sql if to_apply.empty?
+
+        combined = to_apply.map { |f| "#{Primitives.qc(entity.table, f.column)} #{f.expr}" }.join(" AND ")
+        if /\bWHERE\b/i.match?(sql)
+          return sql.sub(/\bWHERE\b/i) { "WHERE #{combined} AND " }
+        end
+        before_match = sql.match(/ (GROUP BY|ORDER BY|LIMIT) /i)
+        if before_match
+          return sql.sub(before_match[0]) { " WHERE #{combined}#{before_match[0]}" }
+        end
+        "#{sql} WHERE #{combined}"
+      end
+
+      def self.column_already_filtered?(sql, table, col)
+        return true if sql.include?(Primitives.qc(table, col))
+        /\b#{Regexp.escape(table)}\.#{Regexp.escape(col)}\b/i.match?(sql)
+      end
+
+      # =====================================================================
+      # V1.3-K shape-repair pass — mirror of TS normalizeIntentShape.
+      #
+      #   1. `where` modifier whose value is a WINDOWS keyword
+      #      → coerce to a `time` modifier with that window.
+      #   2. `time` modifier where the LLM used `value` for the keyword
+      #      instead of `window` → alias the key.
+      #   3. `time` modifier missing field entirely → default to created_at
+      #      if it exists, else the lone timestamp column.
+      # =====================================================================
+      def self.normalize_intent_shape(modifiers, entity)
+        modifiers.map { |m| repair_one(m, entity) }
+      end
+
+      def self.repair_one(modifier, entity)
+        kind = (modifier[:kind] || modifier["kind"]).to_s
+        value = modifier[:value] || modifier["value"]
+        field = modifier[:field] || modifier["field"]
+        window = modifier[:window] || modifier["window"]
+
+        # Rule 1: where with WINDOWS keyword → time
+        if kind == "where" && value.is_a?(String) && SqlChatbot::Grammar::Modifiers::WINDOWS.key?(value.downcase)
+          return {
+            kind: "time",
+            field: field || default_timestamp_field(entity) || "",
+            window: value.downcase,
+          }
+        end
+
+        # Rule 2: time with `value` instead of `window`
+        if kind == "time" && (window.nil? || window.to_s.empty?) && value.is_a?(String) && SqlChatbot::Grammar::Modifiers::WINDOWS.key?(value.downcase)
+          return {
+            kind: "time",
+            field: field || default_timestamp_field(entity) || "",
+            window: value.downcase,
+          }
+        end
+
+        # Rule 3: time missing field → default
+        if kind == "time" && (field.nil? || field.to_s.empty?) && window
+          fallback = default_timestamp_field(entity)
+          return { kind: "time", field: fallback, window: window } if fallback
+        end
+
+        modifier
+      end
+
+      def self.default_timestamp_field(entity)
+        return "created_at" if entity.fields["created_at"]
+        ts_fields = entity.fields.values.select { |f| f.type.to_s == "timestamp" }
+        ts_fields.length == 1 ? ts_fields.first.column : nil
+      end
+    end
+  end
+end