omen 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5ce1b7049f103291d3d3aabb7d02bb80271bb7dca022bb1250db4855b59a4e9
-  data.tar.gz: e323629870bf6d657fa4f43b0c47018eeed8af9946733f962d0e51889297ddcf
+  metadata.gz: 529ccf31849252011c372776067dfb887267dea3b8e1580a0dbb598bab0afa56
+  data.tar.gz: 7a9bb4e0ebd22451484b508b1a96e5f2ba85fcc92fcaaf62cd1f433b683b6ef5
 SHA512:
-  metadata.gz: ff778fcc7568f43a7b0252793443c18ab0aee925c9030dcdef9af262934eb62bfb3a9e34af21c0cb7a4f6d096cdde812fd216fc4c64008095443f44ffea3ab70
-  data.tar.gz: 1aea2af528735383465416dd6dcbd24770b983e630934e4ecf170e36d90120e9fbbf21e85efbd25eb6aa59860ba3c753cb66c97983f61ca5ea9785041a72d3e3
+  metadata.gz: b9d59820ced246e19969a0ff0dbea02b29feb1bc85be637522066ec49d3a15b8e11c83d0aca97397a05235ab1cd7413dc3553bba3b8d17102933fae40c18d549
+  data.tar.gz: bdcda330b4d7e03ef0b1fa6e2586b8c35dee10101af54600e5cdde47ca1f23b0ed06825e59b3d43ce7559f906aab03de186a2ae75d19396bfae8e481e6670a0e

data/CHANGELOG.md

@@ -7,6 +7,24 @@ For more information about changelogs, check [Keep a Changelog](http://keepachan
 
 ## [Unreleased]
 
+## 0.3.0 - 2026-08-24
+
+* [Feature] Create a `miles_between(lat1, lng1, lat2, lng2)` function and name it in the prompt,
+  so a radius is four arguments rather than a dozen nested trigonometric calls that a reply
+  balances by hand -- and gets wrong
+* [Fix] Tell Claude that text is single-quoted and an apostrophe inside it is doubled, since a
+  double-quoted literal is read as a column name and refuses the whole statement
+* [Fix] Tell Claude to declare a `combine` where an encrypted value belongs inside a sentence,
+  rather than returning the pieces as columns for the page to draw apart
+
+## 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

data/README.md

@@ -50,6 +50,21 @@ never crosses a breaking change.
   question ever asked.
 </details>
 
+**Two database functions** 
+
+<details>
+  <summary>A timestamp and a distance are read through a function, never an expression. </summary>
+  `db:omen:grant` creates both. `eastern()` hands a stored timestamp back in the zone the company
+  works in, so every date in the prompt means the same whole days, and
+  `miles_between(lat1, lng1, lat2, lng2)` answers a great-circle distance in miles. The prompt
+  names each and forbids writing either by hand: a conversion assembled per query drifts, and a
+  great-circle expression runs to a dozen nested calls that a reply balances by hand and gets
+  wrong. Both are `LANGUAGE sql IMMUTABLE` and executable by anyone, so neither needs a grant.
+  An app in another zone renames the first; an app whose tables carry no coordinates simply never
+  calls the second. Neither can be a migration: Rails' `:ruby` schema format dumps no functions,
+  so `db:schema:load` would drop one a migration had made.
+</details>
+
 ## Configuration
 
 Installing by adding to your Gemfile and running three commands in your terminal: 
@@ -119,7 +134,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

@@ -24,6 +24,11 @@ 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.
 
+Text goes in single quotes, and an apostrophe inside it is written twice: `'it''s'`. Double
+quotes name a column, so `"it's here"` is read as the name of a column, no such column is found
+and the whole statement is refused. It is the one mistake that still looks like text after you
+have made it, and switching quote style to avoid an apostrophe is how you make it.
+
 ## Reading the schema
 
 Timestamps are stored in UTC, and `%{eastern}()` is the one way to read one: it hands the same
@@ -36,6 +41,12 @@ Today is %{today}. Resolve every relative date yourself; the query has no idea w
 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.
 
+Where a table carries coordinates, the distance between two points in miles is
+`%{miles}(lat1, lng1, lat2, lng2)`, so a radius reads
+`WHERE %{miles}(l.lat, l.lng, u.lat, u.lng) <= 2`. Never write the trigonometry yourself: a
+great-circle expression built by hand runs to a dozen nested calls, and one bracket out of place
+either refuses the statement or, worse, measures something else and says nothing about it.
+
 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'`.
@@ -55,6 +66,11 @@ decrypting, and the page draws one column under the name you gave, in place of i
 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.
 
+Declare it the same way where the value belongs inside a sentence you are building: return the
+text before it, the column itself, and the text after it as three columns, and join them with
+`"separator": ""`. What you must not do is leave the parts as separate columns and let the page
+draw them apart, which is what happens when you work around the ciphertext instead of saying so.
+
 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}.

data/app/models/omen/instructions.rb

@@ -6,6 +6,9 @@ class Omen::Instructions
   # The database function a stored timestamp is read through, created by the gem's rake task.
   EASTERN = 'eastern'
 
+  # The database function a distance in miles is measured with, created by the same task.
+  MILES = 'miles_between'
+
   # The one shape a reply may take: both keys required, and no others admitted.
   ANSWER = {
     type: 'object', additionalProperties: false, required: %w[ sql note combine ],
@@ -33,7 +36,7 @@ class Omen::Instructions
   # 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,
+    format File.read(PROSE), today: Date.current.to_fs(:long), eastern: EASTERN, miles: MILES,
       schema: schema, types: types, readable: readable, refused: refused,
       notes: Omen.config.notes
   end

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

@@ -0,0 +1,31 @@
+module Omen
+  # The database function a reading measures a distance with. Created by the rake task rather
+  # than by a migration, for the reason Omen::Eastern is: Rails' :ruby schema format dumps no
+  # functions, so db:schema:load would drop one a migration had made.
+  module Distance
+    # The earth's mean radius in miles, which is what makes the answer miles.
+    RADIUS = 3958.7613
+
+    # 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) = [ haversine(connection) ]
+
+    # Declared over double precision, which numeric, real and integer all cast to implicitly,
+    # so a host's own column type does not have to be guessed at. Any argument NULL and the
+    # answer is NULL, the way a distance to nowhere ought to read.
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @return [String] the statement declaring the function.
+    def self.haversine(connection)
+      "CREATE OR REPLACE FUNCTION #{name connection}(lat1 double precision, " \
+        'lng1 double precision, lat2 double precision, lng2 double precision) ' \
+        "RETURNS double precision AS $$ SELECT 2 * #{RADIUS} * asin(sqrt(" \
+        'power(sin(radians(lat2 - lat1) / 2), 2) + cos(radians(lat1)) * cos(radians(lat2)) ' \
+        '* power(sin(radians(lng2 - lng1) / 2), 2))) $$ 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::MILES
+  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/inquirer.rb

@@ -75,6 +75,7 @@ module Omen
         *members.map { |member| "GRANT #{role} TO #{connection.quote_table_name member}" },
         *revoked(connection, role),
         *Eastern.statements(connection),
+        *Distance.statements(connection),
       ]
     end
 

data/lib/omen/version.rb

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

data/lib/omen.rb

@@ -2,6 +2,7 @@ require 'active_job/performs'
 require 'anthropic'
 
 require 'omen/config'
+require 'omen/distance'
 require 'omen/eastern'
 require 'omen/inquirer'
 require 'omen/requirements'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omen
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -98,6 +98,7 @@ files:
 - lib/generators/omen/install/templates/omen.rb
 - lib/omen.rb
 - lib/omen/config.rb
+- lib/omen/distance.rb
 - lib/omen/eastern.rb
 - lib/omen/engine.rb
 - lib/omen/inquirer.rb