hecks 3.13.0 → 4.0.0

data/lib/hecks/bluebook/meta_validator.rb

@@ -203,17 +203,6 @@ module Hecks
         registry
       end
 
-      # Whether `grammar_registry`'s memoized singleton has finished its
-      # fixpoint judge and attached-chapter load.
-      #
-      # A cache keyed on "finished" instead of its own inputs already missed
-      # data for a whole build window once.
-      #
-      # @return [Boolean]
-      def self.grammar_registry_ready?
-        @grammar_registry && @grammar_ready_for == @grammar_registry.object_id
-      end
-
       # Loads every `ATTACHED_GRAMMAR_DIR` chapter file into `registry`,
       # judged the ordinary way since the fixpoint has already run.
       #

data/lib/hecks/bluebook/named_pattern.rb

@@ -0,0 +1,33 @@
+module Hecks
+  module Bluebook
+    # The patterns a bluebook names instead of spelling: `matches: :snake_name` says what
+    # `pattern: '^[a-z][a-z0-9_]*$'` does. A name stands for exactly its regex, so the IR, the
+    # generated Rust and the runtime check see the pattern and never the name.
+    #
+    # `rust/parser/src/build/named_pattern.rs` holds the same table; spec/named_pattern_spec.rb
+    # holds the two to each other.
+    module NamedPattern
+      # Name => the regex source it stands for, each the exact source the corpus spelled by hand.
+      TABLE = {
+        present:       '[^ \t\n\r]',
+        not_empty:     '[^\t\n\r]',
+        no_whitespace: '^[^ \t\n\r]+$',
+        snake_name:    "^[a-z][a-z0-9_]*$",
+        git_sha:       "^[0-9a-fA-F]{7,40}$",
+        digits:        "^[0-9]+$"
+      }.freeze
+
+      module_function
+
+      # @param name [Symbol, String] a name in `TABLE`
+      # @return [String] the regex source it stands for
+      # @raise [ArgumentError] when the name is not one the language gives
+      def source(name)
+        TABLE.fetch(name.to_sym) do
+          raise ArgumentError, "matches: #{name.inspect} is not a named pattern — " \
+                               "the names are #{TABLE.keys.map(&:inspect).join(", ")}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/translation.rb

@@ -16,13 +16,16 @@ module Hecks
     # The attribute kept its name, so `rename`/`move` cannot express it.
     TranslationRetype = Struct.new(:from, :to)
 
-    # A computed transform whose only implementation is a SQL expression run inside
-    # the compiled Postgres head; an aggregate carrying one refuses to boot elsewhere.
-    TranslationCompute = Struct.new(:from, :to, :sql)
+    # A new field computed from the record's own text by an expression, read before any other
+    # rule runs. The fields the expression reads stay where they are; `drop` removes them.
+    # `expression` is the source text and `tree` its parsed plan form.
+    TranslationDerive = Struct.new(:to, :expression) do
+      def tree = TranslationExpression.parse(expression)
+    end
 
-    # The aggregate's own key is recomputed by a SQL expression; stored state is untouched.
-    # Postgres-only like `compute`, and it has no `from:`/`to:` path.
-    TranslationRekey = Struct.new(:sql)
+    # The aggregate's id is the value of the field a `derive` writes, for every record where that
+    # derive has a value; a record where it has none keeps its id.
+    TranslationRekey = Struct.new(:to)
 
     # A newly added, required attribute with no source in old data.
     # `default` is what an existing record reads until a command writes a real value;
@@ -32,12 +35,12 @@ module Hecks
     # One aggregate's part of a translation between eras.
     # `drops` makes data loss a declared decision.
     class TranslationAggregate
-      attr_reader :name, :was, :renames, :moves, :converts, :drops, :retypes, :computes, :rekeys, :backfills
+      attr_reader :name, :was, :renames, :moves, :converts, :drops, :retypes, :derives, :rekeys, :backfills
 
       # Every optional field and what it holds when the declaration omits it.
       FIELD_DEFAULTS = {
         was: nil, renames: {}, moves: [], converts: [], drops: [], retypes: [],
-        computes: [], rekeys: [], backfills: []
+        derives: [], rekeys: [], backfills: []
       }.freeze
 
       # @param name [String, Symbol] the aggregate's name in the destination era
@@ -47,8 +50,8 @@ module Hecks
       # @param converts [Array<Bluebook::TranslationConvert>] fields remapped via a lookup table
       # @param drops [Array<Symbol>] fields deliberately not carried forward
       # @param retypes [Array<Bluebook::TranslationRetype>] value object or entity type changes
-      # @param computes [Array<Bluebook::TranslationCompute>] fields computed by Postgres-only SQL
-      # @param rekeys [Array<Bluebook::TranslationRekey>] SQL recomputing the aggregate's identity
+      # @param derives [Array<Bluebook::TranslationDerive>] fields computed from the record's text
+      # @param rekeys [Array<Bluebook::TranslationRekey>] the aggregate's identity, recomputed
       # @param backfills [Array<Bluebook::TranslationBackfill>] new required fields, no old source
       def initialize(name:, **given)
         KeywordFields.assign(self, KeywordFields.fill(given, FIELD_DEFAULTS))
@@ -83,6 +86,11 @@ module Hecks
       # @return [Bluebook::TranslationAggregate, nil] the aggregate's translation, or
       #   `nil` if `name` carries no translation rules
       def for_aggregate(name) = @aggregates.find { |aggregate| aggregate.name == name.to_s }
+
+      # This edge as plain data: each aggregate's rules as an ordered list of ops.
+      #
+      # @return [Hash] see `Bluebook::TranslationPlan`
+      def to_plan = TranslationPlan.build(self)
     end
   end
 end

data/lib/hecks/bluebook/translation_expression/evaluator.rb

@@ -0,0 +1,63 @@
+module Hecks
+  module Bluebook
+    module TranslationExpression
+      # Computes a parsed expression for one record's state. The reference semantics the
+      # compiled Postgres form is held to.
+      module Evaluator
+        module_function
+
+        # @param tree [Array] a tree `TranslationExpression.parse` returned
+        # @param state [Hash] the record's stored state
+        # @return [String, nil] the computed text; nil when the expression has no value
+        def call(tree, state)
+          case tree.first
+          when "lit" then tree[1]
+          when "null" then nil
+          when "ref" then reference(tree[1], state)
+          else apply(tree.first, tree.drop(1), state)
+          end
+        end
+
+        # Reads a dotted path out of a record; only text counts as a value.
+        def reference(path, state)
+          value = path.split(".").inject(state) { |held, key| held.is_a?(Hash) ? member(held, key) : nil }
+          value.is_a?(String) ? value : nil
+        end
+
+        # A record's top-level keys are symbols, a value object's are strings.
+        def member(hash, key) = hash.key?(key.to_sym) ? hash[key.to_sym] : hash[key]
+
+        def apply(name, arguments, state)
+          return lookup(arguments, state) if name == "lookup"
+          return replace(arguments, state) if name == "replace"
+
+          values = arguments.map { |argument| call(argument, state) }
+          return nil if values.any?(&:nil?)
+
+          fold(name, values)
+        end
+
+        def fold(name, values)
+          case name
+          when "lower" then values.first.downcase(:ascii)
+          when "upper" then values.first.upcase(:ascii)
+          else values.join
+          end
+        end
+
+        def replace(arguments, state)
+          target, from, to = arguments
+          call(target, state)&.gsub(from.last) { to.last }
+        end
+
+        def lookup(arguments, state)
+          key, table, fallback = arguments
+          value = call(key, state)
+          return nil if value.nil?
+
+          table.fetch(value) { call(fallback, state) }
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/translation_expression/parser.rb

@@ -0,0 +1,127 @@
+require "json"
+require "strscan"
+
+module Hecks
+  module Bluebook
+    module TranslationExpression
+      # Reads the text of an expression into its tree, refusing anything outside the language.
+      class Parser
+        NAME   = /[a-z_][a-z0-9_]*(?:\.[a-z_][a-z0-9_]*)*/
+        STRING = /"(?:[^"\\]|\\.)*"/
+
+        # @param text [String] the expression's source text
+        def initialize(text)
+          @text = text.to_s
+          @scan = StringScanner.new(@text)
+        end
+
+        # @return [Array] the expression tree
+        # @raise [TranslationExpression::Refused] if the text is not a well-formed expression
+        def call
+          tree = expression
+          skip
+          refuse("unexpected #{@scan.rest[0, 12].inspect} after the expression") unless @scan.eos?
+          tree
+        end
+
+        private
+
+        def expression
+          skip
+          return ["lit", string] if @scan.check(/"/)
+
+          name = @scan.scan(NAME) || refuse("expected a field, a string or a function")
+          return function(name) if @scan.check(/\s*\(/)
+
+          name == "null" ? ["null"] : ["ref", name]
+        end
+
+        def function(name)
+          refuse("#{name} is not a function (#{FUNCTIONS.keys.join(", ")})") unless FUNCTIONS.key?(name)
+          punct("(")
+          arguments = list { argument(name, _1) }
+          punct(")")
+          check_arguments(name, arguments)
+          [name, *arguments]
+        end
+
+        def argument(name, index)
+          skip
+          return table if name == "lookup" && index == 1
+
+          expression
+        end
+
+        def list
+          items = []
+          loop do
+            items << yield(items.size)
+            skip
+            break unless @scan.skip(/,/)
+          end
+          items
+        end
+
+        def table
+          punct("{")
+          pairs = list { pair }
+          punct("}")
+          refuse("a lookup table repeats a key") unless pairs.map(&:first).uniq.size == pairs.size
+          pairs.to_h
+        end
+
+        def pair
+          skip
+          key = string
+          punct(":")
+          skip
+          [key, string]
+        end
+
+        def string
+          token = @scan.scan(STRING) || refuse("expected a string")
+          JSON.parse(token, quirks_mode: true)
+        rescue JSON::ParserError
+          refuse("#{token} is not a well-formed string")
+        end
+
+        def punct(mark)
+          skip
+          @scan.skip(Regexp.new(Regexp.escape(mark))) || refuse("expected #{mark.inspect}")
+        end
+
+        def skip = @scan.skip(/\s+/)
+
+        def check_arguments(name, arguments)
+          arity = FUNCTIONS.fetch(name)
+          refuse("#{name} takes #{arity} expressions, not #{arguments.size}") if arity && arguments.size != arity
+          refuse("concat takes two or more expressions") if arity.nil? && arguments.size < 2
+          check_literals(name, arguments)
+        end
+
+        def check_literals(name, arguments)
+          case name
+          when "replace" then check_replace(arguments)
+          when "lookup" then check_lookup(arguments)
+          end
+        end
+
+        def check_replace(arguments)
+          _target, from, to = arguments
+          refuse("replace needs string literals for what to find and what to put") unless [from, to].all? { _1.first == "lit" }
+          refuse("replace cannot look for an empty string") if from.last.empty?
+        end
+
+        def check_lookup(arguments)
+          _key, table, fallback = arguments
+          refuse("lookup needs a table of at least one pair") unless table.is_a?(Hash) && !table.empty?
+          refuse("lookup needs a string literal or null as its fallback") unless %w[lit null].include?(fallback.first)
+        end
+
+        def refuse(why)
+          raise Refused, "#{why} (in #{@text.inspect} at offset #{@scan.pos})"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/translation_expression.rb

@@ -0,0 +1,39 @@
+require_relative "translation_expression/parser"
+require_relative "translation_expression/evaluator"
+
+module Hecks
+  module Bluebook
+    # The expression a `derive` rule computes a new field from: text functions over the record's
+    # stored text, with no storage engine in sight. It parses to a tree of plain arrays, which
+    # is also its plan form:
+    #
+    #   ["ref", "name.value"]  ["lit", "text"]  ["null"]
+    #   ["lower", x]  ["upper", x]  ["concat", x, y, ...]
+    #   ["replace", x, ["lit", from], ["lit", to]]
+    #   ["lookup", x, {"key" => "value"}, ["lit", default] | ["null"]]
+    #
+    # A reference that is missing or not text has no value, and a function with a valueless
+    # argument has none either.
+    module TranslationExpression
+      # Raised when the text of an expression is not one the language accepts.
+      class Refused < StandardError; end
+
+      # The functions and how many expressions each takes; `nil` means "two or more".
+      FUNCTIONS = { "lower" => 1, "upper" => 1, "concat" => nil, "replace" => 3, "lookup" => 3 }.freeze
+
+      # Parses an expression's text into its tree.
+      #
+      # @param text [String] the expression, e.g. `lower(name.value)`
+      # @return [Array] the expression tree
+      # @raise [Refused] if the text is not a well-formed expression
+      def self.parse(text) = Parser.new(text).call
+
+      # Computes an expression's value for one record's state.
+      #
+      # @param tree [Array] a tree `parse` returned
+      # @param state [Hash] the record's stored state
+      # @return [String, nil] the text it computes; nil when it has no value
+      def self.evaluate(tree, state) = Evaluator.call(tree, state)
+    end
+  end
+end

data/lib/hecks/bluebook/translation_plan.rb

@@ -0,0 +1,70 @@
+module Hecks
+  module Bluebook
+    # A translation as data: each aggregate's rules as an ordered list of ops any runtime can
+    # interpret, with nothing in them that names a storage engine. In the order they apply to a
+    # record, each op has its name under "op" plus:
+    #
+    #   derive "to" "expression" (a tree)   rename "from" "to"   move "from" "to" (dotted paths)
+    #   convert "from" "to" "values" ([old, new] pairs)   drop "path"   retype "from" "to"
+    #   backfill "path" "default"   rekey_to "to"
+    module TranslationPlan
+      VERSION = 1
+
+      # The op names, in the order they apply; one per rule list of a `TranslationAggregate`.
+      OPS = %w[derive rename move convert drop retype backfill rekey_to].freeze
+
+      module_function
+
+      # @param translation [Bluebook::Translation] a declared translation edge
+      # @return [Hash] the edge as plain data, ready for `JSON.generate`
+      def build(translation)
+        {
+          "version" => VERSION, "domain" => translation.domain, "from" => translation.from.to_s,
+          "to" => translation.to.to_s, "retired" => translation.retired.map(&:to_s),
+          "aggregates" => translation.aggregates.map { |aggregate| aggregate_plan(aggregate) }
+        }
+      end
+
+      def aggregate_plan(aggregate)
+        { "name" => aggregate.name, "was" => aggregate.was, "ops" => ops(aggregate) }
+      end
+
+      def ops(aggregate)
+        [*derives(aggregate), *renames(aggregate), *moves(aggregate), *converts(aggregate), *drops(aggregate),
+         *retypes(aggregate), *backfills(aggregate), *rekeys(aggregate)]
+      end
+
+      def derives(aggregate)
+        aggregate.derives.map { |d| { "op" => "derive", "to" => d.to, "expression" => d.tree } }
+      end
+
+      def renames(aggregate)
+        aggregate.renames.map { |from, to| { "op" => "rename", "from" => from.to_s, "to" => to.to_s } }
+      end
+
+      def moves(aggregate)
+        aggregate.moves.map { |m| { "op" => "move", "from" => m.from, "to" => m.to } }
+      end
+
+      def converts(aggregate)
+        aggregate.converts.map do |c|
+          { "op" => "convert", "from" => c.from, "to" => c.to, "values" => c.values.map { |old, new| [old, new] } }
+        end
+      end
+
+      def drops(aggregate) = aggregate.drops.map { |path| { "op" => "drop", "path" => path.to_s } }
+
+      def retypes(aggregate)
+        aggregate.retypes.map { |r| { "op" => "retype", "from" => r.from, "to" => r.to } }
+      end
+
+      def backfills(aggregate)
+        aggregate.backfills.map { |b| { "op" => "backfill", "path" => b.name.to_s, "default" => b.default } }
+      end
+
+      def rekeys(aggregate)
+        aggregate.rekeys.map { |rekey| { "op" => "rekey_to", "to" => rekey.to } }
+      end
+    end
+  end
+end

data/lib/hecks/bluebook.rb

@@ -29,7 +29,9 @@ require_relative "bluebook/ask_resolution"
 require_relative "bluebook/process_manager"
 require_relative "bluebook/aggregate"
 require_relative "bluebook/hecksagon"
+require_relative "bluebook/translation_expression"
 require_relative "bluebook/translation"
+require_relative "bluebook/translation_plan"
 
 require_relative "bluebook/assembly/contract"
 require_relative "bluebook/assembly/contracts"
@@ -44,6 +46,7 @@ require_relative "bluebook/project_loader"
 
 require_relative "bluebook/dsl"
 require_relative "bluebook/pattern_subset"
+require_relative "bluebook/named_pattern"
 
 require_relative "bluebook/meta_validator"
 require_relative "bluebook/meta_validator/plan"

data/lib/hecks/chapters.rb

@@ -5,8 +5,8 @@ require_relative "bluebook/meta_validator"
 
 module Hecks
   # The chapters the gem carries that a hecksagon can attach by name (ADR 0080): the language
-  # declared in itself, Expression, Tenancy, Deploy, Site, Tickets and QualityControl. Framework
-  # members stay in `Framework`; `table` and `attach!` find a name across both.
+  # declared in itself, Expression, Tenancy, Deploy, Site, Tickets, Composer and QualityControl.
+  # Framework members stay in `Framework`; `table` and `attach!` find a name across both.
   #
   # A chapter is named by the `Hecks.bluebook "Name"` header of its files, and may span several.
   # Beside its bluebook a chapter may carry what every hecksagon attaching it needs, whatever
@@ -16,7 +16,7 @@ module Hecks
     # Where attachable chapters live, relative to `lib/hecks/`.
     GLOBS = %w[language/**/*.bluebook grammar/expression.bluebook tenancy/bluebook/*.bluebook
                deploy/bluebook/*.bluebook site/bluebook/*.bluebook tickets/bluebook/*.bluebook
-               quality_control/*.bluebook].freeze
+               composer/bluebook/*.bluebook quality_control/*.bluebook].freeze
 
     # Every attachable chapter, by name, with the files that declare it.
     #

data/lib/hecks/cli/domain_stub.rb

@@ -96,7 +96,7 @@ module Hecks
               attribute :name, ExampleName
 
               value_object "ExampleName" do
-                attribute :value, String, pattern: '[^ \\t\\n\\r]'
+                attribute :value, String, matches: :present
               end
 
               # TODO: replace Create with the first thing that happens to an Example.

data/lib/hecks/cli/interview_aggregate.rb

@@ -6,8 +6,8 @@ module Hecks
     # The bluebook text of one accepted thing: its aggregate, with its value objects, commands and
     # lifecycle. `InterviewDraft` extends it, and supplies the naming and citing helpers it calls.
     module InterviewAggregate
-      # The pattern every generated string field carries: it refuses a blank value.
-      PATTERN = %q('[^ \t\n\r]').freeze
+      # The option every generated string field carries: it refuses a blank value.
+      PRESENT = "matches: :present".freeze
 
       # What stands in for a creating command nothing in the interview named.
       STUB_NOTE = "    # TODO: no action that creates was accepted; replace Create with the real one.".freeze
@@ -15,7 +15,7 @@ module Hecks
       # One accepted thing: what it is called and identified by, its fields, its transitions, the
       # actions that create it and the others.
       Shape = Struct.new(:name, :identifier, :type, :fields, :steps, :creating, :rest, keyword_init: true)
-      private_constant :PATTERN, :STUB_NOTE, :Shape
+      private_constant :PRESENT, :STUB_NOTE, :Shape
 
       # @api private
       def aggregate(interview, thing, actions)
@@ -66,7 +66,7 @@ module Hecks
       # @api private
       def type_lines(shape)
         ["    value_object #{shape.type.inspect} do",
-         "      attribute :value, String, pattern: #{PATTERN}", "    end",
+         "      attribute :value, String, #{PRESENT}", "    end",
          *InterviewShape.value_objects(shape.fields)]
       end
 

data/lib/hecks/composer/adapters/claude_composer.adapter

@@ -0,0 +1,3 @@
+Hecks.adapter "ClaudeComposer" do
+  port "composer_agent"
+end

data/lib/hecks/composer/adapters/claude_composer.rb

@@ -0,0 +1,83 @@
+require "json"
+require "open3"
+require "timeout"
+
+require_relative "../agent"
+require_relative "jev"
+
+module Hecks
+  module Adapters
+    # Real `composer_agent` fulfillment for `draft` and `wire`: the developer's own `claude` run
+    # as the `hecks-composer` agent, which edits the workspace's files in place. Transport only;
+    # whether the edit is any good is the Composer's own check to judge.
+    #
+    # The agent's write guard confines it to domain files inside the git checkout, so the
+    # workspace must sit inside one.
+    module ClaudeComposer
+      TIMEOUT_SECONDS = 300
+
+      AGENT = "hecks-composer".freeze
+
+      DRAFT = "Edit the domain files in %<dir>s as the request below says. Change only what it asks " \
+              "for, write the bluebook first, then any hecksagon wiring it needs. Reply with one line " \
+              "saying what you changed.".freeze
+
+      WIRE = "Change how the chapter in %<dir>s is wired, as the request below says: edit only its " \
+             ".hecksagon and .world files, and bind adapters that already exist. Reply with one line " \
+             "saying what you changed.".freeze
+
+      module_function
+
+      # @param prompt [String] what the author asked for
+      # @param dir [String] the workspace directory
+      # @return [Hash] `"note"` the agent's account of what it changed
+      # @raise [Ports::Agent::Unavailable] see {Composer::Agent::Unavailable}
+      def draft(prompt:, dir:) = call(DRAFT, prompt, dir)
+
+      # @param prompt [String] what the author asked for
+      # @param dir [String] the workspace directory
+      # @return [Hash] `"note"` the agent's account of what it changed
+      def wire(prompt:, dir:) = call(WIRE, prompt, dir)
+
+      # Naming what a prompt asks for is the `jev` categorizer's work, which this adapter lends.
+      #
+      # @param prompt [String] what the author typed
+      # @return [Hash] `"intent"` one of {Composer::Agent::INTENTS}
+      # @raise [Composer::Agent::Unavailable] if `jev` cannot answer
+      def classify(prompt:) = Jev.classify(prompt: prompt)
+
+      # @api private
+      def call(task, prompt, dir)
+        root = checkout_of(dir)
+        message = "#{format(task, dir: dir)}\n\nRequest: #{prompt}"
+        stdout, status = run(root, message)
+        raise Composer::Agent::Unavailable, "claude exited #{status.exitstatus}: #{stdout}" unless status.success?
+
+        { "note" => JSON.parse(stdout).fetch("result").to_s.lines.first.to_s.strip }
+      rescue JSON::ParserError, KeyError => e
+        raise Composer::Agent::ValidationError, "claude's reply was not the expected envelope: #{e.message}"
+      end
+
+      # Argv spawn, never a shell, so a `claude` shell alias cannot apply.
+      # @api private
+      def run(root, message)
+        Timeout.timeout(TIMEOUT_SECONDS) do
+          Open3.capture2("claude", "-p", "--agent", AGENT, "--output-format", "json",
+                         "--permission-mode", "acceptEdits", stdin_data: message, chdir: root)
+        end
+      rescue Timeout::Error
+        raise Composer::Agent::Unavailable, "claude did not answer within #{TIMEOUT_SECONDS}s"
+      rescue Errno::ENOENT => e
+        raise Composer::Agent::Unavailable, "claude is not on PATH: #{e.message}"
+      end
+
+      # @api private
+      def checkout_of(dir)
+        top, status = Open3.capture2("git", "-C", dir, "rev-parse", "--show-toplevel")
+        raise Composer::Agent::Unavailable, "#{dir} is not inside a git checkout" unless status.success?
+
+        top.strip
+      end
+    end
+  end
+end

data/lib/hecks/composer/adapters/fake_agent.adapter

@@ -0,0 +1,3 @@
+Hecks.adapter "FakeAgent" do
+  port "composer_agent"
+end

data/lib/hecks/composer/adapters/fake_agent.rb

@@ -0,0 +1,55 @@
+require_relative "../agent"
+
+module Hecks
+  module Adapters
+    # A scripted `composer_agent`, for specs and for trying the editor with no model behind it.
+    # Each ask is recorded; `draft` and `wire` run a script that may rewrite the workspace's files,
+    # so a test sees the same thing the real agent leaves behind.
+    module FakeAgent
+      class << self
+        # @return [Array<Hash>] every ask, as `{ask:, prompt:, dir:}` in the order made
+        def calls = @calls ||= []
+
+        # @return [#call, nil] takes `(prompt, dir)` and edits files under `dir`; may return a note
+        attr_accessor :edit
+
+        # @return [#call, nil] takes `prompt` and answers an intent
+        attr_accessor :intent
+
+        # Forgets the calls and both scripts.
+        # @return [void]
+        def reset!
+          @calls = []
+          @edit = nil
+          @intent = nil
+        end
+      end
+
+      module_function
+
+      # @param prompt [String] what the author asked for
+      # @param dir [String] the workspace directory
+      # @return [Hash] `"note"` what the script reported
+      def draft(prompt:, dir:) = edited(:draft, prompt, dir)
+
+      # @param prompt [String] what the author asked for
+      # @param dir [String] the workspace directory
+      # @return [Hash] `"note"` what the script reported
+      def wire(prompt:, dir:) = edited(:wire, prompt, dir)
+
+      # @param prompt [String] what the author typed
+      # @return [Hash] `"intent"` what the script answered, `"edit"` without one
+      def classify(prompt:)
+        FakeAgent.calls << { ask: :classify, prompt: prompt, dir: nil }
+        { "intent" => FakeAgent.intent ? FakeAgent.intent.call(prompt) : "edit" }
+      end
+
+      # @api private
+      def edited(ask, prompt, dir)
+        FakeAgent.calls << { ask: ask, prompt: prompt, dir: dir }
+        note = FakeAgent.edit&.call(prompt, dir)
+        { "note" => note.is_a?(String) ? note : "changed nothing" }
+      end
+    end
+  end
+end

data/lib/hecks/composer/adapters/jev.adapter

@@ -0,0 +1,3 @@
+Hecks.adapter "Jev" do
+  port "composer_agent"
+end