omen 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f96e34cbde627e0781a12488ba4308d704c6896a71fc44b031b7d412512c22eb
-  data.tar.gz: 408ad7c0b4a13f8ef3aef1b1c271e81ac116791ff627ffa2d056f5ecb6c45e34
+  metadata.gz: dd517ec9c5893a92f285613782d245ef9573bb83c8ef78378510f49a208626fc
+  data.tar.gz: 5d5f97f73bd6cf0b423f9264426522aee942df7ab4fb622e3442b75493da29c0
 SHA512:
-  metadata.gz: fd53d5b7acb9fea6560bf0edbd5e1fb8f26200d99edaa52dfd9a81c9945dbd154a69514a7ba0028a025f36284bbd04be01e7aa57df61b7c01fa68ceb974638fd
-  data.tar.gz: a5b4226127e861f2600ebf62eb1d0c10ae2921886caf8e27b8041b411ac1b904c5e3406a0265f11e1f4c54a80ae9fa33994f396ec9adbc0df74c57b2304946df
+  metadata.gz: f383e42b3c7e9fdd06f7c69c6ef7fd8563cb55f47db66583ee07c656b56bfabe6217972c63c89596db5407a96af4e8080f71e3561e7ee188a507c74d9ff28404
+  data.tar.gz: a8894e28c75abeeb62cd139ead7bf0abca83593a49c89bae50273dbe178016ef6cf915179a07355b4b7af38f4f17c06efc2e57f597e949637bf5f7528fbce8a7

data/CHANGELOG.md

@@ -7,6 +7,19 @@ For more information about changelogs, check [Keep a Changelog](http://keepachan
 
 ## [Unreleased]
 
+## 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/README.md

@@ -15,14 +15,15 @@ draws the answer (including encrypted attributes) for whoever asked. Nothing tha
 gem install omen
 ```
 
-Or, in a `Gemfile`, pinned to the current major:
+Or, in a `Gemfile`, pinned to the current minor while this is still below 1.0:
 
 ```ruby
-gem 'omen', '~> 0.2'
+gem 'omen', '~> 0.4.0'
 ```
 
-Omen follows [Semantic Versioning](https://semver.org), so `~> major.minor` means `bundle update`
-never crosses a breaking change.
+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
 
@@ -50,18 +51,23 @@ never crosses a breaking change.
   question ever asked.
 </details>
 
-**Two database functions** 
+**Three database functions, all prefixed** 
 
 <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,
+  <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>
 

data/app/models/omen/instructions.md

@@ -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.
 
@@ -102,6 +115,10 @@ 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.
 
+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
 
 ```ruby

data/app/models/omen/instructions.rb

@@ -4,10 +4,14 @@ class Omen::Instructions
   PROSE = File.expand_path 'instructions.md', __dir__
 
   # The database function a stored timestamp is read through, created by the gem's rake task.
-  EASTERN = 'eastern'
+  # Every one of these is prefixed, since `today` especially is a name a host may want itself.
+  TIME_ZONE = 'omen_time_zone'
+
+  # The database function that answers what day it is where the company works.
+  TODAY = 'omen_today'
 
   # The database function a distance in miles is measured with, created by the same task.
-  MILES = 'miles_between'
+  MILES = 'omen_miles_between'
 
   # The one shape a reply may take: both keys required, and no others admitted.
   ANSWER = {
@@ -36,7 +40,8 @@ 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, miles: MILES,
+    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
   end

data/lib/omen/distance.rb

@@ -1,6 +1,6 @@
 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
+  # than by a migration, for the reason Omen::TimeZone 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.

data/lib/omen/grants.rb

@@ -21,7 +21,8 @@ module Omen
         "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::Renamed.statements,
+        *Omen::TimeZone.statements(connection),
         *Omen::Distance.statements(connection),
       ]
     end

data/lib/omen/renamed.rb

@@ -0,0 +1,17 @@
+module Omen
+  # The names these functions had before 1.0, dropped so a database matches the gem installed in
+  # it. A statement stored before the rename names them, and dropping them makes re-running one
+  # fail where leaving them would have it quietly answer -- from a function nothing maintains any
+  # more. An answer already drawn is unaffected: its rows are stored, not recomputed.
+  #
+  # Delete this file once no database still has them.
+  module Renamed
+    # Signatures rather than names, since a function is dropped by the arguments it takes.
+    BEFORE = [ 'eastern(timestamp)', 'eastern(timestamptz)',
+               'miles_between(double precision, double precision, double precision, ' \
+               'double precision)', ]
+
+    # @return [Array<String>] one DROP per function this gem used to create.
+    def self.statements = BEFORE.map { |signature| "DROP FUNCTION IF EXISTS #{signature}" }
+  end
+end

data/lib/omen/time_zone.rb

@@ -0,0 +1,57 @@
+module Omen
+  # The zone the company works in, and the two questions a reading asks about it: what a stored
+  # timestamp says here, and what day it is here. Created by the rake task rather than by a
+  # migration, because Rails' :ruby schema format dumps no functions, so db:schema:load would
+  # drop one a migration had made -- and the format cannot become :sql, since db/schema.rb is
+  # what Claude is shown.
+  module TimeZone
+    # The zone as Postgres names one: Time.zone.name is not a name it takes.
+    ZONE = 'America/New_York'
+
+    # 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) = [ stored(connection), instant(connection), today(connection) ]
+
+    # A stored timestamp says nothing about its own zone, so it is named UTC and then rendered.
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @return [String] the statement declaring the function over a naked timestamp.
+    def self.stored(connection)
+      "CREATE OR REPLACE FUNCTION #{name connection}(ts timestamp) RETURNS timestamp AS " \
+        "$$ SELECT ts AT TIME ZONE 'UTC' AT TIME ZONE #{connection.quote ZONE} $$ " \
+        'LANGUAGE sql IMMUTABLE'
+    end
+
+    # One conversion and not two: an instant already knows which moment it is, so naming it UTC
+    # first would convert it twice and answer hours out. Overloaded because Postgres will not
+    # cast an instant to a timestamp to resolve a call, so now() reaches neither without it.
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @return [String] the statement declaring the function over an instant.
+    def self.instant(connection)
+      "CREATE OR REPLACE FUNCTION #{name connection}(ts timestamptz) RETURNS timestamp AS " \
+        "$$ SELECT ts AT TIME ZONE #{connection.quote ZONE} $$ LANGUAGE sql IMMUTABLE"
+    end
+
+    # What makes a window slide: a statement saying `date_trunc('month', omen_today())` answers
+    # for whichever month it is run in, where a literal answers for the month it was written in.
+    #
+    # STABLE and not IMMUTABLE, unlike its neighbours, which are pure functions of what they are
+    # given. This one reads the clock: marked immutable, Postgres is entitled to fold it to a
+    # constant, and a window would stop moving in the way this function exists to prevent. Stable
+    # is also what has it evaluated once per statement, so a query naming it five times cannot
+    # straddle midnight.
+    #
+    # A date and not a timestamp, so a window cannot silently mean "up to the current hour".
+    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
+    # @return [String] the statement declaring the function.
+    def self.today(connection)
+      "CREATE OR REPLACE FUNCTION #{connection.quote_table_name Omen::Instructions::TODAY}() " \
+        "RETURNS date AS $$ SELECT (now() AT TIME ZONE #{connection.quote ZONE})::date $$ " \
+        'LANGUAGE sql STABLE'
+    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::TIME_ZONE
+  end
+end

data/lib/omen/version.rb

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

data/lib/omen.rb

@@ -4,8 +4,9 @@ require 'anthropic'
 require 'omen/attributes'
 require 'omen/config'
 require 'omen/distance'
-require 'omen/eastern'
 require 'omen/grants'
+require 'omen/renamed'
+require 'omen/time_zone'
 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.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Claudio Baccigalupo
@@ -100,12 +100,13 @@ files:
 - 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/renamed.rb
 - lib/omen/requirements.rb
 - lib/omen/stubs.rb
+- lib/omen/time_zone.rb
 - lib/omen/version.rb
 - lib/tasks/omen.rake
 homepage: https://github.com/claudiob/omen

data/lib/omen/eastern.rb

@@ -1,40 +0,0 @@
-module Omen
-  # The database function a reading's SQL reads every timestamp through. Created by the rake
-  # task rather than by a migration, because Rails' :ruby schema format dumps no functions, so
-  # db:schema:load would drop one a migration had made -- and the format cannot become :sql,
-  # since db/schema.rb is what Claude is shown.
-  module Eastern
-    # The zone the company works in, as Postgres names one: Time.zone.name is not one it takes.
-    ZONE = 'America/New_York'
-
-    # 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)
-      [ stored(connection), instant(connection) ]
-    end
-
-    # A stored timestamp says nothing about its own zone, so it is named UTC and then rendered.
-    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
-    # @return [String] the statement declaring the function over a naked timestamp.
-    def self.stored(connection)
-      "CREATE OR REPLACE FUNCTION #{name connection}(ts timestamp) RETURNS timestamp AS " \
-        "$$ SELECT ts AT TIME ZONE 'UTC' AT TIME ZONE #{connection.quote ZONE} $$ " \
-        'LANGUAGE sql IMMUTABLE'
-    end
-
-    # One conversion and not two: an instant already knows which moment it is, so naming it UTC
-    # first would convert it twice and answer hours out. Overloaded because Postgres will not
-    # cast an instant to a timestamp to resolve a call, so now() reaches neither without it.
-    # @param connection [ActiveRecord::ConnectionAdapters::AbstractAdapter] a writing one.
-    # @return [String] the statement declaring the function over an instant.
-    def self.instant(connection)
-      "CREATE OR REPLACE FUNCTION #{name connection}(ts timestamptz) RETURNS timestamp AS " \
-        "$$ SELECT ts AT TIME ZONE #{connection.quote ZONE} $$ 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::EASTERN
-  end
-end