hecks 3.0.4 → 3.1.0

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

@@ -109,7 +109,7 @@ module Hecks
           webhook_handler_module = deploy_settings.fetch(:handler_module, "WebLambdaHandler")
 
           # Scans every loaded chapter, not just this domain's own — a
-          # `uses_framework`-attached chapter can itself declare a cross-domain
+          # `attaches`-attached chapter can itself declare a cross-domain
           # policy, including one nested inside `aggregate "X" do ... end`.
           cross_domain_lambda_targets = cross_domain_registry.bluebooks.flat_map { |chapter_name, bluebook|
             bluebook.policies.select(&:target_domain).map(&:target_domain)
@@ -909,8 +909,8 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
               # settings -- the exact same call this target runs automatically
               # for a domain with its own dedicated instance.
               #
-              # IF THIS DOMAIN VENDORS/ATTACHES ANOTHER BLUEBOOK (uses_embryonaut_
-              # bluebook, uses_framework), `check!` alone leaves THAT chapter's own
+              # IF THIS DOMAIN VENDORS/ATTACHES ANOTHER BLUEBOOK (attaches,
+              # attaches ... from: :vendor), `check!` alone leaves THAT chapter's own
               # aggregates with no snapshot table at all -- it only provisions the
               # ONE bluebook it's called with (era_resolver.rb's own `bluebook.
               # aggregates.each`), never the whole registry. Found live minting
@@ -998,7 +998,7 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
               # hecks_eras at all. The fix reuses the SAME loading pipeline
               # `Loader.boot` itself does (`Ports::Loading.bootstrap`/
               # `load_library`/`load_project`/`load_domain`) to build a real,
-              # fully-loaded registry (bluebook + any uses_framework attachments),
+              # fully-loaded registry (bluebook + any attaches attachments),
               # then calls straight into PostgresEra's own `LineageManager.check!`
               # with THIS deploy's actual `DATABASE_URL` — bypassing the world
               # file's own adapter choice entirely, the same targeted pattern
@@ -1072,7 +1072,8 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
             end
 
           # Shares mint_era_recipe's bastion/tunnel/retry/teardown chain but
-          # runs `hecks ask scaffold_translation` or `hecks ask audit_translation` over it.
+          # runs `hecks query era.scaffold_translation` or
+          # `hecks query era.audit_translation` over it.
           #
           # Neither script actually reads DATABASE_URL/HECKS_SCHEMA (both call
           # `registry.binding_settings`, a lookup against the literal `database
@@ -1147,12 +1148,12 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
 
           # `hecks ask` answers the scaffold as text, and refuses (exit 1) where the script aborted.
           scaffold_translation_recipe = translation_recipe.call(
-            "scaffold-translation", "exe/hecks ask scaffold_translation", db_env_blind: true,
+            "scaffold-translation", "exe/hecks query era.scaffold_translation", db_env_blind: true,
             run_prefix: "HECKS_ENVIRONMENT=memory ruby", domain_arg: "domain=$(DOMAIN) "
           )
           # A refused audit is a refused query: `hecks ask` exits 1, so the target fails too.
           translation_audit_recipe = translation_recipe.call(
-            "translation-audit", "exe/hecks ask audit_translation", db_env_blind: true,
+            "translation-audit", "exe/hecks query era.audit_translation", db_env_blind: true,
             run_prefix: "HECKS_ENVIRONMENT=memory ruby", domain_arg: "domain=$(DOMAIN) "
           )
 
@@ -1393,7 +1394,7 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
             # field). `hecks build_wasm` recompiles fast enough that "always
             # rebuild" is the safe default, matching rust/host's own bootstrap
             # build just below, which was never guarded this way to begin with.
-            \tcd #{root} && HECKS_ENVIRONMENT=memory ruby exe/hecks build_wasm domain=#{domain} --wait
+            \tcd #{root} && HECKS_ENVIRONMENT=memory ruby exe/hecks build.build_wasm domain=#{domain} --wait
             \t@rustup target list --installed 2>/dev/null | grep -qx aarch64-unknown-linux-gnu || rustup target add aarch64-unknown-linux-gnu
             # `rustup run stable`, not a bare `cargo lambda` — same reasoning
             # `hecks build_wasm`'s own Makefile-equivalent line holds itself to: a
@@ -1495,12 +1496,12 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
             .PHONY: verify-parity-#{logical_id}
             verify-parity-#{logical_id}:
             \t@if [ -f #{root}/spec/corpus/#{domain_name}.json ]; then \\
-            \t\tcd #{root} && HECKS_ENVIRONMENT=memory ruby exe/hecks check_conformance domain=#{domain} script=spec/corpus/#{domain_name}.json artifact=$(WASM) --wait; \\
+            \t\tcd #{root} && HECKS_ENVIRONMENT=memory ruby exe/hecks build.check_conformance domain=#{domain} script=spec/corpus/#{domain_name}.json artifact=$(WASM) --wait; \\
             \telse \\
             \t\techo "verify-parity-#{logical_id}: no spec/corpus/#{domain_name}.json -- SKIPPING the pre-deploy Ruby/Rust parity check, nothing to compare $(WASM) against. Write one (hecks fuzz/hecks run's own script shape) before this domain's next deploy."; \\
             \tfi
             \t@echo "verify-parity-#{logical_id}: fuzzing $(WASM) against generated sequences (ADR 0037's bridge, WARN-ONLY -- see this target's own comment)..."
-            \t-@cd #{root} && HECKS_ENVIRONMENT=memory ruby exe/hecks fuzz_conformance domain=#{domain} artifact=$(WASM) --wait
+            \t-@cd #{root} && HECKS_ENVIRONMENT=memory ruby exe/hecks build.fuzz_conformance domain=#{domain} artifact=$(WASM) --wait
 
             # `make mint-era` — takes #{stack_name}'s RDS instance from freshly
             # created to "era 1 minted, ready for HECKS_DOMAIN/HECKS_ERA to

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

@@ -51,4 +51,4 @@ smoke-after-deploy:
 # Compares the era a live host reports at GET /version with expected-era.
 check-era:
 	@test -n "$(URL)" || { echo "usage: make check-era URL=https://host.example"; exit 1; }
-	HECKS_ENVIRONMENT=memory ruby "$(HECKS_ROOT)/exe/hecks" check_era host="$(URL)" expected=expected-era --wait
+	HECKS_ENVIRONMENT=memory ruby "$(HECKS_ROOT)/exe/hecks" host.check_era host="$(URL)" expected=expected-era --wait

data/lib/hecks/projections/diagrams.rb

@@ -306,12 +306,12 @@ module Hecks
       def frameworks_diagram(bluebook, hecksagon)
         return nil unless hecksagon
 
-        lines = hecksagon.framework_members.map { |name| domain_edge(bluebook.name, "attaches", name, dotted: true) }
+        lines = hecksagon.member_chapters.map { |name| domain_edge(bluebook.name, "attaches", name, dotted: true) }
         lines += bluebook.policies.filter_map(&:target_domain).uniq
                          .map { |name| domain_edge(bluebook.name, "reaches across", name, dotted: false) }
         return nil if lines.empty?
 
-        subject = "#{bluebook.name}'s own declared uses_framework and cross-domain policy targets"
+        subject = "#{bluebook.name}'s own declared attaches and cross-domain policy targets"
         "#{header(bluebook.name, subject)}flowchart LR\n#{lines.uniq.join("\n")}\n"
       end
 

data/lib/hecks/projections/site/edge/behaviours.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      class Edge
+        # The CloudFront behaviours a route table needs.
+        #
+        # Each route through the CDN resolves to the behaviour its origin, cache class, methods and
+        # compression give it. A route needs none of its own when the behaviour that would match its
+        # path anyway (the nearest broader route's, else the default one) is the same. The rest keep
+        # the order the table declares, which is the order CloudFront matches in, and a route that
+        # a broader, different one before it would shadow is refused.
+        class Behaviours
+          # The default behaviour's path: the row that holds the settings of everything else.
+          DEFAULT_PATH = "/*"
+
+          # @param edge [Edge] the edge being built; its rows are set
+          # @param rows [Array<Table::Row>] the route table's rows
+          # @param problems [Array<String>] collects each problem found, one line each
+          def initialize(edge, rows, problems)
+            @edge = edge
+            @rows = rows
+            @problems = problems
+          end
+
+          # @return [Hash{Symbol => Object}] `:default` the default behaviour and `:list` the
+          #   others, each as `Cdn.behavior_lines` takes it, `:path` set on those of the list
+          def call
+            candidates = resolved
+            default = candidates.delete(DEFAULT_PATH) || {}
+            kept = candidates.reject { |pattern, entry| same?(nearest_cover(candidates, pattern, default), entry) }
+            check_order(kept.values)
+            { default: default.except(:path), list: kept.values }
+          end
+
+          private
+
+          def same?(one, other) = one.except(:path) == other.except(:path)
+
+          # Each CDN route's edge pattern to its behaviour; rows on one pattern with different verbs
+          # share it, their methods united.
+          def resolved
+            groups = @rows.select(&:cdn).group_by { |row| Pattern.edge(row.path) }
+            groups.to_h do |pattern, rows|
+              entries = rows.map { |row| entry(row, pattern) }
+              disagree = entries.map { |entry| entry.except(:methods) }.uniq.size > 1
+              problem(pattern, "is declared by #{rows.size} routes that resolve to different behaviours") if disagree
+              [pattern, entries.first.merge(methods: methods(rows))]
+            end
+          end
+
+          def entry(row, pattern)
+            policy = @edge.policy(row.cache, row.origin)
+            {
+              path: pattern, origin: @edge.upstream(row.origin).id, methods: methods([row]),
+              viewer_protocol: protocol(row), compress: row.compress,
+              cache_policy: Checks.resolve(policy.cache),
+              origin_request_policy: reference(policy.origin_request),
+              response_headers_policy: reference(policy.response_headers)
+            }
+          end
+
+          def reference(text) = text.nil? || text == "none" ? nil : Checks.resolve(text)
+
+          # CloudFront takes three sets of methods: read, read with `OPTIONS`, and all.
+          def methods(rows)
+            verbs = rows.flat_map(&:verbs).uniq
+            return Deploy::Fargate::Cdn::METHODS.fetch("all") unless (verbs - ["GET"]).empty?
+
+            assets = rows.all? { |row| row.origin == "assets" }
+            Deploy::Fargate::Cdn::METHODS.fetch(assets ? "get_head" : "read")
+          end
+
+          # A public page that is only read, from the website or the assets, may be asked for over
+          # http and redirected; anything else (a form, an API, a signed or admin page, a route of
+          # the cms or the domain) is served over https only.
+          def protocol(row)
+            plain = row.auth == "public" && row.verbs == ["GET"] && %w[website assets].include?(row.origin)
+            plain ? "redirect-to-https" : "https-only"
+          end
+
+          # The behaviour CloudFront would match for `pattern` were it not in the list: that of the
+          # most specific broader pattern, else the default behaviour.
+          def nearest_cover(candidates, pattern, default)
+            covers = candidates.keys.select { |other| Pattern.strictly_covers?(other, pattern) }
+            nearest = covers.find { |one| covers.none? { |other| Pattern.strictly_covers?(one, other) } }
+            nearest ? candidates.fetch(nearest) : default
+          end
+
+          def check_order(list)
+            list.each_with_index do |later, index|
+              list.first(index).each do |earlier|
+                next unless Pattern.strictly_covers?(earlier[:path], later[:path]) && !same?(earlier, later)
+
+                problem(later[:path], "is shadowed by #{earlier[:path]}, which comes first and matches it; " \
+                                      "declare #{later[:path]} before #{earlier[:path]}")
+              end
+            end
+          end
+
+          def problem(label, text) = @problems << "#{label} #{text}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/edge/checks.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      class Edge
+        # What the edge rows must satisfy before anything is built from them: each reference is to a
+        # thing that exists, no two rows claim one name or priority, and every route the edge serves
+        # has the origin, the policy and, for a server behind the load balancer, the rule it needs.
+        class Checks
+          LOGICAL_ID = /\A[A-Za-z][A-Za-z0-9]*\z/
+          INTRINSIC = /\A!(Ref|ImportValue|Sub|GetAtt)\s+\S/
+          PRIORITIES = (1..50_000)
+
+          # The id a policy reference names, or nil when it names none.
+          #
+          # @param reference [String] a managed policy name, an id, or an intrinsic
+          # @return [Array<String>, nil] `[id_or_intrinsic, comment_or_nil]`
+          def self.resolve(reference)
+            managed = Deploy::Fargate::Cdn::MANAGED_POLICIES[reference]
+            return managed if managed
+            return [reference, nil] if Deploy::Fargate::Cdn::UUID.match?(reference) || INTRINSIC.match?(reference)
+
+            nil
+          end
+
+          # @param edge [Edge] the edge being read, its rows set
+          # @param rows [Array<Table::Row>] the route table's rows
+          # @param vocabulary [Hash{Symbol => Array<String>}] the Site chapter's closed sets
+          # @param problems [Array<String>] collects each problem found, one line each
+          def initialize(edge, rows, vocabulary, problems)
+            @edge = edge
+            @rows = rows
+            @vocabulary = vocabulary
+            @problems = problems
+          end
+
+          # @return [void]
+          def call
+            check_setting
+            check_policies
+            check_upstreams
+            check_rules
+            check_routes
+          end
+
+          private
+
+          def check_setting
+            setting = @edge.setting
+            return problem("Edge", "has no row naming the template; declare one member with template:") unless setting
+
+            template = setting.template.to_s
+            problem("Edge", "template #{template.inspect} must be a path inside the project") if
+              template.empty? || template.start_with?("/") || template.split("/").include?("..")
+            problem("Edge", "has secret_header but no secret_value") if setting.secret_header && !setting.secret_value
+            problem("Edge", "has secret_value but no secret_header") if setting.secret_value && !setting.secret_header
+          end
+
+          def check_policies
+            @edge.policies.each do |policy|
+              label = "EdgePolicy #{policy.cache_class}#{" on #{policy.origin}" if policy.origin}"
+              member_of(label, "cache_class", policy.cache_class, :cache)
+              member_of(label, "origin", policy.origin, :origin) if policy.origin
+              { cache: policy.cache, origin_request: policy.origin_request,
+                response_headers: policy.response_headers }.compact.each do |field, reference|
+                next if (reference == "none" && field != :cache) || self.class.resolve(reference)
+
+                managed = Deploy::Fargate::Cdn::MANAGED_POLICIES.keys.join(", ")
+                problem(label, "has #{field} #{reference.inspect}; use a managed name (#{managed}), " \
+                               "a policy id or an intrinsic like !Ref Name")
+              end
+            end
+            repeated(@edge.policies.map { |policy| [policy.cache_class, policy.origin] }, "EdgePolicy") do |key|
+              "#{key[0]}#{" on #{key[1]}" if key[1]}"
+            end
+          end
+
+          def check_upstreams
+            @edge.upstreams.each do |upstream|
+              member_of("EdgeOrigin #{upstream.origin}", "origin", upstream.origin, :origin)
+              problem("EdgeOrigin #{upstream.origin}", "has id #{upstream.id.inspect}; an origin id is a logical id") unless
+                LOGICAL_ID.match?(upstream.id.to_s)
+            end
+            repeated(@edge.upstreams.map(&:origin), "EdgeOrigin", &:itself)
+          end
+
+          def check_rules
+            problem("EdgeRule", "rows need an Edge row with listener:") if @edge.rules.any? && !@edge.setting&.listener
+            @edge.rules.each { |rule| check_rule(rule) }
+            repeated(@edge.rules.map(&:rule), "EdgeRule", &:itself)
+            repeated(@edge.rules.map(&:priority), "EdgeRule priority", &:to_s)
+          end
+
+          def check_rule(rule)
+            label = "EdgeRule #{rule.rule}"
+            member_of(label, "origin", rule.origin, :origin)
+            problem(label, "has origin assets; the load balancer does not front the assets origin") if rule.origin == "assets"
+            problem(label, "is not a logical id") unless LOGICAL_ID.match?(rule.rule.to_s)
+            unless PRIORITIES.cover?(rule.priority.to_i)
+              problem(label, "has priority #{rule.priority}; a priority is #{PRIORITIES.first} to #{PRIORITIES.last}")
+            end
+            return if rule.origin.nil? || @edge.upstream(rule.origin)&.target_group
+
+            problem(label, "forwards to #{rule.origin}, whose EdgeOrigin names no target_group")
+          end
+
+          def check_routes
+            edge_rows = @rows.select { |row| row.cdn || row.alb_rule }
+            edge_rows.each do |row|
+              next if row.origin == "assets" && !row.cdn
+
+              problem(row.path, "has origin #{row.origin}, which no EdgeOrigin maps") unless @edge.upstream(row.origin)
+              next unless row.cdn && !@edge.policy(row.cache, row.origin)
+
+              problem(row.path, "has cache class #{row.cache} on #{row.origin}, which no EdgePolicy maps")
+            end
+            default_rows = @rows.select { |row| row.path == "/*" && row.cdn }
+            problem("the route table", "needs one row for /* : the default behaviour") if default_rows.empty?
+          end
+
+          def member_of(label, field, value, vocabulary)
+            return if @vocabulary.fetch(vocabulary).include?(value)
+
+            problem(label, "has #{field} #{value.inspect}; #{field} is one of #{@vocabulary.fetch(vocabulary).join(', ')}")
+          end
+
+          def repeated(keys, what)
+            keys.tally.each { |key, count| problem(what, "#{yield(key)} is declared #{count} times") if count > 1 }
+          end
+
+          def problem(label, text) = @problems << "#{label} #{text}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/edge/pattern.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      class Edge
+        # A path pattern as CloudFront and the load balancer read it, and the one question the edge
+        # asks of two of them: does the first match everything the second does.
+        #
+        # A route path names a parameter as `:slug`; the edge has no parameters, so a parameter
+        # stands for `*`. Both services treat `*` as any run of characters, `/` included, and `?` as
+        # one character, and match the whole path, so a pattern without either matches one path.
+        module Pattern
+          module_function
+
+          # @param path [String] a route path such as `/blog/:slug.html` or `/cms/*`
+          # @return [String] the pattern the edge reads for it, `/blog/*.html` for the first
+          def edge(path) = path.gsub(/:[A-Za-z_]\w*/, "*")
+
+          # @param pattern [String] an edge pattern
+          # @return [Regexp] what it matches, from the start of a path to its end
+          def regexp(pattern)
+            source = pattern.each_char.map do |char|
+              case char
+              when "*" then ".*"
+              when "?" then "."
+              else Regexp.escape(char)
+              end
+            end
+            Regexp.new("\\A#{source.join}\\z")
+          end
+
+          # Whether every path `specific` matches is also matched by `general`, tested by reading
+          # `specific` as a literal string, so `/admin*` covers `/admin/members` and `/admin-inbox`
+          # and `/cms/*` covers `/cms/_next/static/*`. A pattern covers itself.
+          #
+          # @param general [String] an edge pattern
+          # @param specific [String] an edge pattern
+          # @return [Boolean]
+          def covers?(general, specific) = regexp(general).match?(specific)
+
+          # @param general [String] an edge pattern
+          # @param specific [String] an edge pattern
+          # @return [Boolean] whether `general` covers `specific` and is not the same pattern
+          def strictly_covers?(general, specific) = general != specific && covers?(general, specific)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/edge/rules.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      class Edge
+        # The load balancer's listener rules a route table needs.
+        #
+        # A route names the rule that carries its path with `alb_rule`. A route of a server other
+        # than the website needs one unless a broader route of the same server has it: `/cms/*`
+        # carries `/cms/_static/*` too. The website's routes need none, since the website takes
+        # whatever no rule claims; the default row `/*` names that rule, written with no path
+        # condition. A rule is refused that carries more paths than a condition may hold, that
+        # carries no route, or that a lower-numbered rule of another server would answer first.
+        class Rules
+          # An ALB rule holds five condition values in all; the secret header's takes one.
+          VALUES = 5
+
+          # @param edge [Edge] the edge being built; its rows are set
+          # @param rows [Array<Table::Row>] the route table's rows
+          # @param problems [Array<String>] collects each problem found, one line each
+          def initialize(edge, rows, problems)
+            @edge = edge
+            @rows = rows
+            @problems = problems
+          end
+
+          # @return [Array<Hash{Symbol => Object}>] each rule by ascending priority, with `:rule`,
+          #   `:priority`, `:origin`, `:target_group` and the `:paths` it carries
+          def call
+            check_names
+            check_carried
+            check_cross_origin
+            @edge.rules.sort_by(&:priority).map { |rule| render(rule) }
+          end
+
+          private
+
+          def render(rule)
+            paths = carried(rule).map { |row| Pattern.edge(row.path) }.uniq
+            check_values(rule, paths)
+            { rule: rule.rule, priority: rule.priority, origin: rule.origin,
+              target_group: @edge.upstream(rule.origin)&.target_group, paths: paths }
+          end
+
+          def carried(rule) = @rows.select { |row| row.alb_rule == rule.rule }
+
+          def check_values(rule, paths)
+            if paths.empty?
+              problem("EdgeRule #{rule.rule}", "carries no route; name it with alb_rule: on a route")
+            elsif paths.include?("/*") && paths.size > 1
+              problem("EdgeRule #{rule.rule}", "carries /*, which every other path it lists is part of")
+            end
+            limit = @edge.setting.secret_header ? VALUES - 1 : VALUES
+            return if paths.size <= limit
+
+            problem("EdgeRule #{rule.rule}", "carries #{paths.size} paths; a rule holds at most #{limit} " \
+                                             "condition values, so split it into two rules")
+          end
+
+          def check_names
+            names = @edge.rules.map(&:rule)
+            @rows.select(&:alb_rule).each do |row|
+              rule = @edge.rules.find { |candidate| candidate.rule == row.alb_rule }
+              next problem(row.path, "names alb_rule #{row.alb_rule}; rules are #{names.join(', ')}") unless rule
+              next if rule.origin == row.origin
+
+              problem(row.path, "is served from #{row.origin} but its rule #{rule.rule} forwards to #{rule.origin}")
+            end
+          end
+
+          # A route of a server behind the load balancer other than the website has a rule of its
+          # own or sits under a broader route of the same server that has one.
+          def check_carried
+            @rows.each do |row|
+              next if row.origin == "website" || row.origin == "assets" || rule_of(row)
+
+              problem(row.path, "is served from #{row.origin} and no rule carries it; name one with alb_rule: " \
+                                "or put it under a broader #{row.origin} route that has one")
+            end
+          end
+
+          # The rule that carries a route: its own, else the nearest broader route's of its server.
+          def rule_of(row)
+            named = @edge.rules.find { |rule| rule.rule == row.alb_rule }
+            return named if named
+
+            covers = @rows.select do |other|
+              other.alb_rule && other.origin == row.origin &&
+                Pattern.strictly_covers?(Pattern.edge(other.path), Pattern.edge(row.path))
+            end
+            covering = covers.find do |one|
+              covers.none? do |other|
+                Pattern.strictly_covers?(Pattern.edge(one.path), Pattern.edge(other.path))
+              end
+            end
+            covering && @edge.rules.find { |rule| rule.rule == covering.alb_rule }
+          end
+
+          # A rule of another server, with a lower priority, whose paths include one a route's own
+          # rule would answer later, is a route answered by the wrong server.
+          def check_cross_origin
+            fallback = default_priority
+            @rows.each do |row|
+              next if row.origin == "assets"
+
+              own = rule_of(row)&.priority || fallback
+              @edge.rules.each do |rule|
+                next if rule.origin == row.origin || rule.priority >= own
+                next unless carried(rule).any? { |other| Pattern.covers?(Pattern.edge(other.path), Pattern.edge(row.path)) }
+
+                problem(row.path, "is served from #{row.origin} but rule #{rule.rule} (priority #{rule.priority}) " \
+                                  "sends it to #{rule.origin} first")
+              end
+            end
+          end
+
+          def default_priority
+            default = @rows.find { |row| row.path == "/*" }
+            @edge.rules.find { |rule| rule.rule == default&.alb_rule }&.priority || Float::INFINITY
+          end
+
+          def problem(label, text) = @problems << "#{label} #{text}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/edge.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+require_relative "../deploy/fargate/cdn"
+require_relative "table"
+require_relative "edge/pattern"
+require_relative "edge/checks"
+require_relative "edge/behaviours"
+require_relative "edge/rules"
+
+module Hecks
+  module Projections
+    module Site
+      # What a site's route table says about the edge: the CloudFront behaviours and the load
+      # balancer's listener rules that send each route to the server and cache that serve it.
+      #
+      # The routes are the table's own `Route` rows. What a table cannot know, the names a template
+      # gives its policies, origins, target groups and listener, a project declares as `member`
+      # rows of four more value objects of the same chapter: `Edge` (the template and listener),
+      # `EdgePolicy`, `EdgeOrigin` and `EdgeRule`. `docs/site-routes.md` lists their fields. A
+      # project that declares none of the four has no edge to project.
+      class Edge
+        Setting  = Struct.new(:template, :listener, :secret_header, :secret_value, keyword_init: true)
+        Policy   = Struct.new(:cache_class, :origin, :cache, :origin_request, :response_headers, keyword_init: true)
+        Upstream = Struct.new(:origin, :id, :target_group, keyword_init: true)
+        Rule     = Struct.new(:rule, :priority, :origin, keyword_init: true)
+
+        # The value objects a project declares its edge rows in, by the kind of record each holds.
+        OBJECTS = { setting: "Edge", policy: "EdgePolicy", upstream: "EdgeOrigin", rule: "EdgeRule" }.freeze
+
+        # The fields each kind of row may carry, with the Ruby class each takes.
+        FIELDS = {
+          setting:  { template: String, listener: String, secret_header: String, secret_value: String },
+          policy:   { cache_class: String, origin: String, cache: String, origin_request: String,
+                    response_headers: String },
+          upstream: { origin: String, id: String, target_group: String },
+          rule:     { rule: String, priority: Integer, origin: String }
+        }.freeze
+
+        # The fields a row of each kind must carry.
+        REQUIRED = { setting: [:template], policy: %i[cache_class cache], upstream: %i[origin id],
+                     rule: %i[rule priority origin] }.freeze
+
+        STRUCTS = { setting: Setting, policy: Policy, upstream: Upstream, rule: Rule }.freeze
+
+        # @return [Setting] the template and the listener
+        attr_reader :setting
+        # @return [Array<Policy>] the cache class to policy mapping
+        attr_reader :policies
+        # @return [Array<Upstream>] the origin mapping
+        attr_reader :upstreams
+        # @return [Array<Rule>] the listener rules
+        attr_reader :rules
+        # @return [Hash{Symbol => Object}] the default behaviour as `Cdn.behavior_lines` takes it
+        attr_reader :default_behaviour
+        # @return [Array<Hash{Symbol => Object}>] the other behaviours, in matching order
+        attr_reader :behaviours
+        # @return [Array<Hash{Symbol => Object}>] each listener rule with the paths it carries
+        attr_reader :listener_rules
+
+        # Reads and checks the edge a chapter declares.
+        #
+        # @param chapter [Bluebook::Chapter] the chapter that declares the route table
+        # @param table [Table] the checked route table
+        # @param vocabulary [Hash{Symbol => Array<String>}] the Site chapter's closed sets
+        # @return [Edge, nil] the checked edge, or nil when the chapter declares none
+        # @raise [Table::Invalid] when a row is refused or the edge contradicts the routes
+        def self.read(chapter, table:, vocabulary:)
+          declared = OBJECTS.transform_values { |name| Table.rows_of(chapter, name) }
+          return nil if declared.values.all?(&:empty?)
+
+          problems = []
+          records = declared.to_h { |kind, members| [kind, build(kind, members, problems)] }
+          new(records, table: table, vocabulary: vocabulary, problems: problems)
+        end
+
+        # @param kind [Symbol] a key of `OBJECTS`
+        # @param members [Array<Hash{Symbol => Object}>] the declared rows
+        # @param problems [Array<String>] collects each problem found
+        # @return [Array<Struct>] the rows that carry known, well-typed fields
+        def self.build(kind, members, problems)
+          members.each_with_index.map do |member, index|
+            label = "#{OBJECTS.fetch(kind)} row #{index + 1}"
+            unknown = member.keys - FIELDS.fetch(kind).keys
+            if unknown.any?
+              problems << "#{label} has no field #{unknown.join(', ')}; fields are #{FIELDS.fetch(kind).keys.join(', ')}"
+            end
+            (REQUIRED.fetch(kind) - member.keys).each { |field| problems << "#{label} needs #{field}" }
+            typed = member.slice(*FIELDS.fetch(kind).keys).select do |field, value|
+              value.is_a?(FIELDS.fetch(kind).fetch(field)) || (problems << "#{label} has #{field} #{value.inspect}; " \
+                                                                           "#{field} is a #{FIELDS.fetch(kind).fetch(field)}")
+            end
+            STRUCTS.fetch(kind).new(**typed)
+          end
+        end
+        private_class_method :build
+
+        # @param records [Hash{Symbol => Array<Struct>}] the rows of each kind
+        # @param table [Table] the checked route table
+        # @param vocabulary [Hash{Symbol => Array<String>}] the closed sets
+        # @param problems [Array<String>] the problems already found in reading the rows
+        # @raise [Table::Invalid] naming every problem when there is one
+        def initialize(records, table:, vocabulary:, problems:)
+          @setting = records.fetch(:setting).first
+          @policies = records.fetch(:policy)
+          @upstreams = records.fetch(:upstream)
+          @rules = records.fetch(:rule)
+          Checks.new(self, table.rows, vocabulary, problems).call
+          if problems.empty?
+            @listener_rules = Rules.new(self, table.rows, problems).call
+            built = Behaviours.new(self, table.rows, problems).call
+            @default_behaviour = built.fetch(:default)
+            @behaviours = built.fetch(:list)
+          end
+          return if problems.empty?
+
+          raise Table::Invalid, "the edge is refused:\n#{problems.map { |line| "  - #{line}" }.join("\n")}"
+        end
+
+        # @param origin [String] an origin of the Origin set
+        # @return [Upstream, nil] its CloudFront origin and target group
+        def upstream(origin) = upstreams.find { |candidate| candidate.origin == origin }
+
+        # The policy mapping for a class on an origin: the row naming both, else the one naming the
+        # class alone.
+        #
+        # @param cache_class [String] a cache class
+        # @param origin [String] an origin
+        # @return [Policy, nil]
+        def policy(cache_class, origin)
+          matching = policies.select { |candidate| candidate.cache_class == cache_class }
+          matching.find { |candidate| candidate.origin == origin } || matching.find { |candidate| candidate.origin.nil? }
+        end
+      end
+    end
+  end
+end