omen 0.3.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f96e34cbde627e0781a12488ba4308d704c6896a71fc44b031b7d412512c22eb
-  data.tar.gz: 408ad7c0b4a13f8ef3aef1b1c271e81ac116791ff627ffa2d056f5ecb6c45e34
+  metadata.gz: 38d16f1a8a34b75c8ec0c68256c468a1964433fd7700c3d70cac77a442d112a5
+  data.tar.gz: de2689fb094379753948c4e7d8a98446b92e7870ea52ec26448f4e9dae19cc04
 SHA512:
-  metadata.gz: fd53d5b7acb9fea6560bf0edbd5e1fb8f26200d99edaa52dfd9a81c9945dbd154a69514a7ba0028a025f36284bbd04be01e7aa57df61b7c01fa68ceb974638fd
-  data.tar.gz: a5b4226127e861f2600ebf62eb1d0c10ae2921886caf8e27b8041b411ac1b904c5e3406a0265f11e1f4c54a80ae9fa33994f396ec9adbc0df74c57b2304946df
+  metadata.gz: 0d53e0fffd2be50f0ed33c9def0f59df816dc6de58be56b9ad0a4397a0d9f4ad5f778c6b046938b85f0cad3e31b32346ee0e395084a29938116d1aa4b553b486
+  data.tar.gz: 410c8befd10808099f1d07969b2197a6212b8a26c3a064788f60d5e828a37d4b9b254a32709171c84e35479183a30f7c6c55b90d8ec922704ee174b9afbf8629

data/CHANGELOG.md

@@ -7,6 +7,48 @@ 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
+  had: `eastern` is now `omen_time_zone`, `miles_between` is `omen_miles_between`. A statement
+  stored before this names the old ones, so re-running one fails rather than answering from a
+  function nothing maintains -- an answer already drawn is unaffected, since its rows are stored
+  rather than recomputed
+* [Feature] Create `omen_today()` and tell Claude to build every relative window on it, so a
+  statement kept and run again answers "last month" for the month it is run in rather than the
+  month it was written in. `STABLE`, and a date rather than a timestamp
+* [Feature] Ask for a note that says a sliding window the way the statement says it, and then
+  what it comes to today, so a stored note does not stop being true on the second run
+
 ## 0.3.1 - 2026-08-24
 
 * [Fix] Stop asserting the role attributes only a superuser may set, since `NOSUPERUSER`,

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,157 +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 major:
+In your `Gemfile`, pinned to the current minor while this is still below 1.0:
 
 ```ruby
-gem 'omen', '~> 0.2'
+gem 'omen', '~> 0.5.0'
 ```
 
-Omen follows [Semantic Versioning](https://semver.org), so `~> major.minor` means `bundle update`
-never crosses a breaking change.
-
-## 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>
-
-**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: 
+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.
@@ -31,19 +31,32 @@ have made it, and switching quote style to avoid an apostrophe is how you make i
 
 ## Reading the schema
 
-Timestamps are stored in UTC, and `%{eastern}()` is the one way to read one: it hands the same
+Timestamps are stored in UTC, and `%{zone_fn}()` is the one way to read one: it hands the same
 moment back in the zone the company works in. Wrap every timestamp you touch in it -- in a
 `WHERE`, in an `ORDER BY`, in a `GROUP BY`, and in a column you return -- so a question about a
-day, a week or a month means whole days here: `date_trunc('day', %{eastern}(created_at))`. Never
+day, a week or a month means whole days here: `date_trunc('day', %{zone_fn}(created_at))`. Never
 write a conversion of your own.
 
-Today is %{today}. Resolve every relative date yourself; the query has no idea what "last
-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.
+Today is %{today}, and `%{today_fn}()` is that same day asked of the database. Use it for every
+window a question describes in relation to now:
+
+```sql
+WHERE %{zone_fn}(created_at) >= date_trunc('month', %{today_fn}()) - interval '1 month'
+  AND %{zone_fn}(created_at) <  date_trunc('month', %{today_fn}())
+```
+
+Write it that way rather than working the dates out and putting them in, because a statement is
+kept and run again: one carrying `'2026-08-01'` answers a question nobody asked the second time,
+where one carrying `%{today_fn}()` still answers "last month" whenever it is run. A window a
+question names outright -- "in July 2026", "since the 3rd" -- is not relative to now, and keeps
+its literal dates.
+
+Never `now()`, `current_date` or `current_timestamp`: those are the machine's clock in the
+machine's zone. `%{today_fn}()` is the company's day, and it is a date, so it needs no truncating.
 
 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
+`%{miles_fn}(lat1, lng1, lat2, lng2)`, so a radius reads
+`WHERE %{miles_fn}(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.
 
@@ -100,7 +113,11 @@ 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
+moment the statement is run again.
 
 ## The schema