omen 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74cc1b0decd3387eee021daab85be576723119ec0f26c88751f003d90e7f7e3d
-  data.tar.gz: b3b663b6c907384cebe0c48e1b6165c2ad93755b84a97dd18bb98be9335bee79
+  metadata.gz: 50e0ccd4a4b0c3fa358e235be39a5e79b53fabbcb4e05c09424508cab6be99f9
+  data.tar.gz: 4c4de5e474629c685455a599469c33caff9ae1e646dd331752313bf8c2e00020
 SHA512:
-  metadata.gz: 9bf73eb524e3f0deb67fcb03a6160e6422cb2de14bf4e1406bed2d1d5bce57d205a7a69512a07b475359c04cf4ed4bcda8926be5d64fbbec0f2cd3c46263f310
-  data.tar.gz: 8cea860cccdfd776b81aa26a7e887b5baffa84a0bf674ac9e2e6a07096e57dcccbc3f2ccbf5c9b21de0adf982a42eca370521123fc9690746b86eccf618d4043
+  metadata.gz: 5158631649bc16dbeffbd630ba07303880657e30dd0c15ccba1ebde0a66317985caff827dfa423259d71091f74bf835634fa029050cd554917427784f9ef766e
+  data.tar.gz: 91910028f557c76263c24b7c664aca12e6e89a8f5c009e605e4fd3563f1c39a8bbd35672dc24c3529c800a689b5c62a09a572e3e5e01f5072232ee8acf98db03

data/CHANGELOG.md

@@ -5,7 +5,32 @@ All notable changes to this project will be documented in this file.
 For more information about changelogs, check [Keep a Changelog](http://keepachangelog.com) and
 [Vandamme](http://tech-angels.github.io/vandamme).
 
-## [Unreleased]
+## 0.8.0 - 2026-09-16
+
+* [Feature] Make how a Postgres role is made safely public, so a host builds the read-only role
+  Omen requires with the care Omen builds its own: `Omen::Grants.made` takes `login:`,
+  `Omen::Attributes.dangerous` and `.settable` take the role they are about, and `Omen.attempted`
+  and `Omen.each_database` are the two a host's rake task calls. A host had to hand-write all of
+  it, and the copy in Fountain asserted `NOSUPERUSER` -- which only a superuser may say, so the
+  grant died at its second statement, warned, and left the deploy green for a year
+
+* [Breaking change] `Omen::Attributes.exists?`, `.held` and `.dangerous` take the role to ask
+  about rather than reading `Omen.config.narrow_role`, since a host asks about its own
+
+* [Breaking change] `Omen::Attributes::SETTABLE` no longer carries `NOLOGIN`, which is now the
+  default of `Omen::Attributes.settable login:` -- a role a host connects as needs `LOGIN`
+
+* [Breaking change] `Omen::Inquirer.attempted` is `Omen.attempted` and `Omen::Inquirer::REFUSED`
+  is `Omen::REFUSED`. Neither was ever about the inquirer, and a host calling `Omen::Inquirer`
+  to build its reader read as though the two roles were one
+
+## 0.7.0 - 2026-09-12
+
+* [Bugfix] Keep the columns of an answer in the order the statement asked for them. They were
+  held as `jsonb`, which sorts a row's keys by length, so a page drew them scrambled
+
+* [Breaking change] Carry five turns of a thread rather than twenty, which is what a question
+  usually leans on and what a thread nobody clears can afford to send again every time
 
 ## 0.6.0 - 2026-09-11
 

data/INSTRUCTIONS.md

@@ -104,8 +104,10 @@ end
 - **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`
   and nothing else. Omen raises rather than falling back to a role that could write, which is
-  the point. Creating that role is the app's own business — Omen has no name for it, and
-  discovers it when granting.
+  the point. Naming that role is the app's own business — Omen has none for it, and discovers
+  it when granting — but making one is not, since a managed database refuses half the DDL it
+  takes. `Omen::Grants.made`, `Omen::Attributes.dangerous`, `Omen.attempted` and
+  `Omen.each_database` are public for that, and the README shows the task they add up to.
 - **Active Record Encryption keys.** Without them an encrypted column reads back as the
   placeholder rather than as the value, quietly.
 - **An `ApplicationJob`.** A reading is answered outside the request, and the job descends
@@ -121,7 +123,7 @@ writes it with each line commented out, as the list of what there is to say.
 | Setting | Default |
 |---|---|
 | `narrow_role` | `'omen_inquirer'` |
-| `remembered` | `20`, the turns of a thread that travel with the next question |
+| `remembered` | `5`, the turns of a thread that travel with the next question |
 | `notes` | none, so the prompt says nothing about this app beyond its schema |
 
 ## What a host builds on top

data/README.md

@@ -41,6 +41,32 @@ None of it is Omen's to create, and each is checked rather than assumed:
 - **A read-only connection role**: `connects_to database: { writing: :primary, reading: :reader }`
   on `ApplicationRecord`, where `reader` logs in as a Postgres role granted `SELECT` and nothing
   else. Omen raises rather than falling back to a role that could write, which is the point.
+  Naming that role is yours; making one safely is not, since a managed database refuses half the
+  DDL it takes — so `Omen::Grants.made`, `Omen::Attributes.dangerous`, `Omen.attempted` and
+  `Omen.each_database` are public, and a host's own task is the grants it wants and little else:
+
+      module Reader
+        ROLE = 'your_app_reader'
+
+        def self.grant = Omen.each_database { |connection| grant_on connection }
+
+        def self.grant_on(connection)
+          statements(connection).each { |it| Omen.attempted connection, it }
+          held = Omen::Attributes.dangerous connection, ROLE
+          warn "#{ROLE} holds #{held.to_sentence}" if held.any?
+        end
+
+        def self.statements(connection)
+          role = connection.quote_table_name ROLE
+          Omen::Grants.made(connection, ROLE, login: true) +
+            [ "GRANT SELECT ON ALL TABLES IN SCHEMA public TO #{role}", ... ]
+        end
+      end
+
+  `Omen.attempted` runs each statement in a savepoint and warns rather than raising, so one
+  refusal discards neither the deploy nor the statements behind it. `Omen::Grants.made` asserts
+  only what whoever may create a role may set: saying `NOSUPERUSER` needs the `SUPERUSER`
+  attribute, so it is read back with `Omen::Attributes.dangerous` and warned about instead.
 - **`ANTHROPIC_API_KEY`**, or a key named in the initializer.
 - **Active Record Encryption keys**, without which an encrypted column reads back as a
   placeholder rather than as its value, quietly.

data/db/migrate/20260821120002_create_omen_answers.rb

@@ -2,7 +2,7 @@ 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.json :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

data/db/migrate/20260912100000_keep_the_column_order_of_an_answer.rb

@@ -0,0 +1,5 @@
+class KeepTheColumnOrderOfAnAnswer < ActiveRecord::Migration[8.1]
+  def up
+    change_column :omen_answers, :result, :json, default: [], null: false
+  end
+end

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

@@ -25,7 +25,7 @@ Omen.configure do |config|
 
   # How many turns of a thread travel with the next question. A thread nobody clears would
   # otherwise carry its whole history into each one, and be charged for it again each time.
-  # config.remembered = 20
+  # config.remembered = 5
 
   # Left unset, the Anthropic SDK resolves ANTHROPIC_API_KEY and its own wider chain.
   # config.api_key = Rails.application.credentials.dig :anthropic, :api_key

data/lib/omen/attributes.rb

@@ -1,35 +1,42 @@
 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.
+  # What a Postgres role 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'
+    SETTABLE = 'NOCREATEDB NOCREATEROLE'
 
     # Read back instead, since saying no to one of these needs the attribute itself.
     DANGEROUS = { rolsuper: 'SUPERUSER', rolbypassrls: 'BYPASSRLS',
                   rolreplication: 'REPLICATION', }
 
+    # @param login [Boolean] whether anything connects as the role.
+    # @return [String] what an ALTER ROLE may assert against any database, managed or not.
+    def self.settable(login: false) = "#{login ? 'LOGIN' : 'NOLOGIN'} #{SETTABLE}"
+
     # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @param name [String] the role to ask about.
     # @return [Boolean] whether the role is there at all to be granted anything.
-    def self.exists?(connection) = held(connection).present?
+    def self.exists?(connection, name) = held(connection, name).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.
+    # @param name [String] the role to ask about.
     # @return [Hash, nil] the row of what the role is, or nothing where the role is not.
-    def self.held(connection)
+    def self.held(connection, name)
       connection.select_one <<~SQL.squish
         SELECT #{DANGEROUS.keys.join ', '} FROM pg_roles
-        WHERE rolname = #{connection.quote Omen.config.narrow_role}
+        WHERE rolname = #{connection.quote name}
       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] }
+    # @param name [String] the role to ask about.
+    # @return [Array<String>] what the role holds that no read-only request should reach.
+    def self.dangerous(connection, name)
+      row = held(connection, name) || {}
+      DANGEROUS.filter_map { |column, attribute| attribute if row[column.to_s] }
     end
   end
 end

data/lib/omen/config.rb

@@ -29,7 +29,7 @@ module Omen
       @narrow_role = 'omen_inquirer'
       @claude_model = 'claude-opus-5'
       @maximum_rows = 100
-      @remembered = 20
+      @remembered = 5
       @schema_path = 'db/schema.rb'
     end
 

data/lib/omen/grants.rb

@@ -70,12 +70,14 @@ module Omen
 
     # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
     # @param name [String] the role to make, where the database has not got it.
+    # @param login [Boolean] whether anything connects as it, as a host's reading role does.
     # @return [Array<String>] the statements that make it and say what it may be.
-    def self.made(connection, name)
+    def self.made(connection, name, login: false)
       role = connection.quote_table_name name
+      entered = login ? 'LOGIN' : 'NOLOGIN'
       [ 'DO $$ BEGIN IF NOT EXISTS (SELECT FROM pg_roles WHERE rolname = ' \
-          "#{connection.quote name}) THEN CREATE ROLE #{role} NOLOGIN; END IF; END $$",
-        "ALTER ROLE #{role} WITH #{Attributes::SETTABLE}", ]
+          "#{connection.quote name}) THEN CREATE ROLE #{role} #{entered}; END IF; END $$",
+        "ALTER ROLE #{role} WITH #{Attributes.settable login: login}", ]
     end
 
     # Intersected, so a bare db:create with no table yet to revoke on is not a failure.

data/lib/omen/inquirer.rb

@@ -14,10 +14,6 @@ module Omen
     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 group, 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.'
@@ -32,7 +28,7 @@ module Omen
     def self.widen
       Omen.each_database do |connection|
         Omen::Reading.narrowings.each do |narrowing|
-          narrowing.widening(connection).each { |group| attempted connection, *group }
+          narrowing.widening(connection).each { |group| Omen.attempted connection, *group }
           puts "Widened #{connection.current_database} back out of #{narrowing.role}"
         end
       end
@@ -46,12 +42,12 @@ module Omen
       read_by = reader
       warn UNGRANTED % { role: Omen.config.reading_role } unless read_by
       members = [ read_by, connection.select_value(WHOEVER) ].compact
-      Grants.statements(connection, members).each { |statement| attempted connection, statement }
+      Grants.statements(connection, members).each { |it| Omen.attempted connection, it }
       role = Omen.config.narrow_role
       return warn UNMADE % { role: role, tables: Omen.tables.to_sentence } unless
-        Attributes.exists? connection
+        Attributes.exists? connection, role
 
-      held = Attributes.dangerous connection
+      held = Attributes.dangerous connection, role
       warn DANGEROUS % { role: role, held: held.to_sentence } if held.any?
       puts "Granted SELECT on #{connection.current_database} to #{role}"
       narrow connection, members
@@ -63,27 +59,11 @@ module Omen
     # @return [void]
     def self.narrow(connection, members)
       Omen::Reading.narrowings.each do |narrowing|
-        narrowing.statements(connection, members).each { |group| attempted connection, *group }
+        narrowing.statements(connection, members).each { |group| Omen.attempted connection, *group }
         puts "Narrowed #{narrowing.role} to the rows #{narrowing.setting} names"
       end
     end
 
-    # A group 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. What arrives
-    # together is applied together: a table is never left with row level security on and no
-    # policy under it.
-    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
-    # @param statements [Array<String>] what Omen::Grants or a narrowing built.
-    # @return [void]
-    def self.attempted(connection, *statements)
-      connection.transaction(requires_new: true) do
-        statements.each { |statement| connection.execute statement }
-      end
-    rescue ActiveRecord::StatementInvalid => error
-      warn REFUSED % { statement: statements.first.squish, error: error.message.lines.first.strip }
-    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.

data/lib/omen/version.rb

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

data/lib/omen.rb

@@ -27,9 +27,27 @@ module Omen
   # @return [void]
   def self.configure = yield config
 
+  # Said where a database refuses one group, since the groups need nothing from one another.
+  REFUSED = 'Skipped, refused by the database: %{statement} (%{error})'
+
   # @return [Array<String>] the environments whose databases a grant should cover.
   def self.environments = Rails.env.development? ? %w[ development test ] : [Rails.env.to_s]
 
+  # A savepoint each and a warning rather than a raise, so a statement a managed database
+  # refuses discards neither the deploy nor the statements behind it -- and what arrives
+  # together is applied together, since a table is never left with row level security on and
+  # no policy under it.
+  # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+  # @param statements [Array<String>] what to run, all of it or none of it.
+  # @return [void]
+  def self.attempted(connection, *statements)
+    connection.transaction(requires_new: true) do
+      statements.each { |statement| connection.execute statement }
+    end
+  rescue ActiveRecord::StatementInvalid => error
+    warn REFUSED % { statement: statements.first.squish, error: error.message.lines.first.strip }
+  end
+
   # @yield [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing connection to each
   #   database this environment prepares.
   # @return [void]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omen
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -99,6 +99,7 @@ files:
 - db/migrate/20260821120001_create_omen_questions.rb
 - db/migrate/20260821120002_create_omen_answers.rb
 - db/migrate/20260912000000_add_type_to_omen_readings.rb
+- db/migrate/20260912100000_keep_the_column_order_of_an_answer.rb
 - lib/generators/omen/install/install_generator.rb
 - lib/generators/omen/install/templates/omen.rb
 - lib/generators/omen/pages/USAGE