omen 0.1.0 → 0.2.1

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

data/app/models/omen/reading.rb

@@ -0,0 +1,18 @@
+# A thread of questions somebody asks Claude about the data this app holds.
+class Omen::Reading < Omen.config.record
+  include Omen::Asked, Omen::Executed, Omen::Stated
+
+  has_many :questions, -> { order :id }, dependent: :destroy
+
+  # What the reading is opened with: a reading nobody asked anything is a reading of nothing.
+  attribute :question, :string
+
+  validates :question, presence: true, on: :create
+
+  after_create -> { ask question }
+
+  performs :run
+
+  # @return [String] the default representation (used in views).
+  def to_s = questions.first&.text.to_s.truncate 80
+end

data/app/models/omen/revealed.rb

@@ -0,0 +1,30 @@
+# Extends Omen::Answer with the plaintext behind the encrypted columns of its rows.
+module Omen::Revealed extend ActiveSupport::Concern
+  # How Rails' encryption opens an envelope, in either case an expression may have left it in.
+  CIPHERTEXT = [ '{"p":', '{"P":' ]
+
+  # @return [Array<Hash>] the rows of the answer a page shows, read back where that is allowed.
+  def shown
+    @shown ||= result.first(Omen.config.maximum_rows).map { |row| combined revealed row }
+  end
+
+private
+
+  def combined(row) = combinations.inject(row) { |left, one| one.applied left }
+
+  def combinations = @combinations ||= Omen::Combination.all(combine, result.first.to_h.keys)
+
+  def revealed(row) = row.to_h { |header, value| [ header, plain(header, value) ] }
+
+  def plain(header, value)
+    if (column = columns[provenance[header]])
+      column.read value
+    elsif value.to_s.start_with?(*CIPHERTEXT)
+      Omen::Column::HIDDEN
+    else
+      value
+    end
+  end
+
+  def columns = @columns ||= Omen::Column.all.index_by(&:name)
+end

data/app/models/omen/role.rb

@@ -0,0 +1,29 @@
+# The Postgres role a reading's statement runs as, which is refused the reading's own tables.
+class Omen::Role
+  # Raised where the database has no such role, or has not granted it to the connecting user.
+  class Unavailable < StandardError; end
+
+  # Ours to write, since it quotes no row: what an asker is told when it was the setup that failed.
+  MISCONFIGURED = 'This app is misconfigured, not the question -- ask an engineer to install ' \
+                  'the read-only role a statement runs as.'
+
+  # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] the one to switch.
+  def initialize(connection)
+    @connection = connection
+  end
+
+  # Given up before anything of ours runs; a statement Postgres refused rolls it back instead.
+  # @return [Object] whatever the block answered.
+  def around
+    enter
+    yield.tap { @connection.execute 'SET LOCAL ROLE NONE' }
+  end
+
+private
+
+  def enter
+    @connection.execute "SET LOCAL ROLE #{@connection.quote_table_name Omen.config.narrow_role}"
+  rescue ActiveRecord::StatementInvalid
+    raise Unavailable, MISCONFIGURED
+  end
+end

data/app/models/omen/schema.rb

@@ -0,0 +1,26 @@
+# What Claude writes its SQL against: the app's own schema, less the tables a reading is kept in.
+class Omen::Schema
+  # A plain index is a note about speed; a unique one is a fact about the rows, so it stays.
+  HINT = /^\s*t\.index (?!.*unique: true).*\n/
+
+  # @return [String] the schema, without this feature's own tables, their keys or their enum.
+  def text = without_orphan_enums hidden.inject(source) { |left, name| without_table left, name }
+
+private
+
+  def source = File.read(Omen.config.schema).gsub HINT, ''
+
+  def hidden = Omen.tables
+
+  def without_table(text, name)
+    text.gsub(/^  create_table "#{name}".*?\n  end\n\n?/m, '')
+      .gsub(/^  add_foreign_key ("#{name}"|"\w+", "#{name}").*\n/, '')
+  end
+
+  def without_orphan_enums(text)
+    # Derived rather than named, so a type the cut tables shared with another survives
+    text.gsub(/^  create_enum "(\w+)".*\n/) do |line|
+      text.include?(%(enum_type: "#{Regexp.last_match 1}")) ? line : ''
+    end
+  end
+end

data/app/models/omen/spoken.rb

@@ -0,0 +1,5 @@
+# Extends a question and an answer with the prose said in it, in the blocks Claude speaks in.
+module Omen::Spoken extend ActiveSupport::Concern
+  # @return [String] everything said in prose, which on an answer may be nothing.
+  def text = content.select { |block| block['type'] == 'text' }.pluck('text').join "\n"
+end

data/app/models/omen/stated.rb

@@ -0,0 +1,21 @@
+# Extends Omen::Reading to have a status of its own, rather than one a host shares out.
+module Omen::Stated extend ActiveSupport::Concern
+  # The states a reading passes through. The reading...
+  STATUSES = [
+    :unstarted, # ... has been asked something and has nothing back yet (default)
+    :started,   # ... is being answered right now, by whichever run holds the claim
+    :completed, # ... has been answered, so another question may follow
+    :failed,    # ... could not be answered at all, and is the asker's to try again
+  ]
+
+  # How long a run holds its claim before another may take the reading over.
+  STALLED_AFTER = 10.minutes
+
+  included do
+    enum :status, Hash[STATUSES.map { |status| [status, status] }]
+  end
+
+private
+
+  def fresh? = updated_at.after? STALLED_AFTER.ago
+end

data/db/migrate/20260821120000_create_omen_readings.rb

@@ -0,0 +1,13 @@
+class CreateOmenReadings < ActiveRecord::Migration[8.1]
+  def change
+    create_enum :omen_status, Omen::Stated::STATUSES
+
+    create_table :omen_readings do |t|
+      t.enum :status, enum_type: :omen_status, default: Omen::Stated::STATUSES.first, null: false
+      t.integer :input_usage, default: 0, null: false
+      t.integer :output_usage, default: 0, null: false
+      t.integer :questions_count, default: 0, null: false
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260821120001_create_omen_questions.rb

@@ -0,0 +1,9 @@
+class CreateOmenQuestions < ActiveRecord::Migration[8.1]
+  def change
+    create_table :omen_questions do |t|
+      t.jsonb :content, default: [], null: false
+      t.references :reading, null: false, foreign_key: { to_table: :omen_readings }
+      t.timestamps
+    end
+  end
+end

data/db/migrate/20260821120002_create_omen_answers.rb

@@ -0,0 +1,16 @@
+class CreateOmenAnswers < ActiveRecord::Migration[8.1]
+  def change
+    create_table :omen_answers do |t|
+      t.jsonb :content, default: [], null: false
+      t.jsonb :result, default: [], null: false
+      t.jsonb :provenance, default: {}, null: false
+      t.integer :input_usage, default: 0, null: false
+      t.integer :output_usage, default: 0, null: false
+      t.references :question, null: false, index: { unique: true },
+        foreign_key: { to_table: :omen_questions }
+      t.string :stop_reason
+      t.string :error
+      t.timestamps
+    end
+  end
+end

data/lib/generators/omen/install/install_generator.rb

@@ -0,0 +1,31 @@
+require 'rails/generators/active_record'
+
+module Omen
+  module Generators
+    # Everything installing this gem writes into a host: three migrations and one initializer.
+    # Not the roles or the database function, which are a rake task, because a copy of those
+    # would drift from what the gem goes on to expect and nothing would detect it.
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      # Both, since the migrations are shipped where they run from rather than as templates.
+      # @return [Array<String>] where a file being copied is looked for.
+      def self.source_paths
+        [ File.expand_path('templates', __dir__), Omen::Engine.root.join('db/migrate').to_s ]
+      end
+
+      # Copied rather than read off the gem, so the host owns the files and their timestamps.
+      # @return [void]
+      def copy_migrations
+        Dir.children(Omen::Engine.root.join('db/migrate')).sort.each do |name|
+          migration_template name, "db/migrate/#{name.split('_', 2).last}"
+        end
+      end
+
+      # @return [void]
+      def copy_initializer
+        template 'omen.rb', 'config/initializers/omen.rb'
+      end
+    end
+  end
+end

data/lib/generators/omen/install/templates/omen.rb

@@ -0,0 +1,35 @@
+# Be sure to restart your server when you modify this file.
+# Every setting Omen has is listed with the default it takes where the line is left out, so
+# an app that accepts all of them can delete the block. What an app has to provide outside
+# this file -- the read-only connection, the narrow role and the database function -- is in
+# the gem's README, and none of it is optional.
+
+Omen.configure do |config|
+  # The Active Record whose descendants are read for encrypted columns, and whose connection
+  # roles a statement is run through. A name, since nothing is autoloaded while this runs.
+  # config.record_class = 'ApplicationRecord'
+
+  # The Rails connection role a statement is read through. This app has to declare it with
+  # connects_to: Omen raises rather than falling back to a role that could write.
+  # config.reading_role = :reading
+
+  # The Postgres role the statement itself runs as, narrower again than the connection's own.
+  # Created by bin/rails db:omen:grant, which is also what revokes Omen's own tables from it.
+  # config.narrow_role = 'omen_inquirer'
+
+  # config.claude_model = 'claude-opus-5'
+
+  # How many rows of one answer a page shows. One more than this is read, so the page can say
+  # there are more without counting them.
+  # config.maximum_rows = 100
+
+  # Left unset, the Anthropic SDK resolves ANTHROPIC_API_KEY and its own wider chain.
+  # config.api_key = Rails.application.credentials.dig :anthropic, :api_key
+
+  # A file of prose about this app's own data: what it is, and where a table's rows really
+  # are. Everything the schema cannot say, and Claude is given it verbatim.
+  # config.notes = Rails.root.join 'config/omen_notes.md'
+
+  # Where Rails keeps the schema this app dumps, which is what Claude is shown.
+  # config.schema_path = 'db/schema.rb'
+end

data/lib/omen/config.rb

@@ -0,0 +1,46 @@
+module Omen
+  # Every fact about the app this feature is installed in, so none of its own classes names one.
+  # All of them have a default, which is what makes the initializer a host writes optional.
+  class Config
+    # The Rails connection role a statement is read through. A host has to declare a read-only
+    # one: Omen raises rather than falling back to the writing role, which is the point.
+    attr_accessor :reading_role
+
+    # The Postgres role a statement runs as, narrower again than the connection's own.
+    attr_accessor :narrow_role
+
+    # The Claude model a question is asked of.
+    attr_accessor :claude_model
+
+    # How many rows of one answer a page will show.
+    attr_accessor :maximum_rows
+
+    # The key the Anthropic API is reached with. Left unset, the SDK resolves one of its own.
+    attr_accessor :api_key
+
+    # What a host states as a name or as a path, each of them resolved only when it is wanted.
+    attr_writer :record_class, :notes, :schema_path
+
+    def initialize
+      @reading_role = :reading
+      @narrow_role = 'omen_inquirer'
+      @claude_model = 'claude-opus-5'
+      @maximum_rows = 100
+      @schema_path = 'db/schema.rb'
+    end
+
+    # A name rather than the class, since nothing is autoloaded while an initializer runs.
+    # @return [Class] the Active Record whose descendants and connection roles this feature uses.
+    def record = @record_class ? @record_class.constantize : default_record
+
+    # @return [String] the host's own notes about its data, which its schema cannot state.
+    def notes = @notes ? File.read(@notes) : ''
+
+    # @return [Pathname] the file Rails keeps in step with the database, which Claude is shown.
+    def schema = Rails.root.join @schema_path
+
+  private
+
+    def default_record = defined?(ApplicationRecord) ? ApplicationRecord : ActiveRecord::Base
+  end
+end

data/lib/omen/eastern.rb

@@ -0,0 +1,40 @@
+module Omen
+  # The database function a reading's SQL reads every timestamp through. Created by the rake
+  # task rather than by a migration, because Rails' :ruby schema format dumps no functions, so
+  # db:schema:load would drop one a migration had made -- and the format cannot become :sql,
+  # since db/schema.rb is what Claude is shown.
+  module Eastern
+    # The zone the company works in, as Postgres names one: Time.zone.name is not one it takes.
+    ZONE = 'America/New_York'
+
+    # DDL, which Active Record has no expression for, and not a query.
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @return [Array<String>] the statements to run, in order.
+    def self.statements(connection)
+      [ stored(connection), instant(connection) ]
+    end
+
+    # A stored timestamp says nothing about its own zone, so it is named UTC and then rendered.
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @return [String] the statement declaring the function over a naked timestamp.
+    def self.stored(connection)
+      "CREATE OR REPLACE FUNCTION #{name connection}(ts timestamp) RETURNS timestamp AS " \
+        "$$ SELECT ts AT TIME ZONE 'UTC' AT TIME ZONE #{connection.quote ZONE} $$ " \
+        'LANGUAGE sql IMMUTABLE'
+    end
+
+    # One conversion and not two: an instant already knows which moment it is, so naming it UTC
+    # first would convert it twice and answer hours out. Overloaded because Postgres will not
+    # cast an instant to a timestamp to resolve a call, so now() reaches neither without it.
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @return [String] the statement declaring the function over an instant.
+    def self.instant(connection)
+      "CREATE OR REPLACE FUNCTION #{name connection}(ts timestamptz) RETURNS timestamp AS " \
+        "$$ SELECT ts AT TIME ZONE #{connection.quote ZONE} $$ LANGUAGE sql IMMUTABLE"
+    end
+
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @return [String] the function's name, quoted.
+    def self.name(connection) = connection.quote_table_name Omen::Instructions::EASTERN
+  end
+end

data/lib/omen/engine.rb

@@ -2,5 +2,15 @@ module Omen
   # Teaches Rails where this gem's models live, and prefixes their tables with `omen_`.
   class Engine < ::Rails::Engine
     isolate_namespace Omen
+
+    # Read off what the app declares rather than by connecting, and late enough that its own
+    # initializer has already said where its schema is. The declared format rather than the
+    # applied one, so nothing here depends on which after_initialize hook ran first.
+    config.after_initialize do
+      configured = ActiveRecord::Base.configurations.configs_for env_name: Rails.env,
+        name: 'primary'
+      Omen::Requirements.met adapter: configured&.adapter, schema: Omen.config.schema,
+        schema_format: Rails.application.config.active_record.schema_format
+    end
   end
 end

data/lib/omen/inquirer.rb

@@ -0,0 +1,91 @@
+module Omen
+  # The Postgres role a reading's own SELECT runs as, blind to the tables a reading is kept in.
+  # It needs no database.yml entry of its own: NOLOGIN, it is a privilege container reached
+  # with SET LOCAL ROLE and never connected as.
+  module Inquirer
+    # What this role may never be: a superuser bypasses GRANT outright.
+    ATTRIBUTES = 'NOSUPERUSER NOCREATEDB NOCREATEROLE NOBYPASSRLS NOREPLICATION'
+
+    # Whom to ask, since the role a host reads through is one this gem has no name for.
+    WHOEVER = 'SELECT current_user'
+
+    # Said on the way through installation step one, where a host has yet to declare the role.
+    UNGRANTED = 'No %{role} connection is configured, so nothing was granted to whatever ' \
+                'reads through it. Run this again once config/database.yml names one.'
+
+    # Creates the role and the function, on every database this environment prepares.
+    # @return [void]
+    def self.grant
+      environments.each do |environment|
+        config = ActiveRecord::Base.configurations.configs_for env_name: environment,
+          name: 'primary'
+        next unless config
+        ActiveRecord::Tasks::DatabaseTasks.with_temporary_connection config do |connection|
+          grant_on connection
+        end
+      end
+    end
+
+    # @return [Array<String>] the environments whose databases this run should cover.
+    def self.environments = Rails.env.development? ? %w[ development test ] : [Rails.env.to_s]
+
+    # Warns rather than raises: a managed database never grants CREATEROLE, and a deploy that
+    # cannot make the role must still finish, having said what has to be made by hand.
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @return [void]
+    def self.grant_on(connection)
+      read_by = reader
+      warn UNGRANTED % { role: Omen.config.reading_role } unless read_by
+      members = [ read_by, connection.select_value(WHOEVER) ].compact
+      statements(connection, members).each { |statement| connection.execute statement }
+      puts "Granted SELECT on #{connection.current_database} to #{Omen.config.narrow_role}"
+    rescue ActiveRecord::StatementInvalid => error
+      warn "Could not make #{Omen.config.narrow_role}, so every reading will say this app is " \
+           'misconfigured. Ask for that role, NOLOGIN, granted SELECT on every table but ' \
+           "#{Omen.tables.to_sentence}: #{error.message}"
+    end
+
+    # Discovered rather than named: SET LOCAL ROLE needs the connecting role to be a member of
+    # this one, and the role a host's reading connection logs in as is the host's own business.
+    # @return [String, nil] the Postgres user a reading is read through, where there is one.
+    def self.reader
+      Omen.config.record.connected_to role: Omen.config.reading_role do
+        Omen.config.record.with_connection { |connection| connection.select_value WHOEVER }
+      end
+    rescue ActiveRecord::ConnectionNotDefined, ActiveRecord::ConnectionNotEstablished
+      nil
+    end
+
+    # DDL, which Active Record has no expression for, and not a query.
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @param members [Array<String>] the roles that may SET LOCAL ROLE to this one. The owner
+    #   running the task is one of them, and matters in tests, where Rails swaps the reading
+    #   pool for the writing one and the test connection is the owner.
+    # @return [Array<String>] the statements to run, in order.
+    def self.statements(connection, members)
+      role = connection.quote_table_name Omen.config.narrow_role
+      [
+        'DO $$ BEGIN IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = ' \
+          "#{connection.quote Omen.config.narrow_role}) THEN CREATE ROLE #{role} NOLOGIN; " \
+          'END IF; END $$',
+        "ALTER ROLE #{role} WITH NOLOGIN #{ATTRIBUTES}",
+        "GRANT USAGE ON SCHEMA public TO #{role}",
+        "GRANT SELECT ON ALL TABLES IN SCHEMA public TO #{role}",
+        "ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO #{role}",
+        *members.map { |member| "GRANT #{role} TO #{connection.quote_table_name member}" },
+        *revoked(connection, role),
+        *Eastern.statements(connection),
+      ]
+    end
+
+    # Intersected, so a bare db:create with no table yet to revoke on is not a failure.
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @param role [String] the role to hide this feature's own tables from.
+    # @return [Array<String>] one REVOKE per table there is.
+    def self.revoked(connection, role)
+      (connection.tables & Omen.tables).map do |table|
+        "REVOKE SELECT ON #{connection.quote_table_name table} FROM #{role}"
+      end
+    end
+  end
+end

data/lib/omen/requirements.rb

@@ -0,0 +1,37 @@
+module Omen
+  # What an app has to be for this gem to keep its promises, checked as that app boots. Both
+  # of these rule an app out rather than inconveniencing it, so neither is worth deferring.
+  module Requirements
+    # Raised where an app cannot be one this gem works in, however else it is configured.
+    class Unmet < StandardError; end
+
+    # The one adapter that reports the table a result column came from, and scopes a role to
+    # a transaction. Everything else Omen promises rests on one of those two.
+    ADAPTER = 'postgresql'
+
+    # The one schema format that can be read as a prompt.
+    FORMAT = :ruby
+
+    # Said where the app reaches its database through anything else.
+    WRONG_ADAPTER = 'Omen needs a postgresql database, and this app names the adapter'
+
+    # Said where the app dumps its schema as SQL, which cannot be shown to Claude.
+    WRONG_FORMAT = 'Omen shows Claude db/schema.rb, so config.active_record.schema_format ' \
+                   'has to be :ruby, and this app sets'
+
+    # Said where the file is not there at all: a run would fail one question at a time, and
+    # a structure.sql copied to that path would leave the reading tables in the prompt.
+    NO_SCHEMA = 'Omen shows Claude the schema Rails dumps, and there is no file at'
+
+    # @param adapter [String, nil] what this app reaches its own database through.
+    # @param schema_format [Symbol, nil] the format it declares, nil where it declares none.
+    # @param schema [Pathname] where the dump is kept.
+    # @return [void]
+    def self.met(adapter:, schema_format:, schema:)
+      dumps = schema_format || FORMAT
+      raise Unmet, "#{WRONG_ADAPTER} #{adapter.inspect}" unless adapter == ADAPTER
+      raise Unmet, "#{WRONG_FORMAT} #{dumps.inspect}" unless dumps == FORMAT
+      raise Unmet, "#{NO_SCHEMA} #{schema}" unless File.exist? schema
+    end
+  end
+end

data/lib/omen/stubs.rb

@@ -0,0 +1,41 @@
+# Answers the Anthropic API with canned turns, so no test of a host reaches the network.
+module Omen::Stubs extend ActiveSupport::Concern
+  # Where a message is asked for.
+  MESSAGES_URL = 'https://api.anthropic.com/v1/messages'
+
+  # Answers each request with the next turn, so a question and its refinement are scripted apart.
+  # @param turns [Array<Hash>] what Claude says, in order.
+  def stub_claude(*turns)
+    stub_request(:post, MESSAGES_URL).
+      to_return(*turns.map { |turn| { body: turn.to_json, headers: json_headers } })
+  end
+
+  # Carries a stray `caller`, so a test notices if a reply is ever replayed whole.
+  # @param sql [String] the statement Claude answers with, or '' to ask something instead.
+  # @param note [String] what Claude says about it.
+  # @param combine [Array<Hash>] the columns it asks to be drawn as their parts joined.
+  # @return [Hash] a turn where Claude answers in the shape the output schema demands.
+  def claude_answers(sql: '', note: '', combine: [])
+    answered = { sql: sql, note: note, combine: combine }
+    claude_turn 'end_turn', [ { type: 'text', text: answered.to_json,
+                                caller: { type: 'assistant' }, } ]
+  end
+
+  # A reply cut short at max_tokens is not JSON, whatever the output schema demanded.
+  # @param text [String] what Claude got as far as saying.
+  # @return [Hash] a turn the API stopped mid-sentence.
+  def claude_says(text)
+    claude_turn 'max_tokens', [ { type: 'text', text: text } ]
+  end
+
+private
+
+  def claude_turn(stop_reason, content)
+    { id: 'msg_01', type: 'message', role: 'assistant', model: 'claude-opus-5',
+      content: content, stop_reason: stop_reason,
+      usage: { input_tokens: 10, output_tokens: 5 },
+    }
+  end
+
+  def json_headers = { 'Content-Type' => 'application/json' }
+end

data/lib/omen/version.rb

@@ -1,4 +1,4 @@
 module Omen
   # The version of this gem, as RubyGems knows it.
-  VERSION = '0.1.0'
+  VERSION = '0.2.1'
 end

data/lib/omen.rb

@@ -1,6 +1,23 @@
+require 'active_job/performs'
+require 'anthropic'
+
+require 'omen/config'
+require 'omen/eastern'
+require 'omen/inquirer'
+require 'omen/requirements'
 require 'omen/version'
 require 'omen/engine'
 
 # Staff ask Claude a question about the data an app holds; Claude writes the SQL, Rails runs it.
 module Omen
+  # Hidden twice over: out of the prompt, and out of what the statement's own role may read.
+  # @return [Array<String>] the tables this feature keeps its log of questions and answers in.
+  def self.tables = [ Omen::Reading, Omen::Question, Omen::Answer ].map(&:table_name)
+
+  # @return [Omen::Config] everything this feature has to be told about the app around it.
+  def self.config = @config ||= Omen::Config.new
+
+  # Yields the configuration, so a host states its own facts in one initializer.
+  # @return [void]
+  def self.configure = yield config
 end

data/lib/tasks/omen.rake

@@ -0,0 +1,9 @@
+namespace :db do
+  namespace :omen do
+    desc 'Create the role a reading runs its statement as, and the function it reads a ' \
+         'timestamp through'
+    task grant: :environment do
+      Omen::Inquirer.grant
+    end
+  end
+end