tina4ruby 3.13.103 → 3.13.105

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6097dca4375329be7c8539cf9e40a8cde39fd9a6041169e58b9edf6bcbcf491a
-  data.tar.gz: 9d90b71f00d6a59a151a5a3108319aed79faccaac0858f40c3572825765f0acf
+  metadata.gz: 4ab6d7ce15da93e814204665a8690be0cc2ac58dc1152fa75f050b91fcb0c4f0
+  data.tar.gz: 35fc27eb9d71c17a0049d983d34ed6c1584e014338192e5ace087e5e2bec0746
 SHA512:
-  metadata.gz: 74d5064e7aca1cffcdfd0389b6662a4f2d921ed18de43f8d9f0741bffa6a8ceb7d381af281b44b9e114237d7c783068c1adef1b709eb8c36efa017aa6eeb633e
-  data.tar.gz: 13fd4fa1ea1e667eee942d516cd48c14a2488e686ace7d9597d3affe368d2e7ad8e86772367b8d5ed5b3cc94b9a5631a41d62694abf055999ccbab30c9efad99
+  metadata.gz: f2e66595ddcf7eca7d498428149ca38a83caf4871d8d5e29e31ef9d72f7f38f2ed9c3afe638ba2891bf9ffda5b00dbbf54883ddc704bf06787f9f06060b0603b
+  data.tar.gz: c45ab7892609d2be7e0b3dc432a8d54bef9dd8281e3594198b9fa93e9170ceeb60372624c69d49978884ef596cb7ff35eeb720216c4d240a176e372ffa33d803

data/CHANGELOG.md

@@ -6,6 +6,26 @@ number means the same thing everywhere.
 **The authoritative release notes for every shipped version live in the documentation:**
 https://tina4.com/ruby/36-releases
 
+## 3.13.105
+
+Bug release. Route inspection stops touching the app; Firebird's migration
+ledger tolerates whatever case the driver hands back; PHP loses a colon-in-
+filename that broke Windows checkouts.
+
+### Route inspection scans, never boots
+
+- `tina4 routes` now walks canonical route files and never executes the
+  application entrypoint or starts the server. Feature 115 / ADR-0058.
+- Fixes the case where `tina4 routes --override` would boot the app on the
+  same port and kill whatever process was already holding it (tina4-python
+  issue #104).
+
+### Firebird migration ledger is case-agnostic
+
+- `tina4_migration` reads and writes work regardless of the case the
+  Firebird driver returns for the `migration_name` column.
+- Uses the atomic sequence table pattern already in place for other engines.
+
 ## 3.13.103
 
 ### Metrics reports what it can prove

data/lib/tina4/cli.rb

@@ -1013,8 +1013,8 @@ module Tina4
 
     def cmd_routes(_argv = nil)
       require_relative "../tina4"
-      Tina4.initialize!(Dir.pwd)
-      load_routes(Dir.pwd)
+      Tina4::Env.load_env(Dir.pwd)
+      load_routes(Dir.pwd, entrypoints: false)
 
       puts "\nRegistered Routes:"
       puts "-" * 60
@@ -2959,7 +2959,7 @@ module Tina4
 
     # ── shared helpers ────────────────────────────────────────────────────
 
-    def load_routes(root_dir)
+    def load_routes(root_dir, entrypoints: true)
       route_dirs = %w[src/routes routes src/api api src/orm orm]
       route_dirs.each do |dir|
         route_dir = File.join(root_dir, dir)
@@ -2967,7 +2967,10 @@ module Tina4
         Dir.glob(File.join(route_dir, "**/*.rb")).sort.each { |f| load f }
       end
 
-      # Also load app.rb if it exists
+      return unless entrypoints
+
+      # Runtime and console boot load the application entrypoint. Inspection
+      # commands opt out so they can never start a server or take over a port.
       app_file = File.join(root_dir, "app.rb")
       load app_file if File.exist?(app_file)
 

data/lib/tina4/field_types.rb

@@ -108,6 +108,11 @@ module Tina4
         register_field(name, :json, nullable: nullable, default: default)
       end
 
+      def point_field(name, srid: Tina4::Point::DEFAULT_SRID, spatial_index: true, nullable: true, default: nil)
+        register_field(name, :point, srid: Integer(srid), spatial_index: spatial_index,
+                       nullable: nullable, default: default)
+      end
+
       # Declare a foreign key integer column and auto-wire relationships.
       #
       # Automatically:
@@ -230,6 +235,13 @@ module Tina4
         # __setattr__ + object.__setattr__ default-seeding.
         attr_reader name
         define_method("#{name}=") do |value|
+          if type == :point && !value.nil?
+            point = Tina4::Point.parse(value, srid: options[:srid])
+            if point.srid != options[:srid]
+              raise ArgumentError, "Point field '#{name}' expects SRID #{options[:srid]}; received #{point.srid}"
+            end
+            value = point
+          end
           fields = (@assigned_fields ||= [])
           fields << name unless fields.include?(name)
           instance_variable_set("@#{name}", value)

data/lib/tina4/orm.rb

@@ -245,7 +245,7 @@ module Tina4
       #
       # @return [Tina4::QueryBuilder]
       def query
-        QueryBuilder.from_table(table_name, db: db)
+        QueryBuilder.from_table(table_name, db: db, primary_key: get_db_column(primary_key_field || :id))
       end
 
       def find(id_or_filter = nil, filter = nil, **kwargs)
@@ -480,13 +480,25 @@ module Tina4
 
       # Invalidate every cached query that touches this model's table.
       #
-      # Tag-scoped, NOT a wholesale flush: a cached JOIN on another model that
-      # reads this table is busted too (it carries this table's tag), while a
-      # query that never touches this table is left intact. Called after every
-      # ORM write (save/delete/force_delete/restore) so a read-after-write never
-      # serves a stale/deleted row (CACHE-DEC-01).
+      # Tag-scoped in the ORM layer (a cached JOIN on another model that reads
+      # this table is busted too because it carries this table's tag; a query
+      # that never touches this table is left intact), then cascaded to the
+      # DB layer on this model's bound connection so an out-of-band write /
+      # deliberate refresh / race-with-another-process cannot leave stale rows
+      # in db.fetch's persistent cache. Called after every ORM write
+      # (save/delete/force_delete/restore) so a read-after-write never serves
+      # a stale/deleted row (CACHE-DEC-01). 3.13.105 (parity port of PY-06-22)
+      # added the DB-layer cascade — previously the two cache layers disagreed
+      # under TINA4_AUTO_CACHING=true + TINA4_DB_CACHE=true.
       def clear_cache
         query_cache.clear_tag(table_name.to_s.downcase)
+        begin
+          get_db.cache_clear
+        rescue StandardError
+          # A resolvable DB is not guaranteed at every clear_cache call site
+          # (module-import time in odd bootstraps, tests that mutate bindings);
+          # never let a cache-clear crash a save/delete.
+        end
         nil
       end
 
@@ -529,7 +541,7 @@ module Tina4
       end
 
       def create_table
-        return true if db.table_exists?(table_name)
+        return create_spatial_indexes if db.table_exists?(table_name)
 
         # v3.13.16: engine-aware DDL. Ruby used to emit SQLite-only DDL on
         # every driver — INTEGER for booleans, DATETIME for datetimes, and a
@@ -594,12 +606,17 @@ module Tina4
           datetime: datetime_sql,
           timestamp: "TIMESTAMP",
           blob: "BLOB",
-          json: json_sql
+          json: json_sql,
+          point: nil
         }
 
         col_defs = []
         field_definitions.each do |name, opts|
-          sql_type = type_map[opts[:type]] || "TEXT"
+          sql_type = if opts[:type] == :point
+                       SQLTranslator.point_column_type(engine, opts[:srid] || Point::DEFAULT_SRID)
+                     else
+                       type_map[opts[:type]] || "TEXT"
+                     end
           if opts[:type] == :string && opts[:length]
             sql_type = "VARCHAR(#{opts[:length]})"
           elsif opts[:type] == :decimal
@@ -687,13 +704,35 @@ module Tina4
             # ONE case is benign - re-raise anything else.
             raise ce unless ce.message.to_s =~ /no corresponding begin/i
           end
-          true
+          create_spatial_indexes
+        rescue SpatialNotSupportedError
+          raise
         rescue => e
           Tina4::Log.error("create_table failed for #{table_name}: #{db.get_error || e.message}", { sql: sql })
           false
         end
       end
 
+      def create_spatial_indexes
+        fields = field_definitions.select { |_name, opts| opts[:type] == :point }
+        return true if fields.empty?
+        engine = db.get_database_type.to_s.downcase
+        begin
+          fields.each do |name, opts|
+            SQLTranslator.point_column_type(engine, opts[:srid] || Point::DEFAULT_SRID)
+            next unless opts.fetch(:spatial_index, true)
+            db.execute(SQLTranslator.spatial_index(engine, table_name, get_db_column(name)))
+          end
+          db.commit
+          true
+        rescue SpatialNotSupportedError
+          raise
+        rescue => e
+          Tina4::Log.error("spatial index creation failed for #{table_name}: #{e.message}")
+          false
+        end
+      end
+
       def scope(name, filter_sql, params = [])
         define_singleton_method(name) do |limit: 100, offset: 0|
           where(filter_sql, params, limit: limit, offset: offset)
@@ -721,6 +760,9 @@ module Tina4
               # leave the raw string in place
             end
           end
+          if fdef && fdef[:type] == :point && !value.nil?
+            value = Point.parse(value, srid: fdef[:srid] || Point::DEFAULT_SRID)
+          end
           setter = "#{attr_name}="
           instance.__send__(setter, value) if instance.respond_to?(setter)
         end
@@ -857,6 +899,12 @@ module Tina4
           # a.meta must not leak into b.meta). Parity with the Python master,
           # which deepcopies a JSONField's dict/list default per instance.
           d = Marshal.load(Marshal.dump(d)) if d.is_a?(Hash) || d.is_a?(Array)
+          if opts[:type] == :point && !d.nil?
+            d = Point.parse(d, srid: opts[:srid] || Point::DEFAULT_SRID)
+            if d.srid != (opts[:srid] || Point::DEFAULT_SRID)
+              raise ArgumentError, "Point field '#{name}' expects SRID #{opts[:srid] || Point::DEFAULT_SRID}; received #{d.srid}"
+            end
+          end
           # #165: seed the default straight into the ivar, BYPASSING the
           # tracking setter, so a default is not recorded as a caller
           # assignment (mirrors the Python master's object.__setattr__).
@@ -1283,7 +1331,8 @@ module Tina4
       key_case = binding.local_variable_get(:case)  # :case is a reserved word
       hash = {}
       self.class.field_definitions.each_key do |name|
-        hash[name] = __send__(name)
+        value = __send__(name)
+        hash[name] = value.is_a?(Point) ? value.geojson : value
       end
 
       if include
@@ -1321,6 +1370,19 @@ module Tina4
       hash
     end
 
+    def to_feature(geometry_field: nil, include: nil)
+      point_fields = self.class.field_definitions.select { |_name, opts| opts[:type] == :point }.keys
+      geometry_field = (geometry_field || point_fields.first)&.to_sym
+      raise ArgumentError, "to_feature needs a declared point_field" unless geometry_field && point_fields.include?(geometry_field)
+      properties = to_h(include: include)
+      geometry = properties.delete(geometry_field)
+      { type: "Feature", geometry: geometry, properties: properties }
+    end
+
+    def self.feature_collection(models, geometry_field: nil, include: nil)
+      { type: "FeatureCollection", features: models.map { |model| model.to_feature(geometry_field: geometry_field, include: include) } }
+    end
+
     alias to_hash to_h
     alias to_dict to_h
     alias to_object to_h
@@ -1377,6 +1439,7 @@ module Tina4
         if opts[:type] == :json && !value.nil? && !value.is_a?(String)
           value = JSON.generate(value)
         end
+        value = value.ewkt if opts[:type] == :point && value.is_a?(Point)
         db_col = mapping[name.to_s] || name
         hash[db_col.to_sym] = value
       end
@@ -1400,6 +1463,7 @@ module Tina4
         if opts[:type] == :json && !value.nil? && !value.is_a?(String)
           value = JSON.generate(value)
         end
+        value = value.ewkt if opts[:type] == :point && value.is_a?(Point)
         db_col = mapping[name.to_s] || name
         hash[db_col.to_sym] = value
       end

data/lib/tina4/point.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Tina4
+  class SpatialNotSupportedError < StandardError; end
+
+  # Immutable SRID-aware longitude/latitude point (ADR-0057).
+  class Point
+    DEFAULT_SRID = 4326
+    EWKB_SRID = 0x20000000
+    EWKB_M = 0x40000000
+    EWKB_Z = 0x80000000
+
+    attr_reader :lon, :lat, :srid
+
+    def initialize(lon, lat, srid: DEFAULT_SRID)
+      raise ArgumentError, "Point longitude and latitude must be numbers" if lon == true || lon == false || lat == true || lat == false
+      @lon = Float(lon)
+      @lat = Float(lat)
+      @srid = Integer(srid)
+      raise ArgumentError, "Point longitude and latitude must be finite" unless @lon.finite? && @lat.finite?
+      if @srid == DEFAULT_SRID
+        raise ArgumentError, "Point longitude #{@lon} is outside -180..180; Tina4 uses longitude, latitude order" unless (-180.0..180.0).cover?(@lon)
+        raise ArgumentError, "Point latitude #{@lat} is outside -90..90; Tina4 uses longitude, latitude order" unless (-90.0..90.0).cover?(@lat)
+      end
+      freeze
+    rescue TypeError, ArgumentError => e
+      raise e if e.message.start_with?("Point ")
+      raise ArgumentError, "Point longitude, latitude and SRID must be numeric"
+    end
+
+    def wkt = "POINT(#{format_coordinate(@lon)} #{format_coordinate(@lat)})"
+    def ewkt = "SRID=#{@srid};#{wkt}"
+    def geojson = { type: "Point", coordinates: [@lon, @lat] }
+    def to_h = geojson
+    def to_a = [@lon, @lat]
+    def to_json(*args) = geojson.to_json(*args)
+
+    def self.parse(value, srid: DEFAULT_SRID)
+      return value if value.is_a?(Point)
+      if value.is_a?(Array)
+        raise ArgumentError, "Point coordinate pair needs longitude and latitude" if value.length < 2
+        return new(value[0], value[1], srid: srid)
+      end
+      return from_geojson(value, srid) if value.is_a?(Hash)
+      if value.is_a?(String)
+        text = value.strip
+        match = text.match(/\A(?:SRID\s*=\s*(\d+)\s*;\s*)?POINT\s*(?:Z|M|ZM)?\s*\(\s*([-+0-9.eE]+)\s+([-+0-9.eE]+)(?:\s+[-+0-9.eE]+)*\s*\)\z/i)
+        return new(match[2], match[3], srid: match[1] ? match[1].to_i : srid) if match
+        raw = [text].pack("H*") if text.length >= 42 && text.length.even? && text.match?(/\A[0-9a-f]+\z/i)
+        raw ||= value.b if [0, 1].include?(value.getbyte(0))
+        return from_wkb(raw, srid) if raw
+      end
+      raise ArgumentError, "Point must be Point, [longitude, latitude], WKT/EWKT, GeoJSON or WKB/EWKB"
+    end
+
+    def self.geometry_binding(value, srid: DEFAULT_SRID)
+      return [parse(value, srid: srid).ewkt, :ewkt] if value.is_a?(Point) || value.is_a?(Array)
+      if value.is_a?(Hash)
+        geometry = value.fetch(:type, value["type"]).to_s.downcase == "feature" ? (value[:geometry] || value["geometry"]) : value
+        type = (geometry[:type] || geometry["type"]).to_s.downcase
+        allowed = %w[point linestring polygon multipoint multilinestring multipolygon geometrycollection]
+        raise ArgumentError, "GeoJSON geometry has an unsupported type" unless allowed.include?(type)
+        return [JSON.generate(geometry), :geojson]
+      end
+      if value.is_a?(String) && value.match?(/\A\s*(?:SRID\s*=\s*\d+\s*;\s*)?(?:POINT|LINESTRING|POLYGON|MULTIPOINT|MULTILINESTRING|MULTIPOLYGON|GEOMETRYCOLLECTION)\b/i)
+        return [value.match?(/\A\s*SRID/i) ? value.strip : "SRID=#{srid};#{value.strip}", :ewkt]
+      end
+      raise ArgumentError, "Geometry must be Point, coordinate pair, WKT/EWKT or GeoJSON"
+    end
+
+    def self.from_geojson(data, srid)
+      type = (data[:type] || data["type"]).to_s.downcase
+      geometry = type == "feature" ? (data[:geometry] || data["geometry"] || {}) : data
+      raise ArgumentError, "Point GeoJSON type must be Point" unless (geometry[:type] || geometry["type"]).to_s.downcase == "point"
+      coordinates = geometry[:coordinates] || geometry["coordinates"]
+      raise ArgumentError, "Point GeoJSON coordinates must be [longitude, latitude]" unless coordinates.is_a?(Array) && coordinates.length >= 2
+      new(coordinates[0], coordinates[1], srid: srid)
+    end
+    private_class_method :from_geojson
+
+    def self.from_wkb(raw, srid)
+      raise ArgumentError, "Point WKB is too short" if raw.bytesize < 21
+      little = raw.getbyte(0) == 1
+      type_word = raw.byteslice(1, 4).unpack1(little ? "V" : "N")
+      offset = 5
+      if (type_word & EWKB_SRID) != 0
+        srid = raw.byteslice(5, 4).unpack1(little ? "V" : "N")
+        offset = 9
+      end
+      code = (type_word & ~(EWKB_SRID | EWKB_Z | EWKB_M)) % 1000
+      raise ArgumentError, "WKB geometry is not a Point" unless code == 1 && raw.bytesize >= offset + 16
+      lon, lat = raw.byteslice(offset, 16).unpack(little ? "E2" : "G2")
+      new(lon, lat, srid: srid)
+    end
+    private_class_method :from_wkb
+
+    private
+
+    def format_coordinate(value)
+      text = format("%.15g", value)
+      text == "-0" ? "0" : text
+    end
+  end
+end

data/lib/tina4/query_builder.rb

@@ -19,10 +19,11 @@ module Tina4
   #     .get
   #
   class QueryBuilder
-    def initialize(table, db: nil)
+    def initialize(table, db: nil, primary_key: nil)
       @table = table
       @db = db
       @columns = ["*"]
+      @select_params = []
       @wheres = []
       @params = []
       @joins = []
@@ -30,6 +31,8 @@ module Tina4
       @havings = []
       @having_params = []
       @order_by_cols = []
+      @order_by_params = []
+      @primary_key = primary_key&.to_s
       @limit_val = nil
       @offset_val = nil
     end
@@ -39,8 +42,8 @@ module Tina4
     # @param table_name [String] The database table name.
     # @param db [Object, nil] Optional database connection.
     # @return [QueryBuilder]
-    def self.from_table(table_name, db: nil)
-      new(table_name, db: db)
+    def self.from_table(table_name, db: nil, primary_key: nil)
+      new(table_name, db: db, primary_key: primary_key)
     end
 
     # Set the columns to select.
@@ -48,7 +51,10 @@ module Tina4
     # @param columns [Array<String>] Column names.
     # @return [self]
     def select(*columns)
-      @columns = columns unless columns.empty?
+      unless columns.empty?
+        @columns = columns
+        @select_params = []
+      end
       self
     end
 
@@ -123,6 +129,46 @@ module Tina4
       self
     end
 
+    def within_distance(column, point, radius_metres, srid: Point::DEFAULT_SRID)
+      radius = Float(radius_metres)
+      raise ArgumentError, "Spatial radius must be finite and greater than or equal to zero" unless radius.finite? && radius >= 0
+      point = Point.parse(point, srid: srid)
+      where(SQLTranslator.within_distance(engine, column, point.srid), [point.lon, point.lat, radius])
+    end
+
+    def intersects(column, geometry, srid: Point::DEFAULT_SRID)
+      bound, form = Point.geometry_binding(geometry, srid: srid)
+      where(SQLTranslator.intersects(engine, column, form, srid), [bound])
+    end
+
+    def bbox(column, min_lon, min_lat, max_lon, max_lat, srid: Point::DEFAULT_SRID)
+      values = [min_lon, min_lat, max_lon, max_lat].map { |value| Float(value) }
+      raise ArgumentError, "Bounding-box coordinates must be finite" unless values.all?(&:finite?)
+      west, south, east, north = values
+      Point.new(west, south, srid: srid)
+      Point.new(east, north, srid: srid)
+      raise ArgumentError, "Bounding box must be ordered west, south, east, north" if west > east || south > north
+      where(SQLTranslator.bbox(engine, column, srid), values)
+    end
+
+    def select_distance(column, point, alias_name: "distance", srid: Point::DEFAULT_SRID)
+      point = Point.parse(point, srid: srid)
+      @columns << SQLTranslator.distance_as(engine, column, alias_name, point.srid)
+      @select_params.concat([point.lon, point.lat])
+      self
+    end
+
+    def order_by_distance(column, point, direction: "ASC", srid: Point::DEFAULT_SRID)
+      direction = direction.to_s.upcase
+      raise ArgumentError, "Distance order direction must be ASC or DESC" unless %w[ASC DESC].include?(direction)
+      raise ArgumentError, "Stable spatial ordering needs a primary key; use ORM.query or pass primary_key:" if @primary_key.to_s.empty?
+      point = Point.parse(point, srid: srid)
+      @order_by_cols << "#{SQLTranslator.distance(engine, column, point.srid)} #{direction}"
+      @order_by_params.concat([point.lon, point.lat])
+      @order_by_cols << "#{SQLTranslator.spatial_identifier(@primary_key, 'primary key')} ASC"
+      self
+    end
+
     # Set LIMIT and optional OFFSET.
     #
     # @param count [Integer] Maximum rows to return.
@@ -167,7 +213,7 @@ module Tina4
     def get
       ensure_db!
       sql = to_sql
-      all_params = @params + @having_params
+      all_params = @select_params + @params + @having_params + @order_by_params
 
       @db.fetch(
         sql,
@@ -183,7 +229,7 @@ module Tina4
     def first
       ensure_db!
       sql = to_sql
-      all_params = @params + @having_params
+      all_params = @select_params + @params + @having_params + @order_by_params
 
       @db.fetch_one(sql, all_params.empty? ? [] : all_params)
     end
@@ -196,9 +242,18 @@ module Tina4
 
       # Build a count query by replacing columns
       original = @columns
+      original_select_params = @select_params
+      original_order = @order_by_cols
+      original_order_params = @order_by_params
       @columns = ["COUNT(*) as cnt"]
+      @select_params = []
+      @order_by_cols = []
+      @order_by_params = []
       sql = to_sql
       @columns = original
+      @select_params = original_select_params
+      @order_by_cols = original_order
+      @order_by_params = original_order_params
 
       all_params = @params + @having_params
 
@@ -272,6 +327,11 @@ module Tina4
 
     private
 
+    def engine
+      ensure_db!
+      @db.get_database_type
+    end
+
     # Parse a single SQL condition into a MongoDB filter hash.
     #
     # @return [Array(Hash, Integer)] [mongo_condition, updated_param_index]

data/lib/tina4/queue.rb

@@ -171,7 +171,14 @@ module Tina4
       @backend.close
     end
 
-    # Get jobs that failed but are still eligible for retry (under max_retries).
+    # Get jobs that failed at least once but are still being retried
+    # (0 < attempts < max_retries). These live in the pending queue under
+    # the auto-retry lifecycle (fail() re-queues them with an incremented
+    # attempts count and a retry_backoff delay) so pop() picks them up
+    # again. They are NOT counted by size("failed") — that alias counts
+    # the dead-letter store, matching dead_letters(). To include retryable-
+    # failed jobs in a total, use size("pending"). Terminal failures are
+    # returned by dead_letters().
     def failed # -> list[dict]
       refuse_operation!("failed()") unless @backend.respond_to?(:failed)
       @backend.failed(@topic, max_retries: @max_retries)
@@ -179,13 +186,24 @@ module Tina4
 
     # Retry a specific failed job by ID, or all dead-letter jobs if no id given.
     # Returns true if re-queued.
+    #
+    # The no-arg branch is materialised by the backend (LiteBackend#retry_job
+    # iterates every dead-letter file with .each, MongoBackend materialises
+    # find(...).to_a before iterating) — no generator inside any() /
+    # short-circuit reduce can silently leave dead letters behind (parity port
+    # of PY-12-04, 3.13.105).
     def retry(job_id = nil, delay_seconds: 0) # -> bool
       refuse_operation!("retry()") unless @backend.respond_to?(:retry_job)
       @backend.retry_job(@topic, job_id: job_id, delay_seconds: delay_seconds)
     end
 
-    # Get dead letter jobs — messages that exceeded max retries.
-    # Pass max_retries to override the queue's default.
+    # Get jobs that exceeded max_retries — terminal failures.
+    #
+    # Same set counted by size("failed") / size("dead") / size("dead_letter")
+    # (three aliases for the dead-letter store). To LIST retryable-but-
+    # attempted jobs (attempts > 0 AND attempts < max_retries) that are still
+    # being auto-retried, use failed() — those live in the pending queue and
+    # are NOT dead letters. Pass max_retries to override the queue's default.
     def dead_letters(max_retries: nil) # -> list[dict]
       refuse_operation!("dead_letters()") unless @backend.respond_to?(:dead_letters)
       @backend.dead_letters(@topic, max_retries: max_retries || @max_retries)
@@ -328,9 +346,21 @@ module Tina4
       attach(@backend.find_by_id(topic || @topic, id))
     end
 
-    # Get the number of messages by status.
-    # status: "pending" (default) counts pending messages in the topic queue.
-    # status: "failed" or "dead" counts messages in the dead_letter directory.
+    # Count jobs by status.
+    #
+    # "pending" counts jobs waiting to be popped — INCLUDES retryable-but-
+    # attempted ones, because they live in the pending queue under the
+    # auto-retry lifecycle (see failed()).
+    # "reserved" counts jobs a consumer has popped but not yet
+    # completed/failed (in-flight against the visibility timeout).
+    # "completed" counts jobs the consumer has finished successfully
+    # (0 on the lite/file backend which deletes on complete; backends that
+    # track completion expose completed_count).
+    # "failed", "dead", "dead_letter" are ALIASES that all count the
+    # dead-letter store — jobs whose attempts >= max_retries and that have
+    # given up. Use dead_letters() to list them. Retryable-but-attempted
+    # jobs are NOT counted by size("failed"); use failed() to list them or
+    # size("pending") to include them in a total.
     def size(status: "pending")
       case status.to_s
       when "pending"

data/lib/tina4/queue_backends/lite_backend.rb

@@ -164,9 +164,26 @@ module Tina4
 
       # Explicit re-queue requested by the caller (job.retry()). Always
       # re-enqueues regardless of the retry limit — a manual override, distinct
-      # from the automatic fail() path. Increments attempts, clears the error.
+      # from the automatic fail() path. Cleans up BOTH the reservation record
+      # and any dead-letter file for this id, so a caller who iterates
+      # dead_letters and calls job.retry on each doesn't leave the dead-letter
+      # directory carrying duplicates (3.13.105, parity port of PY-12-05).
+      # Aligns with retry_job(id) which had always unlinked the dead-letter
+      # file — two spellings of the same intent that previously diverged.
+      # Increments attempts, clears the error.
       def retry(job, delay_seconds: 0)
         clear_reservation(job.topic, job.id)
+        # Drop any dead-letter file for this id BEFORE the re-queue: if this
+        # job came from dead_letters it lives in @dead_letter_dir and would
+        # otherwise stay on disk while a fresh pending file appears in
+        # topic_path, so the next dead_letters call reports the job again
+        # and a consumer processes it twice.
+        begin
+          File.unlink(job_file(@dead_letter_dir, job.id))
+        rescue Errno::ENOENT
+          # No dead-letter file for this id (manual .retry on a live job) —
+          # nothing to clean up.
+        end
         job.attempts += 1
         requeue_job(job, delay_seconds: delay_seconds, error: nil)
       end

data/lib/tina4/queue_backends/mongo_backend.rb

@@ -291,8 +291,19 @@ module Tina4
                   .map { |doc| job_from_doc(doc) }
       end
 
+      # Delete every doc in this queue whose status matches.
+      #
+      # 3.13.105 (parity port): route the dead-letter statuses ("dead",
+      # "failed", "dead_letter") to the ".dead_letter" topic namespace where
+      # they actually live — pre-fix, purge("dead") delete_many'd on
+      # {topic: topic, status: "dead"}, matching zero docs and silently
+      # returning 0 while the dead letters sat untouched in the sibling
+      # namespace. Every path scopes by status so a purge never nukes docs it
+      # was not asked to remove, and every path returns deleted_count so a
+      # caller can log/assert what was purged.
       def purge(topic, status)
-        result = collection.delete_many(topic: topic, status: status.to_s)
+        namespace = dead_status?(status) ? "#{topic}.dead_letter" : topic
+        result = collection.delete_many(topic: namespace, status: status.to_s)
         result.deleted_count
       end
 
@@ -326,20 +337,31 @@ module Tina4
         result.modified_count
       end
 
-      # Move ONE dead-lettered job back to its main topic as pending.
-      # Returns true when a job was revived, false when the id was not found.
+      # Move dead-lettered jobs back to their main topic as pending.
+      #
+      # With +job_id+, revives that ONE dead letter and returns true when
+      # found (false otherwise). With no id, iterates every dead letter for
+      # the topic and revives ALL — materialised into an array before
+      # reducing, so a truthy first result never short-circuits away the
+      # rest (the class of bug the parity port of PY-12-04 pins). Ruby's
+      # dead-letter model stores the SAME document with topic flipped to
+      # "<topic>.dead_letter", so reviving is the reverse in-place update:
+      # flip the topic back, reset status/available_at/error. Mirrors
+      # LiteBackend#retry_job.
       def retry_job(topic, job_id: nil, delay_seconds: 0)
         filter = { topic: "#{topic}.dead_letter", status: "dead" }
         filter[:_id] = job_id if job_id
-        doc = collection.find(filter).first
-        return false unless doc
+        docs = collection.find(filter).to_a
+        return false if docs.empty?
 
         available = delay_seconds.to_f > 0 ? (Time.now.utc + delay_seconds.to_f) : Time.now.utc
-        collection.update_one(
-          { _id: doc["_id"] },
-          { "$set" => { topic: topic, status: "pending", error: nil,
-                        reserved_at: nil, available_at: available } }
-        )
+        docs.each do |doc|
+          collection.update_one(
+            { _id: doc["_id"] },
+            { "$set" => { topic: topic, status: "pending", error: nil,
+                          reserved_at: nil, available_at: available } }
+          )
+        end
         true
       end
 
@@ -358,6 +380,12 @@ module Tina4
 
       private
 
+      DEAD_STATES = %w[failed dead dead_letter].freeze
+
+      def dead_status?(status)
+        DEAD_STATES.include?(status.to_s)
+      end
+
       # A stored document as a plain Hash with string keys, CARRYING attempts
       # and error.
       #

data/lib/tina4/rack_app.rb

@@ -1174,6 +1174,12 @@ module Tina4
         # the auth gate into a 500. It degrades to an empty session, which means
         # no token, which means the ordinary 401 below - a SERVED request.
         session = Tina4::Session.new(env, degrade_on_backend_failure: true)
+        sso = session.get("_tina4_sso")
+        identity = sso.is_a?(Hash) ? sso["identity"] : nil
+        if identity.is_a?(Hash) && identity["issuer"] && identity["subject"]
+          env["tina4.auth_payload"] = identity
+          return nil
+        end
         session_token = session.get("token")
         if session_token && !session_token.empty?
           token = session_token

data/lib/tina4/session.rb

@@ -237,7 +237,7 @@ module Tina4
 
     # Return all session data
     def all
-      @data.dup
+      @data.reject { |key, _| %w[_tina4_sso _tina4_sso_pending].include?(key.to_s) }
     end
 
     # Flash data: set a value that is removed after next read.

data/lib/tina4/sql_translator.rb

@@ -16,7 +16,70 @@ module Tina4
   #   # => "SELECT * FROM users ROWS 6 TO 15"
   #
   class SQLTranslator
+    SPATIAL_ENGINES = %w[postgres postgresql].freeze
+    SPATIAL_IDENTIFIER = /\A[A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*\z/
+
     class << self
+      def require_spatial(engine, feature)
+        name = engine.to_s.downcase
+        return name if SPATIAL_ENGINES.include?(name)
+        raise SpatialNotSupportedError,
+              "#{feature} is not supported on the '#{name.empty? ? 'unknown' : name}' database engine. " \
+              "Tina4 GIS support is PostGIS-first: use PostgreSQL with CREATE EXTENSION postgis. " \
+              "Tina4 will not replace a spatial query with an approximate coordinate query."
+      end
+
+      def spatial_identifier(name, what = "column")
+        text = name.to_s
+        raise ArgumentError, "Spatial #{what} is not a valid SQL identifier: #{text}" unless SPATIAL_IDENTIFIER.match?(text)
+        text
+      end
+
+      def point_column_type(engine, srid = Point::DEFAULT_SRID)
+        require_spatial(engine, "PointField")
+        "geography(Point,#{Integer(srid)})"
+      end
+
+      def spatial_index(engine, table, column)
+        require_spatial(engine, "spatial index creation")
+        table = spatial_identifier(table, "table")
+        column = spatial_identifier(column)
+        "CREATE INDEX IF NOT EXISTS #{table.tr('.', '_')}_#{column}_gist ON #{table} USING GIST (#{column})"
+      end
+
+      def point_literal(engine, srid = Point::DEFAULT_SRID)
+        require_spatial(engine, "spatial predicates")
+        "ST_SetSRID(ST_MakePoint(?, ?), #{Integer(srid)})::geography"
+      end
+
+      def within_distance(engine, column, srid = Point::DEFAULT_SRID)
+        "ST_DWithin(#{spatial_identifier(column)}, #{point_literal(engine, srid)}, ?)"
+      end
+
+      def distance(engine, column, srid = Point::DEFAULT_SRID)
+        "ST_Distance(#{spatial_identifier(column)}, #{point_literal(engine, srid)})"
+      end
+
+      def distance_as(engine, column, alias_name, srid = Point::DEFAULT_SRID)
+        "#{distance(engine, column, srid)} AS #{spatial_identifier(alias_name, 'result alias')}"
+      end
+
+      def geometry_literal(engine, form = :ewkt, srid = Point::DEFAULT_SRID)
+        require_spatial(engine, "spatial predicates")
+        return "ST_GeogFromText(?)" if form.to_sym == :ewkt
+        return "ST_SetSRID(ST_GeomFromGeoJSON(?), #{Integer(srid)})::geography" if form.to_sym == :geojson
+        raise ArgumentError, "Unsupported spatial geometry form: #{form}"
+      end
+
+      def intersects(engine, column, form = :ewkt, srid = Point::DEFAULT_SRID)
+        "ST_Intersects(#{spatial_identifier(column)}, #{geometry_literal(engine, form, srid)})"
+      end
+
+      def bbox(engine, column, srid = Point::DEFAULT_SRID)
+        require_spatial(engine, "bbox")
+        "ST_Intersects(#{spatial_identifier(column)}, ST_MakeEnvelope(?, ?, ?, ?, #{Integer(srid)})::geography)"
+      end
+
       # ── Literal-safe rewriting ────────────────────────────────────
       #
       # A dialect rewrite (|| -> CONCAT, TRUE -> 1, ILIKE -> LOWER LIKE) must NEVER

data/lib/tina4/sso.rb

@@ -0,0 +1,284 @@
+# frozen_string_literal: true
+
+require "base64"
+require "digest"
+require "json"
+require "net/http"
+require "openssl"
+require "securerandom"
+require "uri"
+
+module Tina4
+  class SsoError < StandardError; end
+
+  # Provider-neutral, configuration-first OpenID Connect SSO.
+  class Sso
+    PENDING_KEY = "_tina4_sso_pending"
+    SESSION_KEY = "_tina4_sso"
+    attr_reader :issuer, :client_id, :client_secret, :redirect_uri, :scopes,
+                :verify, :post_logout_redirect_uri, :claim_map
+    @mounted = false
+
+    def initialize(options = {})
+      @issuer = (options[:issuer] || ENV["TINA4_SSO_ISSUER"] || "").sub(%r{/$}, "")
+      @client_id = options[:client_id] || ENV["TINA4_SSO_CLIENT_ID"] || ""
+      @client_secret = options.key?(:client_secret) ? options[:client_secret] : ENV["TINA4_SSO_CLIENT_SECRET"]
+      @redirect_uri = options[:redirect_uri] || ENV["TINA4_SSO_REDIRECT_URI"] || ""
+      @scopes = options[:scopes] || json_env("TINA4_SSO_SCOPES", %w[openid profile email])
+      @verify = (options[:verify] || ENV["TINA4_SSO_VERIFY"] || "introspection").downcase
+      @post_logout_redirect_uri = options[:post_logout_redirect_uri] || ENV["TINA4_SSO_POST_LOGOUT_REDIRECT_URI"]
+      @claim_map = options[:claim_map] || json_env("TINA4_SSO_CLAIM_MAP", {})
+      @metadata = {}
+      validate_config!
+    end
+
+    def self.from_issuer(options = {})
+      new(options).tap(&:discover)
+    end
+
+    def self.configured?
+      %w[TINA4_SSO_ISSUER TINA4_SSO_CLIENT_ID TINA4_SSO_REDIRECT_URI].all? { |key| !ENV[key].to_s.empty? }
+    end
+
+    def json_env(name, fallback)
+      raw = ENV[name]
+      raw.nil? || raw.empty? ? fallback : JSON.parse(raw)
+    rescue JSON::ParserError => e
+      raise SsoError, "#{name} must be valid JSON", cause: e
+    end
+
+    def self.secure_url!(value, name)
+      uri = URI.parse(value)
+      raise SsoError, "#{name} must be an absolute URL" unless uri.absolute? && uri.host
+
+      loopback = %w[localhost 127.0.0.1 ::1].include?(uri.host)
+      raise SsoError, "#{name} must use HTTPS except on loopback" unless uri.scheme == "https" || (uri.scheme == "http" && loopback)
+    rescue URI::InvalidURIError => e
+      raise SsoError, "#{name} must be an absolute URL", cause: e
+    end
+
+    def validate_config!
+      if @issuer.empty? || @client_id.empty? || @redirect_uri.empty?
+        raise SsoError, "TINA4_SSO_ISSUER, TINA4_SSO_CLIENT_ID and TINA4_SSO_REDIRECT_URI are required"
+      end
+      self.class.secure_url!(@issuer, "issuer")
+      self.class.secure_url!(@redirect_uri, "redirect URI")
+      raise SsoError, "TINA4_SSO_VERIFY must be introspection or jwks" unless %w[introspection jwks].include?(@verify)
+      raise SsoError, "jwks verification requires an installed cryptography capability" if @verify == "jwks"
+      raise SsoError, "introspection verification requires TINA4_SSO_CLIENT_SECRET" if @verify == "introspection" && @client_secret.to_s.empty?
+      raise SsoError, "TINA4_SSO_SCOPES must be a list containing openid" unless @scopes.is_a?(Array) && @scopes.include?("openid")
+    end
+
+    def request_json(url, form: nil, bearer: nil, basic: false)
+      uri = URI.parse(url)
+      request = form ? Net::HTTP::Post.new(uri) : Net::HTTP::Get.new(uri)
+      request["Accept"] = "application/json"
+      request.set_form_data(form.transform_values(&:to_s)) if form
+      request["Authorization"] = "Bearer #{bearer}" if bearer
+      request.basic_auth(@client_id, @client_secret) if basic
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.verify_mode = OpenSSL::SSL::VERIFY_PEER if http.use_ssl?
+      http.open_timeout = 10
+      http.read_timeout = 10
+      response = http.request(request)
+      raise SsoError, "OIDC provider request failed" unless response.is_a?(Net::HTTPSuccess)
+      result = JSON.parse(response.body)
+      raise SsoError, "OIDC provider returned a non-object response" unless result.is_a?(Hash)
+      result
+    rescue JSON::ParserError, IOError, SystemCallError, Timeout::Error => e
+      raise SsoError, "OIDC provider request failed", cause: e
+    end
+
+    def discover(force = false)
+      return @metadata.dup unless @metadata.empty? || force
+      result = request_json("#{@issuer}/.well-known/openid-configuration")
+      raise SsoError, "OIDC discovery issuer does not exactly match configuration" unless result["issuer"] == @issuer
+      required = %w[authorization_endpoint token_endpoint]
+      required << "introspection_endpoint" if @verify == "introspection"
+      required.each do |key|
+        raise SsoError, "OIDC discovery is missing #{key}" if result[key].to_s.empty?
+        self.class.secure_url!(result[key], key)
+      end
+      @metadata = result
+      result.dup
+    end
+
+    def self.safe_return(value)
+      return "/" if value.to_s.empty? || !value.start_with?("/") || value.start_with?("//") || value.include?("\\")
+      value.each_byte.any? { |byte| byte < 32 } ? "/" : value
+    end
+
+    def session(value)
+      value.is_a?(Tina4::Session) ? value : value&.session
+    end
+
+    def login(request_or_session, return_to = "/")
+      current = session(request_or_session)
+      raise SsoError, "SSO login requires a Tina4 Session" unless current
+      state = SecureRandom.urlsafe_base64(32)
+      nonce = SecureRandom.urlsafe_base64(32)
+      verifier = SecureRandom.urlsafe_base64(64)
+      challenge = Base64.urlsafe_encode64(Digest::SHA256.digest(verifier), padding: false)
+      current.set(PENDING_KEY, {
+                    "state" => state, "nonce" => nonce, "verifier" => verifier,
+                    "return_to" => self.class.safe_return(return_to), "created_at" => Time.now.to_i
+                  })
+      query = URI.encode_www_form(
+        client_id: @client_id, redirect_uri: @redirect_uri, response_type: "code",
+        scope: @scopes.join(" "), state: state, nonce: nonce,
+        code_challenge: challenge, code_challenge_method: "S256"
+      )
+      "#{discover['authorization_endpoint']}?#{query}"
+    end
+
+    def self.secure_equal(left, right)
+      a = left.to_s
+      b = right.to_s
+      a.bytesize == b.bytesize && OpenSSL.fixed_length_secure_compare(a, b)
+    end
+
+    def self.jwt_payload(token)
+      part = token.split(".")[1].to_s
+      JSON.parse(Base64.urlsafe_decode64(part.ljust((part.length + 3) / 4 * 4, "=")))
+    rescue JSON::ParserError, ArgumentError
+      raise SsoError, "provider returned an invalid ID token"
+    end
+
+    def introspect(access_token)
+      result = request_json(discover["introspection_endpoint"],
+                            form: { token: access_token, token_type_hint: "access_token" }, basic: true)
+      unless result["active"] == true && result["iss"] == @issuer
+        raise SsoError, "OIDC access token is inactive or has the wrong issuer"
+      end
+      audience = result["aud"] || result["client_id"]
+      valid = audience.is_a?(Array) ? audience.include?(@client_id) : audience == @client_id
+      valid ||= result["client_id"] == @client_id
+      raise SsoError, "OIDC token audience mismatch" unless valid
+      result
+    end
+
+    def claim(claims, configured, fallback)
+      (configured || fallback).split(".").reduce(claims) { |value, key| value.is_a?(Hash) ? value[key] : nil }
+    end
+
+    def normalize(claims)
+      subject = claim(claims, @claim_map["subject"], "sub")
+      identity_issuer = claim(claims, @claim_map["issuer"], "iss") || @issuer
+      raise SsoError, "OIDC identity is missing a valid issuer or subject" if subject.to_s.empty? || identity_issuer != @issuer
+      roles = Array(claim(claims, @claim_map["roles"], "realm_access.roles"))
+      roles += Array(claims.dig("resource_access", @client_id, "roles"))
+      groups = Array(claim(claims, @claim_map["groups"], "groups"))
+      {
+        "issuer" => identity_issuer, "subject" => subject,
+        "username" => claim(claims, @claim_map["username"], "preferred_username"),
+        "email" => claim(claims, @claim_map["email"], "email"),
+        "name" => claim(claims, @claim_map["name"], "name"),
+        "roles" => roles.map(&:to_s).uniq.sort, "groups" => groups.map(&:to_s).uniq.sort
+      }
+    end
+
+    def callback(request_or_session, query = nil)
+      current = session(request_or_session)
+      values = query || request_or_session.params
+      pending = current&.get(PENDING_KEY)
+      current&.delete(PENDING_KEY)
+      unless pending.is_a?(Hash) && !values["code"].to_s.empty? && self.class.secure_equal(values["state"], pending["state"])
+        raise SsoError, "OIDC callback state is invalid or already consumed"
+      end
+      raise SsoError, "OIDC callback state has expired" if Time.now.to_i - pending.fetch("created_at", 0).to_i > 600
+      metadata = discover
+      tokens = request_json(metadata["token_endpoint"], form: {
+                              grant_type: "authorization_code", code: values["code"], redirect_uri: @redirect_uri,
+                              client_id: @client_id, code_verifier: pending["verifier"]
+                            }, basic: !@client_secret.to_s.empty?)
+      raise SsoError, "OIDC token response is incomplete" if tokens["access_token"].to_s.empty? || tokens["id_token"].to_s.empty?
+      raise SsoError, "JWKS verification requires an installed cryptography capability" if @verify == "jwks"
+      claims = introspect(tokens["access_token"])
+      unless self.class.secure_equal(self.class.jwt_payload(tokens["id_token"])["nonce"], pending["nonce"])
+        raise SsoError, "OIDC ID token nonce mismatch"
+      end
+      claims.merge!(request_json(metadata["userinfo_endpoint"], bearer: tokens["access_token"])) if metadata["userinfo_endpoint"]
+      identity = normalize(claims)
+      current.regenerate
+      current.set(SESSION_KEY, {
+                    "version" => 1, "identity" => identity, "access_token" => tokens["access_token"],
+                    "refresh_token" => tokens["refresh_token"], "id_token" => tokens["id_token"],
+                    "expires_at" => Time.now.to_i + tokens.fetch("expires_in", 0).to_i
+                  })
+      { "identity" => identity, "return_to" => self.class.safe_return(pending["return_to"]) }
+    end
+
+    def identity(request_or_session)
+      stored = session(request_or_session)&.get(SESSION_KEY)
+      value = stored.is_a?(Hash) ? stored["identity"] : nil
+      request_or_session.user = value if value && !request_or_session.is_a?(Tina4::Session)
+      value
+    end
+
+    def refresh(request_or_session)
+      current = session(request_or_session)
+      stored = current&.get(SESSION_KEY)
+      unless stored.is_a?(Hash) && !stored["refresh_token"].to_s.empty?
+        current&.delete(SESSION_KEY)
+        raise SsoError, "OIDC session cannot be refreshed"
+      end
+      metadata = discover
+      tokens = request_json(metadata["token_endpoint"], form: {
+                              grant_type: "refresh_token", refresh_token: stored["refresh_token"], client_id: @client_id
+                            }, basic: !@client_secret.to_s.empty?)
+      claims = introspect(tokens["access_token"])
+      claims.merge!(request_json(metadata["userinfo_endpoint"], bearer: tokens["access_token"])) if metadata["userinfo_endpoint"]
+      value = normalize(claims)
+      current.set(SESSION_KEY, stored.merge(
+        "identity" => value, "access_token" => tokens["access_token"],
+        "refresh_token" => tokens["refresh_token"] || stored["refresh_token"],
+        "id_token" => tokens["id_token"] || stored["id_token"],
+        "expires_at" => Time.now.to_i + tokens.fetch("expires_in", 0).to_i
+      ))
+      value
+    rescue StandardError
+      current&.delete(SESSION_KEY)
+      raise
+    end
+
+    def logout(request_or_session, return_to = "/")
+      current = session(request_or_session)
+      stored = current&.get(SESSION_KEY)
+      current&.destroy
+      endpoint = discover["end_session_endpoint"]
+      target = @post_logout_redirect_uri || self.class.safe_return(return_to)
+      return target unless endpoint
+      params = { post_logout_redirect_uri: target, client_id: @client_id }
+      params[:id_token_hint] = stored["id_token"] if stored.is_a?(Hash) && stored["id_token"]
+      "#{endpoint}?#{URI.encode_www_form(params)}"
+    end
+
+    def self.mount_configured
+      return false if @mounted || !configured?
+      owned = [["GET", "/auth/login"], ["GET", "/auth/callback"], ["POST", "/auth/logout"]]
+      collisions = Tina4::Router.routes.select { |route| owned.include?([route.method, route.path]) }
+      unless collisions.empty?
+        raise SsoError, "SSO route collision: #{collisions.map { |route| "#{route.method} #{route.path}" }.join(', ')}"
+      end
+      sso = from_issuer
+      Tina4::Router.get("/auth/login") do |request, response|
+        response.redirect(sso.login(request, request.params["return_to"] || "/"))
+      end
+      Tina4::Router.get("/auth/callback") do |request, response|
+        begin
+          response.redirect(sso.callback(request)["return_to"])
+        rescue SsoError => e
+          response.json({ error: "SSO_CALLBACK_FAILED", message: e.message }, 400)
+        end
+      end
+      Tina4::Router.post("/auth/logout") do |request, response|
+        response.redirect(sso.logout(request, request.params["return_to"] || "/"))
+      end
+      @mounted = true
+      true
+    end
+  end
+
+  SSO = Sso
+end

data/lib/tina4/swagger.rb

@@ -161,6 +161,17 @@ module Tina4
           }
         end
 
+        sso_issuer = ENV["TINA4_SSO_ISSUER"].to_s.sub(%r{/$}, "")
+        unless sso_issuer.empty?
+          schemes["oidc"] = {
+            "type" => "openIdConnect",
+            "openIdConnectUrl" => "#{sso_issuer}/.well-known/openid-configuration"
+          }
+          schemes["ssoSession"] = {
+            "type" => "apiKey", "in" => "cookie", "name" => "tina4_session"
+          }
+        end
+
         # Registered schemes win (let an app override bearerAuth or add oauth2).
         @registered_schemes.each { |name, defn| schemes[name] = defn }
         schemes
@@ -302,7 +313,11 @@ module Tina4
         #
         # Both flags are honoured. A custom auth_handler protects a route even
         # when auth_required is false for its method, so it is still documented.
-        return sanitize_security([{ default_scheme => [] }], schemes) if route.auth_required || route.auth_handler
+        if route.auth_required || route.auth_handler
+          requirements = [{ default_scheme => [] }]
+          requirements << { "ssoSession" => [] } if default_scheme == "bearerAuth" && schemes.key?("ssoSession")
+          return sanitize_security(requirements, schemes)
+        end
 
         nil
       end

data/lib/tina4/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tina4
-  VERSION = "3.13.103"
+  VERSION = "3.13.105"
 end

data/lib/tina4.rb

@@ -15,6 +15,7 @@ require_relative "tina4/database_adapter"
 require_relative "tina4/database_url"
 require_relative "tina4/database"
 require_relative "tina4/database_result"
+require_relative "tina4/point"
 require_relative "tina4/field_types"
 require_relative "tina4/orm"
 require_relative "tina4/query_builder"
@@ -25,6 +26,7 @@ require_relative "tina4/template"
 require_relative "tina4/frond"
 require_relative "tina4/auth"
 require_relative "tina4/session"
+require_relative "tina4/sso"
 require_relative "tina4/middleware"
 require_relative "tina4/cors"
 require_relative "tina4/rate_limiter"
@@ -487,6 +489,10 @@ module Tina4
       # Auto-discover routes
       auto_discover(root_dir)
 
+      # Configuration-first OIDC mounts after application discovery so a
+      # canonical-path collision fails loudly rather than being shadowed.
+      Tina4::Sso.mount_configured
+
       # Apply pending DB migrations on startup (non-breaking — see method doc).
       # Runs AFTER route discovery / DB bind, BEFORE serving.
       auto_migrate_on_startup!(root_dir)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tina4ruby
 version: !ruby/object:Gem::Version
-  version: 3.13.103
+  version: 3.13.105
 platform: ruby
 authors:
 - Tina4 Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-16 00:00:00.000000000 Z
+date: 2026-08-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -397,6 +397,7 @@ files:
 - lib/tina4/mqtt_message.rb
 - lib/tina4/orm.rb
 - lib/tina4/plan.rb
+- lib/tina4/point.rb
 - lib/tina4/port_takeover.rb
 - lib/tina4/project_index.rb
 - lib/tina4/public/__feedback/widget.js
@@ -448,6 +449,7 @@ files:
 - lib/tina4/session_handlers/valkey_handler.rb
 - lib/tina4/shutdown.rb
 - lib/tina4/sql_translator.rb
+- lib/tina4/sso.rb
 - lib/tina4/swagger.rb
 - lib/tina4/template.rb
 - lib/tina4/templates/base.twig