hecks 3.2.1 → 3.3.0

data/lib/hecks/runtime/needs.rb

@@ -0,0 +1,48 @@
+require_relative "../ports/clock"
+
+module Hecks
+  module Runtime
+    # Answers the outside facts a command or a query `needs` (ADR 0081). A fact is answered once,
+    # before any given or filter reads the arguments, and the answer rides in the declaration's own
+    # arguments, so an event records it and a replay re-dispatches the recorded value rather than
+    # asking again.
+    module Needs
+      # What answers each fact a declaration may need: `now` is the clock port's reading in epoch
+      # seconds, `today` the day it falls in, whole days since the epoch in UTC.
+      ANSWERS = {
+        now:   ->(registry) { Ports::Clock.now(registry) },
+        today: ->(registry) { Ports::Clock.now(registry) / 86_400 }
+      }.freeze
+
+      module_function
+
+      # Fills each outside fact the declaration `needs` and the caller left out. A value the caller
+      # supplied is kept, so a test or a back-fill can name its own time.
+      #
+      # @param declaring [#needs, #attributes] the command or query being run
+      # @param args [Hash{Symbol => Object}] the arguments the caller passed
+      # @param registry [Runtime::Registry] where the clock port is bound
+      # @return [Hash{Symbol => Object}] `args`, with each missing needed fact answered
+      # @raise [Runtime::WiringError] when the port that answers a fact is not bound exactly once
+      def fill(declaring, args, registry:)
+        missing = declaring.needs.reject { |fact| args.key?(fact) || args.key?(fact.to_s) }
+        return args if missing.empty?
+
+        args.merge(missing.to_h { |fact| [fact, value(declaring, fact, registry)] })
+      end
+
+      # The answer to one fact, in the shape the declaration's argument of that name takes: a bare
+      # Integer for an Integer attribute, else the one-field value object the language declares.
+      #
+      # @param declaring [#attributes] the command or query
+      # @param fact [Symbol] a key of `ANSWERS`
+      # @param registry [Runtime::Registry] where the clock port is bound
+      # @return [Integer, Hash{Symbol => Integer}] the answer, shaped for its argument
+      def value(declaring, fact, registry)
+        answer    = ANSWERS.fetch(fact).call(registry)
+        attribute = declaring.attributes.find { |held| held.name.to_s == fact.to_s }
+        attribute&.type.to_s == "Integer" ? answer : { value: answer }
+      end
+    end
+  end
+end

data/lib/hecks/runtime/query_interpreter.rb

@@ -5,6 +5,7 @@ require_relative "../ports/query/ordering"
 require_relative "../query_specification/field_path"
 require_relative "../query_specification/common/comparison"
 require_relative "errors"
+require_relative "needs"
 require_relative "reference_hop"
 require_relative "refusal_wording"
 require_relative "tenant_scope"
@@ -203,6 +204,7 @@ module Hecks
       def entity_rows(domain, aggregate, dotted, args)
         entity_name, query_name = Naming.split_dotted(dotted)
         entity, declared, list_attr = resolve_entity_query(aggregate, entity_name, query_name)
+        args = Needs.fill(declared, args, registry: @registry)
         declared = TenantScope.apply(declared, args)
 
         parent_key = Naming.reference_key(aggregate.hecks_name)
@@ -282,6 +284,7 @@ module Hecks
       # from field defaults and only refuses when a field has none. `null_vo_argument!`
       # refuses like any other wrong-shaped value. Command arguments are untouched.
       def normalize_args(aggregate, declared, args)
+        args = Needs.fill(declared, args, registry: @registry)
         declared.attributes.each_with_object(args.dup) do |attribute, normalized|
           next unless normalized.key?(attribute.name)
 

data/lib/hecks/runtime/registry/verification.rb

@@ -408,9 +408,9 @@ module Hecks
           File.expand_path(path.to_s).start_with?("#{GEM_CHAPTER_DIR}/")
         end
 
-        # Two packages can share a chapter name by coincidence (found live: a stale
-        # vendor/hecksagain fork of Governance/Identity/Deploy, still on 4 apps' load
-        # paths). Intentional accumulation (several files declaring the same chapter on
+        # Two packages can share a chapter name by coincidence (a stale vendored
+        # fork of Governance/Identity/Deploy still on an app's load paths).
+        # Intentional accumulation (several files declaring the same chapter on
         # purpose) is distinguished by package root, not file identity, and is left
         # untouched here — checked once, after every file has loaded.
         def refuse_cross_package_bluebook_merge!

data/lib/hecks/rust_build/host.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+require_relative "../rust_build"
+require_relative "wasm"
+
+module Hecks
+  module RustBuild
+    # Builds the Rust host binary for a domain and stages it with the domain's module and IR, the
+    # three files a container image copies in.
+    #
+    #   Host.call(["path/to/domain", "--target=aarch64-unknown-linux-gnu", "--stage=build/host"])
+    #
+    # The host is compiled from the workspace this release carries (`rust/host`), so the binary is
+    # the one the installed gem was released with; nothing is fetched. The module and IR come from
+    # `Wasm`. `CARGO_TARGET_DIR` names where Cargo writes (the copy's `target/` for a client), so
+    # a second build recompiles only what changed. Stages `<domain>-host`, `<domain>.wasm` and
+    # `<domain>.ir.json` in `--stage` (default `.hecks/host/<target>/` in the working directory).
+    module Host
+      # The host crate's binary.
+      BINARY = "bootstrap"
+
+      # The toolchain Cargo runs under, as `Wasm` builds with.
+      TOOLCHAIN = "stable"
+
+      # A Rust target triple: `<arch>-<vendor>-<os>`, with an optional `-<env>`.
+      TRIPLE = /\A[a-z0-9_]+(-[a-z0-9_.]+){2,3}\z/
+
+      module_function
+
+      # @param argv [Array<String>] the domain's directory, then optional `--target=<triple>` and
+      #   `--stage=<directory>`
+      # @return [Integer] the exit status
+      # @raise [Failure] when the toolchain, the target or a step is missing or fails
+      def call(argv)
+        domain = argv.find { |arg| !arg.start_with?("--") } or
+          raise Failure, "usage: hecks build_host <domain> [target=<triple>] [stage=<directory>]"
+        target = flag(argv, "target") || host_triple
+        require_buildable!(target)
+        stage = flag(argv, "stage") || File.join(Dir.pwd, ".hecks", "host", target)
+
+        status = Wasm.call([domain])
+        raise Failure, "project_wasm failed for #{domain}" unless status.zero?
+
+        binary = compile(target)
+        publish(binary, File.basename(domain.chomp("/")), stage)
+        0
+      end
+
+      # @param argv [Array<String>] a tool's arguments
+      # @param name [String] a flag's name
+      # @return [String, nil] the value of `--<name>=<value>`, nil when absent
+      def flag(argv, name)
+        argv.filter_map { |arg| arg.delete_prefix("--#{name}=") if arg.start_with?("--#{name}=") }.last
+      end
+
+      # @return [String] the triple the Rust toolchain builds for by default
+      # @raise [Failure] when there is no Rust toolchain
+      def host_triple
+        require_rustup!
+        query("rustup", "run", TOOLCHAIN, "rustc", "-vV").to_s[/^host: (\S+)/, 1] or
+          raise Failure, "rustup has no #{TOOLCHAIN} toolchain. Install it once with:\n\n    " \
+                         "rustup toolchain install #{TOOLCHAIN}\n\nthen re-run the build."
+      end
+
+      def require_buildable!(target)
+        raise Failure, "#{target} is not a Rust target triple (for example aarch64-unknown-linux-gnu)" unless
+          TRIPLE.match?(target)
+        if target.start_with?("wasm")
+          raise Failure, "the host is a server binary; #{target} is a wasm target. Build the module with " \
+                         "build.build_wasm, or name a native target"
+        end
+
+        require_rustup!
+        installed = query("rustup", "target", "list", "--installed", "--toolchain", TOOLCHAIN).to_s.split
+        return if installed.include?(target) || target == host_triple
+
+        raise Failure, <<~MSG
+          #{target} isn't installed for the #{TOOLCHAIN} toolchain. Install it once with:
+
+              rustup target add #{target} --toolchain #{TOOLCHAIN}
+
+          then re-run the build.
+        MSG
+      end
+
+      def require_rustup!
+        return if query("rustup", "--version")
+
+        raise Failure, "rustup isn't installed. Install the Rust toolchain from https://rustup.rs, " \
+                       "then re-run the build."
+      end
+
+      # `rustup run`, not bare `cargo`, as `Wasm` does. A cross target links with the
+      # `<arch>-linux-gnu-gcc` on PATH unless `CARGO_TARGET_<TRIPLE>_LINKER` already names a linker.
+      def compile(target)
+        host_dir = File.join(RustBuild.rust_dir, "host")
+        target_dir = ENV.fetch("CARGO_TARGET_DIR", File.join(host_dir, "target"))
+        puts "== cargo build --release --target #{target} --bin #{BINARY} (rust/host) =="
+        env = { "CARGO_TARGET_DIR" => target_dir }.merge(linker_for(target))
+        RustBuild.command!("rustup", "run", TOOLCHAIN, "cargo", "build", "--release", "--target", target,
+                           "--bin", BINARY, chdir: host_dir, env: env)
+        File.join(target_dir, target, "release", BINARY)
+      rescue Failure => e
+        raise Failure, "#{e.message}#{cross_hint(target)}"
+      end
+
+      def linker_for(target)
+        variable = "CARGO_TARGET_#{target.upcase.tr('-.', '__')}_LINKER"
+        return {} if ENV.key?(variable) || target == host_triple
+
+        candidate = "#{target.split('-').first}-linux-gnu-gcc"
+        target.end_with?("linux-gnu") && query(candidate, "--version") ? { variable => candidate } : {}
+      end
+
+      def cross_hint(target)
+        return "" if target == host_triple
+
+        "\n#{target} differs from this machine's #{host_triple}, so linking needs a linker for it: " \
+          "put a cross compiler such as #{target.split('-').first}-linux-gnu-gcc on PATH, or set " \
+          "CARGO_TARGET_#{target.upcase.tr('-.', '__')}_LINKER"
+      end
+
+      def publish(binary, name, stage)
+        dist = File.join(RustBuild.rust_dir, "dist")
+        files = { binary => "#{name}-host", File.join(dist, "#{name}.wasm") => "#{name}.wasm",
+                  File.join(dist, "#{name}.ir.json") => "#{name}.ir.json" }
+        files.each_key do |path|
+          raise Failure, "the build left no #{path}" unless File.file?(path)
+        end
+        FileUtils.mkdir_p(stage)
+        files.each { |from, to| FileUtils.cp(from, File.join(stage, to)) }
+        File.chmod(0o755, File.join(stage, "#{name}-host"))
+        puts "staged in #{stage}: #{files.values.join(', ')}"
+      end
+
+      # @return [String, nil] a program's combined output, nil when it is missing or fails
+      def query(*command)
+        out, status = Open3.capture2e(*command)
+        status.success? ? out : nil
+      rescue SystemCallError
+        nil
+      end
+    end
+  end
+end

data/lib/hecks/rust_build/kernel_input.rb

@@ -5,12 +5,14 @@ require_relative "../rust_build"
 
 module Hecks
   module RustBuild
-    # The stdin a compiled domain binary reads: the steps to run, plus the declared argument
-    # defaults the host would hand its kernel.
+    # The stdin a compiled domain binary reads: the steps to run, plus what the host would hand its
+    # kernel from the domain's IR.
     #
-    # The kernel has no IR of its own, so a command's declared defaults reach it as a top-level
-    # `"defaults"` table, `{ "Domain::Aggregate.Command" => { "attribute" => value } }`, the same
-    # one the Rust host builds from the domain's IR. A harness that sends only `"steps"` would
+    # The kernel has no IR of its own, so the facts a declaration reaches it with arrive as
+    # top-level tables the Rust host builds from the domain's IR: `"defaults"`, a command's declared
+    # argument defaults (`{ "Domain::Aggregate.Command" => { "attribute" => value } }`); `"needs"`,
+    # the outside facts a command needs; and `"query_needs"`, the same for a query (kept apart: a
+    # command and a query may share a qualified name). A harness that sends only `"steps"` would
     # leave the kernel refusing an argument Ruby fills, so every conformance caller builds its
     # input here.
     module KernelInput
@@ -18,11 +20,10 @@ module Hecks
 
       # @param domain_path [String] the domain's directory; its basename names the generated module
       # @param steps [Array<Hash>] the steps to run
-      # @return [Hash{String => Object}] the input; `"defaults"` is there only when one is declared
+      # @return [Hash{String => Object}] the input; each table is there only when it has an entry
       def build(domain_path, steps)
         input = { "steps" => steps }
-        defaults = defaults_for(domain_path)
-        input["defaults"] = defaults unless defaults.empty?
+        tables_for(domain_path).each { |name, table| input[name] = table unless table.empty? }
         input
       end
 
@@ -35,27 +36,48 @@ module Hecks
       #
       # @param domain_path [String] the domain's directory
       # @return [Hash{String => Hash{String => Object}}] empty when the IR is absent or has none
-      def defaults_for(domain_path)
-        ir = generated_ir(domain_path) or return {}
+      def defaults_for(domain_path) = tables_for(domain_path).fetch("defaults")
+
+      # The three tables of one domain: `"defaults"`, `"needs"` and `"query_needs"`.
+      #
+      # @param domain_path [String] the domain's directory
+      # @return [Hash{String => Hash}] each table, empty when the IR is absent or declares none
+      def tables_for(domain_path)
+        tables = { "defaults" => {}, "needs" => {}, "query_needs" => {} }
+        ir = generated_ir(domain_path) or return tables
         domain = ir["name"].to_s
-        Array(ir["aggregates"]).each_with_object({}) do |aggregate, table|
-          collect_defaults(aggregate, "#{domain}::#{aggregate['name']}", table)
-        end
+        Array(ir["aggregates"]).each { |aggregate| collect(aggregate, "#{domain}::#{aggregate['name']}", tables) }
+        tables
       end
 
-      # Adds the defaults of `node`'s commands, then of each entity nested in it, under `prefix`.
+      # Adds what `node`'s commands and queries declare, then what each entity nested in it does,
+      # under `prefix`.
       #
       # @param node [Hash] an aggregate or entity of the IR
       # @param prefix [String] the verb path down to `node`
-      # @param table [Hash] filled in place
+      # @param tables [Hash] filled in place
       # @return [void]
-      def collect_defaults(node, prefix, table)
+      def collect(node, prefix, tables)
         Array(node["commands"]).each do |command|
+          verb = "#{prefix}.#{command['name']}"
           held = Array(command["attributes"]).reject { |attribute| attribute["default"].nil? }
                                              .to_h { |attribute| [attribute["name"], attribute["default"]] }
-          table["#{prefix}.#{command['name']}"] = held unless held.empty?
+          tables["defaults"][verb] = held unless held.empty?
+          tables["needs"][verb] = needs_of(command) unless Array(command["needs"]).empty?
+        end
+        Array(node["queries"]).each do |query|
+          tables["query_needs"]["#{prefix}.#{query['name']}"] = needs_of(query) unless Array(query["needs"]).empty?
+        end
+        Array(node["entities"]).each { |entity| collect(entity, "#{prefix}.#{entity['name']}", tables) }
+      end
+
+      # @param declaration [Hash] a command or query of the IR that declares `needs`
+      # @return [Array<Hash>] each needed fact with the type of the argument of the same name
+      def needs_of(declaration)
+        Array(declaration["needs"]).map do |need|
+          argument = Array(declaration["attributes"]).find { |attribute| attribute["name"] == need["fact"] }
+          { "fact" => need["fact"], "type" => argument ? argument["type"].to_s : "" }
         end
-        Array(node["entities"]).each { |entity| collect_defaults(entity, "#{prefix}.#{entity['name']}", table) }
       end
 
       # @param domain_path [String] the domain's directory

data/lib/hecks/rust_build/project_rust/codegen_run.rb

@@ -3,7 +3,6 @@
 require "fileutils"
 require "json"
 require "tmpdir"
-require_relative "../rust_literal"
 require_relative "../write_if_changed"
 
 module Hecks
@@ -78,7 +77,6 @@ module Hecks
         def generate_meta(stage, tmp)
           ir_path = write_ir(tmp, "meta", @meta)
           run("full", stage, "meta", META_LABEL, ir_path)
-          write_sidecars(File.join(stage, "meta"), @meta, META_LABEL)
         end
 
         def generate_target(stage, tmp)
@@ -87,9 +85,6 @@ module Hecks
             args.push(chapter.mod_name, chapter.label, write_ir(tmp, chapter.mod_name, chapter.ir))
           end
           run("full", *args)
-          [@target, *@chapters].each do |chapter|
-            write_sidecars(File.join(stage, chapter.mod_name), chapter.ir, chapter.label)
-          end
         end
 
         def write_ir(tmp, name, tree)
@@ -98,19 +93,6 @@ module Hecks
           path
         end
 
-        # `ir.json` is what `rust/host` reads at runtime, and `metadata.rs` embeds the same text;
-        # the codegen binary writes neither.
-        def write_sidecars(mod_dir, tree, label)
-          text = JSON.pretty_generate(tree)
-          File.write(File.join(mod_dir, "ir.json"), text)
-          File.write(File.join(mod_dir, "metadata.rs"), <<~RUST)
-            // GENERATED by hecks project_rust — #{label}'s own canonical IR,
-            // embedded for runtime self-description. Not read by any dispatch
-            // function in this module — introspection only.
-            pub const IR_JSON: &str = #{RustLiteral.string(text)};
-          RUST
-        end
-
         def run(*args)
           return if system(self.class.binary(@rust_dir), *args, out: $stdout, err: $stderr)
 

data/lib/hecks/rust_build/project_rust.rb

@@ -5,7 +5,6 @@ require "json"
 require_relative "../../hecks"
 require_relative "../bluebook/meta_validator"
 require_relative "../ports/persistence/plugins/era"
-require_relative "append_optionals"
 require_relative "domain_name"
 require_relative "write_if_changed"
 
@@ -83,20 +82,14 @@ module Hecks
         vendored = @registry.hecksagons.values.flat_map(&:vendored_packages)
         chapters = (@registry.bluebooks.keys - [@domain_name]).map do |name|
           ir = Hecks::Projector::Exporter.call(@registry).fetch(name)
-          CodegenRun::Chapter.new(name.downcase, "#{@domain} (#{attachment(name, vendored)})", prepared_ir(ir))
+          CodegenRun::Chapter.new(name.downcase, "#{@domain} (#{attachment(name, vendored)})", json_shaped(ir))
         end
         CodegenRun.new(
-          rust_dir: @rust_dir, out_root: @out_root, meta: prepared_ir(meta), chapters: chapters,
-          target: CodegenRun::Chapter.new(@mod_name, @domain, prepared_ir(@ir, shaped: false))
+          rust_dir: @rust_dir, out_root: @out_root, meta: json_shaped(meta), chapters: chapters,
+          target: CodegenRun::Chapter.new(@mod_name, @domain, @ir)
         ).call
       end
 
-      # The IR as the generator reads it: string-keyed through JSON, with the append-optional
-      # fields marked, since `ir.json` records them.
-      def prepared_ir(tree, shaped: true)
-        AppendOptionals.mark(shaped ? json_shaped(tree) : tree)
-      end
-
       # Round-trips a value through JSON so generators see the string-keyed shape a real `ir.json`
       # carries, never live Ruby symbols.
       def json_shaped(payload) = JSON.parse(JSON.generate(payload), symbolize_names: true)

data/lib/hecks/rust_build.rb

@@ -31,6 +31,7 @@ module Hecks
     TOOLS = {
       "project_rust"          => ["rust_build/project_rust", :ProjectRust],
       "project_wasm"          => ["rust_build/wasm", :Wasm],
+      "project_host"          => ["rust_build/host", :Host],
       "project_wasm_browser"  => ["rust_build/wasm_browser", :WasmBrowser],
       "rust_conformance"      => ["rust_build/conformance", :Conformance],
       "rust_conformance_fuzz" => ["rust_build/conformance_fuzz", :ConformanceFuzz],

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

@@ -101,6 +101,10 @@ Hecks.bluebook "Site" do
     attribute :template,  Location,  optional: true
     attribute :extension, Extension, optional: true
     attribute :check,     Switch,    optional: true
+    attribute :live,      Location,  optional: true
+    attribute :distribution, DistributionId, optional: true
+    attribute :expect_new, PathList, optional: true
+    attribute :refs,      PolicyRefs, optional: true
     attribute :output,    Report,    optional: true
     attribute :refusal,   Report,    optional: true
     identified_by :run
@@ -134,6 +138,21 @@ Hecks.bluebook "Site" do
       attribute :value, Boolean
     end
 
+    # A CloudFront distribution's id, whose configuration `check_live` reads.
+    value_object "DistributionId" do
+      attribute :value, String, pattern: '^[A-Z0-9]+$'
+    end
+
+    # Path patterns, comma separated: the behaviours a change is about to add to the live distribution.
+    value_object "PathList" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
+    # Policy references and the ids they stand for live, as `!Ref Name=id`, comma separated.
+    value_object "PolicyRefs" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
     value_object "Report" do
       attribute :value, String
     end
@@ -166,8 +185,36 @@ Hecks.bluebook "Site" do
       emits "SiteProjectionRequested"
     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
+    # 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.
+    command "CheckLive" do
+      goal "Compare a project's generated CloudFront behaviours with a live distribution's"
+
+      attribute :domain,       DomainPath
+      attribute :run,          RunKey
+      attribute :live,         Location,       optional: true
+      attribute :distribution, DistributionId, optional: true
+      attribute :expect_new,   PathList,       optional: true
+      attribute :refs,         PolicyRefs,     optional: true
+
+      given("exactly one of a saved configuration and a distribution is named: pass live= or distribution=, not both") do
+        (live.set? && distribution.unset?) || (live.unset? && distribution.set?)
+      end
+
+      sets :domain
+      sets :run
+      sets :live
+      sets :distribution
+      sets :expect_new
+      sets :refs
+
+      emits "LiveCheckRequested"
+    end
+
     command "Complete" do
-      goal "Record that routes.ts was written, or found current, and where"
+      goal "Record that routes.ts was written, or found current, or the live edge matched, and what it said"
 
       reference_to SiteProjection
       attribute :output, Report
@@ -207,6 +254,11 @@ Hecks.bluebook "Site" do
     trigger SiteProjection::SiteToolchain::Project, with: { run: :run }
   end
 
+  policy "CheckWhenRequested" do
+    on      "SiteProjection.LiveCheckRequested"
+    trigger SiteProjection::SiteToolchain::Compare, with: { run: :run }
+  end
+
   policy "RecordTheProjection" do
     on      "SiteProjection.SiteAnswered"
     trigger SiteProjection::Complete, with: { output: :output }

data/lib/hecks/site/bluebook/site.ports.hecksagon

@@ -11,5 +11,11 @@ Hecks.hecksagon "Site" do
       answers "SiteAnswered"
       refuses "SiteRefused"
     end
+
+    asks "Compare", to: SiteProjection do
+      attribute :run, RunKey
+      answers "SiteAnswered"
+      refuses "SiteRefused"
+    end
   end
 end