hecks 2.7.0 → 2.9.0

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

@@ -6,25 +6,10 @@ module Hecks
   module Adapters
     class PostgresEra
       class Lineage
-        # CRUD over `hecks_eras`/`hecks_era_texts`/`hecks_approvals`: reading
-        # and tamper-verifying held era text, archiving every frozen text
-        # version, recording a Layer-3 approval, and minting an era's name
-        # once (never recomputed after).
+        # CRUD over `hecks_eras`/`hecks_era_texts`/`hecks_approvals`: era text
+        # integrity, archiving, Layer-3 approvals, and once-only era naming.
         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
-          # the canonical projection, minted once, never recomputed): it
-          # 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
+          # Verifies each held text's digest before returning it; a missing digest is backfilled.
           def eras
             @db.exec_params(
               "SELECT ordinal, hash, label, held_text, watermark, held_digest, held_projection::text " \
@@ -37,15 +22,7 @@ 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
+          # Skips the integrity check `eras` runs, so bin/reattest_era can show the raw row first.
           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",
@@ -57,17 +34,7 @@ module Hecks
               held_projection: rows[0]["held_projection"] }
           end
 
-          # 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`.
-          #
-          # @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
+          # Resolves drift via an append-only attestation record — never patch the digest.
           def reattest!(ordinal)
             era = raw_era(ordinal)
             raise Runtime::WiringError, "#{@domain} holds no era #{ordinal} to re-attest" unless era
@@ -94,19 +61,7 @@ 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`
+          # A row with no stored digest yet is backfilled, not refused; only a mismatch raises.
           def verify_integrity!(ordinal, text, stored_digest, stored_projection_json)
             digest = Digest::SHA256.hexdigest(text)
             if stored_digest.nil?
@@ -125,17 +80,7 @@ module Hecks
             raise Runtime::WiringError, Runtime::EraTamper.refusal(domain: @domain, ordinal: ordinal)
           end
 
-          # 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]
+          # Call only on already-verified text; this would bless an unverified edit.
           def backfill_frozen_facts!(ordinal, text, stored_projection_json)
             archive_text!(ordinal, text)
             return if stored_projection_json
@@ -150,27 +95,12 @@ 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
+          # Call only while the domain holds no era; this always advances the write fence to era 1.
           def hold_first!(text, projection: nil)
             @db.exec_params(
               "INSERT INTO hecks_eras (domain, ordinal, held_text, held_digest, held_projection) " \
@@ -178,20 +108,11 @@ module Hecks
               [@domain, text, Digest::SHA256.hexdigest(text), projection && JSON.generate(projection)]
             )
             archive_text!(1, text)
-            # Era 1 is the current era from its first moment — established
-            # here, not left to whichever role happens to boot first.
+            # Set explicitly here, not left to whichever role happens to boot first.
             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
+          # Left alone if already archived, so re-attestation never duplicates a text version.
           def archive_text!(ordinal, text)
             @db.exec_params(
               "INSERT INTO hecks_era_texts (domain, ordinal, digest, held_text) VALUES ($1, $2, $3, $4) " \
@@ -200,19 +121,7 @@ module Hecks
             )
           end
 
-          # 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
+          # Always inserts a new row; `approval_for` picks the latest for a shape pair.
           def record_approval!(from:, to:, edge_digest:)
             @db.exec_params(
               "INSERT INTO hecks_approvals (domain, from_label, to_label, edge_digest, reviewed_ordinal) " \
@@ -221,13 +130,6 @@ 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 " \
@@ -239,16 +141,7 @@ module Hecks
             { edge_digest: rows[0]["edge_digest"], reviewed_ordinal: rows[0]["reviewed_ordinal"].to_i }
           end
 
-          # 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
+          # Sets hash/label only once; nothing ever recomputes a stored name to verify it.
           def mint_name!(ordinal, hash, label)
             @db.exec_params(
               "UPDATE hecks_eras SET hash = $3, label = $4, canon_form = $5 " \
@@ -257,9 +150,6 @@ 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,105 +4,39 @@ module Hecks
   module Adapters
     class PostgresEra
       class Lineage
-        # The per-`where`-field read cache that lets a declared query find
-        # its ids without reducing the whole aggregate first.
+        # Per-`where`-field cache tables that let a declared query find ids without reducing
+        # the whole aggregate. Holds (id, ordinal, value); lists are not cached
+        # (see `eligible_for_cache?`).
         #
-        # ## 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
-        # 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
-        # `head_view` itself changes nothing, because the planner cannot
-        # prove a predicate on a non-partition column commutes with
-        # `DISTINCT ON` without risking a stale row winning).
-        #
-        # ## 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
-        # reduction because `id` is its own partition key, unlike the
-        # original field.
-        #
-        # ## 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
-        # 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.
+        # A `where` on a non-`id` field cannot be pushed through the `DISTINCT ON` reduction in
+        # `head_view`, so a query on a cached field reads `<field>_cache` first, then `head_view`
+        # by `id` (its partition key).
         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.
-          # deadline_at`) combined with a long storage name could exceed
-          # 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.
+          # Hashed to stay under Postgres's 63-byte identifier limit; `@domain` is hashed in
+          # so two domains sharing a database never share a table (ADR 0059).
           #
           # @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"`
+          # @param field [String] the cached `where` field, dotted for a value-object member
           # @return [String] unquoted table name, `hecks_fc_` plus 20 hex characters
           def field_cache(storage_name, era, field)
             "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.
+          # Creates one field's cache table if missing, then backfills it from the current head.
           #
-          # Self-healing, same idiom as `ensure_head_snapshot!`: cheap,
-          # 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
-          # 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
-          # second hand-rolled copy that could silently drift from what a
-          # live query actually filters on.
+          # Safe to call on every boot. Creation holds a short lock; the backfill runs outside it,
+          # one chunk per lock, never one transaction over the scan. `value_expression` is the
+          # SQL `query_expression(field)` compiles, so cache and live queries agree on the value.
           #
           # @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`
+          # @param value_expression [String] SQL extracting the value as text from jsonb `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)
@@ -124,19 +58,15 @@ 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.
+          # Fills an existing cache table from the reduced head, one committed chunk at a time,
+          # resuming from the cursor in `hecks_backfill_progress`; a no-op once 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`
+          # @param value_expression [String] SQL extracting the value as text from jsonb `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,
@@ -153,27 +83,16 @@ module Hecks
             )
           end
 
-          # Upserts one id's cached value from the state being written, leaving the
-          # row alone when it already carries an equal or newer ordinal.
+          # Upserts one id's cached value from the state being written, unless the row 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
-          # `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.
+          # Runs in the journal insert's transaction; `state_json` binds as jsonb `state`.
           #
           # @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 ordinal [String, Integer] the journal ordinal the entry was written at
           # @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`
+          # @param value_expression [String] SQL extracting the value as text from jsonb `state`
           # @return [void]
           # @raise [PG::Error] if Postgres refuses the upsert
           def upsert_field_cache_row!(name, id, ordinal, state_json, value_expression)
@@ -186,38 +105,21 @@ 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.
+          # Removes a deleted id's row so a cached-field query stops offering it. Called from
+          # `append` for a delete entry, in the same transaction as the journal insert.
           #
           # @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
 
           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,
-          # which for era > 1 can come from either this era's own live
-          # 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
-          # 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
-          # 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
-          # 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
-          # means the right thing with no era-aware special case.
+          # The reduced (id, ordinal, state) source a cache backfills from. Unlike the head
+          # snapshot's source it reduces the ancestor tail too (era N > 1 mirrors `compile_head!`)
+          # with ordinal kept; ordinals share one sequence per domain, so `ordinal <` holds.
           def field_cache_source_sql(storage_name, era, value_expression)
             era = era.to_i
             if era == 1
@@ -231,9 +133,7 @@ module Hecks
               if view && view_exists?(view)
                 "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) —
-                # the live snapshot side alone is the whole truth so far.
+                # No compiled ancestor matview yet (era just minted): snapshot side only.
                 "SELECT NULL::bigint AS ordinal, NULL::text AS id, NULL::jsonb AS state WHERE FALSE"
               end