hecks 2.5.0 → 2.6.0

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

@@ -0,0 +1,153 @@
+module Hecks
+  module Bluebook
+    module ModelCheck
+      # The opt-in `client` profile: refuses the bluebook constructs this
+      # repository already knows produce a silently wrong answer, so a client
+      # domain cannot reach one without being told.
+      #
+      # ## What it is not
+      #
+      # It fixes nothing. Each rule below names a bug that is still open and
+      # stops a domain reaching it unnoticed; when the bug is fixed the rule
+      # goes with it. `spec/model_check_client_profile_spec.rb` holds a probe
+      # per rule that runs the buggy code and fails the moment the bug stops
+      # reproducing, naming the rule to delete.
+      #
+      # ## 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.
+        #
+        # @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: [])
+          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}.")]
+        end
+
+        # Refuses a read model that the SQLite projection would answer natively.
+        #
+        # Mirrors the fork in `ReadModelInterpreter#project`: a rooted model with no `group_by`,
+        # `count` or `median` reads through `read_repository`, which is a projection repository
+        # only for an aggregate with a `projected_by` bind. Whether that projection is current
+        # is only known at run time (`Registry#projection_current?`), so a model eligible here
+        # can also silently run in process.
+        #
+        # @param model [Bluebook::ReadModel] the read model to inspect
+        # @param hecksagon [Bluebook::Hecksagon, nil] the wiring holding the `projected_by` binds
+        # @return [Array<ModelCheck::Finding>] one finding, or `[]` when the model cannot be
+        #   pushed down
+        def native_read_model_findings(model, hecksagon)
+          return [] unless hecksagon && native_eligible?(model)
+
+          bind = hecksagon.binds_for(model.reference_target, Ports::Projection::VERB).first
+          return [] unless bind && NATIVE_READ_MODEL_ADAPTERS.include?(bind.adapter.to_s)
+
+          [finding(:client_native_read_model, model.name,
+                   "#{model.reference_target} is projected_by #{bind.adapter.inspect}, so this read model " \
+                   "is answered by SQL when the projection is current and by the in-process loop when it " \
+                   "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
+        # @return [Boolean] true for a rooted model declaring no `group_by`, `count` or `median`
+        def native_eligible?(model)
+          !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
+        # @param subject [String] the read model or `Domain::Aggregate` the finding is about
+        # @param message [String] what was found, why it is refused, and where it is tracked
+        # @return [ModelCheck::Finding] an `:error` finding
+        def finding(kind, subject, message)
+          ModelCheck::Finding.new(kind: kind, severity: :error, subject: subject, message: message)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/model_check.rb

@@ -1,4 +1,5 @@
 require "hecks/vocabulary"
+require_relative "model_check/client_profile"
 
 module Hecks
   module Bluebook
@@ -100,6 +101,9 @@ module Hecks
         # was needed or made.
       }.freeze
 
+      # The profiles `call` accepts; `nil` is the default, unprofiled run.
+      PROFILES = %i[client].freeze
+
       module_function
 
       # Runs every static model check over `bluebook` and returns what it
@@ -137,9 +141,23 @@ module Hecks
       #   target, raising `rust_reserved_name` findings to error
       # @param strict [Boolean] whether to raise every `rust_reserved_name`
       #   finding to error regardless of `rust_target`
+      # @param profile [Symbol, nil] `:client` adds `ClientProfile`'s error
+      #   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
-      def call(bluebook, hecksagon: nil, known_domains: nil, global_emitted_events: nil, rust_target: false, strict: false)
+      # @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: [])
+        unless profile.nil? || PROFILES.include?(profile)
+          raise ArgumentError, "unknown profile #{profile.inspect} (known: #{PROFILES.inspect})"
+        end
+
         findings = []
         bluebook.aggregates.each do |aggregate|
           findings.concat(lifecycle_findings(aggregate, aggregate))
@@ -152,6 +170,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
       end
 

data/lib/hecks/fuzzing/isolated_boot.rb

@@ -93,13 +93,17 @@ module Hecks
       #   `adapter: :postgres_era`; ignored by every other adapter
       # @param schema [String, nil] the schema name, required only for
       #   `adapter: :postgres_era`; ignored by every other adapter
+      # @param scratch [Hash{Symbol => String}] `:database` and/or `:schema` for
+      #   `adapter: :postgres` to use instead of the shared fuzz scratch schema, so a caller
+      #   such as `bin/bench` never drops the schema a concurrent `bin/fuzz` is using;
+      #   ignored by every other adapter
       # @yield [String] the freshly rebound copy's root directory, ready to boot
       # @yieldreturn [Object] anything; becomes this method's own return value
       # @return [Object] whatever the given block returns
       # @raise [ArgumentError] if `adapter` is not `:memory`, `:sqlite`, `:postgres`, or
       #   `:postgres_era`, or if `adapter: :postgres_era` is given without both
       #   `database:` and `schema:`
-      def call(domain_path, adapter: :memory, database: nil, schema: nil)
+      def call(domain_path, adapter: :memory, database: nil, schema: nil, scratch: {})
         Dir.mktmpdir("hecks-fuzz") do |tmp|
           copy = File.join(tmp, File.basename(domain_path))
           copy_dereferencing(domain_path, copy)
@@ -107,7 +111,7 @@ module Hecks
           case adapter
           when :memory       then rebind_to_memory!(copy)
           when :sqlite       then rebind_to_sqlite!(copy)
-          when :postgres     then rebind_to_postgres!(copy)
+          when :postgres     then rebind_to_postgres!(copy, **scratch)
           when :postgres_era then rebind_to_postgres_era!(copy, database: database, schema: schema)
           else raise ArgumentError,
                      "unknown fuzz adapter #{adapter.inspect} — :memory, :sqlite, :postgres, or :postgres_era"
@@ -262,15 +266,20 @@ module Hecks
       FUZZ_POSTGRES_SCHEMA   = "hecks_fuzz".freeze
 
       # Rewrites every `.hecksagon` in the copy to bind through Postgres, against the
-      # shared `FUZZ_POSTGRES_DATABASE`/`FUZZ_POSTGRES_SCHEMA` scratch schema.
+      # shared `FUZZ_POSTGRES_DATABASE`/`FUZZ_POSTGRES_SCHEMA` scratch schema unless the
+      # caller names its own, which lets `bin/bench` run without touching the fuzzer's.
       #
       # @param copy [String] the isolated copy's root directory
+      # @param database [String, nil] the scratch database, `FUZZ_POSTGRES_DATABASE` when nil
+      # @param schema [String, nil] the scratch schema, `FUZZ_POSTGRES_SCHEMA` when nil
       # @return [void]
-      def rebind_to_postgres!(copy)
+      def rebind_to_postgres!(copy, database: nil, schema: nil)
         require "pg"
+        database ||= FUZZ_POSTGRES_DATABASE
+        schema   ||= FUZZ_POSTGRES_SCHEMA
         rewrite_bindings!(copy, "Postgres")
         strip_translations!(copy)
-        ensure_fuzz_schema!
+        ensure_fuzz_schema!(database, schema)
 
         # One `.world` per directory a `.hecksagon` actually lives in, not
         # one at `copy`'s own root — `Folder#load_domain` resolves a
@@ -278,34 +287,17 @@ module Hecks
         # recursively (`Folder#load_each`); a domain can hold several
         # `Hecks.hecksagon "<Name>" do ... end` sibling blocks in that one
         # file (banking.hecksagon declares "Banking", "Governance", and
-        # "Identity" together), so every name found in one `.hecksagon`
-        # file gets bundled into one `.world` written beside it, not
-        # scattered by name.
-        Dir.glob(File.join(copy, "**", "*.hecksagon")).each do |hecksagon_path|
-          names = File.read(hecksagon_path).scan(/Hecks\.hecksagon\s+"([^"]+)"/).flatten.uniq
-          next if names.empty?
-
-          world_path = File.join(File.dirname(hecksagon_path), "hecks_fuzz_postgres.world")
-          File.write(world_path, names.map do |name|
-            <<~WORLD
-              Hecks.world "#{name}" do
-                persisted_by("Postgres") do
-                  database "#{FUZZ_POSTGRES_DATABASE}"
-                  schema "#{FUZZ_POSTGRES_SCHEMA}"
-                end
+        # "Identity" together), so every name found in one directory
+        # is bundled into one `.world` written there, not scattered by name.
+        write_worlds!(copy, "hecks_fuzz_postgres.world") do |name|
+          <<~WORLD
+            Hecks.world "#{name}" do
+              persisted_by("Postgres") do
+                database "#{database}"
+                schema "#{schema}"
               end
-            WORLD
-          end.join("\n"))
-        end
-
-        # Any pre-existing `.world` this copy shipped with (a real
-        # deployment's own connection string) is now redundant with — and
-        # would conflict with, `Registry#add_world`'s own header on
-        # loading the same domain name twice — the fresh one just
-        # written above, so it goes the same way `rebind_to_memory!`
-        # already sends every `.world` in a Memory-mode boot.
-        Dir.glob(File.join(copy, "**", "*.world")).each do |path|
-          File.delete(path) unless File.basename(path) == "hecks_fuzz_postgres.world"
+            end
+          WORLD
         end
       end
 
@@ -318,8 +310,10 @@ module Hecks
       # recreated on every call, which is what actually isolates one
       # ephemeral boot's data from the next.
       #
+      # @param database [String] the scratch database to create if missing
+      # @param schema [String] the schema to drop and recreate inside it
       # @return [void]
-      def ensure_fuzz_schema!
+      def ensure_fuzz_schema!(database = FUZZ_POSTGRES_DATABASE, schema = FUZZ_POSTGRES_SCHEMA)
         # `Adapters::Postgres#initialize` opens one real `PG::Connection`
         # per aggregate and never explicitly closes it — fine for a
         # process that boots once and runs, exactly what every other
@@ -342,17 +336,18 @@ module Hecks
         # something to route around by connecting less carefully.
         GC.start
 
-        unless @fuzz_database_ready
+        @fuzz_databases_ready ||= {}
+        unless @fuzz_databases_ready[database]
           admin = PG.connect(dbname: "postgres")
           exists = admin.exec_params(
-            "SELECT 1 FROM pg_database WHERE datname = $1", [FUZZ_POSTGRES_DATABASE]
+            "SELECT 1 FROM pg_database WHERE datname = $1", [database]
           ).ntuples.positive?
-          admin.exec(%(CREATE DATABASE "#{FUZZ_POSTGRES_DATABASE}")) unless exists
+          admin.exec(%(CREATE DATABASE "#{database}")) unless exists
           admin.close
-          @fuzz_database_ready = true
+          @fuzz_databases_ready[database] = true
         end
 
-        db = PG.connect(dbname: FUZZ_POSTGRES_DATABASE)
+        db = PG.connect(dbname: database)
         # **Quiet on purpose** — same as `Adapters::Postgres.connect_for`'s
         # own `SET client_min_messages`: a `DROP SCHEMA ... CASCADE` that
         # actually has something to drop (every boot after the first)
@@ -361,7 +356,7 @@ module Hecks
         # output under a wall of "drop cascades to table ..." on every
         # single ephemeral boot.
         db.exec("SET client_min_messages = warning")
-        quoted = db.quote_ident(FUZZ_POSTGRES_SCHEMA)
+        quoted = db.quote_ident(schema)
         db.exec("DROP SCHEMA IF EXISTS #{quoted} CASCADE")
         db.exec("CREATE SCHEMA #{quoted}")
         db.close
@@ -416,9 +411,9 @@ module Hecks
         ensure_postgres_era_schema!(database: database, schema: schema)
 
         # Same one-`.world`-per-`.hecksagon`-directory shape `rebind_to_
-        # postgres!` already uses, for the identical reason (`Folder#
-        # load_domain` globs `*.world` non-recursively) — see that
-        # method's own comment on `world_path` above. `PostgresEra`
+        # postgres!` uses, for the identical reason (`Folder#
+        # load_domain` globs `*.world` non-recursively) — see
+        # `write_worlds!`. `PostgresEra`
         # additionally takes `schema:` (postgres_era.rb's own "shared-
         # instance isolation" comment): the caller-supplied throwaway
         # schema is what actually isolates this one ephemeral boot from
@@ -444,36 +439,54 @@ module Hecks
         # database it is about to throw away; the one-line warning
         # PostgresEra prints per boot under the opt-in is the honest
         # price. Inert on a machine whose ambient user is ordinary.
-        # One world file per directory, every hecksagon name in that
-        # directory — not one write per *.hecksagon file. context_map.hecksagon
-        # sits beside the domain file; a second File.write to the same
-        # hecks_fuzz_postgres_era.world would drop the first file's names
-        # (found live: ConcurrentDispatchUnboundFixture + Governance).
-        worlds_by_dir = Hash.new { |h, k| h[k] = [] }
+        write_worlds!(copy, "hecks_fuzz_postgres_era.world") do |name|
+          <<~WORLD
+            Hecks.world "#{name}" do
+              persisted_by("PostgresEra") do
+                database "#{database}"
+                schema "#{schema}"
+                allow_superuser true
+              end
+            end
+          WORLD
+        end
+      end
+
+      # Writes one `.world` file per directory that holds a `.hecksagon`, naming every
+      # `Hecks.hecksagon` block found in that directory, and deletes every other `.world`
+      # in the copy.
+      #
+      # One world file per directory, every hecksagon name in that directory — never one
+      # write per `*.hecksagon` file. A domain's `context_map.hecksagon` sits beside its
+      # main hecksagon (the `qa` domain declares Governance in one and QualityControl in
+      # the other), and a second `File.write` to the same world path would drop the first
+      # file's names, leaving that domain bound to Postgres with no `database` to open.
+      #
+      # Any `.world` the copy shipped with (a real deployment's own connection string) is
+      # redundant with, and would conflict with (`Registry#add_world`'s own header, on
+      # loading the same domain name twice), the fresh one written here, so it goes the same
+      # way `rebind_to_memory!` sends every `.world` in a Memory-mode boot.
+      #
+      # @param copy [String] the isolated copy's root directory
+      # @param world_file [String] the basename of the world file written in each directory
+      # @yield [name] builds the world text for one hecksagon name
+      # @yieldparam name [String] a domain name a `Hecks.hecksagon` block in the directory declares
+      # @yieldreturn [String] the `Hecks.world` block for that name
+      # @return [void]
+      def write_worlds!(copy, world_file, &world_for)
+        names_by_dir = Hash.new { |hash, dir| hash[dir] = [] }
         Dir.glob(File.join(copy, "**", "*.hecksagon")).each do |hecksagon_path|
           names = File.read(hecksagon_path).scan(/Hecks\.hecksagon\s+"([^"]+)"/).flatten
-          worlds_by_dir[File.dirname(hecksagon_path)].concat(names)
+          names_by_dir[File.dirname(hecksagon_path)].concat(names)
         end
-        worlds_by_dir.each do |dir, names|
-          names = names.uniq
+        names_by_dir.each do |dir, names|
           next if names.empty?
 
-          world_path = File.join(dir, "hecks_fuzz_postgres_era.world")
-          File.write(world_path, names.map do |name|
-            <<~WORLD
-              Hecks.world "#{name}" do
-                persisted_by("PostgresEra") do
-                  database "#{database}"
-                  schema "#{schema}"
-                  allow_superuser true
-                end
-              end
-            WORLD
-          end.join("\n"))
+          File.write(File.join(dir, world_file), names.uniq.map(&world_for).join("\n"))
         end
 
         Dir.glob(File.join(copy, "**", "*.world")).each do |path|
-          File.delete(path) unless File.basename(path) == "hecks_fuzz_postgres_era.world"
+          File.delete(path) unless File.basename(path) == world_file
         end
       end
 

data/lib/hecks/mcp_stdio_guard.rb

@@ -0,0 +1,160 @@
+require "socket"
+
+module Hecks
+  # The startup gate for the stdio MCP servers in `bin/` (`hecks_mcp_door`,
+  # `hecks_query_ir_mcp`): it refuses to run when the process was set up to
+  # speak to anything but a local parent, and it says on stderr what the
+  # process does and does not protect.
+  #
+  # ## Why a gate and not a comment
+  #
+  # Both servers have no authentication. What keeps a stranger away from
+  # them is that only a process that can spawn them can write to their
+  # stdin. That holds until someone wraps one in `socat TCP-LISTEN:... EXEC:`
+  # or an `inetd`-style listener, which hands the process a network socket
+  # as stdin/stdout without changing a line of the server. The gate turns
+  # that setup into a refusal at startup instead of an exposure nobody
+  # noticed.
+  #
+  # ## What it checks
+  #
+  # - **Arguments** — none, except `--stdio`. A `--port` or `--http` flag is
+  #   refused rather than ignored, so a caller that believes it started a
+  #   network server finds out immediately.
+  # - **Environment** — no `HECKS_MCP_*` variable except
+  #   `HECKS_MCP_TRANSPORT=stdio`. The servers take no configuration, so an
+  #   unknown option in that namespace fails closed.
+  # - **Descriptors** — stdin and stdout must not be internet-protocol sockets
+  #   (`AF_INET` or `AF_INET6`). A pipe, a file, a terminal and a Unix-domain socket all pass;
+  #   the last matters because some MCP clients spawn servers over a
+  #   `socketpair`, which is local to the machine.
+  #
+  # ## What it does not do
+  #
+  # It does not authenticate anyone and it cannot see a proxy that copies
+  # bytes from a network socket into an ordinary pipe. It closes the
+  # configurations that announce themselves; the ADR on MCP authentication
+  # (`docs/decisions/0062-mcp-servers-need-real-authentication-before-any-network-transport.md`)
+  # covers what a network transport would need.
+  module McpStdioGuard
+    ACCEPTED_ARGS = %w[--stdio].freeze
+    ENV_PREFIX    = "HECKS_MCP_".freeze
+    ACCEPTED_ENV  = { "HECKS_MCP_TRANSPORT" => "stdio" }.freeze
+    EXIT_STATUS   = 2
+
+    # The lines every stdio server prints, ahead of its own notes.
+    COMMON_NOTES = [
+      "stdio only. This server has no authentication and must not be exposed over a network.",
+      "Whoever can write to this process's stdin can make every call it accepts."
+    ].freeze
+
+    module_function
+
+    # Lists every reason this process should not start as a stdio server.
+    #
+    # @param argv [Array<String>] the command-line arguments
+    # @param env [Hash{String => String}] the process environment
+    # @param stdin [IO] the stream requests arrive on
+    # @param stdout [IO] the stream responses leave on
+    # @return [Array<String>] one message per violation; empty when the process is
+    #   set up for stdio
+    def violations(argv: ARGV, env: ENV, stdin: $stdin, stdout: $stdout)
+      argument_violations(argv) + environment_violations(env) + descriptor_violations(stdin, stdout)
+    end
+
+    # Builds the warning printed at startup.
+    #
+    # @param server [String] the server's name, used as the line prefix
+    # @param notes [Array<String>] server-specific lines added after `COMMON_NOTES`
+    # @return [Array<String>] the banner lines, each prefixed with `server`
+    def banner(server:, notes: [])
+      (COMMON_NOTES + notes).map { |line| "#{server}: #{line}" }
+    end
+
+    # Refuses to continue on a non-stdio setup.
+    #
+    # A server calls this before it requires anything heavy, so a misconfigured start
+    # fails in milliseconds and before any protocol byte is answered. Everything goes
+    # to `stderr`: stdout carries the MCP protocol, and one stray line there corrupts
+    # the client's framing.
+    #
+    # @param server [String] the server's name, used as the line prefix
+    # @param argv [Array<String>] the command-line arguments
+    # @param env [Hash{String => String}] the process environment
+    # @param stdin [IO] the stream requests arrive on
+    # @param stdout [IO] the stream responses leave on
+    # @param stderr [IO] where the refusal is written
+    # @return [void]
+    # @raise [SystemExit] with status `EXIT_STATUS` when `violations` is not empty
+    def enforce_stdio!(server:, argv: ARGV, env: ENV, stdin: $stdin, stdout: $stdout, stderr: $stderr)
+      found = violations(argv: argv, env: env, stdin: stdin, stdout: stdout)
+      refuse!(server, found, stderr) unless found.empty?
+    end
+
+    # Prints the startup warning to `stderr`, never to stdout.
+    #
+    # @param server [String] the server's name, used as the line prefix
+    # @param notes [Array<String>] server-specific warning lines
+    # @param stderr [IO] where the warning is written
+    # @return [void]
+    def warn!(server:, notes: [], stderr: $stderr)
+      banner(server: server, notes: notes).each { |line| stderr.puts(line) }
+    end
+
+    # Enforces stdio, then prints the warning.
+    #
+    # @param server [String] the server's name, used as the line prefix
+    # @param notes [Array<String>] server-specific warning lines
+    # @param stderr [IO] where the refusal or the warning is written
+    # @param checks [Hash{Symbol => Object}] `argv:`, `env:`, `stdin:` and `stdout:`, as
+    #   for `enforce_stdio!`
+    # @return [void]
+    # @raise [SystemExit] with status `EXIT_STATUS` when the setup is not stdio
+    def start!(server:, notes: [], stderr: $stderr, **checks)
+      enforce_stdio!(server: server, stderr: stderr, **checks)
+      warn!(server: server, notes: notes, stderr: stderr)
+    end
+
+    # @api private
+    def refuse!(server, found, stderr)
+      found.each { |message| stderr.puts("#{server}: refusing to start: #{message}") }
+      stderr.puts("#{server}: this server speaks MCP over stdio only.")
+      exit(EXIT_STATUS)
+    end
+
+    # @api private
+    def argument_violations(argv)
+      (argv - ACCEPTED_ARGS).map do |arg|
+        "argument #{arg.inspect} is not accepted (only #{ACCEPTED_ARGS.join(', ')}); network options are refused, not ignored"
+      end
+    end
+
+    # @api private
+    def environment_violations(env)
+      env.select { |name, value| name.start_with?(ENV_PREFIX) && ACCEPTED_ENV[name] != value }.map do |name, value|
+        "environment #{name}=#{value.inspect} is not accepted; the servers take no #{ENV_PREFIX}* options " \
+          "except #{ACCEPTED_ENV.map { |k, v| "#{k}=#{v}" }.join(', ')}"
+      end
+    end
+
+    # @api private
+    def descriptor_violations(stdin, stdout)
+      { "stdin" => stdin, "stdout" => stdout }.select { |_, io| ip_socket?(io) }.map do |label, _|
+        "#{label} is a network (IP) socket, so this process is being served over a network"
+      end
+    end
+
+    # A socket whose address cannot be read is refused: it cannot be shown to be local.
+    #
+    # @api private
+    def ip_socket?(io)
+      return false unless io.stat.socket?
+
+      socket = Socket.for_fd(io.fileno)
+      socket.autoclose = false # the descriptor belongs to `io`
+      socket.local_address.ip?
+    rescue SystemCallError, IOError
+      true
+    end
+  end
+end

data/lib/hecks/version.rb

@@ -12,5 +12,5 @@ module Hecks
   # it there, or even in the consuming Gemfile, never closed the gap,
   # because gemspec evaluation happens before anything Bundler
   # resolves is actually loadable yet.
-  VERSION = "2.5.0".freeze
+  VERSION = "2.6.0".freeze
 end

data/lib/hecks.rb

@@ -31,6 +31,7 @@ require_relative "hecks/projections"
 require_relative "hecks/facade/cli_door"
 require_relative "hecks/facade/cli_runner"
 require_relative "hecks/storehouse"
+require_relative "hecks/mcp_stdio_guard"
 require_relative "hecks/framework"
 require_relative "hecks/corpus"
 require_relative "hecks/embryonaut_bluebook"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hecks
 version: !ruby/object:Gem::Version
-  version: 2.5.0
+  version: 2.6.0
 platform: ruby
 authors:
 - Chris Young
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-26 00:00:00.000000000 Z
+date: 2026-09-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism
@@ -94,6 +94,17 @@ files:
 - lib/hecks/behaviors/ir.rb
 - lib/hecks/behaviors/rspec.rb
 - lib/hecks/behaviors/runner.rb
+- lib/hecks/bench.rb
+- lib/hecks/bench/cli.rb
+- lib/hecks/bench/environment.rb
+- lib/hecks/bench/postgres_probe.rb
+- lib/hecks/bench/report.rb
+- lib/hecks/bench/ruby_runner.rb
+- lib/hecks/bench/run.rb
+- lib/hecks/bench/rust_runner.rb
+- lib/hecks/bench/stats.rb
+- lib/hecks/bench/suite.rb
+- lib/hecks/bench/workload.rb
 - lib/hecks/bluebook.rb
 - lib/hecks/bluebook/aggregate.rb
 - lib/hecks/bluebook/assembly.rb
@@ -174,6 +185,7 @@ files:
 - lib/hecks/bluebook/meta_validator/translation_judge.rb
 - lib/hecks/bluebook/meta_validator/world_judge.rb
 - lib/hecks/bluebook/model_check.rb
+- lib/hecks/bluebook/model_check/client_profile.rb
 - lib/hecks/bluebook/pattern_subset.rb
 - lib/hecks/bluebook/policy.rb
 - lib/hecks/bluebook/process_manager.rb
@@ -302,6 +314,7 @@ files:
 - lib/hecks/language/world/wiring.bluebook
 - lib/hecks/language/world/world.bluebook
 - lib/hecks/literal.rb
+- lib/hecks/mcp_stdio_guard.rb
 - lib/hecks/naming.rb
 - lib/hecks/ports.rb
 - lib/hecks/ports/access_control.port