tina4ruby 3.13.94 → 3.13.97

data/lib/tina4/database_result.rb

@@ -8,7 +8,15 @@ module Tina4
     attr_reader :records, :columns, :count, :limit, :offset, :sql,
                 :affected_rows, :last_id, :error
 
-    def initialize(records = [], sql: "", columns: [], count: nil, limit: 10, offset: 0,
+    # `limit` is the row cap ACTUALLY APPLIED to the statement that produced
+    # these records — what Database#fetch appended — and `0` means none was
+    # (an explicit no-limit read, SQL carrying its own trailing LIMIT, or a
+    # write). The default used to be `10`: Database#fetch_direct never passed
+    # limit:/offset:, so that untouched default was reported on EVERY fetch
+    # whatever limit ran — and 10 is the stale v2 documentation number that the
+    # buried PHP row-cap test also asserted as the cap. 0 says "no cap recorded"
+    # instead of quietly naming a number nothing applied.
+    def initialize(records = [], sql: "", columns: [], count: nil, limit: 0, offset: 0,
                    affected_rows: 0, last_id: nil, error: nil, db: nil)
       @records = records || []
       @sql = sql
@@ -91,26 +99,60 @@ module Tina4
       lines.join("\n")
     end
 
-    def to_paginate(page: nil, per_page: nil)
-      per_page ||= @limit > 0 ? @limit : 10
-      page ||= @offset > 0 ? (@offset / per_page) + 1 : 1
-      total = @count
-      total_pages = [1, (total.to_f / per_page).ceil].max
-      slice_offset = (page - 1) * per_page
-      page_records = @records[slice_offset, per_page] || []
+    # Describe the page this result already IS. Takes NO arguments (ADR-0043).
+    #
+    # Every field is derived from the query that produced this result:
+    #   per_page    = the query's limit
+    #   page        = floor(offset / limit) + 1
+    #   total       = the true total for the filter (@count, from the COUNT probe
+    #                 Database#fetch runs when it applied the limit), NEVER the
+    #                 number of rows this page returned
+    #   total_pages = ceil(total / per_page)
+    #   records     = the rows the query returned, VERBATIM, never re-sliced
+    #   limit/offset= the SQL limit/offset actually applied
+    #
+    # The envelope is EXACTLY seven snake_case keys, identical in all four
+    # frameworks: records, total, page, per_page, total_pages, limit, offset. The
+    # old duplicate/camelCase spellings (data, count, totalPages, has_next,
+    # has_prev) are gone - a JSON key is data and does not change spelling by host
+    # language, so the same integer never ships twice under two names.
+    #
+    # PASSING ANY ARGUMENT RAISES. A DatabaseResult holds no connection, so an
+    # argument could only re-slice rows already in memory and then report
+    # total_pages for pages it can never reach. To read page N, FETCH page N
+    # (limit + offset) and call this with no arguments. The removed page:/per_page:
+    # slicing mode is a hard error, never a silent reinterpretation - superseding
+    # the in-memory slice GitHub #106 asked for.
+    #
+    # MEASURED 2026-08-05 on a real 250-row table read with limit=20 offset=40
+    # (page 3 of 13): the old two-mode method re-sliced @records by the ABSOLUTE
+    # offset (40) against an array already only 20 long and returned ZERO records
+    # for a valid page, while still shipping a page number and total - an envelope
+    # that looked authoritative and was empty.
+    def to_paginate(*args, **kwargs)
+      unless args.empty? && kwargs.empty?
+        raise ArgumentError,
+              "to_paginate takes no arguments (ADR-0043): it describes the page " \
+              "this result already IS, derived from the query that produced it. A " \
+              "DatabaseResult holds no connection, so an argument could only " \
+              "re-slice rows already in memory and lie about total_pages. To read " \
+              "another page, FETCH it - fetch(sql, limit: per_page, offset: " \
+              "(page - 1) * per_page) - then call to_paginate with no arguments."
+      end
+
+      per_page    = @limit.to_i > 0 ? @limit.to_i : @records.size
+      page        = per_page > 0 ? (@offset.to_i / per_page) + 1 : 1
+      total       = @count
+      total_pages = per_page > 0 ? [1, (total.to_f / per_page).ceil].max : 1
+
       {
-        records: page_records,
-        data: page_records,
-        count: total,
+        records: @records,
         total: total,
-        limit: per_page,
-        offset: (page - 1) * per_page,
         page: page,
         per_page: per_page,
-        totalPages: total_pages,
         total_pages: total_pages,
-        has_next: page < total_pages,
-        has_prev: page > 1
+        limit: per_page,
+        offset: @offset.to_i
       }
     end
 
@@ -179,7 +221,11 @@ module Tina4
           size: size,
           decimals: decimals,
           nullable: col.key?(:nullable) ? col[:nullable] : (col.key?("nullable") ? col["nullable"] : true),
-          primary_key: col[:primary_key] || col["primary_key"] || col[:primary] || col["primary"] || false
+          # Symbol OR string key, because a driver row may arrive either way.
+          # The `:primary` / `"primary"` fallbacks that used to sit here were
+          # dead: no Ruby driver has ever emitted that spelling. It was mirroring
+          # PHP's odd `primary`, which PHP itself has now dropped for `primaryKey`.
+          primary_key: col[:primary_key] || col["primary_key"] || false
         }
       end
     end

data/lib/tina4/database_url.rb

@@ -0,0 +1,363 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Tina4
+  # A parsed database connection URL, as a VALUE.
+  #
+  # Feature 5 of the feature audit. Ruby had no parser to call: URL handling was
+  # inline in +Database#initialize+, so a URL could not be parsed without
+  # building a connection object. The parse could not be unit tested on its own,
+  # the four frameworks could not be compared without standing up a database,
+  # and +tina4 doctor+ or the setup wizard had nothing to call to validate a URL
+  # before using it.
+  #
+  # What was there instead was +detect_driver+: substring regex matching over the
+  # whole connection string with a silent <tt>else "sqlite"</tt> fallback, so an
+  # unrecognised URL did not fail - it quietly became SQLite. The app boots,
+  # writes to a local file, and nobody learns the real database was never
+  # reached. This class raises instead.
+  #
+  # Core Principle 6 says a connection string must mean literally the same thing
+  # in every framework. +spec/fixtures/database_url_corpus.json+ is the answer
+  # key, byte-identical in all four.
+  # DISPLAY REDACTS, FIDELITY DOES NOT. #inspect, #to_s and #to_safe_string
+  # replace the password with the redaction marker, so a log line, a backtrace or
+  # a status payload is safe. Marshal deliberately does not: its contract is a
+  # faithful round trip, and a masked Marshal would load an object whose password
+  # is the literal "***".
+  #
+  # The consequence: DO NOT PERSIST THIS OBJECT. A DatabaseUrl marshalled into a
+  # cache, a session or a queue payload puts the password in cleartext on disk.
+  # Record #to_safe_string instead. spec/database_url_redaction_spec.rb fails the
+  # build if framework code ever marshals one.
+  class DatabaseUrl
+    # URL scheme to CANONICAL engine. Aliases resolve ONCE, here, so nothing
+    # downstream ever compares raw schemes.
+    #
+    # +sqlite3+ is accepted because the driver is literally named sqlite3 in
+    # every framework (Python's sqlite3 module, Ruby's sqlite3 gem, PHP's
+    # ext-sqlite3, Node's node:sqlite), so people type it. The "3" is a
+    # file-format version, not a different engine, which is why the canonical
+    # name stays +sqlite+.
+    ENGINE_ALIASES = {
+      "sqlite" => "sqlite",
+      "sqlite3" => "sqlite",
+      "postgres" => "postgres",
+      "postgresql" => "postgres",
+      "pgsql" => "postgres",
+      "mysql" => "mysql",
+      "mssql" => "mssql",
+      "sqlserver" => "mssql",
+      "firebird" => "firebird",
+      "mongodb" => "mongodb",
+      "mongo" => "mongodb",
+      "odbc" => "odbc"
+    }.freeze
+
+    # Applied AT PARSE. The port is part of our contract, not the driver's
+    # business: a URL with no port must yield the same struct in all four.
+    DEFAULT_PORTS = {
+      "postgres" => 5432,
+      "mysql" => 3306,
+      "mssql" => 1433,
+      "firebird" => 3050,
+      "mongodb" => 27017
+    }.freeze
+
+    # What replaces a credential everywhere. One spelling, so a test can assert
+    # on it and a reader recognises it on sight.
+    REDACTED = "***"
+
+    # RFC 3986 scheme grammar. A scheme cannot contain ":", "@", "/" or a space,
+    # which is what makes it the ONLY part of an unparseable string that is
+    # provably not a password.
+    SCHEME = /\A[A-Za-z][A-Za-z0-9+.\-]*\z/.freeze
+
+    # host[:port][/path] with a NUMERIC port. The digit requirement is what does
+    # the work: it is why "user:secret" (a URL with the host left off) fails to
+    # match and gets redacted, while "192.168.88.99:55432/tina4_py" is echoed.
+    HOST_PORT = %r{\A(?:\[[0-9A-Fa-f:.]+\]|[A-Za-z0-9._-]+)(?::\d+)?(?:/.*)?\z}m.freeze
+
+    # Credential KEYWORDS in the two keyword=value forms that carry one: the
+    # ODBC connection string (";"-separated) and the libpq/JDBC query string
+    # ("&"-separated). A braced value is matched FIRST because an ODBC value
+    # containing ";" must be braced - stopping at the ";" would leave the tail
+    # of the password in the output, which is exactly the bug shape this file
+    # exists to close.
+    #
+    # UID/USER are deliberately NOT redacted: a username is not a secret, and it
+    # is most of what makes a failed connection diagnosable.
+    CREDENTIAL_KEYWORDS = /\b(PWD|PASSWORD)\s*=\s*(?:\{[^}]*\}|[^;&]*)/i.freeze
+
+    attr_reader :engine, :host, :port, :database, :username, :password,
+                :connection_string
+
+    def initialize(url, username: nil, password: nil)
+      raise ArgumentError, "DatabaseUrl: the URL is empty" if url.nil? || url.to_s.strip.empty?
+
+      url = url.to_s
+      @host = nil
+      @port = nil
+      @database = ""
+      @username = nil
+      @password = nil
+      @connection_string = nil
+
+      if url.start_with?("sqlite:", "sqlite3:")
+        parse_sqlite(url)
+      elsif url.start_with?("odbc:///")
+        @engine = "odbc"
+        @connection_string = url[("odbc:///".length)..]
+      else
+        parse_standard(url)
+      end
+
+      # Separate credentials fill in only when the URL carried NONE.
+      #
+      # ABSENT and BLANK are different values, and the difference is load
+      # bearing: the gate is `nil?`, never `empty?`. A URL written
+      #   postgres://user:@host/db
+      # states an explicitly EMPTY password, so the TINA4_DATABASE_PASSWORD
+      # fallback must NOT fire; only
+      #   postgres://user@host/db
+      # is absent and takes the env value. Measured 2026-08-02: Ruby and PHP
+      # obey this, Python and Node return None for the blank form and therefore
+      # authenticate with a DIFFERENT password off the SAME .env - which is the
+      # kind of divergence nobody notices until an account locks out.
+      @username = username if @username.nil? && username && !username.empty?
+      @password = password if @password.nil? && password && !password.empty?
+    end
+
+    # Parse the configured URL, or nil when the variable is not set.
+    def self.from_env(key = "TINA4_DATABASE_URL")
+      url = (ENV[key] || "").strip
+      return nil if url.empty?
+
+      new(url, username: ENV["TINA4_DATABASE_USERNAME"], password: ENV["TINA4_DATABASE_PASSWORD"])
+    end
+
+    # THE redaction primitive. Every connection string that is about to reach a
+    # log line, an exception message or a dump goes through here.
+    #
+    # It takes a RAW string and never raises, because the paths that most need
+    # redacting are exactly the ones where parsing already failed.
+    #
+    # Measured in this repo on 2026-08-02, before this existed:
+    #   * Database#safe_connection_target carried its OWN regex, and
+    #       postgres://u:p@ss@h:5432/db -> postgres://u:***@ss@h:5432/db
+    #     leaked the password tail past the first "@" (the Ruby twin of the PHP
+    #     `password=\S*` tail leak), and
+    #       odbc:///...;PWD=<secret>    -> returned VERBATIM
+    #     went straight into DatabaseConnectionError, which is raised at the
+    #     first query and lands in a 500 body.
+    #   * DatabaseUrl's own invalid-URL ArgumentError interpolated the whole raw
+    #     URL, and detect_driver raises it on the BOOT path, so one typo in
+    #     TINA4_DATABASE_URL wrote the password into the boot log and CI output.
+    # One primitive means the next such bug is fixed once, not four times.
+    def self.redact(raw)
+      text = raw.to_s
+      return "" if text.empty?
+
+      begin
+        # A URL that PARSES gets the round-tripping form rebuilt from the parsed
+        # FIELDS. That form cannot leak: the password is never copied into it.
+        new(text).to_safe_string
+      rescue StandardError
+        # Unparseable - fall back to the structural scrub. Redaction must never
+        # raise; a raise here would mask the error we were called to describe.
+        scrub(text)
+      end
+    end
+
+    # Structural redaction of a string that did NOT parse.
+    def self.scrub(text)
+      head, separator, rest = text.to_s.partition("://")
+
+      # No "://" - a bare file path, or an ODBC/keyword string. There is no
+      # userinfo to find, so only the keyword form can hide a secret here.
+      return scrub_keywords(text.to_s) if separator.empty?
+
+      # A head that is not a scheme is unknown text, and unknown text may BE the
+      # secret (the measured Python case was `notaurl-with-SuperSecret123`).
+      # Say nothing about it rather than guess.
+      return REDACTED unless head.match?(SCHEME)
+
+      # The authority is taken to the first "?" or "#", NOT to the first "/".
+      # An unencoded "/" inside a password would otherwise cut the region short,
+      # push the "@" outside it, and let the password prefix survive.
+      cut = rest.index(/[?#]/) || rest.length
+      "#{head}://#{redact_authority(rest[0, cut])}#{scrub_keywords(rest[cut..].to_s)}"
+    end
+
+    # Take the credential out of a URL authority.
+    #
+    #   user:pass@host:5432/db -> user:***@host:5432/db
+    #   host:5432/db           -> host:5432/db   (no credential present)
+    #   user:pass              -> user:***       (host left off - a real typo,
+    #                                             and the only reason the no-"@"
+    #                                             branch cannot echo blindly)
+    def self.redact_authority(authority)
+      # The LAST "@", because userinfo ends at the last "@" (RFC 3986). Splitting
+      # on the FIRST one is how an unencoded "@" inside a password leaves a tail
+      # in the output.
+      at = authority.rindex("@")
+      if at
+        userinfo = authority[0, at]
+        host = authority[(at + 1)..].to_s
+        name, colon, = userinfo.partition(":")
+        return colon.empty? ? "#{name}@#{host}" : "#{name}:#{REDACTED}@#{host}"
+      end
+
+      return authority if authority.match?(HOST_PORT)
+
+      name, colon, = authority.partition(":")
+      colon.empty? ? name : "#{name}:#{REDACTED}"
+    end
+
+    # Redact the value side of a credential keyword, leaving every other
+    # keyword visible so the string is still diagnosable.
+    def self.scrub_keywords(text)
+      text.gsub(CREDENTIAL_KEYWORDS) { "#{Regexp.last_match(1)}=#{REDACTED}" }
+    end
+
+    # The invalid-URL message, with the credential taken OUT.
+    #
+    # It still has to be diagnosable, so it keeps the scheme, the host, the port
+    # as written (the usual fault) and the database name - only the password
+    # becomes ***. When the value has no "://" there is no structure to trust,
+    # so the value is not shown at all and the message says why.
+    def self.invalid_url_error(url)
+      text = url.to_s
+      if text.include?("://")
+        "DatabaseUrl: Invalid URL format '#{scrub(text)}' - expected " \
+          "scheme://user:password@host:port/database"
+      else
+        "DatabaseUrl: Invalid URL format - no '://', so there is no scheme to " \
+          "connect with. The URL itself is not shown because it can contain a " \
+          "password. Expected scheme://user:password@host:port/database"
+      end
+    end
+
+    # Connection target. sqlite and odbc are the whole value.
+    def dsn
+      return @database if @engine == "sqlite"
+      return @connection_string.to_s if @engine == "odbc"
+
+      out = @host.to_s
+      out += ":#{@port}" unless @port.nil?
+      out += "/#{@database}" unless @database.empty?
+      out
+    end
+
+    # The URL with the password replaced by <tt>***</tt>.
+    #
+    # The ONLY form allowed in a log line or an error message: a connection URL
+    # in a log is a credential leak. It round-trips the input, so it stays
+    # readable as well as safe.
+    def to_safe_string
+      return "sqlite:///#{@database}" if @engine == "sqlite"
+      # ODBC used to return the connection string VERBATIM here, PWD= included -
+      # measured 2026-08-02. The negative test "never leaks the password" passed
+      # anyway, because the shared corpus had no odbc row for it to check: the
+      # guard existed, the test was green, and it protected nothing. Every other
+      # keyword stays visible so a failed ODBC connection is still diagnosable.
+      return "odbc:///#{self.class.scrub_keywords(@connection_string.to_s)}" if @engine == "odbc"
+
+      out = "#{@engine}://"
+      unless @username.nil?
+        out += @username
+        out += ":***" unless @password.nil?
+        out += "@"
+      end
+      out += @host.to_s
+      out += ":#{@port}" unless @port.nil?
+      out += "/#{@database}" unless @database.empty?
+      out
+    end
+
+    # inspect lands in backtraces and the console, so it MUST be the safe form.
+    def inspect
+      "#<Tina4::DatabaseUrl #{to_safe_string}>"
+    end
+
+    # Interpolation ("connecting to #{url}") and JSON both have to be safe, not
+    # just inspect. Ruby's inspect already guarded the console and backtraces -
+    # these two close the same class of leak PHP has through print_r/var_dump
+    # and Node through JSON.stringify, and they make the useless default
+    # "#<Tina4::DatabaseUrl:0x000...>" say something instead.
+    def to_s
+      to_safe_string
+    end
+
+    def to_json(*args)
+      to_safe_string.to_json(*args)
+    end
+
+    private
+
+    # Strip EXACTLY ONE leading slash: the URL path separator, never more.
+    def strip_one_slash(path)
+      path.start_with?("/") ? path[1..] : path
+    end
+
+    # sqlite is parsed on the RAW string, never through URI. URI collapses
+    # "sqlite:/x" and "sqlite:///x", losing the difference between a one-slash
+    # ABSOLUTE path and the documented three-slash RELATIVE form.
+    #
+    #   sqlite:///app.db       -> app.db        (three slashes = relative)
+    #   sqlite:////abs/app.db  -> /abs/app.db   (four slashes = absolute)
+    #   sqlite:/abs/app.db     -> /abs/app.db   (one slash = a real absolute)
+    #   sqlite:app.db          -> app.db
+    def parse_sqlite(url)
+      @engine = "sqlite"
+      url = "sqlite:#{url[("sqlite3:".length)..]}" if url.start_with?("sqlite3:")
+
+      @database = if ["sqlite::memory:", "sqlite:///:memory:"].include?(url)
+                    ":memory:"
+                  elsif url.start_with?("sqlite:///")
+                    strip_one_slash(url[("sqlite://".length)..])
+                  elsif url.start_with?("sqlite://")
+                    url[("sqlite://".length)..]
+                  else
+                    url[("sqlite:".length)..]
+                  end
+    end
+
+    def parse_standard(url)
+      parsed = begin
+        URI.parse(url)
+      rescue URI::InvalidURIError
+        # NEVER interpolate the raw URL here. Measured 2026-08-02: a malformed
+        # TINA4_DATABASE_URL put the password verbatim into this ArgumentError,
+        # and Database#detect_driver raises it during boot - so the credential
+        # reached the boot log, the error overlay, a crash report and CI output.
+        raise ArgumentError, self.class.invalid_url_error(url)
+      end
+
+      scheme = parsed.scheme.to_s.downcase
+      raise ArgumentError, self.class.invalid_url_error(url) if scheme.empty?
+
+      engine = ENGINE_ALIASES[scheme]
+      if engine.nil?
+        raise ArgumentError,
+              "DatabaseUrl: Unsupported database scheme '#{scheme}'. " \
+              "Supported: #{ENGINE_ALIASES.keys.join(', ')}"
+      end
+
+      @engine = engine
+      @host = parsed.host && !parsed.host.empty? ? parsed.host : nil
+      @port = parsed.port || DEFAULT_PORTS[engine]
+      @username = parsed.user ? URI.decode_www_form_component(parsed.user) : nil
+      @password = parsed.password ? URI.decode_www_form_component(parsed.password) : nil
+
+      # Strip EXACTLY ONE leading slash - the URL path separator. Stripping every
+      # slash turns the documented absolute Firebird form
+      # `firebird://host:3050//var/lib/db.fdb` into the RELATIVE
+      # `var/lib/db.fdb`. Verified against live Firebird 5.0.4: the driver takes
+      # one or two leading slashes and rejects a relative path outright.
+      database = strip_one_slash(parsed.path.to_s)
+      @database = database.empty? && engine == "mongodb" ? "tina4" : database
+    end
+  end
+end

data/lib/tina4/dev.rb

@@ -3,7 +3,6 @@
 # Convenience require for all development/optional tools.
 # Usage: require "tina4/dev"
 
-require_relative "scss_compiler"
 require_relative "testing"
 require_relative "graphql"
 require_relative "websocket"

data/lib/tina4/dev_admin.rb

@@ -467,18 +467,13 @@ module Tina4
         when ["GET", "/__dev/api/system"]
           json_response(system_payload)
         when ["GET", "/__dev/api/queue/topics"]
-          queue_dir = File.join(Dir.pwd, "data", "queue")
-          topics = Dir.exist?(queue_dir) ? Dir.children(queue_dir).select { |d| File.directory?(File.join(queue_dir, d)) }.sort : []
-          topics = ["default"] if topics.empty?
-          json_response({ topics: topics })
+          json_response({ topics: queue_topics })
         when ["GET", "/__dev/api/queue/dead-letters"]
           topic = query_param(env, "topic") || "default"
-          jobs = []
-          begin
-            queue = Tina4::Queue.new(backend: :file, topic: topic) if defined?(Tina4::Queue)
-            jobs = queue.respond_to?(:dead_letters) ? queue.dead_letters.map { |j| j.merge(status: "dead_letter") } : []
-          rescue StandardError => e
-            jobs = []
+          jobs = begin
+            queue_dead_letters(topic)
+          rescue StandardError
+            []
           end
           json_response({ jobs: jobs, count: jobs.size, topic: topic })
         when ["GET", "/__dev/api/queue"]
@@ -492,15 +487,14 @@ module Tina4
               # positionally raises ArgumentError, which the rescue below
               # swallows — silently zeroing every stat. Use keyword form.
               stats = {
-                pending: queue.respond_to?(:size) ? queue.size(status: "pending") : 0,
-                completed: queue.respond_to?(:size) ? queue.size(status: "completed") : 0,
-                failed: queue.respond_to?(:size) ? queue.size(status: "failed") : 0,
-                reserved: queue.respond_to?(:size) ? queue.size(status: "reserved") : 0,
+                pending: queue.size(status: "pending"),
+                completed: queue.size(status: "completed"),
+                failed: queue.size(status: "failed"),
+                reserved: queue.size(status: "reserved"),
               }
-              jobs.concat(queue.failed.map { |j| j.merge(status: "failed") }) if queue.respond_to?(:failed)
-              jobs.concat(queue.dead_letters.map { |j| j.merge(status: "dead_letter") }) if queue.respond_to?(:dead_letters)
+              jobs = queue_jobs(topic, query_param(env, "status"))
             end
-          rescue StandardError => e
+          rescue StandardError
             # fall through to empty stats
           end
           json_response({ jobs: jobs, stats: stats })
@@ -631,10 +625,25 @@ module Tina4
         when ["GET", "/__dev/api/metrics"]
           json_response(Tina4::Metrics.quick_metrics)
         when ["GET", "/__dev/api/metrics/full"]
-          json_response(Tina4::Metrics.full_analysis)
+          # No fallback (ADR-0002). A missing or stale CLI is a 503 naming the
+          # install command, never zeros that read as a healthy codebase.
+          begin
+            json_response(Tina4::Metrics.full_analysis)
+          rescue Tina4::MetricsEngineError => e
+            json_response({ "error" => e.message }, 503)
+          end
         when ["GET", "/__dev/api/metrics/file"]
           file_path = (query_param(env, "path") || "").to_s
-          json_response(Tina4::Metrics.file_detail(file_path))
+          begin
+            json_response(Tina4::Metrics.file_detail(file_path))
+          rescue Tina4::MetricsEngineError => e
+            # A bad path is the caller's mistake (404); anything else is the
+            # engine being unavailable (503).
+            bad_path = e.message.include?("no such file") ||
+                       e.message.include?("not a file") ||
+                       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"]
@@ -805,7 +814,16 @@ module Tina4
           platform: RUBY_PLATFORM,
           debug: ENV["TINA4_DEBUG"] || "false",
           log_level: ENV["TINA4_LOG_LEVEL"] || "ERROR",
-          database: ENV["TINA4_DATABASE_URL"] || "not configured",
+          # REDACTED, not raw. Measured 2026-08-02: this served
+          # TINA4_DATABASE_URL verbatim, so GET /__dev/api/status answered any
+          # caller that could reach the debug port with the database password.
+          # It is a display field - nothing round-trips it back - so the safe
+          # form is strictly better here. (The connections EDITOR at
+          # /__dev/api/connections still returns the raw URL on purpose: it
+          # populates a form that is saved back to .env, and redacting it there
+          # would write *** into the file. That one needs an unchanged-sentinel
+          # design, in all four frameworks.)
+          database: (ENV["TINA4_DATABASE_URL"].to_s.empty? ? "not configured" : Tina4::DatabaseUrl.redact(ENV["TINA4_DATABASE_URL"])),
           db_tables: db_table_count,
           uptime: (Time.now - (defined?(@boot_time) && @boot_time ? @boot_time : (@boot_time = Time.now))).round(1),
           route_count: Tina4::Router.routes.size,
@@ -1053,6 +1071,86 @@ module Tina4
         { ok: false, error: e.message }
       end
 
+      # ── Queue panel: the list must describe the set the stats count ──
+      #
+      # Every reader below goes through Tina4::Queue.base_path / .topic_path,
+      # or through the backend itself — the SAME answers the lite backend
+      # writes to and Queue#size counts. These handlers used to re-derive the
+      # path as
+      # Dir.pwd/data/queue, which no Ruby app ever wrote to, so the topic list
+      # could not name a real topic and the job list described a store that was
+      # not the one being counted.
+      #
+      # Each job appears EXACTLY ONCE, in the bucket its OWN stat counts it in:
+      #
+      #   stats.pending   <- <base>/<topic>/*.queue-data
+      #   stats.reserved  <- <base>/<topic>/reserved/*.queue-data
+      #   stats.failed    <- <base>/dead_letter/*.queue-data tagged with topic
+      #   stats.completed <- always 0; the file backend deletes on complete
+      #
+      # so sum(stats) == jobs.length by construction on a quiescent store, and
+      # every ?status= filter returns exactly what its own stat counts.
+
+      # Topic directories in the real store. The shared dead-letter directory
+      # is a sibling of the topic directories, not a topic.
+      def queue_topics
+        base = Tina4::Queue.base_path
+        return ["default"] unless Dir.exist?(base)
+
+        topics = Dir.children(base)
+                    .select { |entry| File.directory?(File.join(base, entry)) }
+                    .reject { |entry| entry == Tina4::Queue::DEAD_LETTER_DIRNAME }
+                    .sort
+        topics.empty? ? ["default"] : topics
+      rescue StandardError
+        ["default"]
+      end
+
+      # Jobs for +topic+, optionally narrowed to one bucket.
+      def queue_jobs(topic, status_filter = nil)
+        wanted = status_filter.to_s.strip
+        topic_dir = Tina4::Queue.topic_path(topic)
+        jobs = []
+        jobs.concat(read_queue_dir(topic_dir, "pending")) if wanted.empty? || wanted == "pending"
+        if wanted.empty? || wanted == "reserved"
+          jobs.concat(read_queue_dir(File.join(topic_dir, "reserved"), "reserved"))
+        end
+        jobs.concat(queue_dead_letters(topic)) if wanted.empty? || wanted == "failed" || wanted == "dead"
+        jobs
+      end
+
+      # Read one queue directory the way Queue#size COUNTS it. size globs the
+      # files without parsing them, so a job file that cannot be parsed still
+      # counts — and must therefore still be LISTED, or the panel shows a total
+      # it cannot account for. Listing it is also the only way an operator ever
+      # learns the file is there.
+      def read_queue_dir(dir, status)
+        return [] unless Dir.exist?(dir)
+
+        Tina4::Queue.job_files(dir).filter_map do |file|
+          begin
+            JSON.parse(File.read(file)).merge("status" => status)
+          rescue JSON::ParserError
+            { "id" => File.basename(file, Tina4::Queue::JOB_EXTENSION), "status" => status,
+              "error" => "unreadable job file" }
+          rescue Errno::ENOENT
+            nil # consumed between the glob and the read
+          end
+        end
+      end
+
+      # Every dead letter for +topic+ — the same set stats.failed counts.
+      #
+      # max_retries: 0 is the established "no attempt-count filter" spelling
+      # (the `tina4ruby queue retry` command uses it for the same reason). The
+      # DEFAULT filters on the max_retries of the Queue this dev admin happened
+      # to construct, which is 3 and has nothing to do with the app's: an app
+      # configured max_retries: 1 dead-letters a job at ONE attempt, and every
+      # one of those was counted by stats.failed and never listed.
+      def queue_dead_letters(topic)
+        dev_queue(topic).dead_letters(max_retries: 0).map { |job| job.merge("status" => "dead_letter") }
+      end
+
       # ── Queue run-chips (Tier 3) ───────────────────────────────────
 
       # A file-backed dev Queue for +topic+ (matches the GET /queue handler).