hecks 3.9.1 → 3.11.0

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

@@ -8,6 +8,14 @@
 #   40  the box stack has no instance
 #   41  the roll did not succeed on the box
 #   42  the roll succeeded but the box is not healthy after it
+#   43  no restore anchor: the database's backups cannot be read, or are kept fewer days than
+#       MIN_BACKUP_RETENTION_DAYS (default 3)
+#
+# Before anything changes, the roll names the point the database can be restored to: the instance, the
+# moment this roll starts, and how long its continuous backups are kept. A roll that mints a new era is
+# a one-way door, so this is the rollback anchor, and it costs nothing (a point-in-time restore uses the
+# backups the instance already keeps, where a manual snapshot would be stored until someone deleted it).
+# SKIP_RESTORE_ANCHOR=1 skips it.
 #
 # Before the roll replaces a container, the box saves that container's log to
 # /var/log/hecks-captures/<container>-<UTC timestamp>.log and keeps the newest 14 per container
@@ -30,6 +38,27 @@ DB_HOST=$(out "$RDS_STACK" DbEndpoint)
 [ -n "$BOX" ] && [ "$BOX" != None ] || { echo "no instance in stack $BOX_STACK" >&2; exit 40; }
 ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
 
+if [ "${SKIP_RESTORE_ANCHOR:-}" = 1 ]; then
+  echo "==> skipping the restore anchor (SKIP_RESTORE_ANCHOR=1)"
+else
+  DB_ID=${DB_HOST%%.*}
+  BACKUPS=$(aws rds describe-db-instances --db-instance-identifier "$DB_ID" \
+    --query 'DBInstances[0].[BackupRetentionPeriod,LatestRestorableTime]' --output text) || BACKUPS=
+  read -r KEPT_DAYS RESTORABLE <<< "$BACKUPS"
+  case "${KEPT_DAYS:-}" in ''|*[!0-9]*)
+    echo "==> no restore anchor: could not read the backups of $DB_ID (SKIP_RESTORE_ANCHOR=1 rolls without one)" >&2
+    exit 43 ;;
+  esac
+  if [ "$KEPT_DAYS" -lt "${MIN_BACKUP_RETENTION_DAYS:-3}" ]; then
+    echo "==> no restore anchor: $DB_ID keeps backups $KEPT_DAYS day(s), fewer than ${MIN_BACKUP_RETENTION_DAYS:-3}" >&2
+    exit 43
+  fi
+  ANCHOR_AT=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+  echo "==> restore anchor: $DB_ID restorable to $ANCHOR_AT (latest $RESTORABLE, backups kept $KEPT_DAYS days)"
+  echo "    to return: aws rds restore-db-instance-to-point-in-time --source-db-instance-identifier $DB_ID \\"
+  echo "      --target-db-instance-identifier $DB_ID-restore --restore-time $ANCHOR_AT"
+fi
+
 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

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

@@ -24,7 +24,7 @@
 #   32  the box's Compose file is unreadable    33  the box stack has no instance
 #   34  the stack has no parameter for the container   35  the stack update failed or did not settle
 #   36  a parameter other than the container's changed  37  the task definition lacks the pushed image
-#   38  the task definition has no such container      40-42  deploy-box.sh's own
+#   38  the task definition has no such container      40-43  deploy-box.sh's own
 #
 # Environment:
 #   LOCAL_IMAGE               local image to push, default <ecr repository>:latest

data/lib/hecks/projections/deploy/fargate/settings/tuning.rb

@@ -38,6 +38,7 @@ module Hecks
               plan.domain_env = Check.map!(settings.fetch(:domain_env, {}), "domain_env", nil_ok: true)
               plan.install_dir = install_dir(settings.fetch(:install_dir, DEFAULT_INSTALL_DIR))
               plan.build_context_dir = build_context_dir(settings.fetch(:build_context_dir, ""))
+              plan.host_dir = host_dir(settings.fetch(:host_crate, DEFAULT_HOST_DIR))
             end
 
             def check_execution_grant!(plan)
@@ -62,6 +63,20 @@ module Hecks
               raise ArgumentError, "install_dir must be an absolute path without a trailing slash, got #{value.inspect}"
             end
 
+            # The directory of the Cargo package the Makefile builds `bootstrap` from: an absolute
+            # path, or one relative to the Makefile's `ROOT`. Only path characters are accepted,
+            # since the value is written into a Makefile that shell lines expand.
+            def host_dir(value)
+              text = value.to_s
+              return text if text == DEFAULT_HOST_DIR
+              return text if text.match?(%r{\A/[A-Za-z0-9_.-]+(/[A-Za-z0-9_.-]+)*\z})
+              return "$(ROOT)/#{text}" if text.match?(%r{\A[A-Za-z0-9_.-]+(/[A-Za-z0-9_.-]+)*\z})
+
+              raise ArgumentError,
+                    "host_crate must be a directory path of letters, digits, . _ - and /, absolute or relative to the " \
+                    "Makefile's ROOT, got #{value.inspect}"
+            end
+
             def build_context_dir(value)
               text = value.to_s
               return text if text.empty? || text.match?(%r{\A[A-Za-z0-9_.-]+(/[A-Za-z0-9_.-]+)*/\z})

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

@@ -19,7 +19,7 @@ module Hecks
           Plan = Struct.new(
             :ids, :names, :layout, :cdn, :alerts, :extras, :execute_command, :health_check_grace_period,
             :deregistration_delay, :desired_count_parameter, :domain_env, :install_dir, :build_context_dir,
-            :db_name_parameter, :execution_database_grant,
+            :db_name_parameter, :execution_database_grant, :host_dir,
             keyword_init: true
           )
 
@@ -37,6 +37,8 @@ module Hecks
           }.freeze
           NAME_ROLES = [:cluster, :log_group, :service, :alb, :family, :alb_security_group_description, :db_secret_policy].freeze
           DEFAULT_INSTALL_DIR = "/usr/local/bin".freeze
+          # Where the generated Makefile builds the host binary unless `host_crate` names another.
+          DEFAULT_HOST_DIR = "$(ROOT)/rust/host".freeze
 
           extend Ids
           extend Tuning

data/lib/hecks/projections/deploy/fargate/stack/readers.rb

@@ -65,6 +65,7 @@ module Hecks
             def vpc_ref = shared ? "!Ref OwningVpcId" : "!Ref #{db_id}Vpc"
             def sidecar_dir = plan.install_dir
             def build_context_dir = plan.build_context_dir
+            def host_dir = plan.host_dir
             def cmd_binary = sidecar_dir == Settings::DEFAULT_INSTALL_DIR ? domain_name : "#{sidecar_dir}/#{domain_name}"
             def desired_count_value = plan.desired_count_parameter ? "!Ref #{plan.desired_count_parameter}" : desired_count
             def declared_domain_literal = declared_domain_name.inspect

data/lib/hecks/projections/deploy/preview/preview.sh.erb

@@ -365,7 +365,7 @@ signup_admin() {
 # Prints what to paste into the browser console to sign in as the preview's first
 # admin: a session for that email signed with THIS preview's session secret (the
 # secret itself is never printed). Anyone with AWS access to the account could
-# mint the same, which is the point: it is the deployer's door, not a public one.
+# mint the same, which is the point: it is the deployer's entry, not a public one.
 cmd_login() {
   [ -n "$(stack_status)" ] || die "no preview for branch '$BRANCH' - run 'preview.sh deploy'"
   admin_identity

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

@@ -7,6 +7,9 @@ module Hecks
       # VPC, RDS/Aurora, bastion and cross-domain invoke plumbing shared by the
       # `Lambda` and `Fargate` deploy targets. Plain module functions, not a Target.
       module Shared
+        # Raised when a bastion parameter names a stack output that is not declared.
+        class Error < RuntimeError; end
+
         # The names a domain's own VPC and database are rendered by.
         #
         # @!attribute [r] shared [Boolean] whether this domain borrows another domain's RDS instance
@@ -66,11 +69,11 @@ module Hecks
 
         # Generation-time check that every bastion parameter maps to a stack output.
         #
-        # @raise [RuntimeError] if a parameter names a `from_output` absent from `stack_outputs`
+        # @raise [Error] if a parameter names a `from_output` absent from `stack_outputs`
         def check_bastion_parameters!(bastion_parameters, stack_outputs)
           bastion_parameters.each do |param|
             stack_outputs.any? { |o| o[:key] == param[:from_output] } or
-              raise "bastion parameter #{param[:name]} references undeclared stack output #{param[:from_output]}"
+              raise Error, "bastion parameter #{param[:name]} references undeclared stack output #{param[:from_output]}"
           end
         end
 

data/lib/hecks/projections/deploy/templates/fargate/Makefile.tmpl

@@ -1,8 +1,9 @@
 # GENERATED by hecks deploy project @@domain@@ — re-run it to refresh
 # this file rather than hand-editing.
 #
-# `make deploy` — builds rust/host for this domain, pushes it to this
-# stack's own ECR repository, and deploys the CloudFormation stack.
+# `make deploy` — builds the host for this domain (rust/host, or the
+# directory `host_crate` names), pushes it to this stack's own ECR
+# repository, and deploys the CloudFormation stack.
 # No SAM anywhere in this path.
 
 ROOT       := @@root@@
@@ -11,6 +12,8 @@ STACK      := @@stack_name@@
 BASTION_STACK := @@stack_name@@-bastion
 REGION     := @@region@@
 IMAGE_TAG  := latest
+# The Cargo package `bootstrap` is built from; `make HOST_DIR=<dir>` builds another.
+HOST_DIR   ?= @@host_dir@@
 
 build:
 # aarch64, not x86_64 — matches template.yaml's own
@@ -33,8 +36,8 @@ build:
 # rust/dist/@@domain_name@@.wasm/.ir.json from this domain's own
 # .bluebook.
 	cd $(ROOT) && HECKS_ENVIRONMENT=memory ruby exe/hecks build.build_wasm domain=$(DOMAIN) --wait
-	cd $(ROOT)/rust/host && CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc rustup run stable cargo build --release --target aarch64-unknown-linux-gnu --bin bootstrap
-	cp $(ROOT)/rust/host/target/aarch64-unknown-linux-gnu/release/bootstrap @@domain_name@@-host
+	cd $(HOST_DIR) && CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc rustup run stable cargo build --release --target aarch64-unknown-linux-gnu --bin bootstrap
+	cp $(HOST_DIR)/target/aarch64-unknown-linux-gnu/release/bootstrap @@domain_name@@-host
 	cp $(ROOT)/rust/dist/@@domain_name@@.wasm @@domain_name@@.wasm
 	cp $(ROOT)/rust/dist/@@domain_name@@.ir.json @@domain_name@@.ir.json
 

data/lib/hecks/projections/model/deviations.rb

@@ -17,8 +17,8 @@ module Hecks
 
         # One model field gathered from several declared ones.
         FOLDED = {
-          "Aggregate" => { lifecycle: %i[state_field state_start transitions] },
-          "Entity"    => { lifecycle: %i[state_field state_start transitions] },
+          "Aggregate" => { lifecycle: %i[state_field state_start transitions marks] },
+          "Entity"    => { lifecycle: %i[state_field state_start transitions marks] },
           "Query"     => { order_by: %i[order_field order_way] }
         }.freeze
 

data/lib/hecks/projections/model.rb

@@ -16,10 +16,10 @@ module Hecks
           construct: "Policy",
           file:      "policy.rb",
           behaviour: "Behaviour::Policy",
-          readers:   %i[name on_event trigger_command target_domain expect_undelivered where for_each with_spec],
+          readers:   %i[name on_event trigger_command ask target_domain expect_undelivered where for_each with_spec],
           accessors: %i[aggregate],
           defaults:  { name: nil, on_event: "nil", trigger_command: "nil",
-                       target_domain: "nil", expect_undelivered: "false", where: "nil", for_each: "nil",
+                       ask: "nil", target_domain: "nil", expect_undelivered: "false", where: "nil", for_each: "nil",
                        with_spec: "[]", aggregate: "nil" },
           # The language holds a flag as "true" and the builder as `true`; both become a boolean.
           coerce:    { name: ".to_s", aggregate: "&.to_s", expect_undelivered: ".to_s == \"true\"" },

data/lib/hecks/projections/oidc.rb

@@ -1,3 +1,4 @@
+require "json"
 require_relative "../naming"
 require_relative "../projector"
 
@@ -35,6 +36,17 @@ module Hecks
         }
       end
 
+      # The manifest as the text `oidc.json` holds: indented JSON ending in a newline, with an empty
+      # list as `[]`. `JSON.pretty_generate` spells an empty list `[\n\n]` in some json releases
+      # (2.7.2 among them) and `[]` in others, so the file is normalised here and a committed
+      # manifest compares equal whichever json a machine has.
+      #
+      # @param manifest [Hash{String => Object}] what `call` returns
+      # @return [String] the text of the manifest file
+      def render(manifest)
+        "#{JSON.pretty_generate(manifest).gsub(/\[\n\s*\]/, "[]")}\n"
+      end
+
       # Every command's scope entry, entity commands included (they dispatch as `Entity.Command`).
       # Sorted by scope so two manifest versions diff cleanly.
       #
@@ -79,7 +91,7 @@ module Hecks
       end
 
       # One scope entry per command, spelled like `banking:account.open`; snake-cased through
-      # `Naming.snake`, as the facade names its door methods.
+      # `Naming.snake`, as the facade names its module methods.
       #
       # @param commands [Array<Bluebook::Command>] the commands to project
       # @param verb_prefix [String] the owning aggregate or entity's fully-qualified

data/lib/hecks/projections/shape.rb

@@ -6,6 +6,9 @@ module Hecks
     # The storage shape of one bluebook, the form `StorageShape.mint_hash` hashes to name an era.
     # Diffing two of these answers whether a change bumps the era.
     module Shape
+      # Raised when the shape projection is asked for without the era plugin loaded.
+      class Error < RuntimeError; end
+
       extend Projector::Target
 
       projects_as :shape
@@ -15,8 +18,8 @@ module Hecks
       # Registered even when the era plugin is unloaded; the call then refuses clearly.
       def call(bluebook:, options: {})
         unless Ports::Persistence.plugin?(:era)
-          raise "the :shape projection needs the era persistence plugin loaded " \
-                "(require \"hecks/ports/persistence/plugins/era\")"
+          raise Error, "the :shape projection needs the era persistence plugin loaded " \
+                       "(require \"hecks/ports/persistence/plugins/era\")"
         end
 
         Runtime::StorageShape.project(bluebook)

data/lib/hecks/projections/site/cms_editor/attributes.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require_relative "blocks"
+require_relative "hints"
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # One attribute as the editor reads it: its name, the type as the bluebook spells it, how a
+        # value of it is entered (`kind`), and whether it is optional or a list.
+        #
+        # A type that names one of the aggregate's value objects is an `object`; a reference is a
+        # `reference`; the primitives are `integer`, `number`, `boolean` and `text`, and any other
+        # is text. The shape decides what more it is, never a name: a body (`widget: "body"`), a
+        # block list (see `Blocks`), a moment, a `<kind>:` key (see `Hints`) or a picture.
+        class Attributes
+          # The parts a value object needs for its list of blocks to be a document body's blocks.
+          BLOCK_PARTS = %w[kind spans].freeze
+
+          # The kind a primitive's name enters as; any other name is text.
+          KINDS = { "Integer" => "integer", "Float" => "number", "Boolean" => "boolean", "TrueClass" => "boolean",
+                    "FalseClass" => "boolean" }.freeze
+
+          # @param objects [Array<Bluebook::ValueObject>] the aggregate's value objects
+          def initialize(objects)
+            @by_name = objects.to_h { |object| [object.hecks_name, object] }
+            @objects = @by_name.keys
+            @hints = Hints.new(@by_name)
+          end
+
+          # @param attribute [Bluebook::Attribute] a declared attribute
+          # @return [Hash{String => Object}] the attribute as the editor reads it
+          def of(attribute)
+            type = attribute.type
+            return reference(attribute, type.target_name) if type.is_a?(Bluebook::Reference)
+
+            entry = base(attribute, type.to_s, kind(type.to_s))
+            return entry.merge("widget" => "body") if body?(attribute)
+
+            entry.merge(@hints.of(attribute), listing(attribute), pictured(attribute))
+          end
+
+          private
+
+          # @return [Hash{String => Object}] `blockList` when the attribute is a list of blocks
+          def listing(attribute)
+            found = Blocks.of(attribute, @by_name)
+            found ? { "blockList" => found } : {}
+          end
+
+          # @return [Hash{String => Object}] `picture` (the parts that name the file, its
+          #   description and its caption) when the value object is a picture: it has a media key
+          #   and an `alt` and is not a block of a body or a list of mixed blocks
+          def pictured(attribute)
+            object = @by_name[attribute.type.to_s]
+            return {} unless object && !Blocks.body_block?(object) && !listing(attribute).key?("blockList")
+
+            found = Blocks.picture(object)
+            found&.key?("key") && found.key?("alt") ? { "picture" => found } : {}
+          end
+
+          # A single (not listed) attribute whose value object holds a list of document blocks.
+          def body?(attribute)
+            return false if attribute.list?
+
+            block = block_object(@by_name[attribute.type.to_s])
+            !block.nil? && (BLOCK_PARTS - block.attributes.map { |part| part.name.to_s }).empty?
+          end
+
+          # @return [Bluebook::ValueObject, nil] the value object `object`'s `blocks` list holds
+          def block_object(object)
+            blocks = object&.attributes&.find { |part| part.name.to_s == "blocks" && part.list? }
+            blocks && @by_name[blocks.type.to_s]
+          end
+
+          def reference(attribute, target)
+            base(attribute, target, "reference").merge("target" => target)
+          end
+
+          def base(attribute, type, kind)
+            { "name" => attribute.name.to_s, "type" => type, "kind" => kind,
+              "optional" => attribute.optional?, "list" => attribute.list? }
+          end
+
+          def kind(type)
+            return "object" if @objects.include?(type)
+
+            KINDS.fetch(type, "text")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/blocks.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # A list of mixed blocks, found by shape: a `list_of` value object that has a discriminator,
+        # a part that is one of a closed set of kinds. The editor draws it as ordered cards.
+        #
+        # The discriminator is a part whose type is a closed set (`one_of`) of one plain value, or,
+        # failing that, a text part that an invariant restricts to a literal list
+        # (`["a", "b"].include?(kind)`). A value object that holds `spans` is a body's block, which
+        # the rich-text widget edits, and is never a block list.
+        #
+        # Which slots each kind uses is read from a declared table: a closed set of rows with the
+        # parts `kind`, `requires` and `uses` whose kinds are among the discriminator's. With no
+        # such table every slot is shown, and the invariants that name a kind only hint which slots
+        # it reads. A limit is read from an invariant or given of the form `<list>.size <= <n>`.
+        module Blocks
+          # The parts a table of rules must have.
+          RULE_PARTS = %w[kind requires uses].freeze
+
+          # The parts that make a value object's picture, in the vocabulary of a body's image block.
+          PICTURE = { "key" => "media_ref", "alt" => "alt", "caption" => "caption" }.freeze
+
+          # An invariant that restricts a text part to a literal list of kinds.
+          LITERALS = /\A\[((?:"[^"]+"(?:, )?)+)\]\.include\?\((\w+)\)\z/
+
+          # An invariant that holds unless the kind is the named one: what the rest of it reads.
+          GUARD = /\A(\w+)(?:\.value)? != "([^"]+)" \|\| (.*)\z/m
+
+          # A limit written as a size comparison.
+          LIMIT = /\A(\w+)\.size <= (\d+)\z/
+
+          module_function
+
+          # @param attribute [Bluebook::Attribute] a declared attribute
+          # @param objects [Hash{String => Bluebook::ValueObject}] the aggregate's value objects
+          # @return [Hash{String => Object}, nil] the block list the attribute is, or nil
+          def of(attribute, objects)
+            item = objects[attribute.type.to_s]
+            return nil unless attribute.list? && item && !body_block?(item)
+
+            found = discriminator(item, objects)
+            found && describe(item, objects, *found)
+          end
+
+          # @return [Boolean] whether the value object holds `spans`, as a body's block does
+          def body_block?(item) = item.attributes.any? { |part| part.name.to_s == "spans" }
+
+          # @return [Array(String, Array<String>), nil] the part and the kinds it is one of
+          def discriminator(item, objects)
+            closed(item, objects) || literal(item)
+          end
+
+          # @return [Array(String, Array<String>), nil] a part typed as a closed set of plain values
+          def closed(item, objects)
+            item.attributes.each do |part|
+              kinds = members_of(objects[part.type.to_s]) unless part.list?
+              return [part.name.to_s, kinds] if kinds && !kinds.empty?
+            end
+            nil
+          end
+
+          # @return [Array<String>, nil] the values of a closed set of one plain part
+          def members_of(set)
+            return nil unless set&.closed_set? && set.attributes.size == 1
+
+            set.members.filter_map { |member| member[set.attributes.first.name]&.to_s }
+          end
+
+          # @return [Array(String, Array<String>), nil] a text part restricted by a literal list
+          def literal(item)
+            found = literals(item).find { |match| item.attributes.any? { |part| part.name.to_s == match[2] && !part.list? } }
+            found && [found[2], found[1].scan(/"([^"]+)"/).flatten]
+          end
+
+          # @return [Array<MatchData>] the invariants that restrict a part to a literal list
+          def literals(item) = item.invariants.filter_map { |rule| LITERALS.match(rule.canonical.to_s) }
+
+          def describe(item, objects, name, kinds)
+            table = rules(objects, kinds)
+            found = { "discriminator" => name, "kinds" => kinds, "limits" => limits(item), "pictures" => pictures(item, objects) }
+            found["rules"] = table if table
+            found["mentions"] = mentions(item, name, kinds) unless table
+            found.reject { |_, value| value.respond_to?(:empty?) && value.empty? }
+          end
+
+          # @return [Hash{String => Hash}, nil] each kind's `requires` and `uses`, from the table
+          def rules(objects, kinds)
+            table = objects.values.find { |object| ruled?(object, kinds) }
+            return nil unless table
+
+            table.members.to_h { |row| [row[:kind].to_s, { "requires" => words(row[:requires]), "uses" => words(row[:uses]) }] }
+          end
+
+          def ruled?(object, kinds)
+            object.closed_set? && (RULE_PARTS - object.attributes.map { |part| part.name.to_s }).empty? &&
+              object.members.all? { |row| kinds.include?(row[:kind].to_s) }
+          end
+
+          def words(text) = text.to_s.split(",").map(&:strip).reject(&:empty?)
+
+          # @return [Hash{String => Array<String>}] the slots each kind's guarded invariants read
+          def mentions(item, name, kinds)
+            parts = item.attributes.map { |part| part.name.to_s } - [name]
+            guarded(item, name).each_with_object({}) do |(kind, rest), found|
+              next unless kinds.include?(kind)
+
+              found[kind] = ((found[kind] || []) | parts.select { |part| rest.match?(/\b#{Regexp.escape(part)}\b/) })
+            end
+          end
+
+          def guarded(item, name)
+            item.invariants.filter_map do |rule|
+              match = GUARD.match(rule.canonical.to_s)
+              [match[2], match[3]] if match && match[1] == name
+            end
+          end
+
+          # @return [Hash{String => Integer}] each list part of the item and its declared maximum
+          def limits(item)
+            item.invariants.filter_map do |rule|
+              match = LIMIT.match(rule.canonical.to_s)
+              [match[1], match[2].to_i] if match
+            end.to_h
+          end
+
+          # @param commands [Array<Bluebook::Command>] the aggregate's commands
+          # @param name [String] a list attribute's name
+          # @return [Integer, nil] the most the list may hold, from a command's `given`
+          def maximum(commands, name)
+            sizes = commands.flat_map(&:givens).filter_map do |rule|
+              match = LIMIT.match(rule.canonical.to_s)
+              match[2].to_i if match && match[1] == name
+            end
+            sizes.min
+          end
+
+          # @return [Hash{String => Hash}] the value object and each value object its lists hold,
+          #   to the parts that name a picture, for those that have the parts
+          def pictures(item, objects)
+            held = item.attributes.select(&:list?).filter_map { |part| objects[part.type.to_s] }
+            [item, *held].filter_map { |object| (found = picture(object)) && [object.hecks_name, found] }.to_h
+          end
+
+          def picture(object)
+            names = object.attributes.reject(&:list?).map { |part| part.name.to_s }
+            return nil unless names.include?(PICTURE["key"]) && names.include?(PICTURE["alt"])
+
+            PICTURE.select { |_, part| names.include?(part) }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "preview"
+require_relative "scale_checks"
+require_relative "theme_checks"
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # What the `Editor` row must satisfy beyond the class of each field: paths that start with
+        # a slash, a sign-in path the editor serves itself, a role to admit, and a login page a
+        # visitor with no session can reach.
+        module Checks
+          # A base path: one or more segments, starting with a slash and not ending with one.
+          BASE_PATH = %r{\A(/[^/\s]+)+\z}
+
+          # The largest upload size cap a row may name: 100 MiB.
+          MAX_UPLOAD = 104_857_600
+
+          module_function
+
+          # @param row [Hash{Symbol => String}] the row, defaults filled
+          # @param roles [Array<String>] the roles the row names
+          # @param table [Table, nil] the checked route table, to check the login page against
+          # @return [Array<String>] every problem, in the order the fields are declared
+          def problems(row, roles, table)
+            base = row[:base_path]
+            [*path_problems(row, base), *("Editor roles name no role" if roles.empty?), *login_problems(row[:login], table),
+             *media_problems(row), *media_chapter_problems(row), *ThemeChecks.problems(row), *ScaleChecks.problems(row),
+             *Preview.problems(row[:preview].strip)]
+          end
+
+          # @return [Array<String>] the problems with the base path and the sign-in path
+          def path_problems(row, base)
+            found = []
+            found << "base_path #{base.inspect} must start with a slash and not end with one" unless BASE_PATH.match?(base)
+            found << "sso_path #{row[:sso_path]} must be under #{base}/" unless row[:sso_path].start_with?("#{base}/")
+            found
+          end
+
+          # @return [Array<String>] the problems with the picture directory and the upload size cap
+          def media_problems(row)
+            found = []
+            found << "media_dir must not be empty" if row[:media_dir].strip.empty?
+            cap = row[:media_max_bytes]
+            unless cap.match?(/\A[1-9]\d{0,9}\z/) && cap.to_i <= MAX_UPLOAD
+              found << "media_max_bytes #{cap.inspect} must be a whole number of bytes from 1 to #{MAX_UPLOAD}"
+            end
+            found
+          end
+
+          # @return [Array<String>] the problem with a `media` chapter that is one the editor edits
+          def media_chapter_problems(row)
+            named = row[:media].strip
+            return [] unless row[:chapter].split(",").map(&:strip).include?(named)
+
+            ["media #{named.inspect} is this editor's own chapter; name another chapter"]
+          end
+
+          # The login page is a public row: a visitor with no session must reach it.
+          #
+          # @return [Array<String>] the problems with the login page
+          def login_problems(login, table)
+            return ["login #{login} must start with a slash"] unless login.start_with?("/")
+            return [] if table.nil?
+
+            found = table.rows.find { |candidate| candidate.path == login }
+            return ["login #{login} is not a route of the table"] if found.nil?
+
+            found.auth == "public" ? [] : ["login #{login} is #{found.auth}; the login page must be public"]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/clearing.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # A command argument that only clears: the bluebook's way of setting an optional field back
+        # to nothing is an optional argument the command never reads, named as the source of a
+        # `sets <field>, to: :<argument>` mutation (`attribute :nothing, Body, optional: true`,
+        # `sets :draft_body, to: :nothing`). Nobody types into it, so the editor offers no field
+        # for it and the server sends its empty value itself: an empty list, or nothing at all.
+        #
+        # The shape decides it, never a name. The argument is optional, is no attribute of the
+        # aggregate, feeds only plain `sets` mutations of other fields that can be empty (optional
+        # or a list), and no `given` or `ensures` of the command reads it.
+        module Clearing
+          module_function
+
+          # @param command [Bluebook::Command] the command
+          # @param aggregate [Bluebook::Aggregate] the aggregate it belongs to
+          # @return [Array<Bluebook::Attribute>] the command's arguments that only clear
+          def of(command, aggregate)
+            command.attributes.select { |argument| only_clears?(argument, command, aggregate) }
+          end
+
+          # @param shaped [Hash{String => Object}] the command as the editor reads it
+          # @param only [Array<Bluebook::Attribute>] its arguments that only clear
+          # @return [Hash{String => Object}] `shaped` without those arguments, and naming the ones
+          #   that are lists as `empty`, for the editor to send as empty lists
+          def apply(shaped, only)
+            return shaped if only.empty?
+
+            names = only.map { |argument| argument.name.to_s }
+            lists = only.select(&:list?).map { |argument| argument.name.to_s }
+            kept = shaped["attributes"].reject { |attr| names.include?(attr["name"]) }
+            shaped.merge("attributes" => kept, **(lists.empty? ? {} : { "empty" => lists }))
+          end
+
+          # @return [Boolean] whether `argument` is a clearing argument of `command`
+          def only_clears?(argument, command, aggregate)
+            return false if !argument.optional? || named?(aggregate.attributes, argument.name)
+
+            fed = fed_by(argument, command)
+            !fed.empty? && fed.all? { |mutation| clears?(mutation, aggregate) } && !read?(argument, command)
+          end
+
+          # @return [Array<Bluebook::Mutation>] the mutations that take their value from `argument`
+          def fed_by(argument, command)
+            command.mutations.select { |mutation| mutation.source.is_a?(Symbol) && named?([argument], mutation.source) }
+          end
+
+          # @return [Boolean] whether any of `attributes` is called `name`
+          def named?(attributes, name) = attributes.any? { |held| held.name.to_s == name.to_s }
+
+          # @return [Boolean] whether the mutation is a plain set of a field that can be empty
+          def clears?(mutation, aggregate)
+            target = aggregate.attributes.find { |held| held.name.to_s == mutation.target.to_s }
+            mutation.op == :set && !target.nil? && (target.optional? || target.list?)
+          end
+
+          # @return [Boolean] whether a `given` or `ensures` of the command names the argument
+          def read?(argument, command)
+            word = /\b#{Regexp.escape(argument.name.to_s)}\b/
+            [*command.givens, *command.ensures].any? { |rule| word.match?(rule.canonical.to_s) }
+          end
+        end
+      end
+    end
+  end
+end