omen 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0439ba57f67515df5b1685bb241e7c8d904f7039b3c349a45add84eaec5b6330'
-  data.tar.gz: 125790550dbc3c82b2a139c4a09fc1767ea6776ce984357aa40841e397adef38
+  metadata.gz: 7bff8c4c873f1cbc8923e3dbc7cebe42e282126624a56cab8d2461b8c879fb0d
+  data.tar.gz: e8bd747cf8234259e52e7bf5d1ab24e607dc5ba6ba09deef01f037692bd3a6f7
 SHA512:
-  metadata.gz: 3123b62849d8a61bdd7264aa1eba6a13fe0bc8b5225be52cd4d5633840b5117181dca928c1ed21e6a26b54d45650f39037221cedfe8f95f7af1b5047b1523dae
-  data.tar.gz: 6e1a011344a1ec0cb7c09657a8bdfa40159de13f4d65f892f6a23cba5ce965959224fe8c4bd4585d68d82290773035e439c0eb4ec47bf428e6f0e2814890f251
+  metadata.gz: 1c82de79367f41a2712f44bdf21d6ca715c263fbc097dae9d7dcd032ba28a152ebf4c1976b02b37f62992781f98981fab99fd49173a4925bea3664ba668cbff1
+  data.tar.gz: 0a2a09480ee44f60283db5db8976d6c97d6373fca2af7f6e1b2526de51052e5aba96b171ba989af70ef7bf5e9acd1fb01bbd6933cb9ec1b6cf00a10be80f0a8e

data/CHANGELOG.md

@@ -7,6 +7,20 @@ For more information about changelogs, check [Keep a Changelog](http://keepachan
 
 ## [Unreleased]
 
+## 0.2.2 - 2026-08-24
+
+* [Fix] Run a load hook as each model loads, so a host declares `broadcasts_refreshes` and the
+  rest through `ActiveSupport.on_load :omen_reading` rather than by naming the class while
+  initializers run, which loaded Active Record before Rails was up
+* [Fix] Read the adapter through the `:active_record` load hook, so a boot that never touches
+  the database is not the boot that loads it early
+
+## 0.2.1 - 2026-08-24
+
+* [Fix] Declare `eastern()` over an instant as well as a stored timestamp, so a reply that
+  reaches for `now()` finds a function rather than `does not exist`
+* [Fix] Tell Claude not to ask the database what time it is, since the prompt already says
+  what today is
 * [Fix] Point RubyGems at the API reference, so a gem page and a gem listing say the same
   thing about where the documentation is
 

data/README.md

@@ -1,13 +1,13 @@
 # Omen
 
-Staff ask Claude a question about the data an app holds; Claude writes the SQL, Rails runs it.
+You ask Claude a complex question about data stored by your Rails app.
+Claude answers with the SQL. Rails runs it.
 
-Omen ships the models and the logic to talk to Claude, parse what it says back, and run the
-statement it wrote against a read-only connection. It ships **no controllers, routes or views** —
-the pages belong to the app that installs it.
+Omen is an engine that you too can use. You just need a Rails app running on PostgreSQL.
+Omen provides the models and the logic to talk to Claude; to parse what it says; to run read-only statements.
 
-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.
+Your data never travels. Claude is shown the schema and writes one `SELECT`; Rails runs it and
+draws the answer (including encrypted attributes) for whoever asked. Nothing that statement returned is ever sent back.
 
 ## How to install
 
@@ -26,35 +26,38 @@ never crosses a breaking change.
 
 ## Requirements
 
-**PostgreSQL only.** This is not a gap waiting to be filled. Two of the guarantees Omen makes are
-Postgres features with no equivalent elsewhere: it identifies an encrypted column by the table OID
-and column number Postgres reports for each result column, which is what stops an alias or an
-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 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. 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.
-
-**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.
+**PostgreSQL only** 
+
+<details>
+  <summary>This is not a gap waiting to be filled. </summary>
+  Two of the guarantees Omen makes are
+  Postgres features with no equivalent elsewhere: it identifies an encrypted column by the table OID
+  and column number Postgres reports for each result column, which is what stops an alias or an
+  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 at boot on any other adapter rather than running with a weaker promise.
+</details>
+
+**db/schema.rb in Rails** 
+
+<details>
+  <summary>Only the :ruby schema is supported. </summary>
+  The schema is what Claude is shown, so an app
+  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.
+</details>
 
 ## Configuration
 
-Installing is three commands and, if you want to change anything, one file.
-
-### The steps
+Installing by adding to your Gemfile and running three commands in your terminal: 
 
 ```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
+bin/rails g omen:install # adds three migrations + an initializer you can delete
+bin/rails db:migrate     # creates the tables `omen_readings`, `omen_questions`, `omen_answers`
+bin/rails db:omen:grant  # set the read-only role statements run as
 ```
 
 `db:omen:grant` is worth running from the tasks that build a database, so a fresh one is never
@@ -71,10 +74,7 @@ granted = Rake::Task['db:omen:grant']
 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.
+### Requirements
 
 - **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`
@@ -95,14 +95,8 @@ 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
 
@@ -125,7 +119,7 @@ Two things a subclass cannot reach, because the gem's own class is what a job lo
 line in the host does it:
 
 ```ruby
-Rails.application.config.to_prepare { Omen::Reading.broadcasts_refreshes }
+ActiveSupport.on_load(:omen_reading) { broadcasts_refreshes }
 ```
 
 ## After the first deploy

data/app/models/omen/answer.rb

@@ -35,3 +35,5 @@ class Omen::Answer < Omen.config.record
   # @return [Boolean] whether the answer ran past what is shown.
   def truncated? = result.size > Omen.config.maximum_rows
 end
+
+ActiveSupport.run_load_hooks :omen_answer, Omen::Answer

data/app/models/omen/instructions.md

@@ -33,7 +33,8 @@ day, a week or a month means whole days here: `date_trunc('day', %{eastern}(crea
 write a conversion of your own.
 
 Today is %{today}. Resolve every relative date yourself; the query has no idea what "last
-month" means.
+month" means, and it must never ask the database what time it is -- `now()` and
+`current_timestamp` are the clock of the machine, not the date above.
 
 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

data/app/models/omen/question.rb

@@ -11,3 +11,5 @@ class Omen::Question < Omen.config.record
   # @return [String] the side of the conversation this was said on, in the words the API uses.
   def role = 'user'
 end
+
+ActiveSupport.run_load_hooks :omen_question, Omen::Question

data/app/models/omen/reading.rb

@@ -16,3 +16,5 @@ class Omen::Reading < Omen.config.record
   # @return [String] the default representation (used in views).
   def to_s = questions.first&.text.to_s.truncate 80
 end
+
+ActiveSupport.run_load_hooks :omen_reading, Omen::Reading

data/lib/omen/eastern.rb

@@ -11,12 +11,30 @@ module Omen
     # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
     # @return [Array<String>] the statements to run, in order.
     def self.statements(connection)
-      name = connection.quote_table_name Omen::Instructions::EASTERN
-      [
-        "CREATE OR REPLACE FUNCTION #{name}(ts timestamp) RETURNS timestamp AS " \
-          "$$ SELECT ts AT TIME ZONE 'UTC' AT TIME ZONE #{connection.quote ZONE} $$ " \
-          'LANGUAGE sql IMMUTABLE',
-      ]
+      [ 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

@@ -7,10 +7,12 @@ module Omen
     # 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
+      ActiveSupport.on_load :active_record 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
 end

data/lib/omen/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omen
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Claudio Baccigalupo