hecks 1.2.0 → 1.4.0

data/lib/hecks/runtime/command_rules/references.rb

@@ -1,11 +1,13 @@
 require_relative "../errors"
 require_relative "../refusal_wording"
 require_relative "../value"
+require_relative "../../rendering"
+require_relative "../../ports/query/in_memory"
 
 module Hecks
   module Runtime
     class CommandRules
-      # A reference must point at something that EXISTS.
+      # A reference must point at something that exists.
       #
       # `reference_to Customer` is the one guarantee an aggregate reference is
       # for, and it was declared 14 times across banking and enforced nowhere :
@@ -14,7 +16,7 @@ module Hecks
       # no corpus step ever passed a dangling reference.
       module References
         # Resolved here rather than in coercion because coercion is pure — it
-        # holds no repository. A reference INTO ANOTHER DOMAIN is left alone : a
+        # holds no repository. A reference into another domain is left alone : a
         # cross-domain target may legitimately not be loaded, which is the same
         # reading `across` policies already get.
         #
@@ -40,6 +42,8 @@ module Hecks
         # This is what makes a `has_many` declared on an aggregate honest even
         # when a command supplies its list through an ordinary typed argument.
         def resolve_state_references(domain, construct, state)
+          own_tenant_field = tenant_field_for(construct)
+
           construct.attributes.each do |attribute|
             next unless attribute.reference?
 
@@ -51,6 +55,7 @@ module Hecks
             next unless target
 
             validate_reference_values(domain, target, held, list: attribute.list?)
+            enforce_tenant_boundary(domain, construct, attribute, target, held, state, own_tenant_field)
           end
 
           Array(construct.entities).each do |entity|
@@ -78,7 +83,7 @@ module Hecks
                 "#{attribute.type.target_name} identity, got nil"
         end
 
-        # The reference RESOLVES itself — through the chapter's own IR, so the
+        # The reference resolves itself — through the chapter's own IR, so the
         # bluebook's declared heads are the index. This used to regex the target's
         # name out of "Reference<Customer>" and then search
         # `registry.bluebook(domain).aggregates` for it — and later reached the
@@ -96,31 +101,101 @@ module Hecks
             next if @registry.repository(domain, target).find(key)
 
             raise NotFound,
-                  RefusalWording.render("NotFound", "reference_target_missing",
-                                        target: target.name, heads: target.identity_heads.join(", "),
-                                        key: key.inspect)
+                  RefusalWording.render_site("NotFound", "reference_target_missing",
+                                             target: target.name, heads: target.identity_heads.join(", "),
+                                             key: key)
+          end
+        end
+
+        # Angle-8's own write-side half of `TenantScope.apply` (runtime/
+        # tenant_scope.rb) — the query-side mechanism this mirrors. That
+        # module turns a declared `authorize policy, tenant: :field` into a
+        # synthetic where-clause checked against the caller's own supplied
+        # tenant argument; there is no caller-identity/session system this
+        # runtime has to check a write's caller against (TenantScope's own
+        # header names that as a separate, still-open gap), so this checks
+        # the one thing that is available without one: whether the record
+        # being written and the record it references agree about which
+        # tenant they belong to. `lib/hecks/fuzzing/properties/guards.rb`'s
+        # `commands_respect_tenant_scope` states the identical claim,
+        # read off `history[:instances]` after the fact — this is what
+        # makes that claim hold by construction (a refused write is never
+        # stored) rather than merely checked for regression.
+        #
+        # Hooked into `resolve_state_references` rather than a new
+        # DISPATCH_ORDER step deliberately: that method already walks
+        # every `reference_to`-typed attribute against the settled,
+        # post-mutation state (the same moment `commands_respect_tenant_
+        # scope` itself inspects), already resolves the referenced record
+        # through the repository right above, and already runs from both
+        # `CommandInterpreter#step_save` and `EntityInterpreter#step_save`
+        # — one change, both interpreters covered, no new vocabulary step
+        # to keep in sync with `Vocabulary::AggregateDispatchOrder`/
+        # `EntityDispatchOrder`.
+        def enforce_tenant_boundary(domain, construct, attribute, target, held, state, own_tenant_field)
+          return unless own_tenant_field && state.key?(own_tenant_field)
+
+          target_tenant_field = tenant_field_for(target)
+          return unless target_tenant_field
+
+          own_tenant = Ports::Query::InMemory.comparable(state[own_tenant_field])
+
+          values = attribute.list? ? Array(held) : [held]
+          values.each do |value|
+            key = reference_key(value)
+            next if key.empty?
+
+            record = @registry.repository(domain, target).find(key)
+            next unless record&.state&.key?(target_tenant_field)
+
+            target_tenant = Ports::Query::InMemory.comparable(record.state[target_tenant_field])
+            next if target_tenant == own_tenant
+
+            raise Unauthorized,
+                  RefusalWording.render_site("Unauthorized", "cross_tenant_reference",
+                                             aggregate: construct.hecks_name, field: own_tenant_field,
+                                             tenant: Rendering.describe(state[own_tenant_field]),
+                                             attribute: attribute.name, target: target.name,
+                                             target_field: target_tenant_field,
+                                             other: Rendering.describe(record.state[target_tenant_field]))
           end
         end
 
-        # `value` is the referenced record's own id, EXACTLY as `Identity.of`
+        # The field an aggregate's own query names as tenant-scoping — the
+        # exact same lookup `Fuzzing::Properties::Guards#tenant_field_for`
+        # already established for the property that found this gap, reused
+        # here rather than reinvented: an aggregate's own declared tenant
+        # field is whichever field one of its own queries names in
+        # `authorize policy, tenant: :field`. `nil` for a construct that
+        # declares no such query — not every aggregate is tenant-scoped,
+        # and an entity never declares a query of its own at all today
+        # (`Entity.queries` is always empty in the real corpus), so this
+        # answers `nil` for every entity without needing to special-case
+        # one.
+        def tenant_field_for(construct)
+          authorization = construct.queries.filter_map(&:authorization).find(&:tenant)
+          authorization&.tenant&.to_sym
+        end
+
+        # `value` is the referenced record's own id, exactly as `Identity.of`
         # would build it for that record — a bare scalar for a single-field
         # identity (the overwhelming common case; Banking's own plain
         # `reference_to Customer` holds one already, so `Value.
         # materialize_unwrapped` is a no-op passthrough here), or a
         # `Naming.identity`-joined string for a compound one
         # (`belongs_to Translation, as: :translation_ref` — Translation's
-        # own `identified_by :domain, :from, :to`, THREE fields). Before
+        # own `identified_by :domain, :from, :to`, three fields). Before
         # this, plain `value.to_s` on that compound case's own coerced
         # Value hit Ruby's default `Object#to_s` (a raw, run-to-run-random
         # memory address) instead of joining the record's real id — found
         # live via bin/fuzz on the self-hosted "translation" domain
-        # (replay_is_deterministic), the SAME class of gap `Identity.from`
+        # (replay_is_deterministic), the same class of gap `Identity.from`
         # already had for a compound `identified_by`'s own bare (undotted)
         # attribute paths. `materialize_unwrapped` recurses a multi-
         # attribute value object to a plain Hash keyed by attribute name,
         # in declaration order — `Naming.identity` on `.values` reproduces
         # the identical join `Identity.of` itself would produce for the
-        # SAME fields.
+        # same fields.
         def reference_key(value)
           unwrapped = Value.materialize_unwrapped(value)
           return Naming.identity(unwrapped.values).to_s if unwrapped.is_a?(Hash)
@@ -128,35 +203,35 @@ module Hecks
           unwrapped.to_s
         end
 
-        # A COMMAND ARGUMENT's own related record, reachable by name from
+        # A command argument's own related record, reachable by name from
         # `given`/`ensures` — `disputed_by.status`, say, `CardPayment
         # .Dispute`'s own fresh `Reference<Customer>` argument — without
         # teaching the pure expression evaluator anything about
-        # repositories. The lookup happens HERE, once, before evaluation;
+        # repositories. The lookup happens here, once, before evaluation;
         # `Resolver#lookup` just digs into a plain Hash exactly as it
         # always has.
         #
-        # `owner` NARROWED TO `command` ONLY (S12, ADR 0025 — "rules
+        # `owner` narrowed to `command` only (S12, ADR 0025 — "rules
         # confined to their own aggregate boundary"): dereferencing the
-        # DECLARING aggregate/entity's own STORED `reference_to` used to
+        # declaring aggregate/entity's own stored `reference_to` used to
         # be the other half of this method's job — a live query against
         # another aggregate's own repository, every time a `given`/
         # `ensures`/`invariant` ran. That half is gone; a cross-aggregate
-        # fact a rule needs now has to be a `projects`-maintained LOCAL
+        # fact a rule needs now has to be a `projects`-maintained local
         # field (`AggregateBuilder#projects_impl`'s own comment), already
         # present in `subject`'s own state, no hydration needed. A
-        # reference-typed COMMAND ARGUMENT stays in bounds, though — the
+        # reference-typed command argument stays in bounds, though — the
         # ADR's own boundary list names "its command arguments" as
         # readable, and nothing is stored yet for a fresh argument to
-        # project from; resolving it once here, synchronous with THIS
+        # project from; resolving it once here, synchronous with this
         # command's own admission, is a different shape from a live query
-        # against an ALREADY-PERSISTED reference. `enforce_givens`/
+        # against an already-persisted reference. `enforce_givens`/
         # `enforce_ensures` are this method's only two remaining callers,
         # both passing `command`/`args`, never a `subject`'s own
         # aggregate — verified before this comment was written, not
         # assumed.
         #
-        # RECURSES into what it finds, so a chain deeper than one hop
+        # Recurses into what it finds, so a chain deeper than one hop
         # still resolves in one pass. Depth-bounded rather than cycle-
         # detected — nothing in this corpus dots more than two hops on a
         # fresh argument, and a bound is simpler than tracking visited

data/lib/hecks/runtime/command_rules.rb

@@ -20,6 +20,9 @@ module Hecks
 
       attr_reader :registry
 
+      # @param registry [Runtime::Registry, nil] the booted registry the rules read bluebooks,
+      #   repositories and the event log from; nil serves only the rules that read no
+      #   registry, such as `sign_of`
       def initialize(registry)
         @registry = registry
       end

data/lib/hecks/runtime/dependency_planning.rb

@@ -74,12 +74,12 @@ module Hecks
         STATEFUL_MUTATIONS = %i[append increment decrement multiply clamp remove].freeze
 
         # `root_aggregate:` — Wave 8's own audit surfaced a real bug here,
-        # not merely a missing feature: for an ENTITY-owned command,
+        # not merely a missing feature: for an entity-owned command,
         # `EntityInterpreter` calls this with `aggregate:` set to the
-        # ENTITY itself (`element_interpreter.rb`'s own `Analyzer.call
+        # entity itself (`element_interpreter.rb`'s own `Analyzer.call
         # (aggregate: entity, command:)`), so `owner_fields` was always
         # the entity's own attribute set. A `given`/`ensures` reading
-        # `parent.X` legitimately means the ROOT aggregate's own field —
+        # `parent.X` legitimately means the root aggregate's own field —
         # a genuinely different owner — but `classify_path`'s `:parent`
         # branch checked that read against `owner_fields` (the entity's),
         # which can never contain a root-level field, so every entity
@@ -96,10 +96,10 @@ module Hecks
           @owner_fields << aggregate.lifecycle.field.to_sym if aggregate.lifecycle
           @root_owner_fields = root_aggregate.attributes.to_set(&:name)
           @root_owner_fields << root_aggregate.lifecycle.field.to_sym if root_aggregate.lifecycle
-          # `projects` FIELDS (S12, ADR 0025) ARE OWNER STATE TOO — a
+          # `projects` fields (S12, ADR 0025) are owner state too — a
           # `given`/`ensures` reading one (e.g. `customer_status ==
           # "active"`) is reading this record's own stored field, same
-          # as any attribute, even though nothing here WRITES it via a
+          # as any attribute, even though nothing here writes it via a
           # declared mutation (`CommandInterpreter#seed_projected_fields`
           # populates it outside this analysis entirely). Left out of
           # `known_writes` deliberately: `add_preservation_reads` then
@@ -107,7 +107,7 @@ module Hecks
           # a partial mutation, which is exactly right — a projected
           # field's freshness comes from the interpreter reseeding it on
           # save, not from anything a caller-supplied write set carries.
-          # Applies to BOTH `owner_fields` and `root_owner_fields` — an
+          # Applies to both `owner_fields` and `root_owner_fields` — an
           # entity's own `parent.*` read can name the root aggregate's
           # projected field just as easily as one of its real attributes
           # (`Banking::Withdrawal.Dispute`'s own `parent.account_customer_
@@ -237,7 +237,7 @@ module Hecks
           end
         end
 
-        # KNOWN, HARMLESS GAP: `corrects ..., as: :name`'s bound name
+        # Known, harmless gap: `corrects ..., as: :name`'s bound name
         # (admissibility.rb's `enforce_correction_target`/`enforce_givens`/
         # `enforce_ensures`) isn't special-cased here the way `:old`/
         # `:parent` are — a given/ensures referencing it falls through to
@@ -247,7 +247,7 @@ module Hecks
         # `hydrate_existing` path instead of the `ATOMIC_PUT` fast path.
         # Not a correctness bug — `as:`'s runtime binding (a plain `attrs`
         # merge, exactly like `old:`'s) resolves and evaluates correctly
-        # regardless of what this STATIC analysis concludes — just a real,
+        # regardless of what this static analysis concludes — just a real,
         # deliberately-left optimization gap: closing it would mean
         # threading "which names this command declares as correction
         # bindings" into the Analyzer, which doesn't have that per-command
@@ -258,9 +258,9 @@ module Hecks
           name = head.to_sym
 
           if name == :parent
-            # `root_owner_fields` — NOT `owner_fields`. For an entity-owned
-            # command `owner_fields` is the ENTITY's own attribute set;
-            # `parent.X` always means the ROOT aggregate's own field, a
+            # `root_owner_fields` — not `owner_fields`. For an entity-owned
+            # command `owner_fields` is the entity's own attribute set;
+            # `parent.X` always means the root aggregate's own field, a
             # genuinely different owner (`root_aggregate:`'s own header,
             # above, has the full bug this fixes). Identical for a plain
             # aggregate command, where root_aggregate defaults to aggregate