rails-ai-context 5.35.1 → 5.35.2

data/docs/TOOLS.md

@@ -145,9 +145,12 @@ tables of every database the app's own schema dumps declare, as
 Cache and Solid Cable get one line, without their tables. A database whose
 dump was not read is named with "(tables not read)" and left out of the table
 count, and the summary says so: "5 tables in 2 databases, the warehouse
-database not read". It ends with the app's custom
-rake tasks (Rakefile, `lib/tasks`, `rakelib`), each with its arguments,
-description and file: the first 15 at `standard`, every one at `full`.
+database not read". It ends with the app's custom rake tasks (Rakefile,
+`lib/tasks`, `rakelib`), each with its arguments, description and file: the
+first 15 at `standard`, every one at `full`. A known limit: on
+`preset: standard` on the static tier the stack line reads the primary's
+adapter as `unknown`, and a database's heading in the generated files can name
+no adapter.
 Then the app's own generators under `lib/generators` (the `bin/rails generate`
 command and its USAGE line), the `lib/templates` files that replace a built-in
 generator's template, and the Railties under `lib/` with their initializers.
@@ -178,6 +181,14 @@ its own path, else from the other format's file under its name
 (`db/queue_schema.rb` or `db/queue_structure.sql`), whatever `database_tasks`
 or `schema_format` says.
 
+A database only another environment configures carries a mark, as in
+`cache (production only)`, and a first database that is not named `primary`
+is listed under its own name where another database is the one named
+`primary`. Both are the same under every `preset`. With the
+`multi_database` introspector off, as on `preset: standard`, `rails_get_schema`,
+`rails_onboard`, `rails_performance_check` and the generated files read them
+from the app databases list.
+
 Column hints follow the leftmost-prefix rule: `[indexed]` means some index leads
 with the column, so a lookup on it alone can use one; `[unique]` means a unique
 index covers the column alone; `[unique with x]` names the partners of a
@@ -471,7 +482,8 @@ database's name is read whatever `database_tasks` or `schema_dump` says. A
 database whose tables could not be read is listed under **Not checked** with
 the reason: its dump is not on disk or is over `max_schema_file_size`, or its
 `config/database.yml` entry turns `database_tasks` or `schema_dump` off and no
-dump is on disk. A database another environment configures carries its mark:
+dump is on disk, or "`schema_dump` in its database.yml entry names no file this
+check reads". A database another environment configures carries its mark:
 `**Not checked:** warehouse (production only, db/warehouse_schema.rb is not on disk)`.
 
 | Parameter | Type | Default | Description |
@@ -735,13 +747,13 @@ Safe read-only SQL with layered security: the SQL gate, a PostgreSQL plan check
 
 It runs on PostgreSQL, MySQL (with MariaDB) and SQLite, each with its own read-only transaction and statement timeout. On any other adapter it answers with that adapter's name and runs nothing. A statement that runs past `query_timeout` is answered as a timeout and any other database error as an SQL error. Both are error responses: `isError` over MCP and a non-zero exit on the CLI. So is a database no connection reaches, which the answer names with what to do about it. So are a locked SQLite database and the refusal in production.
 
-On PostgreSQL, MySQL and MariaDB every statement a call sends has a time limit. The query has `query_timeout` to itself and the reads beside it share a second one, so the statements of a call take about twice `query_timeout` at most. On SQLite the query has `query_timeout`, and the reads beside it run on the app's own connection with no statement limit. The [security model](SECURITY.md#layer-2---database-level-read-only) says what bounds each statement and lists the stated limits.
+On PostgreSQL, MySQL and MariaDB every statement a call sends has a time limit. The query has `query_timeout` to itself and the reads beside it share a second one, so the statements of a call take about twice `query_timeout` at most. On SQLite the query has `query_timeout`, and the reads beside it run on the app's own connection with no statement limit. A SQLite statement that names something the app's connection alone holds, such as a temp table or an attached database, runs on that connection, and its answer says it ran without a time limit. The [security model](SECURITY.md#layer-2---database-level-read-only) says what bounds each statement and lists the stated limits.
 
 On MySQL, MariaDB and SQLite a statement that names a view whose definition names a secret column is refused. So is a `*` inside a subquery when the statement names a table that holds a secret column, and on SQLite `IN` before a table's name (`x IN t`). On PostgreSQL a materialized view whose definition names a secret column is refused. On SQLite a virtual table that holds a secret column, a shadow table and the page modules are refused, and only the pragma functions that describe the schema or the database file run.
 
 The secret column rule reads the columns of every schema and database a statement reaches: the ones its text names, on PostgreSQL the ones its plan names, and the ones the views it names lead to, three reads deep. So a secret column of a table in another one is refused by name too.
 
-On MySQL and MariaDB the text checks read a backslash in a string both ways, and a statement that either reading refuses is refused. On every family the text checks give up with a refusal when they have run longer than `query_timeout`.
+On MySQL and MariaDB the text checks read a backslash in a string both ways, and a statement that either reading refuses is refused. There a `[` outside a string or a quoted name, a user variable assignment (`:=`) and `LAST_INSERT_ID` with an argument are refused too. On every family the text checks give up with a refusal when they have run longer than `query_timeout`.
 
 | Parameter | Type | Default | Description |
 |:----------|:-----|:--------|:------------|
@@ -755,7 +767,7 @@ On MySQL and MariaDB the text checks read a backslash in a string both ways, and
 
 - A name the app does not have is answered with the closest one and every name it has.
 - A database only another environment configures, a replica and one with `database_tasks` off included, is answered with the environments that do.
-- A top-level entry of `config/database.yml` that code connects to by name (`establish_connection(:reporting)`) is an environment to Rails, so `database` does not take its name: the answer lists the databases of the running environment.
+- A top-level entry of `config/database.yml` that code connects to by name (`establish_connection(:reporting)`) is an environment to Rails, so `database` does not take its name: the answer lists every database the app has, as in "No database named reporting. This app has: primary, cache, queue".
 - One that only a committed dump names is answered as such.
 - On the static tier the whole tool is unavailable, with or without `database`.
 - A SQLite database whose file is not there is an error, with or without `database`. The message starts "The <name> database does not exist yet" and names `bin/rails db:prepare`, and nothing is created. A `file:` URI is checked at the path inside it.
@@ -818,7 +830,7 @@ Each diff passes through the redaction every tool's source does, read as the fil
 
 Live database pool stats, table sizes, pending migrations, cache stats, queue depth.
 
-Table sizes come from PostgreSQL, MySQL (base tables only) and SQLite, and index usage from PostgreSQL. On MySQL, MariaDB and SQLite the full detail says "_Index usage is not available for the MySQL database family._", or SQLite. On an adapter with no database family the database section says table sizes and index usage are not available for that adapter.
+Table sizes come from PostgreSQL, MySQL (base tables only) and SQLite, and index usage from PostgreSQL. On MySQL, MariaDB and SQLite the full detail says "_Index usage is not available for the MySQL database family._", or SQLite. On an adapter with no database family the database section says table sizes and index usage are not available for that adapter. A read that failed or took longer than `query_timeout` is said in one line: "_Table sizes were not read: the read failed or took longer than query_timeout._", and at `detail: "full"` "_Index usage was not read: the read failed or took longer than query_timeout._"
 
 The pool and the cache are read inside the MCP server process, and the answer says so: the pool's counts are that process's own connections, and a `MemoryStore`'s entries are its own, since each app server process holds its own. A store the processes share (Redis, Memcached, Solid Cache, a file store) is the app's. Another environment that configures a shared store is named, as where the app's cache lives there. Solid Cache's stats are read from its database, so when that is a SQLite file that is not there, the cache section says the database does not exist yet and creates nothing.
 

data/docs/TROUBLESHOOTING.md

@@ -278,6 +278,7 @@ The SQL gate refuses write statements, file and admin functions and secret colum
 
 What a string literal holds decides some of these:
 - A write keyword or a semicolon inside a string (`WHERE note = 'please insert coin'`, `'a; b'`) is data on every database, and the query runs
+- A write after a `WITH` clause (`WITH ... INSERT INTO ...`) is named as that write: "Blocked: contains INSERT"
 - A secret column's name, `FOR UPDATE` / `FOR SHARE` or `UNION` inside a string is data on PostgreSQL only. On MySQL, MariaDB and SQLite the raw text decides and the query is refused, since no later check there would catch a quote the masking misread
 - `INTO OUTFILE` / `INTO DUMPFILE` is refused wherever it stands, inside a string too, on every database
 - A file or network function (`pg_read_file`, `LOAD_FILE`), a refused `SHOW` form (`SHOW GRANTS`) and a relation that is not read (`pg_stats`, `slow_log`) are refused wherever they stand, inside a string too, each on the database that has it. `slow_log` is refused on MySQL and MariaDB, and `pg_stats` on PostgreSQL
@@ -292,7 +293,7 @@ MySQL, MariaDB and SQLite trace no result column back to its table column, so th
 - A `*` inside a subquery, a CTE body included, when the statement names a table that holds a secret column. The message names that table and the column. The rule tests the two facts together and does not tell which table the wildcard reads, so the statement is refused also when the wildcard is over another table. Name the columns in the subquery: `WITH x AS (SELECT id, email FROM users) SELECT * FROM x`. On MySQL and MariaDB `(TABLE t)` counts as a wildcard: select the columns you need. `EXISTS (SELECT * ...)` and `count(*)` run
 - On SQLite, `IN` before a table's name (`WHERE id IN users`), when the statement names a table that holds a secret column. It is SQLite's shorthand for `IN (SELECT * FROM users)`. Write the subquery with its columns named: `WHERE id IN (SELECT id FROM users)`
 - On SQLite, either of those two in a statement that holds a string equal to such a table's name (`WHERE role = 'users'`). SQLite reads a string as a table's name where a name can stand, and the rule cannot tell that use from plain data. The message says "in a statement that holds the string 'users'". Name the columns in the subquery, or compare with another value
-- A view whose definition names a secret column, or has a wildcard and names a table that holds one. Query the tables the view reads. When the column holds no secret, list its name in `config.query_allowed_columns`
+- A view whose definition names a secret column, or has a wildcard and names a table that holds one. Query the tables the view reads. When the column holds no secret, exempt it by name as [Column values show [FILTERED]](#column-values-show-filtered) says
 
 On PostgreSQL a plain view runs and its secret columns come back `[FILTERED]`. A materialized view whose definition names a secret column gets the view message, since its stored rows cannot be traced to a table column. Query the tables it was built from.
 
@@ -306,11 +307,11 @@ On SQLite `rails_query` reads no table that holds another table's rows or words
 - An `fts5vocab` or `fts4aux` table over such a table lists its words, so it is refused too
 - A virtual table whose definition names a refused view, or a table that is not read, holds their rows or words. The message says "its definition names" and what it names
 
-A view over one of these is refused with "its definition reads `<table>`, which is not read". The name is refused inside a string too.
+A view over one of these is refused with "its definition names `<table>`, which is not read". The name is refused inside a string too.
 
 ### "Blocked: `pragma_foreign_keys` tells of the connection that runs it"
 
-On SQLite `rails_query` runs a statement on a connection of its own, so a value that belongs to a connection would not be the app's. The pragma functions that describe the schema or the database file run: `pragma_table_info`, `pragma_index_list`, `pragma_foreign_key_list`, `pragma_integrity_check`, `pragma_page_count` and the others [SECURITY.md](SECURITY.md#layer-1---the-sql-gate-statement-checks) lists. Every other `pragma_*` function is refused, and so are `changes()`, `total_changes()` and `last_insert_rowid()`. Read those on the app's own connection, in `bin/rails runner` or the console.
+On SQLite `rails_query` runs a statement on a connection of its own, so a value that belongs to a connection would not be the app's. The pragma functions that describe the schema or the database file run: `pragma_table_info`, `pragma_index_list`, `pragma_foreign_key_list`, `pragma_integrity_check`, `pragma_page_count` and the others [SECURITY.md](SECURITY.md#layer-1---the-sql-gate-statement-checks) lists. Every other `pragma_*` function is refused, and so are `changes()`, `total_changes()` and `last_insert_rowid()`. Read those on the app's own connection, in `bin/rails runner` or the console. A `pragma_*` name is refused wherever it stands, so a column whose own name starts with `pragma_` is refused too: read it in the console as well.
 
 ### "Blocked: the statement is ... bytes long"
 
@@ -318,7 +319,7 @@ On SQLite `rails_query` runs a statement on a connection of its own, so a value
 
 ### "Blocked: the checks on the statement's text ran longer than query_timeout"
 
-The checks that read a statement's text have `query_timeout` to themselves and give up when they pass it. Nothing was sent to the database. Send a shorter statement.
+The checks that read a statement's text have `query_timeout` to themselves and give up when they pass it. The statement was not sent to the database. The schema read that comes before the checks was. Send a shorter statement.
 
 ### "Blocked: ... is not queried: its columns could not be read" and "leads through more databases than rails_query follows"
 
@@ -334,12 +335,32 @@ MySQL's statement timeout does not hold a `SHOW` filter, so it is refused on eve
 
 ### "A name before a dot is read as that schema, so an alias named `sys` needs another name"
 
-On MySQL and MariaDB `mysql.` and `sys.` are read as those schemas wherever they stand outside a single-quoted string. An alias cannot be told from a schema, so `FROM users sys ... sys.id` is refused. Give the alias another name. A double-quoted string that holds `mysql.` or `sys.` is refused too, with a sentence of its own: MySQL reads double-quoted text as a name when the session's sql_mode holds `ANSI_QUOTES`. Write it in single quotes.
+On MySQL and MariaDB `mysql.` and `sys.` are read as those schemas wherever they stand outside a single-quoted string. An alias cannot be told from a schema, so `FROM users sys ... sys.id` is refused. Give the alias another name. The sentence ends every refusal over `mysql.` or `sys.` outside double-quoted text, so a real `FROM mysql.user` gets it too, with `mysql` as the name. A double-quoted string that holds `mysql.` or `sys.` is refused too, with a sentence of its own: MySQL reads double-quoted text as a name when the session's sql_mode holds `ANSI_QUOTES`. Write it in single quotes.
 
 ### "That is how MySQL reads the statement when the session's sql_mode holds NO_BACKSLASH_ESCAPES"
 
 On MySQL and MariaDB a backslash in a string is an escape, unless the session's sql_mode holds `NO_BACKSLASH_ESCAPES`. `rails_query` does not read the session's mode, so it checks the statement under both readings and refuses it when either one does. This message ends a refusal that the second reading alone gives: with `\'` read as a backslash and the end of the string, the text after it is code. Write a quote inside a string doubled (`'it''s'`), so that both readings agree.
 
+### "Blocked: a `[` outside a string or a quoted name is not run"
+
+On MySQL and MariaDB a square bracket outside a string or a quoted name is refused. MariaDB reads `[name]` as a quoted name when the session's sql_mode holds `MSSQL`, and `rails_query` does not read the session's mode, so its checks could read such a statement another way than the server does. Quote a name in backticks: `` `name` ``. A `[` inside a string, such as a JSON path (`'$[0]'`), runs. One case apart: a string that holds a backslash before a quote (`'O\'Brien'`) is read a second way that ends it at that quote, and a `[` which that reading leaves outside a string is refused. Write the quote doubled (`'O''Brien'`).
+
+### "Blocked: a user variable assignment (`:=`) is not run"
+
+On MySQL and MariaDB `SELECT @n := @n + 1` leaves `@n` set on the app's pooled connection after the query returns, and a read-only transaction does not stop that. To number rows, use a window function, which MySQL 8 and MariaDB 10.2 and later have: `SELECT ROW_NUMBER() OVER (ORDER BY id) AS n, title FROM posts`. A `:=` inside a string or a quoted name runs, unless a backslash before a quote in the statement leaves it outside a string in the second reading of a backslash: write that quote doubled.
+
+### "Blocked: LAST_INSERT_ID with an argument is not run"
+
+On MySQL and MariaDB `LAST_INSERT_ID(<value>)` sets the value the next `LAST_INSERT_ID()` returns, and it stays on the app's pooled connection after the query returns. `LAST_INSERT_ID()` with no argument runs. The call is refused wherever it stands, inside a string too.
+
+### "Blocked: a column-alias list" on a statement that has none
+
+One name in parentheses after `GLOB`, `MATCH` or `OVER` that follows a subquery has the shape of a column-alias list, so `WHERE (SELECT title FROM post_titles LIMIT 1) GLOB (title)` and `sum((SELECT 1)) OVER (w)` are refused. Write the name with no parentheses (`GLOB title`), or write the window inline (`OVER (ORDER BY id)`).
+
+### "Blocked: UNION is not run" on a statement with no UNION
+
+A quoted name that spells the word is refused, as in `SELECT 1 AS "union"`. Give the alias another name. On PostgreSQL the word inside a string is data.
+
 ### "Blocked: the setting ... is not read", "Blocked: SHOW ALL is not run" and "Blocked: SHOW takes a setting's plain name on PostgreSQL"
 
 On PostgreSQL `rails_query` reads one setting at a time, by its plain name: `SHOW work_mem`. `SHOW ALL` and a quoted name (`SHOW "work_mem"`) are refused. Six settings can hold a password or a command line that carries one and are refused: `primary_conninfo`, `ssl_passphrase_command`, `archive_command`, `restore_command`, `archive_cleanup_command` and `recovery_end_command`. So is a setting whose own name reads as a secret, such as `app.jwt_secret`.
@@ -362,7 +383,11 @@ The secret column rule reads the database's columns before any query runs. When
 
 ### "The database is locked by another connection, so the query did not run"
 
-Another connection holds a lock on the SQLite database, such as a write transaction left open in a console. Nothing ran. End that transaction and run the query again. The query waits on a lock for 80% of `query_timeout` before it answers this. A lock met while the connection opens, as on the CLI or on a server's first call, gets the same answer.
+Another connection holds a lock on the SQLite database, such as a write transaction left open in a console. Nothing ran. End that transaction and run the query again. The query waits on a lock for 80% of `query_timeout` before it answers this. A lock met while the connection opens, as on the CLI or on a server's first call, gets the same answer. A query that holds its read lock and then runs past `query_timeout` answers the timeout, also when a writer asks for the lock while it runs.
+
+### "This SQLite query ran without a time limit"
+
+On SQLite `rails_query` runs a statement in a process of its own, which it ends at `query_timeout`. That process cannot see what the app's own connection alone holds. So the statement runs on the app's connection, with this note, on an in-memory database, on a platform without `fork`, inside an open transaction, and when it needs a table, a function, a module, a collation or an encryption key only that connection has. While the connection holds a temp object or an attachment, it runs there too when it names a temp object, the `temp` schema, `sqlite_temp_master` or an attached database, or calls a pragma function (`pragma_table_info(...)`, `pragma_table_list` and the rest) or `dbstat`. A name is matched anywhere in the statement, in any letter case and inside a string too. A statement that returns rows slowly still ends a few rows after `query_timeout`. One long step cannot be ended there.
 
 ### "The reads rails_query makes before a statement ... took the whole <N> second timeout"
 
@@ -376,6 +401,8 @@ Columns whose names look secret are redacted, and a query that names one is reje
 config.query_allowed_columns = %w[secret]
 ```
 
+On a standalone install, where no initializer runs, put the name under `query_allowed_columns:` in `.rails-ai-context.yml`.
+
 ---
 
 ## Search issues

data/docs/adr/0008-query-runs-only-where-it-can-guard.md

@@ -2,7 +2,7 @@
 
 Status: accepted
 
-`rails_query` promises two guards the database itself enforces: a read-only transaction and a statement timeout. Each database server spells both differently, and some cannot give one at all, so the tool runs a statement only where it knows the spelling. A **database family** is that knowledge: one per kind of database, read from the adapter's name in the database's configuration before any connection opens, and the only place a database's read-only and timeout rules live.
+`rails_query` promises two guards the database itself enforces: a read-only transaction and a statement timeout. Each database server spells both differently, and some cannot give one at all, so the tool runs a statement only where it knows the spelling. A **database family** is that knowledge: one per kind of database, told by the adapter's name, and the only place a database's read-only and timeout rules live. `rails_query` reads the name from the database's configuration, before any connection opens.
 
 ## Decision
 
@@ -12,7 +12,7 @@ Status: accepted
   - PostgreSQL: `SET LOCAL statement_timeout` inside the read-only transaction, at one millisecond or more, since zero turns the timeout off.
   - MySQL: the session's `max_execution_time`, read first, set for the statement and restored after. The `MAX_EXECUTION_TIME` hint binds only the outermost SELECT and leaves a statement that starts with WITH or EXPLAIN with no bound, so it is not used.
   - MariaDB: the session's `max_statement_time`, read first, set for the statement and restored after. MariaDB ignores the MySQL hint and has no `max_execution_time`.
-  - SQLite: a forked child with a deadline, since sqlite3-ruby holds the interpreter lock while a statement steps and nothing in the process can end it. A statement the child cannot prepare runs on the app's own connection, where a watchdog's interrupt ends one that returns rows slowly.
+  - SQLite: a forked child with a deadline, since sqlite3-ruby holds the interpreter lock while a statement steps and nothing in the process can end it. A statement runs on the app's own connection in five cases: an in-memory database, a platform without `fork`, a statement the child cannot prepare, a transaction open on that connection, and, while that connection holds a temp object or an attachment, a statement that names one of them, the temp catalog or schema, or calls a pragma function or `dbstat`. There a watchdog's interrupt ends a statement that returns rows slowly.
 - What bounds each kind of statement a call sends:
   - The query and `explain: true` have `query_timeout` to themselves: `statement_timeout` on PostgreSQL, the session's statement limit with `lock_wait_timeout` on MySQL and MariaDB, the child's deadline on SQLite.
   - The reads beside the query (the schema, the PostgreSQL plan with its `pg_proc` lookup, the column trace) run in a block the family bounds the same way. They share a second `query_timeout`, and each is charged the time it ran. On SQLite they run on the app's own connection with no statement limit, and a wait on another writer ends at its busy timeout.
@@ -24,7 +24,7 @@ Status: accepted
   - MySQL's statement limit holds `SELECT` only, so the gate refuses `SHOW` with a `WHERE` clause on every family.
 - A timeout is recognised by `ActiveRecord::QueryAborted` (QueryCanceled, StatementTimeout) or by the database's native code. MariaDB's 1969 has no Rails class in any version. Message text is never read, so a missing column named "timeout" is reported as an SQL error.
 - The statement checks before execution stay on every family. MySQL's read-only transaction lets `FOR SHARE`, `LOCK IN SHARE MODE`, `INTO @var` and `INTO OUTFILE` through, so it cannot be the only guard.
-- Only PostgreSQL traces a result column to its table column, through the statement's plan, so there a statement runs only with a plan. MySQL, MariaDB and SQLite have no such trace. There a view is checked by the definition the database stores and refused when it names a secret column, and a `*` inside a subquery is refused when the statement names a table that holds one.
+- Only PostgreSQL traces a result column to its table column, through the statement's plan, so there a statement runs only with a plan. MySQL, MariaDB and SQLite have no such trace. There a view is checked by the definition the database stores and refused when it names a secret column, and a `*` inside a subquery is refused when the statement names a table that holds one. A PostgreSQL materialized view stores its rows, so the plan traces none of its columns either, and it is held to the same view rule.
 - A guarded read leaves an open transaction as it found it: a savepoint on PostgreSQL, and a refusal on MySQL and MariaDB, which cannot make an open transaction read-only.
 
 ## Consequences

data/lib/rails_ai_context/database_family/mysql_runtime.rb

@@ -20,9 +20,8 @@ module RailsAiContext
       REPLACED = "the connection was replaced before the statement was sent, and the new session has no " \
         "read-only transaction and no time limit, so the statement was not sent"
 
-      # The statement limit does not cover SHOW, so lock_wait_timeout (whole seconds) ends a wait on a
-      # metadata lock. Both session values are read first and put back after the block.
-      # Yields the id of the session that holds them.
+      # The statement limit does not cover SHOW, so lock_wait_timeout (whole seconds) ends a wait on a metadata lock.
+      # Both session values are put back after the block, which is given the id of the session that holds them.
       def bounded(conn, timeout)
         limit, value = if conn.mariadb? then [ "max_statement_time", [ timeout.to_f, 0.001 ].max ]
         else [ "max_execution_time", [ (timeout * 1000).to_i, 1 ].max ]

data/lib/rails_ai_context/database_family/postgresql_plan.rb

@@ -16,6 +16,8 @@ module RailsAiContext
       SYSTEM_SCHEMA = /\A(?:pg_catalog|information_schema|pg_toast(?:_temp_\d+)?)\z/
 
       APPENDS = [ "Append", "Merge Append" ].freeze
+      REMOTE_NAME = /"(?:""|[^"])+"|[^\s()."]+/
+      REMOTE_RELATION = /\((?:(#{REMOTE_NAME})\.)?(#{REMOTE_NAME})(?: (#{REMOTE_NAME}))?\)/
 
       # aliases: alias => the relations it stands for, each as `schema.relation` where the plan gives a schema that is no system one.
       attr_reader :nodes, :aliases
@@ -25,17 +27,19 @@ module RailsAiContext
         @top = top
         @nodes = []
         @parents = {}.compare_by_identity
+        @appended = {}.compare_by_identity
         collect(top)
         # The alias defaults to the relation name when the query gave none, which is how `users.*` resolves.
         # Keyed as EXPLAIN prints it: `t` and "T" are two aliases.
         @names = {}
         @aliases = @nodes.each_with_object({}) do |node, map|
-          rel = node["Relation Name"] or next
-          key = [ (node["Schema"] unless node["Schema"].to_s.match?(SYSTEM_SCHEMA)), rel ].compact.join(".").downcase
-          @names[key] = rel.to_s.downcase
-          as = (node["Alias"] || rel).to_s
-          # The members of an Append over partitions are `name_1`, `name_2`, and a node over them names their columns by `name`.
-          [ as, as[/\A(.+)_\d+\z/m, 1] ].compact.each { |name| (map[name] ||= []) << key }
+          scanned(node).each do |schema, rel, as|
+            key = [ (schema unless schema.to_s.match?(SYSTEM_SCHEMA)), rel ].compact.join(".").downcase
+            @names[key] = rel.downcase
+            # The members of an Append over partitions are `name_1`, `name_2`, and a node over them names their columns by `name`.
+            # Anywhere else `name_1` is the plan's own name for a second use of `name`, which stands for another relation.
+            [ as, (as[/\A(.+)_\d+\z/m, 1] if @appended[node]) ].compact.each { |name| (map[name] ||= []) << key }
+          end
         end
         @aliases.each_value(&:uniq!)
       end
@@ -48,15 +52,13 @@ module RailsAiContext
       # @return [Array<Array(String, String)>] [schema, `schema.relation`] for each relation the plan reads
       #   outside the system schemas
       def relations
-        @nodes.filter_map do |node|
-          schema = node["Schema"]
-          [ schema, "#{schema}.#{node["Relation Name"]}".downcase ] if schema && node["Relation Name"] && !schema.match?(SYSTEM_SCHEMA)
+        @nodes.flat_map { |node| scanned(node) }.filter_map do |schema, rel, _as|
+          [ schema, "#{schema}.#{rel}".downcase ] if schema && !schema.match?(SYSTEM_SCHEMA)
         end.uniq
       end
 
-      # The expressions that can stand at each result column: entry i is result column i, with any sort or group key
-      # past the result width. An Append prints no Output, and each of its members hands up a row of its own.
-      # @return [Array<Array<String>>]
+      # @return [Array<Array<String>>] the expressions that can stand at result column i, with any sort or group key
+      #   past the result width. An Append prints no Output, and each of its members hands up a row of its own.
       def output
         return Array(@top["Output"]).map { |expr| [ expr ] } if @top.key?("Output") || !APPENDS.include?(@top["Node Type"])
 
@@ -67,11 +69,11 @@ module RailsAiContext
         members.all? { |member| member["Relation Name"] } && columns.size == 1 ? outputs.transpose : []
       end
 
-      # @return [Array<Array(String, String)>] [relation, column], downcased, for a plain Var of a base relation:
-      #   one for each relation its alias stands for
+      # @return [Array<Array(String, String)>] [relation, column] for a plain Var of a base relation, the column
+      #   folded as the secret column rule folds a name: one for each relation its alias stands for
       def base_columns(expr)
         m = expr.to_s.strip.match(BASE_VAR) or return []
-        column = (m[3] || m[4].gsub('""', '"')).downcase
+        column = SecretColumns.fold(m[3] || m[4].gsub('""', '"'))
         Array(aliases[m[1] || m[2].gsub('""', '"')]).map { |rel| [ rel, column ] }
       end
 
@@ -89,11 +91,24 @@ module RailsAiContext
 
       private
 
+      # [schema, relation, alias] of each relation the node scans. A join or an aggregate that a foreign server runs has
+      # no relation of its own: postgres_fdw names its tables there, each with its alias, as `(schema.table alias)`.
+      def scanned(node)
+        rel = node["Relation Name"]
+        return [ [ node["Schema"], rel.to_s, (node["Alias"] || rel).to_s ] ] if rel
+
+        node["Relations"].to_s.scan(REMOTE_RELATION).map do |parts|
+          schema, name, as = parts.map { |part| part&.delete_prefix('"')&.delete_suffix('"')&.gsub('""', '"') }
+          [ schema, name, as || name ]
+        end
+      end
+
       def collect(node, parent = nil)
         return unless node.is_a?(Hash)
 
         @nodes << node
         @parents[node] = parent
+        @appended[node] = true if parent && (@appended[parent] || APPENDS.include?(parent["Node Type"]))
         Array(node["Plans"]).each { |child| collect(child, node) }
       end
 

data/lib/rails_ai_context/database_family/postgresql_runtime.rb

@@ -116,12 +116,12 @@ module RailsAiContext
         schemas.empty? ? "n.nspname = ANY (current_schemas(false))" : "#{SCHEMA} IN (#{schemas.map { |name| conn.quote(name) }.join(", ")})"
       end
 
-      # Every relation that stores rows: tables, partitioned tables, materialized views and foreign tables.
+      # Every relation a plan can name that stores rows: tables, partitioned tables, materialized views, foreign tables and sequences.
       # One read that takes no lock on any of them.
       def relation_columns(conn, schemas = [])
         rows = conn.select_rows(
           "SELECT #{SCHEMA}, c.relname, a.attname FROM pg_attribute a JOIN pg_class c ON c.oid = a.attrelid " \
-          "JOIN pg_namespace n ON n.oid = c.relnamespace WHERE c.relkind IN ('r', 'p', 'm', 'f') AND a.attnum > 0 " \
+          "JOIN pg_namespace n ON n.oid = c.relnamespace WHERE c.relkind IN ('r', 'p', 'm', 'f', 'S') AND a.attnum > 0 " \
           "AND NOT a.attisdropped AND #{in_schemas(conn, schemas)} ORDER BY c.relname, a.attnum"
         )
         rows.each_with_object({}) do |(schema, relation, column), found|

data/lib/rails_ai_context/database_family/sqlite_runtime.rb

@@ -16,7 +16,7 @@ module RailsAiContext
 
       # What the child writes where a result's length would stand, the moment it meets a lock.
       MET_LOCK = [ (1 << 64) - 1 ].pack("Q>").freeze
-      # What it writes once the statement is prepared: the schema is read, so a lock met on the way there is behind it.
+      # What it writes once it holds its read lock: no lock can stop the statement from there on.
       PAST_LOCK = [ (1 << 64) - 2 ].pack("Q>").freeze
       WAITS_ON_LOCK = { MET_LOCK => true, PAST_LOCK => false }.freeze
 
@@ -33,7 +33,7 @@ module RailsAiContext
       def read_only(conn, sql, timeout)
         deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
         # A child opens the file itself and would answer without the rows of a transaction open here.
-        if !conn.transaction_open? && (path = fork_path(conn))
+        if !conn.transaction_open? && (path = fork_path(conn)) && !DatabaseFamily.bounding { held_here?(conn, sql) }
           result = in_child(conn, path, sql, deadline)
           return Rows.new(result.columns, result.rows, false) if result
         end
@@ -42,6 +42,21 @@ module RailsAiContext
         Rows.new(result.columns, result.rows, true)
       end
 
+      # The temp catalog, the temp schema, and a pragma function or dbstat: each reads any schema, by a name that can be put
+      # together as the statement runs.
+      CONNECTION_CATALOG = /(?<![\w$])(?:sqlite_temp_(?:master|schema)|temp["`'\]]?\s*\.|pragma_\w|dbstat(?![\w$]))/i
+
+      # Whether the statement names what the connection holds and a child would answer wrongly: a temp object, the temp schema or
+      # an attached database, in a string too. A table only an attached database holds needs no match: no child can prepare it.
+      def held_here?(conn, sql)
+        # Neither read waits on another connection's lock, which the pragma function for the same list does.
+        names = conn.select_rows("PRAGMA database_list").filter_map { |_seq, name, _file| name unless OWN_SCHEMAS.include?(name) } +
+          conn.select_values("SELECT name FROM sqlite_temp_master")
+        return false if names.empty?
+
+        sql.match?(CONNECTION_CATALOG) || SecretColumns.fold(sql).match?(Regexp.union(names.map { |name| SecretColumns.identifier(name) }))
+      end
+
       # The watchdog's interrupt lands when the driver is back in Ruby between two rows, so it ends a
       # statement that returns rows slowly and cannot end one long step: the run counts as unbounded.
       def on_app_connection(conn, sql, deadline)
@@ -184,7 +199,7 @@ module RailsAiContext
 
       # pragma_table_list, which types a shadow table, came with this version.
       TYPED_TABLES = "3.37"
-      VOCABULARY = /\bUSING\s+["'`\[]?(fts5vocab|fts4aux)\b["'`\]]?\s*\((.*)\)/mi
+      VOCABULARY = /\A\s*USING\s+["'`\[]?(fts5vocab|fts4aux)\b["'`\]]?\s*\((.*)\)/mi
 
       # Modules that return the database file's pages or cells, whatever table they belong to.
       PAGE_MODULES = %w[sqlite_dbpage sqlite_dbdata sqlite_dbptr].freeze
@@ -193,7 +208,8 @@ module RailsAiContext
       def index_tables(conn, schemas = [])
         tables = ->(kept) { across(schemas) { |schema, _| "SELECT name, sql FROM #{schema}.sqlite_master WHERE type = 'table' AND rootpage #{kept}" } }
         virtual = conn.select_rows(tables.call("= 0")).to_h
-        stored = if conn.database_version >= TYPED_TABLES then conn.select_values("SELECT name FROM pragma_table_list WHERE type = 'shadow'")
+        stored = if conn.database_version >= TYPED_TABLES
+          conn.select_values(across(schemas) { |_, name| "SELECT name FROM pragma_table_list WHERE type = 'shadow' AND schema = #{name} COLLATE NOCASE" })
         else conn.select_rows(tables.call("> 0")).map(&:first)
         end
         found = stored.each_with_object(PAGE_MODULES.to_h { |name| [ name, [ :pages, nil ] ] }) do |name, tables|
@@ -201,14 +217,24 @@ module RailsAiContext
           tables[name] = [ :shadow, owner ] if owner
         end
         virtual.each do |name, sql|
-          mod, args = sql.to_s.match(VOCABULARY)&.captures
+          clause = module_clause(SqlGate.comment_free(sql.to_s, SQLITE))
+          mod, args = clause.match(VOCABULARY)&.captures
           # fts5vocab([schema,] table, type) and fts4aux([schema,] table).
-          names = args.to_s.split(",").map { |arg| arg.strip.delete(%q('"`[])) }
-          found[name] = mod ? [ :vocabulary, mod.casecmp?("fts4aux") ? names.last : names[-2], sql ] : [ :virtual, name, sql ]
+          names = args.to_s.scan(SecretColumns::MODULE_ARGUMENT).map { |arg| arg.strip.delete(%q('"`[])) }
+          found[name] = mod ? [ :vocabulary, mod.casecmp?("fts4aux") ? names.last : names[-2], clause ] : [ :virtual, name, clause ]
         end
         found
       end
 
+      # What a virtual table's definition says after the table's own name: `USING module(arguments)`.
+      # SQLite stores it from the name on, and a quoted name can hold the word USING.
+      def module_clause(sql)
+        scanner = SqlGate::Scanner.new(sql)
+        scanner.skip(/\s*CREATE\s+VIRTUAL\s+TABLE\s+/i)
+        SqlGate.quoted(scanner, SQLITE) || scanner.skip(/[^\s"'`\[]+/)
+        scanner.rest
+      end
+
       def table_sizes(conn)
         # dbstat lists every b-tree, indexes and SQLite internals too.
         app_tables = conn.select_values("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'").to_set
@@ -277,8 +303,11 @@ module RailsAiContext
         payload = begin
           db = SQLite3::Database.new(path, readonly: true, extensions: extensions)
           wait_on_lock(db, writer, timeout * 0.8)
-          stmt = db.prepare(sql)
+          # A read inside a transaction keeps its lock, so the statement itself never waits on one.
+          db.execute("BEGIN")
+          db.execute("SELECT 1 FROM sqlite_master LIMIT 1")
           writer.write(PAST_LOCK)
+          stmt = db.prepare(sql)
           [ :ok, stmt.columns, stmt.to_a ]
         rescue => e
           # Which step failed is the child's own fact; the message can hold text from the statement.
@@ -293,9 +322,8 @@ module RailsAiContext
         exit!(0)
       end
 
-      # Waits on a lock for the seconds given, under the deadline, so a database that stays locked is answered as
-      # locked before the parent stops waiting. The parent is told at the first wait: a child that started late
-      # is still waiting when the deadline passes.
+      # Gives up under the deadline, so the child answers a database that stays locked. The parent is told at
+      # the first wait, for a child that started late and is still waiting at the deadline.
       def wait_on_lock(db, writer, seconds)
         met = nil
         db.busy_handler do |count|

data/lib/rails_ai_context/database_family.rb

@@ -56,6 +56,11 @@ module RailsAiContext
         postgresql?
       end
 
+      # A block comment inside a block comment needs a closer of its own.
+      def nested_comments?
+        postgresql?
+      end
+
       # `/*! ... */` holds text the database runs.
       def executable_comments?
         mysql?
@@ -100,8 +105,8 @@ module RailsAiContext
         runtime.column_sources(connection, sql, plan)
       end
 
-      # Every schema read below takes the schemas to read. With none it reads what a statement reaches with
-      # no schema named: the PostgreSQL search path, the MySQL connection's database, SQLite's main and temp.
+      # A schema read that is given no schemas reads at least what a statement reaches with no schema named:
+      # the PostgreSQL search path, the MySQL connection's database, SQLite's main and temp.
 
       # @return [Array<String>] the schemas a statement reaches with no schema named, where the reads' own
       #   default does not cover them: SQLite's attached databases
@@ -137,9 +142,8 @@ module RailsAiContext
         runtime.generated_columns(connection, schemas)
       end
 
-      # @return [Hash{String => Array(Symbol, String)}] table => [:pages, :shadow, :vocabulary or :virtual, the virtual
-      #   table it belongs to]: what holds another table's rows or words under other names. A virtual table and a
-      #   vocabulary also carry their definition.
+      # @return [Hash{String => Array}] what holds another table's rows or words under other names: table =>
+      #   [:pages, :shadow, :vocabulary or :virtual, its virtual table, and for the last two kinds their definition]
       def index_tables(connection, schemas = [])
         runtime.index_tables(connection, schemas)
       end

data/lib/rails_ai_context/introspectors/declared_constant.rb

@@ -105,17 +105,29 @@ module RailsAiContext
         one.delete("_").casecmp?(other.delete("_"))
       end
 
-      # A loaded class that answers a name no constant carries belongs to no
-      # file - Rails names the anonymous join class it builds for a
-      # has_and_belongs_to_many through a singleton `name=`, so it answers
-      # "HABTM_Tags" while it lives at "Account::HABTM_Tags". Keyed by that
-      # name it would overwrite the real entry, or collapse two owners of one
-      # association name onto one.
+      # A loaded class that answers a name no constant carries belongs to no file: the join class Rails names
+      # "HABTM_Tags" through a singleton `name=`, or a class whose constant was removed and is not yet collected.
       #
       # @param klass [Class] a loaded class
       # @return [Boolean]
       def renamed?(klass)
-        klass.name != klass.to_s
+        scope = Object
+        klass.name.to_s.split("::").each do |part|
+          return true unless scope.const_defined?(part, false)
+          # Asking loads no file: a constant still waiting to autoload is taken to name the class.
+          return false if scope.autoload?(part, false)
+
+          scope = scope.const_get(part, false)
+        end
+        !scope.equal?(klass)
+      rescue NameError
+        # A name that is no constant path, or a path through a value that is no module.
+        true
+      end
+
+      # The loaded classes among these that their own constants still name.
+      def carried(classes)
+        classes.reject { |klass| renamed?(klass) }
       end
 
       # @return [Boolean] whether the source declares a class at all. A file

data/lib/rails_ai_context/introspectors/job_introspector.rb

@@ -79,10 +79,10 @@ module RailsAiContext
         JOB_DIRS.each { |kind| EagerLoad.dir(app.root, kind: kind) }
 
         ActiveJob::Base.descendants.filter_map do |job|
-          next if job.name.nil? || job.name == "ApplicationJob" ||
+          next if job.name.nil? || job.name == "ApplicationJob" || DeclaredConstant.renamed?(job) ||
                   job.name.start_with?("ActionMailer", "ActiveStorage::", "ActionMailbox::", "Turbo::", "Sentry::")
           next unless app_defined?(job)
-          if SuperclassChain.abstract_base?(job.name, inherited: job.descendants.any?)
+          if SuperclassChain.abstract_base?(job.name, inherited: DeclaredConstant.carried(job.descendants).any?)
             reflected_bases << { name: job.name, file: source_file_for(job), active_job: true }
             next
           end
@@ -743,7 +743,7 @@ module RailsAiContext
       def booted_mailer_base(mailer)
         file = source_file_for(mailer)
         source = file && SafeFile.read(File.join(app.root.to_s, file))
-        heirs = mailer.descendants.filter_map(&:name)
+        heirs = DeclaredConstant.carried(mailer.descendants).map(&:name)
         return { name: mailer.name, file: file, inherited_by: heirs.sort.presence }.compact unless source
 
         walked = SourceIntrospector.walk_source(source, {
@@ -765,7 +765,7 @@ module RailsAiContext
         ActionMailer::Base.descendants.filter_map do |mailer|
           # `descendants` is every mailer in the process, and a gem's is not
           # the app's however it is named.
-          next if mailer.name.nil? || !app_defined?(mailer)
+          next if mailer.name.nil? || DeclaredConstant.renamed?(mailer) || !app_defined?(mailer)
 
           # Reflection with the app-base subtraction: `action_methods` stops
           # subtracting at the framework base, so a public helper on a
@@ -776,7 +776,7 @@ module RailsAiContext
           )
           # A base other mailers inherit from is where the helpers they share
           # live. Rails dispatches on those, and no reader sends one.
-          if SuperclassChain.abstract_base?(mailer.name, inherited: mailer.descendants.any?)
+          if SuperclassChain.abstract_base?(mailer.name, inherited: DeclaredConstant.carried(mailer.descendants).any?)
             bases << booted_mailer_base(mailer)
             next
           end
@@ -1279,7 +1279,7 @@ module RailsAiContext
         EagerLoad.dir(app.root, kind: "app/channels")
 
         ActionCable::Channel::Base.descendants.filter_map do |channel|
-          next if channel.name.nil? || channel.name == "ApplicationCable::Channel"
+          next if channel.name.nil? || channel.name == "ApplicationCable::Channel" || DeclaredConstant.renamed?(channel)
 
           file = source_file_for(channel)
           macros = channel_sources.find { |klass| klass.file == file }&.macros ||

data/lib/rails_ai_context/introspectors/model_introspector.rb

@@ -629,10 +629,9 @@ module RailsAiContext
             next unless klass < ActiveRecord::Base && !klass.abstract_class?
             models << klass
             known << class_name
-          rescue NameError, LoadError, ScriptError => e
-            # A syntax-broken file costs itself, not the whole listing, but
-            # its name is recorded: a file that exists for a class reflection
-            # lacks is not the same answer as no such model.
+          rescue StandardError, ScriptError => e
+            # A file that raises as it loads costs itself alone, and its name is recorded:
+            # a file that exists for a class reflection lacks is no missing model.
             @unloadable[class_name] = e.message.to_s.lines.first.to_s.strip
             @outside_model_dirs << class_name unless model_dir_file?(record.path)
           end
@@ -987,7 +986,7 @@ module RailsAiContext
         bases = abstract_bases(model)
         return bases unless model.superclass == ActiveRecord::Base
 
-        bases | ActiveRecord::Base.subclasses.select { |klass| klass.name && klass.abstract_class? }
+        bases | DeclaredConstant.carried(ActiveRecord::Base.subclasses).select(&:abstract_class?)
       end
 
       def every_model_modules
@@ -1137,13 +1136,7 @@ module RailsAiContext
 
         return nil unless has_type_column
 
-        children = if model.respond_to?(:descendants)
-          model.descendants.map(&:name).compact.sort
-        elsif model.respond_to?(:subclasses)
-          model.subclasses.map(&:name).compact.sort
-        else
-          []
-        end
+        children = DeclaredConstant.carried(model.descendants).map(&:name).sort
 
         parent = model.superclass
         sti_parent = if parent && parent != ActiveRecord::Base &&