omen 0.2.2 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7bff8c4c873f1cbc8923e3dbc7cebe42e282126624a56cab8d2461b8c879fb0d
-  data.tar.gz: e8bd747cf8234259e52e7bf5d1ab24e607dc5ba6ba09deef01f037692bd3a6f7
+  metadata.gz: f96e34cbde627e0781a12488ba4308d704c6896a71fc44b031b7d412512c22eb
+  data.tar.gz: 408ad7c0b4a13f8ef3aef1b1c271e81ac116791ff627ffa2d056f5ecb6c45e34
 SHA512:
-  metadata.gz: 1c82de79367f41a2712f44bdf21d6ca715c263fbc097dae9d7dcd032ba28a152ebf4c1976b02b37f62992781f98981fab99fd49173a4925bea3664ba668cbff1
-  data.tar.gz: 0a2a09480ee44f60283db5db8976d6c97d6373fca2af7f6e1b2526de51052e5aba96b171ba989af70ef7bf5e9acd1fb01bbd6933cb9ec1b6cf00a10be80f0a8e
+  metadata.gz: fd53d5b7acb9fea6560bf0edbd5e1fb8f26200d99edaa52dfd9a81c9945dbd154a69514a7ba0028a025f36284bbd04be01e7aa57df61b7c01fa68ceb974638fd
+  data.tar.gz: a5b4226127e861f2600ebf62eb1d0c10ae2921886caf8e27b8041b411ac1b904c5e3406a0265f11e1f4c54a80ae9fa33994f396ec9adbc0df74c57b2304946df

data/CHANGELOG.md

@@ -7,6 +7,24 @@ For more information about changelogs, check [Keep a Changelog](http://keepachan
 
 ## [Unreleased]
 
+## 0.3.1 - 2026-08-24
+
+* [Fix] Stop asserting the role attributes only a superuser may set, since `NOSUPERUSER`,
+  `NOBYPASSRLS` and `NOREPLICATION` are refused outright by every managed database -- a role is
+  created without them anyway, so they are read back and warned about rather than set
+* [Fix] Run each statement of the grant in a savepoint of its own, so one a database refuses no
+  longer discards the grants, the revocations and both functions behind it
+
+## 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

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: 
@@ -132,6 +147,10 @@ usually does — the role is made by hand and the revocation with it:
 REVOKE SELECT ON omen_readings, omen_questions, omen_answers FROM omen_inquirer;
 ```
 
+A managed database also refuses `ALTER ROLE ... NOSUPERUSER`, since only a superuser may say it.
+Omen skips that statement and carries on rather than stopping, then reads the role back and says
+so if it holds `SUPERUSER`, `BYPASSRLS` or `REPLICATION` -- which a role it created never does.
+
 A missed table there means Claude is shown the log of every question ever asked.
 
 ## License

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/lib/omen/attributes.rb

@@ -0,0 +1,35 @@
+module Omen
+  # What the role a statement runs as may and may not be. A role is created with every dangerous
+  # attribute already off, so this gem sets only what whoever created it may set, and reads the
+  # rest back rather than asserting them: saying `NOSUPERUSER` needs the SUPERUSER attribute, so
+  # a managed database refuses the very statement that would have made the role safe.
+  module Attributes
+    # Set on the role, because whoever may create a role may set these.
+    SETTABLE = 'NOLOGIN NOCREATEDB NOCREATEROLE'
+
+    # Read back instead, since saying no to one of these needs the attribute itself.
+    DANGEROUS = { rolsuper: 'SUPERUSER', rolbypassrls: 'BYPASSRLS',
+                  rolreplication: 'REPLICATION', }
+
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @return [Boolean] whether the role is there at all to be granted anything.
+    def self.exists?(connection) = held(connection).present?
+
+    # Nil where there is no such role, so that an empty list and a missing role read apart.
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @return [Hash, nil] the row of what the role is, or nothing where the role is not.
+    def self.held(connection)
+      connection.select_one <<~SQL.squish
+        SELECT #{DANGEROUS.keys.join ', '} FROM pg_roles
+        WHERE rolname = #{connection.quote Omen.config.narrow_role}
+      SQL
+    end
+
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @return [Array<String>] what the role holds that no reading should be able to reach.
+    def self.dangerous(connection)
+      row = held(connection) || {}
+      DANGEROUS.filter_map { |column, name| name if row[column.to_s] }
+    end
+  end
+end

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

@@ -0,0 +1,39 @@
+module Omen
+  # Everything said to a database to make the role a statement runs as: what it may be, what it
+  # may read, and what it may not. Kept apart from the task that runs them, which is about a
+  # database it has to find and a refusal it has to survive rather than about privileges.
+  module Grants
+    # 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 #{Attributes::SETTABLE}",
+        "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),
+        *Omen::Eastern.statements(connection),
+        *Omen::Distance.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/inquirer.rb

@@ -3,9 +3,6 @@ module Omen
   # 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'
 
@@ -13,6 +10,18 @@ module Omen
     UNGRANTED = 'No %{role} connection is configured, so nothing was granted to whatever ' \
                 'reads through it. Run this again once config/database.yml names one.'
 
+    # Said where the role could not be made: a managed database never grants CREATEROLE.
+    UNMADE = 'Could not make %{role}, so every reading will say this app is misconfigured. Ask ' \
+             'for that role, NOLOGIN, granted SELECT on every table but %{tables}.'
+
+    # Said per statement, since the grants, the revocations and the functions need nothing from
+    # one another and one refusal should not discard the rest.
+    REFUSED = 'Skipped, refused by the database: %{statement} (%{error})'
+
+    # Said where a role that already existed is one a reading should not be able to reach through.
+    DANGEROUS = '%{role} holds %{held}. This gem cannot take that away without being a superuser ' \
+                'itself, so ask for it to be taken away.'
+
     # Creates the role and the function, on every database this environment prepares.
     # @return [void]
     def self.grant
@@ -37,12 +46,26 @@ module Omen
       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}"
+      Grants.statements(connection, members).each { |statement| attempted connection, statement }
+      role = Omen.config.narrow_role
+      return warn UNMADE % { role: role, tables: Omen.tables.to_sentence } unless
+        Attributes.exists? connection
+
+      held = Attributes.dangerous connection
+      warn DANGEROUS % { role: role, held: held.to_sentence } if held.any?
+      puts "Granted SELECT on #{connection.current_database} to #{role}"
+    end
+
+    # One statement at a time, so a database that refuses one still runs the others -- and each
+    # inside a savepoint of its own, since a refusal inside a transaction refuses everything
+    # after it too, and this task is as likely to be run from a console as from a deploy.
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @param statement [String] one of the statements Omen::Grants builds.
+    # @return [void]
+    def self.attempted(connection, statement)
+      connection.transaction(requires_new: true) { connection.execute statement }
     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}"
+      warn REFUSED % { statement: statement.squish, error: error.message.lines.first.strip }
     end
 
     # Discovered rather than named: SET LOCAL ROLE needs the connecting role to be a member of
@@ -55,37 +78,5 @@ module Omen
     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/version.rb

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

data/lib/omen.rb

@@ -1,8 +1,11 @@
 require 'active_job/performs'
 require 'anthropic'
 
+require 'omen/attributes'
 require 'omen/config'
+require 'omen/distance'
 require 'omen/eastern'
+require 'omen/grants'
 require 'omen/inquirer'
 require 'omen/requirements'
 require 'omen/version'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omen
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.3.1
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -97,9 +97,12 @@ files:
 - lib/generators/omen/install/install_generator.rb
 - lib/generators/omen/install/templates/omen.rb
 - lib/omen.rb
+- lib/omen/attributes.rb
 - lib/omen/config.rb
+- lib/omen/distance.rb
 - lib/omen/eastern.rb
 - lib/omen/engine.rb
+- lib/omen/grants.rb
 - lib/omen/inquirer.rb
 - lib/omen/requirements.rb
 - lib/omen/stubs.rb