hecks 0.2.0 → 0.3.0

data/lib/hecks/runtime/storage_shape.rb

@@ -0,0 +1,120 @@
+require "json"
+require "digest"
+
+module Hecks
+  module Runtime
+    # The storage-shape projection of a bluebook: exactly the parts of
+    # the IR that decide what persisted data looks like — aggregates,
+    # their attributes (with full value-object/entity structure and
+    # cardinality), references, the lifecycle field, and the identity
+    # paths. Everything behavioral — commands, invariants, queries,
+    # policies, lifecycle transitions, defaults, descriptions, comments,
+    # the declared routing `version:` — is excluded, so editing behavior
+    # never bumps an era and editing shape always does.
+    #
+    # Three attribute facts on the wire are constraints on PERSISTED
+    # VALUES, not behavior, and are still excluded — each decided, not
+    # overlooked:
+    #
+    #   `optional`  — required-ness is enforced at dispatch; stored rows
+    #                 are never re-validated on read, so flipping it
+    #                 strands nothing already written. Excluded.
+    #   `pattern`   — same argument: a fact about what may be WRITTEN
+    #                 next, not about what was stored. Excluded.
+    #   `admits`    — the sharpest of the three: narrowing a closed set
+    #                 CAN strand stored rows outside it, and the wire
+    #                 carries only the set's NAME, so a set whose members
+    #                 changed under a stable name is invisible even to a
+    #                 projection that included the fact (the same lesson
+    #                 recursive value-object drift taught). Excluded, and
+    #                 NAMED as a gap: constraint tightening has no
+    #                 translation-rule vocabulary to acknowledge it yet,
+    #                 so including it would mint era bumps nothing can
+    #                 explain. When the translation language grows a
+    #                 constraint-acknowledgment rule, `admits` (by member
+    #                 list, not by name) is first in line, and that
+    #                 change bumps FORM_VERSION.
+    #
+    # Projection runs over the canonical dump form (`to_h`, JSON
+    # round-tripped), so a verdict depends only on the IR — never on live
+    # object graphs. Structural comparison only, never a hash comparison.
+    module StorageShape
+      module_function
+
+      def project(bluebook)
+        domain = JSON.parse(JSON.generate(bluebook.to_h))
+        {
+          "name"       => bluebook.name,
+          "aggregates" => (domain["aggregates"] || [])
+                          .map { |aggregate| project_aggregate(aggregate) }
+                          .sort_by { |aggregate| aggregate["name"] }
+        }
+      end
+
+      def same?(held, current) = project(held) == project(current)
+
+      # The canonical serialization the Ruby scaffold hashes at MINT time
+      # — the one moment identity is computed. Nothing ever recomputes a
+      # stored era name to verify it, so this form can evolve freely.
+      def canonical(bluebook) = JSON.generate(project(bluebook))
+
+      def mint_hash(bluebook) = Digest::SHA256.hexdigest(canonical(bluebook))
+
+      LABEL_LENGTH = 6
+      def mint_label(bluebook) = mint_hash(bluebook)[0, LABEL_LENGTH]
+
+      # The version of the canonical serialization above. Minted-once
+      # means a stored name stays valid across form changes — but only
+      # if each name records WHICH form minted it, so v1-named and
+      # v2-named eras coexist legibly. Stored beside every minted hash
+      # (names.tsv fourth field / hecks_eras.canon_form); bump this in
+      # the same change that alters project/canonical output.
+      FORM_VERSION = 1
+
+      def project_aggregate(aggregate)
+        {
+          "name"            => aggregate["name"],
+          # The declared identity paths, AS A LIST, in declaration order —
+          # order is semantic (the paths join in order to form the id).
+          # No "id" fallback: an aggregate that declares nothing has [],
+          # and that is a real declared state, distinct from an aggregate
+          # identified by a field named "id".
+          "identity"        => Array(aggregate["identified_by"]).map(&:to_s),
+          "lifecycle_field" => aggregate.dig("lifecycle", "field"),
+          "attributes"      => (aggregate["attributes"] || [])
+                               .map { |attribute| project_attribute(aggregate, attribute, []) }
+                               .sort_by { |attribute| attribute["name"] }
+        }
+      end
+
+      def project_attribute(aggregate, attribute, seen)
+        {
+          "name" => attribute["name"].to_s,
+          "list" => attribute["list"] ? true : false,
+          "type" => type_signature(aggregate, attribute["type"].to_s, seen)
+        }
+      end
+
+      # A plain type name for a primitive; the type name plus its
+      # members' full signatures for a value object or entity — so two
+      # attributes with the same declared type name but different
+      # internals are never mistaken for unchanged.
+      def type_signature(aggregate, type_name, seen)
+        container = nested_type(aggregate, type_name)
+        return type_name if container.nil? || seen.include?(type_name)
+
+        {
+          "type"    => type_name,
+          "members" => (container["attributes"] || [])
+                       .map { |member| project_attribute(aggregate, member, seen + [type_name]) }
+                       .sort_by { |member| member["name"] }
+        }
+      end
+
+      def nested_type(aggregate, type_name)
+        (aggregate["value_objects"] || []).find { |vo| vo["name"] == type_name } ||
+          (aggregate["entities"] || []).find { |entity| entity["name"] == type_name }
+      end
+    end
+  end
+end

data/lib/hecks/runtime/tenant_check.rb

@@ -0,0 +1,84 @@
+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.
+    #
+    # 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
+    # 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.
+    #
+    # So `tenant_capable?` asks a narrower question than it might sound:
+    # 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 lifeadelics D1 tradeoff) answer false, or don't answer at all,
+    # which this module treats identically to false.
+    module TenantCheck
+      module_function
+
+      # 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.
+      def refuse_unless_tenant_capable!(registry, domain)
+        bluebook = registry.bluebook(domain)
+        return unless bluebook
+
+        offender = bluebook.aggregates.find do |aggregate|
+          adapter_name = Ports::Persistence::BindingPolicy.resolve(registry, domain, aggregate).adapter
+          !tenant_capable?(registry, adapter_name)
+        end
+        return unless offender
+
+        adapter_name = Ports::Persistence::BindingPolicy.resolve(registry, domain, offender).adapter
+        raise WiringError,
+              "#{domain}::#{offender.hecks_name} is bound to #{adapter_name}, which is not " \
+              "tenant_capable? — booting #{domain} for more than one tenant would share " \
+              "#{adapter_name}'s own storage across tenants that must never see each other's data. " \
+              "Bind a tenant-capable adapter (Memory, PostgresEra with its own schema: per tenant), " \
+              "or keep #{domain} single-tenant."
+      end
+
+      # 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.
+      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?
+      rescue StandardError
+        false
+      end
+    end
+  end
+end

data/lib/hecks/runtime/tenant_scope.rb

@@ -0,0 +1,55 @@
+require "delegate"
+require_relative "errors"
+require_relative "refusal_wording"
+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.
+    module TenantScope
+      module_function
+
+      def apply(declared, args)
+        tenant = declared.authorization&.tenant
+        return declared unless tenant
+
+        tenant = tenant.to_sym
+        unless args.key?(tenant)
+          raise Unauthorized, RefusalWording.render("Unauthorized", "tenant_required",
+                                                    query: declared.name, field: tenant)
+        end
+
+        Scoped.new(declared, QuerySpecification::Common::WhereClause.new(field: tenant, op: "eq", value: tenant))
+      end
+
+      class Scoped < SimpleDelegator
+        def initialize(declared, clause)
+          super(declared)
+          @clause = clause
+        end
+
+        def wheres = __getobj__.wheres + [@clause]
+      end
+    end
+  end
+end

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

@@ -0,0 +1,112 @@
+require_relative "invariant_violation"
+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.
+      module Admission
+        def admit_member(value_object, fields)
+          return if value_object.members.empty?
+
+          discriminant = value_object.attributes.first.name
+          offered      = fields[discriminant]
+          admitted     = value_object.members.map { |member| member[discriminant].to_s }
+          return if admitted.include?(offered.to_s)
+
+          raise InvariantViolation,
+                RefusalWording.render("InvariantViolation", "closed_set_member",
+                                      type: value_object.hecks_name,
+                                      admitted: admitted.map(&:inspect).join(", "), offered: offered.inspect)
+        end
+
+        # 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
+        # `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.
+        def admit_declared_set(owner, attribute, value)
+          return value if attribute.nil? || attribute.admits.nil? || value.nil?
+
+          admitted = admitted_members(owner, attribute)
+          offered  = admitted_scalar(value)
+          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)
+        end
+
+        # `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.
+        def admitted_members(owner, attribute)
+          aggregate_name, set_name = attribute.admits.to_s.split("::", 2)
+          chapter = chapter_of(owner)
+          set     = set_name && chapter&.aggregate(aggregate_name)&.value_object(set_name)
+
+          unless set
+            raise InvariantViolation,
+                  RefusalWording.render("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
+        # 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.
+        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
+        # plain field, or wrapped in the one-field holder its type names.
+        def admitted_scalar(value)
+          return value unless value.is_a?(self)
+
+          fields = value.to_h
+          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.
+        private def check_admitted(value_object, fields)
+          value_object.attributes.each do |attribute|
+            next unless attribute.admits
+
+            admit_declared_set(value_object, attribute, fields[attribute.name])
+          end
+        end
+      end
+    end
+  end
+end