hecks 3.2.1 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b963870a34a1483bc0156042a2967a72f8fc1b8e907ba5d8cac5a5382d4999d
-  data.tar.gz: 26697af02778cda282a44c1ca099e36a9866bf2d204ab5abb23df8ac2a86283a
+  metadata.gz: 288ec2962d96e6d9772c6fd6155d15461f69259cd7f69e107e308a2710fcb668
+  data.tar.gz: e71d1ec056df32604dc6ef8de8cab5069ae998faa74d89acd377d79b217820ed
 SHA512:
-  metadata.gz: a81b0ffb4b0e04024518169e3c6dd51a3f55b5da39659a852c2a0c9528453fe0eb9facf07d7b18bd35d7924c5a08331b2f1ad82a7e5c4c43c61fae55490d46ed
-  data.tar.gz: f6780cb0c58069a5049081c7a319424787c9fea1fd94a5085153d7b99533c0e1974c23dfeb3515b66f3b2d8d3c7ca83a08dcd5f024df02da2b2fc9609c3ba6b7
+  metadata.gz: a2586bb29d327f576976c7573236abfde1f60deba2eec7529b13ea34fc1b4ea917abe996fd44076cb76690835fb7089f4d18f38d0693d0aa14da2a106334a1a7
+  data.tar.gz: 1101c11307086a6df1833e6cd7b4fb5fdaa5b0d265b0a4569fa9d4df5d85f27039975f46135dd90619ad69e50d553172eb82d203633177595503f9bbfb67998a

data/lib/hecks/bluebook/assembly/contracts.rb

@@ -101,6 +101,7 @@ module Hecks
             order_by:       [:order_by,        :order_by],
             limit:          [:limit,           :limit],
             returns:        [:returns,         :plain],
+            needs:          [:needs,           [:each, :need]],
             # Held by the language as an open map, so every one of these reads the
             # same way and a ninth option needs no new field on either side.
             offset:         [:offset,          [:option, :offset]],
@@ -111,7 +112,7 @@ module Hecks
           },
           rows: { wheres: :where_rows, options: :option_rows },
           reads: { attributes: [:each, :shape_field], wheres: [:each, :where_clause],
-                  order_by: [:call, :order_by], limit: [:call, :limit] },
+                  needs: [:each, :need], order_by: [:call, :order_by], limit: [:call, :limit] },
           derived: {
             position:    :walk,
             order_field: [:folded, :order_by, :field],

data/lib/hecks/bluebook/dsl/bootstrap_table.rb

@@ -75,6 +75,7 @@ module Hecks
           ["Query", "where"] => :where_impl,
           ["Query", "order_by"] => :order_by_impl,
           ["Query", "authorize"] => :authorize_impl,
+          ["Query", "needs"] => :needs_impl,
           ["ValueObject", "attribute"] => :attribute_impl,
           ["ValueObject", "one_of"] => :one_of_impl,
           ["ValueObject", "invariant"] => :invariant_impl,

data/lib/hecks/bluebook/dsl/command_builder.rb

@@ -1,4 +1,5 @@
 require_relative "word_gate"
+require_relative "need_word"
 module Hecks
   module Bluebook
     module DSL
@@ -10,6 +11,7 @@ module Hecks
         include AttributeCollector
         include RuleReference
         include WordGate
+        include NeedWord
 
         # Sentinel for "this keyword was never passed" — distinct from Ruby's own
         # nil/false, so `to: false` doesn't get treated as absent.
@@ -67,31 +69,6 @@ module Hecks
         # @return [String] the description as stored
         def goal(value) = @goal = value
 
-        # The outside facts a command may declare it needs, each the name of the attribute the
-        # runtime fills when the caller leaves it out. `now` is the clock port's answer, in epoch
-        # seconds.
-        NEEDABLE_FACTS = %i[now].freeze
-
-        # Declares an outside fact the runtime supplies before any given runs (ADR 0081):
-        # `needs :now` fills the command's own `now` attribute from the clock port when the caller
-        # names none.
-        #
-        # @param fact [Symbol] one of `NEEDABLE_FACTS`
-        # @return [Array<Symbol>] the facts declared so far
-        # @raise [Bluebook::DSL::Malformed] if the fact is not one the runtime can supply, or is
-        #   declared twice
-        def needs_impl(fact)
-          fact = fact.to_sym
-          unless NEEDABLE_FACTS.include?(fact)
-            raise Malformed,
-                  "#{@name} needs :#{fact}, which the runtime cannot supply — it supplies " \
-                  "#{NEEDABLE_FACTS.map { |known| ":#{known}" }.join(', ')}"
-          end
-          raise Malformed, "#{@name} declares needs :#{fact} twice" if @needs.include?(fact)
-
-          @needs << fact
-        end
-
         # Names where a concept adopted from a canonical source came from.
         #
         # @param from [Object] the canonical source, captured exactly as written
@@ -344,20 +321,6 @@ module Hecks
           )
         end
 
-        # A fact is filled into the argument of the same name, so the command declares one.
-        #
-        # @raise [Bluebook::DSL::Malformed] if a needed fact has no attribute to fill
-        def refuse_undeclared_needs!
-          declared = attributes.map { |attribute| attribute.name.to_s }
-          missing  = @needs.reject { |fact| declared.include?(fact.to_s) }
-          return if missing.empty?
-
-          raise Malformed,
-                "#{@name} needs :#{missing.first} but declares no attribute :#{missing.first} " \
-                "for the runtime to fill — add `attribute :#{missing.first}, <type>`"
-        end
-        private :refuse_undeclared_needs!
-
         # Evaluates a `command` block against a fresh builder and returns what it built.
         #
         # @param name [String] the command's name

data/lib/hecks/bluebook/dsl/hecksagon_builder.rb

@@ -59,7 +59,7 @@ module Hecks
 
         # The release that drops the deprecated spellings of `attaches`; independent of
         # `Hecks::Doors::REMOVAL`, which covers the older `Facade` aliases.
-        REMOVAL = "3.3.0".freeze
+        REMOVAL = "3.4.0".freeze
 
         attr_reader :binds, :subscriptions, :attachments
 

data/lib/hecks/bluebook/dsl/need_word.rb

@@ -0,0 +1,50 @@
+module Hecks
+  module Bluebook
+    module DSL
+      # The `needs` word, shared by the builders of the two declarations that may use it: a
+      # command and a query (ADR 0081). The including builder holds `@name` and `@needs` (an
+      # empty list) and answers `attributes`.
+      module NeedWord
+        # The outside facts a declaration may need, each the name of the attribute the runtime
+        # fills when the caller leaves it out. `now` is the clock port's reading in epoch seconds;
+        # `today` is the day it falls in, whole days since the epoch in UTC.
+        NEEDABLE_FACTS = %i[now today].freeze
+
+        # Declares an outside fact the runtime supplies before any given or filter runs:
+        # `needs :now` fills the declaration's own `now` attribute from the clock port when the
+        # caller names none.
+        #
+        # @param fact [Symbol] one of `NEEDABLE_FACTS`
+        # @return [Array<Symbol>] the facts declared so far
+        # @raise [Bluebook::DSL::Malformed] if the fact is not one the runtime can supply, or is
+        #   declared twice
+        def needs_impl(fact)
+          fact = fact.to_sym
+          unless NEEDABLE_FACTS.include?(fact)
+            raise Malformed,
+                  "#{@name} needs :#{fact}, which the runtime cannot supply — it supplies " \
+                  "#{NEEDABLE_FACTS.map { |known| ":#{known}" }.join(', ')}"
+          end
+          raise Malformed, "#{@name} declares needs :#{fact} twice" if @needs.include?(fact)
+
+          @needs << fact
+        end
+
+        private
+
+        # A fact is filled into the argument of the same name, so the declaration has one.
+        #
+        # @raise [Bluebook::DSL::Malformed] if a needed fact has no attribute to fill
+        def refuse_undeclared_needs!
+          declared = attributes.map { |attribute| attribute.name.to_s }
+          missing  = @needs.reject { |fact| declared.include?(fact.to_s) }
+          return if missing.empty?
+
+          raise Malformed,
+                "#{@name} needs :#{missing.first} but declares no attribute :#{missing.first} " \
+                "for the runtime to fill — add `attribute :#{missing.first}, <type>`"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/dsl/query_builder.rb

@@ -1,4 +1,5 @@
 require_relative "word_gate"
+require_relative "need_word"
 module Hecks
   module Bluebook
     module DSL
@@ -14,11 +15,13 @@ module Hecks
         include AttributeCollector
         include QuerySpecification::Common::DSL
         include WordGate
+        include NeedWord
 
         # @param name [String] the query's name, as written after `query`
         def initialize(name)
           @name   = name
           @wheres = []
+          @needs  = []
         end
 
         # Sets the human-readable description shown for this query.
@@ -75,6 +78,7 @@ module Hecks
         #   implements
         def build
           seal_cursor
+          refuse_undeclared_needs!
           Query.new(
             name:           @name,
             description:    @description,
@@ -87,7 +91,8 @@ module Hecks
             authorization:  @authorization,
             null_semantics: @null_semantics,
             inspection:     @inspection,
-            returns:        @returns
+            returns:        @returns,
+            needs:          @needs
           )
         end
 

data/lib/hecks/bluebook/query.rb

@@ -25,14 +25,14 @@ module Hecks
         limit:       one(:limit)
       )
 
-      attr_reader :name, :description, :attributes, :returns
+      attr_reader :name, :description, :attributes, :returns, :needs
 
       # @param null_semantics [QuerySpecification::Common::NullSemantics, nil] defaults to
       #   `NullSemantics.default`
       def initialize(name:, description: nil, attributes: [], wheres: [],
                      order_by: nil, limit: nil, offset: nil, cursor: nil,
                      authorization: nil, null_semantics: nil,
-                     inspection: nil, returns: nil)
+                     inspection: nil, returns: nil, needs: [])
         null_semantics ||= QuerySpecification::Common::NullSemantics.default
         super(wheres: wheres, order_by: order_by, limit: limit, offset: offset, cursor: cursor,
               authorization: authorization,
@@ -42,6 +42,7 @@ module Hecks
         @description = description
         @attributes  = attributes
         @returns     = returns&.to_s
+        @needs       = needs
       end
 
       # The value object a `returns` names, without the `list_of(...)` wrapper.
@@ -55,13 +56,15 @@ module Hecks
       def returns_list? = !@returns.nil? && @returns.start_with?("list_of(")
 
       # `extra_options_to_h` (count, median, group_by, scope_to) stays dynamic; `super` covers the
-      # declared emission. `returns` follows, only when the query declares one, so a query that
-      # returns nothing keeps its wire shape.
+      # declared emission. `returns` and `needs` follow, only when the query declares them, so a
+      # query that returns nothing and needs nothing keeps its wire shape.
       #
       # @return [Hash] the declared emission merged with `extra_options_to_h`, then `returns`
+      #   and `needs`
       def to_h
         shape = super.merge(extra_options_to_h)
-        @returns ? shape.merge(returns: @returns) : shape
+        shape = shape.merge(returns: @returns) if @returns
+        @needs.empty? ? shape : shape.merge(needs: @needs.map { |fact| { fact: fact.to_s } })
       end
     end
   end

data/lib/hecks/cli/interview_draft.rb

@@ -1,5 +1,6 @@
 require_relative "../naming"
 require_relative "domain_stub"
+require_relative "interview_shape"
 
 module Hecks
   module CLI
@@ -20,7 +21,11 @@ module Hecks
 
       # 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
-      private_constant :PATTERN, :STUB_NOTE
+
+      # 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
 
       module_function
 
@@ -65,14 +70,21 @@ module Hecks
       #
       # @param interview [Object] the booted record
       # @return [Hash] the plain interview this module takes: `reference`, `subject`, `expert`,
-      #   `exchanges` (`question`, `answer`, `topic`), and `things`, `actions` and `rules`, each a
-      #   finding with its `number`, `source` and `status` and the fields of its kind
+      #   `exchanges` (`question`, `answer`, `topic`), and `things`, `actions`, `rules`,
+      #   `fields` and `transitions`, each a finding with its `number`, `source` and `status`
+      #   and the fields of its kind
       def from_record(interview)
         { reference: plain(interview.reference), subject: plain(interview.subject), expert: plain(interview.expert),
           exchanges: interview.exchanges.map { |ex| slice(ex, :question, :answer, :topic) },
           things:    interview.thing_findings.map { |f| slice(f, :number, :name, :identifier, :source, :status) },
-          actions:   interview.action_findings.map { |f| slice(f, :number, :name, :thing, :event, :creates, :source, :status) },
-          rules:     interview.rule_findings.map { |f| slice(f, :number, :statement, :source, :status) } }
+          actions:   interview.action_findings.map do |f|
+            slice(f, :number, :name, :thing, :event, :creates, :takes, :by, :source, :status)
+          end,
+          rules:     interview.rule_findings.map { |f| slice(f, :number, :statement, :source, :status) },
+          fields:    interview.field_findings.map { |f| slice(f, :number, :thing, :name, :values, :source, :status) },
+          transitions: interview.transition_findings.map do |f|
+            slice(f, :number, :thing, :action, :to, :from, :source, :status)
+          end }
       end
 
       # @api private
@@ -127,24 +139,48 @@ module Hecks
 
       # @api private
       def aggregate(interview, thing, actions)
+        shape = shape_of(interview, thing, actions)
+        lines = head_lines(interview, thing, shape)
+        lines.concat(command_lines(interview, shape))
+        lines.concat(InterviewShape.lifecycle(shape.steps, shape.creating, shape.rest))
+        (lines << "  end").join("\n")
+      end
+
+      # What one accepted thing is made of: its fields, its actions, and its steps.
+      # @api private
+      def shape_of(interview, thing, actions)
         name = word(thing[:name])
-        field = Naming.snake(word(thing[:identifier]))
-        field_type = identifier_type(name, field)
+        identifier = Naming.snake(word(thing[:identifier]))
         mine = actions.select { |a| word(a[:thing]) == name }
+        steps = accepted(interview, :transitions).select { |s| word(s[:thing]) == name }
+        found = accepted(interview, :fields).select { |f| word(f[:thing]) == name }
+        type = identifier_type(name, identifier)
+        fields = InterviewShape.fields(found, name, identifier, type, lifecycle: !steps.empty?)
         creating = mine.select { |a| a[:creates] }
-        rest = mine - creating
-        lines = ["  # #{source_note(interview, thing)}".rstrip,
-                 "  aggregate #{name.inspect} do",
-                 "    description #{"TODO: describe what a #{name} is.".inspect}", "",
-                 "    identified_by :#{field}", "",
-                 "    attribute :#{field}, #{field_type}", "",
-                 "    value_object #{field_type.inspect} do",
-                 "      attribute :value, String, pattern: #{PATTERN}",
-                 "    end"]
-        creating = [stub_create(name)] if creating.empty?
-        creating.each { |action| lines.concat(creating_command(interview, action, field, field_type)) }
-        rest.each { |action| lines.concat(mutating_command(interview, action, name)) }
-        (lines << "  end").join("\n")
+        Shape.new(name: name, identifier: identifier, type: type, fields: fields, steps: steps,
+                  creating: creating, rest: mine - creating)
+      end
+
+      # The aggregate's opening: its identity, its fields, and the value object of each.
+      # @api private
+      def head_lines(interview, thing, shape)
+        required = shape.creating.flat_map { |action| InterviewShape.takes(action) }
+        ["  # #{source_note(interview, thing)}".rstrip,
+         "  aggregate #{shape.name.inspect} do",
+         "    description #{"TODO: describe what a #{shape.name} is.".inspect}", "",
+         "    identified_by :#{shape.identifier}", "",
+         "    attribute :#{shape.identifier}, #{shape.type}",
+         *InterviewShape.attributes(shape.fields, required), "",
+         "    value_object #{shape.type.inspect} do",
+         "      attribute :value, String, pattern: #{PATTERN}", "    end",
+         *InterviewShape.value_objects(shape.fields)]
+      end
+
+      # @api private
+      def command_lines(interview, shape)
+        creating = shape.creating.empty? ? [stub_create(shape.name)] : shape.creating
+        creating.flat_map { |action| creating_command(interview, action, shape) } +
+          shape.rest.flat_map { |action| mutating_command(interview, action, shape) }
       end
 
       # The creating command nothing in the interview named: a stub, marked for the developer.
@@ -152,19 +188,24 @@ module Hecks
       def stub_create(name) = { name: "Create", event: "#{name}Created", stub: true }
 
       # @api private
-      def creating_command(interview, action, field, field_type)
+      def creating_command(interview, action, shape)
         verb = word(action[:name])
         note = action[:stub] ? STUB_NOTE : "    # #{source_note(interview, action)}"
-        ["", note, "    command #{verb.inspect} do", "      goal #{"TODO: say what #{verb} does".inspect}", "",
-         "      attribute :#{field}, #{field_type}", "", "      emits #{word(action[:event]).inspect}", "    end"]
+        given, unknown = InterviewShape.inputs(action, shape.fields, shape.identifier)
+        ["", note, "    command #{verb.inspect} do", "      goal #{"TODO: say what #{verb} does".inspect}",
+         *InterviewShape.who_lines(action), "", "      attribute :#{shape.identifier}, #{shape.type}",
+         *given.map { |f| "      attribute :#{f[:name]}, #{f[:type]}" }, *InterviewShape.unknown_lines(unknown), "",
+         "      emits #{word(action[:event]).inspect}", "    end"]
       end
 
       # @api private
-      def mutating_command(interview, action, name)
+      def mutating_command(interview, action, shape)
         verb = word(action[:name])
+        given, unknown = InterviewShape.inputs(action, shape.fields, shape.identifier)
         ["", "    # #{source_note(interview, action)}", "    command #{verb.inspect} do",
-         "      goal #{"TODO: say what #{verb} does".inspect}", "", "      reference_to #{name}", "",
-         "      emits #{word(action[:event]).inspect}", "    end"]
+         "      goal #{"TODO: say what #{verb} does".inspect}", *InterviewShape.who_lines(action), "",
+         "      reference_to #{shape.name}", *InterviewShape.input_lines(given), *InterviewShape.unknown_lines(unknown),
+         *InterviewShape.assignment_lines(given), "", "      emits #{word(action[:event]).inspect}", "    end"]
       end
 
       # An action whose thing nobody accepted has nowhere to go; it is kept as a comment, not lost.
@@ -196,10 +237,15 @@ module Hecks
         lines = interview.fetch(:things).map do |f|
           "- Thing #{f[:number]}, #{f[:status]}: **#{f[:name]}**, identified by `#{f[:identifier]}` (exchange #{f[:source]})"
         end
-        lines += interview.fetch(:actions).map do |f|
-          creates = f[:creates] ? ", creates it" : ""
-          "- Action #{f[:number]}, #{f[:status]}: **#{f[:name]}** on #{f[:thing]}, " \
-            "announcing `#{f[:event]}`#{creates} (exchange #{f[:source]})"
+        lines += interview.fetch(:actions).map { |f| action_line(f) }
+        lines += interview.fetch(:fields, []).map do |f|
+          values = f[:values].to_s.strip.empty? ? "" : ", one of #{f[:values]}"
+          "- Field #{f[:number]}, #{f[:status]}: **#{f[:name]}** on #{f[:thing]}#{values} (exchange #{f[:source]})"
+        end
+        lines += interview.fetch(:transitions, []).map do |f|
+          from = f[:from].to_s.strip.empty? ? "" : " from #{f[:from]}"
+          "- Transition #{f[:number]}, #{f[:status]}: **#{f[:action]}** on #{f[:thing]} to #{f[:to]}#{from} " \
+            "(exchange #{f[:source]})"
         end
         lines + interview.fetch(:rules).map do |f|
           "- Rule #{f[:number]}, #{f[:status]}: #{one_line(f[:statement])} (exchange #{f[:source]})"
@@ -207,7 +253,16 @@ module Hecks
       end
 
       # @api private
-      def accepted(interview, kind) = interview.fetch(kind).select { |finding| finding[:status] == ACCEPTED }
+      def action_line(finding)
+        creates = finding[:creates] ? ", creates it" : ""
+        takes = finding[:takes].to_s.strip.empty? ? "" : ", takes #{finding[:takes]}"
+        by = finding[:by].to_s.strip.empty? ? "" : ", by #{finding[:by]}"
+        "- Action #{finding[:number]}, #{finding[:status]}: **#{finding[:name]}** on #{finding[:thing]}, " \
+          "announcing `#{finding[:event]}`#{creates}#{takes}#{by} (exchange #{finding[:source]})"
+      end
+
+      # @api private
+      def accepted(interview, kind) = interview.fetch(kind, []).select { |finding| finding[:status] == ACCEPTED }
 
       # A free-text name as a PascalCase word safe to write into Ruby: `lend a book` is `LendABook`.
       # @api private

data/lib/hecks/cli/interview_session.rb

@@ -24,36 +24,59 @@ module Hecks
 
       TASK = "You interview a subject matter expert, through the developer who sits beside them, about the " \
              "business domain called %<subject>s, so the developer can model it. Ask one plain-language " \
-             "question at a time about what the business keeps track of, what happens to it, and what must " \
-             "never happen. Use the expert's own words. Do not assume what kind of business it is, or an " \
+             "question at a time about what the business keeps track of, what each thing has, what happens to " \
+             "it and who does it, how it moves from one state to the next, and what must never happen. Use the " \
+             "expert's own words. Do not assume what kind of business it is, or an " \
              "industry, from the name of the domain: learn it from what the expert says. When you interpret " \
              "an answer, propose findings only with the verbs listed under `verbs`, using the argument " \
              "names given there, and nothing else.".freeze
 
       VERBS = {
-        "SME::Interview.ProposeThing"  => {
+        "SME::Interview.ProposeThing"      => {
           "meaning"   => "a thing the business keeps track of, and the field that identifies one of it",
           "arguments" => %w[name identifier]
         },
-        "SME::Interview.ProposeAction" => {
-          "meaning"   => "something that happens to a thing, and the event it announces, in the past tense",
-          "arguments" => %w[name thing event creates]
+        "SME::Interview.ProposeAction"     => {
+          "meaning"   => "something that happens to a thing, and the event it announces, in the past tense; " \
+                         "creates is true for the action that brings the thing into being; takes lists, comma " \
+                         "separated, the fields it needs to be told; by says who does it",
+          "arguments" => %w[name thing event creates takes by]
         },
-        "SME::Interview.ProposeRule"   => {
+        "SME::Interview.ProposeField"      => {
+          "meaning"   => "something a thing has; values lists, comma separated, what it may be when the " \
+                         "expert gave a closed set, and is left out for free text",
+          "arguments" => %w[thing name values]
+        },
+        "SME::Interview.ProposeTransition" => {
+          "meaning"   => "the state an action leaves a thing in, and the state it had to be in before; the " \
+                         "action that creates the thing has no from",
+          "arguments" => %w[thing action to from]
+        },
+        "SME::Interview.ProposeRule"       => {
           "meaning"   => "a rule the expert stated, in their own words",
           "arguments" => %w[statement]
         }
       }.freeze
 
-      # What each finding verb needs, and the SME commands that carry it out and decide it.
+      # What each finding verb needs, the fields it may leave out, and the SME commands that
+      # carry it out and decide it.
       KINDS = {
-        "SME::Interview.ProposeThing"  => { kind: "thing", fields: %w[name identifier], propose: :propose_thing!,
-                                           entity: "ThingFinding", accept: "AcceptThing", reject: "RejectThing" },
-        "SME::Interview.ProposeAction" => { kind: "action", fields: %w[name thing event creates],
-                                            propose: :propose_action!, entity: "ActionFinding",
-                                            accept: "AcceptAction", reject: "RejectAction" },
-        "SME::Interview.ProposeRule"   => { kind: "rule", fields: %w[statement], propose: :propose_rule!,
-                                          entity: "RuleFinding", accept: "AcceptRule", reject: "RejectRule" }
+        "SME::Interview.ProposeThing"      => { kind: "thing", fields: %w[name identifier], optional: [],
+                                           propose: :propose_thing!, entity: "ThingFinding",
+                                           accept: "AcceptThing", reject: "RejectThing" },
+        "SME::Interview.ProposeAction"     => { kind: "action", fields: %w[name thing event creates takes by],
+                                            optional: %w[creates takes by], propose: :propose_action!,
+                                            entity: "ActionFinding", accept: "AcceptAction", reject: "RejectAction" },
+        "SME::Interview.ProposeRule"       => { kind: "rule", fields: %w[statement], optional: [],
+                                          propose: :propose_rule!, entity: "RuleFinding",
+                                          accept: "AcceptRule", reject: "RejectRule" },
+        "SME::Interview.ProposeField"      => { kind: "field", fields: %w[thing name values], optional: %w[values],
+                                          propose: :propose_field!, entity: "FieldFinding",
+                                          accept: "AcceptField", reject: "RejectField" },
+        "SME::Interview.ProposeTransition" => { kind: "transition", fields: %w[thing action to from],
+                                                optional: %w[from], propose: :propose_transition!,
+                                                entity: "TransitionFinding", accept: "AcceptTransition",
+                                                reject: "RejectTransition" }
       }.freeze
 
       TRUE_WORDS = %w[true yes y 1].freeze
@@ -153,7 +176,7 @@ module Hecks
         return say("Ignored a proposal for #{proposal.verb}: not a finding I know.") unless config
 
         fields = fields_of(proposal, config)
-        missing = config[:fields].reject { |f| f == "creates" || fields[f].to_s.strip != "" }
+        missing = config[:fields].reject { |f| config[:optional].include?(f) || fields[f].to_s.strip != "" }
         return say("Ignored a #{config[:kind]} proposal with no #{missing.join(', ')}.") unless missing.empty?
 
         number = propose(config, fields) or return
@@ -166,7 +189,7 @@ module Hecks
         rows = proposal.arguments.to_h { |row| [row[:name].to_s, row[:value]] }
         fields = rows.slice(*config[:fields])
         fields["creates"] = TRUE_WORDS.include?(fields["creates"].to_s.downcase) if fields.key?("creates")
-        fields
+        fields.reject { |key, value| key != "creates" && config[:optional].include?(key) && value.to_s.strip.empty? }
       end
 
       def propose(config, fields)
@@ -192,19 +215,27 @@ module Hecks
         case config[:kind]
         when "thing" then "thing: #{fields['name']}, identified by #{fields['identifier']}"
         when "action" then "action: #{fields['name']} on #{fields['thing']}, announcing #{fields['event']}" \
-                           "#{', creating it' if fields['creates']}"
+                           "#{', creating it' if fields['creates']}#{action_extras(fields)}"
+        when "field" then "field: #{fields['name']} of #{fields['thing']}#{", one of #{fields['values']}" if fields['values']}"
+        when "transition" then "transition: #{fields['action']} leaves #{fields['thing']} #{fields['to']}" \
+                               "#{", from #{fields['from']}" if fields['from']}"
         else "rule: #{fields['statement']}"
         end
       end
 
+      # @api private
+      def action_extras(fields)
+        "#{", taking #{fields['takes']}" if fields['takes']}#{", by #{fields['by']}" if fields['by']}"
+      end
+
       # The plain prompt: findings typed by the developer, accepted as they are entered.
       def manual_findings
         loop do
-          kind = ask("Add a finding from that answer? thing, action or rule (enter to skip): ")
+          kind = ask("Add a finding from that answer? thing, action, rule, field or transition (enter to skip): ")
           kind = kind.to_s.strip.downcase
           break if kind.empty?
 
-          typed = typed_finding(kind) or next say("  I only know thing, action and rule.")
+          typed = typed_finding(kind) or next say("  I only know thing, action, rule, field and transition.")
           config = KINDS["SME::Interview.Propose#{kind.capitalize}"]
           number = propose(config, typed) or next
           decide(config, number, true)
@@ -216,6 +247,11 @@ module Hecks
         when "thing" then named("Name" => "name", "Identified by" => "identifier")
         when "action" then typed_action
         when "rule" then named("The rule, in the expert's words" => "statement")
+        when "field" then named({ "On which thing" => "thing", "Name" => "name",
+                                  "Values it may take, comma separated (enter for any)" => "values" }, %w[values])
+        when "transition" then named({ "On which thing" => "thing", "Caused by which action" => "action",
+                                       "Leaves it in the state" => "to",
+                                       "From the state (enter if it starts there)" => "from" }, %w[from])
         end
       end
 
@@ -224,9 +260,11 @@ module Hecks
         fields.merge("creates" => TRUE_WORDS.include?(ask("  Does it create the thing? [y/N] ").to_s.strip.downcase))
       end
 
-      def named(prompts)
+      def named(prompts, optional = [])
         fields = prompts.to_h { |label, key| [key, ask("  #{label}: ").to_s.strip] }
-        fields.values.all? { |v| !v.empty? } ? fields : nil
+        return nil unless fields.all? { |key, value| optional.include?(key) || !value.empty? }
+
+        fields.reject { |key, value| optional.include?(key) && value.empty? }
       end
 
       def suggest_enough
@@ -271,9 +309,11 @@ module Hecks
       end
 
       def accepted_state(plain)
-        { things:  InterviewDraft.accepted(plain, :things).map { |f| f.slice(:name, :identifier) },
-          actions: InterviewDraft.accepted(plain, :actions).map { |f| f.slice(:name, :thing, :event, :creates) },
-          rules:   InterviewDraft.accepted(plain, :rules).map { |f| f.slice(:statement) } }
+        { things:      InterviewDraft.accepted(plain, :things).map { |f| f.slice(:name, :identifier) },
+          actions:     InterviewDraft.accepted(plain, :actions).map { |f| f.slice(:name, :thing, :event, :creates, :takes, :by) },
+          fields:      InterviewDraft.accepted(plain, :fields).map { |f| f.slice(:thing, :name, :values) },
+          transitions: InterviewDraft.accepted(plain, :transitions).map { |f| f.slice(:thing, :action, :to, :from) },
+          rules:       InterviewDraft.accepted(plain, :rules).map { |f| f.slice(:statement) } }
       end
 
       # What the interview has not yet pinned down, in words a model can act on.
@@ -283,7 +323,18 @@ module Hecks
         gaps = things.reject { |t| actions.any? { |a| a[:thing] == t } }.map { |t| "nothing is yet said to happen to #{t}" }
         gaps += things.reject { |t| actions.any? { |a| a[:thing] == t && a[:creates] } }.map { |t| "nothing yet creates #{t}" }
         unplaced = actions.reject { |a| things.include?(a[:thing].to_s) }
-        gaps + unplaced.map { |a| "#{a[:name]} names #{a[:thing]}, not yet a thing" }
+        gaps + unplaced.map { |a| "#{a[:name]} names #{a[:thing]}, not yet a thing" } + shape_gaps(plain, things, actions)
+      end
+
+      # What a thing is not yet said to have, and how it moves from one state to the next.
+      def shape_gaps(plain, things, actions)
+        fields = InterviewDraft.accepted(plain, :fields)
+        steps = InterviewDraft.accepted(plain, :transitions)
+        bare = things.reject { |t| fields.any? { |f| f[:thing] == t } }
+        gaps = bare.map { |t| "nothing is yet said #{t} has, beyond its identifier" }
+        changing = things.select { |t| actions.count { |a| a[:thing] == t && !a[:creates] } > 1 }
+        unmoved = changing.reject { |t| steps.any? { |s| s[:thing] == t } }
+        gaps + unmoved.map { |t| "nothing yet says how #{t} moves from one state to the next" }
       end
 
       def reason(error) = error.message.sub(/\A[A-Z]\w* refused\s+[—-]\s+/, "").strip