hecks 3.10.0 → 3.12.0

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

@@ -16,6 +16,11 @@ module Hecks
           [/\A(.+)\.set\?\z/, Assignment, { negated: false }], [/\A(.+)\.unset\?\z/, Assignment, { negated: true }]
         ].freeze
 
+        # The strip family, each matched as `<receiver>.<call>`, naming which ends it trims.
+        STRIP_SUFFIXES = [
+          [/\A(.+)\.strip\z/, :both], [/\A(.+)\.lstrip\z/, :left], [/\A(.+)\.rstrip\z/, :right]
+        ].freeze
+
         # The suffix calls that carry one quoted argument, as `<receiver>.<call>("<argument>")`.
         TEXT_SUFFIXES = [
           [/\A(.+)\.split\("([^"]*)"\)\z/, Split, :separator],
@@ -23,10 +28,15 @@ module Hecks
           [/\A(.+)\.end_with\?\("([^"]*)"\)\z/, EndsWith, :substring]
         ].freeze
 
+        # The node each infix operator builds, by precedence level.
+        ADDITIVE       = { "+" => Addition, "-" => Subtraction }.freeze
+        MULTIPLICATIVE = { "*" => Multiplication, "/" => Division }.freeze
+
         # Every step `parse` tries, in precedence order (`.length` first, sign tests before the
         # rest); each answers a node, or `nil` when the expression is not its form.
-        PARSE_STEPS = [:parse_length, :parse_literal, :parse_array, :parse_addition, :parse_sign_test,
-                       :parse_receiver_suffix, :parse_modulo, :parse_matches_regex, :parse_text_suffix,
+        PARSE_STEPS = [:parse_length, :parse_literal, :parse_array, :parse_additive, :parse_multiplicative,
+                       :parse_group, :parse_sign_test,
+                       :parse_receiver_suffix, :parse_strip, :parse_modulo, :parse_matches_regex, :parse_text_suffix,
                        :parse_block_opener].freeze
 
         # @param expr [String] the leaf expression text
@@ -62,9 +72,24 @@ module Hecks
           ArrayLiteral.new(elements: elements.map { |element| parse(element) }) if elements
         end
 
-        def parse_addition(expr)
-          arithmetic = split_addition(expr)
-          Addition.new(left: parse(arithmetic[0]), right: parse(arithmetic[1])) if arithmetic
+        # The additive level: the last top-level `+` or binary `-`, so `a - b + c` is `(a - b) + c`.
+        def parse_additive(expr)
+          parse_binary(expr, ADDITIVE)
+        end
+
+        # The multiplicative level, binding tighter than the additive one.
+        def parse_multiplicative(expr)
+          parse_binary(expr, MULTIPLICATIVE)
+        end
+
+        # A parenthesised group reads as what it wraps.
+        def parse_group(expr)
+          parse(expr[1..-2]) if grouped?(expr)
+        end
+
+        def parse_binary(expr, table)
+          operator, left, right = split_last_binary(expr, table.keys)
+          table.fetch(operator).new(left: parse(left), right: parse(right)) if operator
         end
 
         def parse_sign_test(expr)
@@ -80,6 +105,14 @@ module Hecks
           nil
         end
 
+        def parse_strip(expr)
+          STRIP_SUFFIXES.each do |pattern, side|
+            match = expr.match(pattern)
+            return Strip.new(receiver: parse(match[1]), side: side) if match
+          end
+          nil
+        end
+
         def parse_modulo(expr)
           modulo = match_call(expr, ".modulo(")
           Modulo.new(receiver: parse(modulo[0]), divisor: parse(modulo[1])) if modulo

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

@@ -66,17 +66,34 @@ module Hecks
           elements.map(&:strip)
         end
 
-        # Braces and brackets count toward depth like parens, so a `+` inside a block body
-        # or an array element is not this expression's own addition.
-        def split_addition(expr)
+        # The text before and after the last top-level binary operator in `operators`, so a chain
+        # splits left-associatively. A `-` is binary only after an operand (`a - b`, not `a - -b`
+        # or a leading `-5`).
+        #
+        # @param operators [Array<String>] the single-character operators to split on
+        # @return [Array<String>, nil] the operator and the texts either side, or `nil`
+        def split_last_binary(expr, operators)
           depth = 0
+          found = nil
           scan_text(expr) do |char, index, plain|
             next unless plain
 
             depth += DEPTH_DELTA.fetch(char, 0)
-            return [expr[0...index].strip, expr[(index + 1)..].strip] if char == "+" && depth.zero?
+            found = index if depth.zero? && operators.include?(char) && binary_position?(expr, index, char)
           end
-          nil
+          found && [expr[found], expr[0...found].strip, expr[(found + 1)..].strip]
+        end
+
+        # Whether the operator at `index` has an operand on its left; only `-` can also be a sign.
+        def binary_position?(expr, index, char)
+          return true unless char == "-"
+
+          expr[0...index].rstrip.match?(/[[:alnum:]_)\]"']\z/)
+        end
+
+        # Whether `expr` is one parenthesised group: its first `(` closes at its last character.
+        def grouped?(expr)
+          expr.start_with?("(") && matching_paren(expr, 1) == expr.length - 1
         end
 
         # Whether `expr` is wrapped in a matching pair of quotes.

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

@@ -76,6 +76,16 @@ module Hecks
           value.split(separator)
         end
 
+        def strip_value(value, side)
+          raise EvaluationError, "strip expects a string, got #{describe(value)}" unless value.is_a?(String)
+
+          case side
+          when :left  then value.lstrip
+          when :right then value.rstrip
+          else value.strip
+          end
+        end
+
         def last_of(value)
           return value.last if value.respond_to?(:last)
 

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

@@ -27,6 +27,11 @@ module Hecks
         # A plain class: `Struct.new(keyword_init: true)` with no members raises on Ruby 3.2.
         NilLiteral     = Class.new
         Addition       = Struct.new(:left, :right, keyword_init: true)
+        Subtraction    = Struct.new(:left, :right, keyword_init: true)
+        Multiplication = Struct.new(:left, :right, keyword_init: true)
+        # Integer operands divide with floor semantics (toward negative infinity); a zero divisor
+        # is an evaluation fault, never a crash or an infinity.
+        Division       = Struct.new(:left, :right, keyword_init: true)
         SignTest       = Struct.new(:operator, :test, :receiver, keyword_init: true)
         Empty          = Struct.new(:receiver, keyword_init: true)
         ToS            = Struct.new(:receiver, keyword_init: true)
@@ -43,6 +48,11 @@ module Hecks
 
         Split          = Struct.new(:receiver, :separator, keyword_init: true)
 
+        # `.strip`/`.lstrip`/`.rstrip`: `side` is `:both`, `:left` or `:right`. Strips Ruby's own
+        # whitespace set (null, tab, line feed, vertical tab, form feed, carriage return, space),
+        # never Unicode spaces; a receiver that is not a String is an evaluation fault.
+        Strip          = Struct.new(:receiver, :side, keyword_init: true)
+
         Last           = Struct.new(:receiver, keyword_init: true)
 
         First          = Struct.new(:receiver, keyword_init: true)
@@ -72,12 +82,21 @@ module Hecks
           when IntegerLiteral, FloatLiteral, StringLiteral, BoolLiteral then node.value
           when ArrayLiteral then node.elements.map { |element| interpret(element, state, attrs) }
           when NilLiteral then nil
-          when Addition then add(interpret(node.left, state, attrs), interpret(node.right, state, attrs))
+          when Addition, Subtraction, Multiplication, Division then interpret_binary(node, state, attrs)
           when Lookup then lookup(node.path, state, attrs)
           else interpret_on_receiver(node, state, attrs)
           end
         end
 
+        # Each arithmetic node and the operation that applies it to its two resolved operands.
+        BINARY_OPERATIONS = { Addition => :add, Subtraction => :subtract, Multiplication => :multiply,
+                              Division => :divide }.freeze
+
+        def interpret_binary(node, state, attrs)
+          operation = BINARY_OPERATIONS.find { |klass, _| node.is_a?(klass) }.last
+          public_send(operation, interpret(node.left, state, attrs), interpret(node.right, state, attrs))
+        end
+
         # Resolves the node's receiver, then applies the operation `RECEIVER_OPERATIONS` names.
         def interpret_on_receiver(node, state, attrs)
           _, operation = RECEIVER_OPERATIONS.find { |klass, _| node.is_a?(klass) }

data/lib/hecks/bluebook/hecksagon.rb

@@ -10,10 +10,17 @@ module Hecks
       def effect? = signal == :effect
     end
 
-    Adapter = Struct.new(:name, :port, :fields, :secrets, keyword_init: true) do
+    # One `.adapter`: the port it implements, the settings a world may give it, and the secrets.
+    # `defaults` maps a field's name to the value used when the world gives none; a string may hold
+    # a `{name}` or `{storage_name}` placeholder, filled from the aggregate the adapter is built
+    # for.
+    Adapter = Struct.new(:name, :port, :fields, :secrets, :defaults, keyword_init: true) do
       def declares?(field) = all_fields.include?(field.to_sym)
 
       def all_fields = (fields || []) + (secrets || [])
+
+      # @return [Hash{Symbol => Object}] the declared defaults, empty when none
+      def declared_defaults = defaults || {}
     end
 
     Bind = Struct.new(:aggregate, :verb, :adapter, :role, keyword_init: true) do
@@ -49,15 +56,19 @@ module Hecks
         binds:         many(:binds),
         subscriptions: -> { subscriptions.map(&:to_s) },
         attachments:   -> { attachments.map(&:to_h) },
+        driving:       -> { driving.map(&:to_s) },
         bounded:       :bounded?,
         translates:    -> { translates.map(&:to_s) }
       )
 
-      attr_reader :domain, :binds, :subscriptions, :attachments, :translates
+      attr_reader :domain, :binds, :subscriptions, :attachments, :translates, :driving
+
+      # The driving adapters `driven_by` can name.
+      DRIVING_ADAPTERS = %w[Ruby Cli Json Mcp].freeze
 
       # Every optional keyword and what it holds when the declaration omits it.
       FIELD_DEFAULTS = {
-        binds: [], subscriptions: [], attachments: [], bounded: false, translates: []
+        binds: [], subscriptions: [], attachments: [], bounded: false, translates: [], driving: []
       }.freeze
 
       # @param domain [String, Symbol] the domain this hecksagon wires
@@ -69,11 +80,13 @@ module Hecks
       # @param bounded [Boolean] whether this chapter is an explicit bounded context
       #   (consumer-owned; `attaches` marks attached chapters bounded on the registry instead)
       # @param translates [Array<String>] names of `translates` ACL blocks declared here
+      # @param driving [Array<String>] the driving adapters `driven_by` admits; empty admits all
       def initialize(domain:, **given)
         KeywordFields.assign(self, KeywordFields.fill(given, FIELD_DEFAULTS))
         @domain             = domain.to_s
         @bounded            = @bounded ? true : false
         @translates         = Array(@translates).map(&:to_s)
+        @driving            = Array(@driving).map(&:to_s)
       end
 
       # Says whether this hecksagon marked its own chapter `bounded`.
@@ -93,6 +106,13 @@ module Hecks
       # @return [Boolean] whether that chapter is attached here
       def attaches?(chapter) = member_chapters.include?(chapter.to_s)
 
+      # Says whether a driving adapter may reach this hecksagon's domain: every adapter may when
+      # none is declared, and only the declared ones may once any is.
+      #
+      # @param adapter [String, Symbol] a driving adapter's name, such as `"Mcp"`
+      # @return [Boolean] whether `driven_by` admits that adapter
+      def driven_by?(adapter) = driving.empty? || driving.include?(adapter.to_s)
+
       # The vendored packages this hecksagon attaches.
       #
       # @return [Array<String>] their directory names, in the order they were attached

data/lib/hecks/bluebook/lifecycle.rb

@@ -32,19 +32,38 @@ module Hecks
         field:       -> { field.to_s },
         default:     :default,
         # `expand` is private; a Proc runs in the construct's own context, so it can reach it.
-        transitions: -> { transitions.flat_map { |command, t| expand(command, t) } }
+        transitions: -> { transitions.flat_map { |command, t| expand(command, t) } },
+        # Dropped from `to_h` when empty (see below), so an unmarked lifecycle's IR is unchanged.
+        marks:       :marks
       )
 
-      attr_reader :field, :default, :transitions
+      attr_reader :field, :default, :transitions, :marks
 
       # @param field [Symbol, String] the attribute this state machine lives on
       # @param default [String, Symbol] the state a new record starts in
       # @param transitions [Array<Array(String, Bluebook::StateTransition)>] each declared
       #   `command name, StateTransition` pair, in declaration order
-      def initialize(field:, default:, transitions: [])
+      # @param marks [Hash{String, Symbol => Array<String, Symbol>}] each named meaning and the
+      #   states that carry it, such as `holds_seat => ["pending", "succeeded"]`
+      def initialize(field:, default:, transitions: [], marks: {})
         @field       = field.to_sym
         @default     = default.to_s
         @transitions = transitions
+        @marks       = marks.to_h { |name, states| [name.to_s, Array(states).map(&:to_s)] }
+      end
+
+      # The states a named meaning marks.
+      #
+      # @param name [String, Symbol] the mark, such as `:holds_seat`
+      # @return [Array<String>, nil] the states in declared order, or nil when no such mark
+      def marked(name) = marks[name.to_s]
+
+      # `marks` is left out when the lifecycle declares none, so IR written before the word
+      # existed stays byte-identical.
+      def to_h
+        row = super
+        row.delete(:marks) if marks.empty?
+        row
       end
     end
   end

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

@@ -3,6 +3,9 @@ module Hecks
     module MetaValidator
       # Offers a built .adapter to the self-hosted adapter language (adapter.bluebook).
       class AdapterJudge
+        # Marks a field with no declared default; `nil` and `false` are defaults too.
+        NONE = Object.new.freeze
+
         attr_reader :refusals
 
         # @param adapter [Bluebook::Adapter] the built adapter to judge
@@ -34,10 +37,19 @@ module Hecks
 
         def judge!
           send_to("Adapter::Adapter.Declare", @adapter.name, name: v(@adapter.name), port: v(@adapter.port))
-          add_all("AddField", @adapter.fields)
+          add_fields
           add_all("AddSecret", @adapter.secrets)
         end
 
+        # Offers one `AddField` per field, each with its declared default when it has one.
+        def add_fields
+          Array(@adapter.fields).each do |field|
+            default = @adapter.declared_defaults.fetch(field.to_sym, NONE)
+            send_to("Adapter::Adapter.AddField", @adapter.name, name: @adapter.name, value: v(field),
+                                                                default: default.equal?(NONE) ? nil : v(default.inspect))
+          end
+        end
+
         # Offers one `verb` per value, each addressed to the adapter by name.
         def add_all(verb, values)
           Array(values).each do |value|

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

@@ -4,6 +4,9 @@ module Hecks
       # The mode switches of judging: bootstrapping, deferring, disabled, shadow-parsing and the
       # forced fixpoint. `MetaValidator` extends this, so each reads and writes its own state.
       module Modes
+        # Raised when a mode is asked for a builder that was never opened.
+        class Error < RuntimeError; end
+
         # Whether the language's own grammar is still loading raw, unjudged.
         # Judging it while it loads would recurse, so the bootstrap sets this
         # and the fixpoint clears it once every grammar file is merged.
@@ -66,7 +69,7 @@ module Hecks
           # Bare chapter-level givens must resolve before anything below
           # reads a `Given`'s fields. The `raise` block never runs — this
           # chapter's builder is always already open by the time `chapter` exists.
-          builder = registry.bluebook_builder(name) { raise "internal: no open builder for #{name}" }
+          builder = registry.bluebook_builder(name) { raise Error, "internal: no open builder for #{name}" }
           builder.resolve_pending_chapter_givens!
           # Same, one level down: entity-scoped pending givens.
           builder.resolve_pending_chapter_entity_givens!

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

@@ -57,11 +57,25 @@ module Hecks
           end
         end
 
+        # A mark names several states, so it expands into one row per state, in declared order.
+        def mark_rows(node)
+          lifecycle = node.respond_to?(:lifecycle) ? node.lifecycle : nil
+          return [] unless lifecycle
+
+          lifecycle.marks.flat_map { |name, states| states.map { |state| { name: name, state: state } } }
+        end
+
         # An open map has no value object to hold it, so each entry is its own row.
         def pair_rows(map)
           Array(map&.to_h).map { |key, value| { key: key, value: value } }
         end
 
+        # A member's cells, each spelled so a quoted `"true"` stays a String and a bare `true` a
+        # boolean.
+        def member_pair_rows(map)
+          Array(map&.to_h).map { |key, value| { key: key, value: Assembly::Scalars.mark(value) } }
+        end
+
         # Flattens options via `extra_options_to_h` — a new option needs no
         # change here. `filters: true` reads wheres/order_by/limit live off
         # the node, not `to_h`, so wire-format changes there don't affect it.
@@ -116,7 +130,16 @@ module Hecks
 
           [{ target: mutation.target, op: mutation.op, field: mutation.target,
              kind: classified[:kind],
-             source: classified[:name] || encode_literal(classified[:value]) }]
+             source: scalar_source_text(classified) }]
+        end
+
+        # The one text a scalar mutation's source is stored as: an argument or state name, an
+        # expression's text, or an encoded literal.
+        def scalar_source_text(classified)
+          return classified[:name] if classified.key?(:name)
+          return classified[:text] if classified.key?(:text)
+
+          encode_literal(classified[:value])
         end
 
         # The columns of one canonical-form table entry, as the language declares them.

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

@@ -79,7 +79,8 @@ module Hecks
             {
               field:       field,
               default:     text(row[:state_start]),
-              transitions: Array(row[:transitions]).map { |move| transition(move) }
+              transitions: Array(row[:transitions]).map { |move| transition(move) },
+              marks:       Array(row[:marks]).map { |held| mark(held) }
             }
           end
         end

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

@@ -41,11 +41,14 @@ module Hecks
         # dispatched state, one member at a time, not behind a `DeclaredIn` query.
         def members_row(row) = members_of(row)
 
-        # The key is stringified, never the value: a pair's value keeps whatever
-        # native Ruby type the source line actually wrote.
+        # The key is stringified, never the value: a pair's value is read back from its text by
+        # `Assembly::Scalars`, so a quoted cell returns a String and `true`, `false` and numbers
+        # return as the builder holds them.
         def members_of(value_object_row)
           Array(value_object_row[:members]).map do |member|
-            Array(member[:pairs]).map { |pair| [text(pair[:key]).to_s, text(pair[:value])] }
+            Array(member[:pairs]).map do |pair|
+              [text(pair[:key]).to_s, Assembly::Scalars.unmark(text(pair[:value]))]
+            end
           end
         end
 

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

@@ -86,6 +86,10 @@ module Hecks
           }
         end
 
+        def mark(row)
+          { name: text(row[:name]), state: text(row[:state]) }
+        end
+
         def head(row)
           {
             aggregate: text(row[:aggregate]),
@@ -140,6 +144,7 @@ module Hecks
           value = text(binding[:source])
 
           return { kind: kind, name: value } if %w[argument state].include?(kind)
+          return { kind: kind, text: value } if kind == "expression"
 
           { kind: "literal", value: decode_literal(value) }
         end

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

@@ -34,7 +34,7 @@ module Hecks
         # project, serve or deploy from a chapter, and nothing the judge runs
         # calls into them. An edit there leaves every verdict as it was, so
         # their files stay out of the key. Paths are relative to `lib/hecks`.
-        CONSUMER_TREES = %r{\A/hecks/(?:bench|cli|codemod|deploy|doc|doors|fuzzing|projections|
+        CONSUMER_TREES = %r{\A/hecks/(?:bench|cli|codemod|deploy|doc|adapters/driving|fuzzing|projections|
                             quality_control|release)(?:/|\.rb\z)}x
 
         # Files older than this that do not match the current code digest are

data/lib/hecks/bluebook/meta_validator.rb

@@ -15,7 +15,7 @@ module Hecks
       GRAMMAR_FILES = Dir.glob(File.join(GRAMMAR_DIR, "*.bluebook")).freeze
       WORLD_GRAMMAR = Dir.glob(File.expand_path("../language/world/*.bluebook", __dir__)).freeze
       HECKSAGON_GRAMMAR = Dir.glob(File.expand_path("../language/hecksagon/*.bluebook", __dir__)).freeze
-      # Backs PortJudge, the same door shape as WorldJudge.
+      # Backs PortJudge, the same entry point shape as WorldJudge.
       PORT_GRAMMAR = File.expand_path("../language/port.bluebook", __dir__).freeze
       # Backs AdapterJudge, one file over.
       ADAPTER_GRAMMAR = File.expand_path("../language/adapter.bluebook", __dir__).freeze
@@ -41,42 +41,42 @@ module Hecks
       #   verdict Hash for a chapter
       def self.verdicts = @verdicts ||= VerdictCache.seed
 
-      # Judges `world` through the meta-domain's own `WorldJudge` door.
+      # Judges `world` through the meta-domain's own `WorldJudge` entry point.
       #
       # @param world [Bluebook::World] the world to judge
       # @return [Bluebook::World] `world` unchanged, if well formed or
       #   while disabled/bootstrapping/shadow-parsing
       # @raise [DSL::Malformed] if `WorldJudge` finds `world` malformed
       def self.call_world(world)
-        judge_door(world, WorldJudge, "#{world.domain}'s world") do
+        judge_artifact(world, WorldJudge, "#{world.domain}'s world") do
           JSON.generate([world.domain, world.realm, world.latest, world.settings])
         end
       end
 
-      # Judges `port` through the meta-domain's own `PortJudge` door.
+      # Judges `port` through the meta-domain's own `PortJudge` entry point.
       #
       # @param port [Bluebook::Port] the port to judge
       # @return [Bluebook::Port] `port` unchanged, if well formed or while
       #   disabled/bootstrapping/shadow-parsing
       # @raise [DSL::Malformed] if `PortJudge` finds `port` malformed
       def self.call_port(port)
-        judge_door(port, PortJudge, "#{port.name}'s port") { JSON.generate([port.name, port.verb, port.signal]) }
+        judge_artifact(port, PortJudge, "#{port.name}'s port") { JSON.generate([port.name, port.verb, port.signal]) }
       end
 
-      # Judges `adapter` through the meta-domain's own `AdapterJudge` door.
+      # Judges `adapter` through the meta-domain's own `AdapterJudge` entry point.
       #
       # @param adapter [Bluebook::Adapter] the adapter to judge
       # @return [Bluebook::Adapter] `adapter` unchanged, if well formed or
       #   while disabled/bootstrapping/shadow-parsing
       # @raise [DSL::Malformed] if `AdapterJudge` finds `adapter` malformed
       def self.call_adapter(adapter)
-        judge_door(adapter, AdapterJudge, "#{adapter.name}'s adapter") do
-          JSON.generate([adapter.name, adapter.port, adapter.fields, adapter.secrets])
+        judge_artifact(adapter, AdapterJudge, "#{adapter.name}'s adapter") do
+          JSON.generate([adapter.name, adapter.port, adapter.fields, adapter.secrets, adapter.declared_defaults])
         end
       end
 
       # Judges `translation` through the meta-domain's own `TranslationJudge`
-      # door, walking every nested aggregate's own rule table in one pass.
+      # entry point, walking every nested aggregate's own rule table in one pass.
       #
       # `Translation` has no `.to_h`; `.inspect` embeds an object-id, so
       # structurally-identical translations never cache-hit here (a lost
@@ -88,10 +88,10 @@ module Hecks
       # @raise [DSL::Malformed] if `TranslationJudge` finds `translation`
       #   malformed
       def self.call_translation(translation)
-        judge_door(translation, TranslationJudge, "#{translation.domain}'s translation") { translation.inspect }
+        judge_artifact(translation, TranslationJudge, "#{translation.domain}'s translation") { translation.inspect }
       end
 
-      # The one door every artifact but a chapter goes through: skip while judging is off,
+      # The one entry point every artifact but a chapter goes through: skip while judging is off,
       # else judge once per distinct `key_text` and refuse a malformed artifact.
       #
       # @param subject [Object] the artifact to judge
@@ -100,7 +100,7 @@ module Hecks
       # @yieldreturn [String] the text whose SHA-256 digest keys the verdict
       # @return [Object] `subject` unchanged, if well formed or while judging is off
       # @raise [DSL::Malformed] if `judge` finds `subject` malformed
-      def self.judge_door(subject, judge, label)
+      def self.judge_artifact(subject, judge, label)
         return subject if disabled? || bootstrapping? || shadow_parsing?
 
         key = Digest::SHA256.hexdigest(yield)

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

@@ -0,0 +1,71 @@
+require_relative "../ask_resolution"
+
+module Hecks
+  module Bluebook
+    module ModelCheck
+      # The checks over `ask`: one that resolves to no declared port operation, a port trigger
+      # that should be an ask, and a declared ask no policy reaches.
+      module AskChecks
+        # @param bluebook [Bluebook::Chapter] the chapter the policy is declared in
+        # @param policy [Bluebook::Policy] the policy to check
+        # @return [Finding, nil] an error for an `ask` that names no declared ask (or an
+        #   ambiguous one), a warning for a `trigger` that names a port operation, else `nil`
+        def ask_finding(bluebook, policy)
+          return port_trigger_finding(bluebook, policy) unless policy.asks?
+
+          outcome = AskResolution.call(bluebook, policy)
+          return if outcome.resolved?
+
+          Finding.new(kind: :unresolved_ask, severity: :error, subject: policy.name, message: outcome.detail)
+        end
+
+        # A port operation no policy reaches, by `ask` or by a trigger that names it.
+        #
+        # @param bluebook [Bluebook::Chapter] the chapter whose aggregates declare the ports
+        # @return [Array<Finding>] one warning per outbound operation nothing asks
+        def unused_ask_findings(bluebook)
+          reached = reached_port_verbs(bluebook)
+          bluebook.aggregates.flat_map do |aggregate|
+            outbound_operations(aggregate).filter_map do |port, operation|
+              verb = "#{aggregate.hecks_name}.#{port.name}.#{operation.hecks_name}"
+              next if reached.include?(Naming.split_verb("#{bluebook.name}::#{verb}"))
+
+              Finding.new(kind: :unused_ask, severity: :warning, subject: verb,
+                          message: "the hecksagon declares this ask but no policy asks it")
+            end
+          end
+        end
+
+        private
+
+        def port_trigger_finding(bluebook, policy)
+          return unless port_operation_verb?(bluebook, policy.trigger_command)
+
+          Finding.new(kind: :port_trigger, severity: :warning, subject: policy.name,
+                      message: "trigger #{policy.trigger_command.inspect} names a port operation — " \
+                               "write `ask :#{Naming.snake(policy.trigger_command.to_s.split(".").last)}` and " \
+                               "let the hecksagon map the port")
+        end
+
+        def port_operation_verb?(bluebook, verb)
+          qualified = Naming.split_verb("#{bluebook.name}::#{verb}")
+          !qualified.nil? && port_verbs_of(bluebook).any? { |held| Naming.split_verb(held) == qualified }
+        end
+
+        def reached_port_verbs(bluebook)
+          from_policies = bluebook.policies.map { |policy| policy.trigger_command.to_s }
+          from_sagas = bluebook.process_managers.flat_map do |manager|
+            manager.handlers.flat_map { |handler| handler.dispatches.map(&:command_name) }
+          end
+          (from_policies + from_sagas).to_set { |verb| Naming.split_verb("#{bluebook.name}::#{verb}") }
+        end
+
+        def outbound_operations(aggregate)
+          aggregate.ports.flat_map do |port|
+            port.operations.select(&:outbound?).map { |operation| [port, operation] }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -11,7 +11,8 @@ module Hecks
 
           [
             deaf_policy_finding(policy, emitted_events(bluebook), global_emitted_events),
-            unknown_trigger_finding(bluebook, policy)
+            policy.asks? ? nil : unknown_trigger_finding(bluebook, policy),
+            ask_finding(bluebook, policy)
           ].compact
         end