hecks 2.9.0 → 3.0.0

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

@@ -0,0 +1,172 @@
+require_relative "../errors"
+require_relative "../refusal_wording"
+require_relative "../../rendering"
+
+module Hecks
+  module Runtime
+    class Value
+      # Boundary checks that refuse a mistyped, unknown, missing or malformed field before an
+      # invariant reads it; extended into `Value` alongside `Coercion`, which calls them.
+      module FieldChecks
+        # C3.8 boundary check — refuses a mistyped argument before it breaks a predicate.
+        private def check_bare_primitive(owner, attribute, value)
+          type = attribute.type.to_s
+          expected = NUMERIC[type]
+          mistyped = if expected
+                       !value.is_a?(expected)
+                     elsif NON_NUMERIC_SCALARS.include?(type)
+                       COMPOSITE_SHAPES.any? { |shape| value.is_a?(shape) }
+                     else
+                       false
+                     end
+          if mistyped
+            raise TypeMismatch,
+                  RefusalWording.render_site("TypeMismatch", "numeric_field",
+                                             type: owner.hecks_name, field: attribute.name,
+                                             expected: type, offered: Rendering.describe(value))
+          end
+
+          check_numeric_bounds(owner.hecks_name, attribute.name, value)
+        end
+
+        # C3.3/C3.4 — value bounds enforced at every boundary: an Integer must fit
+        # signed 64 bits, a Float must be finite.
+        INT64_RANGE = (-(2**63))..((2**63) - 1)
+
+        private def check_numeric_bounds(type_name, field_name, given)
+          if given.is_a?(Integer) && !INT64_RANGE.cover?(given)
+            raise TypeMismatch,
+                  RefusalWording.render_site("TypeMismatch", "integer_range",
+                                             type: type_name, field: field_name, offered: Rendering.describe(given))
+          end
+          return unless given.is_a?(Float) && !given.finite?
+
+          raise TypeMismatch,
+                RefusalWording.render_site("TypeMismatch", "non_finite_field",
+                                           type: type_name, field: field_name, offered: Rendering.describe(given))
+        end
+
+        # A value object refuses an undeclared key the same way a command's own
+        # payload does, checked before any other field-content check.
+        private def check_unknown_fields(value_object, fields)
+          known   = value_object.attributes.map { |attribute| attribute.name.to_sym }
+          unknown = (fields.keys.map(&:to_sym) - known).sort
+          return if unknown.empty?
+
+          declared = value_object.attributes.map(&:name)
+          raise UnknownArgument,
+                RefusalWording.render_site("UnknownArgument", "unknown_args",
+                                           command: value_object.hecks_name, unknown: unknown,
+                                           declared: declared)
+        end
+
+        # C3.7 — every non-optional, non-list field must arrive (or construction
+        # refuses); a `default:` has already been filled in by `apply_defaults`.
+        private def check_required_fields(value_object, fields)
+          value_object.attributes.each do |attribute|
+            next if attribute.optional? || attribute.list?
+            next unless fields[attribute.name].nil?
+
+            raise TypeMismatch,
+                  RefusalWording.render_site("TypeMismatch", "numeric_field",
+                                             type: value_object.hecks_name, field: attribute.name,
+                                             expected: attribute.type, offered: "nil")
+          end
+        end
+
+        # Checked before invariants, because an invariant reading a mistyped field
+        # is exactly the thing that would otherwise explode.
+        NUMERIC = { "Integer" => Integer, "Float" => Numeric }.freeze
+        private def check_numeric_fields(value_object, fields)
+          value_object.attributes.each do |attribute|
+            expected = NUMERIC[attribute.type.to_s]
+            next unless expected
+
+            given = fields[attribute.name]
+            next if given.nil?
+
+            offered_items(attribute, given).each do |item|
+              unless item.is_a?(expected)
+                raise TypeMismatch,
+                      RefusalWording.render_site("TypeMismatch", "numeric_field",
+                                                 type: value_object.hecks_name, field: attribute.name,
+                                                 expected: attribute.type, offered: Rendering.describe(item))
+              end
+
+              # `is_a?(expected)` alone waves NaN/Infinity through — both are real
+              # Floats. `-0.0` is deliberately left unchecked: finite and legitimate.
+              check_numeric_bounds(value_object.hecks_name, attribute.name, item)
+            end
+          end
+        end
+
+        # A `list_of` field holds an Array whatever its element type, so a lone scalar
+        # offered for it is refused; nil stays legitimate, as it is for any optional field.
+        private def check_list_shapes(value_object, fields)
+          value_object.attributes.each do |attribute|
+            given = fields[attribute.name]
+            next unless attribute.list? && !given.nil? && !given.is_a?(Array)
+
+            raise TypeMismatch, RefusalWording.render_site(
+              "TypeMismatch", "numeric_field", type: value_object.hecks_name, field: attribute.name,
+              expected: "list_of(#{attribute.type})", offered: Rendering.describe(given)
+            )
+          end
+        end
+
+        # The values a field's element-level checks apply to: each element of a list, or the
+        # one value of a scalar field.
+        private def offered_items(attribute, given) = attribute.list? && given.is_a?(Array) ? given : [given]
+
+        # A scalar field (String, or a boolean) must not arrive as a composite
+        # (Array/Hash) standing in for a leaf value. A String field additionally
+        # must not arrive as any other scalar, except inside `judge_bootstrapping?`.
+        COMPOSITE_SHAPES = [Array, ::Hash].freeze
+        NON_NUMERIC_SCALARS = %w[String TrueClass FalseClass].freeze
+        private def check_scalar_shapes(value_object, fields)
+          value_object.attributes.each do |attribute|
+            type = attribute.type.to_s
+            next unless NON_NUMERIC_SCALARS.include?(type)
+
+            given = fields[attribute.name]
+            next if given.nil?
+
+            offered_items(attribute, given).each do |item|
+              composite = COMPOSITE_SHAPES.any? { |shape| item.is_a?(shape) }
+              non_string_scalar = type == "String" && !composite && !item.is_a?(String) && !judge_bootstrapping?
+              next unless composite || non_string_scalar
+
+              raise TypeMismatch,
+                    RefusalWording.render_site("TypeMismatch", "numeric_field",
+                                               type: value_object.hecks_name, field: attribute.name,
+                                               expected: attribute.type, offered: Rendering.describe(item))
+            end
+          end
+        end
+
+        # A field declared with a pattern must match it, refused as a TypeMismatch
+        # rather than surfacing later as a broken predicate. The pattern itself is
+        # already vetted by PatternSubset when the bluebook is declared. `^` and `$` match the
+        # whole value, as in Rust, so a newline cannot smuggle text past an anchored pattern.
+        private def check_patterns(value_object, fields)
+          value_object.attributes.each do |attribute|
+            pattern = attribute.pattern
+            next unless pattern
+
+            given = fields[attribute.name]
+            next if given.nil?
+
+            offered_items(attribute, given).each do |item|
+              next if item.is_a?(String) && Regexp.new(Hecks::Bluebook::PatternSubset.whole_string(pattern)).match?(item)
+
+              raise TypeMismatch,
+                    RefusalWording.render_site("TypeMismatch", "pattern_mismatch",
+                                               type: value_object.hecks_name, field: attribute.name,
+                                               pattern: pattern, offered: Rendering.describe(item))
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/value.rb

@@ -1,6 +1,7 @@
 require "json"
 require_relative "../rendering"
 require_relative "value/invariant_violation"
+require_relative "value/field_checks"
 require_relative "value/coercion"
 require_relative "value/entity_list_coercion"
 require_relative "value/admission"
@@ -8,8 +9,10 @@ require_relative "value/admission"
 module Hecks
   module Runtime
     # A typed value object: frozen fields, read by name.
-    # Construction lives in value/coercion.rb, entity_list_coercion.rb and admission.rb.
+    # Construction lives in value/coercion.rb, field_checks.rb, entity_list_coercion.rb and
+    # admission.rb.
     class Value
+      extend FieldChecks
       extend Coercion
       extend EntityListCoercion
       extend Admission

data/lib/hecks/runtime.rb

@@ -42,24 +42,38 @@ module Hecks
       #
       # @param path [String] path to a domain directory, or a file inside one
       # @param shared [String, nil] a shared-root override
-      # @param install_facade [Boolean] whether to install the Ruby facade constants
+      # @param install_doors [Boolean] whether to install the Ruby facade constants
+      # @param install_facade [Boolean, nil] the deprecated spelling of `install_doors`; warns
       # @param environment [String, nil] the environment name for `Adapters::Folder#load_domain`
       # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the dispatcher bound
       #   to the booted domain
-      def boot(path, shared: nil, install_facade: true, environment: nil)
-        Loader.boot(path, shared: shared, install_facade: install_facade, environment: environment)
+      def boot(path, shared: nil, install_doors: true, install_facade: nil, environment: Runtime::Loader::FROM_ENV)
+        Loader.boot(path, shared: shared, install_doors: install_doors, environment: environment,
+          install_facade: install_facade)
+      end
+
+      # Loads a domain's declarations without binding any adapter. See Loader.describe.
+      #
+      # @param path [String] path to a domain directory, or a file inside one
+      # @param shared [String, nil] a shared-root override
+      # @param environment [String, nil] the environment overlay; defaults to `HECKS_ENVIRONMENT`
+      # @return [Runtime::Loader::Described] the loaded registry, answering `registry`
+      def describe(path, shared: nil, environment: Runtime::Loader::FROM_ENV)
+        Loader.describe(path, shared: shared, environment: environment)
       end
 
       # Loads only the given files of a domain; otherwise like `boot`. See Loader.boot_files.
       #
       # @param paths [String, Array<String>] one or more file paths within the domain
       # @param shared [String, nil] a shared-root override
-      # @param install_facade [Boolean] whether to install the Ruby facade constants
+      # @param install_doors [Boolean] whether to install the Ruby facade constants
+      # @param install_facade [Boolean, nil] the deprecated spelling of `install_doors`; warns
       # @param environment [String, nil] the environment name for the selected-file loader
       # @return [Runtime::Dispatcher, Runtime::RemoteDispatcher] the dispatcher bound
       #   to the booted domain
-      def boot_files(paths, shared: nil, install_facade: true, environment: nil)
-        Loader.boot_files(paths, shared: shared, install_facade: install_facade, environment: environment)
+      def boot_files(paths, shared: nil, install_doors: true, install_facade: nil, environment: Runtime::Loader::FROM_ENV)
+        Loader.boot_files(paths, shared: shared, install_doors: install_doors, environment: environment,
+          install_facade: install_facade)
       end
 
       # Bind the ambient registry for the duration of the block, restoring

data/lib/hecks/rust_build/conformance.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require_relative "../rust_build"
+require_relative "native_build"
+
+module Hecks
+  module RustBuild
+    # The differential harness (ADR 0010): replays a corpus script through the Ruby interpreter
+    # (`Fuzzing::Replay`) and prints or diffs the JSON surface a Rust artifact must reproduce.
+    #
+    # With no artifact it prints Ruby's result as JSON, which saved to a file becomes a pinned
+    # expectation. The artifact is another artifact's JSON file, `native` (the workspace's
+    # `target/{release,debug}/rust`), a `.wasm` path (run under `wasmtime`), an executable path,
+    # or `build` (the domain's own Cargo feature, built and run); a live one gets the script on
+    # stdin. `HECKS_RUST_DIR` names the workspace and `CARGO_TARGET_DIR` where its output went.
+    module Conformance
+      USAGE = "usage: hecks check_conformance <domain> <script.json> " \
+              "[rust_output.json | native | build | path/to/binary | path/to/module.wasm]"
+
+      # The refusal kinds are not compared for ad-hoc filter steps: C8.3
+      # (docs/semantics/bluebook-semantics.md) is open (RuntimeError in Ruby, TypeMismatch in
+      # Rust), and only the message is byte-exact.
+      FILTER_VERB = "filter "
+
+      module_function
+
+      # @param argv [Array<String>] the domain, the script and optionally the artifact
+      # @return [Integer] 0 when the result is printed or matches, 1 on a mismatch
+      # @raise [Failure] when the artifact cannot be run
+      def call(argv)
+        require_relative "../../hecks"
+        require_relative "../fuzzing"
+        domain, script, other = argv
+        raise Failure, USAGE unless domain && script
+
+        ours = comparable(Hecks::Fuzzing::Replay.call(domain, JSON.parse(File.read(script)).fetch("steps")))
+        return print_result(ours) unless other
+
+        theirs = normalize(JSON.parse(artifact_output(domain, script, other)))
+        report(domain, script, ours, theirs)
+      end
+
+      def print_result(result)
+        puts JSON.pretty_generate(result)
+        0
+      end
+
+      # @param result [Hash] `Fuzzing::Replay`'s answer
+      # @return [Hash{String => Object}] the surface a Rust artifact must reproduce
+      def comparable(result)
+        surface = {
+          "instances" => result[:instances].transform_values { |state| JSON.parse(JSON.generate(state)) },
+          "events"    => result[:events].map { |event| event_surface(event) },
+          "refusals"  => result[:refusals].map do |refusal|
+            { "verb" => refusal[:verb], "error" => refusal[:error], "kind" => refusal[:kind]&.split("::")&.last }
+          end
+        }
+        # `verb` and `ok` only, as `Hecks::Fuzzing::Differential` compares; omitted when none.
+        dry_runs = result[:dry_runs].map { |dry| { "verb" => dry[:verb].to_s, "ok" => dry[:ok] } }
+        surface["dry_runs"] = dry_runs unless dry_runs.empty?
+        surface
+      end
+
+      def event_surface(event)
+        { "name" => event[:name], "aggregate" => event[:aggregate], "id" => event[:id].to_s,
+          "payload" => JSON.parse(JSON.generate(event[:payload])) }
+      end
+
+      # The artifact's JSON for the script: live from a binary, or read from a file.
+      def artifact_output(domain, script, other)
+        case other
+        when "native" then run_binary(native_binary || missing_native!, script)
+        when "build" then run_binary(built_binary(domain), script)
+        when /\.wasm\z/
+          raise Failure, "#{other}: no such file — run hecks build_wasm #{domain} first" unless File.exist?(other)
+
+          run_process(["wasmtime", "run", other], File.read(script))
+        when ->(path) { !path.end_with?(".json") && File.file?(path) && File.executable?(path) }
+          # A pinned per-domain binary, as named by a sweep's `replay:` line.
+          run_binary(other, script)
+        else File.read(other)
+        end
+      end
+
+      def run_binary(binary, script) = run_process([binary], File.read(script))
+
+      def run_process(command, stdin_data)
+        stdout, status = Open3.capture2(*command, stdin_data: stdin_data)
+        raise Failure, "#{command.join(' ')} exited #{status.exitstatus}:\n#{stdout}" unless status.success?
+
+        stdout
+      end
+
+      def target_dir = ENV.fetch("CARGO_TARGET_DIR", File.join(RustBuild.rust_dir, "target"))
+
+      def native_binary
+        %w[release debug].map { |profile| File.join(target_dir, profile, "rust") }.find { |path| File.executable?(path) }
+      end
+
+      def missing_native!
+        raise Failure, "no native rust binary found under rust/target/{release,debug}/rust — run " \
+                       "`cd rust && cargo build` first"
+      end
+
+      # Built on demand because `native` runs whichever domain the crate's default feature names.
+      def built_binary(domain)
+        feature = File.basename(domain.chomp("/"))
+        NativeBuild.build_rust_for(feature, RustBuild.rust_dir) or
+          raise Failure, "no `#{feature}` feature in rust/Cargo.toml — run hecks project_rust #{domain} first"
+      end
+
+      # Strips what a Rust run carries that Ruby has no analog for: `emitted_*` snapshot flags
+      # (ADR 0048) and the wall-clock `occurred_at` stamp two runs can never match.
+      def normalize(theirs)
+        if theirs["instances"].is_a?(Hash)
+          theirs["instances"].each_value do |record|
+            record.reject! { |key, _| key.start_with?("emitted_") } if record.is_a?(Hash)
+          end
+        end
+        theirs["events"].each { |event| event.delete("occurred_at") if event.is_a?(Hash) } if theirs["events"].is_a?(Array)
+        theirs
+      end
+
+      def report(domain, script, ours, theirs)
+        [ours, theirs].each { |side| drop_filter_kinds(side) }
+        mismatches = mismatches(ours, theirs)
+        if mismatches.empty?
+          puts "#{domain} / #{script}: matches."
+          return 0
+        end
+
+        warn "#{domain} / #{script}: #{mismatches.size} mismatch(es)\n\n#{mismatches.join("\n\n")}"
+        1
+      end
+
+      def drop_filter_kinds(side)
+        return unless side["refusals"].is_a?(Array)
+
+        side["refusals"].each { |r| r.delete("kind") if r.is_a?(Hash) && r["verb"].to_s.start_with?(FILTER_VERB) }
+      end
+
+      def mismatches(ours, theirs)
+        found = %w[instances events refusals].filter_map do |key|
+          next if ours[key] == theirs[key]
+
+          "#{key}:\n  ruby:  #{ours[key].inspect}\n  other: #{theirs[key].inspect}"
+        end
+        their_dry_runs = Array(theirs["dry_runs"]).map { |dry| dry.slice("verb", "ok") }
+        if (ours["dry_runs"] || []) != their_dry_runs
+          found << "dry_runs:\n  ruby:  #{ours['dry_runs'].inspect}\n  other: #{their_dry_runs.inspect}"
+        end
+        found
+      end
+    end
+  end
+end

data/lib/hecks/rust_build/conformance_fuzz.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "tmpdir"
+require_relative "../cache_dir"
+require_relative "../rust_build"
+require_relative "conformance"
+
+module Hecks
+  module RustBuild
+    # Runs generated fuzz sequences through `Conformance` against a native or `.wasm` artifact
+    # (ADR 0039), stopping at the first diverging seed with a reproduction command.
+    #
+    #   ConformanceFuzz.call([domain, "native" | "path/to/module.wasm", seeds, steps])
+    #
+    # `seeds` and `steps` default to `SEEDS` and `STEPS` in the environment, then to 10 and 25.
+    module ConformanceFuzz
+      USAGE = "usage: hecks fuzz_conformance <domain> <native|path/to/module.wasm> [seeds] [steps]"
+
+      # What a domain directory's basename may be: a plain identifier, never `.` or `..`.
+      DOMAIN_NAME = /\A[A-Za-z0-9][A-Za-z0-9_-]*\z/
+
+      module_function
+
+      # @param argv [Array<String>] the domain, the artifact, and optionally seeds and steps
+      # @return [Integer] 0 when every sequence matched
+      # @raise [Failure] at the first seed that diverges, naming how to reproduce it
+      def call(argv)
+        require_relative "../../hecks"
+        require_relative "../fuzzing"
+        domain, artifact, seeds, steps = argv
+        raise Failure, USAGE unless domain && artifact
+
+        seeds = Integer(seeds || ENV["SEEDS"] || 10)
+        steps = Integer(steps || ENV["STEPS"] || 25)
+        scratch = scratch_dir(domain)
+        (1..seeds).each { |seed| replay(domain, artifact, seed, seeds, steps, scratch) }
+        FileUtils.rm_rf(scratch)
+        puts "#{domain}: #{seeds} generated sequence(s) x #{steps} step(s) each, all matched #{artifact}."
+        0
+      end
+
+      # A fresh directory per run, under the cache root outside the gem, so concurrent runs never
+      # share one; it is kept when a seed diverges, so the failing script outlives the run.
+      #
+      # @param domain [String] the domain's directory; its basename names the scratch directory
+      # @return [String] the new directory
+      # @raise [Failure] when the basename cannot safely name a directory
+      def scratch_dir(domain)
+        name = File.basename(domain.to_s.chomp("/"))
+        raise Failure, "#{USAGE}\n`#{domain}` is not a domain directory name" unless name.match?(DOMAIN_NAME)
+
+        parent = Hecks::CacheDir.path("rust_conformance_fuzz")
+        FileUtils.mkdir_p(parent)
+        Dir.mktmpdir("#{name}-", parent)
+      end
+
+      def replay(domain, artifact, seed, seeds, steps, scratch)
+        sequence = Hecks::Fuzzing::SequenceGenerator.generate(domain, seed: seed, steps: steps)
+        path = File.join(scratch, "seed-#{seed}.json")
+        File.write(path, JSON.generate({ "steps" => sequence }))
+        return if Conformance.call([domain, path, artifact]).zero?
+
+        raise Failure, "hecks fuzz_conformance: seed #{seed}/#{seeds} diverged against #{artifact} " \
+                       "(see the conformance output above) — " \
+                       "reproduce with: hecks check_conformance #{domain} #{path} #{artifact}"
+      end
+    end
+  end
+end