omen 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5c61b5e791393a47ef018d36fba4ab6455147fd7789e9ad9da2dfa3f4a3c233
-  data.tar.gz: 0ad45e83dfa5a5271acdd9c1a99741dcd360eb3d520f5b6ffe3b81d383e39152
+  metadata.gz: '0439ba57f67515df5b1685bb241e7c8d904f7039b3c349a45add84eaec5b6330'
+  data.tar.gz: 125790550dbc3c82b2a139c4a09fc1767ea6776ce984357aa40841e397adef38
 SHA512:
-  metadata.gz: dbe0dcd9d8dbe1e272b5a9f4d600631c4fa3efca709d80ea71aab1c1212317b462ce516c96d0b18292e2364792bb2167de86a9fb9b9de5cd64f97d4861e55821
-  data.tar.gz: 2fad605e52e97a599c01b842f2e00df7dc77827f1f7c7cfc22eb340101c038857e081766c90739da17c1ee3f3b469627442406c2b6c4d80984008cb0aef0847f
+  metadata.gz: 3123b62849d8a61bdd7264aa1eba6a13fe0bc8b5225be52cd4d5633840b5117181dca928c1ed21e6a26b54d45650f39037221cedfe8f95f7af1b5047b1523dae
+  data.tar.gz: 6e1a011344a1ec0cb7c09657a8bdfa40159de13f4d65f892f6a23cba5ce965959224fe8c4bd4585d68d82290773035e439c0eb4ec47bf428e6f0e2814890f251

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+For more information about changelogs, check [Keep a Changelog](http://keepachangelog.com) and
+[Vandamme](http://tech-angels.github.io/vandamme).
+
+## [Unreleased]
+
+* [Fix] Point RubyGems at the API reference, so a gem page and a gem listing say the same
+  thing about where the documentation is
+
+## 0.2.0 - 2026-08-21
+
+* [Feature] Ask Claude a question about an app's own data, and run the SQL it writes against a
+  read-only connection: three models, the prompt, the narrow role and the function a timestamp
+  is read through, an install generator, and no controllers, routes or views
+
+## 0.1.0 - 2026-08-21
+
+* [Feature] An engine that loads and does not do anything yet

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 HouseAccount
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -6,9 +6,8 @@ Omen ships the models and the logic to talk to Claude, parse what it says back,
 statement it wrote against a read-only connection. It ships **no controllers, routes or views** —
 the pages belong to the app that installs it.
 
-> **0.1.0 does nothing yet.** This release loads as a Rails engine. The models
-> and the Claude logic land in a later version. The requirements below are what it will need, and
-> are stated now so nobody installs it into an app it cannot work in.
+The rows never travel. Claude is shown the schema and writes one `SELECT`; Rails runs it and
+draws the answer for whoever asked. Nothing that statement returned is ever sent back.
 
 ## How to install
 
@@ -19,7 +18,7 @@ gem install omen
 Or, in a `Gemfile`, pinned to the current major:
 
 ```ruby
-gem 'omen', '~> 0.1'
+gem 'omen', '~> 0.2'
 ```
 
 Omen follows [Semantic Versioning](https://semver.org), so `~> major.minor` means `bundle update`
@@ -33,14 +32,114 @@ and column number Postgres reports for each result column, which is what stops a
 expression from laundering one; and it narrows privileges for the statement it runs with
 `SET LOCAL ROLE`, which reverts when the transaction ends. MySQL has `SET ROLE` but nothing
 transaction-scoped, so a raised exception would leave a pooled connection holding the role. Omen
-raises on any other adapter rather than running with a weaker promise.
+raises at boot on any other adapter rather than running with a weaker promise.
 
 **`db/schema.rb`, in Rails' `:ruby` schema format.** The schema is what Claude is shown, so an app
-on `db/structure.sql` cannot use Omen. This is checked at boot rather than left to fail later.
+on `db/structure.sql` cannot use Omen. Checked at boot and raised on, because copying a
+`structure.sql` to that path fails silently and with teeth: the strip regexes read the Ruby DSL,
+so they match nothing, Omen's own tables stay in the prompt, and Claude is shown the log of every
+question ever asked.
 
-**A read-only connection.** Omen runs every statement through a Rails connection role that cannot
-write, and raises rather than falling back to a writable one.
+**Eastern time.** A stored timestamp is read through an `eastern()` function the rake task
+creates, and every date the prompt asks Claude to reason about is a date in `America/New_York`.
+An app that works in another zone has to say so in the function and rename it.
+
+## Configuration
+
+Installing is three commands and, if you want to change anything, one file.
+
+### The steps
+
+```sh
+bin/rails generate omen:install   # three migrations, and an initializer you may delete
+bin/rails db:migrate
+bin/rails db:omen:grant           # the role a statement runs as, and the function it reads a
+                                  # timestamp through
+```
+
+`db:omen:grant` is worth running from the tasks that build a database, so a fresh one is never
+missing the role. In `lib/tasks` of the host:
+
+```ruby
+granted = Rake::Task['db:omen:grant']
+
+%w[ db:create db:prepare db:reset db:test:prepare ].each do |name|
+  Rake::Task[name].enhance do
+    granted.reenable
+    granted.invoke
+  end
+end
+```
+
+### What the app around it has to provide
+
+Configuration is optional. Installation is not: four of these are the app's, and Omen cannot
+supply any of them.
+
+- **A read-only connection role.** `connects_to database: { writing: :primary, reading: :reader }`
+  on the record class, with the `reading` entry logging in as a Postgres role granted `SELECT`
+  and nothing else. Omen raises rather than falling back to a role that could write, which is
+  the point. Creating that role is the app's own business — Omen has no name for it, and
+  discovers it when granting.
+- **Active Record Encryption keys.** Without them an encrypted column reads back as the
+  placeholder rather than as the value, quietly.
+- **An `ApplicationJob`.** A reading is answered outside the request, and the job descends
+  from the app's own base class.
+- **A `db/schema.rb`.** It is the prompt, so a reading cannot happen before the first
+  `db:migrate` has dumped one.
+
+### The options
+
+Every setting has a default, so the initializer is optional. `rails generate omen:install`
+writes it with each line commented out, as the list of what there is to say.
+
+| Setting | Default |
+|---|---|
+| `record_class` | `'ApplicationRecord'`, falling back to `ActiveRecord::Base` |
+| `reading_role` | `:reading` |
+| `narrow_role` | `'omen_inquirer'` |
+| `claude_model` | `'claude-opus-5'` |
+| `maximum_rows` | `100` |
+| `api_key` | unset, so the Anthropic SDK resolves `ANTHROPIC_API_KEY` and its wider chain |
+| `notes` | none, so the prompt says nothing about this app beyond its schema |
+| `schema_path` | `'db/schema.rb'` |
+
+## What a host builds on top
+
+`Omen::Reading` has a `type` column nowhere, so a subclass is a transparent second name for the
+same rows: `Inquiry.all` carries no type condition, and `to_partial_path` becomes
+`inquiries/inquiry`.
+
+```ruby
+class Inquiry < Omen::Reading
+  belongs_to :agent
+end
+```
+
+`Omen::Reading.create! question: 'Where are the homes we serve?'` is the whole of asking; a
+follow-up is `reading.ask '...'`. Each question is answered in a job, and the answer carries the
+statement Claude wrote, the rows it found, and which header of theirs held an encrypted column.
+
+Two things a subclass cannot reach, because the gem's own class is what a job loads:
+`broadcasts_refreshes`, and anything else that has to be declared on `Omen::Reading` itself. One
+line in the host does it:
+
+```ruby
+Rails.application.config.to_prepare { Omen::Reading.broadcasts_refreshes }
+```
+
+## After the first deploy
+
+The narrow role is granted `SELECT` on every table and then refused Omen's own three, which can
+only happen once those tables exist. On a database that forbids `CREATE ROLE` — a managed one
+usually does — the role is made by hand and the revocation with it:
+
+```sql
+REVOKE SELECT ON omen_readings, omen_questions, omen_answers FROM omen_inquirer;
+```
+
+A missed table there means Claude is shown the log of every question ever asked.
 
 ## License
 
-MIT, see [MIT-LICENSE](MIT-LICENSE).
+MIT, see [LICENSE.txt](LICENSE.txt).

data/app/models/omen/answer.rb

@@ -0,0 +1,37 @@
+# What Claude said back: the prose, the statement it wrote, and the rows that statement found.
+class Omen::Answer < Omen.config.record
+  include Omen::Revealed, Omen::Spoken
+
+  # A \uXXXX escape that outlived JSON.parse, because Claude escaped the backslash of its own.
+  UNICODE_ESCAPE = /\\u([0-9a-fA-F]{4})/
+
+  belongs_to :question
+
+  # @return [String] the side of the conversation this was said on, in the words the API uses.
+  def role = 'assistant'
+
+  # A reply cut short is not JSON at all, and reads as an answer with nothing in it.
+  # @return [Hash] the reply, parsed.
+  def answer
+    @answer ||= JSON.parse text
+  rescue JSON::ParserError
+    @answer = {}
+  end
+
+  # @return [Boolean] whether the reply ran out of room, leaving JSON that will not parse.
+  def cut_off? = stop_reason == 'max_tokens'
+
+  # @return [String] the one SELECT Claude wrote, which is empty when it asked instead.
+  def sql = answer['sql'].to_s
+
+  # Decoded here and never in #sql, where a \u may be a literal the statement means to carry.
+  # @return [String] what Claude said about the query, or the question it needs answered first.
+  def note = answer['note'].to_s.gsub(UNICODE_ESCAPE) { $1.hex.chr Encoding::UTF_8 }
+
+  # @return [Array<Hash>] the columns Claude asked to be drawn as their parts joined.
+  def combine = Array answer['combine']
+
+  # The query asks for one row past the cap, so the page can say there are more without counting.
+  # @return [Boolean] whether the answer ran past what is shown.
+  def truncated? = result.size > Omen.config.maximum_rows
+end

data/app/models/omen/asked.rb

@@ -0,0 +1,10 @@
+# Extends Omen::Reading with the way a question is added to it.
+module Omen::Asked extend ActiveSupport::Concern
+  # Records what was typed, which is what sets a run going.
+  # @param question [String] what the asker wants to know.
+  # @return [Omen::Question] the question that was added.
+  def ask(question) = questions.create! content: [ { type: 'text', text: question } ]
+
+  # @return [Boolean] whether Claude is still working on the last question.
+  def answering? = (unstarted? || started?) && fresh?
+end

data/app/models/omen/column.rb

@@ -0,0 +1,60 @@
+# One column of the schema that Rails encrypts before the database is allowed to store it.
+class Omen::Column
+  # What stands in for a value this class will not hand over in the clear.
+  HIDDEN = '(encrypted)'
+
+  # A word that makes a name a credential's: `secret`, `api_key`, `otp_salt`, never `surname`.
+  CREDENTIALS = /secret|key|password|token|pin|salt|credential|signature/
+
+  # @return [Array<Omen::Column>] every encrypted column in the app, one per table and name.
+  def self.all
+    Rails.application.eager_load!
+    Omen.config.record.descendants.flat_map do |model|
+      model.encrypted_attributes.to_a.map { |attribute| new model, attribute }
+    end.uniq(&:name)
+  end
+
+  # An alias in the statement cannot change what Postgres says a value came from.
+  # @param result [PG::Result] what the statement answered.
+  # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] the one it ran on.
+  # @return [Hash] each header of the result that is an encrypted column, to that column's name.
+  def self.of(result, connection)
+    sources = all.index_by { |column| column.source connection }
+    result.nfields.times.each_with_object({}) do |index, into|
+      found = sources[[ result.ftable(index), result.ftablecol(index) ]]
+      into[result.fname index] = found.name if found
+    end
+  end
+
+  # @param model [Class] an Active Record that encrypts the column.
+  # @param attribute [Symbol] the attribute it encrypts.
+  def initialize(model, attribute)
+    @model = model
+    @attribute = attribute
+  end
+
+  # @return [String] the table and column, as Postgres names the source of a value.
+  def name = "#{@model.table_name}.#{@attribute}"
+
+  # @return [Boolean] whether a value of this column may be shown in the clear.
+  def readable? = !CREDENTIALS.match?(@attribute) && type.scheme.deterministic?
+
+  # @return [Array<Integer>] the table OID and column number Postgres reports for this column.
+  def source(connection)
+    described = connection.raw_connection.exec_params probe, []
+    [ described.ftable(0), described.ftablecol(0) ]
+  end
+
+  # @return [String, nil] the plaintext, or the placeholder where there is none to be had.
+  def read(value)
+    readable? ? type.deserialize(value) : HIDDEN
+  rescue ActiveRecord::Encryption::Errors::Decryption
+    HIDDEN
+  end
+
+private
+
+  def type = @model.type_for_attribute @attribute
+
+  def probe = @model.select(@attribute).limit(0).to_sql
+end

data/app/models/omen/combination.rb

@@ -0,0 +1,56 @@
+# One column a reply asks to be drawn as its parts joined, where the database could not join them.
+class Omen::Combination
+  # All a reply may declare: a name, the headers to join, and what goes between them.
+  SCHEMA = {
+    type: 'array',
+    description: 'Columns to draw as one, where the database could not build the value itself ' \
+                 'because a part of it is encrypted. Empty where nothing needs joining.',
+    items: {
+      type: 'object', additionalProperties: false, required: %w[ name parts separator ],
+      properties: {
+        name: { type: 'string', description: 'The header the joined column is drawn under.' },
+        parts: { type: 'array', items: { type: 'string' },
+                 description: 'Headers of your own query to join, in the order they read.', },
+        separator: { type: 'string', description: 'What goes between them, such as ", ".' },
+      },
+    },
+  }
+
+  # @param declared [Array<Hash>] what the reply asked for.
+  # @param headers [Array<String>] the headers the rows really have.
+  # @return [Array<Omen::Combination>] the ones a row can be drawn through.
+  def self.all(declared, headers)
+    declared.map { |one| new one }.select { |combination| combination.over? headers }
+  end
+
+  # @param declared [Hash] one entry of a reply's `combine`.
+  def initialize(declared)
+    @declared = declared
+  end
+
+  # Answered rather than raised on: the rows are right, and only the presentation was wrong.
+  # @param headers [Array<String>] the headers the rows really have.
+  # @return [Boolean] whether every part of this names one of them.
+  def over?(headers) = parts.any? && parts.all? { |part| headers.include? part }
+
+  # Joins what Omen::Column#read handed back, less the blanks: HIDDEN is a value, NULL is not.
+  # @param row [Hash] one row of the answer, decrypted.
+  # @return [Hash] the row with the parts replaced, where the first of them stood.
+  def applied(row)
+    row.each_with_object({}) do |(header, value), into|
+      if header == parts.first
+        into[name] = parts.filter_map { |part| row[part].presence }.join separator
+      elsif parts.exclude? header
+        into[header] = value
+      end
+    end
+  end
+
+private
+
+  def name = @declared['name'].to_s
+
+  def parts = Array @declared['parts']
+
+  def separator = @declared['separator'].to_s
+end

data/app/models/omen/conversation.rb

@@ -0,0 +1,51 @@
+# The one place Claude is spoken to, so everything above it is ours to read and to test.
+class Omen::Conversation
+  # How many tokens one reply may run to. Thinking is on by default and spends from the same
+  # budget, so this is sized well past the JSON it has to leave room for.
+  MAX_TOKENS = 16_000
+
+  # What each kind of block may carry back in, since a reply handed back whole is a 400.
+  SENDABLE = {
+    'text' => %w[ type text ],
+    'thinking' => %w[ type thinking signature ],
+    'redacted_thinking' => %w[ type data ],
+    'tool_use' => %w[ type id name input ],
+    'tool_result' => %w[ type tool_use_id content is_error ],
+  }
+
+  # @param questions [ActiveRecord::Relation] the questions asked so far, oldest first, up to
+  #   and including the one being answered.
+  def initialize(questions)
+    @questions = questions
+  end
+
+  # No tools are sent, by design: a tool_result block would be rows travelling back to Claude.
+  # @return [Hash] the blocks Claude answered with, why it stopped, and what it cost.
+  def advance
+    said = client.messages.create model: Omen.config.claude_model, max_tokens: MAX_TOKENS,
+      system_: Omen::Instructions.block, messages: messages,
+      output_config: Omen::Instructions.output_config
+
+    { content: said.content.map { |block| block.to_h.deep_stringify_keys },
+      stop_reason: said.stop_reason, input_usage: said.usage.input_tokens,
+      output_usage: said.usage.output_tokens,
+    }
+  end
+
+private
+
+  def client = Anthropic::Client.new(**credentials)
+
+  # Omitted rather than nil, which would lose the SDK's own resolution of a key.
+  def credentials = { api_key: Omen.config.api_key }.compact
+
+  def messages
+    spoken.map { |said| { role: said.role, content: said.content.map { |block| sendable block } } }
+  end
+
+  def spoken
+    @questions.includes(:answer).flat_map { |question| [ question, question.answer ].compact }
+  end
+
+  def sendable(block) = block.slice(*SENDABLE.fetch(block['type'], block.keys))
+end

data/app/models/omen/executed.rb

@@ -0,0 +1,39 @@
+# Extends Omen::Reading with the one exchange that turns a question into an answer.
+module Omen::Executed extend ActiveSupport::Concern
+  # A database message can quote a row, so only the kind of failure is passed on.
+  REFUSED = 'so ask it a different way'
+
+private
+
+  # Read again each time round, so a question asked while the API was answering is picked up.
+  def run
+    with_lock { return if started? && fresh?; started! }
+    while (question = questions.where.missing(:answer).first)
+      answer question
+    end
+    completed!
+  rescue StandardError => error
+    Rails.logger.warn "Reading #{id} failed: #{error.class}"
+    failed!
+  end
+
+  def answer(question)
+    reply = Omen::Conversation.new(asked_up_to question).advance
+    increment! :input_usage, reply[:input_usage]
+    increment! :output_usage, reply[:output_usage]
+    execute question.create_answer!(**reply)
+  end
+
+  def asked_up_to(question) = questions.where id: ..question.id
+
+  def execute(answered)
+    return if answered.sql.blank?
+
+    answered.update! Omen::Query.new(answered.sql).answer
+  rescue Omen::Role::Unavailable => error
+    answered.update! error: error.message
+  rescue StandardError => error
+    Rails.logger.warn "Reading #{id} refused a statement: #{error.class}"
+    answered.update! error: "#{(error.cause || error).class}, #{REFUSED}"
+  end
+end

data/app/models/omen/instructions.md

@@ -0,0 +1,92 @@
+You answer questions about the data an app holds, for the staff who run it.
+
+You answer by writing **one PostgreSQL SELECT** against the schema at the end of this message,
+and a short note about it. Nothing else runs.
+
+## You will never see the results
+
+Rails runs your query and shows the rows to the person who asked. They come back to you never.
+So do not offer to interpret them, do not say what the answer will turn out to be, and do not
+plan a second query that depends on the first one's output. Write the query that answers the
+question outright.
+
+Because nobody translates the rows for you, make them readable on their own: join a `*_id` to
+the table it points at and return the name held there rather than the bare integer, and name
+every computed column with `AS` so its header says what it is.
+
+## The connection
+
+Read-only, and a statement that would write is refused rather than run. Write exactly one
+statement: Postgres runs one, and refuses anything that would follow it. Your statement is
+wrapped in `SELECT * FROM (your query) AS answer LIMIT n`, and no more than a page of rows
+comes back however you write it. A `WITH` clause is fine.
+
+Prefer `count(*)`, `group by` and aggregates over returning raw rows: a question about how many
+or about which is most is answered better by ten rows than by a thousand.
+
+## Reading the schema
+
+Timestamps are stored in UTC, and `%{eastern}()` is the one way to read one: it hands the same
+moment back in the zone the company works in. Wrap every timestamp you touch in it -- in a
+`WHERE`, in an `ORDER BY`, in a `GROUP BY`, and in a column you return -- so a question about a
+day, a week or a month means whole days here: `date_trunc('day', %{eastern}(created_at))`. Never
+write a conversion of your own.
+
+Today is %{today}. Resolve every relative date yourself; the query has no idea what "last
+month" means.
+
+Every type named in a `create_enum` line at the top of the schema is a Postgres enum, and the
+values it may take are listed on that line. Compare one as text, for example
+`WHERE status::text = 'fulfilled'`.
+
+Rails encrypts these columns before they are stored, and decrypts them again for the person
+reading the page: %{readable}. Select them freely.
+
+Do not filter, sort or transform one. The database only ever sees the ciphertext, so
+`WHERE street = '2 Rodeo Dr'` matches nothing and `upper(street)` comes back unreadable --
+filter and sort on columns stored in the clear instead. `GROUP BY` one does work, because
+equal values encrypt equally, so "how many homes per street" is answerable.
+
+Where the value somebody wants is one of these joined to something else -- a street with the
+city and state after it -- select the parts and declare the join in `combine`, for example
+`[{"name": "address", "parts": ["street", "rest"], "separator": ", "}]`. Rails joins them after
+decrypting, and the page draws one column under the name you gave, in place of its parts. Every
+entry of `parts` has to be a header your query really returns. Where nothing needs joining,
+`combine` is `[]` -- and never explain a join in `note` instead of declaring it.
+
+These columns are stored encrypted as well, and no page ever reads one back -- either the name
+reads as a credential's, or the value is encrypted in a way no two writes of it agree on -- so
+do not select them: %{refused}.
+
+Every other column is stored in the clear and is yours to use.
+
+Only unique indexes are listed, and one tells you that a column, or a combination of them,
+identifies at most one row -- worth knowing before you reach for `DISTINCT` or a `GROUP BY`.
+Nothing follows from an index not being there.
+
+%{notes}
+
+## Tables whose `type` column holds a Ruby class name
+
+Single-table inheritance: the value is a class name, so `WHERE type = 'estimate'` matches
+nothing rather than erroring. The exact values are:
+
+%{types}
+
+A `type` column not listed above is an ordinary string and means whatever the rows say.
+
+## When the question is not clear enough to answer
+
+If a question could be read more than one way, or is missing the one thing you would need to
+pick a window of days, answer with an **empty** `sql` and put the question you need answered
+into `note`. Do not guess. A question with no date range, on data that spans years, is usually
+one of those.
+
+Otherwise keep the note to a sentence or two: what the query returns, and any assumption you
+made. These are colleagues reading quickly, not a report.
+
+## The schema
+
+```ruby
+%{schema}
+```

data/app/models/omen/instructions.rb

@@ -0,0 +1,56 @@
+# Everything Claude is told before a question: the prose, the schema, and the shape of a reply.
+class Omen::Instructions
+  # The prose, kept beside this class so it reads as prose rather than as a string.
+  PROSE = File.expand_path 'instructions.md', __dir__
+
+  # The database function a stored timestamp is read through, created by the gem's rake task.
+  EASTERN = 'eastern'
+
+  # The one shape a reply may take: both keys required, and no others admitted.
+  ANSWER = {
+    type: 'object', additionalProperties: false, required: %w[ sql note combine ],
+    properties: {
+      sql: { type: 'string',
+             description: 'The one PostgreSQL SELECT that answers the question, or ' \
+                          'empty to ask something first.', },
+      note: { type: 'string',
+              description: 'A sentence or two: what the query returns and any ' \
+                           'assumption made. If sql is empty, the question you ' \
+                           'need answered first.', },
+      combine: Omen::Combination::SCHEMA,
+    },
+  }
+
+  # @return [Hash] what a reply is constrained to, so that it always parses.
+  def self.output_config = { format_: { type: :json_schema, schema: ANSWER } }
+
+  # Cached for an hour: the schema is thousands of tokens, and refining sends it again.
+  # @return [Array<Hash>] the one system block of a request.
+  def self.block
+    [ { type: 'text', text: new.text, cache_control: { type: 'ephemeral', ttl: '1h' } } ]
+  end
+
+  # Today's date is said out loud because "last month" is Claude's to resolve, and it has no clock.
+  # @return [String] the prose, with the schema, the subclasses and the host's notes filled in.
+  def text
+    format File.read(PROSE), today: Date.current.to_fs(:long), eastern: EASTERN,
+      schema: schema, types: types, readable: readable, refused: refused,
+      notes: Omen.config.notes
+  end
+
+private
+
+  def schema = Omen::Schema.new.text
+
+  def types
+    Rails.application.eager_load!
+    Omen.config.record.descendants.select(&:finder_needs_type_condition?)
+      .group_by(&:table_name).sort.map { |table, kinds| "- `#{table}`: #{named kinds}" }.join "\n"
+  end
+
+  def named(kinds) = kinds.map(&:name).sort.map { |name| "`#{name}`" }.join ', '
+
+  def readable = named Omen::Column.all.select(&:readable?)
+
+  def refused = named Omen::Column.all.reject(&:readable?)
+end

data/app/models/omen/query.rb

@@ -0,0 +1,49 @@
+# The one SELECT Claude wrote, held by Postgres and by what it grants the role running it.
+class Omen::Query
+  # Rails writes every timestamp in UTC, which libpq would otherwise read as a local time.
+  UTC = { oid: 1114, name: 'timestamp', format: 0 }
+
+  # @param sql [String] the statement Claude answered with.
+  def initialize(sql)
+    @sql = sql
+  end
+
+  # A savepoint, so a statement Postgres rejects leaves the surrounding transaction usable.
+  # @return [Hash] the rows, and the encrypted column each header of theirs came from.
+  def answer
+    record.connected_to role: Omen.config.reading_role do
+      record.transaction requires_new: true do
+        record.with_connection { |connection| run connection }
+      end
+    end
+  end
+
+private
+
+  def record = Omen.config.record
+
+  def run(connection)
+    answered = Omen::Role.new(connection).around { executed connection }
+    { result: answered.to_a.first(cap), provenance: Omen::Column.of(answered, connection) }
+  end
+
+  def executed(connection)
+    raw = connection.raw_connection
+    result = raw.exec_params capped, []
+    result.type_map = typed raw
+    result
+  end
+
+  def typed(raw)
+    PG::BasicTypeMapForResults.new(raw).tap do |map|
+      map.default_type_map = PG::TypeMapAllStrings.new
+      map.add_coder PG::TextDecoder::TimestampUtc.new(**UTC)
+    end
+  end
+
+  def capped = "SELECT * FROM (#{statement}) AS answer LIMIT #{cap}"
+
+  def statement = @sql.strip.delete_suffix ';'
+
+  def cap = Omen.config.maximum_rows + 1
+end

data/app/models/omen/question.rb

@@ -0,0 +1,13 @@
+# A question somebody typed. There is no asked? to check: a question is asked by definition.
+class Omen::Question < Omen.config.record
+  include Omen::Spoken
+
+  belongs_to :reading, counter_cache: :questions_count, touch: true
+  has_one :answer, dependent: :delete
+
+  # A question is what sets a run going, and an answer is what a run leaves behind.
+  after_create_commit -> { reading.run_later }
+
+  # @return [String] the side of the conversation this was said on, in the words the API uses.
+  def role = 'user'
+end