principles 0.0.1

data/lib/principles/models/member_lines.rb

@@ -0,0 +1,95 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Principles
+  # The domain logic, which loads and saves itself through data/. models/CLAUDE.md owns the boundary.
+  module Models
+    # A member's own lines at its baseline and now, as a one-member audit's request shows them, so the agent reads
+    # the change its quotes are checked against and not the rest of an edit to the file (#379). A long member, such
+    # as a whole file, shows only its changed region: the lines between its first and last difference, with a little
+    # context (#449). Past a limit even that is counted instead, so a request never carries a file twice (D38).
+    class MemberLines
+      # The most lines either side shows: a section or a passage fits, and so does the changed region of most edits
+      # to a whole file. A first guess, for an alpha test to confirm (#379).
+      SHOWN_AT_MOST = 80
+
+      # The unchanged lines shown on each side of a changed region, as git shows by default (#449).
+      CONTEXT_LINES = 3
+
+      # Each line is kept without its line ending, so a line the agent copies from the request is a whole line it
+      # can quote (#451).
+      #: (at_baseline: Array[String], now: Array[String]) -> void
+      def initialize(at_baseline:, now:)
+        @at_baseline = at_baseline.map(&:chomp) #: Array[String]
+        @now = now.map(&:chomp) #: Array[String]
+        freeze
+      end
+
+      # The member's lines at the baseline and now, each without its line ending.
+      #: Array[String]
+      attr_reader :at_baseline
+
+      #: Array[String]
+      attr_reader :now
+
+      # Whether its lines now read otherwise than at the baseline, as a prior finding's evidence item says (#858).
+      #: () -> bool
+      def changed? = @at_baseline != @now
+
+      # Both sides' lines while each fits; else their changed region, with where it starts within the member and
+      # each side's length; else how many lines each side has.
+      #: () -> Hash[String, untyped]
+      def shown
+        sides = { "at_baseline" => @at_baseline, "now" => @now }
+        return sides if fits?(sides.values)
+
+        counts = sides.transform_values(&:length)
+        region = changed_region
+        return { "omitted" => "too_long", "lines" => counts } unless fits?(region.values.map { |each| each["lines"] })
+
+        { "changed_region" => { "context_lines" => CONTEXT_LINES, **region }, "lines" => counts }
+      end
+
+      private
+
+      #: (Array[Array[String]]) -> bool
+      def fits?(sides)
+        sides.all? { |lines| lines.length <= SHOWN_AT_MOST }
+      end
+
+      # Each side's lines from CONTEXT_LINES before its first difference to CONTEXT_LINES after its last, with the
+      # 1-based line, within the member, the region starts at.
+      #: () -> Hash[String, Hash[String, untyped]]
+      def changed_region
+        same_start = common_length(@at_baseline, @now)
+        same_end = common_length(@at_baseline.drop(same_start).reverse, @now.drop(same_start).reverse)
+        from = [same_start - CONTEXT_LINES, 0].max
+        { "at_baseline" => @at_baseline, "now" => @now }.transform_values do |lines|
+          to = [lines.length - same_end + CONTEXT_LINES, lines.length].min
+          { "from_line" => from + 1, "lines" => lines[from...to] || [] }
+        end
+      end
+
+      # How many lines two sides share from their start.
+      #: (Array[String], Array[String]) -> Integer
+      def common_length(one, other)
+        one.zip(other).take_while { |line, other_line| line == other_line && !other_line.nil? }.length
+      end
+    end
+
+    # A member that cannot be placed in its file at the last full audit's commit, as after a move: the commit lacks
+    # the file, or the member's reference finds nothing there. An empty side would say it was empty (#457).
+    class MemberLinesNotFoundAtLastAudit
+      #: () -> void
+      def initialize
+        freeze
+      end
+
+      # That fact, in place of the lines.
+      #: () -> Hash[String, untyped]
+      def shown
+        { "omitted" => "not_found_at_last_audit" }
+      end
+    end
+  end
+end

data/lib/principles/models/member_loads.rb

@@ -0,0 +1,197 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "../data/project_files"
+require_relative "frontmatter_fields"
+require_relative "member_file"
+require_relative "text_size"
+require_relative "agent_loads"
+require_relative "hook_commands"
+require_relative "skill_loads"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # When a host loads a member's file into the agent's context, derived from the file's path as the host
+    # documents its loading, with the size of what loads (D38). Only Claude Code is derived. A derivation says
+    # what the documentation promises, not what loaded in any session. An audit record keeps these loads, and
+    # audit-record.schema.json names each field so show-audit prints it; member_loads_spec holds a sample of each
+    # branch to hold the two together, so add one there for a new branch.
+    class MemberLoads
+      # The instruction files Claude Code loads at session start in the folder it starts in, and once a file is
+      # read, written or edited in a folder below it, as its memory documentation says. This tool assumes a session
+      # started at the project root.
+      INSTRUCTIONS = %w[CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md].freeze
+
+      # The folder Claude Code reads rules from, recursively: a rule loads at start, or with a paths field only
+      # on matching files. This tool shows that field as written and never reads its globs.
+      RULES = ".claude/rules/"
+
+      # The fields that give the size of the whole file that loads.
+      FILE_SIZE_FIELDS = %w[file_bytes estimated_tokens].freeze #: [String, String]
+
+      # The fields that give the member's own share of that file, which moving the member out of it would save.
+      MEMBER_SIZE_FIELDS = %w[member_bytes member_tokens].freeze #: [String, String]
+
+      # The fields that give the size of a skill's or agent's description, which loads apart from its body.
+      DESCRIPTION_SIZE_FIELDS = %w[description_bytes description_tokens].freeze #: [String, String]
+
+      # A rule in a .claude/rules folder below the project root, whose loading this tool does not derive yet.
+      NESTED_RULE = {
+        "when" => "not_determined", "not_derived" => "a rules folder below the project root"
+      }.freeze #: Hash[String, String]
+
+      # The member's loads, from its whole file as files hold it and its own lines in it; a file that cannot be
+      # read gives no size, a member that cannot be found there no size of its own, and freshness reports why.
+      #: (Data::ProjectFiles, Locator, hooks: HookCommands) -> MemberLoads
+      def self.read(files, locator, hooks:)
+        text = files.read_text(locator.path)
+        member = begin
+          MemberFile.for(path: locator.path, text: text).lines_of(locator).join
+        rescue Error
+          nil
+        end
+        new(locator, text, hooks: hooks, member_text: member)
+      rescue Error
+        new(locator, nil, hooks: hooks)
+      end
+
+      # A whole file's loads, with no member's share in it, as LoadedFiles lists each file (#483).
+      #: (Data::ProjectFiles, String, hooks: HookCommands) -> MemberLoads
+      def self.of_file(files, path, hooks:)
+        new(Locator.new("path" => path), files.read_text(path), hooks: hooks)
+      rescue Error
+        new(Locator.new("path" => path), nil, hooks: hooks)
+      end
+
+      # locator is where the member is, as Member#locator gives it; text is its whole file, or nil when it
+      # cannot be read, so its size is left out; member_text is the member's own lines, or nil when it was not
+      # found, so its own size is left out.
+      #: (Locator, String?, hooks: HookCommands, ?member_text: String?) -> void
+      def initialize(locator, text, hooks:, member_text: nil)
+        @path = locator.path #: String
+        @query = locator.query #: String?
+        @text = text
+        @hooks = hooks
+        @member_text = member_text
+        freeze
+      end
+
+      #: () -> Hash[String, untyped]
+      def to_h
+        named = @hooks.naming(@path)
+        { "claude_code" => named.empty? ? claude_code : claude_code.merge("named_in_hooks" => named) }
+      end
+
+      # The moments Claude Code loads the member's file at, as to_h names them.
+      #: () -> Array[String]
+      def moments
+        [claude_code.fetch("when")]
+      end
+
+      # Whether Claude Code loads the file by itself at all, by the facility its path makes it.
+      #: () -> bool
+      def carried?
+        moments != ["no_known_carrier"]
+      end
+
+      # Whether the whole file loads at session start, so it counts towards what a session starts with.
+      #: () -> bool
+      def at_session_start?
+        moments == ["session_start"]
+      end
+
+      # When Claude Code loads the file, by its facility, with the size of what loads.
+      #: () -> Hash[String, untyped]
+      def claude_code
+        found = carrier
+        return { "when" => "no_known_carrier" } unless found
+
+        # A skill's description member costs its description at start, not the file, so it has only its own size.
+        return found.merge(member_size) if found["skill_part"]
+
+        found.merge(size, member_size)
+      end
+
+      # The member's own lines, its share of the file, with tokens estimated as size does; empty when the member
+      # was not found.
+      #: () -> Hash[String, Integer]
+      def member_size = TextSize.new(@member_text).under(MEMBER_SIZE_FIELDS)
+
+      # The whole file loads, so this is the file's size, with tokens estimated as characters / 4, rounded up; empty
+      # when the file cannot be read.
+      #: () -> Hash[String, Integer]
+      def size = TextSize.new(@text).under(FILE_SIZE_FIELDS)
+
+      # The size of the file's skill or agent description when it loads at session start, apart from the body, as the
+      # skill listing or the subagent list reads it; empty for any other file or moment.
+      #: () -> Hash[String, Integer]
+      def description_at_start
+        return {} unless claude_code.dig("description", "when") == "session_start"
+
+        TextSize.new(description_text).under(DESCRIPTION_SIZE_FIELDS)
+      end
+
+      private
+
+      # The description lines of the skill or agent the file is, as its facility reads them; nil for any other file.
+      #: () -> String?
+      def description_text
+        facility&.description_text
+      end
+
+      # The agent or skill the file is, by its path, which owns when its body and description load; nil for any other
+      # file.
+      #: () -> (AgentLoads | SkillLoads)?
+      def facility
+        return AgentLoads.new(@path, @text) if AgentLoads::AGENT_FILE.match?(@path)
+
+        SkillLoads.new(@path, @text, query: @query) if SkillLoads::SKILL_FILE.match?(@path)
+      end
+
+      # When Claude Code loads the file, by the facility its path makes it, or nil for a path it does not load
+      # by itself.
+      #: () -> Hash[String, untyped]?
+      def carrier
+        if @path.end_with?(".md")
+          facility_loads = facility&.to_h
+          return facility_loads if facility_loads
+          return rule if @path.start_with?(RULES)
+          return NESTED_RULE if nested_rule?
+        end
+
+        instruction_file
+      end
+
+      # Whether the file is in a .claude/rules folder below the project root, whose loading this tool does not derive.
+      #: () -> bool
+      def nested_rule?
+        @path.include?("/#{RULES}")
+      end
+
+      # A rule's loading moment, from whether its frontmatter has a paths field; not determined when its file
+      # cannot be read or its frontmatter is one this tool refuses to read as lines.
+      #: () -> Hash[String, untyped]
+      def rule
+        lines = @text&.lines or return { "when" => "not_determined" }
+        paths = FrontmatterFields.new(path: @path, lines: lines).field_lines("$.paths")
+        return { "when" => "session_start" } unless paths
+
+        { "when" => "on_files", "paths_field" => paths.map(&:chomp) }
+      rescue Error => e
+        { "when" => "not_determined", "frontmatter_refused" => e.payload.fetch("code") }
+      end
+
+      # An instruction file's loading moment: at start in the root folder, on files in one below it.
+      #: () -> Hash[String, untyped]?
+      def instruction_file
+        folder = INSTRUCTIONS.filter_map { |name| @path.delete_suffix(name) if @path.end_with?(name) }.min_by(&:length)
+        return unless folder
+        return { "when" => "session_start" } if folder.empty?
+
+        { "when" => "on_files", "files" => [folder] } if folder.end_with?("/")
+      end
+    end
+  end
+end

data/lib/principles/models/member_map.rb

@@ -0,0 +1,219 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "json"
+require_relative "../error"
+require_relative "../data/schema_check"
+require_relative "member"
+require_relative "map_members"
+require_relative "activation"
+require_relative "json_digest"
+require_relative "meta_principle"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # One principle's member map: the principle it names and the members that reinforce it, each a project
+    # file or a place in one, with the role it plays. Every change returns a new map and leaves this one as
+    # it was; MemberMaps saves it. Fields the map holds beyond these are kept as they are.
+    class MemberMap
+      #: String
+      attr_reader :id
+
+      #: (String, Hash[String, untyped]) -> void
+      def initialize(id, fields)
+        @id = id
+        # The map owns its data: every field, an unknown one too, is copied and frozen down to each string, so no
+        # change made in place to what it was built from or what it hands out changes its file or version (#648,
+        # #654). The copy goes through the JSON its version digests, which a map's file holds anyway.
+        owned = JSON.parse(JSON.generate(fields), freeze: true) #: Hash[String, untyped]
+        @members = MapMembers.new(id, owned.fetch("members").map { |each| Member.new(each) }) #: MapMembers
+        @fields = owned.merge("members" => @members.map(&:to_h).freeze).freeze #: Hash[String, untyped]
+        freeze
+      end
+
+      #: () -> untyped
+      def description
+        @fields["description"]
+      end
+
+      # Its members as Member values, which say each one's id, key, place and check.
+      #: MapMembers
+      attr_reader :members
+
+      # Each member in one of paths, by its id and path, as show-meta-principle-passage reports the members already in
+      # an entry file, which the agent judges against the passage (D68).
+      #: (Array[String]) -> Array[Hash[String, String]]
+      def members_in(paths)
+        @members.in_files(paths).map { |member| { "id" => member.id, "path" => member.path } }
+      end
+
+      # Whether this principle's audit keeps the release of principles it ran under, and its next full audit states
+      # what changed since: only the meta-principle's, which judges whether the keeping that release ships still
+      # works (D68).
+      #: () -> bool
+      def keeps_package? = meta_principle?
+
+      # Whether this principle's full audit states which other principles have members no audit has judged as they
+      # are now: only the meta-principle's, whose members are meant to bring those changes to an audit (D71).
+      #: () -> bool
+      def keeps_others_held? = meta_principle?
+
+      # Whether this is the meta-principle's map with no members, as a setup that wrote its map before the first
+      # member, or removing its last member, leaves it. Only this map's having none is out of the way: setup no longer
+      # writes it, and its first add-member creates it with that member (T74), while any other principle has none from
+      # create-principle until its first add-member (#931).
+      #: () -> bool
+      def unstarted? = meta_principle? && @members.empty?
+
+      # The map's version: the digest of what its JSON says, so any change to it gives a new version, and a hand
+      # edit or a formatter that only reorders its keys does not (#656).
+      #: () -> String
+      def version = JsonDigest.new(@fields).to_s
+
+      # Whether other would write the same file as this map, so saving it would change nothing.
+      #: (MemberMap) -> bool
+      def same_as?(other) = version == other.version
+
+      # Each member as this tool prints it: its id beside the fields shown gives it.
+      #: () -> Array[Hash[String, untyped]]
+      def members_shown
+        @members.zip(shown.fetch("members")).map { |member, fields| { "id" => member.id }.merge(fields) }
+      end
+
+      # The map as its file holds it.
+      #: () -> Hash[String, untyped]
+      def to_h
+        @fields
+      end
+
+      # The member with member_id, refused unless the map has it.
+      #: (String) -> Hash[String, untyped]
+      def member(member_id)
+        @members.found(member_id).to_h
+      end
+
+      #: (String) -> MemberMap
+      def describing(description)
+        MemberMap.new(id, @fields.merge("description" => description))
+      end
+
+      # When the agent said this principle's work is in hand, as the map stores it, or nil when it has not (D38).
+      #: () -> Hash[String, untyped]?
+      def activation = @fields["activation"]
+
+      #: (Activation) -> MemberMap
+      def activating(activation) = MemberMap.new(id, @fields.merge("activation" => activation.to_h))
+
+      # This map with member added, refused when the map already has a member with its id.
+      #: (Hash[String, untyped]) -> MemberMap
+      def adding(member)
+        added = Member.new(member)
+        new_id = added.id
+        if @members.taken?(new_id)
+          raise taken(new_id, repair("To change its role", "change-member-role", new_id, "--role ROLE"),
+                      repair("To point it elsewhere", "move-member", new_id, added.move_placeholders))
+        end
+
+        with_members(@members.to_a + [@members.keyed(added)])
+      end
+
+      # This map with member_id pointed at the place located names, in the same file. The new place replaces
+      # the old one whole, and every other field is kept: its role, and any a newer version wrote (D29). It is
+      # refused when another member is already there.
+      #: (String, Hash[String, untyped]) -> MemberMap
+      def moving(member_id, located)
+        old = @members.found(member_id)
+        moved = old.moved_to(located)
+        new_id = moved.id
+        if new_id != member_id && @members.taken?(new_id)
+          raise taken(new_id, repair("To remove one of them", "remove-member", member_id))
+        end
+
+        replacing(old, moved)
+      end
+
+      #: (String, String) -> MemberMap
+      def changing_role(member_id, role) = changing(member_id, "role" => role)
+
+      # Names the command that enforces a member, which an audit asks the agent to run (D30). This tool
+      # stores it and never runs it.
+      #: (String, String) -> MemberMap
+      def changing_check(member_id, check) = changing(member_id, "check" => check)
+
+      #: (String) -> MemberMap
+      def removing_check(member_id)
+        old = @members.found(member_id)
+        unless old.to_h.key?("check")
+          raise Error.new("no_check", "#{member_id} has no check in #{id}",
+                          "To see each member's check: #{Error::EXECUTABLE} show-principle #{id}")
+        end
+
+        replacing(old, old.without_check)
+      end
+
+      #: (String) -> MemberMap
+      def removing(member_id)
+        old = @members.found(member_id)
+        with_members(@members.reject { |each| each.equal?(old) })
+      end
+
+      # Member owns the format each member field needs; this name stays while member_map_spec checks it there.
+      FIELD_FORMATS = Member::FIELD_FORMATS #: Hash[String, Integer]
+
+      # The oldest format that holds every member of this map: 1 unless a member uses a later field.
+      #: () -> Integer
+      def format
+        @members.format
+      end
+
+      private
+
+      # Whether this is the map of the principle that keeps every other one held (D67).
+      #: () -> bool
+      def meta_principle? = @id == MetaPrinciple::ID
+
+      # The map with only the fields this tool knows, for printing: a field someone added to the file is kept
+      # in it but never shown as if this tool had said it.
+      #: () -> Hash[String, untyped]
+      def shown
+        Data::SchemaCheck.new("member-map").known(@fields)
+      end
+
+      # The refusal for a member id another member of this map has, ending with its repairs.
+      #: (String, *Error::RepairCommand) -> Error
+      def taken(new_id, *repairs)
+        Error.new("member_exists", "#{new_id} is already a member of #{id}", "").ending_with(repairs)
+      end
+
+      # A repair command acting on a member of this map, with the placeholders the agent fills; the controller prints
+      # it, quoting the member (D56, #729).
+      #: (String, String, String, ?String?) -> Error::RepairCommand
+      def repair(purpose, command, member, usage = nil)
+        Error::RepairCommand.new(purpose: purpose, command: command, values: [id, member], usage: usage)
+      end
+
+      # The map with member_id's entry holding fields in place of its own.
+      #: (String, Hash[String, untyped]) -> MemberMap
+      def changing(member_id, fields)
+        old = @members.found(member_id)
+        replacing(old, old.with(fields))
+      end
+
+      #: (Member, Member) -> MemberMap
+      def replacing(old, member)
+        with_members(@members.map { |each| each.equal?(old) ? member : each })
+      end
+
+      # Members are kept in id order, so a map's file changes only where a member does.
+      # Its format is worked out again, and written only above 1, so a map that uses no later field keeps
+      # the bytes an older version wrote, and its version.
+      #: (Array[Member]) -> MemberMap
+      def with_members(list)
+        changed = MemberMap.new(id, @fields.merge("members" => list.sort_by(&:id).map(&:to_h)))
+        fields = changed.to_h.except("format")
+        MemberMap.new(id, changed.format > 1 ? fields.merge("format" => changed.format) : fields)
+      end
+    end
+  end
+end

data/lib/principles/models/member_map_history.rb

@@ -0,0 +1,143 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "member"
+require_relative "member_history"
+require_relative "member_maps"
+require_relative "placement"
+require_relative "project_history"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # One map's members as the commits that changed it held them, walking back from HEAD on its first-parent
+    # line. Each member's run is the unbroken stretch of those commits whose map holds a member with its key,
+    # so its oldest commit is the one that mapped the member where it is (#243). The walk stops at a map it
+    # cannot read, so a run may start later than the true mapping; that can only hide an older change.
+    class MemberMapHistory
+      #: (id: String, history: ProjectHistory, member_maps: MemberMaps) -> void
+      def initialize(id:, history:, member_maps:)
+        @id = id
+        @history = history
+        @member_maps = member_maps
+        freeze
+      end
+
+      # Each key's run, newest first, as [commit, the member's fields at that commit]; a key HEAD's map does
+      # not hold has an empty run. Each commit's map is read once for every key.
+      #: (Array[String]) -> Hash[String, Array[[String, Hash[String, untyped]]]]
+      def runs(keys)
+        runs = keys.to_h { |key| [key, []] } #: Hash[String, Array[[String, Hash[String, untyped]]]]
+        open = keys.dup
+        @history.commits_touching(map_paths).each do |commit|
+          sha = commit.fetch("sha")
+          members = members_at(sha) or break
+          # A key the map at sha does not hold ends its run.
+          open.select! { |key| members.key?(key) && runs.fetch(key).push([sha, members.fetch(key)]) }
+          break if open.empty?
+        end
+        runs
+      end
+
+      # Each key's text at the oldest commit of its run that can locate the member, as {"commit", "sha256"};
+      # a key with no such commit is left out.
+      #: (Array[String]) -> Hash[String, Hash[String, String]]
+      def mapped_baselines(keys)
+        runs(keys).each_with_object({}) do |(key, run), found|
+          run.reverse_each do |sha, fields|
+            hash = @history.hashes_by_key_at(sha, [fields])[key] or next
+            found[key] = { "commit" => sha, "sha256" => hash }
+            break
+          end
+        end
+      end
+
+      # The commits that changed member's own text since baseline, walking the commits that touched this map or
+      # any file it has placed the member in, so a move to a renamed file keeps its earlier edits (#284).
+      #: (Member, baseline: String, now: String) -> Hash[String, untyped]
+      def member_history(member, baseline:, now:)
+        key = member.key
+        now_at = @member_maps.find(@id).member(member.id)
+        hashes = {} #: Hash[String, String?]
+        hash_at = ->(revision) { hashes.fetch(revision) { hashes[revision] = hash_at(key, now_at, revision) } }
+        commits = @history.commits_touching([*paths_of(member), *map_paths])
+        MemberHistory.new(baseline: baseline, now: now, commits: commits, hash_at: hash_at).to_h
+      end
+
+      # The map as commit holds it, such as the one an audit began from, refused as MemberMaps refuses its text;
+      # a commit before the folder took its name now holds it under the earlier name (#536), and a commit that lacks
+      # the map under both gives empty text, which is refused as unparseable.
+      #: (String) -> MemberMap
+      def map_at(commit)
+        text = map_paths.lazy.filter_map { |path| @history.text_at(commit, path) }.first
+        @member_maps.parsed(@id, text.to_s, commit: commit)
+      end
+
+      # The member's fields as the map at commit placed it, found by key; nil where that map did not hold it or cannot
+      # be read, so a one-member audit reads a moved member where it was at its baseline (#547).
+      #: (String, String) -> Hash[String, untyped]?
+      def placed_at(commit, key)
+        members_at(commit)&.fetch(key, nil)
+      end
+
+      # Where the member with key may be read at since and at each later commit that touched its map or a file the
+      # map has placed it in, oldest first: as each commit's map placed it, then as now_at, its entry now, places it.
+      # Lazy, so a search for the baseline reads no further than the commit that holds it (#550).
+      #: (String, String, Hash[String, untyped]) -> Enumerator::Lazy[Placement]
+      def placements_since(since, key, now_at)
+        paths = [*paths_of(Member.new(now_at)), *map_paths]
+        later = @history.commits_touching(paths, since: since).map { |commit| commit.fetch("sha") }.reverse
+        [since, *later].lazy.flat_map { |commit| placements_at(commit, key, now_at) }
+      end
+
+      # The paths a change to the member with key from commit to now_at, its entry now, spans: as commit's map placed
+      # it, or as now_at does where that map did not hold it, then its path now (#557).
+      #: (String, String, Hash[String, untyped]) -> Array[String]
+      def paths_from(commit, key, now_at)
+        placements_at(commit, key, now_at).fetch(0).paths_to(Member.new(now_at).path)
+      end
+
+      private
+
+      # The map's file now and under the folder's earlier name, so a walk of its history reaches back past the move.
+      #: () -> Array[String]
+      def map_paths = [@member_maps.file(@id), @member_maps.earlier_file(@id)]
+
+      # The member's placements at commit, as that commit's map placed it and as now_at does, once each.
+      #: (String, String, Hash[String, untyped]) -> Array[Placement]
+      def placements_at(commit, key, now_at)
+        fields_at = [members_at(commit)&.fetch(key, nil), now_at].compact
+        fields_at.uniq { |fields| Member.new(fields).reference }.map do |fields|
+          Placement.new(commit: commit, reference: Member.new(fields).reference,
+                        sha256: @history.hashes_by_key_at(commit, [fields]).values.first)
+        end
+      end
+
+      # Every path this map has given member, newest first, from its run back from HEAD.
+      #: (Member) -> Array[String]
+      def paths_of(member)
+        earlier = runs([member.key]).fetch(member.key).map { |_sha, fields| fields.fetch("path") }
+        [member.path, *earlier].uniq
+      end
+
+      # The hash of the member with key at revision, located as this map at revision places it. Where that map
+      # holds the member but its place cannot be found there, as at the commit that renamed its file before the
+      # map followed, it is located as now_at, its entry in the map now, places it. nil when the map at revision
+      # does not hold it.
+      #: (String, Hash[String, untyped], String) -> String?
+      def hash_at(key, now_at, revision)
+        fields = members_at(revision)&.fetch(key, nil) or return nil
+        @history.hashes_by_key_at(revision, [fields])[key] || @history.hashes_by_key_at(revision, [now_at])[key]
+      end
+
+      # Each member the map at commit holds, by key, or nil when that commit lacks the map or MemberMaps refuses it.
+      #: (String) -> Hash[String, Hash[String, untyped]]?
+      def members_at(commit)
+        map_at(commit).members.to_h { |member| [member.key, member.to_h] }
+      rescue Error
+        nil
+      end
+    end
+  end
+end