hecks 2.7.0 → 2.8.0

data/lib/hecks/bluebook/meta_validator.rb

@@ -541,7 +541,7 @@ module Hecks
       # every Paging-attached word (limit/offset/cursor/nulls) because
       # something called it inside this exact window.
       #
-      # SyntaxBoot.call no longer uses this. Gating its cache on "the
+      # SyntaxBoot.call does not use this. Gating its cache on "the
       # whole registry is finished" meant nothing was cached for the
       # entire window, and the window is not narrow — every word routed
       # through `word_gate_dispatch` while the language judged itself

data/lib/hecks/bluebook/model_check/client_profile.rb

@@ -15,60 +15,29 @@ module Hecks
       #
       # ## The rules
       #
-      # - `:client_group_by_row_drop` — a `group_by` whose fields do not include
-      #   the grouped aggregate's whole identity. Rows sharing a key path are
-      #   collapsed to the first, on every adapter (docs/decisions/0061).
       # - `:client_native_read_model` — a read model the SQLite projection
       #   answers natively, where every other path answers it in process
       #   (docs/1.0-readiness.md, "Known gaps at 1.0", item 2).
-      # - `:client_dotted_compute_source` — an era translation `compute` whose
-      #   source is a dotted path, which never fires
-      #   (`Translation::RuleCompiler.compile_compute`).
       module ClientProfile
         # Adapters whose Ruby class implements `query_read_model`, which is what
         # makes `ReadModelInterpreter#project` take the native path. The spec
         # checks this list against the adapter classes themselves.
         NATIVE_READ_MODEL_ADAPTERS = %w[SqliteProjection].freeze
 
-        GROUP_BY_TRACKER = "docs/decisions/0061-query-dsl-aggregation-count-sum-group-by.md".freeze
         NATIVE_READ_MODEL_TRACKER = "docs/1.0-readiness.md (Known gaps at 1.0, item 2)".freeze
-        DOTTED_COMPUTE_TRACKER = "Translation::RuleCompiler.compile_compute, and the pending example " \
-                                 "\"applies the SQL of a compute whose source is a dotted member\" in " \
-                                 "spec/adapters/driven/postgres_era/migration_data_safety_spec.rb".freeze
 
         module_function
 
-        # Runs every client-profile rule over one chapter and its translations.
+        # Runs every client-profile rule over one chapter.
         #
         # @param bluebook [Bluebook::Chapter] the assembled chapter to check
         # @param hecksagon [Bluebook::Hecksagon, nil] the chapter's sibling wiring file; without
         #   one no aggregate is projected, so the native-read-model rule has nothing to find
-        # @param translations [Array<Bluebook::Translation>] the data translations declared for
-        #   this chapter's domain
         # @return [Array<ModelCheck::Finding>] one error-severity finding per construct refused
-        def call(bluebook, hecksagon: nil, translations: [])
+        def call(bluebook, hecksagon: nil)
           bluebook.read_models.flat_map do |model|
-            group_by_findings(bluebook, model) + native_read_model_findings(model, hecksagon)
-          end + dotted_compute_findings(translations)
-        end
-
-        # Refuses a `group_by` that cannot prove each of its key paths names one row.
-        #
-        # The interpreter's `nest` keeps `stripped.first` per key path, whichever adapter
-        # supplied the rows, because a `group_by` model never reaches the native path. Grouping
-        # by the aggregate's whole identity is the one shape that cannot collide.
-        #
-        # @param bluebook [Bluebook::Chapter] the chapter the read model is declared in
-        # @param model [Bluebook::ReadModel] the read model to inspect
-        # @return [Array<ModelCheck::Finding>] one finding, or `[]` when `model` declares no
-        #   `group_by` or groups by its aggregate's whole identity
-        def group_by_findings(bluebook, model)
-          return [] if model.group_by.empty? || groups_by_identity?(bluebook, model)
-
-          [finding(:client_group_by_row_drop, model.name,
-                   "group_by #{model.group_by_fields.map(&:inspect).join(', ')} does not cover the grouped " \
-                   "aggregate's whole identity, so rows sharing a key path are silently reduced to the " \
-                   "first. Tracked in #{GROUP_BY_TRACKER}.")]
+            native_read_model_findings(model, hecksagon)
+          end
         end
 
         # Refuses a read model that the SQLite projection would answer natively.
@@ -95,26 +64,6 @@ module Hecks
                    "is not, and nothing checks the two agree. Tracked in #{NATIVE_READ_MODEL_TRACKER}.")]
         end
 
-        # Refuses a translation `compute` whose source names a member of a value object.
-        #
-        # `compile_compute` guards the compute with `__s ? '<from>'`, a top-level key test, so a
-        # dotted source never matches, the mint succeeds and the record keeps its old value.
-        #
-        # @param translations [Array<Bluebook::Translation>] the translations to inspect
-        # @return [Array<ModelCheck::Finding>] one finding per dotted-source compute
-        def dotted_compute_findings(translations)
-          translations.flat_map do |translation|
-            translation.aggregates.flat_map do |aggregate|
-              aggregate.computes.select { |compute| compute.from.to_s.include?(".") }.map do |compute|
-                finding(:client_dotted_compute_source, "#{translation.domain}::#{aggregate.name}",
-                        "compute #{compute.from.to_s.inspect} has a dotted source, which the compiled SQL " \
-                        "never matches, so the mint succeeds and leaves the old value in place. " \
-                        "Tracked in #{DOTTED_COMPUTE_TRACKER}.")
-              end
-            end
-          end
-        end
-
         # Reports whether a model's shape sends it down the native path in `#project`.
         #
         # @param model [Bluebook::ReadModel] the read model to inspect
@@ -123,21 +72,6 @@ module Hecks
           !model.reference_target.nil? && model.group_by.empty? && !model.count? && !model.median_field
         end
 
-        # Reports whether a `group_by` names every identity path of the aggregate it groups.
-        #
-        # @param bluebook [Bluebook::Chapter] the chapter the read model is declared in
-        # @param model [Bluebook::ReadModel] a read model that declares a `group_by`
-        # @return [Boolean] false when the many-side aggregate is not a top-level aggregate or
-        #   declares no identity, since uniqueness cannot then be shown
-        def groups_by_identity?(bluebook, model)
-          target = model.aggregate_heads.find { |head| head[:many] }
-          aggregate = target && bluebook.aggregate(target[:aggregate])
-          return false unless aggregate
-
-          identity = Array(aggregate.identity_heads).map(&:to_sym)
-          !identity.empty? && (identity - model.group_by_fields.map(&:to_sym)).empty?
-        end
-
         # Builds one error-severity finding of this profile.
         #
         # @param kind [Symbol] the finding's kind, one of the `:client_*` rules above

data/lib/hecks/bluebook/model_check.rb

@@ -25,7 +25,7 @@ module Hecks
       # **A finding shipped, not silenced** — the coverage-gate idiom, empty
       # allowlists enforced both directions (spec/model_check_spec.rb holds
       # this exact table: an error the checker reports and this does not
-      # name is a regression, an entry the checker no longer reports is
+      # name is a regression, an entry the checker does not report is
       # stale and must be deleted). bin/model_check reads this same
       # constant, so the tool and the spec can never drift apart.
       #
@@ -44,9 +44,9 @@ module Hecks
       # was a `state "x"` line never named by any handler's own from:/to:, a
       # pure declaration-drift artifact. States are derived from the
       # transitions that name them now (ProcessManagerBuilder#derived_
-      # states), so a state nothing ever transitions into or out of no
-      # longer exists to be unreachable — the finding that entry allowlisted
-      # cannot occur any more, by construction.
+      # states), so a state nothing ever transitions into or out of does
+      # not exist to be unreachable — the finding that entry allowlisted
+      # cannot occur, by construction.
       #
       # "banking"/NotifyOnClosure, FlagKeyReturn — gone from here, moved
       # to banking. `across "Notifications"` names a domain that does not
@@ -145,15 +145,11 @@ module Hecks
       #   findings for constructs known to answer wrongly without refusing;
       #   `nil` (the default) adds nothing and leaves every other finding as
       #   it was
-      # @param translations [Array<Bluebook::Translation>] the data
-      #   translations declared for this chapter's domain, read only by the
-      #   `:client` profile — they live on the registry, not the chapter, so
-      #   the caller supplies them the way it supplies `hecksagon`
       # @return [Array<Finding>] every finding this bluebook triggers,
       #   across its lifecycles, sagas, policies, and Rust-reserved names
       # @raise [ArgumentError] if `profile` is neither `nil` nor `:client`
       def call(bluebook, hecksagon: nil, known_domains: nil, global_emitted_events: nil, rust_target: false, strict: false,
-               profile: nil, translations: [])
+               profile: nil)
         unless profile.nil? || PROFILES.include?(profile)
           raise ArgumentError, "unknown profile #{profile.inspect} (known: #{PROFILES.inspect})"
         end
@@ -170,7 +166,7 @@ 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(ClientProfile.call(bluebook, hecksagon: hecksagon, translations: translations)) if profile == :client
+        findings.concat(ClientProfile.call(bluebook, hecksagon: hecksagon)) if profile == :client
         findings
       end
 
@@ -659,6 +655,9 @@ module Hecks
       #   sibling wiring file, if the caller loaded one
       # @param known_domains [Set<String>, nil] every bluebook/hecksagon
       #   name the caller has booted anywhere in this corpus scan
+      # @param global_emitted_events [Set<String>, nil] every event name emitted anywhere in the
+      #   corpus, consulted only as a fallback for a `translates` reaction; nil when the caller
+      #   has no cross-domain set to offer
       # @return [Array<Finding>] every `deaf_policy`/`unknown_trigger`
       #   finding this policy triggers, or `cross_domain_policy_findings`'s
       #   own return for a cross-domain policy
@@ -680,12 +679,12 @@ module Hecks
         # (`across "Compliance"`), which exits this method one line above
         # before the mismatch is ever reached.
         # `global_emitted_events` — a `translates` (hecksagon-level)
-        # reaction is BUILT as the exact same same-domain-target `Policy`
+        # reaction is built as the exact same same-domain-target `Policy`
         # an ordinary `policy` block is (no `target_domain`, so it never
         # reaches `cross_domain_policy_findings` above), but its whole
-        # point is to react to a FOREIGN domain's own event — this
+        # point is to react to a foreign domain's own event — this
         # domain's own `emitted_events(bluebook)` was never going to
-        # contain it. Checked only as a FALLBACK, after the local check
+        # contain it. Checked only as a fallback, after the local check
         # already failed, so a real same-domain typo still gets flagged
         # exactly as before whenever the caller has no cross-domain set
         # to offer (nil — every existing call site, unchanged) or the

data/lib/hecks/cache_dir.rb

@@ -0,0 +1,103 @@
+require "etc"
+require "fileutils"
+require "tmpdir"
+
+module Hecks
+  # The one place the runtime's own scratch files live, outside the gem.
+  #
+  # The syntax-boot cache and the Storehouse audit log are written on a
+  # normal run, so they cannot sit under the gem's own directory: an
+  # installed gem is read-only, and a checkout's `tmp/` is not a place a
+  # library gets to assume. Both ask this module for a subdirectory instead.
+  #
+  # ## Where the root is
+  #
+  # The first of these that can be made a private directory wins:
+  #
+  # 1. `$XDG_CACHE_HOME/hecks`, when `XDG_CACHE_HOME` is set to an absolute path
+  # 2. `~/.cache/hecks`
+  # 3. `<system temp dir>/hecks-<uid>`
+  #
+  # ## Private, or not used
+  #
+  # The syntax-boot cache is read back with `Marshal.load`, so a directory
+  # another account can write to is a way to run code as this one. A
+  # candidate is accepted only if it is owned by the current user and
+  # writable by nobody else; the shared temp directory in particular is
+  # where a predictable name can be planted by someone else. When no candidate
+  # qualifies, a fresh per-process directory stands in: the cache still
+  # works within the process and is never shared with a stranger.
+  module CacheDir
+    module_function
+
+    # The directory a named piece of scratch state lives in.
+    #
+    # @param name [String] the subdirectory, such as `"storehouse"`
+    # @return [String] the absolute path of `name` under the cache root; the
+    #   directory itself is created by whoever writes to it
+    def path(name)
+      File.join(root, name)
+    end
+
+    # The cache root, resolved once per process.
+    #
+    # @return [String] the absolute path of the directory every `path` lives under
+    def root
+      @root ||= resolve
+    end
+
+    # Forgets the resolved root so the next call resolves again.
+    #
+    # @return [void]
+    def reset!
+      @root = nil
+    end
+
+    # Picks the cache root from the environment.
+    #
+    # @param env [Hash{String => String}] the environment to read
+    #   `XDG_CACHE_HOME` and `HOME` from
+    # @param tmpdir [String] the system temp directory
+    # @param uid [Integer] the current user id, used in the temp fallback's name
+    # @return [String] the absolute path of the first candidate that is a
+    #   private directory owned by this user, else a per-process directory
+    def resolve(env: ENV, tmpdir: Dir.tmpdir, uid: Process.uid)
+      candidates(env, tmpdir, uid).each do |candidate|
+        return candidate if private_dir?(candidate)
+      end
+      Dir.mktmpdir("hecks-", tmpdir)
+    rescue StandardError
+      File.join(tmpdir, "hecks-#{uid}")
+    end
+
+    # The roots to try, most preferred first.
+    #
+    # @param env [Hash{String => String}] the environment
+    # @param tmpdir [String] the system temp directory
+    # @param uid [Integer] the current user id
+    # @return [Array<String>] absolute candidate paths
+    def candidates(env, tmpdir, uid)
+      xdg  = env["XDG_CACHE_HOME"].to_s
+      home = env["HOME"].to_s
+      list = []
+      list << File.join(xdg, "hecks") if File.absolute_path?(xdg)
+      list << File.join(home, ".cache", "hecks") if File.absolute_path?(home)
+      list << File.join(tmpdir, "hecks-#{uid}")
+    end
+    private_class_method :candidates
+
+    # Creates `dir` if needed and says whether it is private to this user.
+    #
+    # @param dir [String] the candidate directory
+    # @return [Boolean] true when `dir` is a directory owned by this user that
+    #   no other user can write to; false on any failure
+    def private_dir?(dir)
+      FileUtils.mkdir_p(dir, mode: 0o700)
+      stat = File.stat(dir)
+      stat.directory? && stat.owned? && stat.mode.nobits?(0o022) && File.writable?(dir)
+    rescue StandardError
+      false
+    end
+    private_class_method :private_dir?
+  end
+end

data/lib/hecks/cli/document.rb

@@ -0,0 +1,104 @@
+require_relative "../../hecks"
+
+module Hecks
+  module CLI
+    # The command behind `bin/docs`, `bin/narrate`, `hecks docs` and `hecks narrate`:
+    # one domain's document, projected from its own bluebook, to stdout.
+    #
+    # `:docs` answers the usage document a console's `<Domain>.docs` prints; `:narrate`
+    # answers the same chapter read back in English, for the subject-matter expert
+    # (`Projector::NarrateProjector`). Nothing is written for the caller: redirect it,
+    # so the caller decides where a generated file lands and git decides whether it
+    # drifted.
+    #
+    # ## Every failure is a sentence
+    #
+    # A misspelled aggregate refuses by name rather than printing nothing and exiting
+    # 0. A caller cannot tell an empty document from an empty domain, so this refuses
+    # instead and names what is actually there.
+    #
+    # ## Standing in a domain is enough
+    #
+    # `Adapters::Folder#domain_root` walks up for the nearest `.hecksagon`, which makes
+    # the first argument ambiguous. The rule: a directory is a domain, anything else
+    # is an aggregate name, and the two-argument form says which is which.
+    module Document
+      # Build output and other trees under a root that hold no domain a caller means.
+      # Matched against the path relative to the root, because a substring test
+      # against an absolute path tests wherever somebody happened to clone.
+      IGNORED = %r{\A(rust|deploy|tmp|coverage)/}
+
+      module_function
+
+      # Prints `projection` for the domain and optional aggregate `argv` names.
+      #
+      # @param argv [Array<String>] an optional domain directory, then an optional
+      #   aggregate name
+      # @param projection [Symbol] `:docs` or `:narrate`
+      # @param program [String] the name the usage message calls this command by
+      # @param root [String] the directory whose domains are listed when no domain
+      #   is found
+      # @return [void]
+      # @raise [SystemExit] when no domain is found, it cannot boot, it loads no
+      #   bluebook, or the aggregate does not exist
+      def call(argv, projection:, program:, root:)
+        here = Adapters::Folder.new.domain_root
+        path, aggregate = target(argv, here)
+        refuse_without_domain(program, root) unless path
+
+        begin
+          runtime = Hecks.boot(path, install_facade: false)
+        rescue StandardError => e
+          abort "cannot read #{path}: #{e.message.lines.first.strip}"
+        end
+
+        # The domain's own chapter, not a framework member it attached: insertion
+        # order, the same distinction `Runtime::Loader.dispatcher_for` draws.
+        bluebook = runtime.registry.bluebooks.values.first
+        abort "#{path} loaded no bluebook" unless bluebook
+
+        begin
+          puts Projector.call(projection, bluebook: bluebook, options: aggregate ? { aggregate: aggregate } : {})
+        rescue Runtime::NotFound => e
+          abort e.message
+        end
+      end
+
+      # Lists every directory under `root` that `Hecks.boot` would accept.
+      #
+      # Found by their wiring, not their chapters: a `.hecksagon` is what says "this
+      # is a domain, and here is how its aggregates are stored", while most
+      # `.bluebook` files (era translations, the language's own grammar,
+      # `spec/fixtures`) are not domains anybody boots.
+      #
+      # @param root [String] the directory to search under
+      # @return [Array<String>] domain directory paths relative to `root`,
+      #   deduplicated and sorted
+      def domains(root)
+        Dir.glob(File.join(root, "**/*.hecksagon"))
+           .map    { |path| File.basename(File.dirname(path)) == "bluebook" ? File.dirname(path, 2) : File.dirname(path) }
+           .map    { |path| path.delete_prefix("#{root}/") }
+           .grep_v(IGNORED)
+           .uniq.sort
+      end
+
+      # @api private
+      def target(argv, here)
+        if argv.empty?              then [here, nil]
+        elsif argv.length > 1       then [argv[0], argv[1]]
+        elsif File.directory?(argv[0]) then [argv[0], nil]
+        else [here, argv[0]]
+        end
+      end
+
+      # @api private
+      def refuse_without_domain(program, root)
+        warn "usage: #{program} [domain-path] [aggregate]"
+        warn ""
+        warn "No bluebook here — #{Dir.pwd} is not inside a domain. Name one:"
+        domains(root).each { |candidate| warn "  #{candidate}" }
+        exit 1
+      end
+    end
+  end
+end

data/lib/hecks/cli/ir.rb

@@ -0,0 +1,47 @@
+require_relative "../../hecks"
+# ADR 0033 — a domain wired to PostgresEra needs this plugin loaded
+# explicitly; the era/lineage subsystem does not load with core.
+require_relative "../ports/persistence/plugins/era"
+
+module Hecks
+  module CLI
+    # The command behind `bin/ir` and `hecks ir`: a booted domain's IR as JSON, the
+    # same `to_h` the golden specs pin and `StorageShape` hashes into an era, for
+    # reading rather than asserting on.
+    module Ir
+      module_function
+
+      # Prints the IR `argv` asks for.
+      #
+      # `--meta` prints the language's own IR, the chapters under
+      # `lib/hecks/language/bluebook/` merged into one. It is reached through
+      # `Bluebook::MetaValidator.grammar_registry`, the real boot sequence, so it
+      # cannot drift from what `MetaValidator` itself loads.
+      #
+      # @param argv [Array<String>] a domain path and `--translations`, or `--meta`
+      # @param program [String] the name the usage message calls this command by
+      # @param default_domain [String, nil] the domain booted when `argv` names none;
+      #   nil makes a domain argument required
+      # @return [void]
+      # @raise [SystemExit] when no domain is named and there is no default
+      def call(argv, program:, default_domain: nil)
+        argv = argv.dup
+        if argv.delete("--meta")
+          require_relative "../bluebook/meta_validator"
+          puts Projector::Exporter.json(Bluebook::MetaValidator.grammar_registry)
+          return
+        end
+
+        translations_only = argv.delete("--translations")
+        domain = argv.shift || default_domain or abort "usage: #{program} <domain> [--translations] | #{program} --meta"
+        runtime = Hecks.boot(domain)
+
+        if translations_only
+          puts Projector::Exporter.translations_json(runtime.registry)
+        else
+          puts Projector::Exporter.json(runtime.registry)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/cli/mcp.rb

@@ -0,0 +1,32 @@
+require_relative "../mcp_stdio_guard"
+
+module Hecks
+  module CLI
+    # The command behind `bin/hecks_mcp_door` and `hecks mcp`: the MCP door onto the
+    # storehouse bus, over stdio only.
+    #
+    # This file loads nothing but `McpStdioGuard`, so the transport check runs before
+    # the framework does. The door itself is `McpDoor`, required only once the check
+    # passes.
+    module Mcp
+      # The server name the guard's refusals and warnings carry.
+      SERVER = "hecks-mcp-door".freeze
+
+      module_function
+
+      # Refuses any transport but stdio, then serves JSON-RPC requests from stdin
+      # until it closes.
+      #
+      # @param argv [Array<String>] the arguments after the command; only `--stdio`
+      #   is accepted
+      # @return [void]
+      # @raise [SystemExit] with `McpStdioGuard::EXIT_STATUS` when the process is not
+      #   set up for stdio
+      def call(argv)
+        McpStdioGuard.enforce_stdio!(server: SERVER, argv: argv)
+        require_relative "mcp_door"
+        McpDoor.serve
+      end
+    end
+  end
+end