tina4ruby 3.13.130 → 3.13.132

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb72d4eef1764922872e50ac7f826e90348f10f7bf069013d6bc266cad69c141
-  data.tar.gz: 97d04e7d94c9322784259fff6a3db3336da73f2c825232a1fd7933eac819e2a0
+  metadata.gz: bf58fba1e80ebbfcdeccfdf5ecab50bf0ce08754d834eaffe29e9e7e37ff4363
+  data.tar.gz: f59a4a709438114acd05275ee4220e032ebe539b3d27547b377de492f2583038
 SHA512:
-  metadata.gz: d5a470035bb0c47a676b1d5e56c1ecdc0d072a38dfc99d7aeea2df67b29d637a6b3ac74d21d7c7962faecb2248b1b1f0da1472b16ff6002915d560e5fbdad0fa
-  data.tar.gz: 7090764cf7dc0ea9fca18ca7e526e63e1b3618498efd5c8cf92cebdc8256458e1e6eaf9fbd87eb78b1b0c168abbd678b8ce1311f2764d15f63d0e2c114e4fbc2
+  metadata.gz: 3b4c3b693f8686a0119ed679627ab646439c4e7e4b75649e55e70e5207556582b06bd3413fe4560cbc60183f6f66f6732f4fe11e4c87b7358b2b7327976f5841
+  data.tar.gz: 93b12a0719367dc9c8e4f1a95339d43ae170ea14e4ea52c347d9419044ad508ff894c08ba11a1c930920365a779ca5e0ab95a7e442a8fe60383d35d5fdeac045

data/lib/tina4/dev_admin.rb

@@ -395,15 +395,6 @@ module Tina4
         denial = dev_mutation_denial(env)
         return denial if denial
 
-        # Dynamic-path routes can't live in the case-tuple below — match
-        # them up front. /__dev/api/threads/{id}[/messages] is forwarded
-        # verbatim to the Rust agent's /threads/{id}[/messages] surface
-        # (mirrors Python's `_api_threads_sub`).
-        if path.start_with?("/__dev/api/threads/")
-          suffix = path[("/__dev/api".length)..]  # leaves "/threads/{id}[/messages]"
-          return threads_sub_proxy(env, method, suffix)
-        end
-
         case [method, path]
         when ["GET", "/__dev"], ["GET", "/__dev/"]
           serve_dashboard
@@ -606,22 +597,6 @@ module Tina4
         when ["POST", "/__dev/api/grounding/token"]
           body = read_json_body(env) || {}
           json_response(grounding_token_save(body))
-        when ["POST", "/__dev/api/chat"]
-          # Proxy dev-admin chat to the Rust agent's /chat endpoint.
-          # The SPA POSTs {message, thread_id?, active_file?, settings?}
-          # and expects an SSE stream of `event: status/message/done`
-          # chunks. We forward the JSON body verbatim (active_file rides
-          # along) and pipe upstream bytes back as they arrive. Mirrors
-          # Python's `_api_chat` / `_proxy_to_supervisor` SSE path.
-          body = read_json_body(env) || {}
-          chat_proxy(body)
-        when ["GET", "/__dev/api/threads"]
-          # Parity with Python `_api_threads` (GET → list threads).
-          json_response(proxy_supervisor("/threads", method: "GET", query: env["QUERY_STRING"]))
-        when ["POST", "/__dev/api/threads"]
-          # Parity with Python `_api_threads` (POST → create thread).
-          body = read_json_body(env) || {}
-          json_response(proxy_supervisor("/threads", method: "POST", body: body))
         when ["GET", "/__dev/api/connections"]
           handle_connections_get
         when ["POST", "/__dev/api/connections/test"]
@@ -664,24 +639,6 @@ module Tina4
                        e.message.include?("needs a path")
             json_response({ "error" => e.message }, bad_path ? 404 : 503)
           end
-        when ["GET", "/__dev/api/thoughts"]
-          json_response(thoughts_payload)
-        when ["POST", "/__dev/api/supervise/create"]
-          body = read_json_body(env) || {}
-          json_response(proxy_supervisor("/supervise/create", method: "POST", body: body))
-        when ["GET", "/__dev/api/supervise/sessions"]
-          json_response(proxy_supervisor("/supervise/sessions", method: "GET", query: env["QUERY_STRING"]))
-        when ["GET", "/__dev/api/supervise/diff"]
-          json_response(proxy_supervisor("/supervise/diff", method: "GET", query: env["QUERY_STRING"]))
-        when ["POST", "/__dev/api/supervise/commit"]
-          body = read_json_body(env) || {}
-          json_response(proxy_supervisor("/supervise/commit", method: "POST", body: body))
-        when ["POST", "/__dev/api/supervise/cancel"]
-          body = read_json_body(env) || {}
-          json_response(proxy_supervisor("/supervise/cancel", method: "POST", body: body))
-        when ["POST", "/__dev/api/execute"]
-          body = read_json_body(env) || {}
-          execute_proxy(body)
         when ["GET", "/__dev/api/files"]
           json_response(files_list(env))
         when ["GET", "/__dev/api/file"]
@@ -1580,170 +1537,6 @@ module Tina4
         { deployed: name, files: copied }
       end
 
-      # ── New dev-admin surface area (parity with Python/PHP) ────
-
-      def supervisor_base
-        base = ENV["TINA4_SUPERVISOR_URL"].to_s.strip
-        return base unless base.empty?
-        port = (ENV["TINA4_PORT"] || ENV["PORT"] || "7147").to_i + 2000
-        "http://127.0.0.1:#{port}"
-      end
-
-      def thoughts_payload
-        base = supervisor_base
-        begin
-          uri = URI.parse("#{base}/thoughts")
-          req = Net::HTTP::Get.new(uri)
-          resp = Net::HTTP.start(uri.host, uri.port, open_timeout: 2, read_timeout: 5) { |h| h.request(req) }
-          return JSON.parse(resp.body) if resp.is_a?(Net::HTTPSuccess)
-          { thoughts: [], error: "Supervisor returned #{resp.code}" }
-        rescue StandardError => e
-          { thoughts: [], error: e.message }
-        end
-      end
-
-      def proxy_supervisor(path, method: "GET", body: nil, query: nil)
-        base = supervisor_base
-        url = "#{base}#{path}"
-        url += "?#{query}" if query && !query.empty?
-        begin
-          uri = URI.parse(url)
-          req = case method.upcase
-                when "POST"
-                  r = Net::HTTP::Post.new(uri)
-                  r["Content-Type"] = "application/json"
-                  r.body = JSON.generate(body || {})
-                  r
-                when "PATCH"
-                  r = Net::HTTP::Patch.new(uri)
-                  r["Content-Type"] = "application/json"
-                  r.body = JSON.generate(body || {})
-                  r
-                when "PUT"
-                  r = Net::HTTP::Put.new(uri)
-                  r["Content-Type"] = "application/json"
-                  r.body = JSON.generate(body || {})
-                  r
-                when "DELETE"
-                  r = Net::HTTP::Delete.new(uri)
-                  r["Content-Type"] = "application/json"
-                  r.body = JSON.generate(body) if body
-                  r
-                else
-                  Net::HTTP::Get.new(uri)
-                end
-          resp = Net::HTTP.start(uri.host, uri.port, open_timeout: 2, read_timeout: 30) { |h| h.request(req) }
-          begin
-            JSON.parse(resp.body)
-          rescue JSON::ParserError
-            { body: resp.body, status: resp.code.to_i }
-          end
-        rescue StandardError => e
-          { error: e.message, supervisor: base }
-        end
-      end
-
-      # Proxy /__dev/api/threads/{id}[/messages] through to the Rust
-      # agent. Mirrors Python's `_api_threads_sub`: we already stripped
-      # the dev-admin prefix in handle_request, so `suffix` is the path
-      # the agent expects (e.g. `/threads/abc` or `/threads/abc/messages`).
-      # PATCH /threads/{id} (archive/rename) and GET /threads/{id}/messages
-      # are the two shapes the SPA actually fires.
-      def threads_sub_proxy(env, method, suffix)
-        case method.upcase
-        when "GET"
-          json_response(proxy_supervisor(suffix, method: "GET", query: env["QUERY_STRING"]))
-        when "POST"
-          body = read_json_body(env) || {}
-          json_response(proxy_supervisor(suffix, method: "POST", body: body))
-        when "PATCH"
-          body = read_json_body(env) || {}
-          json_response(proxy_supervisor(suffix, method: "PATCH", body: body))
-        when "PUT"
-          body = read_json_body(env) || {}
-          json_response(proxy_supervisor(suffix, method: "PUT", body: body))
-        when "DELETE"
-          body = read_json_body(env)
-          json_response(proxy_supervisor(suffix, method: "DELETE", body: body))
-        else
-          [405, { "content-type" => "application/json; charset=utf-8" },
-           [JSON.generate({ error: "method not allowed" })]]
-        end
-      end
-
-      # POST /chat — proxy the SPA's chat payload to the Rust agent and
-      # pipe the upstream SSE response back to the browser. Active-file
-      # content (when present in the body) rides along verbatim.
-      #
-      # NOTE on streaming: Tina4 Ruby's Rack app does not currently
-      # expose a chunk-by-chunk streaming API to handlers (see
-      # response.rb — `response.stream(&block)` is not yet wired through
-      # the case-tuple dispatcher used here). We do the next best thing:
-      # use Net::HTTP#request_get with a block so we receive upstream
-      # SSE chunks as they arrive, buffer them, and return the assembled
-      # body with the upstream content-type intact. The SPA's
-      # EventSource reader works either way (it parses `data:` lines
-      # regardless of arrival cadence) — the TODO below tracks
-      # converting this to a true streamed Rack body once dev_admin
-      # routes are migrated off the case-tuple dispatcher.
-      def chat_proxy(body)
-        base = supervisor_base
-        begin
-          uri = URI.parse("#{base}/chat")
-          req = Net::HTTP::Post.new(uri)
-          req["Content-Type"] = "application/json"
-          req["Accept"] = "text/event-stream"
-          req.body = JSON.generate(body || {})
-          http = Net::HTTP.new(uri.host, uri.port)
-          http.open_timeout = 2
-          # /chat runs the supervisor → planner → coder loop with one or
-          # more LLM round-trips. Matches Python's 600s budget.
-          http.read_timeout = 600
-          chunks = []
-          upstream_status = 200
-          upstream_ct = "text/event-stream"
-          http.request(req) do |resp|
-            upstream_status = resp.code.to_i
-            upstream_ct = resp["content-type"] || upstream_ct
-            # TODO: stream chunks straight into the Rack response once
-            # dev_admin migrates to response.stream(). For now we
-            # buffer — the SPA's SSE reader still parses correctly.
-            resp.read_body { |chunk| chunks << chunk }
-          end
-          [upstream_status, { "content-type" => upstream_ct }, [chunks.join]]
-        rescue StandardError => e
-          body_str = JSON.generate({
-            error: "supervisor unavailable",
-            detail: e.message,
-            hint: "Run `tina4 serve` (starts the agent server) or set TINA4_SUPERVISOR_URL",
-            supervisor: base
-          })
-          [503, { "content-type" => "application/json; charset=utf-8" }, [body_str]]
-        end
-      end
-
-      def execute_proxy(body)
-        # Proxy POST /execute to the supervisor at framework_port + 2000.
-        # Pass through the response stream as-is (SSE or JSON).
-        base = supervisor_base
-        begin
-          uri = URI.parse("#{base}/execute")
-          req = Net::HTTP::Post.new(uri)
-          req["Content-Type"] = "application/json"
-          req["Accept"] = "text/event-stream"
-          req.body = JSON.generate(body || {})
-          http = Net::HTTP.new(uri.host, uri.port)
-          http.open_timeout = 2
-          http.read_timeout = 300
-          resp = http.request(req)
-          ct = resp["content-type"] || "application/json; charset=utf-8"
-          [resp.code.to_i, { "content-type" => ct }, [resp.body.to_s]]
-        rescue StandardError => e
-          body_str = JSON.generate({ error: e.message, supervisor: base })
-          [502, { "content-type" => "application/json; charset=utf-8" }, [body_str]]
-        end
-      end
-
       def safe_project_path(rel_path)
         root = File.expand_path(Dir.pwd)
         resolved = File.expand_path(rel_path.to_s, root)

data/lib/tina4/frond.rb

@@ -2489,6 +2489,40 @@ module Tina4
       }
     end
 
+    # Collect the body tokens of a {% <open_tag> %}...{% <close_tag> %} block,
+    # honoring nested same-tag pairs. `start` is the index of the opening tag;
+    # returns [body_tokens, index_just_past_the_matching_close]. Shared by
+    # handle_cache / handle_spaceless / handle_autoescape, whose collection
+    # loops were identical apart from the tag names.
+    def collect_block_body(tokens, start, open_tag, close_tag)
+      body_tokens = []
+      i = start + 1
+      depth = 0
+      while i < tokens.length
+        if tokens[i][0] == BLOCK
+          tc, _, _ = strip_tag(tokens[i][1])
+          tag = tc.split[0] || ""
+          if tag == open_tag
+            depth += 1
+            body_tokens << tokens[i]
+          elsif tag == close_tag
+            if depth == 0
+              i += 1
+              break
+            end
+            depth -= 1
+            body_tokens << tokens[i]
+          else
+            body_tokens << tokens[i]
+          end
+        else
+          body_tokens << tokens[i]
+        end
+        i += 1
+      end
+      [body_tokens, i]
+    end
+
     # {% cache "key" ttl %}...{% endcache %}
     def handle_cache(tokens, start, context)
       content, _, _ = strip_tag(tokens[start][1])
@@ -2523,31 +2557,7 @@ module Tina4
         end
       end
 
-      body_tokens = []
-      i = start + 1
-      depth = 0
-      while i < tokens.length
-        if tokens[i][0] == BLOCK
-          tc, _, _ = strip_tag(tokens[i][1])
-          tag = tc.split[0] || ""
-          if tag == "cache"
-            depth += 1
-            body_tokens << tokens[i]
-          elsif tag == "endcache"
-            if depth == 0
-              i += 1
-              break
-            end
-            depth -= 1
-            body_tokens << tokens[i]
-          else
-            body_tokens << tokens[i]
-          end
-        else
-          body_tokens << tokens[i]
-        end
-        i += 1
-      end
+      body_tokens, i = collect_block_body(tokens, start, "cache", "endcache")
 
       rendered = render_tokens(body_tokens.dup, context)
       cap_cache(@fragment_cache, TEMPLATE_CACHE_MAX)
@@ -2773,31 +2783,7 @@ module Tina4
     end
 
     def handle_spaceless(tokens, start, context)
-      body_tokens = []
-      i = start + 1
-      depth = 0
-      while i < tokens.length
-        if tokens[i][0] == BLOCK
-          tc, _, _ = strip_tag(tokens[i][1])
-          tag = tc.split[0] || ""
-          if tag == "spaceless"
-            depth += 1
-            body_tokens << tokens[i]
-          elsif tag == "endspaceless"
-            if depth == 0
-              i += 1
-              break
-            end
-            depth -= 1
-            body_tokens << tokens[i]
-          else
-            body_tokens << tokens[i]
-          end
-        else
-          body_tokens << tokens[i]
-        end
-        i += 1
-      end
+      body_tokens, i = collect_block_body(tokens, start, "spaceless", "endspaceless")
 
       rendered = render_tokens(body_tokens.dup, context)
       rendered = rendered.gsub(SPACELESS_RE, "><")
@@ -2809,31 +2795,7 @@ module Tina4
       mode_match = content.match(AUTOESCAPE_RE)
       auto_escape_on = !(mode_match && mode_match[1] == "false")
 
-      body_tokens = []
-      i = start + 1
-      depth = 0
-      while i < tokens.length
-        if tokens[i][0] == BLOCK
-          tc, _, _ = strip_tag(tokens[i][1])
-          tag = tc.split[0] || ""
-          if tag == "autoescape"
-            depth += 1
-            body_tokens << tokens[i]
-          elsif tag == "endautoescape"
-            if depth == 0
-              i += 1
-              break
-            end
-            depth -= 1
-            body_tokens << tokens[i]
-          else
-            body_tokens << tokens[i]
-          end
-        else
-          body_tokens << tokens[i]
-        end
-        i += 1
-      end
+      body_tokens, i = collect_block_body(tokens, start, "autoescape", "endautoescape")
 
       if !auto_escape_on
         old_auto_escape = @auto_escape

data/lib/tina4/model_collection.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Tina4
+  # A list of ORM models that ALSO carries the total rows matching the query.
+  #
+  # ModelCollection is what the ORM read queries (+where+ / +select+ / +find+
+  # (filter form) / +all+ / +with_trashed+) return. It IS an Array -- iterate it,
+  # index it, slice it, map it, count it, serialise it to JSON -- so every
+  # existing caller keeps working unchanged. It adds one thing: the TOTAL number
+  # of rows matching the query's filter, independent of +limit+ / +offset+.
+  #
+  # The total is free. Every one of those methods already runs +db.fetch+, which
+  # computes a +SELECT COUNT(*)+ probe and hands it back on +DatabaseResult#count+;
+  # the ORM used to hydrate the page of models and throw that count away. This
+  # class carries it instead, so a caller with 20 models on the page can still
+  # learn there are 250 rows in the set -- with ZERO extra queries.
+  #
+  # Uniform across all four Tina4 frameworks (ADR-0064). Same concept, language-
+  # idiomatic accessor name:
+  #
+  #     Python / Ruby : get_total_records   to_paginate
+  #     PHP / Node    : getTotalRecords     toPaginate
+  #
+  # The accessor is a METHOD, not a +.total+ property, on purpose: +Array#count+
+  # already exists, so a +.count+ would shadow a built-in. +DatabaseResult+ keeps
+  # its +.count+ (it is not an Array); both expose the identical seven-key
+  # +to_paginate+ envelope (ADR-0043).
+  class ModelCollection < Array
+    # The SQL limit / offset that produced this page -- carried for to_paginate.
+    # The total is exposed only through get_total_records (the documented
+    # accessor), never a bare reader, so it reads the same in every framework.
+    attr_reader :limit, :offset
+
+    # @param items  [Array] the page of hydrated model instances
+    # @param total  [Integer] total rows matching the query's filter (ignores limit/offset)
+    # @param limit  [Integer] the SQL limit that produced this page (0 = none applied)
+    # @param offset [Integer] the SQL offset that produced this page
+    def initialize(items = [], total: 0, limit: 0, offset: 0)
+      super()
+      concat(items || [])
+      @total = total.to_i
+      @limit = limit.to_i
+      @offset = offset.to_i
+    end
+
+    # Total rows matching the query's filter, ignoring limit / offset.
+    #
+    # This is the whole point of the collection: the page slice you are iterating
+    # is capped by +limit+, but this number is the full count of matching rows --
+    # what a pager needs to render "page 3 of 13". Sourced from the fetch COUNT
+    # probe (+DatabaseResult#count+); no second query is fired.
+    def get_total_records
+      @total
+    end
+
+    # The canonical pagination envelope -- seven snake_case keys, identical to
+    # +DatabaseResult#to_paginate+ (ADR-0043) and to the other three frameworks'
+    # +toPaginate+:
+    #
+    #   records     the page's rows as model hashes (never re-sliced)
+    #   total       get_total_records -- the true total for the filter
+    #   page        floor(offset / per_page) + 1
+    #   per_page    the query's limit
+    #   total_pages ceil(total / per_page)
+    #   limit       the SQL limit actually applied
+    #   offset      the SQL offset actually applied
+    #
+    # +records+ are model hashes (via +#to_h+) so the JSON a client sees matches
+    # +DatabaseResult+ exactly -- the result is uniform whether the route returned
+    # a raw +db.fetch+ or an ORM query.
+    def to_paginate
+      per_page    = @limit > 0 ? @limit : size
+      page        = per_page > 0 ? (@offset / per_page) + 1 : 1
+      total       = @total
+      total_pages = per_page > 0 ? [1, (total.to_f / per_page).ceil].max : 1
+      {
+        records: map { |model| model.respond_to?(:to_h) ? model.to_h : model },
+        total: total,
+        page: page,
+        per_page: per_page,
+        total_pages: total_pages,
+        limit: per_page,
+        offset: @offset
+      }
+    end
+  end
+end

data/lib/tina4/orm.rb

@@ -250,16 +250,25 @@ module Tina4
 
       def find(id_or_filter = nil, filter = nil, **kwargs)
         include_list = kwargs.delete(:include)
+        # find(filter, limit:, offset:, order_by:) honours pagination on the
+        # filter/all form, matching the Python master (find -> select with
+        # limit/offset/order_by). Ruby used to swallow these into **kwargs and
+        # drop them, so find({...}, limit: 10) returned the default 100-row cap
+        # instead of 10 -- a parity divergence fixed alongside the ADR-0064 port.
+        # The PK branch (find_by_id) stays single and ignores them.
+        limit = kwargs.delete(:limit) || 100
+        offset = kwargs.delete(:offset)
+        order_by = kwargs.delete(:order_by)
 
         # find(id) — find by primary key
         # find(filter_hash) — find by criteria
         # find(name: "Alice") — keyword args as filter hash
         result = if id_or_filter.is_a?(Hash)
-          find_by_filter(id_or_filter)
+          find_by_filter(id_or_filter, limit: limit, offset: offset, order_by: order_by)
         elsif filter.is_a?(Hash)
-          find_by_filter(filter)
+          find_by_filter(filter, limit: limit, offset: offset, order_by: order_by)
         elsif !kwargs.empty?
-          find_by_filter(kwargs)
+          find_by_filter(kwargs, limit: limit, offset: offset, order_by: order_by)
         else
           find_by_id(id_or_filter)
         end
@@ -369,6 +378,23 @@ module Tina4
         end
       end
 
+      # Hydrate a fetch result into a ModelCollection (ADR-0064).
+      #
+      # The page of models AND the total for the query in one return: every read
+      # path already runs db.fetch, which computes a SELECT COUNT(*) probe and
+      # hands the TRUE total back on DatabaseResult#count. We carry it on the
+      # collection instead of throwing it away -- so get_total_records() /
+      # to_paginate() cost ZERO extra queries. limit/offset are what the fetch
+      # actually applied, so ModelCollection#to_paginate matches the same-query
+      # db.fetch(...).to_paginate exactly. The soft-delete filter lives in the SQL
+      # this fetch ran, so the probe already respects it.
+      def hydrate_collection(results, include: nil)
+        instances = results.map { |row| from_hash(row) }
+        eager_load(instances, include) if include
+        ModelCollection.new(instances, total: results.count,
+                            limit: results.limit, offset: results.offset)
+      end
+
       def where(conditions, params = [], limit: 100, offset: nil, order_by: nil, include: nil)
         sql = "SELECT * FROM #{table_name}"
         if soft_delete
@@ -377,10 +403,7 @@ module Tina4
           sql += " WHERE #{conditions}"
         end
         sql += " ORDER BY #{order_by}" if order_by
-        results = db.fetch(sql, params, limit: limit, offset: offset)
-        instances = results.map { |row| from_hash(row) }
-        eager_load(instances, include) if include
-        instances
+        hydrate_collection(db.fetch(sql, params, limit: limit, offset: offset), include: include)
       end
 
       def all(limit: 100, offset: nil, order_by: nil, include: nil)
@@ -389,17 +412,11 @@ module Tina4
           sql += " WHERE #{soft_delete_field} IS NULL OR #{soft_delete_field} = 0"
         end
         sql += " ORDER BY #{order_by}" if order_by
-        results = db.fetch(sql, [], limit: limit, offset: offset)
-        instances = results.map { |row| from_hash(row) }
-        eager_load(instances, include) if include
-        instances
+        hydrate_collection(db.fetch(sql, [], limit: limit, offset: offset), include: include)
       end
 
       def select(sql, params = [], limit: 100, offset: nil, include: nil)
-        results = db.fetch(sql, params, limit: limit, offset: offset)
-        instances = results.map { |row| from_hash(row) }
-        eager_load(instances, include) if include
-        instances
+        hydrate_collection(db.fetch(sql, params, limit: limit, offset: offset), include: include)
       end
 
       def select_one(sql, params = [], include: nil)
@@ -536,8 +553,7 @@ module Tina4
 
       def with_trashed(conditions = "1=1", params = [], limit: 100, offset: 0)
         sql = "SELECT * FROM #{table_name} WHERE #{conditions}"
-        results = db.fetch(sql, params, limit: limit, offset: offset)
-        results.map { |row| from_hash(row) }
+        hydrate_collection(db.fetch(sql, params, limit: limit, offset: offset))
       end
 
       def create_table
@@ -821,14 +837,17 @@ module Tina4
         Tina4.bind_database(Tina4::Database.new(url, username: ENV.fetch("TINA4_DATABASE_USERNAME", ""), password: ENV.fetch("TINA4_DATABASE_PASSWORD", "")))
       end
 
-      def find_by_filter(filter)
+      def find_by_filter(filter, limit: 100, offset: nil, order_by: nil)
         where_parts = filter.keys.map { |k| "#{k} = ?" }
         sql = "SELECT * FROM #{table_name} WHERE #{where_parts.join(' AND ')}"
         if soft_delete
           sql += " AND (#{soft_delete_field} IS NULL OR #{soft_delete_field} = 0)"
         end
-        results = db.fetch(sql, filter.values)
-        results.map { |row| from_hash(row) }
+        sql += " ORDER BY #{order_by}" if order_by
+        # find(filter) returns a ModelCollection (ADR-0064); find(pk) stays single
+        # (find_by_id -> select_one -> .first). find() applies its own eager_load
+        # to the returned collection, which is an Array so nothing there changes.
+        hydrate_collection(db.fetch(sql, filter.values, limit: limit, offset: offset))
       end
 
       # Render a column DEFAULT literal for create_table.