hecks 1.2.0 → 1.4.0

data/lib/hecks/adapters/driven/postgres/schema_builder.rb

@@ -19,16 +19,16 @@ module Hecks
           @db.exec(
             "CREATE TABLE IF NOT EXISTS #{quoted_table} (id text PRIMARY KEY#{', ' unless columns.empty?}#{columns.join(', ')})"
           )
-          # SELF-HEALING, SAME IDIOM AS `ensure_indexes!` BELOW —
-          # `CREATE TABLE IF NOT EXISTS` above does NOT retroactively add a
+          # **Self-healing, same idiom as `ensure_indexes!` below** —
+          # `CREATE TABLE IF NOT EXISTS` above does not retroactively add a
           # column to an already-existing table (a committed database from
           # before optimistic-concurrency CAS existed), so this runs
           # unconditionally on every boot and no-ops once the column is
-          # there. ADAPTER BOOKKEEPING ONLY — never listed in
+          # there. Adapter bookkeeping only — never listed in
           # `persisted_fields` (Codec), so it never appears in `decode`'s
           # domain-state hash or `Instance#to_h`.
           @db.exec("ALTER TABLE #{quoted_table} ADD COLUMN IF NOT EXISTS hecks_version bigint NOT NULL DEFAULT 1")
-          # SAME SELF-HEALING SHAPE, FOR DOMAIN ATTRIBUTES THEMSELVES —
+          # Same self-healing shape, for domain attributes themselves —
           # `hecks_version` above only heals the adapter's own bookkeeping
           # column; a bluebook attribute added (or, via `translations/`,
           # renamed) after this table already exists is not bookkeeping,
@@ -47,7 +47,7 @@ module Hecks
             @db.exec("ALTER TABLE #{quoted_table} ADD COLUMN IF NOT EXISTS " \
                      "#{quote_ident(field[:name])} #{field[:sql_type]}")
           end
-          # RIGHT HERE, NOT A SEPARATE STEP IN `Postgres#initialize` —
+          # Right here, not a separate step in `Postgres#initialize` —
           # same idiom Sqlite::SchemaBuilder's own `create_aggregate_table!`
           # uses: index creation runs unconditionally, right after the
           # table it indexes exists, the same self-healing shape
@@ -118,11 +118,11 @@ module Hecks
         # Derived from every declared query's `where`/`order_by` fields —
         # no bluebook author opts in, matching every other self-healing
         # schema move this adapter makes. Walks the aggregate's own
-        # queries AND each entity's own queries — the same enumeration
+        # queries and each entity's own queries — the same enumeration
         # `dsl/aggregate_builder.rb`'s own `query_surfaces` walks at
         # declaration-seal time — but an entity's own fields never
         # produce an index below: an entity has no table of its own, its
-        # rows live inside a LIST-typed attribute on the AGGREGATE's own
+        # rows live inside a list-typed attribute on the aggregate's own
         # table (`QueryInterpreter#entity_rows` resolves it that way, and
         # answers an entity query entirely in memory over `repository.all`
         # — it never reaches this adapter's own `query` method at all).
@@ -154,15 +154,15 @@ module Hecks
         # FROM jsonb_array_elements(...) ...)` (see `list_contains_clause`
         # below), a SQL shape neither a plain btree on the raw jsonb
         # column nor even a GIN jsonb index (`@>`, `?`) accelerates —
-        # Postgres's own GIN jsonb operators match a DIFFERENT SQL shape
+        # Postgres's own GIN jsonb operators match a different SQL shape
         # than the `EXISTS` + `jsonb_array_elements` this codebase always
         # compiles a list `contains` to. An index here would be dead
         # weight, not free correctness, so none is attempted.
         def index_field!(field)
-          # A HOP PATH ("owner/field" — `Bluebook::AggregateBuilder`'s own
+          # A hop path ("owner/field" — `Bluebook::AggregateBuilder`'s own
           # convention for a field reached by crossing a reference,
           # `aggregate_builder.rb`'s own `field.to_s.include?("/")`
-          # checks) IS NEVER INDEXED HERE — same reasoning as `list_of`
+          # checks) is never indexed here — same reasoning as `list_of`
           # below: `query_expression`/`nested_expression` below have no
           # dialect for this shape at all (they'd compile the whole
           # "owner/field" string as one bare column/jsonb-path segment,
@@ -173,10 +173,10 @@ module Hecks
           # Skipping the index is always safe, the same way skipping a
           # `list_of` index is: an index is a perf optimization, not
           # correctness, so "never built" beats "built wrong." Whether a
-          # hop-path field can be QUERIED at all against this adapter is
+          # hop-path field can be queried at all against this adapter is
           # a separate, still-open question this skip does not answer —
           # see docs/future-features.md's fuzzer-adapter entry, and
-          # docs/1.0-readiness.md item 2 for this gap's OTHER two
+          # docs/1.0-readiness.md item 2 for this gap's other two
           # independent failure points (Postgres querying, Rust codegen's
           # `OpenForSuspendedCustomers` — bin/rust_coverage's own
           # allowlist) — tracked together, not as three unrelated bugs.
@@ -186,7 +186,7 @@ module Hecks
           attribute = @aggregate.attribute(name)
           return if attribute&.list?
 
-          # THE SAME EXPRESSION THE QUERY ITSELF COMPILES TO — calling
+          # The same expression the query itself compiles to — calling
           # `query_expression`/`plain_column`, the real dialect methods,
           # rather than a second, hand-rolled derivation of the same
           # path that could silently drift from it. An index whose
@@ -211,7 +211,7 @@ module Hecks
           @db.exec("CREATE INDEX IF NOT EXISTS #{quote_ident(name)} ON #{quoted_table} ((#{expression}))")
         end
 
-        # Postgres identifiers cap at 63 bytes. Hashing TABLE + FIELD
+        # Postgres identifiers cap at 63 bytes. Hashing table + field
         # together keeps every generated index name well under that no
         # matter how long an aggregate or attribute name gets, and keeps
         # two distinct fields — on the same table or different ones —

data/lib/hecks/adapters/driven/postgres.rb

@@ -23,19 +23,24 @@ module Hecks
     # actually needs to survive a live shape change. See
     # docs/implemented/postgres-era-adapter-split-plan.md for why the two are split.
     #
+    # ## What it is not
+    #
     # No `hecks_eras`, no lineage, no advisory-lock-per-write for era
     # tracking, no `lineage_capable?`/`era_check!` — this class simply
     # doesn't define those methods at all, and the capability idiom
     # elsewhere already treats their absence as "not lineage-capable".
     #
-    # Storage shape (see postgres/schema_builder.rb for the DDL,
-    # postgres/codec.rb for the encode/decode):
+    # ## Storage shape
+    #
+    # See postgres/schema_builder.rb for the DDL, postgres/codec.rb for the
+    # encode/decode.
+    #
     # - One real column per attribute, typed for a scalar
     #   (`SQL_TYPES`, `text` default), `jsonb` for a nested (value-object)
-    #   or list-typed attribute — never JSON-in-TEXT the way `Sqlite` has
+    #   or list-typed attribute — never JSON-in-text the way `Sqlite` has
     #   to, since Postgres has a native jsonb type.
     # - `append` and `project` are two real Postgres statements — `save`/
-    #   `delete` wrap them in ONE transaction, same "the journal insert
+    #   `delete` wrap them in one transaction, same "the journal insert
     #   and the snapshot stay atomic" reasoning `PostgresEra#append`'s own
     #   comment gives: a crash between the two must never leave a
     #   half-written state. `append`/`project` stay plain, individually-
@@ -53,10 +58,24 @@ module Hecks
 
       attr_reader :aggregate
 
+      # Names the optional persistence capabilities `Ports::Persistence::AppendOnly` may rely on.
+      #
+      # @return [Array<Symbol>] `[:atomic_put, :optimistic_concurrency]`
       def persistence_capabilities = [:atomic_put, :optimistic_concurrency]
 
+      # Opens a connection to the database a world declares, scoped to its `schema` if any.
+      #
+      # @param name [String] the aggregate's name, used only in error messages
+      # @param settings [Hash{Symbol, String => Object}] world settings for the binding;
+      #   `database` (a database name or a `postgres://` URL) is required and `schema` is
+      #   optional, each read under a Symbol or a String key
+      # @return [PG::Connection] a live connection with `search_path` and
+      #   `client_min_messages` already set
+      # @raise [Runtime::WiringError] if the settings declare no `database`, or Postgres
+      #   refuses the connection or the `SET` statements
+      # @raise [LoadError] if the `pg` gem is not installed
       def self.connect_for(name, settings)
-        # LAZY, ON PURPOSE — same reasoning as PostgresEra's own
+        # **Lazy, on purpose** — same reasoning as PostgresEra's own
         # connect_for: a domain that never wires Postgres should never
         # need the gem installed.
         require "pg"
@@ -75,7 +94,7 @@ module Hecks
             PG.connect(dbname: declared)
           end
 
-        # SHARED-INSTANCE ISOLATION — same as PostgresEra's own: a
+        # **Shared-instance isolation** — same as PostgresEra's own: a
         # domain that declares `schema` is sharing its Postgres instance
         # with other domains, so every unqualified reference this
         # adapter constructs resolves through search_path. A domain with
@@ -83,8 +102,8 @@ module Hecks
         schema = settings.key?(:schema) ? settings[:schema] : settings["schema"]
         connection.exec("SET search_path TO #{connection.quote_ident(schema)}") if schema.to_s != ""
 
-        # QUIET ON PURPOSE — same reasoning as PostgresEra's own: a
-        # schema/table that already exists is the ORDINARY case on every
+        # **Quiet on purpose** — same reasoning as PostgresEra's own: a
+        # schema/table that already exists is the ordinary case on every
         # boot after the first, not news.
         connection.exec("SET client_min_messages = warning")
         connection
@@ -93,11 +112,22 @@ module Hecks
               "cannot bind Postgres at #{declared} for #{name}: #{e.message.strip}"
       end
 
+      # Connects and creates the aggregate, journal, event, saga and outbox tables if absent.
+      #
+      # @param aggregate [Bluebook::Aggregate] the aggregate whose table this adapter owns
+      # @param settings [Hash{Symbol, String => Object}] world settings for the binding:
+      #   `database` (required), `schema` and `domain` (optional; `domain` defaults to the
+      #   aggregate's storage name and scopes saga rows)
+      # @param root [String, nil] project root directory; accepted for the shared adapter
+      #   constructor shape and ignored
+      # @raise [Runtime::WiringError] if the settings declare no `database` or the connection
+      #   is refused
+      # @raise [PG::Error] if creating a table or index fails
       def initialize(aggregate:, settings: {}, root: nil)
         @aggregate = aggregate
         @settings  = settings
         @db = self.class.connect_for(aggregate.name, settings)
-        # THE OPTIONAL saga-persistence capability's own scoping column
+        # The optional saga-persistence capability's own scoping column
         # (§2/§4) — falls back to the aggregate's own storage name for a
         # directly-instantiated adapter (specs), same fallback shape
         # Sqlite's own @domain already uses.
@@ -118,8 +148,18 @@ module Hecks
         create_outbox_table!
       end
 
+      # Names the aggregate's table; the journal table and outbox rows are keyed off it.
+      #
+      # @return [String] the aggregate's snake_case storage name, unquoted
       def table = @aggregate.storage_name
 
+      # Reads the current row for one aggregate identity, stamped with its stored version.
+      #
+      # @param id [String, Object] the aggregate identity, bound as `id.to_s`
+      # @return [Runtime::Instance, nil] the decoded record with `version` set, or nil when
+      #   no row has that id
+      # @raise [PG::Error] if the statement fails; a `PG::ConnectionBad` also triggers a
+      #   reconnect for the next caller
       def find(id)
         result = pg_exec_params("SELECT * FROM #{quoted_table} WHERE id = $1", [id.to_s])
         return nil if result.ntuples.zero?
@@ -127,9 +167,20 @@ module Hecks
         instance_from_row(result[0])
       end
 
-      # order_by IS A RUNTIME VALUE — see Sqlite#all's own reasoning;
+      # Lists every stored record, ordered by id unless an ordering attribute is given.
+      #
+      # order_by is a runtime value — see Sqlite#all's own reasoning;
       # whitelisted the identical way before it ever reaches
       # order_expression.
+      #
+      # @param order_by [String, Symbol, nil] attribute (or dotted value-object path) to sort
+      #   by, with id as the tie-break; nil orders by id alone
+      # @param direction [Symbol, String] `:asc` or `:desc`, case-insensitive; anything else
+      #   sorts ascending
+      # @return [Array<Runtime::Instance>] the decoded records with `version` set, `[]` when
+      #   the table is empty
+      # @raise [Runtime::WiringError] if `order_by` names no attribute of the aggregate
+      # @raise [PG::Error] if the statement fails
       def all(order_by: nil, direction: :asc)
         order_sql = "ORDER BY id"
         if order_by
@@ -146,38 +197,59 @@ module Hecks
         pg_exec("SELECT * FROM #{quoted_table} #{order_sql}").map { |row| instance_from_row(row) }
       end
 
+      # Counts the rows in the aggregate's table, deleted records excluded.
+      #
+      # @return [Integer] number of current records
+      # @raise [PG::Error] if the statement fails
       def count = pg_exec("SELECT COUNT(*) FROM #{quoted_table}")[0]["count"].to_i
 
+      # Inserts one journal row, outside any transaction of its own.
+      #
+      # @param entry [Ports::Persistence::Entry] the save or delete to journal; `state` is
+      #   encoded through the state codec and `mirrors` stored as JSON, or NULL when nil
+      # @return [Ports::Persistence::Entry] the same `entry`
+      # @raise [PG::Error] if the insert fails
       def append(entry)
         pg_exec_params(
           "INSERT INTO #{quoted_entry_table} (aggregate_id, operation, state, mirrors) VALUES ($1, $2, $3, $4)",
-          # `mirrors` (unlike `state`) is a NULLABLE column — an absent
+          # `mirrors` (unlike `state`) is a nullable column — an absent
           # mirrors hash must bind a real SQL NULL, not the four-character
           # JSON text `"null"` (`JSON.generate(nil)`), or a future `IS NULL`
           # check against it would never match. Same guard `sqlite.rb`/
           # `d1.rb`/`postgres_era.rb` already use for their own journal's
           # `mirrors` column.
-          [entry.id, entry.operation, JSON.generate(entry.state), entry.mirrors && JSON.generate(entry.mirrors)]
+          [entry.id, entry.operation, state_json(entry.state), entry.mirrors && JSON.generate(entry.mirrors)]
         )
         entry
       end
 
+      # Upserts or deletes the aggregate's row for one journal entry, bumping its version.
+      #
       # `expected_version:` requests optimistic-concurrency CAS (see
       # `persistence_capabilities`/`Ports::Persistence::AppendOnly#save`).
-      # `hecks_version` is ADAPTER BOOKKEEPING — never in `persisted_fields`
+      # `hecks_version` is adapter bookkeeping — never in `persisted_fields`
       # (Codec), so it never reaches `decode`'s domain-state hash. It goes
       # in the INSERT column list at `1` (a genuinely new row) and bumps by
       # one in the `ON CONFLICT DO UPDATE` branch; when `expected_version`
-      # is given, that UPDATE branch additionally requires
+      # is given, that update branch additionally requires
       # `hecks_version = expected_version` to apply at all — Postgres's own
       # `INSERT ... ON CONFLICT DO UPDATE ... WHERE`, which gates only
-      # whether the CONFLICT branch's update applies. A genuinely new row
+      # whether the conflict branch's update applies. A genuinely new row
       # never reaches that branch at all, so it always inserts regardless
-      # of this WHERE. `RETURNING hecks_version` plus `ntuples.zero?` is
+      # of this where. `RETURNING hecks_version` plus `ntuples.zero?` is
       # how a real version mismatch is told apart from an ordinary write:
-      # zero rows back means the conflict branch's WHERE excluded the row
+      # zero rows back means the conflict branch's where excluded the row
       # entirely — the version had already moved — so `nil` is returned
       # for the caller (`AppendOnly#save`) to treat as "stale, no-op".
+      #
+      # @param entry [Ports::Persistence::Entry] the save or delete to materialize
+      # @param expected_version [Integer, nil] the `hecks_version` the row must still hold for
+      #   an update to apply; nil writes unconditionally. Ignored for a delete
+      # @return [Runtime::Instance, PG::Result, nil] for a save, a new instance over the
+      #   entry's state with `version` set to the stored `hecks_version`, or nil when
+      #   `expected_version` no longer matched and nothing was written; for a delete, the
+      #   `DELETE` statement's `PG::Result`
+      # @raise [PG::Error] if the statement fails
       # rubocop:disable Metrics/AbcSize -- the CAS/plain upsert split is one
       # protocol; splitting it would hide the version handshake.
       def project(entry, expected_version: nil)
@@ -206,31 +278,50 @@ module Hecks
       end
       # rubocop:enable Metrics/AbcSize
 
+      # Reads the whole journal back in append order, for `AppendOnly#recover!` to replay.
+      #
+      # @return [Array<Ports::Persistence::Entry>] every journalled entry, state decoded
+      #   through the state codec and `mirrors` parsed with String keys (nil when none were
+      #   stored); `[]` when nothing has been appended
+      # @raise [PG::Error] if the statement fails
+      # @raise [JSON::ParserError] if a stored `state` or `mirrors` value is not valid JSON
       def entries
         pg_exec("SELECT aggregate_id, operation, state, mirrors FROM #{quoted_entry_table} ORDER BY sequence").map do |row|
           state = JSON.parse(row["state"])
           Ports::Persistence::Entry.new(
             operation: row["operation"] || "save",
             id:        row["aggregate_id"],
-            state:     state&.transform_keys(&:to_sym),
+            state:     Ports::Persistence::StateCodec.decode(@aggregate, state),
             mirrors:   row["mirrors"] && JSON.parse(row["mirrors"])
           )
         end
       end
 
+      # Deletes every row of the aggregate's table and its journal; events, saga rows and
+      # outbox rows are left in place.
+      #
+      # @return [Adapters::Postgres] self
+      # @raise [PG::Error] if a statement fails
       def reset!
         pg_exec("DELETE FROM #{quoted_table}")
         pg_exec("DELETE FROM #{quoted_entry_table}")
         self
       end
 
-      # ONE TRANSACTION, not the plain append-then-project two-step a
+      # Journals and upserts an instance's current state atomically.
+      #
+      # One transaction, not the plain append-then-project two-step a
       # file-based adapter needs a crash-recovery replay for (Heki) —
       # real Postgres ACID atomicity is sitting right there, so a crash
       # between the journal insert and the table upsert must not leave
       # the two disagreeing. `append`/`project` themselves stay plain,
       # transaction-free methods (see the class comment above) — the
       # transaction lives here, the one caller that runs both together.
+      #
+      # @param instance [Runtime::Instance] the instance to store
+      # @return [Runtime::Instance] a new instance over the saved state, `version` set to the
+      #   row's new `hecks_version`
+      # @raise [PG::Error] if either statement fails; the transaction is rolled back
       def save(instance)
         entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
         transaction do
@@ -239,6 +330,14 @@ module Hecks
         end
       end
 
+      # Stores an entry under a per-identity advisory lock and reports whether it inserted,
+      # replaced or conflicted, so two concurrent creators of one id cannot both insert.
+      #
+      # @param entry [Ports::Persistence::Entry] the save to store
+      # @param insert_only [Boolean] when true, an existing row is left untouched
+      # @return [Symbol] `:inserted`, `:replaced`, or `:conflicted` when `insert_only` met an
+      #   existing row and nothing was written
+      # @raise [PG::Error] if a statement fails; the transaction is rolled back
       def atomic_put(entry, insert_only: false)
         status = nil
         transaction do
@@ -262,6 +361,11 @@ module Hecks
         status
       end
 
+      # Journals a delete and removes the row atomically, whether or not a row exists.
+      #
+      # @param id [String, Object] the aggregate identity, journalled as `id.to_s`
+      # @return [Boolean] always true
+      # @raise [PG::Error] if either statement fails; the transaction is rolled back
       def delete(id)
         entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
         transaction do
@@ -271,6 +375,11 @@ module Hecks
         true
       end
 
+      # Inserts an emitted event into the shared `events` table.
+      #
+      # @param event [Runtime::Event] the emitted event; `payload` is stored as JSON
+      # @return [PG::Result] the insert's result; callers ignore it
+      # @raise [PG::Error] if the insert fails
       def record_event(event)
         pg_exec_params(
           "INSERT INTO events (name, aggregate, aggregate_id, payload, occurred_at) VALUES ($1, $2, $3, $4, $5)",
@@ -278,6 +387,12 @@ module Hecks
         )
       end
 
+      # Reads back every recorded event in insertion order — the whole `events` table, not
+      # only this aggregate's rows.
+      #
+      # @return [Array<Runtime::Event>] the stored events, `payload` parsed with Symbol keys
+      #   and `occurred_at` as the String Postgres returns; `[]` when none are recorded
+      # @raise [PG::Error] if the statement fails
       def events
         pg_exec("SELECT * FROM events ORDER BY id").map do |row|
           Runtime::Event.new(
@@ -290,9 +405,22 @@ module Hecks
         end
       end
 
-      # ── the OPTIONAL saga-persistence capability (§2) — same DDL and
+      # Upserts one saga instance's checkpoint, keyed by domain, process manager and
+      # correlation.
+      #
+      # ── the optional saga-persistence capability (§2) — same DDL and
       # shape as PostgresEra's own (postgres_era.rb), not lineage-
       # specific, copied verbatim.
+      #
+      # @param process_manager [String, Symbol] the process manager's name
+      # @param correlation [String, Object] the instance's correlation value, stored as
+      #   `correlation.to_s`
+      # @param state [String, Symbol] the saga's current state name
+      # @param memory [Hash] the saga's memory; must be JSON-serializable
+      # @param completed_compensations [Array] the ledger of completed compensable legs; must
+      #   be JSON-serializable
+      # @return [PG::Result] the upsert's result; callers ignore it
+      # @raise [PG::Error] if the statement fails
       def save_saga(process_manager:, correlation:, state:, memory:, completed_compensations: [])
         pg_exec_params(
           "INSERT INTO hecks_saga_instances (domain, process_manager, correlation, state, memory, completed_compensations) " \
@@ -305,6 +433,13 @@ module Hecks
         )
       end
 
+      # Removes a finished saga instance's checkpoint; a missing row is not an error.
+      #
+      # @param process_manager [String, Symbol] the process manager's name
+      # @param correlation [String, Object] the instance's correlation value, matched as
+      #   `correlation.to_s`
+      # @return [PG::Result] the delete's result; callers ignore it
+      # @raise [PG::Error] if the statement fails
       def delete_saga(process_manager:, correlation:)
         pg_exec_params(
           "DELETE FROM hecks_saga_instances WHERE domain = $1 AND process_manager = $2 AND correlation = $3",
@@ -312,6 +447,18 @@ module Hecks
         )
       end
 
+      # Yields every checkpointed saga instance of this adapter's domain, for
+      # `Registry#rehydrate_sagas!` to restore at boot.
+      #
+      # @yieldparam process_manager [String] the process manager's name
+      # @yieldparam correlation [String] the instance's correlation value
+      # @yieldparam state [String] the saga's state name
+      # @yieldparam memory [Hash{Symbol => Object}] the saga's memory, Symbol keys at every depth
+      # @yieldparam completed_compensations [Array] the completed-compensation ledger, `[]`
+      #   when the column is NULL
+      # @return [Enumerator, PG::Result] an enumerator over the same five values when no block
+      #   is given; otherwise the query result
+      # @raise [PG::Error] if the statement fails
       def each_saga
         return enum_for(:each_saga) unless block_given?
 
@@ -344,7 +491,7 @@ module Hecks
         "position(#{placeholder} in #{expression}) > 0"
       end
 
-      # THE LIST COLUMN ITSELF IS THE JSONB ARRAY — no reaching into a
+      # The list column itself is the JSONB array — no reaching into a
       # shared blob a jsonb path has to walk into first (PostgresEra's
       # own version does, since every attribute there shares one `state`
       # column). Here, `column` names a real column of its own, already
@@ -357,17 +504,17 @@ module Hecks
 
       def plain_column(name) = quote_ident(name)
 
-      # PostgresEra's own `jsonb_path` walks `[name, *path]` into ONE
-      # shared `state` column — the attribute name is PART of the path
-      # there. Here the attribute name IS THE COLUMN: the path into it
-      # is whatever is LEFT after the column, never the column name
+      # PostgresEra's own `jsonb_path` walks `[name, *path]` into one
+      # shared `state` column — the attribute name is part of the path
+      # there. Here the attribute name is the column: the path into it
+      # is whatever is left after the column, never the column name
       # repeated inside its own path.
       def nested_expression(name, path, member)
         segments = path.empty? ? [(member || "value").to_s] : path
         jsonb_path(name, segments)
       end
 
-      # Scalar, non-value-object attributes get a REAL typed column
+      # Scalar, non-value-object attributes get a real typed column
       # (bigint/double precision/text) — comparing and sorting one needs
       # no cast at all, unlike PostgresEra's shared jsonb `state` blob,
       # where even a top-level scalar only ever comes out of `#>>` as
@@ -428,7 +575,7 @@ module Hecks
       end
 
       # Same walk PostgresEra's own numeric_field? uses — decides
-      # numericness at ANY depth from the declared shape itself, not a
+      # numericness at any depth from the declared shape itself, not a
       # runtime value.
       def numeric_field?(field)
         name, *path = field.to_s.split(".")
@@ -437,7 +584,7 @@ module Hecks
         end
       end
 
-      # ARRAY[...] of individually-escaped literals — same escaping
+      # Array[...] of individually-escaped literals — same escaping
       # PostgresEra's own jsonb_path carries and the same reason: a
       # hand-rolled '{a,b,c}' array literal has no escaping at all, and
       # a segment is a field or value-object member name this method has

data/lib/hecks/adapters/driven/postgres_era.adapter

@@ -14,4 +14,9 @@ Hecks.adapter "PostgresEra" do
   field :database
   field :role
   field :schema
+  # `allow_superuser true` — the explicit, on-the-record opt-in to boot
+  # over a connection whose role is a Postgres superuser or carries
+  # BYPASSRLS, which the era write-fence (row-level security) cannot
+  # bite. Refused by default; see `Lineage#check_fence_applies!` (BUG#24).
+  field :allow_superuser
 end

data/lib/hecks/adapters/driven/prism.rb

@@ -13,7 +13,7 @@ module Hecks
     # path; `forget`/`forget_all` exist for a caller that reloads an edited
     # file in-process (see their own comment).
     module Prism
-      # NOT frozen — a real cache, keyed by file path and mutated by
+      # Not frozen — a real cache, keyed by file path and mutated by
       # #tree_for below (`TREES[file] ||= ...`) and #forget/#forget_all.
       # False positive for Style/MutableConstant.
       # rubocop:disable-next Style/MutableConstant
@@ -58,12 +58,12 @@ module Hecks
         TREES[file] ||= ::Prism.parse(File.read(file)).value
       end
 
-      # `TREES` caches for the life of the PROCESS, keyed by path, with
+      # `TREES` caches for the life of the process, keyed by path, with
       # no staleness check — correct for every ordinary caller (a file
       # loads once per process: one `bin/ir` run, one rspec worker,
-      # never edited out from under it), but WRONG for anything that
+      # never edited out from under it), but wrong for anything that
       # legitimately reloads an edited file in-process: a stale cached
-      # tree reports a `given`/`ensures` block at its OLD line number,
+      # tree reports a `given`/`ensures` block at its old line number,
       # which no longer matches the freshly re-executed file's own
       # `block.source_location` — surfacing as "did not survive
       # extraction" on a perfectly valid file. Found for real building