hecks 1.2.0 → 1.4.0

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

@@ -11,12 +11,20 @@ module Hecks
         # version, recording a Layer-3 approval, and minting an era's name
         # once (never recomputed after).
         module EraStore
+          # Lists every era the domain holds, oldest first, refusing any whose text was edited.
+          #
           # Every held text is verified against its raw-byte digest on the
           # way out — an edited storage fact refuses rather than silently
-          # reporting "no drift". This is NOT the era name (which hashes
+          # reporting "no drift". This is not the era name (which hashes
           # the canonical projection, minted once, never recomputed): it
-          # is a plain integrity check over bytes, and a row from before
-          # the check existed is backfilled, not refused.
+          # is a plain integrity check over bytes, and a row that carries
+          # no digest yet is backfilled, not refused.
+          #
+          # @return [Array<Hash{Symbol => Object}>] one Hash per era in ordinal order, `[]` when
+          #   the domain holds none; keys are `:ordinal` (Integer), `:hash` and `:label` (String,
+          #   nil until `mint_name!` names the era), `:held_text` (String) and `:watermark`
+          #   (Integer journal ordinal the era was cut at, nil for era 1)
+          # @raise [Runtime::WiringError] if a held text no longer matches its stored digest
           def eras
             @db.exec_params(
               "SELECT ordinal, hash, label, held_text, watermark, held_digest, held_projection::text " \
@@ -29,8 +37,15 @@ module Hecks
             end
           end
 
+          # Reads one era's stored row without running the integrity check that `eras` applies.
+          #
           # The unverified row — what bin/reattest_era shows an operator
           # after the integrity check fires.
+          #
+          # @param ordinal [Integer] ordinal of the era to read
+          # @return [Hash{Symbol => String, nil}, nil] `:held_text`, `:held_digest` (SHA-256 hex,
+          #   nil if never stored), `:hash` (nil until minted) and `:held_projection` (JSON text,
+          #   nil if never stored); nil when the domain holds no such era
           def raw_era(ordinal)
             rows = @db.exec_params(
               "SELECT held_text, held_digest, hash, held_projection::text FROM hecks_eras WHERE domain = $1 AND ordinal = $2",
@@ -42,10 +57,17 @@ module Hecks
               held_projection: rows[0]["held_projection"] }
           end
 
-          # The recovery path: tamper-EVIDENCE (against accident and
+          # Accepts an era's held text as it now stands, replacing its stored digest.
+          #
+          # The recovery path: tamper-evidence (against accident and
           # drift, not adversaries) gets resolved by a human acknowledging
           # the text as it now stands — recorded in an append-only
-          # attestation table, never by a bare psql UPDATE.
+          # attestation table, never by a bare psql `UPDATE`.
+          #
+          # @param ordinal [Integer] ordinal of the era to re-attest
+          # @return [String] the new SHA-256 hex digest of the held text
+          # @raise [Runtime::WiringError] if the domain holds no era with that ordinal
+          # @raise [PG::Error] if Postgres refuses the attestation DDL or a write
           def reattest!(ordinal)
             era = raw_era(ordinal)
             raise Runtime::WiringError, "#{@domain} holds no era #{ordinal} to re-attest" unless era
@@ -72,6 +94,19 @@ module Hecks
             fresh
           end
 
+          # Checks one held text against its stored digest, storing the digest if the row has none.
+          #
+          # A text that passes (or that had no digest to fail against) also gets
+          # `backfill_frozen_facts!`; a text that fails gets nothing written.
+          #
+          # @param ordinal [Integer] ordinal of the era the text belongs to
+          # @param text [String] the era's held bluebook source text
+          # @param stored_digest [String, nil] SHA-256 hex digest stored with the row; nil when
+          #   the row carries none yet
+          # @param stored_projection_json [String, nil] the row's stored projection as JSON text;
+          #   nil when the row carries none yet
+          # @return [void]
+          # @raise [Runtime::WiringError] if `stored_digest` is present and does not match `text`
           def verify_integrity!(ordinal, text, stored_digest, stored_projection_json)
             digest = Digest::SHA256.hexdigest(text)
             if stored_digest.nil?
@@ -90,9 +125,17 @@ module Hecks
             raise Runtime::WiringError, Runtime::EraTamper.refusal(domain: @domain, ordinal: ordinal)
           end
 
-          # A verified-authentic text backfills what older rows lack: its
+          # Fills in the archive copy and the stored projection an era row is missing.
+          #
+          # A verified-authentic text backfills what a row may lack: its
           # projection and its archive copy. Never run on a text that
           # failed verification — that would bless the edit.
+          #
+          # @param ordinal [Integer] ordinal of the era the text belongs to
+          # @param text [String] the era's verified held source text
+          # @param stored_projection_json [String, nil] the row's stored projection as JSON text;
+          #   nil makes this derive one from `text` and store it, unless `text` does not load
+          # @return [void]
           def backfill_frozen_facts!(ordinal, text, stored_projection_json)
             archive_text!(ordinal, text)
             return if stored_projection_json
@@ -107,11 +150,27 @@ module Hecks
             )
           end
 
+          # Reports the ordinal of the newest era the domain holds.
+          #
+          # @return [Integer] the highest held ordinal, or 1 when no era is held yet
+          # @raise [Runtime::WiringError] if a held text no longer matches its stored digest
           def current_era
             held = eras
             held.empty? ? 1 : held.last[:ordinal]
           end
 
+          # Holds a domain's first source text as era 1 and makes era 1 the writable era.
+          #
+          # Call only while the domain holds no era — every caller checks `eras.empty?` first.
+          # An existing era 1 row is kept (`ON CONFLICT DO NOTHING`), but `advance_era!(1)` runs
+          # regardless, so calling this on a domain past era 1 would roll the write fence back.
+          #
+          # @param text [String] the bluebook source text to freeze as era 1
+          # @param projection [Hash{String => Object}, nil] the storage-shape projection of the
+          #   bluebook, as `Runtime::StorageShape.project` returns it; nil stores none
+          # @return [void]
+          # @raise [PG::Error] if Postgres refuses the insert or the policy change, as it does
+          #   for a role that does not own the journal
           def hold_first!(text, projection: nil)
             @db.exec_params(
               "INSERT INTO hecks_eras (domain, ordinal, held_text, held_digest, held_projection) " \
@@ -124,6 +183,15 @@ module Hecks
             advance_era!(1)
           end
 
+          # Copies one version of an era's text into `hecks_era_texts`, keyed by its digest.
+          #
+          # A version already archived is left alone (`ON CONFLICT DO NOTHING`), so every
+          # distinct text an era ever held survives a re-attestation.
+          #
+          # @param ordinal [Integer] ordinal of the era the text belongs to
+          # @param text [String] the source text to archive
+          # @return [void]
+          # @raise [PG::Error] if Postgres refuses the insert
           def archive_text!(ordinal, text)
             @db.exec_params(
               "INSERT INTO hecks_era_texts (domain, ordinal, digest, held_text) VALUES ($1, $2, $3, $4) " \
@@ -132,10 +200,19 @@ module Hecks
             )
           end
 
-          # A Layer-3 approval, recorded IN the database it was reviewed
+          # Records that a human approved a translation edge's audit samples.
+          #
+          # A Layer-3 approval, recorded in the database it was reviewed
           # against — bound to the edge's parsed content and the journal's
           # high-water ordinal at review time. The latest row for a shape
           # pair wins (re-approval supersedes).
+          #
+          # @param from [String] label of the era shape the edge leaves
+          # @param to [String] label of the era shape the edge leads to
+          # @param edge_digest [String] SHA-256 hex digest of the edge's parsed content, as
+          #   `Translation::Audit.edge_digest` computes it
+          # @return [void]
+          # @raise [PG::Error] if Postgres refuses the insert
           def record_approval!(from:, to:, edge_digest:)
             @db.exec_params(
               "INSERT INTO hecks_approvals (domain, from_label, to_label, edge_digest, reviewed_ordinal) " \
@@ -144,6 +221,13 @@ module Hecks
             )
           end
 
+          # Finds the most recent approval recorded for the edge between two era shapes.
+          #
+          # @param from [String] label of the era shape the edge leaves
+          # @param to [String] label of the era shape the edge leads to
+          # @return [Hash{Symbol => Object}, nil] `:edge_digest` (String, SHA-256 hex of the edge
+          #   that was reviewed) and `:reviewed_ordinal` (Integer, the journal's highest ordinal at
+          #   review time); nil when no approval is recorded for the pair
           def approval_for(from:, to:)
             rows = @db.exec_params(
               "SELECT edge_digest, reviewed_ordinal FROM hecks_approvals " \
@@ -155,8 +239,16 @@ module Hecks
             { edge_digest: rows[0]["edge_digest"], reviewed_ordinal: rows[0]["reviewed_ordinal"].to_i }
           end
 
-          # Era identity is minted ONCE and stored; nothing ever recomputes
+          # Stores an era's hash and label, only if the era has no hash yet.
+          #
+          # Era identity is minted once and stored; nothing ever recomputes
           # a stored name to verify it.
+          #
+          # @param ordinal [Integer] ordinal of the era to name
+          # @param hash [String] the era's shape hash, SHA-256 hex
+          # @param label [String] the short label edges and refusals use, a prefix of `hash`
+          # @return [void]
+          # @raise [PG::Error] if Postgres refuses the update
           def mint_name!(ordinal, hash, label)
             @db.exec_params(
               "UPDATE hecks_eras SET hash = $3, label = $4, canon_form = $5 " \
@@ -165,6 +257,9 @@ module Hecks
             )
           end
 
+          # Reads the journal's high-water mark across every era's partition.
+          #
+          # @return [Integer] the highest ordinal in the journal, or 0 when the journal is empty
           def last_ordinal
             @db.exec("SELECT COALESCE(max(ordinal), 0) AS o FROM #{quoted_journal}")[0]["o"].to_i
           end

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