hecks 7.0.0 → 7.1.0

data/lib/hecks/behaviors/expectations/adapter_selection.rb

@@ -0,0 +1,82 @@
+require_relative "../../runtime/registry"
+
+module Hecks
+  module Behaviors
+    module Expectations
+      # Which `.adapter` files a behaviors suite boots, chosen without a list (ADR 0171): every
+      # project adapter that says `stays_inside`, every stand-in in `behavior_adapters/` beside
+      # the suite, and any adapter the suite names in `loads`. A stand-in or a named adapter takes
+      # its port from the project's. A project adapter that reaches outside is never loaded, and
+      # its Ruby never runs: its declaration is read with its `require` lines left out.
+      #
+      # A project opts in by having a `behavior_adapters/` directory beside the suite or by any of
+      # its adapters saying `stays_inside`; until then its suites keep the loader's own choice.
+      module AdapterSelection
+        STAND_INS = "behavior_adapters".freeze
+        PROJECT_PATTERNS = %w[*.adapter */*.adapter */*/*.adapter].freeze
+        REQUIRE_LINE = /\A\s*require(?:_relative)?\s+["'][^"']+["']\s*\z/
+        SELECTIONS = {} # rubocop:disable Style/MutableConstant -- a per-process cache, filled under the lock
+        SELECTIONS_LOCK = Mutex.new
+        private_constant :SELECTIONS, :SELECTIONS_LOCK
+
+        module_function
+
+        # @param suite_path [String] the `.behaviors` file
+        # @param files [Array<String>] the suite's `loads`, absolute
+        # @return [Array<String>, nil] the `.adapter` files to boot, absolute, in a stable
+        #   order; nil when the suite's project has not opted in
+        def call(suite_path, files)
+          SELECTIONS_LOCK.synchronize do
+            SELECTIONS.fetch([suite_path, files]) { SELECTIONS[[suite_path, files]] = choose(suite_path, files) }
+          end
+        end
+
+        def choose(suite_path, files)
+          project = project_adapters(files)
+          return nil unless opted_in?(suite_path, project)
+
+          chosen = files.select { |file| file.end_with?(".adapter") } + stand_ins(suite_path)
+          claimed = chosen.flat_map { |file| ports_of(file) }
+          (chosen + project.select { |file| inside_and_unclaimed?(file, claimed) }).uniq.sort
+        end
+
+        def opted_in?(suite_path, project)
+          stand_ins(suite_path).any? || project.any? { |file| declarations(file).any?(&:stays_inside?) }
+        end
+
+        # @return [Array<String>] the stand-ins beside the suite
+        def stand_ins(suite_path) = Dir.glob(File.join(File.dirname(suite_path), STAND_INS, "*.adapter"))
+
+        # @return [Array<String>] the project's own adapters, found as the loader finds them
+        def project_adapters(files)
+          root = Ports::Loading.bootstrap.shared_root(nil, File.dirname(files.first))
+          return [] unless root
+
+          PROJECT_PATTERNS.flat_map { |pattern| Dir.glob(File.join(root, "adapters", pattern)) }.sort
+        end
+
+        def inside_and_unclaimed?(file, claimed)
+          declared = declarations(file)
+          declared.any? && declared.all?(&:stays_inside?) && !declared.map(&:port).intersect?(claimed)
+        end
+
+        def ports_of(file) = declarations(file).map(&:port)
+
+        # The adapters a file declares, read in a throwaway registry with its `require` lines left
+        # out, so an adapter that reaches outside is never constructed and its code never loads.
+        #
+        # @param file [String] an `.adapter` file
+        # @return [Array<Bluebook::Adapter>] none when the file cannot be read on its own
+        def declarations(file)
+          text = File.readlines(file).grep_v(REQUIRE_LINE).join
+          registry = Runtime::Registry.new
+          Hecks.with_registry(registry) { TOPLEVEL_BINDING.eval(text, file) }
+          registry.adapters.values
+        rescue StandardError, ScriptError
+          # A declaration that cannot be read without its code is treated as reaching outside.
+          []
+        end
+      end
+    end
+  end
+end

data/lib/hecks/behaviors/expectations/boot.rb

@@ -2,6 +2,7 @@ require_relative "../ir"
 require_relative "../../runtime/loader"
 require_relative "../../runtime/errors"
 require_relative "../../ports/persistence/binding_policy"
+require_relative "adapter_selection"
 
 module Hecks
   module Behaviors
@@ -25,24 +26,30 @@ module Hecks
         # @raise [Malformed] if any aggregate the suite boots is not bound to the
         #   default (Memory) adapter
         def runtime_for(suite)
-          files = Array(suite.loads).map { |path| File.expand_path(path) }
-          key   = files.map { |file| [file, File.exist?(file) ? File.mtime(file).to_f : nil] }
+          files    = Array(suite.loads).map { |path| File.expand_path(path) }
+          adapters = suite.path && AdapterSelection.call(suite.path, files)
+          key      = boot_key(files + Array(adapters))
 
           RUNTIMES_LOCK.synchronize do
-            RUNTIMES[key] ||= boot_and_guard(files)
+            RUNTIMES[key] ||= boot_and_guard(files, adapters)
           end
         end
 
+        # Each file with its mtime, so an edited file boots fresh.
+        def boot_key(files) = files.map { |file| [file, File.exist?(file) ? File.mtime(file).to_f : nil] }
+
         # Refuses at boot when any aggregate binds to a non-Memory adapter —
         # `reset_runtime_state!` only resets Memory's own per-instance store.
         #
         # @param files [Array<String>] absolute paths to the bluebook/hecksagon/world
         #   files to boot
+        # @param adapters [Array<String>, nil] the `.adapter` files `AdapterSelection` chose, or
+        #   nil for a suite with no file of its own
         # @return [Runtime::Dispatcher, Adapters::Lambda::RemoteDispatcher] the booted,
         #   Memory-only-guarded runtime
         # @raise [Malformed] if any aggregate is bound to a non-Memory adapter
-        def boot_and_guard(files)
-          runtime = Hecks.boot_files(files, install_driving: false)
+        def boot_and_guard(files, adapters = nil)
+          runtime = Hecks.boot_files(files, install_driving: false, adapters: adapters)
           guard_memory_only!(runtime)
           runtime
         end

data/lib/hecks/bluebook/acknowledgements.rb

@@ -15,7 +15,7 @@ module Hecks
       # itself. An undeclared coupling or a separate-ways breach has no relationship to carry the
       # allowance; the fix is to declare one.
       RELATIONSHIP_KINDS = %i[relationship_kind_mismatch conformist_translates unpublished_dependency
-                              unused_relationship redundant_relationship].freeze
+                              unused_relationship redundant_relationship core_conforms].freeze
 
       # @param owner [String] the declaration carrying the word, for the message
       # @param finding [Symbol, String] the kind being acknowledged

data/lib/hecks/bluebook/command.rb

@@ -85,7 +85,8 @@ module Hecks
         # @return [Boolean] whether a second delivery leaves the state a first one did
         def idempotent? = @idempotent ? true : false
 
-        # @return [Boolean] whether this command's own record may be written through an unminted boot
+        # @return [Boolean] whether this command's own record may be written through an unminted
+        #   boot
         def mints_era? = @mints_era ? true : false
 
         # @return [Array<String>] every role that may run it when more than one may, else empty
@@ -97,7 +98,7 @@ module Hecks
         # Mints one command as its own anonymous subclass of the class `declare` is called on.
         #
         # @param name [String, Symbol] the command's declared name
-        # @param role [String, nil] the declared role; `roles` all of them, `audience` who it is listed for
+        # @param role [String, nil] the declared role; `roles` all of them, `audience` who it is for
         # @param attributes [Array<Bluebook::Attribute>] the declared arguments
         # @param givens [Array<Bluebook::Given>] the declared preconditions
         # @param ensures [Array<Bluebook::Given>] the postconditions; `needs` the facts it supplies

data/lib/hecks/bluebook/declaration.rb

@@ -65,7 +65,8 @@ module Hecks
         #
         # @param row [Bluebook::Declaration::ModuleRow, #to_h] a `ModuleRow` already, or anything
         #   answering `to_h` with `name`/`vision`/`aggregate` entries
-        # @return [Bluebook::Declaration::ModuleRow] `row` itself if it already is one, else a new one
+        # @return [Bluebook::Declaration::ModuleRow] `row` itself if it already is one, else a new
+        #   one
         def self.from(row)
           return row if row.is_a?(self)
 

data/lib/hecks/bluebook/dsl/adapter_builder.rb

@@ -61,6 +61,13 @@ module Hecks
         # @return [Array<String>] every capability named so far, this one last
         def provides(capability) = @provides << capability.to_s
 
+        # Says this adapter reaches nothing outside the process and the checkout: no network, no
+        # model, no host side effect. A behaviors suite loads it instead of asking for a stand-in
+        # (ADR 0171); an adapter that does not say it is kept out of every suite.
+        #
+        # @return [true]
+        def stays_inside = @stays_inside = true
+
         # Names the wasm module this adapter runs, beside its `.adapter` file.
         #
         # @param file [String] the module's file name, such as `"occurrences.wasm"`
@@ -75,7 +82,8 @@ module Hecks
         def build
           MetaValidator.call_adapter(
             Adapter.new(name: @name, port: @port, fields: @fields, secrets: @secrets, defaults: @defaults,
-                        answers: @answers, runs: @runs, provides: @provides, source_dir: @source_dir)
+                        answers: @answers, runs: @runs, provides: @provides, source_dir: @source_dir,
+                        stays_inside: @stays_inside == true)
           )
         end
 

data/lib/hecks/bluebook/dsl/bluebook_builder/metadata.rb

@@ -26,18 +26,20 @@ module Hecks
             @namespace = value.to_s
           end
 
-          # Classifies this bluebook as core to the framework, rather than a domain built on it.
+          # Classifies this bluebook as the core subdomain: where the domain's advantage lies, which
+          # no generic context may depend on and which translates rather than conforms (ADR 0172).
           #
           # @return [Symbol] `:core`
           def core       = classify(:core)
 
-          # Classifies this bluebook as a supporting piece of the framework, rather than a domain
-          # built on it.
+          # Classifies this bluebook as a supporting subdomain: specific to this business, but not
+          # where its advantage lies.
           #
           # @return [Symbol] `:supporting`
           def supporting = classify(:supporting)
 
-          # Classifies this bluebook as generic infrastructure, rather than a domain built on it.
+          # Classifies this bluebook as a generic subdomain: a solved problem that could be bought
+          # or attached, so it may not depend on the core (ADR 0172).
           #
           # @return [Symbol] `:generic`
           def generic    = classify(:generic)

data/lib/hecks/bluebook/dsl/bluebook_builder/modules.rb

@@ -5,15 +5,18 @@ module Hecks
         # Groups a bluebook's aggregates in the modules it declares (ADR 0163). `domain_module
         # "Deliver" do … end` opens a block whose `aggregate` words are recorded under the module;
         # the module changes no aggregate, it names the task each one belongs to. Policies, read
-        # models and process managers inside the block are the bluebook's own, as they are outside it.
+        # models and process managers inside the block are the bluebook's own, as they are outside
+        # it.
         module Modules
           # Opens the module `name` and evaluates its body; a module of that name that an earlier
           # file opened gains the aggregates this body declares.
           #
           # @param name [String] the module's own name, such as `"Deliver"`
-          # @yield the module body: its vision, aggregates, policies, read models and process managers
+          # @yield the module body: its vision, aggregates, policies, read models and process
+          #   managers
           # @return [Array<Bluebook::Declaration::ModuleRow>] every membership declared so far
-          # @raise [Bluebook::DSL::Malformed] if a module opens inside another, or holds no aggregate
+          # @raise [Bluebook::DSL::Malformed] if a module opens inside another, or holds no
+          #   aggregate
           def domain_module(name, &)
             refuse_nested_module!(name)
             @open_module = name.to_s

data/lib/hecks/bluebook/dsl/bluebook_builder/validation/correlation_keys.rb

@@ -47,7 +47,8 @@ module Hecks
               bluebook.aggregates.find { |candidate| candidate.name.to_s == Naming.demodulise(key) }
             end
 
-            # The one field an aggregate is correlated by: its identity, or `id` when it declares none.
+            # The one field an aggregate is correlated by: its identity, or `id` when it declares
+            # none.
             # A value-object identity drops its trailing `.value`, so `Thing` reads as `Thing.id`.
             def identity_path(process_manager, aggregate)
               paths = aggregate.identity_paths.map(&:to_s)

data/lib/hecks/bluebook/dsl/command_builder/folded_sets.rb

@@ -2,10 +2,12 @@ module Hecks
   module Bluebook
     module DSL
       class CommandBuilder
-        # `attribute :name, Type, sets: true`: the argument and the plain `sets :name` that a following
+        # `attribute :name, Type, sets: true`: the argument and the plain `sets :name` that a
+        # following
         # line would record, at the same position among the command's mutations.
         module FoldedSets
-          # Declares one argument and, with `sets: true`, the plain `sets` of the owner's field of the
+          # Declares one argument and, with `sets: true`, the plain `sets` of the owner's field of
+          # the
           # same name.
           #
           # @param name [Symbol] the argument's name

data/lib/hecks/bluebook/dsl/generic_dispatch.rb

@@ -10,7 +10,8 @@ module Hecks
 
         COERCE_BY_KIND = { "text" => :to_s, "symbol" => :to_sym }.freeze
 
-        # The arguments of one word call: its positional arguments, its keyword arguments, and its block.
+        # The arguments of one word call: its positional arguments, its keyword arguments, and its
+        # block.
         Invocation = Struct.new(:args, :kwargs, :block)
 
         # Not derivable from `fills:` (these rows all carry `fills: ""`) — the append target

data/lib/hecks/bluebook/hecksagon.rb

@@ -19,10 +19,10 @@ module Hecks
     # and names the queries it `answers` (`"Bluebook::Aggregate.Query"`); it needs no port, and the
     # runtime binds each query it answers without a hecksagon line.
     #
-    # `provides` names what the adapter can do beyond its port's contract, such as
-    # `"set_transform"`; a caller asks before relying on it.
+    # `provides` names what it can do beyond its port's contract (`"set_transform"`), and
+    # `stays_inside` is true when it reaches nothing outside the process and checkout (ADR 0171).
     Adapter = Struct.new(:name, :port, :fields, :secrets, :defaults, :answers, :runs, :provides, :source_dir,
-                         keyword_init: true) do
+                         :stays_inside, keyword_init: true) do
       def declares?(field) = all_fields.include?(field.to_sym)
 
       def all_fields = (fields || []) + (secrets || [])
@@ -40,6 +40,9 @@ module Hecks
       # @return [Boolean] whether this adapter declares `provides` for it
       def provides?(capability) = capabilities.include?(capability.to_s)
 
+      # @return [Boolean] whether this adapter says it stays inside
+      def stays_inside? = stays_inside == true
+
       # @return [Boolean] whether this adapter is a wasm plugin
       def plugin? = !runs.nil?
 

data/lib/hecks/bluebook/meta_validator/adapter_judge.rb

@@ -36,14 +36,21 @@ module Hecks
         end
 
         def judge!
-          send_to("Adapter::Adapter.Declare", @adapter.name, name: v(@adapter.name), port: v(@adapter.port),
-                                                             runs: v(@adapter.runs))
+          declare
           add_fields
           add_all("AddSecret", @adapter.secrets)
           add_all("AnswerQuery", @adapter.answered_queries)
           add_all("Provide", @adapter.capabilities)
         end
 
+        # Offers the `Declare` that names the adapter, its port, its plugin module and its reach.
+        def declare
+          send_to("Adapter::Adapter.Declare", @adapter.name, name: v(@adapter.name), port: v(@adapter.port),
+                                                             runs: v(@adapter.runs), stays_inside: v(containment))
+        end
+
+        def containment = ("inside" if @adapter.stays_inside?)
+
         # Offers one `AddField` per field, each with its declared default when it has one.
         def add_fields
           Array(@adapter.fields).each do |field|

data/lib/hecks/bluebook/meta_validator.rb

@@ -73,7 +73,7 @@ module Hecks
       def self.call_adapter(adapter)
         judge_artifact(adapter, AdapterJudge, "#{adapter.name}'s adapter") do
           JSON.generate([adapter.name, adapter.port, adapter.fields, adapter.secrets, adapter.declared_defaults,
-                         adapter.answered_queries, adapter.runs, adapter.capabilities])
+                         adapter.answered_queries, adapter.runs, adapter.capabilities, adapter.stays_inside?])
         end
       end
 

data/lib/hecks/bluebook/model_check/aggregate_checks.rb

@@ -36,7 +36,8 @@ module Hecks
           end
         end
 
-        # @return [Array<Bluebook::Aggregate>] the aggregates with no commands that do not acknowledge it
+        # @return [Array<Bluebook::Aggregate>] the aggregates with no commands that do not
+        #   acknowledge it
         def unacknowledged_commandless(bluebook)
           commandless = bluebook.aggregates.select { |aggregate| aggregate.commands.empty? }
           commandless.reject { |aggregate| Acknowledgements.held?(aggregate, :no_command_surface) }

data/lib/hecks/bluebook/model_check/classification_checks.rb

@@ -0,0 +1,51 @@
+module Hecks
+  module Bluebook
+    module ModelCheck
+      # The checks a bluebook's `core`, `supporting` or `generic` keys (ADR 0172): a generic
+      # subdomain may not depend on the core, and a core context should translate what it takes
+      # from another rather than conform to it. Classifications are read from each bluebook, never
+      # restated in a context map.
+      module ClassificationChecks
+        # @param edges [Array<Hash>] `Projections::ContextRelationships.call`, from the context that
+        #   depends to the one it depends on
+        # @param classifications [Hash{String => String}] each context to its classification
+        # @return [Array<Finding>] one error per generic context that depends on a core one
+        def generic_depends_on_core_findings(edges, classifications)
+          edges.select { |edge| generic_on_core?(edge, classifications) }.uniq { |edge| [edge[:from], edge[:to]] }.map do |edge|
+            Finding.new(kind: :generic_depends_on_core, severity: :error, subject: "#{edge[:from]} -> #{edge[:to]}",
+                        message: "#{edge[:from]} is generic but depends on #{edge[:to]}, which is core " \
+                                 "(#{edge[:kind]}#{" via #{edge[:via]}" if edge[:via]}); a generic subdomain must be " \
+                                 "replaceable, so invert the dependency or reclassify one of them")
+          end
+        end
+
+        # @param map [Bluebook::ContextMap] the declared map
+        # @param classifications [Hash{String => String}] each context to its classification
+        # @return [Array<Finding>] one warning per declared conformist relationship whose downstream
+        #   is core, unless the relationship acknowledges it. The conformist ADR 0155 implies for an
+        #   `attaches` is not declared and is not read.
+        def core_conforms_findings(map, classifications)
+          map.relationships.filter_map do |relationship|
+            next unless core_conformist?(relationship, classifications)
+
+            Finding.new(kind: :core_conforms, severity: :warning,
+                        subject: "#{relationship.downstream} <- #{relationship.upstream}",
+                        message: "#{relationship.downstream} is core but conforms to #{relationship.upstream}; " \
+                                 "the core model should translate what it receives (an anticorruption_layer)")
+          end
+        end
+
+        private
+
+        def generic_on_core?(edge, classifications)
+          classifications[edge[:from].to_s] == "generic" && classifications[edge[:to].to_s] == "core"
+        end
+
+        def core_conformist?(relationship, classifications)
+          relationship.kind == :conformist && !relationship.implied &&
+            classifications[relationship.downstream.to_s] == "core" && !relationship.acknowledges?(:core_conforms)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/model_check/context_checks.rb

@@ -1,4 +1,5 @@
 require_relative "context_map_checks"
+require_relative "classification_checks"
 
 module Hecks
   module Bluebook
@@ -7,6 +8,7 @@ module Hecks
       # this hecksagon acknowledges, and no two contexts may depend on each other in a cycle.
       module ContextChecks
         include ContextMapChecks
+        include ClassificationChecks
 
         # The edge kinds that couple two contexts at run time. A shared kernel merges in-process, so
         # two contexts attaching each other is a different question and is left out.

data/lib/hecks/bluebook/model_check/redundant_relationships.rb

@@ -21,7 +21,8 @@ module Hecks
           end
         end
 
-        # @return [Boolean] whether the relationship is a bare conformist that attaches alone explain
+        # @return [Boolean] whether the relationship is a bare conformist that attaches alone
+        #   explain
         def restates_attach?(relationship, edges)
           return false unless relationship.kind == :conformist && relationship.published.to_a.empty?
 

data/lib/hecks/ci_speed/adapters/shard_partitioner.adapter

@@ -0,0 +1,7 @@
+# Binds the `Planner` port to `ShardPartitioner`, which splits a family's files and writes the plan.
+# Required by name, not relative, so a copy of this directory shares the one implementation loaded.
+require "hecks/ci_speed/adapters/shard_partitioner"
+
+Hecks.adapter "ShardPartitioner" do
+  port "Planner"
+end

data/lib/hecks/ci_speed/adapters/shard_partitioner.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "hecks/tools/shard_planner"
+
+module Hecks
+  module Adapters
+    # The `Planner` port's adapter: splits a family's files among its shards with the shared
+    # longest-processing-time planner and writes the plan where the shard legs read it:
+    # `group-<n>.txt` (one file per line), `runtimes.log` (every file's price, for the leg's own
+    # worker split) and `plan.json`.
+    class ShardPartitioner
+      # @param aggregate [Object, nil] unused
+      # @param root [String, nil] the checkout patterns are read in; the working directory if nil
+      def initialize(aggregate: nil, root: nil)
+        @root = root || Dir.pwd
+      end
+
+      # @param held [Hash] the `ShardPlan` record and the ask's arguments: `shards`, `items_from`,
+      #   `out_dir`, `source` (`timings` or `size`) and `timings`
+      # @return [Hash] `shards:`, `files:` and the predicted `longest` and `mean` leg price
+      # @raise [ArgumentError] when there is nothing to split
+      def partition(**held)
+        plan = held.transform_values { |value| value.is_a?(Hash) ? value[:value] : value }
+        items = items_of(plan.fetch(:items_from))
+        raise ArgumentError, "no files to split in #{plan[:items_from]}" if items.empty?
+
+        prices = prices_of(items, plan)
+        groups = Tools::ShardPlanner.partition(items, plan.fetch(:shards), prices)
+        write(plan.fetch(:out_dir), groups, prices, plan.fetch(:source))
+        answer(groups, prices)
+      end
+
+      private
+
+      def items_of(from)
+        kind, spec = from.split(":", 2)
+        found = kind == "glob" ? Dir.glob(spec, base: @root) : File.readlines(File.join(@root, spec), chomp: true)
+        named = found.map(&:strip).reject(&:empty?)
+        named.uniq.sort
+      end
+
+      def prices_of(items, plan)
+        table = plan[:source] == "timings" ? Tools::ShardPlanner.parse(plan[:timings]) : {}
+        Tools::ShardPlanner.prices(items, table, ->(item) { File.size?(File.join(@root, item)) || 1 })
+      end
+
+      def write(dir, groups, prices, source)
+        out = File.join(@root, dir)
+        FileUtils.mkdir_p(out)
+        groups.each_with_index { |files, index| File.write(File.join(out, "group-#{index + 1}.txt"), listing(files)) }
+        File.write(File.join(out, "runtimes.log"), listing(prices.map { |file, price| "#{file}:#{price}" }.sort))
+        File.write(File.join(out, "plan.json"), JSON.pretty_generate(source: source, groups: groups))
+      end
+
+      def listing(lines) = lines.empty? ? "" : "#{lines.join("\n")}\n"
+
+      def answer(groups, prices)
+        loads = groups.map { |files| files.sum { |file| prices.fetch(file) } }
+        { shards: { value: groups.size }, files: { value: prices.size },
+          longest: { value: loads.max.round(2) }, mean: { value: (loads.sum / loads.size).round(2) } }
+      end
+    end
+  end
+end

data/lib/hecks/ci_speed/adapters/timings_source.adapter

@@ -0,0 +1,7 @@
+# Binds the `TimingsSource` port to `TimingsSource`, which finds the previous main run's per-file timings.
+# Required by name, not relative, so a copy of this directory shares the one implementation loaded.
+require "hecks/ci_speed/adapters/timings_source"
+
+Hecks.adapter "TimingsSource" do
+  port "TimingsSource"
+end

data/lib/hecks/ci_speed/adapters/timings_source.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "tmpdir"
+require "hecks/tools/shard_planner"
+
+module Hecks
+  module Adapters
+    # The `TimingsSource` port's adapter: finds the seconds each file took in the newest successful
+    # CI run on main. `timings_from` is a directory of timing logs already on disk, or `main`, which
+    # downloads the runtime-log artifacts of that run through `gh`. It refuses when it finds no
+    # timing at all, and the bluebook's fallback policy plans by file size instead.
+    class TimingsSource
+      # Raised when no timing could be read; it is the reason `TimingsUnavailable` carries.
+      class Unavailable < StandardError; end
+
+      # The CI workflow whose runs on main hold the artifacts.
+      WORKFLOW = "ci.yml"
+
+      # @param aggregate [Object, nil] unused
+      def initialize(aggregate: nil); end
+
+      # @param held [Hash] the `ShardPlan` record: `name` and `timings_from`
+      # @return [Hash] `timings:` the merged `path:seconds` lines of every log found
+      # @raise [Unavailable] when there is no run, no artifact or no readable timing
+      def fetch(**held)
+        name, from = held.values_at(:name, :timings_from).map { |value| value.is_a?(Hash) ? value[:value] : value }
+        table = Tools::ShardPlanner.merge(logs_in(from == "main" ? download(name) : from))
+        raise Unavailable, "no timings found in #{from}" if table.empty?
+
+        { timings: { value: table.map { |file, seconds| "#{file}:#{seconds}" }.sort.join("\n") } }
+      end
+
+      private
+
+      # @return [Array<String>] the text of every file under `directory`
+      def logs_in(directory)
+        raise Unavailable, "#{directory} is not a directory" unless File.directory?(directory.to_s)
+
+        files = Dir.glob(File.join(directory, "**", "*")).select { |path| File.file?(path) }
+        files.sort.map { |path| File.read(path) }
+      end
+
+      # Downloads the runtime logs of the newest successful run on main into a new directory.
+      #
+      # @return [String] the directory
+      def download(name)
+        run = newest_run
+        dir = Dir.mktmpdir("shard-timings-")
+        pattern = "#{name.tr("_", "-")}-runtime-group-*"
+        _, err, status = Open3.capture3("gh", "run", "download", run, "--pattern", pattern, "--dir", dir)
+        raise Unavailable, "could not download #{pattern} of run #{run}: #{err.strip}" unless status.success?
+
+        dir
+      end
+
+      # @return [String] the id of the newest successful run of the CI workflow on main
+      def newest_run
+        out, err, status = Open3.capture3("gh", "run", "list", "--workflow", WORKFLOW, "--branch", "main",
+                                          "--status", "success", "--limit", "1", "--json", "databaseId")
+        raise Unavailable, "could not list CI runs: #{err.strip}" unless status.success?
+
+        JSON.parse(out).dig(0, "databaseId")&.to_s or raise Unavailable, "no successful CI run on main"
+      end
+    end
+  end
+end