hecks 1.3.0 → 1.5.0

data/lib/hecks/ports/persistence/plugins/era/postgres_era/lineage/field_cache.rb

@@ -4,11 +4,16 @@ module Hecks
   module Adapters
     class PostgresEra
       class Lineage
-        # THE READ-SIDE OF THE ERA WORKAROUND. Once a domain mints a
+        # The per-`where`-field read cache that lets a declared query find
+        # its ids without reducing the whole aggregate first.
+        #
+        # ## Why a cache and not an index
+        #
+        # **The read-side of the era workaround**. Once a domain mints a
         # second era, `head_view` is a `DISTINCT ON`/`UNION ALL`
         # reduction — and a `where` clause on anything but `id` (its own
         # partition key) cannot be pushed through that reduction, so every
-        # declared query pays the cost of reducing the WHOLE aggregate
+        # declared query pays the cost of reducing the whole aggregate
         # before it can filter anything (see docs/implemented/postgres-era-adapter-
         # split-plan.md's own trigger section — this is a real
         # SQL-semantics wall, not a missing index; adding one to
@@ -16,29 +21,35 @@ module Hecks
         # prove a predicate on a non-partition column commutes with
         # `DISTINCT ON` without risking a stale row winning).
         #
-        # THE WORKAROUND: one narrow table per declared `where`-field
-        # (never `order_by`-only fields — sorting the reduced output was
-        # never blocked by the reduction; only filtering was), holding
-        # exactly (id, ordinal, value) — the CURRENT extracted value for
+        # ## The table
+        #
+        # **The workaround**: one narrow table per declared `where`-field
+        # (never `order_by`-only fields — sorting the reduced output is
+        # not blocked by the reduction; only filtering is), holding
+        # exactly (id, ordinal, value) — the current extracted value for
         # every live id, maintained transactionally by `append` alongside
         # the head snapshot it already upserts (same ordinal-guard idiom:
         # `WHERE ordinal < EXCLUDED.ordinal`). A query whose sole `where`
         # is on a cached field never runs the reduction at all: `SELECT id
         # FROM <field>_cache WHERE value <op> $1`, then `SELECT id, state
-        # FROM head_view WHERE id = ANY($ids)` — safe THROUGH the
+        # FROM head_view WHERE id = ANY($ids)` — safe through the
         # reduction because `id` is its own partition key, unlike the
         # original field.
         #
-        # SCOPED TO NON-LIST FIELDS ONLY, same reasoning Track A (plain
+        # ## What it does not cover
+        #
+        # Scoped to non-list fields only, same reasoning Track A (plain
         # Postgres) and Track B (Sqlite/D1) both landed on independently
         # for their own automatic indexing: this codebase's `contains`
         # compiles to element-membership (`jsonb_array_elements`/
         # `json_each` + `EXISTS`), which a (id, ordinal, value) cache table
-        # keyed on ONE scalar value per id has no way to represent — a
+        # keyed on one scalar value per id has no way to represent — a
         # list field would need one row per (id, element), a different
         # shape this plan does not build. `PostgresEra#eligible_for_cache?`
         # is where that boundary lives.
         module FieldCache
+          # Names the cache table for one field of one aggregate in one era.
+          #
           # Deterministic and collision-free regardless of field-path
           # length or storage-name length — Postgres identifiers cap at 63
           # bytes, and a value-object member path (`compliance.review.
@@ -46,22 +57,52 @@ module Hecks
           # that if built any less defensively. Not meant to be
           # human-readable; `hecks_backfill_progress`/catalog lookups are
           # always driven by this same computed name, never typed by hand.
+          #
+          # `@domain` is part of the hash input — this table is exposed to
+          # the exact same collision this whole file's siblings
+          # (`head_view`/`head_snapshot`/`matview`, `lineage.rb`) are
+          # domain-qualified against in docs/decisions/0059: without it,
+          # two domains bound to PostgresEra against the same database,
+          # each with an aggregate sharing a storage_name and a cached
+          # where-field of the same name, derive the identical
+          # `hecks_fc_<hash>` table and silently share cached rows across
+          # domains. Already fully hashed, so folding the domain in costs
+          # nothing readability could lose.
+          #
+          # @param storage_name [String] the aggregate's snake-cased storage name
+          # @param era [Integer] ordinal of the era the cache belongs to
+          # @param field [String] the cached `where` field, a dotted path for a
+          #   value-object member such as `"compliance.review.deadline_at"`
+          # @return [String] unquoted table name, `hecks_fc_` plus 20 hex characters
           def field_cache(storage_name, era, field)
-            "hecks_fc_#{Digest::SHA256.hexdigest("#{storage_name}\0#{era}\0#{field}")[0, 20]}"
+            "hecks_fc_#{Digest::SHA256.hexdigest("#{@domain}\0#{storage_name}\0#{era}\0#{field}")[0, 20]}"
           end
 
+          # Creates one field's cache table if it is missing, then backfills it
+          # from the current head until the backfill is recorded complete.
+          #
           # Self-healing, same idiom as `ensure_head_snapshot!`: cheap,
-          # unconditional, safe to call on every boot. CREATION is a
+          # unconditional, safe to call on every boot. Creation is a
           # short-held lock (table doesn't exist yet — nothing to block);
-          # BACKFILL runs outside it, chunk by chunk, each chunk its own
+          # backfill runs outside it, chunk by chunk, each chunk its own
           # short lock — never one transaction spanning the scan, per
           # principle 1. `value_expression` is the exact SQL
           # `PostgresEra#query_expression(field)` already compiles for
           # this field, applied against a `state` column this module's own
           # SQL always makes available in scope (see `field_cache_source_sql`)
-          # — ONE source of truth for "what does this field mean", not a
+          # — one source of truth for "what does this field mean", not a
           # second hand-rolled copy that could silently drift from what a
           # live query actually filters on.
+          #
+          # @param storage_name [String] the aggregate's snake-cased storage name
+          # @param era [Integer] ordinal of the era the cache belongs to
+          # @param field [String] the cached `where` field, dotted for a value-object member
+          # @param value_expression [String] SQL expression that extracts the field's
+          #   value as text from a jsonb column named `state`
+          # @return [String] unquoted name of the cache table, as `field_cache` derives it
+          # @raise [PG::Error] if Postgres refuses the DDL, a source read, or an upsert
+          # @raise [Runtime::WiringError] if `era` is past 1, a chunk is still to be
+          #   backfilled, and a held era's text fails its digest check (see `eras`)
           def ensure_field_cache!(storage_name, era, field, value_expression)
             name = field_cache(storage_name, era, field)
             unless table_exists?(name)
@@ -83,6 +124,19 @@ module Hecks
             name
           end
 
+          # Fills an existing cache table from the reduced head, one committed chunk
+          # of `ResumableBackfill::CHUNK_SIZE` ids at a time, resuming from the cursor
+          # held in `hecks_backfill_progress` and doing nothing once it is complete.
+          #
+          # @param name [String] unquoted cache table name, from `field_cache`
+          # @param storage_name [String] the aggregate's snake-cased storage name
+          # @param era [Integer] ordinal of the era whose head is read
+          # @param value_expression [String] SQL expression that extracts the field's
+          #   value as text from a jsonb column named `state`
+          # @return [void]
+          # @raise [PG::Error] if Postgres refuses a source read or an upsert
+          # @raise [Runtime::WiringError] if `era` is past 1, a chunk is still to be
+          #   backfilled, and a held era's text fails its digest check (see `eras`)
           def backfill_field_cache!(name, storage_name, era, value_expression)
             chunked_backfill!(
               name,
@@ -99,16 +153,29 @@ module Hecks
             )
           end
 
-          # THE LIVE-WRITE SIDE — called from `append`, inside the SAME
+          # Upserts one id's cached value from the state being written, leaving the
+          # row alone when it already carries an equal or newer ordinal.
+          #
+          # **The live-write side** — called from `append`, inside the same
           # transaction as the journal insert and the head-snapshot
           # upsert, for every field this aggregate has a cache table for.
-          # `state_json` is the entry's OWN new state (already the thing
+          # `state_json` is the entry's own new state (already the thing
           # `append` is about to write) — bound as a literal jsonb value
           # and aliased `state`, so `value_expression` (built to read a
           # column literally named `state`) evaluates identically here and
           # in every backfill/query-time use, with no separate Ruby-side
           # re-implementation of "how to pick a value-object's member" to
           # keep in sync.
+          #
+          # @param name [String] unquoted cache table name, from `field_cache`
+          # @param id [String] the aggregate id the entry belongs to
+          # @param ordinal [String, Integer] the journal ordinal the entry was written
+          #   at; `append` passes the decimal text Postgres returned from its INSERT
+          # @param state_json [String] the entry's encoded state, as JSON text
+          # @param value_expression [String] SQL expression that extracts the field's
+          #   value as text from a jsonb column named `state`
+          # @return [void]
+          # @raise [PG::Error] if Postgres refuses the upsert
           def upsert_field_cache_row!(name, id, ordinal, state_json, value_expression)
             @db.exec_params(<<~SQL, [id, ordinal, state_json])
               INSERT INTO #{quote(name)} (id, ordinal, value)
@@ -119,6 +186,14 @@ module Hecks
             SQL
           end
 
+          # Removes a deleted id's row from one cache table, so a cached-field query
+          # stops offering that id. Called from `append` for a delete entry, inside the
+          # same transaction as the journal insert and the head-snapshot tombstone.
+          #
+          # @param name [String] unquoted cache table name, from `field_cache`
+          # @param id [String] the aggregate id whose row is removed
+          # @return [void]
+          # @raise [PG::Error] if Postgres refuses the delete
           def delete_field_cache_row!(name, id)
             @db.exec_params("DELETE FROM #{quote(name)} WHERE id = $1", [id])
           end
@@ -126,19 +201,19 @@ module Hecks
           private
 
           # The reduced (id, ordinal, state) source a field cache backfills
-          # from — NOT the raw journal (unlike `backfill_head_snapshot!`'s
-          # own source): a field cache reflects the CURRENT HEAD value,
+          # from — not the raw journal (unlike `backfill_head_snapshot!`'s
+          # own source): a field cache reflects the current head value,
           # which for era > 1 can come from either this era's own live
-          # writes OR an untouched-this-era id whose value still comes
+          # writes or an untouched-this-era id whose value still comes
           # from the translated ancestor tail. Era 1 has no ancestor tail
-          # (the snapshot table IS the head, verbatim); era N reduces the
-          # SAME two sources `compile_head!`'s own final view definition
+          # (the snapshot table is the head, verbatim); era N reduces the
+          # same two sources `compile_head!`'s own final view definition
           # unions (head_compiler.rb) — this is deliberately the identical
           # shape, ordinal kept in the SELECT list instead of dropped,
-          # because a backfilled cache row needs a REAL ordinal to guard
+          # because a backfilled cache row needs a real ordinal to guard
           # against a concurrent live write the same way every other
           # upsert in this adapter already does. Ordinals are safe to
-          # compare across that union because they come from ONE spanning
+          # compare across that union because they come from one spanning
           # sequence per domain (see lineage.rb's own header comment) —
           # an ancestor-era ordinal is always numerically smaller than any
           # current-era one, so the ordinary `ordinal <` guard already
@@ -157,7 +232,7 @@ module Hecks
                 "SELECT ordinal, aggregate_id AS id, state FROM #{quote(view)} WHERE operation = 'save'"
               else
                 # No compiled ancestor matview yet (e.g. this era was just
-                # minted and compile_head! hasn't run for THIS aggregate) —
+                # minted and compile_head! hasn't run for this aggregate) —
                 # the live snapshot side alone is the whole truth so far.
                 "SELECT NULL::bigint AS ordinal, NULL::text AS id, NULL::jsonb AS state WHERE FALSE"
               end