hecks 2.5.1 → 2.7.0

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

@@ -11,8 +11,17 @@ module Hecks
         # Starts with no settings recorded.
         def initialize = @values = {}
 
-        def method_missing(key, *args, &)
-          @values[key.to_sym] = args.size == 1 ? args.first : args
+        # A call with a block records the block's own settings as a nested Hash, so a bind can
+        # group settings (`preview do ... end`); a call without one records its argument.
+        def method_missing(key, *args, &block)
+          @values[key.to_sym] =
+            if block
+              nested = SettingsCollector.new
+              nested.instance_eval(&block)
+              nested.to_h
+            else
+              args.size == 1 ? args.first : args
+            end
         end
 
         def respond_to_missing?(_name, _include_private = false) = true
@@ -96,6 +105,35 @@ module Hecks
           @latest = required(value, "latest version")
         end
 
+        # Names the connection every chapter's database-taking persistence adapter uses
+        # unless that chapter's own world settings name one.
+        #
+        # Answers the `default_database` word through the table's `calls:` column, the
+        # same way `realm_impl` does. A chapter's own
+        # `persisted_by("Adapter") { database ... }` still wins for that adapter.
+        #
+        # @param value [String] the connection, such as a database URL; blankness is
+        #   judged by the world language at `build`, not here
+        # @return [String] the connection as stored
+        def default_database_impl(value)
+          @default_database = required(value, "default database")
+        end
+
+        # Names the persistence adapter every aggregate binds to unless its own chapter's
+        # hecksagon binds it.
+        #
+        # Answers the `default_adapter` word through the table's `calls:` column, the same
+        # way `realm_impl` does. Sits between an explicit bind and the framework's
+        # in-memory fallback; whether the adapter really is a persistence adapter is
+        # judged at boot, where adapters are known.
+        #
+        # @param value [String, Symbol] the adapter's declared name, such as `"PostgresEra"`;
+        #   blankness is judged by the world language at `build`, not here
+        # @return [String] the adapter name as stored
+        def default_adapter_impl(value)
+          @default_adapter = required(value, "default adapter")
+        end
+
         def method_missing(verb, *args, **kwargs, &block)
           result = word_gate_dispatch(verb, args, kwargs, block)
           return result unless result.equal?(WordGate::NOT_ADMITTED)
@@ -134,7 +172,8 @@ module Hecks
         #   as a blank `realm`
         def build
           MetaValidator.call_world(
-            World.new(domain: @domain, realm: @realm, latest: @latest, settings: @settings)
+            World.new(domain: @domain, realm: @realm, latest: @latest, settings: @settings,
+                      default_database: @default_database, default_adapter: @default_adapter)
           )
         end
 

data/lib/hecks/bluebook/hexagon.rb

@@ -97,9 +97,10 @@ module Hecks
       include Hecks::IR
       include Behaviour::World
 
-      emits_ir(domain: :domain, realm: :realm, latest: :latest, settings: :settings)
+      emits_ir(domain: :domain, realm: :realm, latest: :latest, settings: :settings,
+               default_database: :default_database, default_adapter: :default_adapter)
 
-      attr_reader :domain, :realm, :latest, :settings
+      attr_reader :domain, :realm, :latest, :settings, :default_database, :default_adapter
 
       # @param domain [String, Symbol] the domain this world configures
       # @param realm [String, Symbol, nil] the declared realm/version marker, or `nil`
@@ -108,11 +109,18 @@ module Hecks
       #   if none is declared
       # @param settings [Hash] the declared adapter bind settings, keyed by verb and,
       #   for a qualified entry, `"verb:adapter"`
-      def initialize(domain:, realm: nil, latest: nil, settings: {})
-        @domain   = domain.to_s
-        @realm    = realm&.to_s
-        @latest   = latest&.to_s
-        @settings = settings
+      # @param default_database [String, nil] the connection every chapter's
+      #   database-taking persistence adapter uses unless its own settings name one,
+      #   or `nil` if none is declared
+      # @param default_adapter [String, nil] the persistence adapter every aggregate
+      #   binds to unless its chapter's hecksagon binds it, or `nil` if none is declared
+      def initialize(domain:, realm: nil, latest: nil, settings: {}, default_database: nil, default_adapter: nil)
+        @domain           = domain.to_s
+        @realm            = realm&.to_s
+        @latest           = latest&.to_s
+        @settings         = settings
+        @default_database = default_database&.to_s
+        @default_adapter  = default_adapter&.to_s
       end
     end
   end

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

@@ -40,7 +40,9 @@ module Hecks
         def judge!
           domain = @world.domain
           send_to("World::World.Declare", domain, domain: v(domain),
-                  realm: v(@world.realm), latest: v(@world.latest))
+                  realm: v(@world.realm), latest: v(@world.latest),
+                  default_database: v(@world.default_database),
+                  default_adapter: v(@world.default_adapter))
 
           Hash(@world.settings).each do |verb, values|
             # the DSL records each binding twice — once by verb, once by

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

@@ -0,0 +1,153 @@
+module Hecks
+  module Bluebook
+    module ModelCheck
+      # The opt-in `client` profile: refuses the bluebook constructs this
+      # repository already knows produce a silently wrong answer, so a client
+      # domain cannot reach one without being told.
+      #
+      # ## What it is not
+      #
+      # It fixes nothing. Each rule below names a bug that is still open and
+      # stops a domain reaching it unnoticed; when the bug is fixed the rule
+      # goes with it. `spec/model_check_client_profile_spec.rb` holds a probe
+      # per rule that runs the buggy code and fails the moment the bug stops
+      # reproducing, naming the rule to delete.
+      #
+      # ## The rules
+      #
+      # - `:client_group_by_row_drop` — a `group_by` whose fields do not include
+      #   the grouped aggregate's whole identity. Rows sharing a key path are
+      #   collapsed to the first, on every adapter (docs/decisions/0061).
+      # - `:client_native_read_model` — a read model the SQLite projection
+      #   answers natively, where every other path answers it in process
+      #   (docs/1.0-readiness.md, "Known gaps at 1.0", item 2).
+      # - `:client_dotted_compute_source` — an era translation `compute` whose
+      #   source is a dotted path, which never fires
+      #   (`Translation::RuleCompiler.compile_compute`).
+      module ClientProfile
+        # Adapters whose Ruby class implements `query_read_model`, which is what
+        # makes `ReadModelInterpreter#project` take the native path. The spec
+        # checks this list against the adapter classes themselves.
+        NATIVE_READ_MODEL_ADAPTERS = %w[SqliteProjection].freeze
+
+        GROUP_BY_TRACKER = "docs/decisions/0061-query-dsl-aggregation-count-sum-group-by.md".freeze
+        NATIVE_READ_MODEL_TRACKER = "docs/1.0-readiness.md (Known gaps at 1.0, item 2)".freeze
+        DOTTED_COMPUTE_TRACKER = "Translation::RuleCompiler.compile_compute, and the pending example " \
+                                 "\"applies the SQL of a compute whose source is a dotted member\" in " \
+                                 "spec/adapters/driven/postgres_era/migration_data_safety_spec.rb".freeze
+
+        module_function
+
+        # Runs every client-profile rule over one chapter and its translations.
+        #
+        # @param bluebook [Bluebook::Chapter] the assembled chapter to check
+        # @param hecksagon [Bluebook::Hecksagon, nil] the chapter's sibling wiring file; without
+        #   one no aggregate is projected, so the native-read-model rule has nothing to find
+        # @param translations [Array<Bluebook::Translation>] the data translations declared for
+        #   this chapter's domain
+        # @return [Array<ModelCheck::Finding>] one error-severity finding per construct refused
+        def call(bluebook, hecksagon: nil, translations: [])
+          bluebook.read_models.flat_map do |model|
+            group_by_findings(bluebook, model) + native_read_model_findings(model, hecksagon)
+          end + dotted_compute_findings(translations)
+        end
+
+        # Refuses a `group_by` that cannot prove each of its key paths names one row.
+        #
+        # The interpreter's `nest` keeps `stripped.first` per key path, whichever adapter
+        # supplied the rows, because a `group_by` model never reaches the native path. Grouping
+        # by the aggregate's whole identity is the one shape that cannot collide.
+        #
+        # @param bluebook [Bluebook::Chapter] the chapter the read model is declared in
+        # @param model [Bluebook::ReadModel] the read model to inspect
+        # @return [Array<ModelCheck::Finding>] one finding, or `[]` when `model` declares no
+        #   `group_by` or groups by its aggregate's whole identity
+        def group_by_findings(bluebook, model)
+          return [] if model.group_by.empty? || groups_by_identity?(bluebook, model)
+
+          [finding(:client_group_by_row_drop, model.name,
+                   "group_by #{model.group_by_fields.map(&:inspect).join(', ')} does not cover the grouped " \
+                   "aggregate's whole identity, so rows sharing a key path are silently reduced to the " \
+                   "first. Tracked in #{GROUP_BY_TRACKER}.")]
+        end
+
+        # Refuses a read model that the SQLite projection would answer natively.
+        #
+        # Mirrors the fork in `ReadModelInterpreter#project`: a rooted model with no `group_by`,
+        # `count` or `median` reads through `read_repository`, which is a projection repository
+        # only for an aggregate with a `projected_by` bind. Whether that projection is current
+        # is only known at run time (`Registry#projection_current?`), so a model eligible here
+        # can also silently run in process.
+        #
+        # @param model [Bluebook::ReadModel] the read model to inspect
+        # @param hecksagon [Bluebook::Hecksagon, nil] the wiring holding the `projected_by` binds
+        # @return [Array<ModelCheck::Finding>] one finding, or `[]` when the model cannot be
+        #   pushed down
+        def native_read_model_findings(model, hecksagon)
+          return [] unless hecksagon && native_eligible?(model)
+
+          bind = hecksagon.binds_for(model.reference_target, Ports::Projection::VERB).first
+          return [] unless bind && NATIVE_READ_MODEL_ADAPTERS.include?(bind.adapter.to_s)
+
+          [finding(:client_native_read_model, model.name,
+                   "#{model.reference_target} is projected_by #{bind.adapter.inspect}, so this read model " \
+                   "is answered by SQL when the projection is current and by the in-process loop when it " \
+                   "is not, and nothing checks the two agree. Tracked in #{NATIVE_READ_MODEL_TRACKER}.")]
+        end
+
+        # Refuses a translation `compute` whose source names a member of a value object.
+        #
+        # `compile_compute` guards the compute with `__s ? '<from>'`, a top-level key test, so a
+        # dotted source never matches, the mint succeeds and the record keeps its old value.
+        #
+        # @param translations [Array<Bluebook::Translation>] the translations to inspect
+        # @return [Array<ModelCheck::Finding>] one finding per dotted-source compute
+        def dotted_compute_findings(translations)
+          translations.flat_map do |translation|
+            translation.aggregates.flat_map do |aggregate|
+              aggregate.computes.select { |compute| compute.from.to_s.include?(".") }.map do |compute|
+                finding(:client_dotted_compute_source, "#{translation.domain}::#{aggregate.name}",
+                        "compute #{compute.from.to_s.inspect} has a dotted source, which the compiled SQL " \
+                        "never matches, so the mint succeeds and leaves the old value in place. " \
+                        "Tracked in #{DOTTED_COMPUTE_TRACKER}.")
+              end
+            end
+          end
+        end
+
+        # Reports whether a model's shape sends it down the native path in `#project`.
+        #
+        # @param model [Bluebook::ReadModel] the read model to inspect
+        # @return [Boolean] true for a rooted model declaring no `group_by`, `count` or `median`
+        def native_eligible?(model)
+          !model.reference_target.nil? && model.group_by.empty? && !model.count? && !model.median_field
+        end
+
+        # Reports whether a `group_by` names every identity path of the aggregate it groups.
+        #
+        # @param bluebook [Bluebook::Chapter] the chapter the read model is declared in
+        # @param model [Bluebook::ReadModel] a read model that declares a `group_by`
+        # @return [Boolean] false when the many-side aggregate is not a top-level aggregate or
+        #   declares no identity, since uniqueness cannot then be shown
+        def groups_by_identity?(bluebook, model)
+          target = model.aggregate_heads.find { |head| head[:many] }
+          aggregate = target && bluebook.aggregate(target[:aggregate])
+          return false unless aggregate
+
+          identity = Array(aggregate.identity_heads).map(&:to_sym)
+          !identity.empty? && (identity - model.group_by_fields.map(&:to_sym)).empty?
+        end
+
+        # Builds one error-severity finding of this profile.
+        #
+        # @param kind [Symbol] the finding's kind, one of the `:client_*` rules above
+        # @param subject [String] the read model or `Domain::Aggregate` the finding is about
+        # @param message [String] what was found, why it is refused, and where it is tracked
+        # @return [ModelCheck::Finding] an `:error` finding
+        def finding(kind, subject, message)
+          ModelCheck::Finding.new(kind: kind, severity: :error, subject: subject, message: message)
+        end
+      end
+    end
+  end
+end

data/lib/hecks/bluebook/model_check.rb

@@ -1,4 +1,5 @@
 require "hecks/vocabulary"
+require_relative "model_check/client_profile"
 
 module Hecks
   module Bluebook
@@ -100,6 +101,9 @@ module Hecks
         # was needed or made.
       }.freeze
 
+      # The profiles `call` accepts; `nil` is the default, unprofiled run.
+      PROFILES = %i[client].freeze
+
       module_function
 
       # Runs every static model check over `bluebook` and returns what it
@@ -137,9 +141,23 @@ module Hecks
       #   target, raising `rust_reserved_name` findings to error
       # @param strict [Boolean] whether to raise every `rust_reserved_name`
       #   finding to error regardless of `rust_target`
+      # @param profile [Symbol, nil] `:client` adds `ClientProfile`'s error
+      #   findings for constructs known to answer wrongly without refusing;
+      #   `nil` (the default) adds nothing and leaves every other finding as
+      #   it was
+      # @param translations [Array<Bluebook::Translation>] the data
+      #   translations declared for this chapter's domain, read only by the
+      #   `:client` profile — they live on the registry, not the chapter, so
+      #   the caller supplies them the way it supplies `hecksagon`
       # @return [Array<Finding>] every finding this bluebook triggers,
       #   across its lifecycles, sagas, policies, and Rust-reserved names
-      def call(bluebook, hecksagon: nil, known_domains: nil, global_emitted_events: nil, rust_target: false, strict: false)
+      # @raise [ArgumentError] if `profile` is neither `nil` nor `:client`
+      def call(bluebook, hecksagon: nil, known_domains: nil, global_emitted_events: nil, rust_target: false, strict: false,
+               profile: nil, translations: [])
+        unless profile.nil? || PROFILES.include?(profile)
+          raise ArgumentError, "unknown profile #{profile.inspect} (known: #{PROFILES.inspect})"
+        end
+
         findings = []
         bluebook.aggregates.each do |aggregate|
           findings.concat(lifecycle_findings(aggregate, aggregate))
@@ -152,6 +170,7 @@ module Hecks
         findings.concat(rust_reserved_name_findings(domain_name: bluebook.name,
                                                     aggregate_names: bluebook.aggregates.map(&:hecks_name),
                                                     rust_target: rust_target, strict: strict))
+        findings.concat(ClientProfile.call(bluebook, hecksagon: hecksagon, translations: translations)) if profile == :client
         findings
       end
 
@@ -774,7 +793,7 @@ module Hecks
 
         # **Typo detection, deliberately weaker** — `known_domains` can only
         # ever be a monorepo-scoped heuristic: a real external hecks
-        # consumer's own domain (this repo's own embryonaut/lifeadelics-
+        # consumer's own domain (this repo's own embryonaut client-
         # shaped case) lives in a genuinely separate repository this
         # corpus scan can never see, so a target this check cannot find
         # is "unknown to THIS corpus," never proof of a typo. A target

data/lib/hecks/embryonaut_bluebook/lock.rb

@@ -0,0 +1,72 @@
+require "digest"
+
+module Hecks
+  module EmbryonautBluebook
+    # What a vendored package records about the release it came from:
+    # `vendor/embryonaut_bluebooks/<name>/bluebook.lock`.
+    #
+    # ## File format
+    #
+    # One `key: value` line each for `package`, `version`, `tag`, `commit`
+    # and `digest`, then one `shape: <Domain> <label>` line per domain:
+    #
+    #     package: payments
+    #     version: 1.2.0
+    #     tag: payments-v1.2.0
+    #     commit: <full commit id the tag points at>
+    #     digest: <sha256 of the vendored *.bluebook files>
+    #     shape: Payments d33c23
+    #
+    # The digest is the sha256 of the `<sha256>  <name>` lines of every
+    # top-level `*.bluebook` file, sorted by name. The source repository's own
+    # `bin/bluebook_digest` prints the same number for the tagged release, which
+    # is how a vendored copy is proven to be exactly what it claims to be.
+    Lock = Struct.new(:package, :version, :tag, :commit, :digest, :shape, keyword_init: true) do
+      # Computes the content digest of a directory's `*.bluebook` files.
+      #
+      # @param dir [String] the directory to measure
+      # @return [String, nil] 64 lowercase hex characters, nil when the directory holds
+      #   no bluebook file
+      def self.digest_of(dir)
+        names = Dir.children(dir).select { |name| name.end_with?(".bluebook") }.sort
+        return nil if names.empty?
+
+        lines = names.map { |name| "#{Digest::SHA256.file(File.join(dir, name)).hexdigest}  #{name}\n" }
+        Digest::SHA256.hexdigest(lines.join)
+      end
+
+      # Reads a lock file.
+      #
+      # @param path [String] the `bluebook.lock` path
+      # @return [Lock, nil] the parsed lock, nil when the file does not exist
+      def self.read(path)
+        return nil unless File.file?(path)
+
+        parse(File.read(path))
+      end
+
+      # Parses a lock's text.
+      #
+      # @param text [String] the file's content
+      # @return [Lock] the lock, with `shape` as an Array of lines (empty when none)
+      def self.parse(text)
+        fields = { shape: [] }
+        text.each_line do |line|
+          key, _, value = line.chomp.partition(": ")
+          next if key.empty?
+
+          key == "shape" ? fields[:shape] << value : fields[key.to_sym] = value
+        end
+        new(**fields.slice(*members))
+      end
+
+      # Renders the lock as the text written to `bluebook.lock`.
+      #
+      # @return [String] the lines described above, newline terminated
+      def to_s
+        header = %i[package version tag commit digest].map { |key| "#{key}: #{self[key]}\n" }
+        (header + Array(shape).map { |line| "shape: #{line}\n" }).join
+      end
+    end
+  end
+end

data/lib/hecks/embryonaut_bluebook/shape.rb

@@ -0,0 +1,47 @@
+require_relative "../ports/persistence/plugins/era/storage_shape"
+
+module Hecks
+  module EmbryonautBluebook
+    # The storage-shape labels of a directory of `*.bluebook` files.
+    #
+    # A label is what `PostgresEra` mints an era from, so a vendored package
+    # whose label changed is one whose next deploy mints a new era. This reads
+    # the files the way the era guard reads a held era's text: parse only, no
+    # boot, no wiring, no database, each file loaded into a scratch registry.
+    module Shape
+      module_function
+
+      # Measures every domain a directory's bluebook files declare.
+      #
+      # @param dir [String] a directory holding `*.bluebook` files
+      # @return [Array<String>] one `"<Domain> <label>"` line per domain, sorted by domain name
+      # @raise [Vendoring::Error] if the directory holds no bluebook file, or the files do
+      #   not load, the refusal a boot would raise
+      def labels(dir)
+        files = Dir[File.join(dir, "*.bluebook")]
+        raise Vendoring::Error, "no *.bluebook files in #{dir}" if files.empty?
+
+        load_all(files).bluebooks.sort_by { |name, _| name.to_s }.map do |name, bluebook|
+          "#{name} #{Runtime::StorageShape.mint_label(bluebook)}"
+        end
+      end
+
+      # Loads bluebook files into a registry of their own.
+      #
+      # @param files [Array<String>] absolute bluebook file paths, in load order
+      # @return [Runtime::Registry] the scratch registry holding what the files declared
+      # @raise [Vendoring::Error] if any file fails to load
+      def load_all(files)
+        scratch = Runtime::Registry.new
+        library = Ports::Loading.bootstrap
+        Hecks.with_registry(scratch) do
+          library.load_library
+          files.each { |file| Kernel.load(file) }
+        end
+        scratch
+      rescue StandardError, ScriptError => e
+        raise Vendoring::Error, "the bluebook files do not load: #{e.class}: #{e.message.lines.first.to_s.strip}"
+      end
+    end
+  end
+end

data/lib/hecks/embryonaut_bluebook/vendor.rb

@@ -0,0 +1,194 @@
+require "fileutils"
+require_relative "../vendoring"
+require_relative "lock"
+require_relative "shape"
+
+module Hecks
+  module EmbryonautBluebook
+    # Vendors one package of the bluebook registry into a consuming project.
+    #
+    # ## What it does
+    #
+    # Pins the package's top-level `bluebook/*.bluebook` files from one commit
+    # of a local source repository into
+    # `<root>/vendor/embryonaut_bluebooks/<name>/bluebook/`, where `load!`
+    # resolves them. Only bluebook files are taken: a `.hecksagon`, `.port` or
+    # `.adapter` is a wiring decision for whoever deploys, never part of the
+    # vendored package.
+    #
+    # ## Releases and bare commits
+    #
+    # The source repository tags each release `<name>-v<X.Y.Z>` on a commit
+    # whose `<name>/bluebook.yml` says that version. A release pin (`ref` nil for
+    # the newest tag, `"1.2.0"`, or the tag name) also writes `bluebook.lock`,
+    # which records version, tag, commit, content digest and storage shape, and
+    # holds two refusals, because a production project is bound to `PostgresEra`:
+    #
+    # - a version lower than the vendored one, unless `allow_downgrade`;
+    # - a storage-shape change that does not raise the version by at least a
+    #   minor, so a new era shows in the version number and not only in a hash.
+    #
+    # Any other commit-ish pins that commit and writes only the marker, with no
+    # lock and no version checks. Either way nothing on disk changes when a
+    # pin is refused or its files do not load.
+    class Vendor
+      # A release version, `X.Y.Z`.
+      VERSION = /\A\d+\.\d+\.\d+\z/
+
+      # A package name is a directory name and a bluebook name stem.
+      NAME = /\A[a-z][a-z0-9_]*\z/
+
+      # What a vendoring changed.
+      #
+      # @!attribute [r] previous_version
+      #   @return [String, nil] the version recorded before, nil when there was none
+      # @!attribute [r] previous_shape
+      #   @return [Array<String>, nil] the shape lines measured before, nil when there was
+      #   no earlier copy
+      Result = Struct.new(:package, :commit, :version, :tag, :digest, :shape,
+                          :previous_version, :previous_shape, :dir, keyword_init: true) do
+        # Says whether this was a release pin, which writes a lock.
+        #
+        # @return [Boolean] true for a release, false for a bare commit
+        def release? = !tag.nil?
+
+        # Says whether the storage shape moved since the earlier copy.
+        #
+        # @return [Boolean] true when an earlier copy existed and its shape differs
+        def shape_changed? = !previous_shape.nil? && previous_shape != shape
+      end
+
+      # @param name [String, Symbol] the package's directory name, such as `"payments"`
+      # @param from [String] path of the local source repository
+      # @param ref [String, nil] `X.Y.Z`, a release tag name, any commit-ish, or nil for the
+      #   newest release
+      # @param root [String] the consuming project's root
+      # @param allow_downgrade [Boolean] whether a release older than the vendored one is allowed
+      # @raise [Vendoring::Error] if the name is not a plain package name
+      def initialize(name, from:, root:, ref: nil, allow_downgrade: false)
+        @name = name.to_s
+        raise Vendoring::Error, "#{name.inspect} is not a package name" unless @name.match?(NAME)
+
+        @source = Vendoring::GitSource.new(from)
+        @ref = ref&.to_s
+        @root = root
+        @allow_downgrade = allow_downgrade
+      end
+
+      # Pins the package and reports what changed.
+      #
+      # @return [Result] the commit, version and shape now vendored
+      # @raise [Vendoring::Error] if the release or commit is not found, the tagged commit
+      #   disagrees with its own version, the files do not load, or a refusal above applies
+      def call
+        tag, version = release
+        previous_version, previous_shape = existing
+        shape = nil
+        pin = Vendoring.pin(from: @source.path, ref: tag || @ref, subtree: "#{@name}/bluebook",
+                            into: package_dir, glob: "*.bluebook") do |staged, commit|
+          shape = Shape.labels(staged)
+          next nil unless tag
+
+          refuse_unless_acceptable!(version, previous_version, previous_shape, shape)
+          { "bluebook.lock" => lock(version, tag, commit, staged, shape).to_s }
+        end
+        build_result(pin, tag, version, shape, previous_version, previous_shape)
+      end
+
+      private
+
+      def package_dir = File.join(@root, "vendor", "embryonaut_bluebooks", @name)
+
+      # Resolves what `ref` asks for into a release tag and its version.
+      #
+      # @return [Array(String, String), nil] tag and version for a release, nil for a bare commit
+      def release
+        tag = release_tag
+        return nil unless tag
+
+        version = tag.delete_prefix("#{@name}-v")
+        tagged = @source.read(tag, "#{@name}/bluebook.yml")&.[](/^version: *(\S+)/, 1)
+        unless tagged == version
+          raise Vendoring::Error, "#{tag} points at a commit whose bluebook.yml says version #{tagged.inspect}"
+        end
+
+        [tag, version]
+      end
+
+      def release_tag
+        return newest_release_tag if @ref.nil?
+        return existing_tag("#{@name}-v#{@ref}") if @ref.match?(VERSION)
+
+        @ref.match?(/\A#{Regexp.escape(@name)}-v\d+\.\d+\.\d+\z/) ? existing_tag(@ref) : nil
+      end
+
+      def newest_release_tag
+        tags = release_tags
+        raise Vendoring::Error, "no #{@name}-v* release tag in #{@source.path}" if tags.empty?
+
+        "#{@name}-v#{tags.max_by { |version| Gem::Version.new(version) }}"
+      end
+
+      def existing_tag(tag)
+        return tag if release_tags.include?(tag.delete_prefix("#{@name}-v"))
+
+        raise Vendoring::Error, "no release #{tag} in #{@source.path} (releases: #{release_tags.sort_by do |v|
+          Gem::Version.new(v)
+        end.join(' ')})"
+      end
+
+      def release_tags
+        @source.tags("#{@name}-v*").map { |tag| tag.delete_prefix("#{@name}-v") }.grep(VERSION)
+      end
+
+      # The version and storage shape of what is vendored now, measured from
+      # its files as they stand rather than read back, so a copy vendored before
+      # locks existed still gets a real "before".
+      def existing
+        version = Lock.read(File.join(package_dir, "bluebook.lock"))&.version
+        dir = File.join(package_dir, "bluebook")
+        shape = File.directory?(dir) ? Shape.labels(dir) : nil
+        [version, shape]
+      rescue Vendoring::Error
+        [version, nil]
+      end
+
+      def refuse_unless_acceptable!(version, previous_version, previous_shape, shape)
+        return unless previous_version
+
+        refuse_downgrade!(version, previous_version)
+        return if previous_shape.nil? || previous_shape == shape
+        return if minor_or_more?(previous_version, version)
+
+        raise Vendoring::Error,
+              "#{@name} #{previous_version} -> #{version} changes the storage shape but is only a patch bump " \
+              "(before: #{previous_shape.join(' ')}; after: #{shape.join(' ')}). Raise the package's version " \
+              "by at least a minor in the source repository and release again. Nothing was changed."
+      end
+
+      def refuse_downgrade!(version, previous_version)
+        return if @allow_downgrade || Gem::Version.new(version) >= Gem::Version.new(previous_version)
+
+        raise Vendoring::Error, "#{@name} #{previous_version} is vendored; #{version} is older. " \
+                                "Pass allow_downgrade to do it anyway."
+      end
+
+      def minor_or_more?(old, new)
+        old_major, old_minor = old.split(".").map(&:to_i)
+        new_major, new_minor = new.split(".").map(&:to_i)
+        new_major > old_major || (new_major == old_major && new_minor > old_minor)
+      end
+
+      def lock(version, tag, commit, staged, shape)
+        Lock.new(package: @name, version: version, tag: tag, commit: commit,
+                 digest: Lock.digest_of(staged), shape: shape)
+      end
+
+      def build_result(pin, tag, version, shape, previous_version, previous_shape)
+        Result.new(package: @name, commit: pin.commit, version: version, tag: tag,
+                   digest: Lock.digest_of(pin.dir), shape: shape, dir: pin.dir,
+                   previous_version: previous_version, previous_shape: previous_shape)
+      end
+    end
+  end
+end