hecks 2.9.0 → 3.0.0

data/lib/hecks/bluebook/dsl/world_builder.rb

@@ -101,15 +101,42 @@ module Hecks
           )
         end
 
+        class << self
+          # The builder whose block is being evaluated, so an aggregate door a facade already
+          # installed (a repeat boot in one process) can record a qualified bind into it.
+          #
+          # @return [Bluebook::DSL::WorldBuilder, nil] nil outside a `.world` block
+          attr_reader :current
+        end
+
         # Wraps `instance_eval` in `ConstShim`'s resolver: without it, an aggregate-qualified
         # verb call raises `NameError`, since the bare constant has nothing to resolve to.
+        # A bare name resolves to a namespace whose `::` reaches the proxy; a qualified path
+        # (`Pizzas::Order`, handed over by an installed facade chapter's `const_missing`)
+        # is already the aggregate, so it resolves to the proxy itself.
+        #
+        # @param domain [String] the domain the world belongs to
+        # @yield the world's DSL block
+        # @return [Bluebook::World] the judged world
         def self.build(domain, &block)
           builder  = new(domain)
-          resolver = ->(_domain) { WorldConstProxy.namespace(builder) }
-          ConstShim.with(resolver) { builder.instance_eval(&block) } if block
+          resolver = lambda do |name|
+            name.to_s.include?("::") ? WorldConstProxy.new(builder) : WorldConstProxy.namespace(builder)
+          end
+          evaluate(builder, resolver, &block) if block
           builder.build
         end
 
+        # @api private
+        def self.evaluate(builder, resolver, &block)
+          previous = @current
+          @current = builder
+          ConstShim.with(resolver) { builder.instance_eval(&block) }
+        ensure
+          @current = previous
+        end
+        private_class_method :evaluate
+
         private
 
         def required(value, _label)

data/lib/hecks/bluebook/expression/canonical_form.rb

@@ -11,7 +11,7 @@ module Hecks
 
         STRATEGIES = Hecks::Vocabulary.fetch("NormalisationStrategy")
 
-        # Normalisation rules projected from the grammar chapter by bin/expression_projection.
+        # Normalisation rules projected from the grammar chapter by hecks project_expression_tables.
         RULES = JSON.parse(
           File.read(File.join(__dir__, "projection.json")), symbolize_names: true
         ).fetch(:normalisations).map { |row| Rule.new(**row) }.freeze

data/lib/hecks/bluebook/expression/resolver.rb

@@ -201,8 +201,9 @@ module Hecks
         def blank?(value)
           return true if value.nil? || value == false
 
-          # Duck-typed: reaching across to Runtime::Value would couple the namespaces.
-          value = value.to_h if value.respond_to?(:to_h) && !value.is_a?(Hash)
+          # Duck-typed: reaching across to Runtime::Value would couple the namespaces. A list
+          # is judged by its own emptiness, never coerced: `[0].to_h` would raise TypeError.
+          value = value.to_h if value.respond_to?(:to_h) && !value.is_a?(Hash) && !value.is_a?(Array)
           case value
           when String, Array, Hash then value.empty?
           else false

data/lib/hecks/bluebook/hexagon.rb

@@ -32,32 +32,34 @@ module Hecks
         subscriptions:      -> { subscriptions.map(&:to_s) },
         framework_members:  -> { framework_members.map(&:to_s) },
         vendored_bluebooks: -> { vendored_bluebooks.map(&:to_s) },
-        bounded:            :bounded,
+        attached_chapters:  -> { attached_chapters.map(&:to_s) },
+        bounded:            :bounded?,
         translates:         -> { translates.map(&:to_s) }
       )
 
       attr_reader :domain, :binds, :subscriptions, :framework_members, :vendored_bluebooks,
-                  :translates
+                  :attached_chapters, :translates
 
       # @param domain [String, Symbol] the domain this hecksagon wires
       # @param binds [Array<Bluebook::Bind>] the declared adapter binds
       # @param subscriptions [Array<String, Symbol>] the external events this domain
       #   subscribes to
-      # @param framework_members [Array<String, Symbol>] the framework members
-      #   (`Governance`, `Identity`, ...) this domain attaches
+      # @param framework_members [Array<String, Symbol>] attached framework members (`Governance`)
       # @param vendored_bluebooks [Array<String, Symbol>] the vendored embryonaut
       #   bluebook package names this domain attaches
+      # @param attached_chapters [Array<String, Symbol>] chapters the gem carries, attached by name
       # @param bounded [Boolean] whether this chapter is an explicit bounded context
       #   (consumer-owned; `uses_framework` / `uses_embryonaut_bluebook` mark
       #   attached chapters bounded on the registry instead)
       # @param translates [Array<String>] names of `translates` ACL blocks declared here
       def initialize(domain:, binds: [], subscriptions: [], framework_members: [],
-                     vendored_bluebooks: [], bounded: false, translates: [])
+                     vendored_bluebooks: [], attached_chapters: [], bounded: false, translates: [])
         @domain             = domain.to_s
         @binds              = binds
         @subscriptions      = subscriptions
         @framework_members  = framework_members
         @vendored_bluebooks = vendored_bluebooks
+        @attached_chapters  = attached_chapters
         @bounded            = bounded ? true : false
         @translates         = Array(translates).map(&:to_s)
       end
@@ -66,6 +68,12 @@ module Hecks
       #
       # @return [Boolean] whether `bounded` was declared on this block
       def bounded? = @bounded
+
+      # Every chapter this hecksagon brings into its domain's registry: framework members and
+      # attached chapters alike, which resolve the same way.
+      #
+      # @return [Array<String>] the chapters' names, framework members first
+      def member_chapters = (framework_members + attached_chapters).map(&:to_s)
     end
 
     # The built form of a `.world` file, produced by `DSL::WorldBuilder`.

data/lib/hecks/bluebook/meta_validator/reconstruction.rb

@@ -24,6 +24,7 @@ module Hecks
             vision:            text(@chapter[:vision]),
             classification:    text(@chapter[:classification]),
             formerly_known_as: text(@chapter[:formerly_known_as]),
+            namespace:         text(@chapter[:namespace]),
             attaches_to:       attached_contexts(@chapter),
             provides:          provisions(@chapter),
             aggregates:        declared("Aggregate", chapter_id).map { |row| aggregate(row) },

data/lib/hecks/bluebook/meta_validator/syntax_boot.rb

@@ -85,9 +85,12 @@ module Hecks
 
         def disk_cache_key(chapters)
           names = chapters.map { |name, _chapter| name }
-          Digest::SHA256.hexdigest("#{names.join(',')}:#{grammar_content_digest}")
+          Digest::SHA256.hexdigest("#{names.join(',')}:#{grammar_content_digest}:#{VerdictCache.code_digest}")
         end
 
+        # The key also carries `VerdictCache.code_digest` (all of `lib/`), so an
+        # edit to Ruby that builds or judges the grammar misses too.
+        #
         # Covers every chapter's grammar files, not just the core ones —
         # coarser than strictly necessary, but under-covering this set would
         # let a stale table survive a real grammar edit.

data/lib/hecks/bluebook/meta_validator/verdict_cache.rb

@@ -0,0 +1,246 @@
+require "digest"
+require "fileutils"
+require "json"
+require_relative "../../cache_dir"
+require_relative "../../version"
+
+module Hecks
+  module Bluebook
+    module MetaValidator
+      # Cross-process store of the meta-domain's chapter verdicts, so a boot
+      # judges only the chapters no earlier process has judged.
+      #
+      # Only chapter verdicts live here; `Assembly.call` still runs every boot
+      # and a miss judges as a cold process does. The file name carries a digest
+      # of the judging code (every file under `lib/`, the Ruby and Hecks
+      # versions, `FORMAT`); each entry is keyed by the chapter IR's SHA-256.
+      # The file is tagged JSON, never `Marshal`, read only from a private,
+      # user-owned directory: a forged "no refusals" entry would skip validation.
+      #
+      #   VerdictCache.record(key, held)
+      #   VerdictCache.flush  # also runs at process exit
+      module VerdictCache
+        module_function
+
+        # Bumped when the encoding or the entry shape changes.
+        FORMAT = 1
+
+        # Files older than this that do not match the current code digest are
+        # pruned on write.
+        STALE_AFTER = 60 * 60
+
+        # Whether the disk cache is on; `HECKS_VERDICT_CACHE=off` disables it.
+        #
+        # @return [Boolean]
+        def enabled? = ENV["HECKS_VERDICT_CACHE"] != "off"
+
+        # The directory the verdict files live in.
+        #
+        # @return [String] an absolute path under `Hecks::CacheDir`
+        def dir = Hecks::CacheDir.path("hecks_verdict_cache")
+
+        # The file the current code's verdicts live in.
+        #
+        # @return [String] an absolute path
+        def path = File.join(dir, "verdicts-#{code_digest}.json")
+
+        # A digest of everything that decides a verdict: each file under
+        # `lib/` (path and bytes), the Ruby and Hecks versions and `FORMAT`.
+        # Computed once per process, at first use, which is when the judging
+        # code was loaded.
+        #
+        # @return [String] a hex SHA-256
+        def code_digest = @code_digest ||= digest_of(File.expand_path("../../..", __dir__))
+
+        # The digest `code_digest` reports, for any tree.
+        #
+        # @param lib [String] the directory whose files decide a verdict
+        # @return [String] a hex SHA-256 over `FORMAT`, the versions and every
+        #   file's relative path and bytes, in sorted order
+        def digest_of(lib)
+          state = Digest::SHA256.new
+          state << "#{FORMAT}\0#{RUBY_VERSION}\0#{Hecks::VERSION}\0"
+          Dir.glob(File.join(lib, "**", "*"), File::FNM_DOTMATCH).sort.each do |file|
+            next unless File.file?(file)
+
+            state << file.delete_prefix(lib) << "\0" << File.binread(file) << "\0"
+          end
+          state.hexdigest
+        end
+
+        # Loads the stored verdicts, once per process; later calls return an
+        # empty hash so a caller that resets its own memo re-judges for real.
+        #
+        # @return [Hash{String => Hash}] verdicts by chapter key; empty when
+        #   the cache is off, absent, unreadable, corrupt or not private
+        def seed
+          return {} if @seeded
+
+          @seeded = true
+          return {} unless enabled?
+
+          loaded = read
+          entries.merge!(loaded)
+          loaded.dup
+        rescue StandardError
+          {}
+        end
+
+        # Remembers a freshly judged chapter verdict for the next `flush`.
+        #
+        # @param key [String] the chapter's SHA-256 key
+        # @param held [Hash] the verdict `MetaValidator.hold` returned
+        # @return [void]
+        def record(key, held)
+          return unless enabled?
+
+          entries[key] = held
+          @dirty = true
+          register_exit_flush
+        end
+
+        # Writes every known verdict when any was added since the last write.
+        # Failure of any kind leaves the cache as it was.
+        #
+        # @return [void]
+        def flush
+          return unless @dirty && enabled?
+
+          @dirty = false
+          encoded = encode(entries)
+          return unless decode(encoded) == entries
+
+          write(JSON.generate({ "format" => FORMAT, "entries" => encoded }, max_nesting: false))
+          prune
+        rescue StandardError
+          nil
+        end
+
+        # Forgets the process's own bookkeeping (not the files).
+        #
+        # @return [void]
+        def reset!
+          @seeded = false
+          @dirty = false
+          @entries = nil
+          @code_digest = nil
+        end
+
+        # @return [Hash{String => Hash}] every verdict this process knows
+        def entries = @entries ||= {}
+
+        # Reads and decodes the current code's file.
+        #
+        # @return [Hash{String => Hash}] entries, or `{}` on any problem
+        def read
+          file = path
+          return {} unless File.file?(file) && trusted?(file)
+
+          doc = JSON.parse(File.binread(file), max_nesting: false)
+          return {} unless doc.is_a?(Hash) && doc["format"] == FORMAT
+
+          decoded = decode(doc["entries"])
+          well_formed?(decoded) ? decoded : {}
+        rescue StandardError
+          {}
+        end
+
+        # Whether `file` and its directory belong to this user and nobody else
+        # can write them.
+        #
+        # @param file [String] a path
+        # @return [Boolean]
+        def trusted?(file)
+          [File.stat(file), File.stat(File.dirname(file))].all? do |stat|
+            stat.owned? && stat.mode.nobits?(0o022)
+          end
+        end
+
+        # @param entries [Object] a decoded `entries` value
+        # @return [Boolean] whether it is a hash of chapter verdicts
+        def well_formed?(entries)
+          entries.is_a?(Hash) && entries.all? do |key, held|
+            key.is_a?(String) && held.is_a?(Hash) && held[:refusals].is_a?(Array) &&
+              (held[:refusals].any? || held[:declaration].is_a?(Hash))
+          end
+        end
+
+        # Writes through a PID-suffixed temp file and an atomic rename, so a
+        # concurrent reader never sees a torn file.
+        #
+        # @param text [String] the file body
+        # @return [void]
+        def write(text)
+          file = path
+          FileUtils.mkdir_p(File.dirname(file), mode: 0o700)
+          tmp = "#{file}.#{Process.pid}.tmp"
+          File.binwrite(tmp, text)
+          File.chmod(0o600, tmp)
+          File.rename(tmp, file)
+        end
+
+        # Removes verdict files for other code digests once they are stale.
+        #
+        # @return [void]
+        def prune
+          keep = File.basename(path)
+          Dir.glob(File.join(dir, "verdicts-*")).each do |file|
+            next if File.basename(file) == keep || Time.now - File.mtime(file) < STALE_AFTER
+
+            File.delete(file)
+          rescue StandardError
+            next
+          end
+        end
+
+        # Encodes plain data as JSON-safe data, tagging what JSON would lose:
+        # a symbol is `{"$s" => name}`, a hash is `{"$h" => [[key, value], ...]}`
+        # (pair order is hash order).
+        #
+        # @param obj [Object] Hash, Array, String, Symbol, Integer, nil, true or false
+        # @return [Object] the tagged form
+        # @raise [ArgumentError] for any other class
+        def encode(obj)
+          case obj
+          when Symbol then { "$s" => obj.to_s }
+          when Hash then { "$h" => obj.map { |key, value| [encode(key), encode(value)] } }
+          when Array then obj.map { |item| encode(item) }
+          when String
+            plain = obj.valid_encoding? && (obj.ascii_only? || obj.encoding == Encoding::UTF_8)
+            raise ArgumentError, "unencodable string" unless plain
+
+            obj
+          when Integer, nil, true, false then obj
+          else raise ArgumentError, "unencodable #{obj.class}"
+          end
+        end
+
+        # The inverse of `encode`.
+        #
+        # @param obj [Object] the tagged form
+        # @return [Object] the original data
+        def decode(obj)
+          case obj
+          when Array then obj.map { |item| decode(item) }
+          when Hash
+            if obj.size == 1 && obj.key?("$s") then obj["$s"].to_sym
+            elsif obj.size == 1 && obj.key?("$h") then obj["$h"].to_h { |key, value| [decode(key), decode(value)] }
+            else raise ArgumentError, "untagged hash"
+            end
+          else obj
+          end
+        end
+
+        # Registers the exit hook once per process.
+        #
+        # @return [void]
+        def register_exit_flush
+          return if @exit_registered
+
+          @exit_registered = true
+          at_exit { flush }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/meta_validator.rb

@@ -1,5 +1,6 @@
 require "digest"
 require "json"
+require_relative "meta_validator/verdict_cache"
 
 module Hecks
   module Bluebook
@@ -150,9 +151,13 @@ module Hecks
       # Process-wide judging cache, keyed on a SHA-256 digest of the judged
       # artifact so a changed bluebook is always re-judged.
       #
-      # @return [Hash{String => Array<String>}] refusal messages per digest
-      #   (`[]` when well formed)
-      def self.verdicts = @verdicts ||= {}
+      # Seeded once per process with the chapter verdicts earlier processes
+      # stored (see `VerdictCache`); every other verdict starts empty.
+      #
+      # @return [Hash{String => Object}] refusal messages per digest for a
+      #   world/port/adapter/translation (`[]` when well formed); the held
+      #   verdict Hash for a chapter
+      def self.verdicts = @verdicts ||= VerdictCache.seed
 
       # Judges `world` through the meta-domain's own `WorldJudge` door.
       #
@@ -248,7 +253,7 @@ module Hecks
         end
 
         key = Digest::SHA256.hexdigest(JSON.generate(bluebook.to_h))
-        held = verdicts[key] ||= hold(bluebook)
+        held = verdicts[key] || (verdicts[key] = hold(bluebook).tap { |fresh| VerdictCache.record(key, fresh) })
 
         unless held[:refusals].empty?
           raise DSL::Malformed,

data/lib/hecks/bluebook/model_check.rb

@@ -51,10 +51,33 @@ module Hecks
         findings.concat(rust_reserved_name_findings(domain_name: bluebook.name,
                                                     aggregate_names: bluebook.aggregates.map(&:hecks_name),
                                                     rust_target: rust_target, strict: strict))
+        findings.concat(external_query_findings(bluebook, rust_target: rust_target))
         findings.concat(ClientProfile.call(bluebook, hecksagon: hecksagon)) if profile == :client
         findings
       end
 
+      # Flags a query the hecksagon binds to a port's adapter. Only the Ruby runtime asks an
+      # adapter for an answer; a Rust host would find nothing behind the query.
+      #
+      # @param bluebook [Bluebook::Chapter] the assembled chapter, its hecksagon's ports attached
+      # @param rust_target [Boolean] whether this domain has a real Rust target; a domain without
+      #   one is not checked, since nothing but the Ruby runtime serves it
+      # @return [Array<Finding>] one :external_query error per bound query, none off a Rust target
+      def external_query_findings(bluebook, rust_target: false)
+        return [] unless rust_target
+
+        bluebook.aggregates.flat_map do |aggregate|
+          aggregate.ports.flat_map do |port|
+            port.answered_queries.map do |answer|
+              Finding.new(kind: :external_query, severity: :error,
+                          subject: "#{aggregate.hecks_name}.#{answer.name}",
+                          message: "the #{port.name} port's adapter answers this query, and only the Ruby " \
+                                   "runtime asks an adapter — the Rust host cannot serve it")
+            end
+          end
+        end
+      end
+
       # Flags an aggregate or domain name that collides with a Rust keyword or reserved
       # Cargo key — both become bare module identifiers with no `r#` escape hatch.
       #

data/lib/hecks/bluebook/pattern_subset.rb

@@ -101,6 +101,44 @@ module Hecks
         nil
       end
 
+      # Rewrites the line anchors of a declared pattern into whole-string anchors.
+      #
+      # Ruby reads `^` and `$` as line anchors, so `"ok\n../evil"` satisfies `^[a-z]+$`; Rust's
+      # `regex` reads them as text anchors. Enforcement matches the rewritten source so both
+      # engines refuse the same values. Escaped characters and bracket classes are left alone.
+      #
+      # @param pattern [String, Symbol, #to_s] the declared `pattern:` regex source
+      # @return [String] the source with `^` as `\A` and `$` as `\z` outside classes
+      def whole_string(pattern)
+        chars = pattern.to_s.chars
+        in_class = false
+        class_start = nil
+        out = +""
+        index = 0
+        while index < chars.length
+          char = chars[index]
+          if char == "\\"
+            out << char << chars[index + 1].to_s
+            index += 2
+            next
+          end
+          if in_class
+            in_class = false if char == "]" && index != class_start
+          elsif char == "["
+            in_class = true
+            class_start = index + 1
+            class_start += 1 if chars[class_start] == "^"
+          elsif char == "^"
+            char = "\\A"
+          elsif char == "$"
+            char = "\\z"
+          end
+          out << char
+          index += 1
+        end
+        out
+      end
+
       # Spelled out, not derived from the key: callers read these strings in refusals.
       CONSTRUCTS = {
         backreference:       "backreference",

data/lib/hecks/bluebook/query.rb

@@ -25,14 +25,14 @@ module Hecks
         limit:       one(:limit)
       )
 
-      attr_reader :name, :description, :attributes
+      attr_reader :name, :description, :attributes, :returns
 
       # @param null_semantics [QuerySpecification::Common::NullSemantics, nil] defaults to
       #   `NullSemantics.default`
       def initialize(name:, description: nil, attributes: [], wheres: [],
                      order_by: nil, limit: nil, offset: nil, cursor: nil,
                      authorization: nil, null_semantics: nil,
-                     inspection: nil)
+                     inspection: nil, returns: nil)
         null_semantics ||= QuerySpecification::Common::NullSemantics.default
         super(wheres: wheres, order_by: order_by, limit: limit, offset: offset, cursor: cursor,
               authorization: authorization,
@@ -41,13 +41,28 @@ module Hecks
         @hecks_name  = @name
         @description = description
         @attributes  = attributes
+        @returns     = returns&.to_s
       end
 
+      # The value object a `returns` names, without the `list_of(...)` wrapper.
+      #
+      # @return [String, nil] the value object's name, or `nil` when the query returns nothing
+      def returns_name = @returns&.sub(/\Alist_of\((.*)\)\z/, '\1')
+
+      # Says whether the answer is many rows of the returned value object.
+      #
+      # @return [Boolean] true for `returns list_of(Name)`
+      def returns_list? = !@returns.nil? && @returns.start_with?("list_of(")
+
       # `extra_options_to_h` (count, median, group_by, scope_to) stays dynamic; `super` covers the
-      # declared emission.
+      # declared emission. `returns` follows, only when the query declares one, so a query that
+      # returns nothing keeps its wire shape.
       #
-      # @return [Hash] the declared emission merged with `extra_options_to_h`
-      def to_h = super.merge(extra_options_to_h)
+      # @return [Hash] the declared emission merged with `extra_options_to_h`, then `returns`
+      def to_h
+        shape = super.merge(extra_options_to_h)
+        @returns ? shape.merge(returns: @returns) : shape
+      end
     end
   end
 end

data/lib/hecks/bluebook/smoke_test.rb

@@ -23,7 +23,7 @@ module Hecks
       def call(dir)
         Dir.mktmpdir("hecks-smoke-") do |scratch|
           isolate!(dir, scratch)
-          dispatcher = Hecks.boot(scratch, install_facade: false)
+          dispatcher = Hecks.boot(scratch, install_doors: false)
           domain     = dispatcher.registry.bluebooks.keys.first
           next [] unless domain
 

data/lib/hecks/canonical_json.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Hecks
+  # A JSON document with every object's keys sorted. Key order is not semantics, so a diff a person
+  # reads should not have to notice it moved.
+  module CanonicalJson
+    module_function
+
+    # Sorts every Hash's keys within a parsed JSON document, recursively.
+    #
+    # @param node [Object] a value from `JSON.parse`: a `Hash`, an `Array`, or a JSON scalar
+    # @return [Object] the same shape with every nested `Hash`'s keys sorted by their string form
+    def sort_deep(node)
+      case node
+      when Hash then node.sort_by { |key, _| key.to_s }.to_h { |key, value| [key, sort_deep(value)] }
+      when Array then node.map { |item| sort_deep(item) }
+      else node
+      end
+    end
+
+    # @param text [String] a JSON document
+    # @return [String] the document pretty-printed with its keys in order
+    # @raise [JSON::ParserError] if the text is not JSON
+    def pretty(text)
+      JSON.pretty_generate(sort_deep(JSON.parse(text)))
+    end
+  end
+end