omen 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dd517ec9c5893a92f285613782d245ef9573bb83c8ef78378510f49a208626fc
-  data.tar.gz: 5d5f97f73bd6cf0b423f9264426522aee942df7ab4fb622e3442b75493da29c0
+  metadata.gz: 38d16f1a8a34b75c8ec0c68256c468a1964433fd7700c3d70cac77a442d112a5
+  data.tar.gz: de2689fb094379753948c4e7d8a98446b92e7870ea52ec26448f4e9dae19cc04
 SHA512:
-  metadata.gz: f383e42b3c7e9fdd06f7c69c6ef7fd8563cb55f47db66583ee07c656b56bfabe6217972c63c89596db5407a96af4e8080f71e3561e7ee188a507c74d9ff28404
-  data.tar.gz: a8894e28c75abeeb62cd139ead7bf0abca83593a49c89bae50273dbe178016ef6cf915179a07355b4b7af38f4f17c06efc2e57f597e949637bf5f7528fbce8a7
+  metadata.gz: 0d53e0fffd2be50f0ed33c9def0f59df816dc6de58be56b9ad0a4397a0d9f4ad5f778c6b046938b85f0cad3e31b32346ee0e395084a29938116d1aa4b553b486
+  data.tar.gz: 410c8befd10808099f1d07969b2197a6212b8a26c3a064788f60d5e828a37d4b9b254a32709171c84e35479183a30f7c6c55b90d8ec922704ee174b9afbf8629

data/CHANGELOG.md

@@ -7,6 +7,35 @@ For more information about changelogs, check [Keep a Changelog](http://keepachan
 
 ## [Unreleased]
 
+## 0.5.0 - 2026-09-11
+
+* [Breaking change] `omen_readings` carries a `type` column, so a host's two kinds of reading
+  are two classes rather than two names for the same rows. Without it the class that loaded a
+  row decided what it could read: a customer's own reading, loaded as the host's admin one, ran
+  its statement as the wider role. Rows written before this migration have no type and come
+  back as `Omen::Reading`, so a host with subclasses backfills its own -- one `UPDATE` per kind
+* [Feature] Narrow a reading to one owner's rows. A subclass declares what its audience may
+  read -- `narrows 'the_role', by: :provider_id, own: { 'bookings' => 'provider_id = %{owner}' },
+  whole: %w[ zips ]` -- and `db:omen:grant` writes the role, the column grants and the policies.
+  The rows are held by Postgres, so every statement Claude can write resolves through them
+* [Feature] Turning row level security on takes nothing away from whoever could already read: a
+  permissive policy for everybody goes on beside a RESTRICTIVE one for the narrowed role, which
+  is ANDed with it and applies to nobody else -- a role made after the fact included
+* [Feature] Grant the membership a narrowed role needs `WITH INHERIT FALSE`, so a role that may
+  enter it is not itself held back by its policies. Postgres 16 and later
+* [Feature] `db:omen:widen` takes every narrowing back off, and `db:omen:narrowed` says which
+  roles each restrictive policy really holds back, membership included, and exits non-zero on
+  one nobody asked for
+* [Feature] Show Claude the schema the role may actually read: a table none of whose columns it
+  holds `SELECT` on goes, and so does a column a column-level grant left out, so the prompt
+  follows the grants rather than restating them
+* [Fix] Revoke before granting a role the columns of a table, since a grant only ever adds: a
+  column dropped from the list used to stay readable by whoever was granted it last time
+* [Breaking change] `Omen::Query.new` and `Omen::Conversation.new` take the reading they answer,
+  and `Omen::Instructions.block` and `Omen::Schema.new` take what it says they may read
+* [Breaking change] The shape a reply is held to is `Omen::Reply::SHAPE`, and the config that
+  sends it `Omen::Reply.output_config`, both moved off `Omen::Instructions`
+
 ## 0.4.0 - 2026-08-24
 
 * [Breaking change] Prefix every database function this gem creates, and drop the names they

data/INSTRUCTIONS.md

@@ -0,0 +1,225 @@
+# Omen, in full
+
+Everything there is to say about installing Omen and building on it. The [README](README.md) is
+the short way in; this is the reasoning underneath it, and the place to come when a default
+turns out not to suit.
+
+You ask Claude a complex question about data stored by your Rails app.
+Claude answers with the SQL. Rails runs 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.
+
+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
+
+```sh
+gem install omen
+```
+
+Or, in a `Gemfile`, pinned to the current minor while this is still below 1.0:
+
+```ruby
+gem 'omen', '~> 0.4.0'
+```
+
+Omen follows [Semantic Versioning](https://semver.org) from 1.0 onwards. Until then a release may
+break whatever it likes, so the pin stops short of the next minor: `~> 0.4.0` takes every fix in
+0.4 and nothing beyond it.
+
+## Requirements
+
+**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>
+
+**Three database functions, all prefixed** 
+
+<details>
+  <summary>A timestamp, a day and a distance go through a function, never an expression. </summary>
+  `db:omen:grant` creates all three, each named `omen_` so that none of them can take a name an
+  app wanted for itself -- `today` especially. `omen_time_zone()` hands a stored timestamp back in
+  the zone the company works in, so every date means the same whole days. `omen_today()` answers
+  what day it is there, and the prompt builds every relative window on it, so a statement that is
+  kept and run again answers "last month" for the month it is run in rather than the month it was
+  written in. `omen_miles_between(lat1, lng1, lat2, lng2)` answers a great-circle distance in
+  miles. The prompt names each and forbids writing any of them 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. The first and last are `IMMUTABLE`; `omen_today()` is `STABLE`, because
+  it reads the clock and an immutable function of the clock may be folded to a constant -- which
+  is exactly the sliding this one exists to keep. All are executable by anyone, so none needs a
+  grant. An app in another zone renames the first two; an app whose tables carry no coordinates
+  never calls the last. None 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: 
+
+```sh
+bin/rails g omen:install # adds the 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
+missing the role. In `lib/tasks` of the host:
+
+```ruby
+granted = Rake::Task['db:omen:grant']
+
+%w[ db:create db:prepare db:reset db:test:prepare ].each do |name|
+  Rake::Task[name].enhance do
+    granted.reenable
+    granted.invoke
+  end
+end
+```
+
+### 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`
+  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.
+- **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
+  from the app's own base class.
+- **A `db/schema.rb`.** It is the prompt, so a reading cannot happen before the first
+  `db:migrate` has dumped one.
+
+### The options
+
+Every setting has a default, so the initializer is optional. `rails generate omen:install`
+writes it with each line commented out, as the list of what there is to say.
+
+| Setting | Default |
+|---|---|
+| `narrow_role` | `'omen_inquirer'` |
+| `notes` | none, so the prompt says nothing about this app beyond its schema |
+
+## What a host builds on top
+
+`Omen::Reading` has a `type` column nowhere, so a subclass is a transparent second name for the
+same rows: `Inquiry.all` carries no type condition, and `to_partial_path` becomes
+`inquiries/inquiry`.
+
+```ruby
+class Inquiry < Omen::Reading
+  belongs_to :agent
+end
+```
+
+`Omen::Reading.create! question: 'Where are the homes we serve?'` is the whole of asking; a
+follow-up is `reading.ask '...'`. Each question is answered in a job, and the answer carries the
+statement Claude wrote, the rows it found, and which header of theirs held an encrypted column.
+
+Two things a subclass cannot reach, because the gem's own class is what a job loads:
+`broadcasts_refreshes`, and anything else that has to be declared on `Omen::Reading` itself. One
+line in the host does it, and `rails g omen:pages` below writes that line where there is a Turbo
+to broadcast over:
+
+```ruby
+ActiveSupport.on_load(:omen_reading) { broadcasts_refreshes }
+```
+
+## Putting it on a screen
+
+Omen ships no controllers, no views and no routes, and there is no engine to mount: what a
+reading looks like belongs to the app that installs it. What it takes to *draw* one is the gem's
+own business, though, and a fourth command hands that over:
+
+```sh
+bin/rails g omen:pages
+```
+
+```
+      create  app/models/inquiry.rb
+      create  app/controllers/inquiries_controller.rb
+      create  app/views/inquiries/index.html.erb
+      create  app/views/inquiries/show.html.erb
+      create  app/views/inquiries/_form.html.erb
+       route  resources :inquiries
+```
+
+`bin/rails s`, then `/inquiries`. Type a question and the answer arrives under it, with the
+statement Claude wrote and the rows it found. Every one of those files lands in the host and is
+the host's from then on -- rename them, restyle them, throw them away. Pass a name to be called
+something else: `bin/rails g omen:pages Consultation` writes `Consultation`,
+`ConsultationsController` and `app/views/consultations`.
+
+The generator exists because four of the things those files get right are things nobody should
+have to learn before their first question:
+
+- **The controller descends from `ApplicationController`**, so whatever guards the rest of the
+  app guards the one page that will run SQL across all of it. This is the reason the pages are
+  generated into the host rather than mounted from the gem: a mounted engine inherits none of
+  the app's `before_action`, and forgetting to say so publishes an ask-anything console.
+- **There is no `new` and no `edit`.** Opening a reading is asking its first question, so
+  `create` is the only way in and a blank one has no page; and a reading is never edited, so
+  `update` calls `ask` and the thread grows by one. `question` is an attribute, not a column --
+  an `edit` form would rewrite something nothing reads back.
+- **The rows come from `answer.shown`, never `answer.result`.** The second is what Postgres
+  handed over; the first is that read back through Active Record Encryption, with the columns
+  Claude asked to be drawn joined. An answer with no `sql` is Claude asking something back, and
+  `note` is where it says so.
+- **The refresh is subscribed to as `Omen::Reading`.** Where the host has Turbo, `show` gets
+  `turbo_stream_from @inquiry.becomes(Omen::Reading)` and a `config/initializers/omen_broadcasts.rb`
+  is written beside it declaring `broadcasts_refreshes`. Both name the gem's class and not
+  `Inquiry`, because a question reaches its reading through the association: what a job is
+  handed, and so what it broadcasts as, is always `Omen::Reading`. A stream named after the
+  subclass hears nothing. Where there is no Turbo neither line is written, and a reload is what
+  shows an answer.
+
+What the generator cannot do for you is the part above: `ANTHROPIC_API_KEY` has to be
+resolvable, `db:omen:grant` has to have run, and `config/database.yml` has to have the read-only
+entry that `connects_to` names. The two are missed differently, which is why the `show` page
+draws both -- a reading that could not reach Claude at all is left `failed`, with the class of
+what went wrong in the log and nothing in the page, since a message from that far down may quote
+a row; a reading whose statement had no role to run as is answered, with
+`Omen::Role::MISCONFIGURED` in `answer.error`.
+
+## After the first deploy
+
+The narrow role is granted `SELECT` on every table and then refused Omen's own three, which can
+only happen once those tables exist. On a database that forbids `CREATE ROLE` — a managed one
+usually does — the role is made by hand and the revocation with it:
+
+```sql
+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
+
+MIT, see [LICENSE.txt](LICENSE.txt).

data/README.md

@@ -1,163 +1,121 @@
 # Omen
 
-You ask Claude a complex question about data stored by your Rails app.
+You ask Claude a complex question about the data your Rails app already holds.
 Claude answers with the SQL. Rails runs 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 demo goes here. Drop the recording in as demo.gif at the root of the repo and
+     uncomment the line below:
 
-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.
+![Asking Omen a question inside a Rails app](demo.gif)
+-->
 
-## How to install
+Your data never travels. Claude is shown the schema and writes one `SELECT`; Rails runs it
+read-only and draws the answer -- encrypted columns included -- for whoever asked. Nothing that
+statement returned is ever sent back.
 
-```sh
-gem install omen
-```
+## Running it
 
-Or, in a `Gemfile`, pinned to the current minor while this is still below 1.0:
+In your `Gemfile`, pinned to the current minor while this is still below 1.0:
 
 ```ruby
-gem 'omen', '~> 0.4.0'
+gem 'omen', '~> 0.5.0'
 ```
 
-Omen follows [Semantic Versioning](https://semver.org) from 1.0 onwards. Until then a release may
-break whatever it likes, so the pin stops short of the next minor: `~> 0.4.0` takes every fix in
-0.4 and nothing beyond it.
-
-## Requirements
-
-**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>
-
-**Three database functions, all prefixed** 
-
-<details>
-  <summary>A timestamp, a day and a distance go through a function, never an expression. </summary>
-  `db:omen:grant` creates all three, each named `omen_` so that none of them can take a name an
-  app wanted for itself -- `today` especially. `omen_time_zone()` hands a stored timestamp back in
-  the zone the company works in, so every date means the same whole days. `omen_today()` answers
-  what day it is there, and the prompt builds every relative window on it, so a statement that is
-  kept and run again answers "last month" for the month it is run in rather than the month it was
-  written in. `omen_miles_between(lat1, lng1, lat2, lng2)` answers a great-circle distance in
-  miles. The prompt names each and forbids writing any of them 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. The first and last are `IMMUTABLE`; `omen_today()` is `STABLE`, because
-  it reads the clock and an immutable function of the clock may be folded to a constant -- which
-  is exactly the sliding this one exists to keep. All are executable by anyone, so none needs a
-  grant. An app in another zone renames the first two; an app whose tables carry no coordinates
-  never calls the last. None 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: 
+Then four commands:
 
 ```sh
-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
+bin/rails g omen:install   # the migrations and an initializer you may delete
+bin/rails db:migrate       # omen_readings, omen_questions, omen_answers
+bin/rails db:omen:grant    # the read-only role a statement runs as, and three functions
+bin/rails g omen:pages     # a model, a controller, three views and a route, all yours
 ```
 
-`db:omen:grant` is worth running from the tasks that build a database, so a fresh one is never
-missing the role. In `lib/tasks` of the host:
-
-```ruby
-granted = Rake::Task['db:omen:grant']
-
-%w[ db:create db:prepare db:reset db:test:prepare ].each do |name|
-  Rake::Task[name].enhance do
-    granted.reenable
-    granted.invoke
-  end
-end
-```
+`bin/rails s`, then `/inquiries`. Type a question and the answer arrives under it, with the
+statement Claude wrote and the rows it found.
 
-### Requirements
+## What your app has to have first
 
-- **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.
-- **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
-  from the app's own base class.
-- **A `db/schema.rb`.** It is the prompt, so a reading cannot happen before the first
-  `db:migrate` has dumped one.
+None of it is Omen's to create, and each is checked rather than assumed:
 
-### The options
+- **PostgreSQL**, and a `db/schema.rb` rather than a `structure.sql`. Both are raised on at boot.
+- **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.
+- **`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.
+- **An `ApplicationJob`**, since a reading is answered outside the request.
 
-Every setting has a default, so the initializer is optional. `rails generate omen:install`
-writes it with each line commented out, as the list of what there is to say.
+## What you get
 
-| Setting | Default |
-|---|---|
-| `narrow_role` | `'omen_inquirer'` |
-| `notes` | none, so the prompt says nothing about this app beyond its schema |
+`Omen::Reading.create! question: 'Where are the homes we serve?'` is the whole of asking, and
+`reading.ask '...'` is a follow-up. Each question is answered in a job, and the answer carries
+the statement Claude wrote, the rows it found, and which of their headers held an encrypted
+column. `rails g omen:pages` writes the pages that draw all of that, into your app, for you to
+keep or replace.
 
-## What a host builds on top
+## Two kinds of reading
 
-`Omen::Reading` has a `type` column nowhere, so a subclass is a transparent second name for the
-same rows: `Inquiry.all` carries no type condition, and `to_partial_path` becomes
-`inquiries/inquiry`.
+`omen_readings` carries a `type`, so a subclass of `Omen::Reading` is a kind of reading rather
+than a second name for every row: `Inquiry.count` counts inquiries, and a row answers as what it
+was written as, whatever class asks for it. That last part is what keeps a narrowing honest --
+what a reading may read is the row's own to say, not the caller's.
 
-```ruby
-class Inquiry < Omen::Reading
-  belongs_to :agent
-end
-```
+Upgrading an app that already has readings: they were written without a type, so they come back
+as `Omen::Reading` until you say what they were. One `UPDATE omen_readings SET type = 'Inquiry'`
+per kind, in a migration of your own.
 
-`Omen::Reading.create! question: 'Where are the homes we serve?'` is the whole of asking; a
-follow-up is `reading.ask '...'`. Each question is answered in a job, and the answer carries the
-statement Claude wrote, the rows it found, and which header of theirs held an encrypted column.
+## Narrowing a reading to one owner's rows
 
-Two things a subclass cannot reach, because the gem's own class is what a job loads:
-`broadcasts_refreshes`, and anything else that has to be declared on `Omen::Reading` itself. One
-line in the host does it:
+A reading answers with whatever its role may read, so an app that lets a customer ask about
+their own data says so on the reading, and `db:omen:grant` writes it into the database:
 
 ```ruby
-ActiveSupport.on_load(:omen_reading) { broadcasts_refreshes }
-```
+class Consult < Omen::Reading
+  belongs_to :provider
 
-## After the first deploy
+  narrows 'provider_inquirer', by: :provider_id,
+    own: {
+      'bookings' => 'provider_id = %{owner}',
+      'locations' => 'EXISTS (SELECT 1 FROM bookings WHERE bookings.location_id = locations.id)',
+    },
+    whole: %w[ states zips ], except: /_count\z/
 
-The narrow role is granted `SELECT` on every table and then refused Omen's own three, which can
-only happen once those tables exist. On a database that forbids `CREATE ROLE` — a managed one
-usually does — the role is made by hand and the revocation with it:
-
-```sql
-REVOKE SELECT ON omen_readings, omen_questions, omen_answers FROM omen_inquirer;
+  def notes = Rails.root.join('config/provider_notes.md').read
+end
 ```
 
-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.
+`own` is every table it reads rows of, and what makes a row its own -- `%{owner}` stands for
+whoever the reading names, and a table reaching through another needs no owner of its own, since
+the policy on the table it reaches through has already run. `whole` is read entire, because
+nothing in those tables is anybody's; `except` is the columns of those it may not read, a counter
+over everybody being the case it exists for. A credential is refused everywhere, by name, without
+being asked for.
+
+What that buys is that it does not matter what SQL Claude writes -- a join, a `WITH`, a `UNION`,
+a subquery on a table it was never shown -- every path resolves through the policy, and rows
+outside it do not exist for that role. The reading's own row says who it is: the setting is `SET
+LOCAL` inside the transaction the statement runs in, and gone with it. A reading that names
+nobody reads nothing.
+
+### What it does not take away
+
+Row level security binds every role but a table's owner, so turning it on could empty a table for
+everybody else. It does not: each table gets a permissive policy for everybody beside the
+`RESTRICTIVE` one for the narrowed role, which is ANDed with it and applies to nobody else -- a
+role created afterwards included. The membership that lets a role enter the narrowed one is
+granted `WITH INHERIT FALSE` (Postgres 16 and later) so that entering it is not the same as being
+held back by it.
+
+`db:omen:narrowed` says which roles each restrictive policy really holds back, membership and all,
+and exits non-zero on one nobody asked for -- worth running in CI, since an over-narrowed role
+reads empty rather than raising. `db:omen:widen` takes it all back off.
+
+## Everything else
+
+[INSTRUCTIONS.md](INSTRUCTIONS.md) has the reasoning: why Postgres and no other adapter, what
+`db:omen:grant` creates and what to do on a managed database that forbids it, every setting and
+its default, what the generated pages get right and why, and what a host can build on top.
 
 ## License
 

data/app/models/omen/conversation.rb

@@ -15,16 +15,18 @@ class Omen::Conversation
 
   # @param questions [ActiveRecord::Relation] the questions asked so far, oldest first, up to
   #   and including the one being answered.
-  def initialize(questions)
+  # @param reading [Omen::Reading] the one they were asked of, which says what it may read.
+  def initialize(questions, reading)
     @questions = questions
+    @reading = reading
   end
 
   # No tools are sent, by design: a tool_result block would be rows travelling back to Claude.
   # @return [Hash] the blocks Claude answered with, why it stopped, and what it cost.
   def advance
     said = client.messages.create model: Omen.config.claude_model, max_tokens: MAX_TOKENS,
-      system_: Omen::Instructions.block, messages: messages,
-      output_config: Omen::Instructions.output_config
+      system_: Omen::Instructions.block(@reading), messages: messages,
+      output_config: Omen::Reply.output_config
 
     { content: said.content.map { |block| block.to_h.deep_stringify_keys },
       stop_reason: said.stop_reason, input_usage: said.usage.input_tokens,

data/app/models/omen/executed.rb

@@ -18,7 +18,7 @@ private
   end
 
   def answer(question)
-    reply = Omen::Conversation.new(asked_up_to question).advance
+    reply = Omen::Conversation.new(asked_up_to(question), self).advance
     increment! :input_usage, reply[:input_usage]
     increment! :output_usage, reply[:output_usage]
     execute question.create_answer!(**reply)
@@ -29,7 +29,7 @@ private
   def execute(answered)
     return if answered.sql.blank?
 
-    answered.update! Omen::Query.new(answered.sql).answer
+    answered.update! Omen::Query.new(answered.sql, self).answer
   rescue Omen::Role::Unavailable => error
     answered.update! error: error.message
   rescue StandardError => error

data/app/models/omen/instructions.md

@@ -1,4 +1,4 @@
-You answer questions about the data an app holds, for the staff who run it.
+You answer questions about the data an app holds, for the person who asked.
 
 You answer by writing **one PostgreSQL SELECT** against the schema at the end of this message,
 and a short note about it. Nothing else runs.
@@ -113,7 +113,7 @@ into `note`. Do not guess. A question with no date range, on data that spans yea
 one of those.
 
 Otherwise keep the note to a sentence or two: what the query returns, and any assumption you
-made. These are colleagues reading quickly, not a report.
+made. This is somebody reading quickly, not a report.
 
 Say a sliding window the way the statement says it, and then what it comes to today: "in the
 previous calendar month (July 2026)". A note reading "in July 2026" alone stops being true the

data/app/models/omen/instructions.rb

@@ -1,4 +1,4 @@
-# Everything Claude is told before a question: the prose, the schema, and the shape of a reply.
+# Everything Claude is told before a question: the prose, and the schema it may write against.
 class Omen::Instructions
   # The prose, kept beside this class so it reads as prose rather than as a string.
   PROSE = File.expand_path 'instructions.md', __dir__
@@ -13,28 +13,16 @@ class Omen::Instructions
   # The database function a distance in miles is measured with, created by the same task.
   MILES = 'omen_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 ],
-    properties: {
-      sql: { type: 'string',
-             description: 'The one PostgreSQL SELECT that answers the question, or ' \
-                          'empty to ask something first.', },
-      note: { type: 'string',
-              description: 'A sentence or two: what the query returns and any ' \
-                           'assumption made. If sql is empty, the question you ' \
-                           'need answered first.', },
-      combine: Omen::Combination::SCHEMA,
-    },
-  }
-
-  # @return [Hash] what a reply is constrained to, so that it always parses.
-  def self.output_config = { format_: { type: :json_schema, schema: ANSWER } }
-
   # Cached for an hour: the schema is thousands of tokens, and refining sends it again.
+  # @param reading [Omen::Reading] the one being answered, which says what it may read.
   # @return [Array<Hash>] the one system block of a request.
-  def self.block
-    [ { type: 'text', text: new.text, cache_control: { type: 'ephemeral', ttl: '1h' } } ]
+  def self.block(reading)
+    [ { type: 'text', text: new(reading).text, cache_control: { type: 'ephemeral', ttl: '1h' } } ]
+  end
+
+  # @param reading [Omen::Reading] the one being answered, which says what it may read.
+  def initialize(reading)
+    @reading = reading
   end
 
   # Today's date is said out loud because "last month" is Claude's to resolve, and it has no clock.
@@ -43,17 +31,20 @@ class Omen::Instructions
     format File.read(PROSE), today: Date.current.to_fs(:long), zone_fn: TIME_ZONE,
       today_fn: TODAY, miles_fn: MILES,
       schema: schema, types: types, readable: readable, refused: refused,
-      notes: Omen.config.notes
+      notes: @reading.notes
   end
 
 private
 
-  def schema = Omen::Schema.new.text
+  def schema = Omen::Schema.new(@reading.runs_as).text
 
+  # This gem's own tables are told apart by a type column too, and are hidden from the schema,
+  # so naming their subclasses here would say the one thing the schema is careful not to.
   def types
     Rails.application.eager_load!
     Omen.config.record.descendants.select(&:finder_needs_type_condition?)
-      .group_by(&:table_name).sort.map { |table, kinds| "- `#{table}`: #{named kinds}" }.join "\n"
+      .group_by(&:table_name).except(*Omen.tables).sort
+      .map { |table, kinds| "- `#{table}`: #{named kinds}" }.join "\n"
   end
 
   def named(kinds) = kinds.map(&:name).sort.map { |name| "`#{name}`" }.join ', '