hecks 1.3.0 → 1.4.0

data/lib/hecks/runtime/saga_pending_dispatch.rb

@@ -1,13 +1,13 @@
 module Hecks
   module Runtime
-    # THE ONE SHARED CONSTANT between `SagaInterpreter` (the writer) and
+    # The one shared constant between `SagaInterpreter` (the writer) and
     # `Registry::SagaPersistence#rehydrate_sagas!` (the reader) for a
     # scoped, minimal answer to the saga-durability review's item 8 (a
     # durable outbox): a marker that survives exactly the window a crash
     # in `advance_saga`/`unwind` can otherwise hide.
     #
-    # THE PROBLEM THIS CLOSES — `checkpoint` persists a saga's new state
-    # BEFORE the leg that justifies it (`handler.dispatches`) runs, and
+    # **The problem this closes** — `checkpoint` persists a saga's new state
+    # before the leg that justifies it (`handler.dispatches`) runs, and
     # deliberately so: the mutex it holds is not reentrant, and a
     # dispatch can re-enter this same interpreter. If the process dies
     # in that window, the store says the transition happened and there
@@ -15,33 +15,33 @@ module Hecks
     # domain never got asked), not a defect (nothing raised), just
     # silence indistinguishable from a leg that finished cleanly.
     #
-    # THE FIX — `checkpoint` now writes this key into the SAME already-
+    # **The fix** — `checkpoint` now writes this key into the same already-
     # durable `memory` blob (no new column, no adapter/schema change:
     # `memory` is already an opaque, adapter-agnostic JSON blob every
     # `save_saga` implementation round-trips verbatim) whenever it
-    # checkpoints a state a dispatch cascade hasn't run for YET, and
+    # checkpoints a state a dispatch cascade hasn't run for yet, and
     # clears it (a second checkpoint, `pending: nil`) once that cascade
     # — success, refusal-compensated, defect-compensated, or ceiling-
     # compensated — has actually run. A crash between those two writes
     # leaves the marker standing; `rehydrate_sagas!` strips it back out
-    # of the LIVE instance's own `:memory` (so no dispatch/`given`/
+    # of the live instance's own `:memory` (so no dispatch/`given`/
     # fuzzer/doc consumer of a saga's memory ever sees this key — it
     # exists only in the persisted blob) and surfaces it loudly instead.
     #
-    # WHAT THIS DELIBERATELY DOES NOT DO — auto-redrive the pending leg.
+    # **What this deliberately does not do** — auto-redrive the pending leg.
     # Redelivering a dispatch whose outcome is genuinely unknown is only
     # safe with idempotent delivery (the downstream command recognizing
     # and no-op'ing a duplicate), which hecks's command/event pipeline
     # has no mechanism for today. Blindly re-dispatching without that is
-    # how a stalled transfer becomes a DOUBLE-CREDITED one — a strictly
+    # how a stalled transfer becomes a double-credited one — a strictly
     # worse defect than the stall it would replace. So this is real,
-    # durable, crash-surviving VISIBILITY into exactly what a stalled
+    # durable, crash-surviving visibility into exactly what a stalled
     # saga was doing when the process died — the missing half of "no
     # reconciliation pass exists". The full pending → claimed →
     # delivered outbox now exists too (`Runtime::Outbox`, ADR 0053) and
-    # is COMPLEMENTARY, not a replacement: the outbox row names the
-    # EVENT owed to this saga (and redrives it if the saga never got to
-    # claim it); this marker names the saga's own LEG mid-flight after
+    # is complementary, not a replacement: the outbox row names the
+    # event owed to this saga (and redrives it if the saga never got to
+    # claim it); this marker names the saga's own leg mid-flight after
     # the event was delivered. A crash can leave either standing.
     SAGA_PENDING_DISPATCH_KEY = :__hecks_saga_pending_dispatch__
   end

data/lib/hecks/runtime/tenant_check.rb

@@ -2,26 +2,26 @@ require_relative "../ports/persistence/binding_policy"
 
 module Hecks
   module Runtime
-    # The capability idiom for MULTI-TENANT hosting — mirrors EraCheck's
+    # The capability idiom for multi-tenant hosting — mirrors EraCheck's
     # own `lineage_capable?`, one level over. An adapter answers
-    # `tenant_capable?` with true when its OWN instances genuinely
+    # `tenant_capable?` with true when its own instances genuinely
     # isolate one boot's data from another's, given each tenant is its
     # own separate `Runtime.boot` call (its own Registry, its own
     # Dispatcher, its own adapter instances) rather than one shared
     # process switching connections mid-dispatch.
     #
-    # THAT LAST PART IS THE FINDING THIS MODULE ENCODES. The project
+    # That last part is the finding this module encodes. The project
     # register (Bluebook::ProjectRegister) already resolves an address's
-    # REALM to a DISPATCHER at registration time — Router#resolve looks
+    # realm to a dispatcher at registration time — Router#resolve looks
     # the FQN up in one flat table keyed by realm::domain::aggregate.verb,
-    # and each entry already carries its OWN dispatcher from its OWN
-    # boot. So "which tenant" is decided ONCE, at boot/registration time
+    # and each entry already carries its own dispatcher from its own
+    # boot. So "which tenant" is decided once, at boot/registration time
     # (which of possibly many boots of the same directory a request's
     # realm resolves to), never per-dispatch inside a shared registry.
     # No ambient thread-local "current tenant" is needed, and no
     # connection cache is needed beyond what booting-once-per-tenant
     # already gives for free — each tenant's own PostgresEra instance
-    # IS its own connection, held for the life of that boot.
+    # is its own connection, held for the life of that boot.
     #
     # So `tenant_capable?` asks a narrower question than it might sound:
     # not "can this adapter switch tenants," but "does booting this
@@ -41,7 +41,7 @@ module Hecks
     module TenantCheck
       module_function
 
-      # A domain is safe to boot for MORE THAN ONE TENANT only if every
+      # A domain is safe to boot for more than one tenant only if every
       # aggregate's resolved persistence adapter is tenant_capable? — one
       # ungoverned adapter sharing state across two tenant boots is a
       # real data leak, not a theoretical one, so this is checked before
@@ -67,7 +67,7 @@ module Hecks
               "or keep #{domain} single-tenant."
       end
 
-      # The capability idiom itself — an adapter CLASS that answers
+      # The capability idiom itself — an adapter class that answers
       # tenant_capable? with true keeps two boots' data apart by
       # construction (Memory) or by an explicit per-boot isolation
       # setting (PostgresEra's schema:). Same defensive shape

data/lib/hecks/runtime/tenant_scope.rb

@@ -7,9 +7,9 @@ module Hecks
   module Runtime
     # `authorize policy, tenant: :field` declared a tenant boundary that
     # nothing enforced — the policy name and the field were stored and read
-    # by nothing at dispatch time. This is the half that CAN be enforced
+    # by nothing at dispatch time. This is the half that can be enforced
     # without a caller-identity/session system: the boundary itself, made
-    # mandatory. Whether THIS caller actually holds `policy` for THIS
+    # mandatory. Whether this caller actually holds `policy` for this
     # tenant needs real identity infrastructure this runtime does not have
     # — that stays a named, open gap, not something this quietly pretends
     # to answer.
@@ -22,7 +22,7 @@ module Hecks
     # free, with no per-engine code and no way for one engine to forget it.
     # `Scoped` is handed only to those engines as their `declared`/
     # `specification` argument — never returned to a caller that might call
-    # an IR-level method (`filtered_head_name`, `to_h`, …) whose OWN
+    # an IR-level method (`filtered_head_name`, `to_h`, …) whose own
     # internal `wheres` call would resolve against the original object, not
     # this override, since `SimpleDelegator` only intercepts calls made
     # directly on the wrapper.
@@ -35,8 +35,8 @@ module Hecks
 
         tenant = tenant.to_sym
         unless args.key?(tenant)
-          raise Unauthorized, RefusalWording.render("Unauthorized", "tenant_required",
-                                                    query: declared.name, field: tenant)
+          raise Unauthorized, RefusalWording.render_site("Unauthorized", "tenant_required",
+                                                         query: declared.name, field: tenant)
         end
 
         Scoped.new(declared, QuerySpecification::Common::WhereClause.new(field: tenant, op: "eq", value: tenant))

data/lib/hecks/runtime/value/admission.rb

@@ -8,6 +8,15 @@ module Hecks
       # refusals that make them rules rather than decoration. Extended into
       # Value beside Coercion; `self` is the Value class.
       module Admission
+        # Refuses fields that match no declared member of a closed-set (`one_of`) value object.
+        #
+        # @param value_object [Bluebook::ValueObject] the type being built; one with no
+        #   members is not a closed set and is never refused
+        # @param fields [Hash{Symbol => Object}] the offered fields, keyed by attribute name
+        # @return [nil] when the type has no members, or some member matches on every
+        #   field it names
+        # @raise [Runtime::InvariantViolation] if no member matches; the message lists the
+        #   admitted values of the first attribute and the one offered
         def admit_member(value_object, fields)
           return if value_object.members.empty?
 
@@ -17,42 +26,54 @@ module Hecks
           return if value_object.members.any? { |member| member_matches?(member, fields) }
 
           raise InvariantViolation,
-                RefusalWording.render("InvariantViolation", "closed_set_member",
-                                      type: value_object.hecks_name,
-                                      admitted: admitted.map(&:inspect).join(", "), offered: offered.inspect)
+                RefusalWording.render_site("InvariantViolation", "closed_set_member",
+                                           type: value_object.hecks_name,
+                                           admitted: admitted, offered: offered.inspect)
         end
 
-        # EVERY DECLARED FIELD, not only the discriminant — a multi-column
+        # Every declared field, not only the discriminant — a multi-column
         # `member` row (`StatementFrequency`'s `cadence`/`retention_months`/
         # `paper_fee_cents`, statements.bluebook) names a whole tuple, and a
         # caller offering the right `cadence` with the wrong
-        # `retention_months` is not a genuine member just because the FIRST
-        # column happened to match. `admitted.include?(offered.to_s)` above
-        # used to be the entire check, so it stopped at that first column —
+        # `retention_months` is not a genuine member just because the first
+        # column happened to match. Comparing only the discriminant
+        # (`admitted.include?(offered.to_s)`) stops at that first column —
         # confirmed live: `Value.build(StatementFrequency, cadence:
-        # "monthly", retention_months: 999, paper_fee_cents: 999)` was
-        # admitted outright, no member of the closed set declares that row.
+        # "monthly", retention_months: 999, paper_fee_cents: 999)` would be
+        # admitted outright, though no member of the closed set declares that row.
         # A single-field set (`AccountKind`, `LedgerDirection`, ...) has
-        # exactly one key here, so this reduces to the original discriminant-
-        # only comparison for every set that only ever had one column to
-        # begin with — same refusal, same wording, unchanged.
+        # exactly one key here, so this reduces to a discriminant-only
+        # comparison for every set that has one column — same refusal,
+        # same wording.
         private def member_matches?(member, fields)
           member.all? { |field, value| fields[field].to_s == value.to_s }
         end
 
-        # THE SAME REFUSAL, FOR A SET NAMED SOMEWHERE ELSE.
+        # Checks a value against the closed set its attribute names with `admits:`.
+        #
+        # The same refusal, for a set named somewhere else.
         #
-        # `admit_member` above refuses a non-member when the value object BEING
-        # BUILT is itself the closed set — which is the only shape `one_of` can
-        # make, because it SYNTHESISES the set from the values written inline. An
+        # `admit_member` above refuses a non-member when the value object being
+        # built is itself the closed set — which is the only shape `one_of` can
+        # make, because it synthesises the set from the values written inline. An
         # `admits:` attribute is the other direction: the value is an ordinary
         # String or a plain text holder, and the set it must belong to was
         # declared once, elsewhere, and is named rather than restated.
         #
-        # Without this the word was a DECLARATION and nothing more — read by
+        # Without this the word was a declaration and nothing more — read by
         # projections, read by nobody at the door. A rule
         # that cannot be the one to refuse is decoration, and this language has
         # paid for that mistake before.
+        #
+        # @param owner [Bluebook::Aggregate, Bluebook::Entity, Bluebook::ValueObject] the
+        #   construct that declares `attribute`; the walk to the chapter starts here
+        # @param attribute [Bluebook::Attribute, nil] the attribute being filled; nil, or one
+        #   with no `admits:`, means nothing is checked
+        # @param value [Object, nil] the coerced value: a bare scalar, or a `Runtime::Value`
+        #   holding one field; nil is never checked
+        # @return [Object, nil] `value`, unchanged
+        # @raise [Runtime::InvariantViolation] if the value is not a member of the named set,
+        #   or `admits:` names a set no aggregate in the chapter declares
         def admit_declared_set(owner, attribute, value)
           return value if attribute.nil? || attribute.admits.nil? || value.nil?
 
@@ -61,21 +82,32 @@ module Hecks
           return value if admitted.include?(offered.to_s)
 
           raise InvariantViolation,
-                RefusalWording.render("InvariantViolation", "admits_declared_set",
-                                      name: attribute.name, admits: attribute.admits,
-                                      admitted: admitted.map(&:inspect).join(", "), offered: offered.inspect)
+                RefusalWording.render_site("InvariantViolation", "admits_declared_set",
+                                           name: attribute.name, admits: attribute.admits,
+                                           admitted: admitted, offered: offered.inspect)
         end
 
-        # `Vocabulary::MutationOp` — the aggregate that HOLDS the set, then the
-        # set. Qualified because a closed set is a value object INSIDE an
+        # Lists the values the closed set named by an attribute's `admits:` allows.
+        #
+        # `Vocabulary::MutationOp` — the aggregate that holds the set, then the
+        # set. Qualified because a closed set is a value object inside an
         # aggregate, which is exactly why `admits` could not be spelled as a
         # reference: `reference_to` reaches aggregate heads and nothing below one.
         #
-        # RESOLVED LATE, like `Reference#resolve` and for the same reason — the
+        # Resolved late, like `Reference#resolve` and for the same reason — the
         # set may be declared further down the file than the attribute that names
-        # it. And REFUSED when it resolves to nothing, also like `Reference`: a
+        # it. And refused when it resolves to nothing, also like `Reference`: a
         # link checked against nothing is worse than no link, because it reads
         # like a rule.
+        #
+        # @param owner [Bluebook::Aggregate, Bluebook::Entity, Bluebook::ValueObject] the
+        #   construct that declares `attribute`
+        # @param attribute [Bluebook::Attribute] an attribute whose `admits` is
+        #   `"Aggregate::SetName"`
+        # @return [Array<String>] each member's value for the set's first attribute, as a String,
+        #   in declaration order
+        # @raise [Runtime::InvariantViolation] if `admits` is not qualified, no chapter is
+        #   reachable from `owner`, or the chapter declares no such aggregate or value object
         def admitted_members(owner, attribute)
           aggregate_name, set_name = attribute.admits.to_s.split("::", 2)
           chapter = chapter_of(owner)
@@ -83,26 +115,39 @@ module Hecks
 
           unless set
             raise InvariantViolation,
-                  RefusalWording.render("InvariantViolation", "undeclared_set",
-                                        name: attribute.name, admits: attribute.admits)
+                  RefusalWording.render_site("InvariantViolation", "undeclared_set",
+                                             name: attribute.name, admits: attribute.admits)
           end
 
           discriminant = set.attributes.first.name
           set.members.map { |member| member.to_h[discriminant].to_s }
         end
 
-        # UP TO THE CHAPTER, from wherever the attribute was declared. A value
+        # Walks `hecks_owner` links upward until it reaches the chapter.
+        #
+        # Up to the chapter, from wherever the attribute was declared. A value
         # object's owner is its aggregate and an aggregate's owner is its chapter,
         # so the walk stops at the first construct that can answer for an
-        # aggregate BY NAME — which is the chapter, and only the chapter.
+        # aggregate by name — which is the chapter, and only the chapter.
+        #
+        # @param construct [Bluebook::ValueObject, Bluebook::Entity, Bluebook::Aggregate,
+        #   Bluebook::Chapter, nil] the construct to start from; the chapter answers itself
+        # @return [Bluebook::Chapter, nil] the first construct on the way up that responds to
+        #   `aggregate`; nil when the chain ends without one
         def chapter_of(construct)
           node = construct
           node = node.hecks_owner while node && !node.respond_to?(:aggregate) && node.respond_to?(:hecks_owner)
           node.respond_to?(:aggregate) ? node : nil
         end
 
-        # An admitted value is a SCALAR however it arrived — as a bare string on a
+        # Unwraps a one-field value object to the scalar it holds, so membership compares scalars.
+        #
+        # An admitted value is a scalar however it arrived — as a bare string on a
         # plain field, or wrapped in the one-field holder its type names.
+        #
+        # @param value [Object] a bare scalar, or a `Runtime::Value`
+        # @return [Object] the sole field's value for a one-field `Runtime::Value`; otherwise
+        #   `value` itself, a multi-field `Runtime::Value` included
         def admitted_scalar(value)
           return value unless value.is_a?(self)
 
@@ -110,7 +155,7 @@ module Hecks
           fields.size == 1 ? fields.values.first : value
         end
 
-        # A FIELD OF A VALUE OBJECT MAY NAME A SET TOO.
+        # A field of a value object may name a set too.
         #
         # Beside check_patterns and for the same reason: `Query::Filter.op` is a
         # plain String field that admits `Vocabulary::QueryComparator`, and the