hecks 2.7.0 → 2.9.0

data/lib/hecks/runtime/tenant_check.rb

@@ -3,62 +3,13 @@ require_relative "../ports/persistence/binding_policy"
 module Hecks
   module Runtime
     # 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
-    # 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.
-    #
-    # ## Why no ambient "current tenant"
-    #
-    # The project register (Bluebook::ProjectRegister) already resolves an
-    # address's 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
-    # (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.
-    #
-    # ## What `tenant_capable?` really asks
-    #
-    # Not "can this adapter switch tenants," but "does booting this
-    # adapter twice, with different settings, for the same directory,
-    # actually keep the two boots' data apart." Memory answers true
-    # trivially — a `@records` Hash is a plain instance variable, and
-    # two `Runtime.boot` calls build two entirely separate Registry
-    # objects, so two Memory adapter instances never share state by
-    # construction. PostgresEra answers true because its own `schema:`
-    # setting (already built, already the Storehouse mechanism) puts
-    # each boot's tables in their own Postgres schema via `SET
-    # search_path` — proven for real, not assumed, by
-    # tenant_isolation_spec.rb. Plain Postgres (no schema story) and D1
-    # (no schema-equivalent at all — see world.bluebook's own comment on
-    # the D1 tradeoff) answer false, or don't answer at all,
-    # which this module treats identically to false.
+    # own `lineage_capable?`, one level over.
     module TenantCheck
       module_function
 
-      # Refuses to let `domain` boot for more than one tenant unless every
-      # aggregate's resolved persistence adapter is `tenant_capable?`.
-      #
-      # 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
-      # a second tenant boot of the same directory is trusted, the same
-      # severity EraCheck/refuse_ungoverned_roles! already hold their
-      # own gates to.
-      #
-      # @param registry [Runtime::Registry] the booted registry to check
-      # @param domain [String, Symbol] the domain name to check every aggregate of
-      # @return [void]
-      # @raise [Runtime::WiringError] if any aggregate in `domain` is bound to an adapter
-      #   that is not `tenant_capable?`
+      # One ungoverned adapter sharing state across two tenant boots is a
+      # real data leak, so this is checked with the same severity
+      # EraCheck/refuse_ungoverned_roles! already hold their own gates to.
       def refuse_unless_tenant_capable!(registry, domain)
         bluebook = registry.bluebook(domain)
         return unless bluebook
@@ -78,21 +29,8 @@ module Hecks
               "or keep #{domain} single-tenant."
       end
 
-      # Answers whether `adapter_name`'s Ruby implementation keeps two
-      # tenants' boots of the same directory from sharing data.
-      #
-      # 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
-      # EraCheck#lineage_capable? already uses: a class that doesn't
-      # respond at all is false, not an error.
-      #
-      # @param registry [Runtime::Registry] the booted registry the adapter is wired into
-      # @param adapter_name [String] the adapter's declared name, such as `"PostgresEra"`
-      # @return [Boolean] true when the adapter is registered, has a Ruby implementation,
-      #   and answers `tenant_capable?` true; false for any other case, including a
-      #   missing adapter or one whose lookup raises
+      # Same defensive shape as EraCheck#lineage_capable? — a class that
+      # doesn't respond at all, or whose lookup raises, is false, not an error.
       def tenant_capable?(registry, adapter_name)
         adapter_class = registry.adapters[adapter_name] && registry.adapter_class(adapter_name)
         adapter_class.respond_to?(:tenant_capable?) && adapter_class.tenant_capable?

data/lib/hecks/runtime/tenant_scope.rb

@@ -5,27 +5,8 @@ require_relative "../query_specification/common/where_clause"
 
 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
-    # without a caller-identity/session system: the boundary itself, made
-    # 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.
-    #
-    # Enforcement is a synthetic `eq` where-clause, symbol-valued exactly
-    # the way a dynamic `where(field: :arg_name)` already resolves against
-    # args in every engine (QueryInterpreter#interpret,
-    # Ports::Query::InMemory, both SQL adapters via SqlQueryBuilder) — so
-    # every engine that already reads `.wheres` enforces the boundary for
-    # 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
-    # internal `wheres` call would resolve against the original object, not
-    # this override, since `SimpleDelegator` only intercepts calls made
-    # directly on the wrapper.
+    # Enforces the `authorize policy, tenant: :field` boundary as a synthetic `eq` where-clause.
+    # `Scoped` goes only to query engines; IR-level calls on it would bypass the override.
     module TenantScope
       module_function
 
@@ -52,13 +33,7 @@ module Hecks
         Scoped.new(declared, QuerySpecification::Common::WhereClause.new(field: tenant, op: "eq", value: tenant))
       end
 
-      # A SimpleDelegator wrapping one declared query/read-model spec
-      # with its tenant `eq` where-clause appended to #wheres — the
-      # object every query engine actually reads, so nothing beyond
-      # TenantScope.apply itself has to know the boundary exists. Never
-      # handed back to a caller that might call an IR-level method whose
-      # own internal `.wheres` read would bypass this override (see this
-      # module's own header for why).
+      # A SimpleDelegator whose #wheres has the tenant clause appended.
       class Scoped < SimpleDelegator
         # @param declared [Bluebook::Query, Bluebook::ReadModel] the specification to wrap,
         #   delegated to for everything but `#wheres`

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

@@ -4,9 +4,8 @@ require_relative "../refusal_wording"
 module Hecks
   module Runtime
     class Value
-      # Closed sets — `one_of` members and `admits:` declarations — and the
-      # refusals that make them rules rather than decoration. Extended into
-      # Value beside Coercion; `self` is the Value class.
+      # Closed sets (`one_of` members and `admits:` declarations) and their refusals.
+      # Extended into Value beside Coercion.
       module Admission
         # Refuses fields that match no declared member of a closed-set (`one_of`) value object.
         #
@@ -31,46 +30,20 @@ module Hecks
                                            admitted: admitted, offered: offered.inspect)
         end
 
-        # 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. 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)` 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 a discriminant-only
-        # comparison for every set that has one column — same refusal,
-        # same wording.
+        # Compares every declared field, not only the first: a multi-column `member` row is a
+        # whole tuple, so a matching first column with a wrong second is not a member.
         private def member_matches?(member, fields)
           member.all? { |field, value| fields[field].to_s == value.to_s }
         end
 
         # Checks a value against the closed set its attribute names with `admits:`.
         #
-        # The same refusal, for a set named somewhere else.
+        # Unlike `admit_member`, the set is declared elsewhere and named, not written inline.
         #
-        # `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
-        # 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
+        # @param owner [Bluebook::Aggregate, Bluebook::Entity, Bluebook::ValueObject] declares
+        #   `attribute`; the walk to the chapter starts here
+        # @param attribute [Bluebook::Attribute, nil] nil, or one with no `admits:`, checks nothing
+        # @param value [Object, nil] a bare scalar or a one-field `Runtime::Value`; nil is skipped
         # @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
@@ -89,23 +62,13 @@ module Hecks
 
         # 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
-        # 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
-        # link checked against nothing is worse than no link, because it reads
-        # like a rule.
+        # Resolved late, since the set may be declared below the attribute, and refused when
+        # it resolves to nothing.
         #
-        # @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
+        # @param owner [Bluebook::Aggregate, Bluebook::Entity, Bluebook::ValueObject] declares
+        #   `attribute`
+        # @param attribute [Bluebook::Attribute] an attribute whose `admits` is `"Aggregate::Set"`
+        # @return [Array<String>] each member's first-attribute value as a String, in 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)
@@ -125,11 +88,6 @@ module Hecks
 
         # 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.
-        #
         # @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
@@ -142,9 +100,6 @@ module Hecks
 
         # 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
@@ -155,13 +110,7 @@ module Hecks
           fields.size == 1 ? fields.values.first : value
         end
 
-        # 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
-        # value object is what gets built — no attribute passes through
-        # `for_attribute` on the way. Both doors, or the word means one thing on
-        # an argument and nothing on a field.
+        # Applies `admits:` to value-object fields too, which never pass through `for_attribute`.
         private def check_admitted(value_object, fields)
           value_object.attributes.each do |attribute|
             next unless attribute.admits