hecks 3.10.0 → 3.11.0

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

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "color"
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # What the `Editor` row's look settings must satisfy: an accent that is a six-digit hex
+        # colour, a logo that is a relative path to a picture file the server can read from its
+        # own directory, and a brand that is one line of text.
+        module ThemeChecks
+          # The file types a logo may be.
+          LOGO_TYPES = %w[png jpg jpeg webp gif avif svg].freeze
+
+          # The longest brand the header has room for.
+          BRAND_LENGTH = 60
+
+          module_function
+
+          # @param row [Hash{Symbol => String}] the row, defaults filled
+          # @return [Array<String>] every problem with `brand`, `accent` and `logo`
+          def problems(row)
+            [*accent_problems(row[:accent].strip), *logo_problems(row[:logo].strip), *brand_problems(row[:brand].strip)]
+          end
+
+          # @return [Array<String>] the problem with an accent that is not blank or six hex digits
+          def accent_problems(accent)
+            return [] if accent.empty? || Color::HEX.match?(accent)
+
+            ["accent #{accent.inspect} must be a six-digit hex colour such as #1f7a6d"]
+          end
+
+          # @return [Array<String>] the problem with a logo that is not a safe relative picture path
+          def logo_problems(logo)
+            return [] if logo.empty? || safe_path?(logo)
+
+            ["logo #{logo.inspect} must be a relative path to a #{LOGO_TYPES.join(", ")} file, with no .. or hidden part"]
+          end
+
+          # @return [Array<String>] the problem with a brand that is long or has more than one line
+          def brand_problems(brand)
+            return [] if brand.length <= BRAND_LENGTH && !brand.match?(/[[:cntrl:]]/)
+
+            ["brand must be one line of at most #{BRAND_LENGTH} characters"]
+          end
+
+          # @return [Boolean] whether `path` is relative, has no hidden part, and is a picture
+          def safe_path?(path)
+            LOGO_TYPES.include?(File.extname(path).delete_prefix(".").downcase) && !path.start_with?("/") &&
+              path.split("/", -1).none? { |part| part.empty? || part.start_with?(".") } && !path.match?(/[\\[:cntrl:]]/)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -5,6 +5,8 @@ require_relative "../../projector"
 require_relative "cms_editor/setting"
 require_relative "cms_editor/schema"
 require_relative "cms_editor/pretty"
+require_relative "cms_editor/icons"
+require_relative "cms_editor/theme"
 
 module Hecks
   module Projections
@@ -28,29 +30,36 @@ module Hecks
 
         # The files, by path relative to the directory they are written to.
         FILES = %w[
-          package.json tsconfig.json src/config.ts src/schema.ts src/host.ts src/commands.ts src/app.ts src/server.ts
-          src/auth/membership.ts src/auth/session.ts src/auth/sso.ts
-          src/ui/html.ts src/ui/outline.ts src/ui/fields.ts src/ui/input.ts src/ui/pages.ts
-          src/ui/body_model.js src/ui/body_parse.js src/ui/body_widget.js
+          package.json tsconfig.json src/config.ts src/schema.ts src/names.ts src/host.ts src/commands.ts src/choices.ts
+          src/app.ts src/server.ts src/assets.ts src/flash.ts src/auth/membership.ts src/auth/session.ts src/auth/sso.ts
+          src/ui/html.ts src/ui/words.ts src/ui/icons.ts src/ui/shell.ts src/ui/outline.ts src/ui/fields.ts
+          src/ui/input.ts src/ui/table.ts src/ui/paging.ts src/ui/pickers.ts src/ui/moments.ts src/ui/detail.ts
+          src/ui/pages.ts src/ui/theme.js src/ui/body_model.js src/ui/body_parse.js src/ui/availability.ts src/ui/dialogs.ts
+          src/ui/links.ts src/ui/preview.ts src/ui/related.ts src/ui/schedule.ts src/ui/values.ts src/ui/world.ts
+          src/browser/app.css src/browser/main.js src/browser/shell.js src/browser/forms.js src/browser/toast.js
+          src/browser/lists.js src/browser/pickers.js src/browser/epoch.js src/browser/moments.js
+          src/browser/body_doc.js src/browser/body_editor.js src/browser/autosave.js src/browser/preview.js
+          src/ui/blocks.ts src/ui/block_list.js src/browser/blocks.js
         ].freeze
 
         # The files only an editor of a chapter with a picture aggregate has: the upload, the
-        # storage port with its local-disk adapter, and the picker the rich-text widget opens.
+        # storage port with its local-disk adapter, and the picker the rich-text editor opens.
         MEDIA_FILES = %w[
-          src/media/sniff.ts src/media/multipart.ts src/media/storage.ts src/media/handler.ts src/ui/media_picker.js
+          src/media/sniff.ts src/media/multipart.ts src/media/storage.ts src/media/handler.ts src/browser/media_picker.js
         ].freeze
 
-        # The browser modules the rich-text widget loads, served to a signed-in editor.
-        ASSETS = %w[body_widget.js body_model.js body_parse.js].freeze
-
-        # What `app.ts` holds for a picture upload; each is left out when the chapter has none.
+        # What `app.ts` and the body editor hold for a picture upload; each is left out when the
+        # chapter has none.
         MEDIA_LINES = {
-          "__MEDIA_IMPORT__" => ["import { mediaHandler } from \"./media/handler.ts\";",
-                                 "import type { MediaStorage } from \"./media/storage.ts\";"].join("\n"),
-          "__MEDIA_OPTION__" => ["  /** Where picture bytes are kept: the local disk unless given (see media/storage.ts). */",
-                                 "  storage?: MediaStorage;"].join("\n"),
-          "__MEDIA_SETUP__"  => "  const media = mediaHandler(options.storage);",
-          "__MEDIA_ROUTE__"  => "    if (segments[0] === \"media\") return media(client, request, segments.slice(1));"
+          "__MEDIA_IMPORT__"  => ["import { mediaHandler, mediaOpen } from \"./media/handler.ts\";",
+                                  "import type { MediaStorage } from \"./media/storage.ts\";"].join("\n"),
+          "__MEDIA_OPTION__"  => ["  /** Where picture bytes are kept: the local disk unless given (see media/storage.ts). */",
+                                  "  storage?: MediaStorage;"].join("\n"),
+          "__MEDIA_SETUP__"   => "  const media = mediaHandler(options.storage, { url: options.url, fetch: options.fetch });",
+          "__MEDIA_ROUTE__"   => ["    if (segments[0] === \"media\") {",
+                                  "      if (!mediaOpen(role)) return plain(\"Pictures are not open to your role.\", 403);",
+                                  "      return media(client, request, segments.slice(1));", "    }"].join("\n"),
+          "__PICKER_LOADER__" => "() => import(\"./media_picker.js\")"
         }.freeze
 
         module_function
@@ -58,8 +67,11 @@ module Hecks
         # Renders the editor's files for a project that declares an `Editor` row.
         #
         # @param bluebook [Bluebook::Chapter] the chapter that declares the route table and the row
-        # @param options [Hash{Symbol => Object}] `:domain_chapter` the chapter to edit; `:table`
-        #   the checked route table, when the login page is to be checked against it
+        # @param options [Hash{Symbol => Object}] `:domain_chapters` the chapters to edit, in the
+        #   order the row names them (`:domain_chapter` for one);
+        #   `:media_chapter` the chapter the row's `media` names, whose picture aggregate the
+        #   pictures use; `:table` the checked route table, when the login page is to be checked
+        #   against it
         # @return [Hash{String => String}] each file's path relative to the editor's directory to
         #   its text; empty when the project declares no `Editor` row
         # @raise [Table::Invalid] when the row is refused
@@ -68,18 +80,32 @@ module Hecks
           setting = Setting.read(bluebook, table: options[:table])
           return {} unless setting
 
-          schema = Schema.read(options.fetch(:domain_chapter), skip: setting.skip)
+          chapters = options[:domain_chapters] || options.fetch(:domain_chapter)
+          schema = Schema.read(chapters, skip: setting.skip, pictures: options[:media_chapter], roles: setting.chapter_roles)
           media = schema.key?("media")
-          tokens = setting.tokens.merge("__SCHEMA__" => Pretty.generate(schema), **media_tokens(media))
+          tokens = tokens(setting, schema, media)
           [*FILES, *(MEDIA_FILES if media)].to_h { |path| [path, fill(File.read(File.join(TEMPLATES, "#{path}.tmpl")), tokens)] }
         end
 
+        # @return [Hash{String => String}] each placeholder of the templates and its text
+        def tokens(setting, schema, media)
+          setting.tokens.merge(look_tokens(setting, schema), "__SCHEMA__" => Pretty.generate(schema), **media_tokens(media))
+        end
+
         # @param media [Boolean] whether the chapter has a picture aggregate
         # @return [Hash{String => String}] each media placeholder to its text, empty when none
         def media_tokens(media)
-          assets = RoutesTs.literal(media ? [*ASSETS, "media_picker.js"] : ASSETS)
-          lines = media ? MEDIA_LINES : MEDIA_LINES.transform_values { "" }
-          { "__ASSETS__" => assets, **lines }
+          return MEDIA_LINES if media
+
+          MEDIA_LINES.transform_values { "" }.merge("__PICKER_LOADER__" => "null")
+        end
+
+        # @param setting [Setting] the checked row
+        # @param schema [Hash{String => Object}] the chapter as the editor reads it
+        # @return [Hash{String => String}] the brand, the icon sprite and the theme's colours
+        def look_tokens(setting, schema)
+          { "__BRAND__" => JSON.generate(setting.brand || schema["domain"]), "__ICONS__" => Icons.sprite,
+            "__CSS_BANNER__" => "/* #{RoutesTs::BANNER.delete_prefix("// ")} */", **Theme.tokens(setting.accent) }
         end
 
         # @param text [String] a template with `__NAME__` placeholders

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../../bluebook/synthesizer"
+
 module Hecks
   module Projections
     module Site

data/lib/hecks/projector/cli_audience.rb

@@ -2,7 +2,8 @@ module Hecks
   module Projector
     # What a launcher's help leaves out and points at for whoever typed the line: the aggregates
     # only a maintainer of a hecks checkout runs, and the attached chapters worth a line each.
-    # `CliProjector` renders the help; the runner decides the audience (`Doors::LauncherOptions`).
+    # `CliProjector` renders the help; the runner decides the audience
+    # (`Adapters::Driving::LauncherOptions`).
     module CliAudience
       module_function
 

data/lib/hecks/projector/cli_projector/listing.rb

@@ -67,7 +67,7 @@ module Hecks
         end
 
         # " (also: mcp!)" for a spec the chapter gave a short name, else nothing. A short name that
-        # is only the command's own name (`init` for `door.init`) is already in the line.
+        # is only the command's own name (`init` for `launch.init`) is already in the line.
         def alias_note(spec)
           return "" if spec[:short_was].nil? || spec[:short_was].split(".").last == spec[:short]
 

data/lib/hecks/projector/cli_projector/option_specs.rb

@@ -29,7 +29,7 @@ module Hecks
         # One option per field of a value object, recursing into a field that is itself one.
         #
         # The list flag rides on each leaf: without it a repeated flag overwrote the
-        # leaf silently, and CliDoor only ever sees a path and a spec.
+        # leaf silently, and Cli only ever sees a path and a spec.
         def leaf_options(value_object, aggregate, path, optional)
           value_object.attributes.flat_map do |field|
             nested = value_object_for(field, value_object, aggregate)

data/lib/hecks/projector/docs_projector/closing.rb

@@ -18,7 +18,7 @@ module Hecks
           return [] if bluebook.policies.empty?
 
           rows = bluebook.policies.map do |policy|
-            ["`#{policy.on_event}`", "`#{policy.trigger_command}`", policy.target_domain || bluebook.name]
+            ["`#{policy.on_event}`", "`#{policy.reaches}`", policy.target_domain || bluebook.name]
           end
           [DocsProjector.h(depth, "Reactions"), "",
            "These fire on their own. Issuing the verb on the left also causes the one on the right.", "",

data/lib/hecks/projector/docs_projector.rb

@@ -110,7 +110,7 @@ module Hecks
         out.compact.join("\n")
       end
 
-      # An entity has no door of its own; its verbs go through the holding aggregate.
+      # An entity has no entry point of its own; its verbs go through the holding aggregate.
       def entity_addressing(aggregate, entity)
         "Addressed through its holder — `#{aggregate.hecks_name}.#{entity.hecks_name}.<Verb>`, " \
           "passing the #{aggregate.hecks_name}'s `id` and this element's " \

data/lib/hecks/projector/exporter/bindings.rb

@@ -1,3 +1,5 @@
+require_relative "capability_values"
+
 module Hecks
   module Projector
     module Exporter
@@ -5,6 +7,8 @@ module Hecks
       # membership, identity, newsletter, registrations, payments): a per-deployment binding fact,
       # not part of the declared IR. Each answers `{}` when nothing the domain attaches provides it.
       module Bindings
+        include CapabilityValues
+
         # Which chapter this domain's role checks resolve against
         # (`Registry#authorization_provider_for`); `{}` if none does.
         #
@@ -70,16 +74,20 @@ module Hecks
         # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
         # @param domain_name [String] the domain to export the newsletter binding for
         # @return [Hash{Symbol => String, nil}] `:provider` (name), `:subscribe`, `:add_name`,
-        #   `:confirm`, `:unsubscribe` (qualified verbs), and `:aggregate` (`:subscribe`'s own
-        #   leading qualified aggregate name); `{}` if nothing this domain attaches provides
-        #   newsletter
+        #   `:confirm`, `:unsubscribe` (qualified verbs), `:aggregate` (`:subscribe`'s own
+        #   leading qualified aggregate name) and, when declared, `:awaiting_confirmation`,
+        #   `:receives_issues` and `:left` (the states of the lifecycle marks they name) and
+        #   `:confirm_window` and `:unsubscribe_window` (seconds); `{}` if nothing this domain
+        #   attaches provides newsletter
         def newsletter(registry, domain_name)
           provider = registry.newsletter_provider_for(domain_name)
           return {} unless provider
 
           verbs = verbs_of(provider, Bluebook::Capabilities::NEWSLETTER,
                            :subscribe, :add_name, :confirm, :unsubscribe)
-          { provider: provider.name, **verbs, aggregate: aggregate_of(verbs[:subscribe]) }
+          { provider: provider.name, **verbs, aggregate: aggregate_of(verbs[:subscribe]),
+            **all_marked_states(provider, Bluebook::Capabilities::NEWSLETTER),
+            **all_durations(provider, Bluebook::Capabilities::NEWSLETTER) }
         end
 
         # Which chapter answers sending a newsletter issue
@@ -107,15 +115,18 @@ module Hecks
         # @param domain_name [String] the domain to export the registrations binding for
         # @return [Hash{Symbol => String, nil}] `:provider` (name), `:schedule`, `:request`
         #   (qualified verbs), `:event_aggregate` and `:registration_aggregate` (each verb's own
-        #   leading qualified aggregate name); `{}` if nothing this domain attaches provides
-        #   registrations
+        #   leading qualified aggregate name) and, when declared, `:frees_seat` (the states of the
+        #   lifecycle mark it names) and `:registered_at` (the attribute that stamps a request);
+        #   `{}` if nothing this domain attaches provides registrations
         def registrations(registry, domain_name)
           provider = registry.registrations_provider_for(domain_name)
           return {} unless provider
 
           verbs = verbs_of(provider, Bluebook::Capabilities::REGISTRATIONS, :schedule, :request)
           { provider: provider.name, **verbs,
-            **aggregates_of(verbs, event_aggregate: :schedule, registration_aggregate: :request) }
+            **aggregates_of(verbs, event_aggregate: :schedule, registration_aggregate: :request),
+            **all_marked_states(provider, Bluebook::Capabilities::REGISTRATIONS),
+            **all_words(provider, Bluebook::Capabilities::REGISTRATIONS) }
         end
 
         # Which chapter owns the payment-processor connection
@@ -142,14 +153,33 @@ module Hecks
         # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
         # @param domain_name [String] the domain to export the payments binding for
         # @return [Hash{Symbol => String, nil}] `:provider` (name), `:initiate`, `:succeeded`,
-        #   `:failed` (qualified verbs), and `:aggregate` (`:initiate`'s own leading qualified
-        #   aggregate name); `{}` if nothing this domain attaches provides payments
+        #   `:failed` (qualified verbs), `:aggregate` (`:initiate`'s own leading qualified
+        #   aggregate name) and, when declared, `:holds_seat` (the states of the lifecycle mark
+        #   it names) and `:lapse_reason` (the word a lapsed hold
+        #   records); `{}` if nothing this domain attaches provides payments
         def payments(registry, domain_name)
           provider = registry.payments_provider_for(domain_name)
           return {} unless provider
 
           verbs = verbs_of(provider, Bluebook::Capabilities::PAYMENTS, :initiate, :succeeded, :failed)
-          { provider: provider.name, **verbs, aggregate: aggregate_of(verbs[:initiate]) }
+          { provider: provider.name, **verbs, aggregate: aggregate_of(verbs[:initiate]),
+            **marked_states(provider, Bluebook::Capabilities::PAYMENTS, :holds_seat),
+            **all_words(provider, Bluebook::Capabilities::PAYMENTS) }
+        end
+
+        # Which chapter owns the checkout boundary (`Registry#checkout_provider_for`); `{}` if
+        # none does.
+        #
+        # @param registry [Runtime::Registry] the booted registry `domain_name` is loaded in
+        # @param domain_name [String] the domain to export the checkout binding for
+        # @return [Hash{Symbol => Object}] `:provider` (name) and, when declared,
+        #   `:webhook_tolerance` and `:session_hold` (whole seconds); `{}` if nothing this
+        #   domain attaches provides checkout
+        def checkout(registry, domain_name)
+          provider = registry.checkout_provider_for(domain_name)
+          return {} unless provider
+
+          { provider: provider.name, **all_durations(provider, Bluebook::Capabilities::CHECKOUT) }
         end
 
         private

data/lib/hecks/projector/exporter/capability_values.rb

@@ -0,0 +1,55 @@
+module Hecks
+  module Projector
+    module Exporter
+      # The values a capability's optional contract entries resolve to in the exported fact: the
+      # states of a lifecycle `:mark` (ADR 0097), the whole seconds of a `:duration` (ADR 0098), and
+      # the word of a `:text` or `:attribute` entry (ADR 0099).
+      module CapabilityValues
+        private
+
+        # `{ key => states }` for each optional `:mark` entry `provider` declares under
+        # `capability`.
+        def all_marked_states(provider, capability)
+          mark_keys = declared_keys(capability, :mark)
+          mark_keys.reduce({}) { |marks, key| marks.merge(marked_states(provider, capability, key)) }
+        end
+
+        # `{ key => seconds }` for each optional `:duration` entry `provider` declares under
+        # `capability`: the whole-seconds default of the attribute it names.
+        def all_durations(provider, capability)
+          declared_keys(capability, :duration).each_with_object({}) do |key, durations|
+            verb = provider.provision(capability)&.fetch(key, nil)
+            durations[key] = Bluebook::Capabilities.duration_of(provider, verb) if verb
+          end
+        end
+
+        # `{ key => word }` for each optional `:text` entry and `{ key => attribute_name }` for each
+        # optional `:attribute` entry `provider` declares under `capability` (ADR 0099).
+        def all_words(provider, capability)
+          words = { text: :text_of, attribute: :attribute_of }.flat_map do |kind, resolver|
+            declared_keys(capability, kind).filter_map do |key|
+              verb = provider.provision(capability)&.fetch(key, nil)
+              [key, Bluebook::Capabilities.public_send(resolver, provider, verb)] if verb
+            end
+          end
+          words.to_h
+        end
+
+        # `{ key => states }` for an optional `:mark` entry `provider` declares under `capability`:
+        # the states of the named aggregate's lifecycle mark. `{}` when the entry is not declared.
+        def marked_states(provider, capability, key)
+          verb = provider.provision(capability)&.fetch(key, nil)
+          return {} unless verb
+
+          aggregate_name, mark = verb.split(".", 2)
+          { key => provider.aggregate(aggregate_name).lifecycle.marked(mark) }
+        end
+
+        # The contract keys of `capability` whose kind is `kind`.
+        def declared_keys(capability, kind)
+          Bluebook::Capabilities::CONTRACTS.fetch(capability).select { |_, entry| entry == kind }.keys
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projector/narrate_projector/reactions.rb

@@ -16,7 +16,7 @@ module Hecks
         # A policy as the sentence saying it fires on its own.
         def policy_sentence(policy)
           elsewhere = policy.target_domain ? " in #{policy.target_domain}" : ""
-          "Whenever `#{policy.on_event}` happens, `#{policy.trigger_command}` fires on its own#{elsewhere} — " \
+          "Whenever `#{policy.on_event}` happens, `#{policy.reaches}` fires on its own#{elsewhere} — " \
             "nobody has to ask for it."
         end
 

data/lib/hecks/projector/target.rb

@@ -58,6 +58,17 @@ module Hecks
       #   before `projects_as` is called
       def projection_needs_world? = @projection_needs_world || false
 
+      # Derives what kind of target this is from flags it already declares,
+      # so there is no second spelling to drift.
+      #
+      # @return [Symbol] `:export` if it needs a world, `:meta` if it needs a
+      #   chapter declaring particular aggregates, otherwise `:projection`
+      def projection_category
+        return :export if projection_needs_world?
+
+        projection_declares.empty? ? :projection : :meta
+      end
+
       # Names the capability module(s) a construct must satisfy, defaulting
       # to plain chapter-hood when `projects_as` named none.
       #

data/lib/hecks/projector.rb

@@ -4,10 +4,13 @@ module Hecks
   #
   #   Projector.call(:ir, bluebook: chapter)
   #
-  # A projection is inert and derived from a chapter's declaration. An export
-  # (rust crate, WASM, CloudFormation) also needs `.world` bindings and declares
-  # `needs_world: true`. State projections (`hecks project_expression_tables`) and
-  # `Ports::Projection` read-model catch-up are different things and not registered.
+  # A target's category is derived from the flags it declares (`category`):
+  #
+  # - `:projection` is inert and derived from any chapter's declaration.
+  # - `:meta` also needs a chapter declaring particular aggregates (`declares:`),
+  #   so it only fits hecks's own grammar chapters.
+  # - `:export` (CloudFormation, ...) also needs `.world` bindings and declares
+  #   `needs_world: true`; that is adapter wiring, not a projection of the domain.
   module Projector
     class UnknownProjector < StandardError; end
     # A chapter-scoped projector was handed something that is not a chapter.
@@ -38,7 +41,9 @@ module Hecks
     # @raise [WrongConstruct] if `bluebook` lacks what the projector requires
     def call(name, bluebook:, options: {}, world: nil)
       projector = registry.fetch(name.to_sym) do
-        raise UnknownProjector, "no projector registered for #{name.inspect} — registered: #{registered.sort.inspect}"
+        raise UnknownProjector,
+              "no projector registered for #{name.inspect} — registered: " \
+              "#{registered_by_category.map { |kind, keys| "#{kind} #{keys.inspect}" }.join(", ")}"
       end
       admits!(name, projector, bluebook, world)
       projector.call(bluebook: bluebook, options: world ? options.merge(world: world) : options)
@@ -114,6 +119,28 @@ module Hecks
     # @return [Array<Symbol>] every key currently registered
     def registered = registry.keys
 
+    # Gives the category of a registered target, derived from its flags.
+    # A target that answers no `projection_category` (the built-ins, which do
+    # not extend `Target`) is a plain projection.
+    #
+    # @param name [String, Symbol] the registered projector's key
+    # @return [Symbol] `:projection`, `:meta` or `:export` (`:projection` for an
+    #   unregistered `name`)
+    def category(name)
+      projector = registry.fetch(name.to_sym) { return :projection }
+      projector.respond_to?(:projection_category) ? projector.projection_category : :projection
+    end
+
+    # Lists every registered key under its category.
+    #
+    # @return [Hash{Symbol => Array<Symbol>}] `:projection`, `:meta` and `:export`
+    #   (always all three), each with its sorted keys
+    def registered_by_category
+      grouped = { projection: [], meta: [], export: [] }
+      registered.sort.each { |key| grouped[category(key)] << key }
+      grouped
+    end
+
     # Gives the live registry, initializing it on first use.
     #
     # @return [Hash{Symbol => Module, Class, #call}] the live key => projector registry

data/lib/hecks/quality_control/adapters/github_checks.rb

@@ -2,12 +2,16 @@
 
 require "open3"
 require "json"
+require_relative "../../indifferent_key"
 
 module Hecks
   module Adapters
     # The `CI` port adapter: answers `Clearance.CI.Run` from GitHub's check runs for a commit.
     # Raises when no checks exist, any are still running, or any failed.
     class GithubChecks
+      # Raised when check runs cannot be read or have not settled.
+      class Error < RuntimeError; end
+
       # All keywords are unused; the adapter takes no per-boot configuration.
       def initialize(aggregate: nil, settings: {}, root: nil); end
 
@@ -29,7 +33,7 @@ module Hecks
       #
       # @param commit [Hash, String] a materialized value object (`{value: sha}`) or a bare sha
       # @return [Hash] `{ summary: { value: ... } }` when every check is green
-      # @raise [RuntimeError] when the sha is malformed, `gh` is missing or fails, no checks
+      # @raise [Error] when the sha is malformed, `gh` is missing or fails, no checks
       #   exist, any are incomplete, or any failed
       def run(commit:, **)
         sha = valid_sha(commit)
@@ -49,7 +53,7 @@ module Hecks
       # @param names [Array<String>] the checks to look up
       # @return [Hash{String => Symbol}] each name to `:passed`, `:failed`, `:pending` (reported but
       #   not completed) or `:missing` (not reported at all)
-      # @raise [RuntimeError] when the sha is malformed or `gh` is missing or fails
+      # @raise [Error] when the sha is malformed or `gh` is missing or fails
       def states(commit:, names:)
         reported = check_runs(valid_sha(commit)).select { |run| actions?(run) }.group_by { |run| run["name"] }
         latest = reported.transform_values { |runs| runs.max_by { |run| run["id"].to_i } }
@@ -62,7 +66,7 @@ module Hecks
 
       def valid_sha(commit)
         sha = sha_of(commit)
-        raise "not a commit sha: #{sha.inspect}" unless sha.match?(SHA_PATTERN)
+        raise Error, "not a commit sha: #{sha.inspect}" unless sha.match?(SHA_PATTERN)
 
         sha
       end
@@ -70,11 +74,11 @@ module Hecks
       # The check runs against `sha`, once none is still running.
       def settled_runs(sha)
         runs = check_runs(sha)
-        raise "gh reports no checks at all against #{sha}" if runs.empty?
+        raise Error, "gh reports no checks at all against #{sha}" if runs.empty?
 
         # Refuse rather than answer on an incomplete run; asking again once it settles is safe.
         incomplete = runs.reject { |run| run["status"] == "completed" }
-        raise "checks against #{sha} are still running — asked before they settled" if incomplete.any?
+        raise Error, "checks against #{sha} are still running — asked before they settled" if incomplete.any?
 
         runs
       end
@@ -95,7 +99,7 @@ module Hecks
       def sha_of(commit)
         return commit if commit.is_a?(String)
 
-        (commit.key?(:value) ? commit[:value] : commit["value"]).to_s
+        IndifferentKey.read(commit, :value).to_s
       end
 
       # Every page of check runs: a red run past the first page must still be seen.
@@ -115,11 +119,11 @@ module Hecks
       def check_run_page(sha, page)
         path = "repos/{owner}/{repo}/commits/#{sha}/check-runs?per_page=#{PER_PAGE}&page=#{page}"
         out, err, status = Open3.capture3("gh", "api", path)
-        raise "gh api check-runs failed for #{sha}: #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
+        raise Error, "gh api check-runs failed for #{sha}: #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
 
         JSON.parse(out)
       rescue Errno::ENOENT
-        raise "gh is not installed or not on PATH — cannot read check runs for #{sha}"
+        raise Error, "gh is not installed or not on PATH — cannot read check runs for #{sha}"
       end
     end
   end

data/lib/hecks/quality_control/adapters/github_issues.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
 require "open3"
+require_relative "../../indifferent_key"
 
 module Hecks
   module Adapters
     # The `IssueTracker` port's adapter: files a `QualityControl::Ticket` as a GitHub issue.
     # Raises when `gh` refuses, which the runtime records as the ticket's refusal.
     class GithubIssues
+      # Raised when `gh` cannot file the issue.
+      class Error < RuntimeError; end
+
       # @param aggregate [Object, nil] unused
       # @param settings [Hash] unused
       # @param root [String, nil] unused
@@ -18,7 +22,7 @@ module Hecks
       #   value objects (`{value: ...}`) or bare strings, and `pull_request` names a proposed fix
       # @return [Hash{Symbol => Hash}] `number:` and `url:` of the issue, in the shape the
       #   ticket's `Filed` command takes
-      # @raise [RuntimeError] when `gh` exits non-zero or prints no issue URL
+      # @raise [Error] when `gh` exits non-zero or prints no issue URL
       def file(**held)
         out = create_issue(plain(held[:repository]), plain(held[:title]).to_s, issue_body(held))
         url, number = issue_url_and_number(out)
@@ -37,7 +41,7 @@ module Hecks
       def issue_url_and_number(out)
         url = out.strip.lines.last.to_s.strip
         number = url[%r{/issues/(\d+)\z}, 1]
-        raise "gh issue create printed no issue URL: #{out.strip.inspect}" unless number
+        raise Error, "gh issue create printed no issue URL: #{out.strip.inspect}" unless number
 
         [url, number]
       end
@@ -45,7 +49,7 @@ module Hecks
       def create_issue(repository, title, body)
         out, err, status = Open3.capture3("gh", "issue", "create", "--repo", repository,
                                           "--title", title, "--body", body)
-        raise "gh issue create failed — #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
+        raise Error, "gh issue create failed — #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
 
         out
       end
@@ -54,7 +58,7 @@ module Hecks
       def plain(field)
         return field unless field.is_a?(Hash)
 
-        field.key?(:value) ? field[:value] : field["value"]
+        IndifferentKey.read(field, :value)
       end
     end
   end

data/lib/hecks/quality_control/cli/qa_open_pr.rb

@@ -11,8 +11,8 @@ require_relative "qa_open_pr/recording"
 module Hecks
   module QualityControlCli
     # The command behind `hecks quality_control patch.open`: opens a PR and records it in the
-    # QualityControl ledger in one step. It is the only door into `QualityControl::Patch.Open` and
-    # `QualityControl::Improvement.Open`.
+    # QualityControl ledger in one step. It is the only entry point into
+    # `QualityControl::Patch.Open` and `QualityControl::Improvement.Open`.
     #
     # It refuses (exit 1, nothing opened or recorded) unless the ledger's own `Open` command would
     # take the record and the `GitPr` adapter agrees. The command's `given`s are the rules, asked

data/lib/hecks/quality_control/cli/qa_sweep/checks/shrinking.rb

@@ -10,7 +10,7 @@ module Hecks
           private
 
           # Re-runs only the comparison that surprised; `seat` matters only for `self_consistency`,
-          # which reads the Rust binary's rehydration door under a differential seat.
+          # which reads the Rust binary's rehydration entry point under a differential seat.
           def candidate_divergences(check_mode, seat, steps)
             case check_mode
             when :differential

data/lib/hecks/quality_control/cli/qa_sweep/finding_report.rb

@@ -37,7 +37,7 @@ module Hecks
 
         def print_finding_instructions
           puts "No Bug was logged (that needs a real failing-test demonstration, which"
-          puts "needs judgment this script does not have — hecks quality_control log is the door)"
+          puts "needs judgment this script does not have — hecks quality_control log is the entry point)"
           puts "and the sweep was not concluded. The ledger's own SuspendOnSurprise"
           puts "policy took the target out of the rotation; it stays out until a PERSON"
           puts "runs: hecks quality_control ask run target=#{@target_reference} " \