hecks 0.2.0 → 0.3.0

data/lib/hecks/adapters/driven/folder.rb

@@ -0,0 +1,199 @@
+require_relative "../../vocabulary"
+
+module Hecks
+  module Adapters
+    class Folder
+      DOMAIN_ORDER = Hecks::Vocabulary.fetch("LoadOrder")
+      PORTS        = "ports"
+      ADAPTERS     = "adapters"
+
+      def initialize(settings: {}, root: nil)
+        @settings = settings
+        @root     = root
+      end
+
+      def load_library
+        load_each(library(PORTS),    %w[*.port])
+        load_each(library(ADAPTERS), %w[*/*.adapter */*/*.adapter])
+      end
+
+      def load_project(root)
+        return unless root
+
+        load_each(File.join(root, PORTS),    %w[*.port */*.port])
+        load_each(File.join(root, ADAPTERS), %w[*.adapter */*.adapter */*/*.adapter])
+      end
+
+      # CHAPTERS FIRST, JUDGED ONCE, THEN EVERYTHING THAT READS THEM.
+      # A chapter may be split across files (the language's own grammar is
+      # nine), and judging file one before files two-through-nine exist
+      # refuses references that are perfectly well declared a file later —
+      # see MetaValidator.defer for the whole reasoning. DOMAIN_ORDER
+      # already places every `*.bluebook` ahead of hecksagons and worlds,
+      # so the window ends at the last chapter pattern rather than at a
+      # hand-written list this would otherwise have to keep in step.
+      # `environment:` — ONE MORE PAIR OF FILES, LOADED LAST, NOT A GLOB.
+      # RECOVERED, not new — see Runtime::Loader.boot's own comment for
+      # the provenance. A caller passing `Hecks.boot(path, environment:
+      # "production")` gets exactly `environments/production.hecksagon`
+      # and `environments/production.world` loaded, whichever exist (a
+      # missing one is a silent no-op — not every environment overrides
+      # both; see docs/implemented/guides/wiring.md's "Swapping wiring per
+      # environment" for the motivating case: swapping a driven adapter
+      # — e.g. a real payment gateway for a mock one, or a hosting
+      # layer's tenancy settings — without an `if`/`else` anywhere in
+      # the domain's own wiring). Never matched by `DOMAIN_ORDER`'s own
+      # globs (all non-recursive, none named `environments/*`), so this
+      # is the only thing that ever reaches them. Loaded as genuine
+      # `Hecks.hecksagon "SameDomain" do ... end` / `Hecks.world
+      # "SameDomain" do ... end` blocks — MERGED into the base file's
+      # own hecksagon/world (Registry#add_hecksagon / #add_world,
+      # concatenate/override rather than replace), so an overlay can
+      # rebind or add settings for anything the base file declared
+      # without needing to know what else the base file said.
+      def load_domain(directory, environment: nil)
+        boundary = DOMAIN_ORDER.rindex { |pattern| pattern.end_with?(".bluebook") }
+        if boundary
+          load_bluebooks(directory, DOMAIN_ORDER[0..boundary])
+          load_each(directory, DOMAIN_ORDER[(boundary + 1)..])
+        else
+          load_each(directory, DOMAIN_ORDER)
+        end
+
+        return unless environment
+
+        load_each(directory, [File.join("environments", "#{environment}.hecksagon")])
+        load_each(directory, [File.join("environments", "#{environment}.world")])
+      end
+
+      # EVERY BLUEBOOK IN A FOLDER IS ONE DECLARATION SET. Individual files
+      # remain organized in the domain expert's language; the folder is the
+      # unit callers load. Builders group declarations by the chapter name in
+      # each file, so a folder may hold more than one chapter without a catalog.
+      # Sorting makes source order deterministic while the deferred window keeps
+      # cross-file references from being judged against a partial chapter.
+      def load_bluebooks(directory, patterns = ["*.bluebook"])
+        Bluebook::MetaValidator.defer { load_each(directory, patterns) }
+        Bluebook::MetaValidator.judge_deferred!(Hecks.current_registry)
+      end
+
+      # THE EXPLICIT-FILE SIBLING OF `load_domain` — for a caller that names
+      # its own exact files rather than a directory to glob (`Loader.boot_files`,
+      # behind `Hecks.boot_files`). No `Dir.glob`, no copying: every path here
+      # is a real file on disk, wherever it actually lives, loaded in place —
+      # a `.behaviors` file's `loads` scopes a boot this way specifically so a
+      # per-test boot never has to fake isolation by staging bluebooks into a
+      # tmpdir (see Loader.boot_files's own header for why that pattern is a
+      # hazard, not a convenience).
+      #
+      # ORDERED BY CATEGORY, NOT BY THE CALLER'S OWN LIST ORDER — same four
+      # groups `Vocabulary.fetch("LoadOrder")` walks a directory in
+      # (bluebook chapters, translations, hecksagons, worlds), because a
+      # hecksagon can reference a bluebook's own constants and must not load
+      # first regardless of which order a caller happened to write `loads
+      # "x.hecksagon", "x.bluebook"` in. Bluebook chapters are judged as one
+      # deferred group exactly like `load_domain` does, for the identical
+      # forward-reference reason (MetaValidator.defer's own header).
+      def load_selected(files, environment: nil)
+        bluebooks, rest = files.partition { |f| f.end_with?(".bluebook") }
+
+        if bluebooks.any?
+          Bluebook::MetaValidator.defer { bluebooks.sort.each { |f| Kernel.load(f) } }
+          Bluebook::MetaValidator.judge_deferred!(Hecks.current_registry)
+        end
+
+        %w[.hecksagon .world].each do |ext|
+          rest.select { |f| f.end_with?(ext) }.sort.each { |f| Kernel.load(f) }
+        end
+
+        return unless environment
+
+        directory = File.dirname(files.first)
+        load_each(directory, [File.join("environments", "#{environment}.hecksagon")])
+        load_each(directory, [File.join("environments", "#{environment}.world")])
+      end
+
+      def load_each(directory, patterns)
+        return unless File.directory?(directory)
+
+        patterns.each do |pattern|
+          Dir[File.join(directory, pattern)].sort.each { |file| Kernel.load(file) }
+        end
+      end
+
+      def bluebook_directory(path)
+        expanded = File.expand_path(path)
+        nested   = File.join(expanded, "bluebook")
+
+        return nested   if File.directory?(nested)
+        return expanded if File.directory?(expanded)
+
+        raise Errno::ENOENT, "no such domain directory: #{path}"
+      end
+
+      # THE DOMAIN YOU ARE STANDING IN. Walks up from `from` — the way git
+      # finds `.git` — and answers the nearest directory a boot would accept,
+      # or nil if there is not one above you.
+      #
+      # MARKED BY A `.hecksagon`, NOT BY A `.bluebook`. Chapters are
+      # everywhere: era translations, the language's own self-hosted grammar,
+      # and `spec/fixtures`, which holds a dozen unrelated ones in a single
+      # directory. A `.hecksagon` is the file that says "this is a domain, and
+      # here is how its aggregates are stored", which is exactly the claim a
+      # caller is relying on when they omit the path.
+      #
+      # Both layouts, because `bluebook_directory` above accepts both: a
+      # domain directory holding a `bluebook/` subdirectory (every example in
+      # this corpus), or one holding the files directly.
+      # NORMALISED TO THE OUTER DIRECTORY. Standing in `examples/banking/bluebook`,
+      # the `.hecksagon` is right there, so a plain walk stops on the
+      # `bluebook/` directory itself. Both boot identically — `bluebook_directory`
+      # accepts either and `Loader.boot` takes `File.dirname` of what it gets,
+      # so the registry root comes out the same — but `examples/banking` is the
+      # directory a person names, and the one a `.world`'s `dir "data"` reads
+      # as relative to.
+      def domain_root(from = Dir.pwd)
+        found = nearest_domain(File.expand_path(from))
+        return nil unless found
+
+        parent = File.dirname(found)
+        File.basename(found) == "bluebook" && domain?(parent) ? parent : found
+      end
+
+      def nearest_domain(current)
+        loop do
+          return current if domain?(current)
+
+          parent = File.dirname(current)
+          return nil if parent == current
+
+          current = parent
+        end
+      end
+
+      def domain?(directory)
+        !Dir[File.join(directory, "*.hecksagon")].empty? ||
+          !Dir[File.join(directory, "bluebook", "*.hecksagon")].empty?
+      end
+
+      def shared_root(given, directory)
+        return File.expand_path(given) if given
+
+        current = directory
+        loop do
+          return current if File.directory?(File.join(current, PORTS)) ||
+                            File.directory?(File.join(current, ADAPTERS))
+
+          parent = File.dirname(current)
+          return nil if parent == current
+
+          current = parent
+        end
+      end
+
+      def library(folder)
+        File.expand_path("../../#{folder}", __dir__)
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/google_authentication.adapter

@@ -0,0 +1,3 @@
+Hecks.adapter "GoogleAuthentication" do
+  port "authentication"
+end

data/lib/hecks/adapters/driven/google_authentication.rb

@@ -0,0 +1,100 @@
+require "securerandom"
+
+require_relative "../../ports/authentication"
+
+module Hecks
+  module Adapters
+    # GOOGLE'S OWN OIDC HANDSHAKE — the `authentication` port's one real
+    # implementation today, moved here from being hand-rolled per-app
+    # (an embryonaut_console `google_auth.rb` used to do exactly this;
+    # any hecks-based app gets Google sign-in for free now, the
+    # same "one adapter, reusable everywhere" value every other adapter
+    # in this directory already has).
+    #
+    # `oauth2` does ONLY the authorization-code exchange (no Rack
+    # middleware, no Omniauth strategy indirection) ; `google-id-token`
+    # does ONLY ID-token verification (signature checked against
+    # Google's real, rotating JWKS — real, maintained code, never
+    # hand-rolled here). Neither library decides what a verified
+    # (issuer, subject) MEANS — that's `Ports::IdentityResolution`'s
+    # job, called by whoever consumes this port's `verify`.
+    #
+    # LAZY REQUIRES, same reasoning `Postgres.connect_for` already
+    # holds itself to for `pg`: a domain that never binds
+    # `authentication` to this adapter should never need these gems
+    # installed. This FILE loads in every boot (driven.rb's own
+    # unconditional require_relative list) ; the GEMS load only where
+    # a real handshake actually happens.
+    #
+    # `GOOGLE_CLIENT_ID`/`GOOGLE_CLIENT_SECRET`/`GOOGLE_REDIRECT_URI` —
+    # no defaults, on purpose: a login mechanism silently
+    # half-configured is worse than one that refuses to boot at all.
+    module GoogleAuthentication
+      ISSUER = "https://accounts.google.com"
+
+      module_function
+
+      def client
+        require "oauth2"
+        OAuth2::Client.new(
+          ENV.fetch("GOOGLE_CLIENT_ID"), ENV.fetch("GOOGLE_CLIENT_SECRET"),
+          site:          "https://oauth2.googleapis.com",
+          authorize_url: "https://accounts.google.com/o/oauth2/v2/auth",
+          token_url:     "/token"
+        )
+      end
+
+      # The URL to send a browser to, carrying a fresh CSRF `state` the
+      # caller is responsible for stashing (a session, typically) and
+      # checking again in `verify`.
+      def authorization_url
+        state = SecureRandom.hex(24)
+        url = client.auth_code.authorize_url(
+          redirect_uri: ENV.fetch("GOOGLE_REDIRECT_URI"),
+          scope:        "openid email profile",
+          state:        state
+        )
+        [url, state]
+      end
+
+      # Exchanges `code` for tokens, verifies the returned ID token's
+      # signature and claims against Google's own JWKS, and confirms
+      # `state` matches what `authorization_url` handed out — a
+      # mismatch (or any failure in the exchange/verification itself)
+      # is a Ports::Authentication::ValidationError, never a
+      # silently-empty result. Returns
+      # {issuer:, subject:, email:, email_verified:} on success — never
+      # the raw token, never anything a caller would need to re-verify
+      # itself. `email_verified` rides along because a caller granting
+      # access off this email needs to know Google actually checked it.
+      def verify(code:, state:, expected_state:)
+        # BOTH GEMS, BEFORE ANYTHING ELSE — not staggered further down
+        # this method: the rescue clause below names GoogleIDToken
+        # ::ValidationError, and Ruby resolves that constant reference
+        # at the moment an exception is being matched, not at parse
+        # time. An OAuth2::Error raised before a later `require
+        # "google-id-token"` line ran would make the rescue clause
+        # itself blow up on an undefined constant, masking the real
+        # error. Requiring both up front means whichever one raises
+        # first, the constant is already there to catch it.
+        require "oauth2"
+        require "google-id-token"
+
+        unless state && expected_state && state == expected_state
+          raise Ports::Authentication::ValidationError, "state mismatch"
+        end
+
+        token = client.auth_code.get_token(code, redirect_uri: ENV.fetch("GOOGLE_REDIRECT_URI"))
+        id_token = token.params["id_token"] or raise Ports::Authentication::ValidationError, "no id_token in the response"
+
+        payload = GoogleIDToken::Validator.new.check(id_token, ENV.fetch("GOOGLE_CLIENT_ID"))
+        {
+          issuer: payload.fetch("iss"), subject: payload.fetch("sub"),
+          email: payload["email"], email_verified: [true, "true"].include?(payload["email_verified"])
+        }
+      rescue OAuth2::Error, GoogleIDToken::ValidationError => e
+        raise Ports::Authentication::ValidationError, e.message
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/governance_authorization.adapter

@@ -0,0 +1,3 @@
+Hecks.adapter "GovernanceAuthorization" do
+  port "authorization"
+end

data/lib/hecks/adapters/driven/governance_authorization.rb

@@ -0,0 +1,62 @@
+module Hecks
+  module Adapters
+    # THE `authorization` PORT, FULFILLED BY GOVERNANCE — same registry,
+    # same boot, so "ask Governance" is a dispatch against records
+    # already sitting in the store this adapter is handed, not a bridge
+    # to a second runtime. `Runtime::Dispatcher.new(registry)` is cheap
+    # to build fresh per call (`Registry#capability_graph`'s own
+    # neighbor, `#repository`, does the same kind of on-demand build) —
+    # nothing here holds one across calls, so there is no boot-order
+    # dependency on WHEN Governance's bluebook loads relative to this
+    # adapter, only that it has by the time `holds_role?` is called.
+    #
+    # AN ACTIVE ASSIGNMENT, not merely a historical one : `RoleAssignment`
+    # answers with every assignment an actor has ever held
+    # (`AssignmentsForActor`'s own description — "currently or
+    # historically") and leaves `ends_at` for the caller to read, the
+    # same deferral `Governance::RoleTransition.Allowed` makes for the
+    # same reason. This is that caller.
+    module GovernanceAuthorization
+      module_function
+
+      def holds_role?(registry, actor_id:, role:)
+        rows = Runtime::Dispatcher.new(registry).query(
+          "Governance::RoleAssignment.AssignmentsForActor",
+          actor_id: { value: actor_id.to_s }
+        )
+
+        rows.any? { |row| row[:role_name][:value] == role.to_s && row[:ends_at].nil? }
+      end
+
+      # THE OTHER HALF — may role X act as role Y. `RoleTransition.Allowed`
+      # is identified by the exact pair, so at most one row ever comes
+      # back ; still read as `.any?` rather than trusting that structurally,
+      # the same defensiveness `holds_role?` already has to have anyway
+      # since `AssignmentsForActor` can return several.
+      def authorized_as?(registry, from_role:, to_role:)
+        rows = Runtime::Dispatcher.new(registry).query(
+          "Governance::RoleTransition.Allowed",
+          from_role: { value: from_role.to_s }, to_role: { value: to_role.to_s }
+        )
+
+        rows.any? { |row| row[:ends_at].nil? }
+      end
+
+      # THE ROLE ITSELF, not just a yes/no about one — the same
+      # `AssignmentsForActor` query `holds_role?` runs, just returning
+      # the live (non-revoked) row's `role_name` instead of comparing it
+      # against a caller-supplied guess. `nil` for no live assignment at
+      # all — the caller's own fallback (an aggregate's own role field,
+      # a default) is domain-specific and does not belong here.
+      def live_role_for(registry, actor_id:)
+        rows = Runtime::Dispatcher.new(registry).query(
+          "Governance::RoleAssignment.AssignmentsForActor",
+          actor_id: { value: actor_id.to_s }
+        )
+
+        live = rows.find { |row| row[:ends_at].nil? }
+        live && live[:role_name][:value]
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/heki/journal.rb

@@ -0,0 +1,51 @@
+require_relative "../../../ports/persistence/append_only"
+
+module Hecks
+  module Adapters
+    class Heki
+      # The append-only journal beside the snapshot: one JSON line per
+      # entry, fsynced on append, replayed over the snapshot on read.
+      module Journal
+        def entries
+          return [] unless File.exist?(@journal_path)
+
+          File.readlines(@journal_path, chomp: true).reject(&:empty?).map do |line|
+            value = JSON.parse(line)
+            state = value["state"]&.transform_keys(&:to_sym)
+            Ports::Persistence::Entry.new(operation: value.fetch("operation"), id: value.fetch("id"), state: state,
+                                          mirrors: value["mirrors"])
+          end
+        end
+
+        private
+
+        def replay_journal(records)
+          return records unless File.exist?(@journal_path)
+
+          File.foreach(@journal_path) do |line|
+            entry = JSON.parse(line)
+            id    = entry.fetch("id")
+
+            case entry.fetch("operation")
+            when "save"   then records[id] = entry.fetch("state")
+            when "delete" then records.delete(id)
+            else raise Malformed, "#{@journal_path}: unknown journal operation #{entry.fetch("operation").inspect}"
+            end
+          end
+          records
+        rescue JSON::ParserError => e
+          raise Malformed, "#{@journal_path}: json error: #{e.message}"
+        end
+
+        def append_entry(operation, id, state)
+          File.open(@journal_path, "ab") do |journal|
+            journal.write(JSON.generate(operation: operation, id: id.to_s, state: state, mirrors: @entry_mirrors))
+            journal.write("\n")
+            journal.flush
+            journal.fsync
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/heki/snapshot.rb

@@ -0,0 +1,38 @@
+require "zlib"
+
+module Hecks
+  module Adapters
+    class Heki
+      # The binary snapshot codec: magic-header framing around
+      # deflate-compressed, id-sorted JSON. Reading refuses loudly on a
+      # short file, a bad magic, or a body neither zlib nor JSON will own.
+      module Snapshot
+        private
+
+        def read_snapshot
+          return {} unless File.exist?(@path)
+
+          data = File.binread(@path)
+          raise Malformed, "#{@path}: too short" if data.bytesize < HEADER_BYTES
+          raise Malformed, "#{@path}: bad magic" unless data[0, 4] == MAGIC
+
+          JSON.parse(Zlib::Inflate.inflate(data[HEADER_BYTES..]))
+        rescue Zlib::DataError => e
+          raise Malformed, "#{@path}: zlib error: #{e.message}"
+        rescue JSON::ParserError => e
+          raise Malformed, "#{@path}: json error: #{e.message}"
+        end
+
+        def write(records)
+          sorted = records.sort_by { |id, _| id }.to_h
+          json   = JSON.generate(sorted)
+
+          File.binwrite(
+            @path,
+            MAGIC + [sorted.size].pack("N") + Zlib::Deflate.deflate(json, Zlib::BEST_COMPRESSION)
+          )
+        end
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/heki.adapter

@@ -0,0 +1,4 @@
+Hecks.adapter "Heki" do
+  port   "persistence"
+  field  :dir
+end

data/lib/hecks/adapters/driven/heki.rb

@@ -0,0 +1,148 @@
+require "json"
+require "fileutils"
+require_relative "heki/snapshot"
+require_relative "heki/journal"
+require_relative "heki/saga_store"
+require_relative "../../ports/persistence/append_only"
+require_relative "../../ports/query/in_memory"
+require_relative "in_memory_ordering"
+require_relative "../../runtime/instance"
+
+module Hecks
+  module Adapters
+    # The file-backed store: a compressed snapshot (heki/snapshot.rb)
+    # plus an append-only journal beside it (heki/journal.rb). What stays
+    # here is the repository surface — find/all/save/delete, and the
+    # entry append/project pair the persistence port drives.
+    class Heki
+      include Snapshot
+      include Journal
+
+      MAGIC = "HEKI"
+      HEADER_BYTES = 8
+
+      class Malformed < StandardError; end
+
+      attr_reader :aggregate, :path
+
+      def initialize(aggregate:, settings: {}, root: nil)
+        @aggregate = aggregate
+        @path      = resolve_path(settings, root)
+        @journal_path = "#{@path}.journal"
+        @events    = []
+        # THE OPTIONAL saga-persistence capability's own scoping (§2/§4)
+        # — falls back to the aggregate's own name for a directly-
+        # instantiated adapter (specs), same fallback shape Postgres's
+        # own @domain already uses.
+        @domain    = (settings[:domain] || settings["domain"] || aggregate.name).to_s
+
+        FileUtils.mkdir_p(File.dirname(@path))
+      end
+
+      def find(id)
+        record = store[id.to_s]
+        return nil unless record
+
+        instance(id.to_s, record)
+      end
+
+      def all(order_by: nil, direction: :asc)
+        records = store.sort_by { |id, _| id }.map { |id, record| instance(id, record) }
+        InMemoryOrdering.ordered(records, aggregate: @aggregate, order_by: order_by, direction: direction)
+      end
+
+      def count = store.size
+
+      # `registry: context[:registry]` — Memory's own `query` already
+      # threads this through; Heki's own never did, which made
+      # `none_in_state?` (Ports::Query::InMemory) unconditionally
+      # return `true` (its own graceful "no registry, no way to look
+      # the target up" default) for EVERY `none_in_state` where-clause
+      # against a Heki-backed aggregate — silently excluding nothing,
+      # always, no matter the actual target state.
+      def query(specification, args = {}, context: {})
+        Ports::Query::InMemory.execute(all, specification, args, registry: context[:registry])
+      end
+
+      def append(entry)
+        @entry_mirrors = entry.mirrors
+        append_entry(entry.operation, entry.id, entry.state)
+        entry
+      ensure
+        @entry_mirrors = nil
+      end
+
+      def project(entry)
+        current = store
+        entry.save? ? current[entry.id] = entry.state.dup : current.delete(entry.id)
+        write(current)
+        @store = current
+        entry
+      end
+
+      def save(instance)
+        entry = Ports::Persistence::Entry.new(operation: "save", id: instance.id.to_s, state: instance.state.dup)
+        append(entry)
+        project(entry)
+        instance
+      end
+
+      def delete(id)
+        return false unless find(id)
+
+        entry = Ports::Persistence::Entry.new(operation: "delete", id: id.to_s, state: nil)
+        append(entry)
+        project(entry)
+        true
+      end
+
+      def record_event(event) = @events << event
+
+      def events = @events
+
+      # ── the OPTIONAL saga-persistence capability (§2) — Heki's own
+      # shape (a sibling snapshot+journal file pair, `SagaStore`,
+      # heki/saga_store.rb) rather than a table in a store this adapter
+      # doesn't have.
+      def save_saga(process_manager:, correlation:, state:, memory:)
+        saga_store.save_saga(@domain, process_manager.to_s, correlation.to_s, state.to_s, memory)
+      end
+
+      def delete_saga(process_manager:, correlation:)
+        saga_store.delete_saga(@domain, process_manager.to_s, correlation.to_s)
+      end
+
+      def each_saga(&block) = saga_store.each_saga(@domain, &block)
+
+      private
+
+      def saga_store
+        @saga_store ||= SagaStore.new(File.dirname(@path))
+      end
+
+      def instance(id, record)
+        Runtime::Instance.new(
+          aggregate: @aggregate,
+          id:        id,
+          state:     record.transform_keys(&:to_sym)
+        )
+      end
+
+      def store
+        @store ||= read
+      end
+
+      def read
+        snapshot = read_snapshot
+        replay_journal(snapshot)
+      end
+
+      def resolve_path(settings, root)
+        declared = settings[:dir] || settings["dir"] || "data"
+        dir      = declared.start_with?("/") ? declared : File.join(root || Dir.pwd, declared)
+
+        File.join(dir, "#{@aggregate.storage_name}.heki")
+      end
+    end
+  end
+end

data/lib/hecks/adapters/driven/identity_registry.adapter

@@ -0,0 +1,3 @@
+Hecks.adapter "IdentityRegistry" do
+  port "identity_resolution"
+end

data/lib/hecks/adapters/driven/identity_registry.rb

@@ -0,0 +1,26 @@
+module Hecks
+  module Adapters
+    # THE `identity_resolution` PORT, FULFILLED BY THE Identity FRAMEWORK
+    # BLUEBOOK — same registry, same boot, so this is a dispatch against
+    # records already sitting in the store this adapter is handed, not a
+    # bridge to a second runtime. Same reasoning `GovernanceAuthorization`
+    # gives for itself, one port over.
+    module IdentityRegistry
+      module_function
+
+      # `nil` for a pair nothing has linked, the first match otherwise —
+      # `ResolvedBy` is a lookup by the exact (issuer, subject) an
+      # authenticated token carries, not a listing, so more than one row
+      # would mean two links share a pair, which `Link`'s own natural
+      # key already prevents by construction.
+      def resolve(registry, issuer:, subject:)
+        rows = Runtime::Dispatcher.new(registry).query(
+          "Identity::ExternalIdentifier.ResolvedBy",
+          issuer: { value: issuer.to_s }, subject: { value: subject.to_s }
+        )
+
+        rows.first&.fetch(:identity)
+      end
+    end
+  end
+end