tina4ruby 3.13.137 → 3.13.138

data/lib/tina4/auth.rb

@@ -1,9 +1,17 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 require "openssl"
-require "base64"
+require_relative "base64"
 require "json"
 require "fileutils"
 require "securerandom"
+require_relative "parse_json"
+require_relative "secret_file"
 
 module Tina4
   module Auth
@@ -100,12 +108,10 @@ module Tina4
           local_path = File.join(root_dir, ".env.local")
           # If the file exists and does not end in a newline, prepend one so the
           # new key lands on its own line rather than gluing onto the last value.
-          prefix = ""
-          if File.exist?(local_path)
-            content = File.read(local_path)
-            prefix = "\n" if !content.empty? && !content.end_with?("\n")
+          SecretFile.update(local_path) do |content|
+            prefix = !content.empty? && !content.end_with?("\n") ? "\n" : ""
+            content + "#{prefix}TINA4_SECRET=#{new_secret}\n"
           end
-          File.open(local_path, "a") { |f| f.write("#{prefix}TINA4_SECRET=#{new_secret}\n") }
           log_info("Auth: generated a development secret, saved to .env.local (gitignored)")
         rescue StandardError => e
           # Keep the in-memory secret for this run; just warn. Never crash boot.
@@ -139,7 +145,7 @@ module Tina4
 
       # Base64url-encode without padding (JWT spec)
       def base64url_encode(data)
-        Base64.urlsafe_encode64(data, padding: false)
+        Tina4::Base64.urlsafe_encode64(data, padding: false)
       end
 
       # Base64url-decode (handles missing padding)
@@ -147,7 +153,7 @@ module Tina4
         # Add back padding
         remainder = str.length % 4
         str += "=" * ((4 - remainder) % 4) if remainder != 0
-        Base64.urlsafe_decode64(str)
+        Tina4::Base64.urlsafe_decode64(str)
       end
 
       # Pick the JWT algorithm: explicit argument, else TINA4_JWT_ALGORITHM, else
@@ -200,10 +206,10 @@ module Tina4
       def decode_envelope(token, algorithm)
         parts = token.to_s.split(".")
         return nil unless parts.length == 3
-        return nil unless JSON.parse(base64url_decode(parts[0]))["alg"] == algorithm
+        return nil unless Tina4.parse_json(base64url_decode(parts[0]))["alg"] == algorithm
         return nil unless yield("#{parts[0]}.#{parts[1]}", base64url_decode(parts[2]))
 
-        payload = JSON.parse(base64url_decode(parts[1]))
+        payload = Tina4.parse_json(base64url_decode(parts[1]))
         now = Time.now.to_i
 
         # RFC 7519 s4.1.4: "The processing of the 'exp' claim requires that the
@@ -361,7 +367,7 @@ module Tina4
         return nil unless parts.length == 3
 
         payload_json = base64url_decode(parts[1])
-        JSON.parse(payload_json)
+        Tina4.parse_json(payload_json)
       rescue ArgumentError, JSON::ParserError
         nil
       end
@@ -564,7 +570,7 @@ module Tina4
       def generate_keys
         Tina4::Log.info("Generating RSA key pair for JWT authentication")
         key = OpenSSL::PKey::RSA.generate(2048)
-        File.write(private_key_path, key.to_pem)
+        SecretFile.update(private_key_path) { key.to_pem }
         File.write(public_key_path, key.public_key.to_pem)
         @private_key = nil
         @public_key = nil

data/lib/tina4/auto_crud.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 require "json"
 
 module Tina4
@@ -105,17 +111,46 @@ module Tina4
             page     = [page, 1].max
             limit    = per_page
             offset   = req.query["offset"] ? req.query["offset"].to_i : (page - 1) * per_page
-            order_by = parse_sort(req.query["sort"])
 
-            # Filter support: ?filter[field]=value
+            # Filter support: ?filter[field]=value. ADR-0069: ANY bracket key is
+            # captured and must resolve to a declared field (attribute or its
+            # mapped column); an unknown key is a 400 before any SQL runs.
+            #
+            # The query parser keeps bracketed keys flat, so a list or map shows
+            # up as "sort[...]" or "filter[name][...]": a 400, never ignored.
+            if req.query.keys.any? { |key| key.start_with?("sort[") }
+              next res.error("INVALID_QUERY_PARAMETER",
+                             "Query parameter 'sort' must be a single comma-separated string", 400)
+            end
+
             filter_conditions = []
             filter_values = []
+            unknown_filter_field = nil
+            nested_filter_field = nil
             req.query.each do |key, value|
-              if key =~ /\Afilter\[(\w+)\]\z/
-                filter_conditions << "#{$1} = ?"
-                filter_values << value
+              next unless key =~ /\Afilter\[(.*)\]\z/m
+
+              filter_key = Regexp.last_match(1)
+              if filter_key.include?("][")
+                nested_filter_field = filter_key.split("][", 2).first
+                break
               end
+              column = model_class.resolve_field_column(filter_key)
+              unless column
+                unknown_filter_field = filter_key
+                break
+              end
+              filter_conditions << "#{column} = ?"
+              filter_values << value
+            end
+            if nested_filter_field
+              next res.error("INVALID_QUERY_PARAMETER",
+                             "Filter value for '#{nested_filter_field}' must be a single value", 400)
             end
+            next res.error("UNKNOWN_FIELD", "Unknown filter field '#{unknown_filter_field}'", 400) if unknown_filter_field
+
+            order_by, unknown_sort_field = parse_sort(model_class, req.query["sort"])
+            next res.error("UNKNOWN_FIELD", "Unknown sort field '#{unknown_sort_field}'", 400) if unknown_sort_field
 
             if filter_conditions.empty?
               records = model_class.all(limit: limit, offset: offset, order_by: order_by)
@@ -150,8 +185,7 @@ module Tina4
         # GET /api/{table}/{id} -- get single record
         Tina4::Router.add("GET", "#{prefix}/#{table}/{id}", proc { |req, res|
           begin
-            id = req.params["id"]
-            record = model_class.find_by_id(id.to_i)
+            record = find_addressed_record(model_class, req.params["id"])
             if record
               res.json({ data: record.to_h })
             else
@@ -200,8 +234,7 @@ module Tina4
         # PUT /api/{table}/{id} -- update record
         put_route = Tina4::Router.add("PUT", "#{prefix}/#{table}/{id}", proc { |req, res|
           begin
-            id = req.params["id"]
-            record = model_class.find_by_id(id.to_i)
+            record = find_addressed_record(model_class, req.params["id"])
             unless record
               next res.json({ error: "Not found" }, status: 404)
             end
@@ -236,8 +269,7 @@ module Tina4
         # DELETE /api/{table}/{id} -- delete record
         delete_route = Tina4::Router.add("DELETE", "#{prefix}/#{table}/{id}", proc { |req, res|
           begin
-            id = req.params["id"]
-            record = model_class.find_by_id(id.to_i)
+            record = find_addressed_record(model_class, req.params["id"])
             unless record
               next res.json({ error: "Not found" }, status: 404)
             end
@@ -314,27 +346,51 @@ module Tina4
         auto_increment = single_pk && defs[single_pk.to_sym] && defs[single_pk.to_sym][:auto_increment]
         strip_pk = is_create ? !(single_pk && !auto_increment) : true
 
+        # ADR-0069: a body key is written only when it resolves to a DECLARED
+        # field, by attribute name or its mapped column - the SAME resolver the
+        # list route's filter/sort use. Anything else is dropped (writes drop,
+        # reads 400).
         data.each_with_object({}) do |(key, value), allowed|
-          key_s = key.to_s
-          next unless defs.key?(key_s.to_sym)
-          next if key_s == "is_deleted"
-          next if strip_pk && pk_fields.include?(key_s)
+          attribute = model_class.resolve_field(key)
+          next unless attribute
 
-          allowed[key] = value
+          attribute_name = attribute.to_s
+          next if attribute_name == "is_deleted"
+          next if strip_pk && pk_fields.include?(attribute_name)
+
+          allowed[attribute_name] = value
         end
       end
 
-      # Parse sort parameter: "-name,created_at" => "name DESC, created_at ASC"
-      def parse_sort(sort_str)
-        return nil if sort_str.nil? || sort_str.empty?
-        sort_str.split(",").map do |field|
-          field = field.strip
-          if field.start_with?("-")
-            "#{field[1..-1]} DESC"
-          else
-            "#{field} ASC"
-          end
-        end.join(", ")
+      # The row a URL {id} addresses, or nil. The id is bound, never
+      # interpolated; ORM.coerce_primary_key keeps a string natural key as-is
+      # and answers nil for a non-integer id on an integer key (-> 404).
+      def find_addressed_record(model_class, raw_id)
+        id = model_class.coerce_primary_key(raw_id)
+        id.nil? ? nil : model_class.find_by_id(id)
+      end
+
+      # Parse the sort parameter: "-name,created_at" => "name DESC, created_at ASC".
+      #
+      # ADR-0069: each part (empty parts skipped, a leading "-" means DESC) must
+      # resolve to a declared field; the ORDER BY is built ONLY from resolved
+      # columns plus ASC/DESC. Returns [order_by_or_nil, unknown_field_or_nil].
+      def parse_sort(model_class, sort_str)
+        return [nil, nil] if sort_str.nil? || sort_str.empty?
+
+        parts = []
+        sort_str.split(",").each do |part|
+          part = part.strip
+          next if part.empty?
+
+          descending = part.start_with?("-")
+          field = descending ? part[1..].strip : part
+          column = model_class.resolve_field_column(field)
+          return [nil, field] unless column
+
+          parts << "#{column} #{descending ? 'DESC' : 'ASC'}"
+        end
+        [parts.empty? ? nil : parts.join(", "), nil]
       end
     end
   end

data/lib/tina4/background.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 module Tina4
   # Periodic background task registry.
@@ -9,7 +15,7 @@ module Tina4
   #
   # Ruby has no asyncio event loop, so each task runs in its own dedicated OS
   # thread, started at registration time. Because the thread runs regardless of
-  # which web server (Puma/WEBrick) is in front, a Ruby background task is never
+  # which web server (the built-in server or Puma) is in front, a Ruby background task is never
   # a silent no-op under production — the thread IS the runtime (contrast the
   # Python ASGI / PHP-FPM silent-no-op the other frameworks had to fix). The GIL
   # keeps it cooperative-enough for the periodic work this is meant for (queue

data/lib/tina4/base64.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
+
+module Tina4
+  # Base64 on core Array#pack / String#unpack1, so Tina4 needs no base64 gem.
+  #
+  # The base64 gem stopped being a default gem in Ruby 3.4, and a bundled gem an
+  # app does not declare is not on the load path under Bundler. The gem is itself
+  # a thin wrapper over pack("m"), so this module keeps its method names and its
+  # exact semantics (same bytes out, same ArgumentError on bad strict input) and
+  # the call sites read the same with a Tina4:: prefix.
+  module Base64
+    module_function
+
+    # RFC 2045 (MIME): a newline after every 60 encoded characters and at the end.
+    def encode64(binary)
+      [binary].pack("m")
+    end
+
+    # Lenient decode: characters outside the alphabet are skipped, never raised on.
+    def decode64(string)
+      string.unpack1("m")
+    end
+
+    # RFC 4648: no line feeds.
+    def strict_encode64(binary)
+      [binary].pack("m0")
+    end
+
+    # Raises ArgumentError on anything that is not canonical, padded base64.
+    def strict_decode64(string)
+      string.unpack1("m0")
+    end
+
+    # RFC 4648 URL-safe alphabet ("-" and "_"), padding optional.
+    def urlsafe_encode64(binary, padding: true)
+      encoded = strict_encode64(binary)
+      encoded.chomp!("==") or encoded.chomp!("=") unless padding
+      encoded.tr!("+/", "-_")
+      encoded
+    end
+
+    # Accepts padded or unpadded input; raises ArgumentError on invalid input.
+    def urlsafe_decode64(string)
+      if !string.end_with?("=") && string.length % 4 != 0
+        string = string.ljust((string.length + 3) & ~3, "=")
+        string.tr!("-_", "+/")
+      else
+        string = string.tr("-_", "+/")
+      end
+      strict_decode64(string)
+    end
+  end
+end

data/lib/tina4/cache.rb

@@ -1,3 +1,9 @@
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 module Tina4
   # In-memory TTL cache with tag-based invalidation.
   #

data/lib/tina4/cache_backends/base_backend.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 module Tina4
   module CacheBackends

data/lib/tina4/cache_backends/database_backend.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require "json"
 require_relative "base_backend"

data/lib/tina4/cache_backends/file_backend.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require "json"
 require "fileutils"

data/lib/tina4/cache_backends/memcached_backend.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require "json"
 require "socket"

data/lib/tina4/cache_backends/memory_backend.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require_relative "base_backend"
 

data/lib/tina4/cache_backends/mongo_backend.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require "json"
 require "uri"

data/lib/tina4/cache_backends/redis_backend.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require "json"
 require "socket"

data/lib/tina4/cache_backends/valkey_backend.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require_relative "redis_backend"
 

data/lib/tina4/cache_backends.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require_relative "cache_backends/base_backend"
 require_relative "cache_backends/memory_backend"

data/lib/tina4/cli.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 require "optparse"
 require "fileutils"
@@ -8,6 +14,7 @@ require "tmpdir"    # Dir.mktmpdir — used by the ADR-0063 sandbox edit-hint sc
 require "stringio"  # StringIO — captures generator stdout during the sandbox run
 require "open3"     # Open3.capture2e — captures `ruby -c` output+status for `lint`
 require_relative "port_takeover"
+require_relative "env"       # Tina4::Env.is_truthy -- resolve_config runs before lib/tina4 loads
 
 module Tina4
   class CLI
@@ -676,7 +683,7 @@ module Tina4
         # invokes PHP. That mismatch is why Ruby could not be launched through
         # the shared launcher the other frameworks use.
         opts.on("--managed", "Running under the tina4 CLI supervisor") { options[:managed] = true }
-        opts.on("--production", "Use production server (Puma)") { options[:production] = true }
+        opts.on("--production", "Production mode: Puma if the app bundles it, else the built-in server") { options[:production] = true }
         opts.on("--no-browser", "Do not open browser on start") { options[:no_browser] = true }
         opts.on("--no-reload", "Disable file watcher / live-reload") { options[:no_reload] = true }
         opts.on("--no-kill", "Never take over the port from a stale dev server") { options[:no_kill] = true }
@@ -727,9 +734,9 @@ module Tina4
 
       is_debug = Tina4::Env.is_truthy(ENV["TINA4_DEBUG"])
 
-      # Use Puma only when explicitly requested via --production flag
-      # WEBrick is used for development (supports dev toolbar/reload)
-      # Same production server, same shutdown contract as Tina4.run! - one
+      # Puma only with --production AND only when the app bundles it
+      # (ADR-0067); otherwise Tina4's built-in server, in development and
+      # production alike. Same production server, same shutdown contract as Tina4.run! - one
       # implementation, so the two entry points cannot drift again (the old
       # copy here claimed "we handle DB cleanup" and did no cleanup at all).
       # TINA4_DEFAULT_WEBSERVER=TRUE pins the built-in server even with
@@ -739,7 +746,6 @@ module Tina4
         return
       end
 
-      Tina4::Log.info("Development server: WEBrick")
       server = Tina4::WebServer.new(app, host: options[:host], port: options[:port])
       server.start
     end
@@ -3806,7 +3812,7 @@ module Tina4
         # loopback, not 0.0.0.0. Only the DEFAULT changes: production
         # (TINA4_DEBUG off) keeps 0.0.0.0, and a developer who WANTS network
         # exposure sets TINA4_HOST=0.0.0.0 to override deliberately.
-        Tina4.truthy?(ENV["TINA4_DEBUG"]) ? "127.0.0.1" : DEFAULT_HOST
+        Tina4::Env.is_truthy(ENV["TINA4_DEBUG"]) ? "127.0.0.1" : DEFAULT_HOST
       end
     end
 
@@ -3875,9 +3881,18 @@ module Tina4
 
       # Gemfile
       unless File.exist?(File.join(dir, "Gemfile"))
+        # Same Gemfile `tina4 init ruby` writes. The gem is published as
+        # "tina4ruby" ("tina4-ruby" does not exist, so bundle install failed),
+        # and sqlite3 is an app dependency (ADR-0067): tina4ruby loads it lazily
+        # for the default SQLite database but never declares it.
         File.write(File.join(dir, "Gemfile"), <<~RUBY)
           source "https://rubygems.org"
-          gem "tina4-ruby", "~> 3.0"
+
+          gem "tina4ruby", "~> 3.0"
+
+          # SQLite driver for the default database (TINA4_DATABASE_URL=sqlite:...).
+          # tina4ruby loads it lazily; it is an app dependency, like pg or mysql2.
+          gem "sqlite3"
         RUBY
       end
 

data/lib/tina4/constants.rb

@@ -1,3 +1,9 @@
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 # Tina4 Constants — HTTP status codes and content types.
 #
 # Standard constants for use in route handlers across all Tina4 frameworks.
@@ -59,25 +65,23 @@ module Tina4
     304 => "Not Modified", 307 => "Temporary Redirect", 308 => "Permanent Redirect",
     400 => "Bad Request", 401 => "Unauthorized", 403 => "Forbidden",
     404 => "Not Found", 405 => "Method Not Allowed", 406 => "Not Acceptable",
+    408 => "Request Timeout",
     409 => "Conflict", 410 => "Gone", 413 => "Content Too Large",
     415 => "Unsupported Media Type", 422 => "Unprocessable Content",
-    429 => "Too Many Requests",
+    429 => "Too Many Requests", 431 => "Request Header Fields Too Large",
     500 => "Internal Server Error", 501 => "Not Implemented",
-    502 => "Bad Gateway", 503 => "Service Unavailable", 504 => "Gateway Timeout"
+    502 => "Bad Gateway", 503 => "Service Unavailable", 504 => "Gateway Timeout",
+    505 => "HTTP Version Not Supported"
   }.freeze
 
   # Return the canonical HTTP reason phrase for ``status``.
   #
   # Falls back to a sensible label when an exotic status is used. Never
   # returns an empty string — the HTTP/1.1 status line requires a phrase.
-  # Prefers Rack::Utils::HTTP_STATUS_CODES when Rack is available so the
-  # phrase tracks Rack's mapping, otherwise uses the local table above.
+  # The table is Tina4's own (the phrases match Python's and PHP's); it no
+  # longer defers to Rack::Utils, which is not a dependency.
   def self.http_reason(status)
     code = status.to_i
-    if defined?(Rack::Utils::HTTP_STATUS_CODES)
-      phrase = Rack::Utils::HTTP_STATUS_CODES[code]
-      return phrase if phrase && !phrase.empty?
-    end
     phrase = HTTP_REASON_PHRASES[code]
     return phrase if phrase && !phrase.empty?
     return "OK" if code >= 200 && code < 300

data/lib/tina4/container.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 module Tina4
   # Lightweight dependency injection container.

data/lib/tina4/context/chunker.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 # Tina4 Ruby
 #

data/lib/tina4/context.rb

@@ -1,4 +1,10 @@
 # frozen_string_literal: true
+# Copyright (c) 2026 Code Infinity
+# SPDX-License-Identifier: MPL-2.0
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at https://mozilla.org/MPL/2.0/.
+
 
 # Tina4 Ruby
 #
@@ -6,9 +12,10 @@
 #
 # Lets a Tina4 app ground its own AI assistant on its own source, offline: it
 # walks the project, chunks code on def/class/module boundaries and docs as
-# prose, and answers keyword/fuzzy queries over a SQLite FTS5 index. The
-# sqlite3 gem is already a Tina4-Ruby runtime dependency and modern SQLite ships
-# FTS5 + bm25() built in, so this adds NO new dependency.
+# prose, and answers keyword/fuzzy queries over a SQLite FTS5 index. It uses the
+# sqlite3 gem the APP declares (the `tina4 init ruby` Gemfile carries it; tina4ruby
+# itself does not, ADR-0067) and modern SQLite ships FTS5 + bm25() built in, so
+# this adds NO dependency. Without the gem the index reports itself unavailable.
 #
 # The retrieval core is a thin port of tina4-python's tina4_python/context
 # (itself the proven slice of neemee: SqliteFTS + the stable
@@ -29,6 +36,7 @@ require "pathname"
 require "fileutils"
 require "set"
 require_relative "context/chunker"
+require_relative "sqlite3_gem"
 
 module Tina4
   class Context
@@ -70,7 +78,7 @@ module Tina4
       @available = !!check.call
       return unless @available
 
-      require "sqlite3"
+      Tina4.require_sqlite3!
       parent = File.dirname(@path)
       FileUtils.mkdir_p(parent) unless parent.empty? || parent == "." || File.directory?(parent)
       # One connection guarded by a Mutex — the dev-MCP reload hook may run on a
@@ -82,7 +90,7 @@ module Tina4
     # ── FTS5 availability ───────────────────────────────────────
     # Whether this Ruby's sqlite3 build supports FTS5 (a real in-memory probe).
     def self.fts5_available?
-      require "sqlite3"
+      Tina4.require_sqlite3!
       db = SQLite3::Database.new(":memory:")
       begin
         db.execute("CREATE VIRTUAL TABLE _probe USING fts5(x)")