hecks 6.0.0 → 7.0.0

data/lib/hecks/adapters/driving/mcp_scope/argument_policy.rb

@@ -13,17 +13,40 @@ module Hecks
           # Checks every argument in `args`, nested or not, and refuses the first one the policy
           # forbids.
           #
+          # Read-only questions whose `path` names one file of the checkout. `path` is denied by name
+          # for every other command, since it can name a place to write; these reads are allowed it,
+          # and admit_path! still confines it to the checkout.
+          READ_PATH_QUESTIONS = %w[codebase.read_source codebase.outline].freeze
+
+          # The line window those reads take: plain numbers that name no place, so they pass.
+          READ_WINDOW_ARGUMENTS = %w[from to top].freeze
+
+          # The boundary between a lower-case letter or digit and the upper-case letter after it.
+          CAMEL_BOUNDARY = /([a-z\d])([A-Z])/
+
           # @param args [Hash, Array, nil] the arguments as the caller gave them
           # @param label [String] how the server describes its mode, for the refusal
+          # @param question [String, nil] the query asked, when the arguments are a question's
           # @raise [Runtime::TypeMismatch] on the first argument refused
-          def admit!(args, label)
-            each_argument(args) do |name, value|
-              if DENIED_ARGUMENTS.include?(name)
-                refuse!(name, label, "never passes it on: it names a host, a binary, an output or a change of state")
-              end
-              admit_path!(name, value, label) if PATH_ARGUMENTS.include?(name)
-              admit_ref!(name, value, label) if REF_ARGUMENTS.include?(name)
+          def admit!(args, label, question = nil)
+            read_question = READ_PATH_QUESTIONS.include?(snake_question(question))
+            each_argument(args) { |name, value| admit_one!(name, value, label, read_question) }
+          end
+
+          # Whether an argument is a line window the read questions take, which names no place.
+          def window?(name, read_question) = read_question && READ_WINDOW_ARGUMENTS.include?(name)
+
+          # Checks one argument by its name: a read path is allowed its path, and anything else is
+          # refused, confined to the checkout, or checked as a ref.
+          def admit_one!(name, value, label, read_question)
+            return if window?(name, read_question)
+            return admit_path!(name, value, label) if name == "path" && read_question
+
+            if DENIED_ARGUMENTS.include?(name)
+              refuse!(name, label, "never passes it on: it names a host, a binary, an output or a change of state")
             end
+            admit_path!(name, value, label) if PATH_ARGUMENTS.include?(name)
+            admit_ref!(name, value, label) if REF_ARGUMENTS.include?(name)
           end
 
           # Yields every argument name with its value, descending into nested objects and lists, so
@@ -47,6 +70,16 @@ module Hecks
             value.fetch("value") { value.fetch(:value, value) }
           end
 
+          # The question as `Aggregate.query` or `aggregate_run.query` names it, in the snake form
+          # `READ_PATH_QUESTIONS` uses.
+          def snake_question(question)
+            parts = question.to_s.split(".")
+            parts.map { |part| snake_part(part) }.join(".")
+          end
+
+          # One part of a question name, in snake form: `ReadSource` is `read_source`.
+          def snake_part(part) = part.gsub(CAMEL_BOUNDARY, '\1_\2').downcase
+
           def refuse!(name, label, why)
             raise Runtime::TypeMismatch, "argument: #{name.inspect} is refused: this server runs in #{label} and #{why}"
           end

data/lib/hecks/adapters/driving/mcp_scope.rb

@@ -31,9 +31,9 @@ module Hecks
         # write, a port to open, a store to switch to, or flips a command from a preview to a
         # change of state.
         DENIED_ARGUMENTS = %w[
-          adapter artifact brief claimed confirm expected from gem_only header health_path host live no_wait npm_local
-          npm_only output path payload payload_file port prebuilt remote row rust_binary scheme stage_dir state_path
-          stdio url write
+          adapter artifact brief claimed confirm expected force from gem_only header health_path host live
+          no_wait npm_local npm_only output path payload payload_file port prebuilt remote row rust_binary
+          scheme stage_dir state_path stdio url write
         ].freeze
 
         # Argument names whose values are paths (a comma-separated list for some). A restricted
@@ -41,11 +41,11 @@ module Hecks
         # passes them on only when each resolves, symlinks followed, inside `Storehouse::BOOT_ROOT`,
         # and holds no colon: `host:repo` and `https://host/x` would otherwise pass as relative
         # paths.
-        PATH_ARGUMENTS = %w[checkout dir directory domain domains file fixture paths repo root script].freeze
+        PATH_ARGUMENTS = %w[checkout dir directory domain domains file files fixture paths repo root script].freeze
 
         # Argument names whose values are git refs: plain names only, so a value cannot read as an
         # option to git.
-        REF_ARGUMENTS = %w[branch commit onto ref].freeze
+        REF_ARGUMENTS = %w[base branch commit onto ref].freeze
 
         # What a plain git ref looks like: no leading dash, no `..`, no spaces.
         PLAIN_REF = %r{\A[A-Za-z0-9][A-Za-z0-9._/~^@-]*\z}
@@ -155,11 +155,12 @@ module Hecks
         # files should name it in `DENIED_ARGUMENTS` or `PATH_ARGUMENTS` (ADR 0089).
         #
         # @param args [Hash, Array, nil] the arguments as the caller gave them, nested or not
+        # @param question [String, nil] the query asked, when these are a question's arguments
         # @raise [Runtime::TypeMismatch] on the first argument refused
-        def admit_arguments!(args)
+        def admit_arguments!(args, question = nil)
           return unless restricted?
 
-          ArgumentPolicy.admit!(args, mode_label)
+          ArgumentPolicy.admit!(args, mode_label, question)
         end
 
         # The one domain a restricted server serves, when it serves exactly one: a call may leave

data/lib/hecks/adapters/driving/ruby/aggregate_module/hooks.rb

@@ -0,0 +1,154 @@
+module Hecks
+  module Adapters
+    module Driving
+      module Ruby
+        module AggregateModule
+          # The hooks an aggregate module lands on: a port declared inside a repeat boot, the bare and
+          # qualified binding calls a `.hecksagon` and a `.world` make, and constant lookup. Each is a
+          # module function, called as `Hooks.name` from the blocks that define the module's methods, since
+          # a block defined with `define_singleton_method` runs with the module as `self`.
+          module Hooks
+            # What `bound_outcome` answers for a call that is not a binding, so `super` handles it.
+            UNBOUND = Object.new.freeze
+
+            # What `bound_outcome` answers for a call that recorded a binding, so the module answers itself.
+            BOUND = Object.new.freeze
+
+            module_function
+
+            # Defines `port`, which declares a port on the aggregate during a repeat boot.
+            #
+            # @param mod [Module] the aggregate module
+            # @param domain [String] the domain the aggregate belongs to
+            # @param aggregate [Bluebook::Aggregate] the aggregate
+            # @param fqn [String] the aggregate's qualified name
+            # @return [void]
+            def define_port_hook(mod, domain, aggregate, fqn)
+              mod.define_singleton_method(:port) do |name, &block|
+                Hooks.attach_port(name, domain, aggregate, fqn, &block)
+                self
+              end
+            end
+
+            # Defines `ask_via`, the repeat-boot form of `BindingProxy#ask_via`.
+            #
+            # @param mod [Module] the aggregate module
+            # @param domain [String] the domain the aggregate belongs to
+            # @param aggregate [Bluebook::Aggregate] the aggregate
+            # @return [void]
+            def define_ask_via(mod, domain, aggregate)
+              mod.define_singleton_method(:ask_via) do |name, port:|
+                declaration = Hecks.current_registry&.bluebook(domain)
+                Bluebook::AskResolution.pick!(declaration, aggregate.hecks_name, name, port)
+                self
+              end
+            end
+
+            # Defines `method_missing`: a bare call starts a Privacy marking chain, and a qualified
+            # call records a binding. Anything else falls through to `super`.
+            #
+            # @param mod [Module] the aggregate module
+            # @param fqn [String] the aggregate's qualified name
+            # @return [void]
+            def define_method_missing(mod, fqn)
+              mod.define_singleton_method(:method_missing) do |verb, *args, **kwargs, &block|
+                outcome = Hooks.bound_outcome(fqn, verb, args, kwargs, block)
+                return super(verb, *args, **kwargs, &block) if outcome.equal?(Hooks::UNBOUND)
+
+                outcome.equal?(Hooks::BOUND) ? self : outcome
+              end
+            end
+
+            # Defines `respond_to_missing?`, answering true while a `.hecksagon` or `.world` is being declared.
+            #
+            # @param mod [Module] the aggregate module
+            # @return [void]
+            def define_respond_to_missing(mod)
+              mod.define_singleton_method(:respond_to_missing?) do |name, include_private = false|
+                !Bluebook::DSL::HecksagonBuilder.collector.nil? || !Bluebook::DSL::WorldBuilder.current.nil? ||
+                  super(name, include_private)
+              end
+            end
+
+            # Defines `const_missing`. It uses `aggregate.hecks_name`, not the qualified name: qualifying it
+            # would make `Account::Debit`'s meaning depend on whether a stale module from an earlier boot is
+            # still on this process.
+            #
+            # @param mod [Module] the aggregate module
+            # @param aggregate [Bluebook::Aggregate] the aggregate
+            # @return [void]
+            def define_const_missing(mod, aggregate)
+              mod.define_singleton_method(:const_missing) do |name|
+                resolver = Bluebook::DSL::ConstShim.resolver
+                return resolver.call("#{aggregate.hecks_name}::#{name}") if resolver
+
+                super(name)
+              end
+            end
+
+            # Declares a port on an aggregate during a repeat boot, and registers it with the live registry.
+            # Re-resolves the aggregate via `Hecks.current_registry` rather than the closed-over `aggregate`,
+            # which can be stale from an earlier boot.
+            #
+            # @raise [Bluebook::DSL::Malformed] when called outside a boot
+            def attach_port(name, domain, aggregate, fqn, &block)
+              current = current_aggregate(name, domain, aggregate, fqn)
+              built = Bluebook::DSL::ConstShim.with(->(const) { const }) do
+                Bluebook::DSL::DomainPortBuilder.build(name, owner: current.hecks_name, &block)
+              end
+              # A `verb`-shaped port is a plain `Port`, the same struct `Hecks.port` registers. It belongs to
+              # no aggregate IR, so it takes the registry's `add_port` directly. Mirrors `DSL::BindingProxy#port`,
+              # which handles the identical shape on a domain's first in-process boot.
+              return Hecks.current_registry.add_port(built) if built.is_a?(Bluebook::Port)
+
+              reference_operations(built, current)
+              current.add_port(built)
+            end
+
+            # @return [Bluebook::Aggregate] the live registry's copy of the aggregate
+            # @raise [Bluebook::DSL::Malformed] when no boot is in progress
+            def current_aggregate(name, domain, aggregate, fqn)
+              Hecks.current_registry&.bluebook(domain)&.aggregate(aggregate.hecks_name) or
+                raise Bluebook::DSL::Malformed, "#{fqn}.port(#{name.inspect}) called outside a boot"
+            end
+
+            # Points each reference attribute of a port's operations at the aggregate that declares it.
+            def reference_operations(built, current)
+              built.operations.each do |operation|
+                operation.attributes.select(&:reference?).each { |attribute| attribute.type.declared_in = current }
+              end
+            end
+
+            # Answers what a method-missing call means: a bare call's attribute path, the world's record of
+            # a setting, a recorded binding (BOUND), or nothing to bind (UNBOUND).
+            #
+            # @return [Object] the answer, or BOUND or UNBOUND
+            def bound_outcome(fqn, verb, args, kwargs, block)
+              return Bluebook::DSL::AttributePath.new(fqn, [verb.to_s]) if bare_call?(args, kwargs, block)
+
+              collector = Bluebook::DSL::HecksagonBuilder.collector
+              world = Bluebook::DSL::WorldBuilder.current
+              # Inside a `.world` block the same qualified spelling records a world setting.
+              return world.record_binding(verb, args, kwargs, block) if world && !collector
+              return UNBOUND unless collector
+
+              collector << bind_for(fqn, verb, args, kwargs)
+              block&.call
+              BOUND
+            end
+
+            # @return [Boolean] whether the call names no arguments and no block, so it is a bare attribute path
+            def bare_call?(args, kwargs, block)
+              args.empty? && kwargs.empty? && !block
+            end
+
+            # @return [Bluebook::Bind] the binding a qualified call declares
+            def bind_for(fqn, verb, args, kwargs)
+              Bluebook::Bind.new(aggregate: fqn, verb: verb.to_s, adapter: args.first.to_s, role: kwargs[:role]&.to_s)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driving/ruby/aggregate_module.rb

@@ -8,6 +8,7 @@ require_relative "../handle"
 require_relative "bulk_verbs"
 require_relative "query_rows"
 require_relative "../../../naming"
+require_relative "aggregate_module/hooks"
 
 module Hecks
   module Adapters
@@ -19,22 +20,48 @@ module Hecks
           # Builds one aggregate module: creating-command methods, query methods,
           # find/all/count/events, project/docs/narrate, and the port/binding hooks.
           #
-          # Kept as one method: `:port`/`:method_missing`/`:const_missing` below
-          # cross-reference each other and would lose that thread if split up.
-          # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+          # Each concern is a helper that defines its methods on the module and closes over the same
+          # arguments. The hooks live in `AggregateModule::Hooks`, which the module's blocks call by name.
           def aggregate_module(dispatcher, domain, aggregate)
             fqn = "#{domain}::#{aggregate.hecks_name}"
             mod = Module.new
 
+            warn_shadowed_attributes(aggregate)
+            define_surface(mod, dispatcher, domain, aggregate, fqn)
+            Hooks.define_port_hook(mod, domain, aggregate, fqn)
+            Hooks.define_ask_via(mod, domain, aggregate)
+            Hooks.define_method_missing(mod, fqn)
+            Hooks.define_respond_to_missing(mod)
+            Hooks.define_const_missing(mod, aggregate)
+            mod
+          end
+
+          private
+
+          # Warns for each attribute that shadows a built-in, since no reader is defined for it.
+          def warn_shadowed_attributes(aggregate)
             aggregate.attributes.each do |attribute|
               next unless RESERVED.include?(attribute.name.to_sym)
 
               warn "[hecks] #{aggregate.hecks_name}##{attribute.name} shadows a built-in — no reader defined"
             end
+          end
 
-            # `!` marks a creating command (Ruby's mutate-and-may-refuse convention).
-            # Without it, a query sharing the same business name (e.g. Account's
-            # "Open") would collide with the creating command's own bare name.
+          # The module's everyday surface: its commands, its identity, its projections, and its reads.
+          def define_surface(mod, dispatcher, domain, aggregate, fqn)
+            define_creating_commands(mod, dispatcher, domain, aggregate, fqn)
+            define_reflection(mod, dispatcher, domain, aggregate, fqn)
+            define_names(mod, aggregate)
+            define_projection(mod, aggregate)
+            define_narration(mod, dispatcher, domain, aggregate)
+            define_finders(mod, dispatcher, domain, aggregate)
+            define_tallies(mod, dispatcher, domain, aggregate, fqn)
+          end
+
+          # `!` marks a creating command (Ruby's mutate-and-may-refuse convention).
+          # Without it, a query sharing the same business name (e.g. Account's
+          # "Open") would collide with the creating command's own bare name.
+          def define_creating_commands(mod, dispatcher, domain, aggregate, fqn)
             aggregate.commands.select(&:creates?).each do |command|
               mod.define_singleton_method("#{Naming.snake(command.hecks_name)}!") do |**args|
                 Handle.new(dispatcher: dispatcher, domain: domain, aggregate: aggregate,
@@ -47,13 +74,27 @@ module Hecks
             # A query is a bare module method (no `!`): it reads and returns the raw rows
             # `dispatcher.query` answers, as `QueryRows` so a bulk run can name the query.
             BulkVerbs.define_queries(mod, dispatcher, fqn, aggregate)
+          end
+
+          # The module's own identity: its FQN, its IR, and its repository.
+          def define_reflection(mod, dispatcher, domain, aggregate, fqn)
+            mod.define_singleton_method(:fqn) { fqn }
+            mod.define_singleton_method(:ir)  { aggregate }
+            mod.define_singleton_method(:repository) { dispatcher.registry.repository(domain, aggregate) }
+          end
 
-            mod.define_singleton_method(:fqn)        { fqn }
-            mod.define_singleton_method(:ir)         { aggregate }
+          # The names of the aggregate's commands and queries.
+          def define_names(mod, aggregate)
+            mod.define_singleton_method(:commands) do
+              aggregate.commands.map { |c| "#{Naming.snake(c.hecks_name)}!" }.sort
+            end
+            mod.define_singleton_method(:queries) { aggregate.queries.map { |q| Naming.snake(q.hecks_name) }.sort }
+          end
 
-            # Every construct emits its own IR, so an aggregate is a legitimate
-            # `project` target too. A bluebook-scoped target refuses here via
-            # `Projector.admits!` rather than answering a confidently empty result.
+          # Every construct emits its own IR, so an aggregate is a legitimate
+          # `project` target too. A bluebook-scoped target refuses here via
+          # `Projector.admits!` rather than answering a confidently empty result.
+          def define_projection(mod, aggregate)
             mod.define_singleton_method(:project) do |target, out: nil, **options|
               key      = Projector.key_for(target)
               artifact = Projector.call(key, bluebook: aggregate, options: options)
@@ -61,24 +102,22 @@ module Hecks
 
               Projector.write(artifact, out, as: Projector.emits_for(key))
             end
-            mod.define_singleton_method(:repository) { dispatcher.registry.repository(domain, aggregate) }
-            mod.define_singleton_method(:commands) do
-              aggregate.commands.map { |c| "#{Naming.snake(c.hecks_name)}!" }.sort
-            end
-            mod.define_singleton_method(:queries) { aggregate.queries.map { |q| Naming.snake(q.hecks_name) }.sort }
-            # This bluebook's own `:docs` projection, narrowed to this aggregate.
+          end
+
+          # This bluebook's own `:docs` and `:narrate` projections, narrowed to this aggregate.
+          def define_narration(mod, dispatcher, domain, aggregate)
             mod.define_singleton_method(:docs) do |**options|
               Projector.call(:docs, bluebook: dispatcher.registry.bluebook(domain),
                                     options:  options.merge(aggregate: aggregate.hecks_name))
             end
-            # Same narrowing as `:docs`, aimed at `:narrate`.
             mod.define_singleton_method(:narrate) do |**options|
               Projector.call(:narrate, bluebook: dispatcher.registry.bluebook(domain),
                                        options:  options.merge(aggregate: aggregate.hecks_name))
             end
-            mod.define_singleton_method(:count)      { dispatcher.registry.repository(domain, aggregate).count }
-            mod.define_singleton_method(:events)     { dispatcher.events.select { |event| event.aggregate == fqn } }
+          end
 
+          # `find` and `all` read the aggregate's repository and wrap each instance in a handle.
+          def define_finders(mod, dispatcher, domain, aggregate)
             mod.define_singleton_method(:find) do |id|
               found = dispatcher.registry.repository(domain, aggregate).find(id)
               found && Handle.new(dispatcher: dispatcher, domain: domain, aggregate: aggregate, instance: found)
@@ -90,80 +129,12 @@ module Hecks
                 Handle.new(dispatcher: dispatcher, domain: domain, aggregate: aggregate, instance: instance)
               end
             end
+          end
 
-            # Re-resolves via `Hecks.current_registry` rather than the closed-over
-            # `aggregate`: this module can be stale from an earlier boot, and its own
-            # `aggregate` would silently port a discarded one instead of the live one.
-            mod.define_singleton_method(:port) do |name, &block|
-              current = Hecks.current_registry&.bluebook(domain)&.aggregate(aggregate.hecks_name) or
-                raise Bluebook::DSL::Malformed, "#{fqn}.port(#{name.inspect}) called outside a boot"
-
-              built = Bluebook::DSL::ConstShim.with(->(const) { const }) do
-                Bluebook::DSL::DomainPortBuilder.build(name, owner: current.hecks_name, &block)
-              end
-
-              # A `verb`-shaped port is a plain `Port`, the same struct `Hecks.port` registers —
-              # it belongs to no aggregate IR the way an operations-shaped `DomainPort` does, so
-              # it takes the registry's `add_port` directly. Mirrors `DSL::BindingProxy#port`,
-              # which handles the identical shape on a domain's first in-process boot (before
-              # this facade constant exists); this method is what a repeat boot reaches instead.
-              if built.is_a?(Bluebook::Port)
-                Hecks.current_registry.add_port(built)
-                return self
-              end
-
-              built.operations.each do |operation|
-                operation.attributes.select(&:reference?).each { |attribute| attribute.type.declared_in = current }
-              end
-              current.add_port(built)
-              self
-            end
-
-            # `BindingProxy#ask_via` for a repeat boot, when this module stands where the proxy is.
-            mod.define_singleton_method(:ask_via) do |name, port:|
-              declaration = Hecks.current_registry&.bluebook(domain)
-              Bluebook::AskResolution.pick!(declaration, aggregate.hecks_name, name, port)
-              self
-            end
-
-            mod.define_singleton_method(:method_missing) do |verb, *args, **kwargs, &block|
-              # A bare call starts a Privacy marking chain (see
-              # `BindingProxy#method_missing`), reached here when the module is already
-              # installed (a second in-process boot) rather than at parse time.
-              return Bluebook::DSL::AttributePath.new(fqn, [verb.to_s]) if args.empty? && kwargs.empty? && !block
-
-              collector = Bluebook::DSL::HecksagonBuilder.collector
-              world     = Bluebook::DSL::WorldBuilder.current
-              # Inside a `.world` block the same qualified spelling records a world setting.
-              return world.record_binding(verb, args, kwargs, block) if world && !collector
-              return super(verb, *args, **kwargs, &block) unless collector
-
-              collector << Bluebook::Bind.new(
-                aggregate: fqn,
-                verb:      verb.to_s,
-                adapter:   args.first.to_s,
-                role:      kwargs[:role]&.to_s
-              )
-              block&.call
-              self
-            end
-
-            mod.define_singleton_method(:respond_to_missing?) do |name, include_private = false|
-              !Bluebook::DSL::HecksagonBuilder.collector.nil? || !Bluebook::DSL::WorldBuilder.current.nil? ||
-                super(name, include_private)
-            end
-
-            # Uses `aggregate.hecks_name`, not the qualified `fqn`: qualifying it here
-            # would make `Account::Debit`'s meaning depend on whether a stale module
-            # from an earlier boot happens to be sitting on this process.
-            mod.define_singleton_method(:const_missing) do |name|
-              resolver = Bluebook::DSL::ConstShim.resolver
-              return resolver.call("#{aggregate.hecks_name}::#{name}") if resolver
-
-              super(name)
-            end
-
-            mod
+          # `count` and `events` read what the aggregate has stored and emitted.
+          def define_tallies(mod, dispatcher, domain, aggregate, fqn)
+            mod.define_singleton_method(:count)  { dispatcher.registry.repository(domain, aggregate).count }
+            mod.define_singleton_method(:events) { dispatcher.events.select { |event| event.aggregate == fqn } }
           end
         end
       end

data/lib/hecks/adapters/driving/usage_log.rb

@@ -0,0 +1,146 @@
+require "fileutils"
+require "json"
+require_relative "usage_cache"
+
+module Hecks
+  module Adapters
+    module Driving
+      # Keeps a local record of the commands and queries a launcher runs, so the everyday list and
+      # the timing of a deprecation rest on what people type rather than on a guess.
+      #
+      # A run appends one JSON line to `usage.jsonl` in the directory `UsageCache` already uses:
+      # the name as typed, the name it resolved to, the exit status, the duration in milliseconds
+      # and the date. No arguments, values or paths are written. The record is on unless
+      # `HECKS_USAGE=off` is set or a `usage.off` marker sits in that directory. The first run that
+      # writes prints one line on standard error saying so, then leaves a `usage.noticed` marker.
+      # Writing never fails the command it records.
+      module UsageLog
+        # The file each run appends its line to.
+        FILE = "usage.jsonl".freeze
+        # The variable that turns the record off when set to `off`.
+        OPT_OUT_VARIABLE = "HECKS_USAGE".freeze
+        # The marker file that turns the record off.
+        OPT_OUT_MARKER = "usage.off".freeze
+        # The marker file that says the first-run notice has been printed.
+        NOTICE_MARKER = "usage.noticed".freeze
+        # The line printed once, on the first run that writes.
+        NOTICE = "hecks keeps a local record of the commands it runs in %s; set HECKS_USAGE=off to stop.".freeze
+        # The window `summary` counts when none is given, in days.
+        DEFAULT_WINDOW = 30
+        # Seconds in a day.
+        DAY = 24 * 60 * 60
+
+        module_function
+
+        # Appends the line for one run, unless the record is off.
+        #
+        # @param argv [Array<String>] the command line as typed
+        # @param resolved [String, nil] the name the runner resolved it to
+        # @param status [Integer] the exit status the run answered
+        # @param started [Float] the monotonic clock reading when the run began
+        # @return [void]
+        def record(argv:, resolved:, status:, started:)
+          return unless enabled?
+
+          FileUtils.mkdir_p(directory)
+          notice
+          append(line(argv, resolved, status, started))
+        rescue StandardError
+          nil
+        end
+
+        # @return [Boolean] whether a run is recorded
+        def enabled?
+          ENV[OPT_OUT_VARIABLE].to_s != "off" && !File.exist?(marker(OPT_OUT_MARKER))
+        end
+
+        # Prints the first-run line once, then leaves its marker.
+        def notice
+          return if File.exist?(marker(NOTICE_MARKER))
+
+          warn(format(NOTICE, path))
+          FileUtils.touch(marker(NOTICE_MARKER))
+        end
+
+        # The entry for one run.
+        #
+        # @return [Hash] the fields `record` writes
+        def line(argv, resolved, status, started)
+          { "typed" => typed(argv), "resolved" => resolved, "status" => status,
+            "ms" => ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round,
+            "date" => Time.now.utc.strftime("%Y-%m-%d") }
+        end
+
+        # The name the person typed: the first word that is not a flag, past a `query` word.
+        #
+        # @return [String, nil]
+        def typed(argv)
+          words = argv.reject { |word| word.start_with?("-") }
+          words.shift if CliRunner::QUERY_WORDS.include?(words.first)
+          words.first
+        end
+
+        # Writes one entry as a line of the file.
+        def append(entry)
+          File.open(path, "a") { |file| file.puts(JSON.generate(entry)) }
+        end
+
+        # The entries on file, oldest first. A line that does not parse is skipped.
+        #
+        # @return [Array<Hash>]
+        def entries
+          File.readlines(path).filter_map { |line| JSON.parse(line) }
+        rescue SystemCallError, JSON::ParserError
+          []
+        end
+
+        # Counts the runs in the window and names the known ones that did not run in it.
+        #
+        # @param known [Array<String>] every name the launcher answers to, as the projection names
+        #   them
+        # @param window [Integer] how many days back a run counts
+        # @return [String] the text `hecks usage` prints
+        def summary(known:, window: DEFAULT_WINDOW)
+          counts = counts_since(window)
+          unrun = known.sort - counts.keys
+          ["runs in the last #{window} days, most used first:", *tally_lines(counts),
+           "", "never run in that window:", *unrun.map { |name| "  #{name}" }].join("\n")
+        end
+
+        # How often each resolved name ran since the window opened.
+        #
+        # @return [Hash{String => Integer}]
+        def counts_since(window)
+          since = (Time.now.utc - (window * DAY)).strftime("%Y-%m-%d")
+          resolved_names(entries.select { |entry| entry["date"].to_s >= since })
+        end
+
+        # @return [Hash{String => Integer}] how many runs resolved to each name
+        def resolved_names(runs)
+          runs.map { |entry| entry["resolved"] }.compact.tally
+        end
+
+        # @return [Array<String>] one line per name that ran, most used first
+        def tally_lines(counts)
+          ranked = counts.sort_by { |name, count| [-count, name] }
+          ranked.map { |name, count| format("  %<count>4d  %<name>s", count: count, name: name) }
+        end
+
+        # @return [String] the file the record lives in
+        def path
+          File.join(directory, FILE)
+        end
+
+        # @return [String] the directory the record lives in: the usage cache's own
+        def directory
+          UsageCache.directory
+        end
+
+        # @return [String] a marker file in the directory
+        def marker(name)
+          File.join(directory, name)
+        end
+      end
+    end
+  end
+end