principles 0.0.1

data/lib/principles/models/member.rb

@@ -0,0 +1,171 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "locator"
+
+module Principles
+  # The domain logic, which loads and saves itself through data/. models/CLAUDE.md owns the boundary.
+  module Models
+    # One member of a principle as its map records it: a file, a Markdown section of it, or a passage
+    # starting at a quoted first line. Its id names all three, so an agent can read where the member is
+    # from the id alone.
+    class Member
+      # The Unicode names of the format characters and separators most often met in text, by code point.
+      # Ruby has no table of names, so a character missing here is given by its code point alone.
+      HIDDEN_CHARACTER_NAMES = {
+        0x00AD => "SOFT HYPHEN", 0x061C => "ARABIC LETTER MARK", 0x180E => "MONGOLIAN VOWEL SEPARATOR",
+        0x200B => "ZERO WIDTH SPACE", 0x200C => "ZERO WIDTH NON-JOINER", 0x200D => "ZERO WIDTH JOINER",
+        0x200E => "LEFT-TO-RIGHT MARK", 0x200F => "RIGHT-TO-LEFT MARK", 0x2028 => "LINE SEPARATOR",
+        0x2029 => "PARAGRAPH SEPARATOR", 0x202A => "LEFT-TO-RIGHT EMBEDDING", 0x202B => "RIGHT-TO-LEFT EMBEDDING",
+        0x202C => "POP DIRECTIONAL FORMATTING", 0x202D => "LEFT-TO-RIGHT OVERRIDE",
+        0x202E => "RIGHT-TO-LEFT OVERRIDE", 0x2060 => "WORD JOINER", 0x2066 => "LEFT-TO-RIGHT ISOLATE",
+        0x2067 => "RIGHT-TO-LEFT ISOLATE", 0x2068 => "FIRST STRONG ISOLATE", 0x2069 => "POP DIRECTIONAL ISOLATE",
+        0xFEFF => "ZERO WIDTH NO-BREAK SPACE"
+      }.freeze #: Hash[Integer, String]
+
+      # The map format each member field needs: a member using a field is unreadable, without loss, by a
+      # version older than its format. Every field the member-map schema names is listed; a spec checks it.
+      # A new member field that changes what an audit asks or records gets the next format, and
+      # Data::MapFiles::NEWEST_FORMAT moves with it.
+      FIELD_FORMATS = { "path" => 1, "section" => 1, "starting_at" => 1, "ending_at" => 1, "role" => 1,
+                        "key" => 1, "check" => 2, "query" => 2 }.freeze #: Hash[String, Integer]
+
+      # The fields that say where a member's text is; a move replaces them whole.
+      LOCATORS = %w[path section starting_at ending_at query].freeze #: [String, String, String, String, String]
+
+      # fields is copied and frozen, so no caller changes a member through the hash it was built from or handed;
+      # the copy is shallow, so its strings are the caller's. MemberMap builds its members from strings it has
+      # copied and frozen, so a member in a map shares nothing (#654).
+      #: (Hash[String, untyped]) -> void
+      def initialize(fields)
+        @fields = fields.dup.freeze #: Hash[String, untyped]
+        freeze
+      end
+
+      # The member's fields, as its map's file holds them.
+      #: () -> Hash[String, untyped]
+      def to_h = @fields
+
+      # path, path#section or path$query, or either of the first two followed by @ and the passage's first-line
+      # anchor.
+      #: () -> String
+      def id
+        id = @fields["section"] ? "#{@fields.fetch("path")}##{@fields["section"]}" : @fields.fetch("path")
+        id = "#{id}#{@fields["query"]}" if @fields["query"]
+        @fields["starting_at"] ? "#{id}@#{@fields["starting_at"]}" : id
+      end
+
+      # What the member is known by across moves: its stored key, which move-member keeps from its id before
+      # its first move, or else its id. Audit records file each member's hash under it.
+      #: () -> String
+      def key
+        @fields["key"] || id
+      end
+
+      # The move-member options that place a member of this kind, with placeholders to fill: a section's heading,
+      # a passage's anchors or a query, or else the whole file's path. Run as printed, a placeholder fails, where a
+      # bare --path would silently widen a section or passage to its whole file.
+      #: () -> String
+      def move_placeholders
+        placed = { "section" => "--section HEADING", "starting_at" => "--starting-at TEXT",
+                   "ending_at" => "--ending-at TEXT", "query" => "--query QUERY" }
+                 .filter_map { |field, option| option if @fields[field] }
+        placed.empty? ? "--path PATH" : placed.join(" ")
+      end
+
+      # The oldest map format that holds this member: 1 unless it uses a later field.
+      #: () -> Integer
+      def map_format
+        @fields.keys.map { |field| FIELD_FORMATS.fetch(field, 1) }.max || 1
+      end
+
+      # The file the member is in.
+      #: () -> String
+      def path
+        @fields.fetch("path")
+      end
+
+      # Whether it is its whole file, which no locator but its path narrows, so it holds all the text of every
+      # line it spans (#756).
+      #: () -> bool
+      def whole_file?
+        (LOCATORS - ["path"]).none? { |locator| @fields.key?(locator) }
+      end
+
+      # What the member does for its principle, as the map states it.
+      #: () -> String?
+      def role
+        @fields["role"]
+      end
+
+      # The command that enforces the member, which an audit asks the agent to run (D30); nil when it has none.
+      #: () -> String?
+      def check
+        @fields["check"]
+      end
+
+      # Each invisible formatting or direction-changing character, or line separator, the member's check
+      # holds, in order, as its code point, its name when HIDDEN_CHARACTER_NAMES has it, and its position
+      # counted in characters from 1; none when it has no check. This tool prints such characters escaped, and
+      # naming them helps a reviewer who scans the command quickly (#258, #260).
+      #: () -> Array[String]
+      def check_hidden_characters
+        check.to_s.each_char.with_index(1).filter_map do |character, position|
+          next unless character.match?(/[\p{Cf}\p{Zl}\p{Zp}]/)
+
+          code = character.ord
+          [format("U+%04X", code), HIDDEN_CHARACTER_NAMES[code], "at character #{position}"].compact.join(" ")
+        end
+      end
+
+      # Where the member's text is, as MemberFile finds it.
+      #: () -> Hash[String, untyped]
+      def reference
+        { "path" => @fields.fetch("path"), "heading" => @fields["section"],
+          "starting_at" => @fields["starting_at"], "ending_at" => @fields["ending_at"],
+          "query" => @fields["query"] }.compact
+      end
+
+      # Where the member's text is, as the Locator MemberFile reads.
+      #: () -> Locator
+      def locator = Locator.new(reference)
+
+      # This member, still known by key once it has moved. The key is stored only while it differs from the
+      # member's id, so a member moved back to where it began has the bytes it had.
+      #: (String) -> Member
+      def keeping_key(key)
+        without = Member.new(@fields.except("key"))
+        without.id == key ? without : without.keyed_as(key)
+      end
+
+      # This member pointed at the place located names: the new place replaces the old one whole, every other
+      # field is kept, and the member is still known by its key.
+      #: (Hash[String, untyped]) -> Member
+      def moved_to(located)
+        Member.new(located.merge(@fields.except(*LOCATORS))).keeping_key(key)
+      end
+
+      # This member known by key, as a member added where another moved away from keeps its own audit.
+      #: (String) -> Member
+      def keyed_as(key) = with("key" => key)
+
+      # This member with fields in place of its own.
+      #: (Hash[String, untyped]) -> Member
+      def with(fields) = Member.new(@fields.merge(fields))
+
+      # This member with no check.
+      #: () -> Member
+      def without_check = Member.new(@fields.except("check"))
+
+      # Refuses a place an agent gave that quotes where a passage ends but not where it starts.
+      #: () -> void
+      def check_location
+        return unless @fields["ending_at"] && !@fields["starting_at"]
+
+        raise Error.new("ending_without_start", "--ending-at needs --starting-at",
+                        "Quote the passage's opening with --starting-at too.")
+      end
+    end
+  end
+end

data/lib/principles/models/member_assessments.rb

@@ -0,0 +1,144 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "locator"
+require_relative "answer_fields"
+require_relative "answer_place"
+require_relative "carried_assessments"
+require_relative "map_members"
+require_relative "member_sighting"
+require_relative "misspelt_member_id"
+require_relative "record_judged_against"
+require_relative "reported_check"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The member_assessments of an assessment answer: one for each mapped member, each with an assessment, a delivery,
+    # an observation when delivery is observed, evidence that resolves, and the result of the member's check when it
+    # has one (D30).
+    class MemberAssessments
+      # What a record entry keeps for a member carried forward, until completion puts back its last assessment.
+      CARRIED = { "carried_forward" => true }.freeze #: Hash[String, untyped]
+
+      # assessments is the answer's member_assessments; members are the mapped members, with each checked one's
+      # check; fields checks each field and locates each piece of evidence; judged_against is the principle's record
+      # as it stands, which says which members' last assessments may be carried forward, marked {"member_id",
+      # "carried_forward": true} (D49), and which command it ran for each member's check (D63); answered_at is when
+      # the answer came, which no sighting it reports is after (#699).
+      #: (untyped, MapMembers, fields: AnswerFields, answered_at: String, ?judged_against: RecordJudgedAgainst?)
+      #|   -> void
+      def initialize(assessments, members, fields:, answered_at:, judged_against: nil)
+        @assessments = assessments
+        @members = members
+        @answered_at = answered_at
+        @fields = fields
+        @judged_against = judged_against
+        @carried = judged_against&.carried #: CarriedAssessments?
+        freeze
+      end
+
+      # Refuses the assessments unless each mapped member is assessed exactly once, and each assessment is complete.
+      #: () -> void
+      def check
+        assessments = @fields.array(@assessments, "member_assessments")
+        refuse_incomplete_coverage(assessments.map { |assessment| assessment["member_id"] })
+        assessments.each_with_index { |assessment, index| member_assessment(assessment, place_of(assessment, index)) }
+      end
+
+      # The result reported for each checked member's check, by member id, once each has been checked. Call it after
+      # check, which refuses an unmapped id first: finding the command the record ran needs each member's key.
+      #: () -> Hash[String, Hash[String, untyped]]
+      def check_results
+        @assessments.each_with_index.to_h do |assessment, index|
+          [assessment["member_id"], reported(assessment, place_of(assessment, index))]
+        end.compact
+      end
+
+      # Each member's assessment by id, as its record entry keeps it: what the agent said, and the hash of each piece
+      # of evidence it cited, which the block locates, so the next audit can say whether that evidence changed (D49).
+      #: () { (Locator) -> Hash[String, untyped] } -> Hash[String, Hash[String, untyped]]
+      def kept(&locate)
+        @assessments.to_h do |assessment|
+          next [assessment.fetch("member_id"), { "assessment" => CARRIED }] if carried_forward?(assessment)
+
+          hashes = assessment.fetch("evidence").map { |reference| locate.call(Locator.new(reference)).fetch("sha256") }
+          [assessment.fetch("member_id"),
+           { "assessment" => assessment.slice("assessment", "delivery", "observation", "observed_at", "evidence")
+                                       .reject { |key, value| key == "observed_at" && value.nil? }
+                                       .merge("evidence_sha256" => hashes) }]
+        end
+      end
+
+      private
+
+      # Refuses answered, the ids the assessments name, unless they are the mapped ids, each once, hinting at any
+      # mapped id an unmapped one is spelled like.
+      #: (Array[untyped]) -> void
+      def refuse_incomplete_coverage(answered)
+        ids = @members.ids
+        return if answered.sort == ids.sort
+
+        raise Error.new("incomplete_coverage", "Assess each member exactly once: #{ids.join(", ")}",
+                        [*(answered - ids).grep(String).filter_map { |id| MisspeltMemberId.new(id).hint(ids) },
+                         "Complete the member_assessments array, copying each member id exactly."].join(" "))
+      end
+
+      # The place of the assessment at index in the answer, whose fields each refusal about it points into.
+      #: (untyped, Integer) -> AnswerPlace
+      def place_of(assessment, index)
+        AnswerPlace.new("/member_assessments/#{index}", "Member #{assessment["member_id"]}")
+      end
+
+      #: (untyped, AnswerPlace) -> void
+      def member_assessment(assessment, place)
+        return carried_assessment(assessment, place) if carried_forward?(assessment)
+
+        @fields.text(assessment["assessment"], "member_assessment.assessment")
+        sighting = MemberSighting.for(assessment, carried: @carried, answered_at: @answered_at, at: place)
+        @fields.evidence(assessment["evidence"], place.child("evidence"))
+        sighting.check
+        reported(assessment, place)
+      end
+
+      # Whether the assessment is a marker carrying forward the member's last one.
+      #: (untyped) -> bool
+      def carried_forward?(assessment) = assessment.key?("carried_forward")
+
+      # A marker is accepted only for a member the request listed as carried, alone but for its check's result.
+      #: (Hash[String, untyped], AnswerPlace) -> void
+      def carried_assessment(assessment, place)
+        reason = marker_refusal(assessment) or return reported(assessment, place)
+
+        raise Error.new("invalid_answer", "#{assessment["member_id"]} cannot be carried forward: #{reason}",
+                        "Assess it as the request's template does, or give only {\"member_id\", " \
+                        "\"carried_forward\": true} for a member the request lists with carried_forward.",
+                        fields: [{ "pointer" => place.child("carried_forward").pointer, "problem" => reason }])
+      end
+
+      # Why a marker cannot carry the member's assessment forward, or nil when it can: the request asks to judge the
+      # member, giving why, or the marker is not true or comes with an assessment.
+      #: (Hash[String, untyped]) -> String?
+      def marker_refusal(assessment)
+        return "carried_forward must be true" unless assessment["carried_forward"] == true
+
+        assessed = assessment.keys.intersect?(%w[assessment delivery evidence])
+        return "give the marker or an assessment, not both" if assessed
+
+        reason = @carried ? @carried.judge_because(assessment["member_id"]) : "not_assessed_before"
+        "the request asks to judge it: judge_because #{reason}" if reason
+      end
+
+      # The result reported for the member assessed at place, checked against its check.
+      #: (untyped, AnswerPlace) -> Hash[String, untyped]?
+      def reported(assessment, place)
+        id = assessment["member_id"]
+        key = @members.found(id).key
+        ReportedCheck.new(place, @members.check(id), ran: @judged_against&.check_run_for(key),
+                                                     kept: @judged_against&.check_review_for(key) || {})
+                     .result(assessment["check_result"])
+      end
+    end
+  end
+end

data/lib/principles/models/member_elsewhere.rb

@@ -0,0 +1,74 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "line_span"
+require_relative "member"
+
+module Principles
+  # The domain logic, which loads and saves itself through data/. models/CLAUDE.md owns the boundary.
+  module Models
+    # A member of another principle's map whose text shares a line with one located member: its principle, id,
+    # role there and lines, and how its lines stand to the located member's: the same lines, all of them, within
+    # them, or none of these, for a partial overlap (#383, #442, #610, #718). These are lines, not text, so what an
+    # edit reaches is left to the agent.
+    class MemberElsewhere
+      # member is the other map's member, whose id and role are printed; span is its lines now.
+      #: (principle_id: String, member: Member, span: LineSpan, located: LineSpan) -> void
+      def initialize(principle_id:, member:, span:, located:)
+        @principle_id = principle_id
+        @member = member
+        @span = span
+        @relation = relation_to(located) #: String?
+        @text_check_needed = text_check_needed_against?(located) #: bool
+        freeze
+      end
+
+      # Whether the agent should check the text where the lines meet before deciding which edit reaches which
+      # member: one holds the other's lines, and the one holding them is not a whole file (#756).
+      #: () -> bool
+      def text_check_needed? = @text_check_needed
+
+      # The principle whose map holds it.
+      #: String
+      attr_reader :principle_id
+
+      # The findings among left_open, its principle's open findings, that name it (#772).
+      #: (Array[OpenFinding]) -> Array[OpenFinding]
+      def open_among(left_open) = left_open.select { |finding| finding.on?(@member.key) }
+
+      # Its entry, naming by id the findings among left_open that name it, which the request lists once, so the same
+      # problem is not raised again in another principle's audit (#772, D62); as to_h when none do.
+      #: (Array[OpenFinding]) -> Hash[String, untyped]
+      def naming(left_open)
+        on_it = open_among(left_open)
+        on_it.empty? ? to_h : to_h.merge("open_finding_ids" => on_it.map(&:id))
+      end
+
+      # As add-member, show-principle and a full audit's request print it under mapped_elsewhere, its relation marked
+      # true when it has one.
+      #: () -> Hash[String, untyped]
+      def to_h
+        { "principle_id" => @principle_id, "member_id" => @member.id, "role" => @member.role,
+          "first_line" => @span.first_line, "last_line" => @span.last_line, **(@relation ? { @relation => true } : {}) }
+      end
+
+      private
+
+      #: (LineSpan) -> String?
+      def relation_to(located)
+        return "same_lines" if @span.same_lines_as?(located)
+        return "spans_these_lines" if @span.holds?(located)
+
+        "within_these_lines" if located.holds?(@span)
+      end
+
+      #: (LineSpan) -> bool
+      def text_check_needed_against?(located)
+        return !@span.holds_all_text_of?(located) if @relation == "spans_these_lines"
+        return !located.holds_all_text_of?(@span) if @relation == "within_these_lines"
+
+        false
+      end
+    end
+  end
+end

data/lib/principles/models/member_file.rb

@@ -0,0 +1,156 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "digest"
+require_relative "../error"
+require_relative "locator"
+require_relative "write_up_opening"
+
+module Principles
+  # The domain logic, which loads and saves itself through data/. models/CLAUDE.md owns the boundary.
+  module Models
+    # The text of one project file, as the type that knows how to find a member in it. It holds text, not a
+    # file, so the same rules apply to a file on disk and to the file at a commit. Each type finds the region
+    # a member names; passage anchors then narrow it the same way in every type.
+    class MemberFile
+      # The refusals, raised here and by the file types, that say a member's reference finds nothing in a file's
+      # text, rather than that the reference itself is wrong. Add a new one here when it raises one (#457).
+      PLACEMENT_REFUSALS = %w[section_not_found ambiguous_heading passage_not_found ambiguous_passage
+                              passage_end_not_found section_needs_markdown query_needs_frontmatter field_not_found
+                              unsupported_frontmatter duplicate_frontmatter_key].freeze
+      # The placement refusals of a quote the text does not hold, which a pointer that is not a member may also
+      # repair by pointing at other text (#742).
+      QUOTE_NOT_FOUND = %w[passage_not_found passage_end_not_found].freeze #: Array[String]
+      # The placement refusals that mean a member's place in its file is gone: its heading, passage anchor or
+      # frontmatter field no longer matches, so it is lost there, not changed and not unreadable.
+      PLACE_LOST = %w[section_not_found passage_not_found passage_end_not_found ambiguous_heading
+                      ambiguous_passage field_not_found].freeze #: Array[String]
+
+      # The file name endings read as Markdown, where a # line is a heading and not a comment.
+      MARKDOWN = /\.(md|markdown|mdx)\z/i #: Regexp
+
+      # The file type for path, chosen by its name.
+      #: (path: String, text: String) -> MemberFile
+      def self.for(path:, text:)
+        (path.match?(MARKDOWN) ? MarkdownFile : PlainTextFile).new(path: path, text: text)
+      end
+
+      #: String
+      attr_reader :path
+      #: String
+      attr_reader :text
+
+      #: (path: String, text: String) -> void
+      def initialize(path:, text:)
+        @path = path
+        @text = text
+        freeze
+      end
+
+      # Where the member locator names is in this text, and the hash of what it says there.
+      #: (Locator) -> Hash[String, untyped]
+      def locate(locator)
+        refuse_mixed_locators(locator)
+        lines = @text.lines
+        first, last = region(lines, locator)
+        selected = lines[first...last].to_a.join
+        start_text = locator.starting_at
+        first, last, selected = passage(lines, first, selected, start_text, locator.ending_at) if start_text
+        snapshot(locator, selected, first + 1, last)
+      end
+
+      # The lines of the region locator names, as the agent reads them (D33).
+      #: (Locator) -> Array[String]
+      def lines_of(locator)
+        located = locate(locator)
+        @text.lines[(located.fetch("first_line") - 1)...located.fetch("last_line")].to_a
+      end
+
+      # The opening of the region locator names, after the heading line itself when it names a heading, as
+      # WriteUpOpening finds it; nil when there is none. This tool does not judge what it says (#300).
+      #: (Locator) -> Hash[String, untyped]?
+      def write_up_opening(locator)
+        located = locate(locator)
+        heading_line = locator.heading && !locator.starting_at ? 1 : 0
+        WriteUpOpening.new(lines: @text.lines, first: located.fetch("first_line") - 1 + heading_line,
+                           last: located.fetch("last_line")).to_h
+      end
+
+      private
+
+      # What locate found: the member's place, the hash of its text and its span. query appears only for a
+      # member that has one, so every other member's snapshot, and each request id digesting it, is unchanged.
+      #: (Locator, String, Integer, Integer) -> Hash[String, untyped]
+      def snapshot(locator, selected, first_line, last_line)
+        { "path" => @path, "heading" => locator.heading, "starting_at" => locator.starting_at,
+          "sha256" => Digest::SHA256.hexdigest(selected), "characters" => selected.length,
+          "first_line" => first_line, "last_line" => last_line }.merge(locator.to_h.slice("query"))
+      end
+
+      # A query names a field whole, so it takes no section or passage beside it.
+      #: (Locator) -> void
+      def refuse_mixed_locators(locator)
+        return unless locator.query && (locator.heading || locator.starting_at)
+
+        raise Error.new("query_with_other_locators",
+                        "--query names a whole field, so it takes no --section or --starting-at",
+                        "Give --query alone, or --section and --starting-at without it.", @path)
+      end
+
+      # The line range a member names before any passage narrows it; each file type says.
+      #: (Array[String], Locator) -> [Integer, Integer]
+      def region(lines, locator)
+        raise NotImplementedError, "#{self.class} names no region"
+      end
+
+      # Narrows a member to a passage of its section, or of the whole text. starting_at must occur exactly
+      # once. With ending_at, the passage runs from the start of that match to the end of the first ending_at
+      # after it; without, to the end of the line it starts on. Anchors, never line numbers, so the passage
+      # stays found while text around and inside it changes. A lost anchor is refused, never widened to the
+      # whole file. Returns the passage's first and last lines, counted from the start of the text, and the
+      # passage.
+      #: (Array[String], Integer, String, String, String?) -> [Integer, Integer, String]
+      def passage(lines, first, selected, start_text, end_text)
+        start = only_opening(selected, start_text)
+        found = selected[start...passage_end(selected, start, start_text, end_text)].to_s
+        line = @text[0, lines[0...first].to_a.join.length + start].to_s.count("\n")
+        [line, line + line_count(found), found]
+      end
+
+      # How many lines a passage spans, counting a last line with no line break.
+      #: (String) -> Integer
+      def line_count(found)
+        found.count("\n") + (found.end_with?("\n") ? 0 : 1)
+      end
+
+      #: (String, String) -> Integer
+      def only_opening(text, start_text)
+        matches = text.scan(start_text).length
+        return text.index(start_text).to_i if matches == 1
+        if matches.zero?
+          raise Error.new("passage_not_found", "The passage starting #{start_text.inspect} is not in the file",
+                          "Quote the passage's opening text exactly.", @path)
+        end
+
+        raise Error.new("ambiguous_passage", "#{start_text.inspect} occurs #{matches} times",
+                        "Quote more of the passage's start so it occurs once.", @path)
+      end
+
+      #: (String, Integer, String, String?) -> Integer
+      def passage_end(text, start, start_text, end_text)
+        return (text.index("\n", start) || (text.length - 1)) + 1 unless end_text
+
+        found = text.index(end_text, start + start_text.length)
+        unless found
+          raise Error.new("passage_end_not_found", "No #{end_text.inspect} after #{start_text.inspect}",
+                          "Quote the passage's closing text exactly.", @path)
+        end
+
+        found + end_text.length
+      end
+    end
+  end
+end
+
+require_relative "markdown_file"
+require_relative "plain_text_file"

data/lib/principles/models/member_grounds.rb

@@ -0,0 +1,32 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "json_digest"
+require_relative "loading_facts"
+require_relative "map_members"
+require_relative "member_loads"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The facts beside each member's own text that its assessment was judged on: its map entry, which holds its path,
+    # locator, role and check, and when it loads, without the sizes an edit elsewhere in its file moves. A full audit
+    # keeps a digest of each with the assessment, and carries the assessment forward only while both match (D49).
+    class MemberGrounds
+      # members are the map's members; loads is each member's MemberLoads by id.
+      #: (MapMembers, Hash[String, MemberLoads]) -> void
+      def initialize(members, loads)
+        @members = members.by_id #: Hash[String, Member]
+        @loads = loads
+        freeze
+      end
+
+      # The digests of the member id's map entry and of its loading facts, as its kept assessment holds them.
+      #: (String) -> Hash[String, String]
+      def of(id)
+        { "entry_sha256" => JsonDigest.new(@members.fetch(id).to_h).to_s,
+          "loads_sha256" => JsonDigest.new(LoadingFacts.new(@loads.fetch(id).to_h).to_h).to_s }
+      end
+    end
+  end
+end

data/lib/principles/models/member_history.rb

@@ -0,0 +1,68 @@
+# 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
+    # The commits that changed one member's own text since this tool last knew it, newest first. The walk goes
+    # back from HEAD and stops at the first commit whose text for the member hashes to the baseline, so a fix
+    # an audit already took in is never listed. It also stops where the member cannot be found, or at the limit.
+    # It reports facts; whether a change is accounted for is the agent's judgement.
+    class MemberHistory
+      # The most commits listed for one member; the walk says when it stopped here.
+      LIMIT = 20
+
+      # commits are the commits that touched the member's file or its map, newest first; hash_at gives the
+      # member's hash at a revision, or nil where it cannot be found there.
+      #: (baseline: String, now: String, commits: Array[Hash[String, String]], hash_at: ^(String) -> String?) -> void
+      def initialize(baseline:, now:, commits:, hash_at:)
+        @baseline = baseline
+        @now = now
+        @commits = commits
+        @hash_at = hash_at
+        freeze
+      end
+
+      # The commits that changed the member's text, where and why the walk stopped, and whether the text on disk
+      # differs from HEAD.
+      #: () -> Hash[String, untyped]
+      def to_h
+        listed = [] #: Array[Hash[String, String]]
+        stopped = walk(listed)
+        { "commits" => listed, "stopped_at" => stopped, "uncommitted" => @hash_at.call("HEAD") != @now }
+      end
+
+      private
+
+      #: (Array[Hash[String, String]]) -> Hash[String, String]
+      def walk(listed)
+        @commits.each do |commit|
+          after = @hash_at.call(commit.fetch("sha"))
+          return stop("baseline_matched", commit) if after == @baseline
+          return { "reason" => "limit" } if listed.length == LIMIT
+
+          stopped = step(listed, commit, after)
+          return stopped if stopped
+        end
+        { "reason" => "history_start" }
+      end
+
+      # Lists commit when it changed the member's text, and says why the walk stops at it, if it does: a root
+      # commit has no parent, and a parent without the member ends what can be tied to it.
+      #: (Array[Hash[String, String]], Hash[String, String], String?) -> Hash[String, String]?
+      def step(listed, commit, after)
+        root = commit.fetch("root") == "true"
+        before = root ? nil : @hash_at.call("#{commit.fetch("sha")}^")
+        listed << commit.except("sha", "root") if before != after
+        return { "reason" => "history_start" } if root
+
+        stop("member_not_found", commit) unless before
+      end
+
+      #: (String, Hash[String, String]) -> Hash[String, String]
+      def stop(reason, commit)
+        { "reason" => reason, "commit" => commit.fetch("commit") }
+      end
+    end
+  end
+end