woods 1.6.1 → 2.0.0.beta2

data/lib/woods/console/eval_guard.rb

@@ -14,13 +14,15 @@ module Woods
     #
     # ## Reachability (v0.2)
     #
-    # EvalGuard is the first of five controls on the embedded `console_eval`
-    # opt-in path. `EmbeddedExecutor#handle_eval` calls `check!` before
-    # anything else — ahead of the Confirmation prompt, the SafeContext
-    # rollback, the timeout, and the audit log. When the opt-in is off
-    # (the default), `refusal_for('eval')` still short-circuits with the
-    # `eval_disabled` payload and this guard is not reached. See
-    # docs/CONSOLE_MCP_SETUP.md "console_eval opt-in" and backlog B-053.
+    # `EmbeddedExecutor#send_request` already wraps every dispatched tool —
+    # `console_eval` included — inside `SafeContext#execute`'s rolled-back
+    # transaction before `handle_eval` runs at all. Within that,
+    # `handle_eval` calls `EvalGuard#check!` before anything else it
+    # controls: ahead of the Confirmation prompt, the timeout, and the audit
+    # log. When the opt-in is off (the default), `refusal_for('eval')` still
+    # short-circuits with the `eval_disabled` payload and this guard is not
+    # reached. See docs/CONSOLE_MCP_SETUP.md "console_eval opt-in" and
+    # backlog B-053.
     #
     # Bridge-process mode (in development) will call the same guard before
     # shipping the payload to the remote Rails worker.
@@ -98,24 +100,29 @@ module Woods
       #   `remove_method` / `method_defined?` / `prepend` / `include_module`
       #   reflection family.
       # - State mutation: `instance_variable_set` / `instance_variable_get`,
-      #   `class_variable_set` / `class_variable_get` / `freeze` / `taint`.
+      #   `class_variable_set` / `class_variable_get`.
       # - Object-space escapes: `_id2ref`, `each_object`, `const_source_location`.
       # - System / process: `system`, `exec`, `spawn`, `fork`, `popen`, `%x{}`
       #   (AST method name `backtick` / xstr) so they can't be invoked
       #   implicitly.
-      # - File / IO: `open` (bare Kernel#open — the File-specific reader is
-      #   handled separately via CREDENTIAL_FILE_READERS, but the bare
-      #   `Kernel.open("|shell-command")` form is how most shellshock-style
-      #   escapes slip through).
-      # - Network: `URI.open` (when called as `open` on URI, the AST method
-      #   name is `open` so the string match above catches it). HTTP / Socket
-      #   constants are denied separately via DENIED_CONSTANTS.
-      # - Loader: `load`, `require`, `require_relative`, `autoload`.
+      # - Loader: `require`, `require_relative`, `autoload`. Bare `load` is
+      #   NOT in this list (Marshal.load/YAML.load call sites are the ones
+      #   worth denying, and those go through the constant gate below).
       # - Unsafe deserialization: `unsafe_load` / `_load` (Marshal.load and
-      #   YAML.load are denied via DENIED_CONSTANTS + method gate below).
-      # - Threading escapes from SafeContext's rollback: `new` on Thread /
-      #   Fiber / Process is denied via DENIED_CONSTANTS so the
-      #   {Kernel.fork, Thread.new} pair can't slip past.
+      #   YAML.load are denied via DENIED_CONSTANTS on the `Marshal`/`YAML`
+      #   receiver, not through this list).
+      # - Legacy taint-mode escapes: `taint` / `untaint`.
+      #
+      # Bare `open` (Kernel#open, e.g. `open("|shell-command")`) is NOT in
+      # this list and is NOT denied — a receiver-less call has no receiver
+      # for {#refuse_credential_file_read!} to match either. `File.open` /
+      # `IO.open` / `Pathname.new(...).open` are caught only when the
+      # argument looks like a credential path, via CREDENTIAL_FILE_READERS
+      # below. `URI.open` is denied, but via `URI` being a denied receiver
+      # in DENIED_CONSTANTS ({#refuse_denied_constant_receiver!}), not via an
+      # `open` entry here. Threading escapes from SafeContext's rollback
+      # (`Thread.new`, `Fiber.new`, `Process.fork`, ...) are denied the same
+      # way, via their receiver constants.
       DENIED_REFLECTION = %w[
         eval instance_eval class_eval module_eval binding
         instance_exec class_exec module_exec

data/lib/woods/console/input_contract.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Woods
+  module Console
+    # Normalizes integer inputs and enforces the bounds declared by a ToolSpec.
+    module InputContract
+      class ValidationError < StandardError; end
+
+      DECIMAL_INTEGER = /\A-?(?:0|[1-9]\d*)\z/
+      private_constant :DECIMAL_INTEGER
+
+      module_function
+
+      def normalize!(arguments, properties)
+        properties.each do |property_name, definition|
+          next unless definition[:type] == 'integer'
+
+          key = argument_key(arguments, property_name)
+          next unless key
+
+          value = parse_integer(arguments[key], property_name)
+          enforce_bounds!(value, property_name, definition)
+          arguments[key] = value
+        end
+
+        arguments
+      end
+
+      # Reject a String value for any integer-typed property, without
+      # attempting to parse it. Used ahead of {normalize!} on paths that skip
+      # full JSON-Schema validation (e.g. an unregistered tool spec): without
+      # this, a well-formed decimal string like `"15"` sails past
+      # {parse_integer} untouched (it's valid input to that method) even
+      # though the declared schema's `type: integer` would reject any String
+      # outright — silently coercing input the public contract disallows.
+      #
+      # @param arguments [Hash] Mutated arguments hash (string or symbol keys)
+      # @param properties [Hash] ToolSpec JSON Schema property definitions
+      # @raise [ValidationError] when an integer-typed property holds a String
+      def reject_string_typed_integers!(arguments, properties)
+        properties.each do |property_name, definition|
+          next unless definition[:type] == 'integer'
+
+          key = argument_key(arguments, property_name)
+          next unless key
+          next unless arguments[key].is_a?(String)
+
+          raise ValidationError, "#{property_name} must be an integer"
+        end
+      end
+
+      def argument_key(arguments, property_name)
+        return property_name if arguments.key?(property_name)
+
+        string_name = property_name.to_s
+        string_name if arguments.key?(string_name)
+      end
+      private_class_method :argument_key
+
+      def parse_integer(value, property_name)
+        return value if value.is_a?(Integer)
+        return Integer(value, 10) if value.is_a?(String) && DECIMAL_INTEGER.match?(value)
+
+        raise ValidationError, "#{property_name} must be an integer"
+      end
+      private_class_method :parse_integer
+
+      def enforce_bounds!(value, property_name, definition)
+        minimum = definition.fetch(:minimum)
+        maximum = definition.fetch(:maximum)
+        return if value.between?(minimum, maximum)
+
+        raise ValidationError, "#{property_name} must be between #{minimum} and #{maximum}"
+      end
+      private_class_method :enforce_bounds!
+    end
+  end
+end

data/lib/woods/console/model_validator.rb

@@ -20,8 +20,14 @@ module Woods
     #
     class ModelValidator
       # @param registry [Hash<String, Array<String>>] Model name => column names mapping
-      def initialize(registry:)
+      # @param table_names [Hash<String, String>] Model name => table name mapping, used to
+      #   resolve a qualified `table.column` reference back to the model that owns it. Optional
+      #   and defaults to empty — callers that don't supply it get every qualified column
+      #   reference rejected by {#validate_table_column!} (fail closed: an unmapped table can't
+      #   be proven safe).
+      def initialize(registry:, table_names: {})
         @registry = registry
+        @model_by_table = table_names.each_with_object({}) { |(model, table), acc| acc[table.to_s] = model }
       end
 
       # Validate that a model name is known.
@@ -59,6 +65,28 @@ module Woods
         column_names.each { |col| validate_column!(model_name, col) }
       end
 
+      # Validate a qualified `table.column` reference against the real
+      # columns of the model that owns `table_name`. Table gating (TableGate)
+      # only checks whether a table is *blocked*; it never confirms the
+      # column exists on that table at all, so a syntactically valid but
+      # nonexistent qualified column previously reached SQL execution and
+      # failed as a generic adapter error instead of a typed one.
+      #
+      # @param table_name [String]
+      # @param column_name [String]
+      # @return [true]
+      # @raise [ValidationError] if the table is unmapped or the column is unknown on it
+      def validate_table_column!(table_name, column_name)
+        model_name = @model_by_table[table_name.to_s]
+        unless model_name
+          raise ValidationError,
+                "Unknown table '#{table_name}'. Cannot validate qualified column " \
+                "'#{table_name}.#{column_name}'."
+        end
+
+        validate_column!(model_name, column_name)
+      end
+
       # List all known model names.
       #
       # @return [Array<String>]

data/lib/woods/console/rack_middleware.rb

@@ -17,9 +17,8 @@ module Woods
     #
     #   config.middleware.use Woods::Console::RackMiddleware, path: '/mcp/console'
     #
-    # This mounts 31 console tools at /mcp/console. By default, console_sql and
-    # console_query are blocked in embedded mode and return an "unsupported" error
-    # pointing users to enable the flag.
+    # This mounts the 9 executable Tier 1 tools at /mcp/console. Explicit
+    # read-tool mode registers console_sql and console_query as well.
     #
     # == Enabling the feature
     #
@@ -31,10 +30,12 @@ module Woods
     #     config.console_redacted_columns = %w[api_token password_digest]
     #   end
     #
-    # With the flag off, requests to the mounted path return 410 Gone so
-    # operators can see the endpoint exists but is gated. See
-    # docs/CONSOLE_MCP_SETUP.md for the full security posture (blocked tables,
-    # credential scanner, column/EAV redaction, SafeContext rollback).
+    # With the flag off, requests — including those at the mounted path —
+    # pass through to the app untouched. The Woods railtie mounts this
+    # middleware unconditionally (#183), so a host that has not opted in
+    # must be completely unaffected. See docs/CONSOLE_MCP_SETUP.md for the
+    # full security posture (blocked tables, credential scanner, column/EAV
+    # redaction, SafeContext rollback).
     #
     # == Enabling read tools (console_sql + console_query)
     #
@@ -48,9 +49,11 @@ module Woods
     #
     # Security posture with embedded_read_tools: true:
     #
-    # 1. SqlValidator denylist — console_sql rejects INSERT/UPDATE/DELETE/DROP/TRUNCATE/
-    #    ALTER/CREATE/REPLACE and similar DML/DDL at the string level before any database
-    #    interaction. Only SELECT and WITH...SELECT are allowed.
+    # 1. SqlValidator — console_sql rejects INSERT/UPDATE/DELETE/DROP/TRUNCATE/ALTER/CREATE
+    #    and similar DML/DDL keywords via a denylist at the string level before any database
+    #    interaction. REPLACE is rejected too, but by the separate allowed-prefix check
+    #    (only SELECT, WITH, and EXPLAIN may lead a statement), not the denylist — it isn't
+    #    in SqlValidator::FORBIDDEN_KEYWORDS.
     #
     # 2. SafeContext rollback — every request (including console_query) runs inside
     #    a database transaction that is always rolled back on completion. Even if a
@@ -61,59 +64,65 @@ module Woods
     #    ActiveRecord::Base's pool and returns it after the response. No shared
     #    mutable state leaks between requests.
     #
-    # These three layers make embedded_read_tools: true safe for read-only workloads.
-    # If your threat model requires stricter isolation, use the bridge mode instead
-    # (docs/CONSOLE_MCP_SETUP.md) which runs the executor in a separate process.
+    # These three layers define the supported read-tool posture. Keep read tools
+    # disabled when the host requires a narrower database capability.
     #
-    class RackMiddleware
+    class RackMiddleware # rubocop:disable Metrics/ClassLength
       # @param app [#call] The next Rack app in the middleware stack
       # @param path [String] URL path to mount the MCP endpoint (default: '/mcp/console')
-      # @param embedded_read_tools [Boolean] Enable sql/query tools in embedded mode (default: false)
-      # @param unsafe_eval_confirmation [Confirmation, nil] Approval callback for the
-      #   `console_eval` opt-in. Required when `WOODS_CONSOLE_UNSAFE_EVAL=true` (or
-      #   `config.console_unsafe_eval_enabled = true`); the server refuses to boot
-      #   without it. Takes precedence over `config.console_unsafe_eval_confirmation`.
-      # @param unsafe_eval_audit_log_path [String, Pathname, nil] JSONL audit log
-      #   path for every `console_eval` run. Required on the opt-in path. Takes
-      #   precedence over `config.console_unsafe_eval_audit_log_path`.
-      def initialize(app, path: '/mcp/console', embedded_read_tools: false,
-                     unsafe_eval_confirmation: nil, unsafe_eval_audit_log_path: nil)
+      # @param embedded_read_tools [Boolean, #call] Enable sql/query tools in
+      #   embedded mode (default: false). May be a callable resolved when the
+      #   server is first built — the railtie passes one because middleware
+      #   arguments are captured before config/initializers run (#183).
+      # @param stateless [Boolean, #call] Use modern stateless Streamable HTTP
+      #   semantics (default: true). Set false only for compatibility with a
+      #   client that still requires MCP session IDs.
+      # @param unsafe_eval_confirmation [Confirmation, nil] Legacy option retained
+      #   for compatibility. Passing it fails closed because console_eval is unavailable.
+      # @param unsafe_eval_audit_log_path [String, Pathname, nil] Legacy option retained
+      #   for compatibility. Passing it fails closed because console_eval is unavailable.
+      def initialize(app, path: '/mcp/console', embedded_read_tools: false, # rubocop:disable Metrics/ParameterLists
+                     unsafe_eval_confirmation: nil, unsafe_eval_audit_log_path: nil,
+                     stateless: true)
         @app = app
         @path = path
         @embedded_read_tools = embedded_read_tools
         @unsafe_eval_confirmation = unsafe_eval_confirmation
         @unsafe_eval_audit_log_path = unsafe_eval_audit_log_path
+        @stateless = stateless
         @mutex = Mutex.new
         @transport = nil
       end
 
-      DISABLED_BODY = JSON.generate(
-        error: 'woods_console_disabled',
-        message: 'Woods Console MCP is disabled. Set ' \
-                 'Woods.configuration.console_mcp_enabled = true to enable. ' \
-                 'See docs/CONSOLE_MCP_SETUP.md for the full security posture.'
-      ).freeze
-
       # Rack interface — intercepts requests at the configured path.
       #
-      # Returns 410 Gone when Woods.configuration.console_mcp_enabled is false
-      # (the default). This keeps the middleware inert on hosts that have
-      # mounted it but not yet opted into the feature. All other requests at
-      # non-matching paths pass through to the wrapped app unchanged.
+      # The enabled flag is read from Woods.configuration on every request,
+      # never captured at construction: the railtie inserts this middleware
+      # before config/initializers have run (#183). While
+      # `console_mcp_enabled` is false (the default), requests — even at the
+      # mounted path — pass through to the wrapped app unchanged, so a host
+      # that never opted in is completely unaffected. Requests at
+      # non-matching paths always pass through.
       #
       # @param env [Hash] Rack environment
       # @return [Array] Rack response triple
       def call(env)
-        return @app.call(env) unless env['PATH_INFO'].start_with?(@path)
-        return [410, { 'content-type' => 'application/json' }, [DISABLED_BODY]] unless enabled?
+        return @app.call(env) unless env['PATH_INFO'].to_s.start_with?(@path)
+        return @app.call(env) unless enabled?
 
-        ensure_transport.handle_request(Rack::Request.new(env))
+        transport = ensure_transport
+        request_env = env.dup
+        request_env.delete('HTTP_MCP_SESSION_ID') if @stateless_mode
+        transport.handle_request(Rack::Request.new(request_env))
       end
 
       private
 
+      # Whether the console is enabled, read from the live configuration on
+      # every request. Nil-safe: the railtie mounts this middleware in every
+      # app (#183), including hosts that never called Woods.configure.
       def enabled?
-        Woods.configuration.console_mcp_enabled
+        Woods.configuration&.console_mcp_enabled
       end
 
       # Thread-safe lazy initialization of the MCP server and transport.
@@ -131,7 +140,10 @@ module Woods
           Rails.application.eager_load!
 
           server = build_embedded_server
-          @transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(server)
+          @stateless_mode = resolve_deferred(@stateless)
+          @transport = ::MCP::Server::Transports::StreamableHTTPTransport.new(
+            server, stateless: @stateless_mode
+          )
           server.transport = @transport
           @transport
         end
@@ -176,11 +188,11 @@ module Woods
         config = Woods.configuration
         introspection = build_model_introspection
         Server.build_embedded(
-          model_validator: ModelValidator.new(registry: introspection[:registry]),
+          model_validator: ModelValidator.new(registry: introspection[:registry], table_names: introspection[:tables]),
           safe_context: SafeContext.new(pool: ActiveRecord::Base.connection_pool),
           redacted_columns: Array(config&.console_redacted_columns),
           redacted_key_values: Array(config&.console_redacted_key_values),
-          read_tools_enabled: @embedded_read_tools,
+          read_tools_enabled: resolve_deferred(@embedded_read_tools),
           model_tables: introspection[:tables],
           model_reflections: introspection[:reflections],
           unsafe_eval_confirmation: @unsafe_eval_confirmation,
@@ -235,6 +247,17 @@ module Woods
         end
       end
 
+      # Resolve a constructor option that may have been passed as a callable.
+      # The railtie defers option values because middleware arguments are
+      # captured at railtie-initializer time — before config/initializers
+      # have run (#183).
+      #
+      # @param value [Object, #call]
+      # @return [Object]
+      def resolve_deferred(value)
+        value.respond_to?(:call) ? value.call : value
+      end
+
       def structured_logger
         @structured_logger ||= Woods::Observability::StructuredLogger.new
       end

data/lib/woods/console/redactor.rb

@@ -112,17 +112,30 @@ module Woods
       # Resolve EAV patterns against a `columns` header into concrete index
       # pairs. A rule only fires when both key_column and value_column are
       # present in the header, and costs nothing per row otherwise.
+      #
+      # A duplicated key or value header (an `AS` alias can shadow the real
+      # column — CON-1) makes index attribution ambiguous: a last-index-wins
+      # lookup would let the shadow steal the mask from the secret. The
+      # executor refuses those selects up front; here, defense-in-depth
+      # fails toward masking — every cell under a value-named header is
+      # redacted unconditionally.
       def positional_kv_rules(columns, ctx)
         return [] unless columns.is_a?(Array)
 
-        index = columns.each_with_index.to_h { |name, idx| [name.to_s, idx] }
-        ctx.redacted_key_values.filter_map do |pattern|
-          key_idx = index[pattern['key_column']]
-          val_idx = index[pattern['value_column']]
-          next unless key_idx && val_idx
+        names = columns.map(&:to_s)
+        ctx.redacted_key_values.filter_map { |pattern| positional_kv_rule(names, pattern) }
+      end
+
+      # One resolved rule for one EAV pattern, or nil when the header lacks
+      # either column. Unambiguous headers get the key/value index pair;
+      # duplicated headers get the unconditional mask list.
+      def positional_kv_rule(names, pattern)
+        key_idxs = names.each_index.select { |i| names[i] == pattern['key_column'] }
+        val_idxs = names.each_index.select { |i| names[i] == pattern['value_column'] }
+        return nil if key_idxs.empty? || val_idxs.empty?
+        return { mask_idxs: val_idxs } unless key_idxs.one? && val_idxs.one?
 
-          { key_idx: key_idx, val_idx: val_idx, sensitive: pattern['sensitive_keys'] }
-        end
+        { key_idx: key_idxs.first, val_idx: val_idxs.first, sensitive: pattern['sensitive_keys'] }
       end
 
       # Redact positional row data using a precomputed plan. Handles both
@@ -140,7 +153,12 @@ module Woods
       def redact_row(row, plan)
         result = apply_mask(row, plan[:mask])
         plan[:kv_rules].each do |rule|
-          result[rule[:val_idx]] = '[REDACTED]' if rule[:sensitive].include?(row[rule[:key_idx]].to_s)
+          if rule[:mask_idxs]
+            # Ambiguous (duplicated) headers: mask every value-named cell.
+            rule[:mask_idxs].each { |idx| result[idx] = '[REDACTED]' }
+          elsif rule[:sensitive].include?(row[rule[:key_idx]].to_s)
+            result[rule[:val_idx]] = '[REDACTED]'
+          end
         end
         result
       end

data/lib/woods/console/safe_context.rb

@@ -13,8 +13,10 @@ module Woods
     #
     # Safety layers:
     # - Every query runs inside a transaction that is always rolled back
-    # - Statement timeout uses `SET LOCAL` so it cannot leak to the next
-    #   pool consumer
+    # - Statement timeout cannot leak to the next pool consumer: PostgreSQL
+    #   uses `SET LOCAL`, which self-discards at transaction end; MySQL has
+    #   no LOCAL equivalent, so its session-scoped `max_execution_time` is
+    #   read before the override and restored in an `ensure` instead
     # - Column redaction replaces sensitive values with "[REDACTED]"
     #
     # == What SafeContext does NOT cover
@@ -86,7 +88,7 @@ module Woods
     #     ]
     #   )
     #
-    class SafeContext
+    class SafeContext # rubocop:disable Metrics/ClassLength
       # Thread-local key that exposes the connection currently leased for
       # the in-flight #execute block. Handlers should prefer this over
       # acquiring their own connection so every request stays on a single
@@ -183,6 +185,24 @@ module Woods
         apply_key_value_redaction(redacted)
       end
 
+      # Return a SafeContext that keeps THIS context's execution behavior —
+      # the same pool (or wrapped connection), statement timeout, and
+      # rolled-back transaction — with the given redaction policy applied,
+      # so the executor and the renderer can share one policy-complete
+      # context. A non-empty kwarg defines that list (the documented
+      # configuration surface); an empty kwarg preserves the list this
+      # context already carries, so spec-style wiring that configures
+      # lists on the context keeps working. See {initialize} for the
+      # kwarg shapes.
+      #
+      # @return [SafeContext]
+      def with_redaction_policy(redacted_columns: [], redacted_key_values: [])
+        policy_columns = redacted_columns.empty? ? @redacted_columns : redacted_columns
+        policy_key_values = redacted_key_values.empty? ? @redacted_key_values : redacted_key_values
+        SafeContext.new(pool: @pool, timeout_ms: @timeout_ms,
+                        redacted_columns: policy_columns, redacted_key_values: policy_key_values)
+      end
+
       private
 
       # Wrap one connection in a rolled-back transaction with timeout, and
@@ -190,17 +210,21 @@ module Woods
       # clears the thread-local in ensure so a raise mid-block cannot leak
       # a stale connection reference into the next request on this thread.
       def run_with_timeout(connection)
-        previous = Thread.current[LEASED_CONNECTION_KEY]
+        previous_lease = Thread.current[LEASED_CONNECTION_KEY]
         Thread.current[LEASED_CONNECTION_KEY] = connection
         result = nil
         connection.transaction do
-          set_timeout(connection)
-          result = yield(connection)
+          restore_timeout = set_timeout(connection)
+          begin
+            result = yield(connection)
+          ensure
+            restore_timeout&.call
+          end
           raise ActiveRecord::Rollback
         end
         result
       ensure
-        Thread.current[LEASED_CONNECTION_KEY] = previous
+        Thread.current[LEASED_CONNECTION_KEY] = previous_lease
       end
 
       def normalize_key_value_patterns(patterns)
@@ -241,14 +265,25 @@ module Woods
       # request, background job, etc.). Safe here because every #execute
       # is wrapped in a transaction.
       #
-      # MySQL uses `SET max_execution_time` (applies to SELECT only — DDL
-      # and DML statements cannot be time-limited via this variable).
+      # MySQL has no per-statement equivalent of `SET LOCAL`: `SET
+      # max_execution_time` (applies to SELECT only — DDL and DML statements
+      # cannot be time-limited via this variable) is SESSION scope and
+      # survives ROLLBACK, so left alone it would leak onto the next request
+      # served from the same pooled connection. {#set_mysql_timeout} reads
+      # the session's current value first and returns a Proc that restores
+      # it; the caller runs that Proc in an +ensure+ around the yielded
+      # block.
+      #
+      # @return [Proc, nil] a restore callback for MySQL, or nil when no
+      #   restoration is needed (PostgreSQL's LOCAL scope self-discards; an
+      #   unsupported adapter sets nothing to restore).
       def set_timeout(connection, timeout_ms = @timeout_ms)
         adapter = connection.adapter_name.downcase
         if adapter.include?('mysql')
-          connection.execute("SET max_execution_time = #{timeout_ms.to_i}")
+          set_mysql_timeout(connection, timeout_ms)
         else
           connection.execute("SET LOCAL statement_timeout = '#{timeout_ms.to_i}ms'")
+          nil
         end
       rescue StandardError => e
         # Unsupported adapter (SQLite, Trilogy on unsupported version, Oracle) —
@@ -259,6 +294,19 @@ module Woods
         nil
       end
 
+      # Read MySQL's current session-scoped `max_execution_time`, override
+      # it, and return a Proc that restores the value read here. There is no
+      # per-statement `SET LOCAL` on MySQL, so the override otherwise
+      # outlives this transaction's rollback and bleeds onto whatever the
+      # pooled connection serves next.
+      #
+      # @return [Proc] restores the previous session value
+      def set_mysql_timeout(connection, timeout_ms)
+        previous_value = connection.select_value('SELECT @@SESSION.max_execution_time').to_i
+        connection.execute("SET max_execution_time = #{timeout_ms.to_i}")
+        -> { connection.execute("SET max_execution_time = #{previous_value}") }
+      end
+
       def warn_timeout_unsupported(adapter, error)
         return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
 

data/lib/woods/console/scope_predicate_parser.rb

@@ -39,6 +39,15 @@ module Woods
       # Suffix pattern — longest suffix match wins because we scan the full list.
       SUFFIX_PATTERN = /(_eq|_not_eq|_gteq|_lteq|_gt|_lt|_not_in|_not_null|_in|_null|_present|_blank|_matches)\z/
 
+      # Suffix classes, each with its own required value type. Ruby truthiness
+      # treats any non-nil, non-false value as true — so without a strict type
+      # check, `{status_present: "false"}` (a JSON string) inverts the caller's
+      # intent instead of raising. `_eq`/`_not_eq`/`_matches` accept any scalar
+      # and are intentionally not classified here.
+      EXISTENCE_SUFFIXES = %w[_null _not_null _present _blank].freeze
+      COMPARISON_SUFFIXES = %w[_gt _gteq _lt _lteq].freeze
+      SET_SUFFIXES = %w[_in _not_in].freeze
+
       SUFFIX_HINT = "Supported suffixes: #{SUPPORTED_SUFFIXES.join(', ')}.".freeze
 
       # @param model_name [String] ActiveRecord model name (e.g. 'Order')
@@ -70,8 +79,10 @@ module Woods
             suffix = match[1]
             column = key.delete_suffix(suffix)
             @model_validator.validate_column!(@model_name, column)
+            validate_suffix_value_type!(suffix, value)
             arel_nodes << build_node(relation, column, suffix, value)
           else
+            @model_validator.validate_column!(@model_name, key)
             equality[raw_key] = value
           end
         end
@@ -83,6 +94,36 @@ module Woods
 
       private
 
+      # Enforce the suffix-dependent value type before any Arel node is
+      # built. `true`/`false` are checked by identity (`==`), not truthiness,
+      # so a JSON string like `"false"` is rejected rather than silently
+      # treated as truthy.
+      #
+      # @param suffix [String] One of SUPPORTED_SUFFIXES
+      # @param value [Object] The predicate value
+      # @raise [ValidationError] when the value's type doesn't match the suffix class
+      def validate_suffix_value_type!(suffix, value)
+        case suffix
+        when *EXISTENCE_SUFFIXES
+          return if [true, false].include?(value)
+
+          raise ValidationError,
+                "Predicate suffix '#{suffix}' requires a strict boolean value " \
+                "(got #{value.class}: #{value.inspect}). #{SUFFIX_HINT}"
+        when *COMPARISON_SUFFIXES
+          return if value.is_a?(String) || value.is_a?(Numeric)
+
+          raise ValidationError,
+                "Predicate suffix '#{suffix}' requires a scalar (String or Numeric) value " \
+                "(got #{value.class}: #{value.inspect}). #{SUFFIX_HINT}"
+        end
+        # _in/_not_in are intentionally not type-checked here: build_node
+        # already wraps a scalar in a single-element Array via `Array(value)`,
+        # a pre-existing, separately-tested convenience for callers building
+        # scope hashes programmatically. The public JSON Schema still
+        # requires a real array for _in/_not_in at the MCP boundary.
+      end
+
       # Build an Arel predicate node for a validated column + suffix.
       #
       # @param relation [ActiveRecord::Relation, Class] Used to get the arel_table