hecks 3.1.1 → 3.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8bfb40ad9e9760533d77e179154821128fee28930877e35118b5e87c5c32731
-  data.tar.gz: 49fd0e562e846d8633c11101d7b11c6d751089c8ca0f281907f1c669e1d19438
+  metadata.gz: 88b11874249737158a9451d66aa0842ef88fb3f1ff047cced68d97b2ce9fdc5f
+  data.tar.gz: 2872e381ce8e7fe5d46ef7a7623134dc23d923e57bdf194758effedaa1cc4671
 SHA512:
-  metadata.gz: e584bed9d83942763f583530d44910d6a988c7b55af6a4177f257ba017562957f373ea7ea726340b7ae845e2811d7217665ab6815991ae9cffb0e6cb437928c2
-  data.tar.gz: 6cac69c95c6dedc28736d5401d64a6597327c27b8d3ed1909c225ad6191c4cb0cac929ac9f3896f5c648c890d75b10d6d4b3d5431498e82e560bd682f2dc312d
+  metadata.gz: 76a39ab361adfb4e07bb558cb917d46bf3d7b6bb21340ff9789cb7b6c10be47a3197df4f394e8da73129feeb5b8439d9401f5e83b8620e0a512fce966c891377
+  data.tar.gz: 58f1514450a234f3807897401daf7db410739463a8603bf58b7d73e548f14424211b4d1c5f3af1dc7421b769f39582e15c6f22188932af3de054961eed2cb641

data/examples/pizzas/bluebook/hecksagon/mock_stripe_payment_adapter.rb

@@ -0,0 +1,36 @@
+#!/usr/bin/env ruby
+
+# Driving adapter standing in for a Stripe webhook handler: boots Pizzas and calls
+# Dispatcher#dispatch_port, which translates the payment into PizzaPaymentReceived.
+#
+#   examples/pizzas/bluebook/hecksagon/mock_stripe_payment_adapter.rb
+
+$LOAD_PATH.unshift File.expand_path("../../../../lib", __dir__)
+
+require "hecks"
+
+DOMAIN  = File.expand_path("../..", __dir__)
+RUNTIME = Hecks.boot(DOMAIN)
+
+# Unique per run: identity is never minted, so a repeated name would be refused as AlreadyExists.
+NAME = "StripeDemoMargherita-#{Process.pid}-#{rand(10_000)}".freeze
+
+# Set the stage: an order Purchase's `given` rules will accept.
+order = Order.create_pizza(name: { value: NAME }, pizza: { price_cents: { cents: 1200 }, size: { value: "large" } })
+order.add_topping(topping: { value: "Basil" }, amount: { value: 3 })
+
+puts "Before payment: #{order.status}, customer=#{order.customer_name.inspect}"
+
+# The webhook: a real handler would verify a Stripe signature; a reference is always a bare id.
+RUNTIME.dispatch_port(
+  "Pizzas", "Order", "PaymentGateway", "Receive",
+  flat: {
+    name:          NAME,
+    customer_name: { value: "Chris" },
+    amount:        { cents: 1200 }
+  }
+)
+
+sold = Order.find(NAME)
+puts "After payment:  #{sold.status}, customer=#{sold.customer_name.to_h}"
+puts "Events: #{sold.events.map(&:name).join(', ')}"

data/examples/pizzas/bluebook/pizzas.behaviors

@@ -0,0 +1,70 @@
+Hecks.behaviors "Pizzas" do
+  vision "Examples of how a pizza is built, sold, and found through this domain."
+
+  # `pizzas_behaviors.hecksagon` is a Memory-persisted sibling of
+  # `pizzas.hecksagon` that lives OUTSIDE bluebook/, so an ordinary
+  # directory boot of examples/pizzas never globs it up alongside the
+  # real one.
+  loads "pizzas.bluebook", "../pizzas_behaviors.hecksagon"
+
+  test "CreatePizza puts a fresh pizza on the menu, available for sale" do
+    tests "CreatePizza", on: "Order"
+    input  name: "Margherita", pizza: { price_cents: { cents: 1200 }, size: "large" }
+    expect status: "available", customer_name: nil
+  end
+
+  test "AddTopping refuses more than ten toppings" do
+    tests "AddTopping", on: "Order"
+    setup  "CreatePizza", name: "Loaded", pizza: { price_cents: { cents: 1500 }, size: "large" }
+    setup  "AddTopping",  name: "Loaded", topping: "Basil",     amount: 1
+    setup  "AddTopping",  name: "Loaded", topping: "Olives",    amount: 1
+    setup  "AddTopping",  name: "Loaded", topping: "Mushroom",  amount: 1
+    setup  "AddTopping",  name: "Loaded", topping: "Onion",     amount: 1
+    setup  "AddTopping",  name: "Loaded", topping: "Pepper",    amount: 1
+    setup  "AddTopping",  name: "Loaded", topping: "Sausage",   amount: 1
+    setup  "AddTopping",  name: "Loaded", topping: "Bacon",     amount: 1
+    setup  "AddTopping",  name: "Loaded", topping: "Pineapple", amount: 1
+    setup  "AddTopping",  name: "Loaded", topping: "Anchovy",   amount: 1
+    setup  "AddTopping",  name: "Loaded", topping: "Jalapeno",  amount: 1
+    input  name: "Loaded", topping: "Extra Cheese", amount: 1
+    expect refused: "at most 10 toppings"
+  end
+
+  test "Purchase refuses a pizza with no toppings on it" do
+    tests "Purchase", on: "Order"
+    setup  "CreatePizza", name: "Bare", pizza: { price_cents: { cents: 900 }, size: "small" }
+    input  name: "Bare", customer_name: "Chris", amount: { cents: 900 }
+    expect refused: "at least one topping"
+  end
+
+  test "Purchase sells the pizza and closes its lifecycle" do
+    tests "Purchase", on: "Order"
+    setup  "CreatePizza", name: "Sold Out", pizza: { price_cents: { cents: 1200 }, size: "large" }
+    setup  "AddTopping",  name: "Sold Out", topping: "Basil", amount: 2
+    input  name: "Sold Out", customer_name: "Chris", amount: { cents: 1200 }
+    expect emits: ["PizzaPurchased"]
+  end
+
+  test "a sold pizza is no longer Available" do
+    tests "Available", on: "Order", kind: :query
+    setup  "CreatePizza", name: "Fresh",     pizza: { price_cents: { cents: 1000 }, size: "small" }
+    setup  "CreatePizza", name: "Also Sold", pizza: { price_cents: { cents: 1100 }, size: "small" }
+    setup  "AddTopping",  name: "Also Sold", topping: "Basil", amount: 1
+    setup  "Purchase",    name: "Also Sold", customer_name: "Chris", amount: { cents: 1100 }
+    expect count: 1
+  end
+
+  test "CostingLessThan finds a pizza under the ceiling named" do
+    tests "CostingLessThan", on: "Order", kind: :query
+    setup  "CreatePizza", name: "Bargain", pizza: { price_cents: { cents: 800 }, size: "small" }
+    setup  "CreatePizza", name: "Splurge", pizza: { price_cents: { cents: 1800 }, size: "large" }
+    input  ceiling: { cents: 1000 }
+    expect count: 1
+  end
+
+  test "Available's own row can be checked directly, not just counted" do
+    tests "Available", on: "Order", kind: :query
+    setup  "CreatePizza", name: "Only One", pizza: { price_cents: { cents: 950 }, size: "small" }
+    expect status: "available", name: { value: "Only One" }
+  end
+end

data/examples/pizzas/bluebook/pizzas.bluebook

@@ -0,0 +1,138 @@
+Hecks.bluebook "Pizzas" do
+  vision "Put toppings on a pizza and sell it to a customer."
+  supporting
+
+  aggregate "Order" do
+    description "An order that gathers toppings on a pizza and is eventually sold to a customer."
+
+    attribute :name,          PizzaName
+    attribute :pizza,         Pizza
+    attribute :toppings,      list_of(Topping)
+    # Optional: unknown until `Purchase` sets it.
+    attribute :customer_name, CustomerName, optional: true
+
+    identified_by :name
+
+    value_object "PizzaName" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a pizza is named") { !value.to_s.empty? }
+    end
+
+    value_object "Price" do
+      attribute :cents, Integer
+
+      invariant("a price is never negative") { cents >= 0 }
+    end
+
+    value_object "CustomerName" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a customer is named") { !value.to_s.empty? }
+    end
+
+    value_object "ToppingName" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+
+      invariant("a topping is named") { !value.to_s.empty? }
+    end
+
+    value_object "ToppingAmount" do
+      attribute :value, Integer
+
+      invariant("an amount is positive") { value.positive? }
+    end
+
+    value_object "Topping" do
+      attribute :name,   String, pattern: '[^ \t\n\r]'
+      attribute :amount, Integer
+    end
+
+    # A named, reusable closed set as a sibling value object; the inline `one_of(...)` shorthand
+    # cannot be spelled inside a `value_object` block.
+    value_object "Size" do
+      attribute :value, String, one_of: ["small", "large"]
+    end
+
+    # What was ordered; who ordered it and payment state live on Order.
+    value_object "Pizza" do
+      attribute :price_cents, Price
+      attribute :size,        Size
+    end
+
+    lifecycle :status, default: "available" do
+      transition "Purchase" => "sold", from: "available"
+    end
+
+    query "Available" do
+      where(status: "available")
+      order_by :name
+    end
+
+    # Both price queries reach through the nested Pizza value object with a dotted path.
+    query "CostingLessThan" do
+      attribute :ceiling, Price
+      where(:"pizza.price_cents.cents" => { lt: :ceiling })
+      order_by :name
+    end
+
+    # A literal, not a kwarg: exercises the path where the where-clause number is stringified.
+    query "Expensive" do
+      where(:"pizza.price_cents.cents" => { gt: 1000 })
+      order_by :name
+    end
+
+    command "CreatePizza" do
+      role "Chef"
+      goal "Put a new pizza on the menu"
+
+      attribute :name,  PizzaName
+      attribute :pizza, Pizza
+
+      sets :name
+      sets :pizza
+
+      emits PizzaCreated
+    end
+
+    # AddTopping has no transition, so `from:` is its only lifecycle guard.
+    command "AddTopping", from: "available" do
+      role "Chef"
+      goal "Customize a pizza with an ingredient"
+
+      reference_to Order
+      attribute :topping, ToppingName
+      attribute :amount, ToppingAmount
+
+      given("at most 10 toppings")            { toppings.size < 10 }
+
+      sets :toppings, append: { name: :topping, amount: :amount }
+
+      emits ToppingAdded
+    end
+
+    command "Purchase", from: "available" do
+      role "Customer"
+      goal "Buy the pizza"
+
+      reference_to Order
+      attribute :amount, Price
+
+      given("a pizza needs at least one topping") { toppings.size.positive? }
+      given("a payment was actually made")         { amount.cents.positive? }
+      # Checks the payment itself is plausible (e.g. an underpayment), not whether one happened.
+      given("the payment covers the price") { amount.cents >= pizza.price_cents.cents }
+
+      # The lifecycle transition sets status; a `sets` on the lifecycle field is refused at build.
+      sets :customer_name
+
+      emits PizzaPurchased
+    end
+  end
+
+  # A payment arriving is an external fact; the business rules stay on Purchase.
+  policy "OnPizzaPaymentReceived" do
+    on Order::PizzaPaymentReceived
+    trigger Order::Purchase
+  end
+end

data/examples/pizzas/bluebook/pizzas.hecksagon

@@ -0,0 +1,21 @@
+Hecks.hecksagon "Pizzas" do
+  # Role declarations only enforce access once Governance can check them; this standalone
+  # deploy attaches and binds Governance itself.
+  attaches "Governance"
+  Pizzas::Order.persisted_by("Memory")
+
+  # The primary port: an outside adapter (a payment webhook) translates an external fact into
+  # our vocabulary; business rules stay on Purchase, reached via OnPizzaPaymentReceived.
+  Pizzas::Order.port "PaymentGateway" do
+    operation "Receive" do
+      attribute :customer_name, CustomerName
+      attribute :amount, Price
+      emits "PizzaPaymentReceived"
+    end
+  end
+end
+
+Hecks.hecksagon "Governance" do
+  Governance::RoleAssignment.persisted_by("Memory")
+  Governance::RoleTransition.persisted_by("Memory")
+end

data/examples/pizzas/bluebook/pizzas.world

@@ -0,0 +1,3 @@
+Hecks.world "Pizzas" do
+  realm "Examples"
+end

data/examples/pizzas/bluebook/translations/2-77625c.bluebook

@@ -0,0 +1,6 @@
+Hecks.data_translation "Pizzas", from: "e3f3d7", to: "77625c" do
+  aggregate "Order", was: "Pizza" do
+    move :price_cents, to: "pizza.price_cents"
+    move :size,         to: "pizza.size"
+  end
+end

data/examples/pizzas/oidc.json

@@ -0,0 +1,24 @@
+{
+  "audience": "Pizzas",
+  "scopes": [
+    {
+      "scope": "pizzas:order.add_topping",
+      "verb": "Pizzas::Order.AddTopping",
+      "role": "Chef"
+    },
+    {
+      "scope": "pizzas:order.create_pizza",
+      "verb": "Pizzas::Order.CreatePizza",
+      "role": "Chef"
+    },
+    {
+      "scope": "pizzas:order.purchase",
+      "verb": "Pizzas::Order.Purchase",
+      "role": "Customer"
+    }
+  ],
+  "roles": [
+    "Chef",
+    "Customer"
+  ]
+}

data/examples/pizzas/pizzas_behaviors.hecksagon

@@ -0,0 +1,19 @@
+# Memory-bound sibling of pizzas.hecksagon: `pizzas.behaviors` boots a fresh runtime per
+# test, so it loads this sibling instead of the one beside the bluebook.
+Hecks.hecksagon "Pizzas" do
+  attaches "Governance"
+  Pizzas::Order.persisted_by("Memory")
+
+  Pizzas::Order.port "PaymentGateway" do
+    operation "Receive" do
+      attribute :customer_name, CustomerName
+      attribute :amount, Price
+      emits "PizzaPaymentReceived"
+    end
+  end
+end
+
+Hecks.hecksagon "Governance" do
+  Governance::RoleAssignment.persisted_by("Memory")
+  Governance::RoleTransition.persisted_by("Memory")
+end

data/lib/hecks/cli/console.rb

@@ -47,12 +47,15 @@ module Hecks
       end
 
       # @param runtime [Runtime] a booted domain
-      # @return [String] each chapter's vision and its aggregates' commands
+      # @return [String] each chapter's vision, and its aggregates' descriptions and commands
       def overview(runtime)
         runtime.registry.bluebooks.each_value.map do |bluebook|
           aggregates = bluebook.aggregates.map do |aggregate|
             commands = aggregate.commands.map { |command| "#{Naming.snake(command.hecks_name)}!" }.sort.join(", ")
-            "    #{aggregate.name}: #{commands}"
+            description = aggregate.description.to_s.strip
+            lines = ["    #{aggregate.name}: #{commands}"]
+            lines << "      #{description}" unless description.empty?
+            lines.join("\n")
           end
 
           "\n    #{bluebook.name} — #{bluebook.vision}\n#{aggregates.join("\n")}\n"

data/lib/hecks/doors/cli_runner.rb

@@ -120,6 +120,7 @@ module Hecks
 
         name = argv.first
         return { answer: [cli[:usage], 0] } if name.nil? || %w[--help -h help].include?(name)
+        return { answer: [all_usage(bluebook, options), 0] } if name == "--all"
 
         asking, name, argv = entry_word(cli, argv)
         return { answer: [cli[:usage], 1] } if name.nil?
@@ -141,6 +142,11 @@ module Hecks
           launcher: launcher }
       end
 
+      # The usage with the internal commands and queries listed too, which `--all` asks for.
+      def all_usage(bluebook, options)
+        Projector.call(:cli, bluebook: bluebook, options: options.merge(all: true))[:usage]
+      end
+
       # Reads the entry words of a line: whether it asks a query, the bare name, and the words
       # from the name on.
       #

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

@@ -79,7 +79,7 @@ module Hecks
             :infra_name, :stack_prefix, :instance_type, :volume_gb, :swap_gb, :database_class,
             :storage_gb, :backup_days, :snapshots_keep, :database_name, :engine_version,
             :containers, :routes, :default_container, :origin_header, :origin_secret,
-            :secret_prefixes, :tunnel, :tunnel_service, :proxy_image, :task_definition,
+            :secret_prefixes, :writable_secrets, :tunnel, :tunnel_service, :proxy_image, :task_definition,
             :migration, :s3_buckets, keyword_init: true
           ) do
             # @return [String] the CloudFormation stack that holds the database
@@ -119,6 +119,7 @@ module Hecks
               containers: containers, routes: read_routes(s.fetch(:routes, []), containers),
               default_container: read_default(s[:default_container], containers), origin_header: header,
               origin_secret: secret, secret_prefixes: read_prefixes(s, infra_name),
+              writable_secrets: read_writable_secrets(s),
               tunnel: tunnel, tunnel_service: tunnel_service,
               proxy_image: check(:proxy_image, s.fetch(:proxy_image, PROXY_IMAGE), IMAGE),
               task_definition: task_definition, migration: read_migration(s[:migration], database_name),
@@ -283,6 +284,12 @@ module Hecks
             list.map { |p| check(:secret_prefixes, p, SECRET_NAME) }
           end
 
+          # Secrets the box may overwrite, such as one an admin page stores a key in. Production
+          # only: a rehearsal box never changes a secret.
+          def read_writable_secrets(settings)
+            Array(settings.fetch(:writable_secrets, [])).map { |name| check(:writable_secrets, name, SECRET_NAME) }
+          end
+
           def string_map(key, value, key_pattern, value_pattern)
             raise ArgumentError, "#{key}: expected a hash" unless value.is_a?(Hash)
 

data/lib/hecks/projections/deploy/box/templates/box.yaml.tmpl

@@ -104,6 +104,7 @@ Resources:
                 Resource:
                   - !Ref DbSecretArn
 @@SECRET_RESOURCES@@
+@@WRITABLE_SECRETS@@
 @@S3_POLICY@@
 
   BoxProfile:

data/lib/hecks/projections/deploy/box/templates/deploy-box.sh.tmpl

@@ -18,6 +18,19 @@ DB_SECRET=$(out "$RDS_STACK" DbSecretArn)
 ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
 
 WORK=$(mktemp -d); trap 'rm -rf "$WORK"' EXIT
+
+# SMOKE_LISTENER=1 (a rehearsal box only) mounts a loopback HTTPS site on 127.0.0.1:8443 that adds the
+# origin secret, so a browser-driven smoke run can reach the box through an SSM port-forward without the
+# CDN. TLS because a site that treats a request carrying the origin secret as https expects an https
+# Origin on every form post.
+cat > "$WORK/smoke.caddy" <<'SMOKE_EOF'
+https://127.0.0.1:8443 {
+	tls internal
+	reverse_proxy 127.0.0.1:80 {
+@@SMOKE_HEADER@@
+	}
+}
+SMOKE_EOF
 ( cd "$WORK" && bash "$HERE/render-compose.sh" "$DB_HOST" "$DB_SECRET" "$@" )
 
 # Run a script on the box over SSM, wait for it, print its output, return its status.
@@ -38,12 +51,14 @@ run_on_box() {
 B64() { base64 < "$1" | tr -d '\n'; }
 ROLL=$(jq -n --arg compose "$(B64 "$WORK/compose.json")" --arg secrets "$(B64 "$WORK/secrets.json")" \
   --arg caddy "$(B64 "$HERE/Caddyfile")" --arg fetch "$(B64 "$HERE/fetch-secrets.sh")" \
+  --arg smokefile "$(B64 "$WORK/smoke.caddy")" --arg smoke "${SMOKE_LISTENER:-}" \
   --arg registry "$ACCOUNT.dkr.ecr.$REGION.amazonaws.com" --arg dir "$DIR" '
   {commands: ["cloud-init status --wait >/dev/null 2>&1 || true",
     "set -e", "mkdir -p \($dir)/caddy-extra && cd \($dir)", "umask 077",
     "echo \($compose) | base64 -d > compose.json; echo \($secrets) | base64 -d > secrets.json",
     "echo \($caddy) | base64 -d > Caddyfile; echo \($fetch) | base64 -d > fetch-secrets.sh",
     "bash fetch-secrets.sh",
+    (if $smoke == "1" then "echo \($smokefile) | base64 -d > caddy-extra/smoke.caddy" else "rm -f caddy-extra/smoke.caddy" end),
     "aws ecr get-login-password --region '"$REGION"' | docker login --username AWS --password-stdin \($registry) >/dev/null",
     "docker compose -f compose.json pull --quiet",
     "docker compose -f compose.json up -d --remove-orphans",

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

@@ -196,7 +196,8 @@ module Hecks
                    "VOLUME_GB" => plan.volume_gb.to_s, "SNAPSHOTS_KEEP" => plan.snapshots_keep.to_s,
                    "AMI_PARAMETER" => ami_parameter(plan.instance_type),
                    "COMPUTE_DOMAIN" => compute_domain(region),
-                   "SECRET_RESOURCES" => secret_resources(plan), "TUNNEL_EGRESS" => tunnel_egress(plan),
+                   "SECRET_RESOURCES" => secret_resources(plan), "WRITABLE_SECRETS" => writable_secrets(plan),
+                   "TUNNEL_EGRESS" => tunnel_egress(plan),
                    "SWAP_COMMANDS" => swap_commands(plan), "ECR_REPOSITORIES" => ecr_repositories(plan),
                    "ECR_OUTPUTS" => ecr_outputs(plan), "S3_POLICY" => s3_policy(plan))
         end
@@ -261,6 +262,28 @@ module Hecks
           end.join.chomp
         end
 
+        # The statement that lets a production box overwrite the secrets named as writable.
+        #
+        # @param plan [Settings::Plan] the resolved settings
+        # @return [String] a policy statement for the role, or nothing when none are declared
+        def writable_secrets(plan)
+          return "" if plan.writable_secrets.empty?
+
+          arns = plan.writable_secrets.map { |name| name.end_with?("*") ? name : "#{name}-*" }.uniq
+          resources = arns.map do |pattern|
+            "#{' ' * 20}- !Sub \"arn:${AWS::Partition}:secretsmanager:${AWS::Region}:${AWS::AccountId}:secret:#{pattern}\"\n"
+          end.join
+          <<~YAML.chomp
+            #{' ' * 14}- !If
+            #{' ' * 16}- IsProduction
+            #{' ' * 16}- Effect: Allow
+            #{' ' * 18}Action: secretsmanager:PutSecretValue
+            #{' ' * 18}Resource:
+            #{resources.chomp}
+            #{' ' * 16}- !Ref AWS::NoValue
+          YAML
+        end
+
         # @param plan [Settings::Plan] the resolved settings
         # @return [String] the outbound rules a Cloudflare Tunnel sidecar needs, or nothing
         def tunnel_egress(plan)
@@ -437,7 +460,14 @@ module Hecks
           template("deploy-box.sh.tmpl", "STACK" => plan.infra_name, "BOX_STACK" => plan.box_stack,
                                          "RDS_STACK" => plan.rds_stack, "REGION" => region,
                                          "DIR" => "/opt/#{plan.infra_name}", "HEALTH_CHECKS" => health_checks(plan),
-                                         "USAGE" => deploy_usage(plan))
+                                         "SMOKE_HEADER" => smoke_header(plan), "USAGE" => deploy_usage(plan))
+        end
+
+        # @param plan [Settings::Plan] the resolved settings
+        # @return [String] the line that adds the origin secret to the smoke listener's requests, or
+        #   nothing when the world has no origin guard
+        def smoke_header(plan)
+          plan.origin_header ? "\t\theader_up #{plan.origin_header} {$ORIGIN_SECRET}" : ""
         end
 
         # @param plan [Settings::Plan] the resolved settings

data/lib/hecks/projections/deploy/scripts/hosting.mk.tmpl

@@ -8,11 +8,15 @@
 # machine. It replaces any path to a working copy: ROOT below points the
 # Makefile's build and mint-era steps at it. Override HECKS_VERSION to build
 # from another release, or HECKS_ROOT to use a checkout you manage yourself.
+#
+# HECKS_VERSION=edge is the one exception to "pinned": it follows the newest commit on main,
+# is fetched afresh on every build, and prints the commit it got.
 
 HECKS_VERSION   ?= @@RELEASE@@
 HECKS_SOURCE    ?= @@SOURCE@@
 HECKS_CACHE_DIR ?= @@CACHE_DIR@@
 HECKS_ROOT      ?= $(HECKS_CACHE_DIR)/hecks-$(HECKS_VERSION)
+HECKS_TAG       := $(if $(filter edge,$(HECKS_VERSION)),edge,v$(HECKS_VERSION))
 ROOT            := $(HECKS_ROOT)
 SERVICE         ?= @@SERVICE@@
 URL             ?= @@URL@@
@@ -22,20 +26,32 @@ URL             ?= @@URL@@
 build: hecks-release
 
 # Fetches the pinned release's tag into HECKS_ROOT unless it is already there,
-# and refuses a checkout that is not exactly that tag.
+# and refuses a checkout that is not exactly that tag. The edge tag moves, so it is
+# fetched afresh on every build and its commit is printed, not checked.
 hecks-release:
+ifeq ($(HECKS_VERSION),edge)
+	@mkdir -p "$(HECKS_CACHE_DIR)"; \
+		if [ -d "$(HECKS_ROOT)/.git" ]; then \
+			git -C "$(HECKS_ROOT)" fetch --quiet --depth 1 origin "+refs/tags/edge:refs/tags/edge" && \
+			git -C "$(HECKS_ROOT)" checkout --quiet --detach edge; \
+		else \
+			git clone --quiet --depth 1 --branch edge "$(HECKS_SOURCE)" "$(HECKS_ROOT)"; \
+		fi; \
+		echo "hecks edge at $$(git -C "$(HECKS_ROOT)" rev-parse --short HEAD) in $(HECKS_ROOT)"
+else
 	@if [ -f "$(HECKS_ROOT)/exe/hecks" ]; then \
 		echo "hecks v$(HECKS_VERSION) is already at $(HECKS_ROOT)"; \
 	else \
 		echo "Fetching hecks v$(HECKS_VERSION) from $(HECKS_SOURCE) into $(HECKS_ROOT)..."; \
 		mkdir -p "$(HECKS_CACHE_DIR)" && \
-		git clone --quiet --depth 1 --branch "v$(HECKS_VERSION)" "$(HECKS_SOURCE)" "$(HECKS_ROOT)"; \
+		git clone --quiet --depth 1 --branch "$(HECKS_TAG)" "$(HECKS_SOURCE)" "$(HECKS_ROOT)"; \
 	fi
 	@tag="$$(git -C "$(HECKS_ROOT)" describe --tags --exact-match 2>/dev/null)"; \
-		if [ "$$tag" != "v$(HECKS_VERSION)" ]; then \
-			echo "$(HECKS_ROOT) is at '$$tag', not v$(HECKS_VERSION). Remove it and re-run, or set HECKS_ROOT."; \
+		if [ "$$tag" != "$(HECKS_TAG)" ]; then \
+			echo "$(HECKS_ROOT) is at '$$tag', not $(HECKS_TAG). Remove it and re-run, or set HECKS_ROOT."; \
 			exit 1; \
 		fi
+endif
 
 # Pushes one container's already-built local image under a fresh tag and rolls
 # it out. Build the image first (docker-build); see deploy-service.sh.

data/lib/hecks/projections/deploy/scripts/settings.rb

@@ -12,6 +12,8 @@ module Hecks
           REF       = %r{\A[\w./-]+\z}
           ERA       = /\A[0-9a-zA-Z._-]+\z/
           RELEASE   = /\Av?\d+\.\d+\.\d+([.-][0-9A-Za-z.-]+)?\z/
+          # The moving tag on main; the one release name that is not a version.
+          EDGE      = "edge".freeze
           SOURCE    = %r{\A[\w.@:/~-]+\z}
           MAKE_PATH = /\A[^\s#]+\z/
 
@@ -43,6 +45,8 @@ module Hecks
             release = fetch(:hecks_release, nil)
             raise ArgumentError, missing_release_message unless release
 
+            return EDGE if release.to_s == EDGE
+
             check(:hecks_release, release.to_s, RELEASE).delete_prefix("v")
           end
 
@@ -63,6 +67,8 @@ module Hecks
                   end
 
               so the domain image is built from a fixed Hecks release, not from a checkout on one machine.
+              `hecks_release "edge"` follows the newest commit on main instead: each build fetches it
+              afresh and prints the commit it got, so a build is not reproducible from the name alone.
             MSG
           end