hecks 3.4.1 → 3.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b47e9f61f073e7c8512365b3bb5112f4e214c26cec46e08a323c6f02c509d555
-  data.tar.gz: d84b642199556cc1b9bbcbc6635c2e248f3f4b63232bb0ca6abee589f85661ca
+  metadata.gz: 1d33b33e869c53f5b2c5825c2c9ec8a1a4a2b6dd6fad676b3e9403f314f4bf33
+  data.tar.gz: bc9b6f6509c6e31f6708254ba98e3d2346238ea6d487f25897a1ae5dac2968f0
 SHA512:
-  metadata.gz: e2280fdb747d6d8a299bd58f4ab261e71a0d977ed805e9fcfe86ae108cc248724c96960614b9af6796d4617ef9102be1343107a91c6044123a97f298ba6002f1
-  data.tar.gz: 6558a4e9698ca6e01a665ab3d9aa435da6990e20a69ef06b0c0cd91bc0edcedc771a976dc664c4501d56883ebca1435adb534d3516a20d8fd55dca3c90ff40ff
+  metadata.gz: c53a6ea1c22f5f87116d1a9cf7f432a402cabeb1b2f8c7a9d199bc7e1adfc46bcb0f3d391435138f1d20423e10d1047fba5d673fc9d00087d36b44fa5218e956
+  data.tar.gz: a9945ea4ddb39bfb0876eecf5d2b699c34f77e565333b60435fe626d492b9befedbd0fc7aaa81c91b6c48cd74ace82d884e482a535697cd0c256eafd896ef924

data/lib/hecks/adapters/driven/memory/shared_elements.rb

@@ -9,9 +9,12 @@ module Hecks
       # Lets a Memory save of a growing `list_of` copy and hydrate only the elements it has not
       # seen. A hydrated composite element is frozen, so its codec copy (the journal form) and
       # its hydrated form are each computed once, frozen, and shared by every journal entry and
-      # record that holds it. Shared nodes are immutable, so a caller cannot reach the journal
-      # through a returned instance. Everything else in the state goes through `StateCodec`
-      # whole. Both tables are weak and identity-keyed: a cache, never the only holder.
+      # record that holds it. A single value-object attribute that holds a list, directly or
+      # through a nested value object, shares the same way: the hydrated `Runtime::Value` is
+      # copied once, and a later version of it reuses the copies of the list elements it still
+      # holds. Shared nodes are immutable, so a caller cannot reach the journal through a
+      # returned instance. Everything else in the state goes through `StateCodec` whole. The
+      # tables are weak and identity-keyed: a cache, never the only holder.
       class SharedElements
         # @param aggregate [Bluebook::Aggregate] the aggregate whose state this shares elements of
         def initialize(aggregate)
@@ -25,6 +28,7 @@ module Hecks
         def reset!
           @journal = ObjectSpace::WeakMap.new   # live element => frozen decoded copy
           @live    = ObjectSpace::WeakMap.new   # frozen decoded copy => hydrated element
+          @copies  = ObjectSpace::WeakMap.new   # frozen value-object copy this table built => true
           self
         end
 
@@ -36,11 +40,13 @@ module Hecks
         #   are frozen and shared with every other copy that holds them, nothing else is shared
         #   with `state`
         def journal_state(state)
-          lists = shareable_lists(state)
-          return Ports::Persistence::StateCodec.copy(@aggregate, state) if lists.empty?
+          lists  = shareable_lists(state)
+          values = journal_values(state)
+          return Ports::Persistence::StateCodec.copy(@aggregate, state) if lists.empty? && values.empty?
 
-          copied = Ports::Persistence::StateCodec.copy(@aggregate, placeholders(state, lists))
+          copied = Ports::Persistence::StateCodec.copy(@aggregate, placeholders(state, lists, values))
           lists.each { |name, (attribute, elements)| copied[name] = journal_list(attribute, elements) }
+          values.each { |name, (attribute, value)| copied[name] = journal_value(attribute, value) }
           copied
         end
 
@@ -48,12 +54,14 @@ module Hecks
         #
         # @param decoded [Hash] a fresh state in the shape `journal_state` returns; its non-shared
         #   values are hydrated in place of copies, so it must not be a journal entry's own state
-        # @return [Hash{Symbol => Object}] hydrated state, defaults filled; the lists it shares
-        #   are frozen arrays of frozen elements, and nothing mutable is shared with `decoded`
+        # @return [Hash{Symbol => Object}] hydrated state, defaults filled; the lists and value
+        #   objects it shares are frozen, and nothing mutable is shared with `decoded`
         def live_state(decoded)
-          lists = shareable_lists(decoded)
-          hydrated = Runtime::Instance.hydrate_with_defaults(@aggregate, placeholders(decoded, lists))
+          lists  = shareable_lists(decoded)
+          values = live_values(decoded)
+          hydrated = Runtime::Instance.hydrate_with_defaults(@aggregate, placeholders(decoded, lists, values))
           lists.each { |name, (attribute, elements)| hydrated[name] = live_list(attribute, elements) }
+          values.each { |name, (attribute, copy)| hydrated[name] = live_value(attribute, copy) }
           hydrated
         end
 
@@ -70,26 +78,122 @@ module Hecks
           end
         end
 
-        def composite_lists
-          @composite_lists ||= @aggregate.attributes.each_with_object({}) do |attribute, found|
+        def composite_lists = list_attributes(@aggregate)
+
+        def list_attributes(owner)
+          owner.attributes.each_with_object({}) do |attribute, found|
             next unless attribute.list? && !attribute.reference? && composite?(attribute)
 
             found[attribute.name.to_sym] = attribute
           end
         end
 
+        # The attributes of the aggregate that hold one value object able to hold a list, by
+        # name. A value object with no list in it is small and is left to the codec.
+        def growable_values
+          @growable_values ||= @aggregate.attributes.each_with_object({}) do |attribute, found|
+            next if attribute.list? || attribute.reference?
+
+            shape = value_object_of(attribute)
+            found[attribute.name.to_sym] = attribute if shape && growable?(shape, [])
+          end
+        end
+
+        def value_object_of(attribute)
+          return nil unless @aggregate.respond_to?(:value_object)
+
+          Runtime::Value.value_object_for(@aggregate, attribute.type.to_s)
+        end
+
+        def growable?(shape, seen)
+          return false if seen.include?(shape)
+
+          shape.attributes.any? do |attribute|
+            next false if attribute.reference?
+            next true if attribute.list?
+
+            nested = value_object_of(attribute)
+            nested ? growable?(nested, seen + [shape]) : false
+          end
+        end
+
+        # The growable value-object attributes of `state` holding a frozen value of their type.
+        def journal_values(state)
+          return {} unless state.is_a?(Hash)
+
+          growable_values.each_with_object({}) do |(name, attribute), found|
+            value = state[name]
+            found[name] = [attribute, value] if value.is_a?(Runtime::Value) && sharable_value?(attribute, value)
+          end
+        end
+
+        def sharable_value?(attribute, value)
+          value.frozen? && value.type_name == value_object_of(attribute).hecks_name
+        end
+
+        # The growable value-object attributes of `decoded` holding a frozen Hash: a copy this
+        # table made, or one a caller froze.
+        def live_values(decoded)
+          return {} unless decoded.is_a?(Hash)
+
+          growable_values.each_with_object({}) do |(name, attribute), found|
+            copy = decoded[name]
+            found[name] = [attribute, copy] if copy.is_a?(Hash) && copy.frozen?
+          end
+        end
+
         def composite?(attribute)
           type = attribute.type.to_s
           !Runtime::Value.find_entity(@aggregate, type).nil? ||
             (@aggregate.respond_to?(:value_object) && !Runtime::Value.value_object_for(@aggregate, type).nil?)
         end
 
-        # `state` with each shared list replaced by nil, which the codec leaves alone and
-        # which holds the list's place in the key order.
-        def placeholders(state, lists)
-          return state if lists.empty?
+        # `state` with each shared list and value object replaced by nil, which the codec
+        # leaves alone and which holds its place in the key order.
+        def placeholders(state, lists, values)
+          return state if lists.empty? && values.empty?
+
+          state.merge(lists.merge(values).transform_values { nil })
+        end
+
+        # The frozen codec copy of one value object. A list it holds is rebuilt from the copies
+        # of its elements, so a new version of the value costs the new elements, not all of them.
+        def journal_value(attribute, value)
+          known = @journal[value]
+          return known if known
+
+          fields = value.raw_fields
+          lists  = value_lists(attribute, fields)
+          held   = fields.merge(lists.transform_values { nil })
+          copy   = Ports::Persistence::StateCodec.copy_list_element(@aggregate, attribute, held)
+          copy.each_value { |inner| Freezer.deep(inner) }
+          lists.each { |name, (list_attribute, elements)| copy[name] = journal_list(list_attribute, elements) }
+          @copies[copy.freeze] = true
+          @journal[value] = copy
+        end
+
+        def value_lists(attribute, fields)
+          list_attributes(value_object_of(attribute)).each_with_object({}) do |(name, list_attribute), found|
+            elements = fields[name]
+            found[name] = [list_attribute, elements] if elements.is_a?(Array)
+          end
+        end
+
+        # The hydrated value for one frozen copy, its lists rebuilt from the hydrated elements
+        # already held.
+        def live_value(attribute, copy)
+          known = @live[copy]
+          return known if known
+
+          lists  = value_lists(attribute, copy)
+          fields = copy.merge(lists.to_h { |name, (list_attribute, elements)| [name, live_list(list_attribute, elements)] })
+          live   = Runtime::Value.trusting_stored_state do
+            Runtime::Value.for_attribute(@aggregate, attribute, fields)
+          end
+          return live unless @copies.key?(copy)
 
-          state.merge(lists.transform_values { nil })
+          @journal[live] = copy
+          @live[copy] = live
         end
 
         def journal_list(attribute, elements)

data/lib/hecks/deploy/bluebook/deploy.bluebook

@@ -770,6 +770,129 @@ Hecks.bluebook "Deploy" do
     trigger CostCheck::Flag, with: { refusal: :refusal }
   end
 
+  aggregate "SmokeRun" do
+    description "One post-deploy smoke: the generated smoke-after-deploy script run, and how it ended."
+
+    attribute :project, Location
+    attribute :script,  Location, optional: true
+    attribute :run,     RunKey
+    attribute :taskdef, TaskDefinition, optional: true
+    attribute :skip,    Switch, optional: true
+    attribute :async,   Switch, optional: true
+    attribute :dry_run, Switch, optional: true
+    attribute :report,  Report, optional: true
+    attribute :refusal, Report, optional: true
+    identified_by :run
+
+    value_object "RunKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a run is named") { !value.to_s.empty? }
+    end
+
+    value_object "Location" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+
+      invariant("a project or script is named by its path") { !value.to_s.empty? }
+    end
+
+    # A task definition family, or family:revision, as the generated script takes it in TASKDEF.
+    value_object "TaskDefinition" do
+      attribute :value, String, pattern: '^[A-Za-z0-9_-]+(:[0-9]+)?$'
+    end
+
+    value_object "Switch" do
+      attribute :value, Boolean
+    end
+
+    value_object "Report" do
+      attribute :value, String
+    end
+
+    lifecycle :status, default: "requested" do
+      transition "Pass" => "passed", from: "requested"
+      transition "Flag" => "flagged", from: "requested"
+    end
+
+    # `hecks deploy smoke_run.run <project> [script=<path>] [taskdef=<family[:rev]>] [skip=true]
+    # [async=true] [dry_run=true]`. Finds the `smoke-after-deploy.sh` the project's AwsBox projection
+    # generated (`script=` names it when the project holds more than one) and runs it once a roll
+    # has settled: the script waits for the box, dispatches the smoke workflow and follows it.
+    # It only reads AWS; the smoke itself runs on GitHub. Exit 1 when it did not pass, with the
+    # script's own status (20 unsettled, 21 not run, 22 failed, 23 unknown) in the reason.
+    command "Run" do
+      goal "Run a project's generated post-deploy smoke and record whether the live site passed"
+
+      attribute :project, Location
+      attribute :script,  Location, optional: true
+      attribute :run,     RunKey
+      attribute :taskdef, TaskDefinition, optional: true
+      attribute :skip,    Switch, optional: true
+      attribute :async,   Switch, optional: true
+      attribute :dry_run, Switch, optional: true
+
+      sets :project
+      sets :script
+      sets :run
+      sets :taskdef
+      sets :skip
+      sets :async
+      sets :dry_run
+
+      emits "SmokeRequested"
+    end
+
+    command "Pass" do
+      goal "Record that the smoke passed, was skipped on purpose, or was left running, and what it said"
+
+      reference_to SmokeRun
+      attribute :report, Report
+
+      sets :report
+
+      emits "SmokePassed"
+    end
+
+    command "Flag" do
+      goal "Record that the smoke failed, did not run or could not be read, and what was said"
+
+      reference_to SmokeRun
+      attribute :refusal, Report
+
+      sets :refusal
+
+      emits "SmokeFlagged"
+    end
+
+    query "Verdict" do
+      description "What one smoke found: its status, and the report or the reason it was flagged."
+      attribute :run, RunKey
+      where(run: :run)
+      order_by :run
+    end
+
+    query "Flagged" do
+      description "Every smoke that failed, did not run or could not be read."
+      where(status: "flagged")
+      order_by :run
+    end
+  end
+
+  policy "SmokeWhenRequested" do
+    on      "SmokeRun.SmokeRequested"
+    trigger SmokeRun::DeployToolchain::Smoke, with: { run: :run }
+  end
+
+  policy "RecordThePassedSmoke" do
+    on      "SmokeRun.SmokeAnswered"
+    trigger SmokeRun::Pass, with: { report: :report }
+  end
+
+  policy "RecordTheFlaggedSmoke" do
+    on      "SmokeRun.SmokeRefused"
+    trigger SmokeRun::Flag, with: { refusal: :refusal }
+  end
+
   aggregate "TemplateComparison" do
     description "One offline comparison of two CloudFormation templates, by logical id."
 

data/lib/hecks/deploy/bluebook/deploy.hecksagon

@@ -43,6 +43,14 @@ Hecks.hecksagon "Deploy" do
     end
   end
 
+  Deploy::SmokeRun.port "DeployToolchain" do
+    asks "Smoke", to: SmokeRun do
+      attribute :run, RunKey
+      answers "SmokeAnswered"
+      refuses "SmokeRefused"
+    end
+  end
+
   Deploy::TemplateComparison.port "DeployToolchain" do
     asks "Compare", to: TemplateComparison do
       attribute :run, RunKey

data/lib/hecks/deploy/oidc.json

@@ -76,6 +76,21 @@
       "verb": "Deploy::Recipe.Project",
       "role": null
     },
+    {
+      "scope": "deploy:smoke_run.flag",
+      "verb": "Deploy::SmokeRun.Flag",
+      "role": null
+    },
+    {
+      "scope": "deploy:smoke_run.pass",
+      "verb": "Deploy::SmokeRun.Pass",
+      "role": null
+    },
+    {
+      "scope": "deploy:smoke_run.run",
+      "verb": "Deploy::SmokeRun.Run",
+      "role": null
+    },
     {
       "scope": "deploy:template_comparison.diff",
       "verb": "Deploy::TemplateComparison.Diff",

data/lib/hecks/doors/cli_runner.rb

@@ -251,13 +251,22 @@ module Hecks
         events    = runtime.events.select { |event| event.aggregate == fqn && event.id == handle.id }
         answer    = { id: handle.id, state: JsonDoor.materialize(state),
                       events: (events.empty? ? handle.events : events).map(&:name) }.merge(extra)
-        if LauncherOptions.failed?(aggregate, state, launcher)
-          field = aggregate.lifecycle.field
-          why  += [failure_sentence(aggregate, state, field)]
-        end
+        failed = LauncherOptions.failed?(aggregate, state, launcher)
+        why += [failure_sentence(aggregate, state, aggregate.lifecycle.field)] if failed
+        return report_of(answer[:state], why) if LauncherOptions.report?(launcher, spec)
+
         finish(JSON.pretty_generate(answer), why)
       end
 
+      # The answer of a command the launcher prints as its report: the text it recorded, with
+      # the status 1 when the run failed, and nothing else.
+      def report_of(state, why)
+        text = state[why.empty? ? :output : :refusal]
+        text = text[:value] if text.is_a?(Hash)
+        text = why.join("\n") if text.to_s.strip.empty?
+        [text.to_s, why.empty? ? 0 : 1]
+      end
+
       # The sentence for a record that ended in a failure state: the state, then the record's own
       # `refusal` when it keeps one, without the class name an adapter's failure carries.
       def failure_sentence(aggregate, state, field)

data/lib/hecks/doors/launcher_options.rb

@@ -12,8 +12,9 @@ module Hecks
     #
     # - **run_keys** mints the `run` key of a creating command that was given none.
     # - **failure_states** are the lifecycle states `--wait` reports as a failure (exit 1).
-    # - **settled** lists the commands (`aggregate.command`) that always behave as if `--wait` was
-    #   given, so a script gets their outcome in its exit status.
+    # - **settled** lists the commands (`aggregate.command`) that always behave as if `--wait`
+    #   was given, so a script gets their outcome in its exit status.
+    # - **report** lists the settled commands whose answer is the report they recorded, as text.
     # - **names** maps a launcher name to the command it stands for (see `CliProjector`).
     # - **streams** lists the questions `--stream` may tail, one JSON line per new entry.
     module LauncherOptions
@@ -97,6 +98,17 @@ module Hecks
         Array(launcher[:settled]).map(&:to_s).include?(spec[:short].to_s)
       end
 
+      # Whether a command prints the report it recorded instead of its whole record.
+      #
+      # @param launcher [Hash, nil] the chapter's `launcher` setting
+      # @param spec [Hash] the command's projected spec
+      # @return [Boolean] true for a command the setting lists under `report`
+      def report?(launcher, spec)
+        return false unless launcher && spec[:kind] == :command
+
+        Array(launcher[:report]).map(&:to_s).include?(spec[:short].to_s)
+      end
+
       # Whether a question may be tailed with `--stream`: the chapter's `launcher` setting lists it
       # under `streams`, by the question's own name.
       #

data/lib/hecks/hecks/adapters/deploy_toolchain.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "console_capture"
+require_relative "shell"
 require_relative "codebase/tree"
 require_relative "codebase/ruby_child"
 require "hecks/projections/deploy/template_diff"
@@ -12,8 +13,10 @@ module Hecks
     #
     # The recipe, the lint and the manifests run the `Hecks::Tools` tool that already does the work,
     # in this process with its printing and exit status captured: a tool that ends non-zero is a
-    # refusal whose reason is what it printed. They write into a hecks checkout, so outside one the
-    # ask is refused with "needs a hecks checkout". A comparison needs no checkout.
+    # refusal whose reason is what it printed. The lint and the manifests write into a hecks
+    # checkout, so outside one the ask is refused with "needs a hecks checkout". The recipe reads
+    # the project it is given, wherever that is, so it needs no checkout, and neither does a
+    # comparison.
     class DeployToolchain
       # The `Hecks::Tools` tool an ask runs, by ask.
       SCRIPTS = { generate: "project_deploy", lint: "lint_deploy_recipes", manifest: "project_oidc" }.freeze
@@ -22,6 +25,13 @@ module Hecks
       GENERATE_FLAGS = { "--tenant" => :tenant, "--schema" => :schema, "--out" => :out,
                          "--environment" => :environment }.freeze
 
+      # The file name the AwsBox projection gives the post-deploy smoke.
+      SMOKE_SCRIPT = "smoke-after-deploy.sh"
+
+      # What each status of `smoke-after-deploy.sh` means, for the reason a refusal gives.
+      SMOKE_STATUS = { 20 => "the roll did not settle", 21 => "gh missing or no repository, smoke not run",
+                       22 => "the smoke failed", 23 => "the smoke's result is unknown" }.freeze
+
       # Accepts the arguments every driven adapter is built with and keeps none of them.
       #
       # @param aggregate [Object, nil] unused
@@ -29,17 +39,29 @@ module Hecks
       # @param root [String, nil] unused
       def initialize(aggregate: nil, settings: {}, root: nil); end
 
-      # Writes a domain's deploy recipe (the template, scripts and Makefile) from its declared
-      # `deployed_to` target, through `hecks deploy recipe.project`.
+      # Writes a domain's deploy recipe from its declared `deployed_to` target, through
+      # `hecks deploy recipe.project`.
+      #
+      # The domain and `out` are paths relative to where the command runs, or absolute, so a
+      # project outside the hecks checkout (an installed gem has none) works. The Makefiles name
+      # the checkout as their root when the tree is one, else the directory the command runs in.
       #
       # @param held [Hash] the `Recipe` record: `domain`, and `tenant`, `schema`, `out` and
       #   `environment` when set
       # @return [Hash{Symbol => Hash}] `output:` one line per file written
-      # @raise [ConsoleCapture::Failure] when the tree is not a checkout, or the generator refuses
-      #   (no `deployed_to` target, conflicting settings, a schema with no tenant)
+      # @raise [ConsoleCapture::Failure] when the generator refuses (no `deployed_to` target,
+      #   conflicting settings, a schema with no tenant)
       def generate(**held)
-        flags = GENERATE_FLAGS.filter_map { |flag, key| "#{flag}=#{plain(held[key])}" unless plain(held[key]).nil? }
-        child(:generate, [*flags, plain(held[:domain])])
+        tree = Codebase::Tree.new
+        root = tree.checkout? ? tree.root : Dir.pwd
+        flags = GENERATE_FLAGS.filter_map do |flag, key|
+          value = plain(held[key])
+          next if value.nil?
+
+          "#{flag}=#{key == :out ? File.expand_path(value) : value}"
+        end
+        domain = project_path(plain(held[:domain]), root)
+        run(Codebase::Tree.new(root: root), :generate, [*flags, domain])
       end
 
       # Lints generated deploy Makefiles for prod-touching recipes that hide failure, through
@@ -86,17 +108,85 @@ module Hecks
         raise ConsoleCapture::Failure, e.message
       end
 
+      # Runs a project's generated `smoke-after-deploy.sh`, through `hecks deploy smoke_run.run`.
+      #
+      # The script is the one the AwsBox projection writes, found beside the Makefile or, failing
+      # that, the only one under the project (`script` names it otherwise). It waits for the roll
+      # to settle, then dispatches and follows the smoke workflow, and only ever reads AWS. Its
+      # options travel in the environment variables it documents.
+      #
+      # @param held [Hash] the `SmokeRun` record: `project`, and `script`, `taskdef`, `skip`,
+      #   `async` and `dry_run` when set
+      # @return [Hash{Symbol => Hash}] `report:` what the script printed
+      # @raise [ConsoleCapture::Failure] when no script, or more than one, is found, or it ends
+      #   non-zero; the message names its status and what it printed
+      def smoke(**held)
+        script = smoke_script(plain(held[:project]), plain(held[:script]))
+
+        result = Shell.new.capture("bash", script, env: smoke_env(held), chdir: File.dirname(script))
+        report = [result.out, result.err].map(&:strip).reject(&:empty?).join("\n")
+        return { report: { value: report } } if result.ok?
+
+        code = result.status.exitstatus
+        raise ConsoleCapture::Failure, "smoke ended #{code} (#{SMOKE_STATUS.fetch(code, 'unexpected')})\n#{report}"
+      end
+
       private
 
+      # The script a project's smoke runs: the override, else `smoke-after-deploy.sh` in the project
+      # itself, else the only one beneath it (not under `node_modules`, `vendor` or `.git`).
+      def smoke_script(project, override)
+        return existing_script(override) if override
+
+        root = File.expand_path(project.to_s)
+        beside = File.join(root, SMOKE_SCRIPT)
+        return beside if File.file?(beside)
+
+        found = Dir.glob(File.join(root, "**", SMOKE_SCRIPT)).grep_v(%r{/(node_modules|vendor|\.git)/})
+        return found.first if found.one?
+
+        raise ConsoleCapture::Failure, ambiguity(root, found.sort)
+      end
+
+      def ambiguity(root, found)
+        return "no #{SMOKE_SCRIPT} under #{root}; generate the AwsBox recipe or pass script=<path>" if found.empty?
+
+        "#{found.size} #{SMOKE_SCRIPT} files under #{root}; pass script=<path>: #{found.join(', ')}"
+      end
+
+      def existing_script(path)
+        script = File.expand_path(path.to_s)
+        File.file?(script) ? script : raise(ConsoleCapture::Failure, "no such script: #{script}")
+      end
+
+      # The variables the generated script reads, set only when the record asks for them.
+      def smoke_env(held)
+        { "TASKDEF" => plain(held[:taskdef]), "SKIP_POST_DEPLOY_SMOKE" => flag(held[:skip]),
+          "SMOKE_ASYNC" => flag(held[:async]), "DRY_RUN" => flag(held[:dry_run]) }.compact
+      end
+
+      def flag(argument) = plain(argument) == true ? "1" : nil
+
       def child(ask, argv)
         tree = Codebase::Tree.new
         tree.require_checkout!
+        run(tree, ask, argv)
+      end
+
+      def run(tree, ask, argv)
         result = Codebase::RubyChild.new(tree).capture(SCRIPTS.fetch(ask), *argv)
         raise ConsoleCapture::Failure, message_of(result) unless result.ok?
 
         { output: { value: result.out } }
       end
 
+      # A project path the tool can read from `root`: relative to it when it lies beneath it, so a
+      # recipe made in a checkout names `examples/pizzas`, else absolute.
+      def project_path(path, root)
+        absolute = File.expand_path(path)
+        absolute.start_with?("#{root}/") ? absolute.delete_prefix("#{root}/") : absolute
+      end
+
       def message_of(result)
         text = [result.err, result.out].map(&:strip).reject(&:empty?).join("\n")
         text.empty? ? "the tool ended with status #{result.status.exitstatus}" : text

data/lib/hecks/hecks/adapters/first_admin.rb

@@ -17,6 +17,13 @@ module Hecks
       # The roles that count as an administrator besides the one the grant command is gated to.
       OWNER_ROLES = %w[Owner].freeze
 
+      # What the refusal says when no chapter provides membership: the line to add to one.
+      NO_MEMBERSHIP = "this domain attaches no chapter that provides \"membership\". Add a line like " \
+                      "`provides \"membership\", admit: \"Person.Admit\", grant: \"Person.GrantAccess\", " \
+                      "people: \"Person.All\"` to the chapter that keeps who may sign in: admit and grant " \
+                      "name its commands (the grant command is gated to the administrator role), people " \
+                      "names the query that lists everyone (docs/running-a-rules-service.md)"
+
       # What a bootstrap did.
       #
       # @!attribute [r] email
@@ -64,7 +71,7 @@ module Hecks
       def membership_provider
         domain = @registry.bluebooks.values.first&.name
         @registry.membership_provider_for(domain) or
-          raise Runtime::NotFound, "this domain attaches no chapter that provides \"membership\""
+          raise Runtime::NotFound, NO_MEMBERSHIP
       end
 
       def verbs_of(provider)

data/lib/hecks/hecks/adapters/git.rb

@@ -79,6 +79,28 @@ module Hecks
         raise Runtime::NotFound, e.message
       end
 
+      # Prints the content digest and shape labels of one package, as its `bluebook.lock` records
+      # them: `Lock.digest_of` over the package's `bluebook/*.bluebook` files alone, and the labels
+      # `Shape.labels` gives the same files. The package is read from `<root>/<package>/bluebook`
+      # (a registry), else from `<root>/vendor/embryonaut_bluebooks/<package>/bluebook` (a project
+      # that vendors it).
+      #
+      # @param held [Hash] the `Registry` query's arguments: `package`, and `root` (the current
+      #   directory when absent)
+      # @return [Hash{Symbol => String}] `text:` a `digest:` line, then a `shape:` line each
+      # @raise [Runtime::NotFound] when the package has no `bluebook/` with `*.bluebook` files, or
+      #   they do not load
+      def digest(**held)
+        name = plain(held[:package])
+        dir = package_bluebook_dir(File.expand_path(plain(held[:root]) || Dir.pwd), name)
+        digest = EmbryonautBluebook::Lock.digest_of(dir) or
+          raise Runtime::NotFound, "#{dir} holds no *.bluebook files"
+        lines = ["digest: #{digest}", *EmbryonautBluebook::Shape.labels(dir).map { |label| "shape: #{label}" }]
+        { text: "#{lines.join("\n")}\n" }
+      rescue Vendoring::Error => e
+        raise Runtime::NotFound, e.message
+      end
+
       # Judges every package of a bluebook registry against its latest release, through
       # `Hecks::EmbryonautBluebook::Registry#check`.
       #
@@ -136,6 +158,13 @@ module Hecks
 
       private
 
+      def package_bluebook_dir(root, name)
+        places = [File.join(name, "bluebook"), File.join("vendor", "embryonaut_bluebooks", name, "bluebook")]
+        found = places.map { |place| File.join(root, place) }.find { |dir| File.directory?(dir) }
+        found or raise Runtime::NotFound,
+                       "#{name} has no bluebook/ directory in #{root} (looked in #{places.join(' and ')})"
+      end
+
       def registry(held)
         EmbryonautBluebook::Registry.new(File.expand_path(plain(held[:root]) || Dir.pwd))
       end

data/lib/hecks/hecks/adapters/site_toolchain.rb

@@ -55,13 +55,13 @@ module Hecks
       # changed on either side.
       #
       # @param held [Hash] the `SiteProjection` record: `domain`, and `live` or `distribution`,
-      #   with `expect_new` (path patterns, comma separated) and `refs` (`!Ref Name=id` words,
-      #   comma separated) when set
+      #   with `template` (stands in for the Edge row's own; never read), `expect_new` (path
+      #   patterns, comma separated) and `refs` (`!Ref Name=id` words, comma separated) when set
       # @return [Hash{Symbol => Hash}] `output:` the report of a distribution that matches
       # @raise [ConsoleCapture::Failure] when the project has no edge, the live configuration
       #   cannot be read, or the two differ; the message is the report
       def compare(**held)
-        edge = edge_of(located(:domain, held[:domain]))
+        edge = edge_of(located(:domain, held[:domain]), located(:template, held[:template]))
         live = live_configuration(held)
         live_edge = Projections::Site::LiveEdge
         comparison = live_edge.new(edge, live, expect_new: words(held[:expect_new]),
@@ -74,7 +74,7 @@ module Hecks
       private
 
       # The project's checked edge, read the way `project_site` reads it.
-      def edge_of(root)
+      def edge_of(root, template = nil)
         registry = nil
         outcome = ConsoleCapture.capture { registry = Tools::SiteRoutes.registry_for(root) }
         raise ConsoleCapture::Failure, outcome.output.strip unless outcome.ok?
@@ -82,7 +82,7 @@ module Hecks
         site = Projections::Site
         chapter = site::Table.chapter(registry)
         table = site::Table.read(chapter, registry: registry)
-        site::Edge.read(chapter, table: table, vocabulary: site::Table.vocabulary(registry)) ||
+        site::Edge.read(chapter, table: table, template: template, vocabulary: site::Table.vocabulary(registry)) ||
           raise(ConsoleCapture::Failure, "#{root} declares no Edge rows")
       rescue Projections::Site::Table::Invalid => e
         raise ConsoleCapture::Failure, e.message

data/lib/hecks/hecks/custodian.bluebook

@@ -1420,6 +1420,17 @@ policy "RecordTheEra" do
       returns Document
     end
 
+    # `hecks package.digest <package> [root=path]`: a read of the package's files, so it keeps no
+    # record. The digest is `Lock.digest_of` over `<package>/bluebook/*.bluebook` only (the
+    # `bluebook.lock` digest line), then the package's shape labels; `root` is the registry, or a
+    # project that vendors the package.
+    query "Digest" do
+      description "Print a package's content digest and shape labels, as its bluebook.lock records them."
+      attribute :package, PackageName
+      attribute :root, Location, optional: true
+      returns Document
+    end
+
     query "Releasing" do
       description "What releasing one run did: its status, and the report or the refusal."
       attribute :run, RegistryKey

data/lib/hecks/hecks/hecks.hecksagon

@@ -105,6 +105,7 @@ Hecks.hecksagon "Hecks" do
     end
 
     answers_query "Check"
+    answers_query "Digest"
   end
 
   Hecks::Door.port "Workspace" do
@@ -400,6 +401,14 @@ Hecks.hecksagon "Hecks" do
     end
   end
 
+  Deploy::SmokeRun.port "DeployToolchain" do
+    asks "Smoke", to: SmokeRun do
+      attribute :run, RunKey
+      answers "SmokeAnswered"
+      refuses "SmokeRefused"
+    end
+  end
+
   Deploy::TemplateComparison.port "DeployToolchain" do
     asks "Compare", to: TemplateComparison do
       attribute :run, RunKey

data/lib/hecks/hecks/hecks.world

@@ -40,9 +40,10 @@ Hecks.world "Hecks" do
                        failure_states: %w[flagged failed drifted unreachable refused faulted halted stopped
                                           abandoned red needs_fix],
                        settled: %w[package.vendor package.revendor package.release
-                                  operation.bootstrap_admin],
+                                  operation.bootstrap_admin smoke_run.run],
                        names: { "mcp" => "door.serve_mcp", "console" => "operation.open_console", "init" => "door.init",
                                 "interview" => "door.interview", "package.check" => "registry.check",
+                                "package.digest" => "registry.digest",
                                 "package.release" => "registry.release" },
                        streams: %w[Follow],
                        executable: "exe/hecks",

data/lib/hecks/hecks/site.world

@@ -5,9 +5,11 @@
 # `run_keys` mints the `run` key of a projection, and `--wait` reports a faulted projection (a
 # routes.ts out of date under `--check`, or a route table the projector refused) as exit 1, and
 # `settled` makes `site_projection.check_live` wait for its reactions without the flag, so a live
-# distribution that differs from the project is an exit status.
+# distribution that differs from the project is an exit status. `report` prints that command's
+# answer as the report alone: the differences, or the line saying the distribution matches.
 Hecks.world "Site" do
   launcher "Launcher", run_keys: true,
                        failure_states: %w[faulted refused halted stopped abandoned red needs_fix],
-                       settled: %w[site_projection.check_live]
+                       settled: %w[site_projection.check_live],
+                       report: %w[site_projection.check_live]
 end

data/lib/hecks/projections/deploy/box/hosting.rb

@@ -33,8 +33,9 @@ module Hecks
           # @param plan [Settings::Plan] the resolved settings
           # @return [String] the Makefile fragment the box `Makefile` includes
           def hosting_mk(plan)
-            Box.template("hosting.mk.tmpl", "SERVICE" => plan.containers.first.name,
-                                            "URL"     => plan.hosting.public_url.to_s)
+            Box.template("hosting.mk.tmpl", "SERVICE"      => plan.containers.first.name,
+                                            "URL"          => plan.hosting.public_url.to_s,
+                                            "SMOKE_RECIPE" => Box::SMOKE_RECIPE)
           end
 
           # @param plan [Settings::Plan] the resolved settings

data/lib/hecks/projections/deploy/box/templates/hosting.mk.tmpl

@@ -13,10 +13,13 @@ URL     ?= @@URL@@
 deploy-service:
 	bash ./deploy-service.sh $(SERVICE)
 
-# Waits for the last roll to settle, then dispatches and follows the smoke.
+# Waits for the last roll to settle, then dispatches and follows the smoke, as the smoke_run.run
+# command, which runs smoke-after-deploy.sh and records how it ended in the Hecks database
+# (HECKS_DATABASE, default postgres://hecks@localhost/hecks). Without that database the smoke still
+# runs and its result is printed, and the target exits non-zero (24 if the smoke passed).
 # SKIP_POST_DEPLOY_SMOKE=1 opts out, DRY_RUN=1 dispatches nothing.
 smoke-after-deploy:
-	bash ./smoke-after-deploy.sh
+	@@SMOKE_RECIPE@@
 
 # Compares the era a live host reports at GET /version with expected-era.
 check-era:

data/lib/hecks/projections/deploy/box.rb

@@ -28,6 +28,25 @@ module Hecks
                       "# after adding one: the admin API is off, so a reload cannot reach it.\n" \
                       "import /etc/caddy/extra/*\n".freeze
 
+        # The `smoke-after-deploy` recipe: the smoke runs as `smoke_run.run`, which finds
+        # `smoke-after-deploy.sh` beside the Makefile and records how it ended in the Hecks
+        # database. When that database cannot be opened the command never starts, so the recipe
+        # runs the script itself, states the database error apart from the smoke's result, and
+        # exits non-zero (24 when the smoke passed).
+        SMOKE_RECIPE = [
+          "@err=$$(mktemp); \\",
+          '$(HECKS) deploy smoke_run.run project="$(CURDIR)" --wait $(if $(TASKDEF),taskdef=$(TASKDEF)) 2>"$$err"; rc=$$?; \\',
+          'if [ $$rc -ne 0 ] && grep -q \'^cannot open Hecks\' "$$err"; then \\',
+          '  echo "==> the deploy record was NOT written: $$(grep -m1 \'^cannot open Hecks\' "$$err")" >&2; \\',
+          '  echo "    one-time setup on this machine: createdb hecks, or set HECKS_DATABASE to a Postgres URL" >&2; \\',
+          '  echo "    running the smoke anyway so its result is not lost" >&2; \\',
+          '  rm -f "$$err"; TASKDEF="$(TASKDEF)" bash ./smoke-after-deploy.sh; rc=$$?; \\',
+          '  echo "==> smoke exit $$rc. The deploy record was NOT written: the database is unavailable (see above)." >&2; \\',
+          "  [ $$rc -ne 0 ] || rc=24; exit $$rc; \\",
+          "fi; \\",
+          'cat "$$err" >&2; rm -f "$$err"; exit $$rc'
+        ].join("\n\t").freeze
+
         module_function
 
         # Generates `rds.yaml`, `box.yaml`, `Caddyfile`, `services.json`, `render-compose.sh`,
@@ -582,7 +601,7 @@ module Hecks
         def hosting_makefile_tail(plan)
           return "" unless plan.hosting
 
-          "\t#{'TASKDEF="$(TASKDEF)" ' if plan.task_definition}bash ./smoke-after-deploy.sh\n\ninclude hosting.mk\n"
+          "\t$(MAKE) smoke-after-deploy\n\ninclude hosting.mk\n"
         end
 
         # Fills `@@NAME@@` markers. A marker alone on its line is replaced together with the line,

data/lib/hecks/runtime/value.rb

@@ -47,6 +47,13 @@ module Hecks
       # @param field [String, Symbol] the field name; `:value` resolves the same way `[]` does
       # @return [Boolean] true when the field is held
       def key?(field) = @fields.key?(resolve_field(field))
+
+      # Reads the held fields as they are stored, without materializing nested values.
+      #
+      # @return [Hash{Symbol => Object}] the frozen, Symbol-keyed field Hash, in storage order;
+      #   a nested `Runtime::Value` stays a `Runtime::Value`
+      def raw_fields = @fields
+
       def to_h = @fields.transform_values { |value| self.class.materialize(value) }
 
       # Renders this value object as JSON, through the same shape `to_h` builds.

data/lib/hecks/site/bluebook/site.bluebook

@@ -186,14 +186,18 @@ Hecks.bluebook "Site" do
     end
 
     # `hecks site site_projection.check_live <project> live=<saved-config.json> | distribution=<id>
-    # [expect_new=<paths>] [refs=<!Ref Name=id,...>]`. Compares the project's generated CloudFront
+    # [template=<file>] [expect_new=<paths>] [refs=<!Ref Name=id,...>]`. Compares the project's generated CloudFront
     # behaviours with a live distribution's, changing neither. `live` is a saved answer of
     # `aws cloudfront get-distribution-config`; `distribution` fetches it with that one read-only call.
+    # `template` stands in for the `Edge` row's `template:` as it does for `project_site`; the check
+    # reads no template, so the file need not exist. It prints the report alone and exits 1 on a
+    # difference.
     command "CheckLive" do
       goal "Compare a project's generated CloudFront behaviours with a live distribution's"
 
       attribute :domain,       DomainPath
       attribute :run,          RunKey
+      attribute :template,     Location,       optional: true
       attribute :live,         Location,       optional: true
       attribute :distribution, DistributionId, optional: true
       attribute :expect_new,   PathList,       optional: true
@@ -205,6 +209,7 @@ Hecks.bluebook "Site" do
 
       sets :domain
       sets :run
+      sets :template
       sets :live
       sets :distribution
       sets :expect_new

data/lib/hecks/version.rb

@@ -1,5 +1,5 @@
 module Hecks
   # Read directly by the gemspec, so this file must never require the
   # rest of the gem (its dependencies aren't resolved yet at that point).
-  VERSION = "3.4.1".freeze
+  VERSION = "3.4.2".freeze
 end

data/rust/host/HECKS_RELEASE

@@ -1 +1 @@
-3.4.1
+3.4.2

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hecks
 version: !ruby/object:Gem::Version
-  version: 3.4.1
+  version: 3.4.2
 platform: ruby
 authors:
 - Chris Young
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-05 00:00:00.000000000 Z
+date: 2026-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: prism