omen 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0439ba57f67515df5b1685bb241e7c8d904f7039b3c349a45add84eaec5b6330'
-  data.tar.gz: 125790550dbc3c82b2a139c4a09fc1767ea6776ce984357aa40841e397adef38
+  metadata.gz: c5ce1b7049f103291d3d3aabb7d02bb80271bb7dca022bb1250db4855b59a4e9
+  data.tar.gz: e323629870bf6d657fa4f43b0c47018eeed8af9946733f962d0e51889297ddcf
 SHA512:
-  metadata.gz: 3123b62849d8a61bdd7264aa1eba6a13fe0bc8b5225be52cd4d5633840b5117181dca928c1ed21e6a26b54d45650f39037221cedfe8f95f7af1b5047b1523dae
-  data.tar.gz: 6e1a011344a1ec0cb7c09657a8bdfa40159de13f4d65f892f6a23cba5ce965959224fe8c4bd4585d68d82290773035e439c0eb4ec47bf428e6f0e2814890f251
+  metadata.gz: ff778fcc7568f43a7b0252793443c18ab0aee925c9030dcdef9af262934eb62bfb3a9e34af21c0cb7a4f6d096cdde812fd216fc4c64008095443f44ffea3ab70
+  data.tar.gz: 1aea2af528735383465416dd6dcbd24770b983e630934e4ecf170e36d90120e9fbbf21e85efbd25eb6aa59860ba3c753cb66c97983f61ca5ea9785041a72d3e3

data/CHANGELOG.md

@@ -7,6 +7,12 @@ For more information about changelogs, check [Keep a Changelog](http://keepachan
 
 ## [Unreleased]
 
+## 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
 

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/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/version.rb

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

metadata

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