hecks 2.6.0 → 2.8.0

data/lib/hecks/runtime/registry/saga_persistence.rb

@@ -56,7 +56,13 @@ module Hecks
           end
         end
 
-        # Walks every loaded domain, repopulating `saga_instances` from
+        # Every domain whose sagas can persist somewhere: one with a hecksagon, or one a
+        # world's `default_adapter` binds though it has none.
+        #
+        # @return [Array<String>] the domain names, hecksagon domains first
+        def saga_domains = @hecksagons.keys | @bluebooks.keys.select { |domain| default_adapter_for(domain) }
+
+        # Walks every loaded domain in `saga_domains`, repopulating `saga_instances` from
         # whatever `saga_persistence(domain)` resolves to — a real store
         # for a domain whose adapter answers the capability, `each_saga`
         # yielding real rows; `NULL_SAGA_STORE`'s own `each_saga` for
@@ -79,7 +85,7 @@ module Hecks
         #
         # @return [Hecks::Runtime::Registry] self
         def rehydrate_sagas!
-          @hecksagons.each_key do |domain|
+          saga_domains.each do |domain|
             saga_persistence(domain).each_saga do |process_manager, correlation, state, memory, completed_compensations = []|
               pending = memory.delete(SAGA_PENDING_DISPATCH_KEY)
               @saga_instances[process_manager][correlation] =

data/lib/hecks/runtime/registry/verification.rb

@@ -17,10 +17,12 @@ module Hecks
         # @raise [Runtime::WiringError] if a bind names an undeclared aggregate, an
         #   adapter cannot satisfy its port's verb or declared `answers`, a world
         #   setting names a field its adapter does not declare, the default adapter
-        #   is unusable, a command declares a role with no authorization provider
-        #   attached, or a membership chapter is loaded with no identity chapter
+        #   is unusable, a world's `default_adapter` is not a persistence adapter, a
+        #   command declares a role with no authorization provider attached, or a
+        #   membership chapter is loaded with no identity chapter
         def verify!
           verify_default_adapter!
+          verify_world_defaults!
           verify_singleton_port_answers!
           refuse_cross_package_bluebook_merge!
           refuse_membership_without_identity!
@@ -270,7 +272,7 @@ module Hecks
         # types the consumer inlines. `uses_embryonaut_bluebook` only loads
         # the package's `.bluebook` files — persistence, Governance, and the
         # anti-corruption layer (`translates` field mapping) live on a named
-        # sibling hecksagon the CONSUMER must declare. Without that hexagon
+        # sibling hecksagon the consumer must declare. Without that hexagon
         # the package has no wiring of its own, and cross-context field
         # mapping has nowhere to be written. Breaking in 2.0: attaching a
         # vendored chapter without `Hecks.hecksagon "PackageName"` refuses
@@ -309,7 +311,7 @@ module Hecks
         # An explicit `bounded` mark on a consumer chapter always needs an
         # ACL — at least one `translates` block. Any field can be mapped;
         # the BC does not list which. `uses_framework` / `uses_embryonaut_bluebook`
-        # mark the ATTACHED chapter bounded (module wrap, no Object shortcut)
+        # mark the attached chapter bounded (module wrap, no Object shortcut)
         # and require the sibling hecksagon above; they do not require a
         # `translates` on that sibling unless the consumer also wrote `bounded`.
         # rust/host Google sign-in reads `ir.json`'s `membership` and
@@ -391,22 +393,22 @@ module Hecks
           bluebook_ir.aggregates.flat_map { |aggregate| aggregate.commands + aggregate.entities.flat_map(&:commands) }
         end
 
-        # TWO UNRELATED PACKAGES, ONE CHAPTER NAME BY COINCIDENCE — the
+        # Two unrelated packages, one chapter name by coincidence — the
         # real risk `Registry#bluebook_sources` exists to catch (found
         # live: a stale `vendor/hecksagain` fork's own copy of Governance/
         # Identity/Deploy, still reachable on 4 consuming apps' own load
         # paths alongside the real gem). `BluebookBuilder.build`'s own
-        # accumulation (several files declaring the SAME chapter name ON
-        # PURPOSE — `lib/hecks/language/bluebook/*.bluebook` all open
+        # accumulation (several files declaring the same chapter name on
+        # purpose — `lib/hecks/language/bluebook/*.bluebook` all open
         # `Hecks.bluebook "Bluebook"`) is never touched here — that merge
-        # stays unconditional, checked only AFTER every file has loaded,
+        # stays unconditional, checked only after every file has loaded,
         # the same "check the merged final result once" timing
         # `refuse_ungoverned_roles!` already uses and for the same reason
         # (a check against an incomplete load can never see the real
         # shape). What distinguishes intentional accumulation from
-        # coincidence is PACKAGE ROOT, not file identity: files a real
+        # coincidence is package root, not file identity: files a real
         # gemspec or a `vendor/` boundary already treats as one unit are
-        # expected to share a name; files from two DIFFERENT roots never
+        # expected to share a name; files from two different roots never
         # legitimately do.
         def refuse_cross_package_bluebook_merge!
           @bluebook_sources.each do |name, paths|
@@ -422,9 +424,9 @@ module Hecks
           end
         end
 
-        # THE NEAREST BOUNDARY A PATH ALREADY BELONGS TO — a real
-        # gemspec (this IS a package, whatever depends on it or vendors
-        # it), or a bare `vendor/` path component, treated as its OWN
+        # The nearest boundary a path already belongs to — a real
+        # gemspec (this is a package, whatever depends on it or vendors
+        # it), or a bare `vendor/` path component, treated as its own
         # root regardless of what gemspec might sit above it: vendored
         # code should never be considered "the same package" as whatever
         # it's vendored into, even when nothing else marks the boundary.

data/lib/hecks/runtime/registry/world_defaults.rb

@@ -0,0 +1,106 @@
+module Hecks
+  module Runtime
+    class Registry
+      # **World defaults** — the `default_database` and `default_adapter` words a
+      # `.world` can declare once for every chapter a boot loaded, resolved against
+      # the registry's own worlds. Included into Registry; the callers are the
+      # persistence binding policy (`default_adapter_for`), every reader of a bind's
+      # world settings (`binding_settings`), and `verify!` (`verify_world_defaults!`).
+      #
+      # **Resolution order**, most specific first — nothing here ever overrides a
+      # chapter's own explicit declaration:
+      #
+      #   1. the chapter's own `persisted_by(...) { database ... }` block, and the
+      #      hecksagon bind (aggregate-specific, then domain-level) that names its adapter;
+      #   2. the default declared by the chapter's own world;
+      #   3. the default declared by the project's world — the world of the first
+      #      chapter the boot loaded, the same convention `Loader#dispatcher_for` uses
+      #      to find the domain a boot targets;
+      #   4. today's behavior: no database setting, and the framework's in-memory
+      #      adapter for a chapter with no hecksagon.
+      #
+      # A default is resolved when a bind's settings or binding are asked for, never
+      # written into a chapter's world or hecksagon, so a chapter's own declarations
+      # stay exactly what its files say and a hecksagon-less chapter still trips the
+      # sibling-hecksagon gates the way it always did.
+      module WorldDefaults
+        # The settings a chapter's world gives one bind, with the project's default
+        # database filled in where the chapter left it out.
+        #
+        # The default database only ever reaches a persistence bind whose adapter
+        # declares a `database` field — a projection or an adapter without one is
+        # untouched. A `database` the chapter's own settings name wins; every other
+        # setting the chapter declared rides along unchanged.
+        #
+        # @param domain [String, Symbol] the domain whose world is asked
+        # @param verb [String, Symbol] the bind's port verb, such as `"persisted_by"`
+        # @param adapter [String, Symbol] the bind's adapter name
+        # @return [Hash{Symbol => Object}] the chapter's own settings for the bind, plus
+        #   `:database` from the default when one applies; `{}` when there is nothing
+        def binding_settings(domain, verb, adapter)
+          declared = world(domain)&.for_binding(verb, adapter) || {}
+          database = default_database_for(domain)
+          return declared unless database && default_database_applies?(verb, adapter)
+
+          { adapter: adapter.to_s, database: database }.merge(declared)
+        end
+
+        # The persistence adapter a chapter's aggregates fall back to when their
+        # hecksagon does not bind them.
+        #
+        # @param domain [String, Symbol] the domain to resolve the default for
+        # @return [String, nil] the chapter's own world's `default_adapter`, else the
+        #   project's; `nil` when neither declares one
+        def default_adapter_for(domain) = world_default(domain, :default_adapter)
+
+        # The database connection a chapter's database-taking persistence adapter uses
+        # when its own settings name none.
+        #
+        # @param domain [String, Symbol] the domain to resolve the default for
+        # @return [String, nil] the chapter's own world's `default_database`, else the
+        #   project's; `nil` when neither declares one
+        def default_database_for(domain) = world_default(domain, :default_database)
+
+        # Refuses a `default_adapter` that no persistence adapter answers to.
+        #
+        # @return [Runtime::Registry] self
+        # @raise [Runtime::WiringError] if a world's `default_adapter` names an unknown
+        #   adapter, one that is not a persistence adapter, or one with no Ruby
+        #   implementation
+        def verify_world_defaults!
+          @worlds.each_value do |declared|
+            name = declared.default_adapter
+            next unless name
+
+            verify_default_adapter_named!(declared.domain, name)
+          end
+          self
+        end
+
+        private
+
+        # The chapter's own world answers first; the project's world fills the gap.
+        def world_default(domain, field)
+          world(domain)&.public_send(field) || project_world&.public_send(field)
+        end
+
+        # The world of the first chapter this registry loaded — the target of a boot, ahead of
+        # any framework member it attaches.
+        def project_world = world(@bluebooks.keys.first || @worlds.keys.first)
+
+        def default_database_applies?(verb, adapter)
+          verb.to_s == Ports::Persistence::VERB && @adapters[adapter.to_s]&.declares?(:database)
+        end
+
+        def verify_default_adapter_named!(domain, name)
+          check_verb(Bluebook::Bind.new(aggregate: "(default)", verb: Ports::Persistence::VERB, adapter: name))
+          adapter_class(name)
+        rescue WiringError => e
+          raise WiringError,
+                "#{domain}'s world declares default_adapter #{name.inspect}, which is not a usable " \
+                "persistence adapter: #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/runtime/registry.rb

@@ -1,5 +1,6 @@
 require_relative "registry/verification"
 require_relative "registry/saga_persistence"
+require_relative "registry/world_defaults"
 require_relative "outbox"
 require_relative "../naming"
 
@@ -10,10 +11,12 @@ module Hecks
     # The collections a boot gathers — bluebooks, hexagons, ports, adapters,
     # worlds, the logs — and how a repository is resolved from them. The
     # wiring gate lives in registry/verification.rb, saga persistence
-    # resolution in registry/saga_persistence.rb.
+    # resolution in registry/saga_persistence.rb, and a `.world`'s project-wide
+    # defaults in registry/world_defaults.rb.
     class Registry
       include Verification
       include SagaPersistence
+      include WorldDefaults
 
       attr_reader :root, :bluebooks, :hecksagons, :ports, :adapters, :worlds, :event_log,
                   :reaction_log, :saga_log, :saga_instances, :translations, :saga_mutex,
@@ -36,7 +39,7 @@ module Hecks
         @event_log    = []
         @reaction_log = []
         @saga_log = []
-        # A DECLARATIVE FACT, NOT YET A DISPATCHED ONE — `AggregateDoor#
+        # A declarative fact, not yet a dispatched one — `AggregateDoor#
         # mark_sensitive` (called from a `.hecksagon` file, the same way
         # `port`/`persisted_by` already are) appends here at
         # hecksagon-build time; `Runtime::Loader.boot`'s own post-dispatcher
@@ -159,19 +162,23 @@ module Hecks
       # @return [Bluebook::Chapter] `item`, unchanged
       def add_bluebook(item) = @bluebooks[item.name] = item
 
-      # PROVENANCE, SIDE-CHANNEL — which real `.bluebook` file(s)
+      # Provenance, side-channel — which real `.bluebook` file(s)
       # contributed to a chapter name, never part of the exported IR (a
       # boot-time loading fact, not a domain fact) and never Rust-mirrored
       # (the same "additive, Ruby-only" shape `@translations` above already
-      # is). Legitimate accumulation (several files declaring the SAME
+      # is). Legitimate accumulation (several files declaring the same
       # chapter name on purpose — `lib/hecks/language/bluebook/*.bluebook`
       # all open `Hecks.bluebook "Bluebook"`) pushes more than one path
       # here too; that alone is not a problem. What this exists to let
       # `refuse_cross_package_bluebook_merge!` (registry/verification.rb)
-      # catch is TWO UNRELATED PACKAGES accumulating into the same name by
+      # catch is two unrelated packages accumulating into the same name by
       # coincidence — a stale vendored fork's own copy of a real gem's
       # chapter, still reachable on the load path, silently merging its
       # aggregates into the real one via this exact accumulation mechanism.
+      #
+      # @param name [String, Symbol] the chapter name the file contributed to
+      # @param path [String] the `.bluebook` file that declared it
+      # @return [Array<String>] every path recorded for that chapter, `path` last
       def record_bluebook_source(name, path)
         (@bluebook_sources[name.to_s] ||= []) << path
       end
@@ -257,7 +264,7 @@ module Hecks
       # entry into a real `Privacy::Marking.Mark` once a dispatcher exists.
       #
       # @param domain [String] the marked attribute's own aggregate FQN, e.g.
-      #   `"Lifeadelics::Registration"`
+      #   `"Site::Registration"`
       # @param attribute_path [String] the dotted path within that aggregate, e.g.
       #   `"attendee.medications"`
       # @param category [String] the marking's own sensitivity category, e.g. `"phi"`
@@ -593,7 +600,7 @@ module Hecks
       #   concatenated, `base` then `overlay`
       def merge_hecksagons(base, overlay)
         # Same-name blocks concatenate regardless of which file they came
-        # from (`lifeadelics.hecksagon`, `context_map.hecksagon`, an
+        # from (`site.hecksagon`, `context_map.hecksagon`, an
         # environment overlay). Order-independent: list facts uniq, so
         # loading context_map before or after the domain file is the same
         # merged hecksagon. Binds stay concatenated (BindingPolicy still
@@ -610,8 +617,8 @@ module Hecks
       end
 
       # Recovered and generalized — see `add_world`'s own comment. `realm`/
-      # `latest` are scalars, so the overlay's value wins when present,
-      # else the base's survives; `settings` is a shallow merge keyed by
+      # `latest`, `default_database` and `default_adapter` are scalars, so the overlay's
+      # value wins when present, else the base's survives; `settings` is a shallow merge keyed by
       # verb (and `"verb:adapter"`) — an overlay entry for a key the base
       # also declares replaces that key's whole resolved hash (the same
       # all-or-nothing shape `WorldBuilder#method_missing` already builds
@@ -623,10 +630,12 @@ module Hecks
       #   present, and `settings` shallow-merged, `overlay`'s keys winning
       def merge_worlds(base, overlay)
         Bluebook::World.new(
-          domain:   base.domain,
-          realm:    overlay.realm || base.realm,
-          latest:   overlay.latest || base.latest,
-          settings: base.settings.merge(overlay.settings)
+          domain:           base.domain,
+          realm:            overlay.realm || base.realm,
+          latest:           overlay.latest || base.latest,
+          settings:         base.settings.merge(overlay.settings),
+          default_database: overlay.default_database || base.default_database,
+          default_adapter:  overlay.default_adapter || base.default_adapter
         )
       end
     end

data/lib/hecks/runtime/saga_interpreter.rb

@@ -425,7 +425,7 @@ module Hecks
       #
       # A compensation that is itself refused does not unwind again, and needs no
       # flag to stop it: the state moves to the compensating leg's to_state before
-      # its dispatches run, so a second refusal finds the instance no longer in
+      # its dispatches run, so a second refusal finds the instance already out of
       # from_state and records that instead. The check is the guard.
       def unwind(process_manager, event, instance, correlation, domain)
         return unless instance && process_manager.handles?(REFUSED)

data/lib/hecks/runtime/tenant_check.rb

@@ -38,7 +38,7 @@ module Hecks
     # search_path` — proven for real, not assumed, by
     # tenant_isolation_spec.rb. Plain Postgres (no schema story) and D1
     # (no schema-equivalent at all — see world.bluebook's own comment on
-    # the lifeadelics D1 tradeoff) answer false, or don't answer at all,
+    # the D1 tradeoff) answer false, or don't answer at all,
     # which this module treats identically to false.
     module TenantCheck
       module_function

data/lib/hecks/runtime/value/coercion.rb

@@ -916,11 +916,11 @@ module Hecks
         # C3.8 — the boundary check for an attribute whose type is a bare
         # primitive rather than a value object: `Integer`/`Float` by exact
         # numeric class (`NUMERIC`), `String`/booleans by rejecting only a
-        # composite shape (`COMPOSITE_SHAPES`) — not the same as
+        # composite shape (`COMPOSITE_SHAPES`) — a looser test than
         # `check_scalar_shapes` holds a value object's own `String` field to
-        # any more (QualityControl BUG#125 tightened that one to also refuse
+        # (QualityControl BUG#125 has that one also refuse
         # a non-string scalar; a bare `String` argument here still admits
-        # any other scalar, left exactly as it was — a bare-primitive
+        # any other scalar — a bare-primitive
         # attribute was never part of BUG#125's own investigation or fix,
         # and whether it needs the same tightening, and against what real
         # Judge dependency if any, is still open); worded by the same

data/lib/hecks/runtime/value/entity_list_coercion.rb

@@ -27,7 +27,7 @@ module Hecks
         # because coercion has to resolve value objects, and only the
         # root answers `.value_object` at all (Entity's own header
         # comment: an entity must not answer to it, or `Value.
-        # for_attribute` could no longer tell a piece from a head). So
+        # for_attribute` could not tell a piece from a head). So
         # a nested entity — Dispatch, inside Handler — is not a direct
         # child of the root the way Handler itself is, and a plain
         # `aggregate.entities.find` stops one level short of it.

data/lib/hecks/storehouse.rb

@@ -1,6 +1,7 @@
 require "json"
 require "fileutils"
 require "time"
+require_relative "cache_dir"
 require_relative "facade/command_request"
 require_relative "facade/json_door"
 require_relative "naming"
@@ -8,7 +9,7 @@ require_relative "projector"
 require_relative "runtime/errors"
 
 module Hecks
-  # **The bus, not a door** — `docs/hecks-survey-what-we-wish-we-had.md` and
+  # **The bus, not a door** — `docs/archive/hecks-survey-what-we-wish-we-had.md` and
   # `docs/future-features.md` both name the sibling project's own
   # "Storehouse" the single highest-priority gap this repo had: "no
   # per-command tool... the bluebook is the contract, the [door] just
@@ -90,19 +91,24 @@ module Hecks
   module Storehouse
     module_function
 
-    # The same closed set `docs/hecks-survey-what-we-wish-we-had.md`'s
+    # The same closed set `docs/archive/hecks-survey-what-we-wish-we-had.md`'s
     # `SourceTag` names — who dispatched, not what. Optional: a caller
     # that omits it gets `source: nil` recorded, honestly, rather than a
     # guessed default.
     SOURCE_TAGS = %w[process-manager operator hook sidequest-agent cascade daemon].freeze
 
-    # **The bus's own audit trail** — a JSONL file per domain, one line per
-    # `dispatch`/`query`/`state`/dry-run call, `follow` tails it back.
-    # `tmp/`, not the domain's own directory: this is the bus's record
-    # of what was asked of it, not part of the domain's own persisted
-    # state, and `tmp/` is already gitignored for exactly this kind of
-    # local, disposable-but-useful-while-it-lasts file.
-    LOG_ROOT = File.expand_path("../../tmp/storehouse", __dir__)
+    # Names the directory holding the bus's own audit trail.
+    #
+    # The trail is a JSONL file per domain, one line per
+    # `dispatch`/`query`/`state`/dry-run call, and `follow` tails it back.
+    # It is kept under `Hecks::CacheDir`, not the domain's own directory: this is
+    # the bus's record of what was asked of it, not part of the domain's own
+    # persisted state, and not the gem's own directory either, which is
+    # read-only on an installed gem.
+    #
+    # @return [String] the absolute path of the `storehouse` directory under
+    #   the cache root
+    def log_root = Hecks::CacheDir.path("storehouse")
 
     # The root every `domain:`/`under:` must resolve under — the project
     # directory by default, `HECKS_STOREHOUSE_ROOT` to widen or move it.
@@ -321,9 +327,9 @@ module Hecks
     #
     # @param domain_name [String, Symbol, #to_s] the domain name
     # @return [String] the absolute path to that domain's JSONL log file, under
-    #   `LOG_ROOT`
+    #   `log_root`
     def log_path(domain_name)
-      File.join(LOG_ROOT, "#{domain_name.to_s.gsub(/[^A-Za-z0-9_-]/, '_')}.jsonl")
+      File.join(log_root, "#{domain_name.to_s.gsub(/[^A-Za-z0-9_-]/, '_')}.jsonl")
     end
 
     # Appends one call's outcome to its domain's audit log.
@@ -351,7 +357,7 @@ module Hecks
       entry = { time: Time.now.utc.iso8601, tool: tool, verb: verb, summary: summary, source: source,
                 role: role, actor_id: actor_id,
                 ok: outcome[:ok], id: outcome[:id], error: outcome[:error], events: outcome[:events] }.compact
-      FileUtils.mkdir_p(LOG_ROOT)
+      FileUtils.mkdir_p(log_root)
       File.open(log_path(domain_name), "a") { |f| f.puts(JSON.generate(entry)) }
     rescue StandardError
       nil

data/lib/hecks/vendoring/git_environment.rb

@@ -0,0 +1,35 @@
+module Hecks
+  module Vendoring
+    # The environment a `git` subprocess needs so it resolves its repository
+    # from the directory it is pointed at, not from whoever launched Ruby.
+    #
+    # Git exports `GIT_DIR`, `GIT_INDEX_FILE` and their kin to the hooks it
+    # runs (a push from a linked worktree runs `pre-push` this way). Every
+    # `git` that a hook's process tree starts inherits them, and they outrank
+    # both `git -C` and the working directory: a command aimed at a scratch
+    # repository would read, or commit into, the repository that was pushing.
+    module GitEnvironment
+      # The variables that pin git to one repository, work tree or index.
+      INHERITED = %w[
+        GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE GIT_PREFIX GIT_COMMON_DIR
+        GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES
+      ].freeze
+
+      # An environment hash for `Open3`, `IO.popen` and `system` that unsets
+      # every repository-pinning variable and leaves the rest alone.
+      #
+      # @return [Hash{String => nil}] each inherited variable mapped to nil
+      def self.clean
+        INHERITED.to_h { |name| [name, nil] }
+      end
+
+      # Removes the repository-pinning variables from this process's own
+      # environment, so every later `git` child starts clean.
+      #
+      # @return [void]
+      def self.scrub!
+        INHERITED.each { |name| ENV.delete(name) }
+      end
+    end
+  end
+end

data/lib/hecks/vendoring/git_source.rb

@@ -0,0 +1,102 @@
+require "open3"
+require "tmpdir"
+require_relative "git_environment"
+
+module Hecks
+  module Vendoring
+    # A local git repository read through the `git` executable, never through
+    # its working tree.
+    #
+    # Everything here names a commit and reads what that commit holds, so a
+    # shared checkout with uncommitted edits, or a different branch checked
+    # out, cannot leak into what gets vendored. Every command runs under
+    # {GitEnvironment.clean}, so a `GIT_DIR` inherited from a hook cannot
+    # redirect it to some other repository.
+    class GitSource
+      # @param path [String] a directory that is a git repository (or a
+      #   worktree of one)
+      # @raise [Vendoring::Error] if `path` is not a directory
+      def initialize(path)
+        @path = File.expand_path(path.to_s)
+        raise Error, "no source repository at #{@path}" unless File.directory?(@path)
+      end
+
+      # @return [String] the absolute path of the repository
+      attr_reader :path
+
+      # Resolves a commit-ish to the full commit id it names.
+      #
+      # @param ref [String] a branch, tag, abbreviated or full commit id
+      # @return [String] the 40-character commit id
+      # @raise [Vendoring::Error] if `ref` names no commit in the repository
+      def commit(ref)
+        out, _err, status = git("rev-parse", "--verify", "--quiet", "#{ref}^{commit}")
+        raise Error, "no commit #{ref.inspect} in #{@path}" unless status.success?
+
+        out.strip
+      end
+
+      # Lists tag names matching a shell pattern.
+      #
+      # @param pattern [String] a `git tag --list` pattern, such as `"payments-v*"`
+      # @return [Array<String>] the matching tag names, in git's own order
+      def tags(pattern)
+        out, _err, status = git("tag", "--list", pattern)
+        status.success? ? out.lines.map(&:chomp) : []
+      end
+
+      # Reads one file as a commit holds it.
+      #
+      # @param ref [String] the commit-ish to read from
+      # @param file [String] a repository-relative path
+      # @return [String, nil] the file's content, or nil when the commit has no such file
+      def read(ref, file)
+        out, _err, status = git("show", "#{ref}:#{file}")
+        status.success? ? out : nil
+      end
+
+      # Lists the files directly inside a directory of a commit.
+      #
+      # Subdirectories are left out on purpose: a vendored package carries the
+      # top-level files of its subtree and nothing nested beneath.
+      #
+      # @param ref [String] the commit-ish to read from
+      # @param subtree [String] a repository-relative directory, such as `"payments/bluebook"`
+      # @param glob [String] a `File.fnmatch` pattern the file's own name must match
+      # @return [Array<String>] repository-relative paths, sorted
+      def files(ref, subtree, glob = "*")
+        out, _err, status = git("ls-tree", "-r", "--name-only", ref, "--", subtree)
+        return [] unless status.success?
+
+        out.lines.map(&:chomp).select do |file|
+          File.dirname(file) == subtree && File.fnmatch(glob, File.basename(file))
+        end.sort
+      end
+
+      # Extracts named files of a commit into a directory with `git archive`,
+      # keeping their repository-relative paths.
+      #
+      # @param ref [String] the commit-ish to export
+      # @param files [Array<String>] repository-relative paths to export
+      # @param into [String] an existing directory to extract into
+      # @return [void]
+      # @raise [Vendoring::Error] if `git archive` or `tar` fails
+      def export(ref, files, into)
+        Dir.mktmpdir("hecks-archive") do |scratch|
+          tarball = File.join(scratch, "export.tar")
+          run!("git archive", "git", "-C", @path, "archive", "--format=tar", "--output=#{tarball}", ref, "--", *files)
+          run!("tar", "tar", "-xf", tarball, "-C", into)
+        end
+      end
+
+      private
+
+      def git(*) = Open3.capture3(GitEnvironment.clean, "git", "-C", @path, *)
+
+      def run!(label, *command)
+        _out, err, status = Open3.capture3(GitEnvironment.clean, *command)
+        raise Error, "#{label} failed: #{err.lines.first.to_s.strip}" unless status.success?
+      end
+    end
+  end
+end