principles 0.0.1

data/lib/principles/models/decided_prior_findings.rb

@@ -0,0 +1,106 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "member_moves"
+require_relative "recorded_finding"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # What the next full audit decided about each prior finding (D35), once this tool has checked the decisions:
+    # the findings that still hold, as the record keeps them; the ones closed, with their reasons; and, for each
+    # new finding that raises a prior one again, when that one was first raised. The correction's basis carries
+    # these fields, so an audit with findings completes with the same decisions.
+    class DecidedPriorFindings
+      #: (Hash[String, untyped]) -> void
+      def initialize(fields)
+        @fields = fields.freeze #: Hash[String, untyped]
+        freeze
+      end
+
+      # Whether there was no prior finding to decide.
+      #: () -> bool
+      def none?
+        kept.empty? && closed.empty? && @fields.fetch("inherited").empty?
+      end
+
+      # Each finding that still holds, as the record keeps it.
+      #: () -> Array[Hash[String, untyped]]
+      def kept
+        @fields.fetch("kept")
+      end
+
+      #: () -> Array[String]
+      def kept_ids = kept_findings.map(&:id)
+
+      # Refuses a new finding that reuses the id of a prior finding that still holds, since the record would then hold
+      # two findings under one id.
+      #: (Array[String]) -> void
+      def distinct_from(new_ids)
+        return unless kept_ids.intersect?(new_ids)
+
+        raise Error.new("duplicate_finding", "A new finding reuses the id of a prior finding that still holds",
+                        "Give new findings ids other than the kept ones: #{kept_ids.join(", ")}.")
+      end
+
+      # Each finding resolved or withdrawn, with its decision and reason.
+      #: () -> Array[Hash[String, untyped]]
+      def closed
+        @fields.fetch("closed")
+      end
+
+      # The ids of the prior findings decided resolved; a withdrawn one was never a gap (#714).
+      #: () -> Array[String]
+      def resolved_ids = closed.select { |each| each["decision"] == "resolved" }.map { |each| each.fetch("finding_id") }
+
+      # Each kept finding whose pointer its decision dropped with null, with the pointer it had (#374). A
+      # correction basis printed before this was built carries none.
+      #: () -> Array[Hash[String, untyped]]
+      def dropped
+        @fields.fetch("dropped", [])
+      end
+
+      # Each kept finding whose waits_on its decision dropped, with null or by accepting it, with the line and since
+      # it had (D52). A correction basis printed before this was built carries none.
+      #: () -> Array[Hash[String, untyped]]
+      def waits_on_dropped
+        @fields.fetch("waits_on_dropped", [])
+      end
+
+      # Each kept evidence item a still_holds decision gave a new place, as it was and is now (D70). A correction
+      # basis printed before this was built carries none.
+      #: () -> Array[Hash[String, untyped]]
+      def evidence_replaced
+        @fields.fetch("evidence_replaced", [])
+      end
+
+      # When the prior finding that the new finding id raises again was first raised, or nothing.
+      #: (String) -> Hash[String, String]
+      def first_raised(id)
+        inherited = @fields.fetch("inherited")
+        inherited.key?(id) ? { "first_raised_at" => inherited.fetch(id) } : {}
+      end
+
+      # These decisions with each kept finding filed under its members' ids after moves (D28).
+      #: (MemberMoves) -> DecidedPriorFindings
+      def moved(moves)
+        DecidedPriorFindings.new(@fields.merge("kept" => moves.findings(kept)))
+      end
+
+      # The fields as the correction's basis carries them.
+      #: () -> Hash[String, untyped]
+      def to_h
+        @fields
+      end
+
+      NONE = new({ "kept" => [], "closed" => [], "inherited" => {} }) #: DecidedPriorFindings
+
+      private
+
+      # Each finding that still holds, read as the record keeps it.
+      #: () -> Array[RecordedFinding]
+      def kept_findings = kept.map { |finding| RecordedFinding.new(finding) }
+    end
+  end
+end

data/lib/principles/models/declared_map_changes.rb

@@ -0,0 +1,156 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "member_map"
+require_relative "member_moves"
+
+module Principles
+  # The domain: maps, audits and command steps, with every rule a schema cannot express.
+  # models/CLAUDE.md owns the boundary.
+  module Models
+    # The changes a correction declares it made to the map after the audit began: the members it moved (D28),
+    # and the members whose role or check a fix changed, which each fixed disposition lists in
+    # changed_map_entries (D40). This tool checks them against the map at the base commit, which may also hold
+    # members added since, needing no declaration, as a fix maps a member a finding said was missing (T69); whether a
+    # change fixes its finding is the agent's judgement.
+    class DeclaredMapChanges
+      # The changes an answer declares: its moved_members and each disposition's changed_map_entries.
+      #: (untyped) -> DeclaredMapChanges
+      def self.declared_in(response)
+        new(MemberMoves.new(response["moved_members"]), response["dispositions"])
+      end
+
+      #: (MemberMoves, untyped) -> void
+      def initialize(moves, dispositions)
+        @moves = moves
+        @entries = claimed(dispositions) #: Array[String]
+        freeze
+      end
+
+      #: () -> bool
+      def empty?
+        @moves.empty? && @entries.empty?
+      end
+
+      # The base commit, to read there the map the audit began from, or nil when nothing is declared and current is
+      # still at map_version, the version the audit began from. Outside git, a map that changed is refused, as are
+      # declared changes, since there is no base map to check them against.
+      #: (String?, MemberMap, map_version: String, map_file: String) -> String?
+      def base_to_read(base, current, map_version:, map_file:)
+        return check_in_git(base, principle_id: current.id) unless empty?
+        return if current.version == map_version
+        return base if base
+
+        raise stale_map(current.id, map_file)
+      end
+
+      # Refuses declared changes outside git, where there is no base map to check them against.
+      #: (String?, principle_id: String) -> String
+      def check_in_git(base, principle_id:)
+        return @moves.check_in_git(base, principle_id: principle_id) unless @moves.empty?
+        return base if base
+
+        raise Error.new("map_entries_need_git",
+                        "changed_map_entries needs git, to read the map #{principle_id} began from",
+                        "Outside git, defer the finding, commit nothing, and start a fresh audit: " \
+                        "#{Error::EXECUTABLE} start-audit #{principle_id}")
+      end
+
+      # Refuses unless base is the map the audit began from and current is base with exactly the declared
+      # members moved, the claimed members' role and check changed, and any members added (T69).
+      #: (MemberMap, MemberMap, map_version: String, map_file: String) -> void
+      def check(base, current, map_version:, map_file:)
+        raise unexplained(current.id, map_file) unless base.version == map_version
+
+        expected = @entries.reduce(@moves.applied(base, current)) { |map, id| claimed_entry(map, current, id) }
+        raise unexplained(current.id, map_file) unless with_added(expected, current).version == current.version
+      end
+
+      # Each claimed member's role and check, as was and now, where they differ between the base map with the
+      # declared moves applied, which check compares, and current. The block gives [base, current], and is
+      # called only when a fix claims an entry, so nothing else reads the base map (#462).
+      #: () { () -> [MemberMap, MemberMap] } -> Array[Hash[String, untyped]]
+      def entry_changes(&)
+        return [] if @entries.empty?
+
+        base, current = yield
+        moved = @moves.applied(base, current)
+        @entries.map { |id| changed_fields(id, moved.member(id), current.member(id)) }
+      end
+
+      # The map file, when a fix changed a member's role or check in it or the correction added members to it, so the
+      # agent commits it too (T69).
+      #: (String, ?added: Array[String]) -> Array[String]
+      def files_to_commit(map_file, added: [])
+        @entries.empty? && added.empty? ? [] : [map_file]
+      end
+
+      private
+
+      # expected with each member of current whose id it lacks added, as add-member adds it.
+      #: (MemberMap, MemberMap) -> MemberMap
+      def with_added(expected, current)
+        added = current.members.ids - expected.members.ids
+        added.reduce(expected) { |map, id| map.adding(current.member(id)) }
+      end
+
+      #: (untyped) -> Array[String]
+      def claimed(dispositions)
+        Array(dispositions).flat_map { |each| each.is_a?(Hash) ? Array(each["changed_map_entries"]) : [] }.uniq
+      end
+
+      # The map with the claimed member's role and check as current holds them, refused when they are as
+      # they were at the base commit.
+      #: (MemberMap, MemberMap, String) -> MemberMap
+      def claimed_entry(map, current, id)
+        unless current.members.taken?(id)
+          raise Error.new("unknown_member", "#{id} is not a member of #{current.id}",
+                          "Name in changed_map_entries an id that this command lists: " \
+                          "#{Error::EXECUTABLE} show-principle #{current.id}")
+        end
+        return replayed(map, id, current.member(id)) unless as_at_base?(map, current, id)
+
+        raise Error.new("claimed_change_missing", "#{id}'s role and check did not change during this audit",
+                        "The role and check of #{id} are as they were at the base commit; remove it from " \
+                        "changed_map_entries.")
+      end
+
+      # The map with the member's role and check changed to now's, as change-member-role, change-member-check
+      # and remove-member-check changed them.
+      #: (MemberMap, String, Hash[String, untyped]) -> MemberMap
+      def replayed(map, id, now)
+        roled = map.changing_role(id, now.fetch("role"))
+        return roled.changing_check(id, now.fetch("check")) if now.key?("check")
+
+        roled.member(id).key?("check") ? roled.removing_check(id) : roled
+      end
+
+      #: (String, Hash[String, untyped], Hash[String, untyped]) -> Hash[String, untyped]
+      def changed_fields(id, was, now)
+        changed = %w[role check].reject { |field| was[field] == now[field] }
+        { "member_id" => id, **changed.to_h { |field| [field, { "was" => was[field], "now" => now[field] }] } }
+      end
+
+      #: (MemberMap, MemberMap, String) -> bool
+      def as_at_base?(map, current, id)
+        map.member(id).slice("role", "check") == current.member(id).slice("role", "check")
+      end
+
+      #: (String, String) -> Error
+      def unexplained(principle_id, map_file)
+        @moves.empty? ? stale_map(principle_id, map_file) : @moves.undeclared(principle_id, map_file)
+      end
+
+      #: (String, String) -> Error
+      def stale_map(principle_id, map_file)
+        Error.new("stale_map", "The map of #{principle_id} changed during this audit",
+                  "If you moved a member to fix a finding, declare it in the answer's moved_members as " \
+                  "{\"from\": OLD_ID, \"to\": NEW_ID}; if a fix changed a member's role or check, list the " \
+                  "member's id in that fixed disposition's changed_map_entries. In git, a member you added with " \
+                  "add-member needs no declaration, as long as nothing else changed.\n" \
+                  "Otherwise, start a fresh audit: #{Error::EXECUTABLE} start-audit #{principle_id}", map_file)
+      end
+    end
+  end
+end

data/lib/principles/models/disposition.rb

@@ -0,0 +1,233 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "answer_fields"
+require_relative "answer_place"
+require_relative "answer_text"
+require_relative "waits_on"
+require_relative "write_up_pointer"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # One disposition of a correction answer: the action the agent chose for one finding, why, its evidence and
+    # where it is written up, and the members a fix claims it changed. The agent's AnswerFields check each field
+    # and locate each piece of evidence in the project. Its readers read what the agent gave, so callers ask them
+    # only once CorrectionAnswer has checked every disposition, and found none of its fields unfinished, its action
+    # among them (#753, #791, #794).
+    class Disposition
+      ACTIONS = %w[fixed deferred accepted disagreed].freeze #: Array[String]
+
+      # A field the agent left unfinished: empty, the template's placeholder, the answer guide's sample (#789), or
+      # an action not one of the four. It says where it sits in the answer and what to write there, which one
+      # refusal lists beside every other (#791).
+      class UnfinishedField
+        #: String
+        attr_reader :repair
+
+        #: (AnswerPlace, String, problem: String, repair: String) -> void
+        def initialize(place, name, problem:, repair:)
+          @place = place
+          @name = name
+          @problem = problem
+          @repair = repair
+          freeze
+        end
+
+        # Whose field it is, such as "Finding F1 reason".
+        #: () -> String
+        def to_s = "#{@place.subject} #{@name}"
+
+        # Its entry in the refusal's fields, as a malformed answer's are (D29).
+        #: () -> Hash[String, String]
+        def field = { "pointer" => @place.pointer, "problem" => @problem }
+      end
+
+      # A text field the agent must write: the placeholder the correction template leaves in it, which an answer may
+      # not send back unchanged, and what to write instead; reassessment applies only to a fix (#725).
+      class TextField
+        #: String
+        attr_reader :placeholder
+
+        #: (placeholder: String, repair: String) -> void
+        def initialize(placeholder:, repair:)
+          @placeholder = placeholder
+          @repair = repair
+          freeze
+        end
+
+        # The field named name, at place, when value leaves it empty, as the placeholder (#788, #725) or as sample,
+        # the answer guide's illustration of this field for the disposition's action, if it gives one (#789).
+        #: (untyped, AnswerPlace, String, sample: String?) -> UnfinishedField?
+        def left_in(value, place, name, sample:)
+          problem = if !AnswerText.new(value).written? then "must be a nonempty string"
+                    elsif value == @placeholder then "is the template's placeholder, unchanged"
+                    elsif value == sample then SAMPLE_UNCHANGED
+                    end
+          UnfinishedField.new(place, name, problem:, repair: @repair) if problem
+        end
+      end
+
+      # The problem with a field the agent gave back as the answer guide's sample (#789).
+      SAMPLE_UNCHANGED = "is the answer guide's sample, unchanged" #: String
+
+      TEXT_FIELDS = {
+        "reason" => TextField.new(placeholder: "Why, and what remains",
+                                  repair: "Write why you chose this action and what remains."),
+        "reassessment" => TextField.new(placeholder: "When fixed, how the changed members now carry the principle",
+                                        repair: "Write how the changed members now carry the principle.")
+      }.freeze #: Hash[String, TextField]
+      # The placeholder in each field, which the template prints.
+      PLACEHOLDERS = TEXT_FIELDS.transform_values(&:placeholder).freeze #: Hash[String, String]
+
+      # at is the disposition's place in the answer, such as /dispositions/0, which a refusal about its pointers names.
+      # samples is the answer guide's disposition for each action, whose text illustrates each field (#789).
+      #: (untyped, AnswerFields, at: String, samples: Hash[String, untyped]) -> void
+      def initialize(disposition, fields, at:, samples:)
+        @disposition = disposition
+        @fields = fields
+        @samples = samples
+        @place = AnswerPlace.new(at, "Finding #{disposition["finding_id"]}") #: AnswerPlace
+        freeze
+      end
+
+      #: () -> untyped
+      def finding_id = @disposition["finding_id"]
+
+      # The disposition as the agent gave it.
+      #: () -> untyped
+      def to_h = @disposition
+
+      #: () -> String
+      def action = @disposition.fetch("action")
+
+      #: () -> bool
+      def fixed? = action == "fixed"
+
+      # The members a fix says it changed.
+      #: () -> Array[String]
+      def changed_members = @disposition.fetch("changed_members")
+
+      # The file where the finding is written up, if anywhere.
+      #: () -> String?
+      def recorded_path = recorded_at&.path
+
+      # What the audit record keeps of this disposition beside its finding: the action, where the finding is
+      # written up and what a deferral waits on, when given (D52).
+      #: () -> Hash[String, untyped]
+      def recorded_outcome
+        { "action" => action, "recorded_at" => recorded_at&.to_h, "waits_on" => @disposition["waits_on"] }.compact
+      end
+
+      # Where the finding is written up, if anywhere, as checked_fields located it.
+      #: () -> WriteUpPointer?
+      def recorded_at
+        fields = @disposition["recorded_at"]
+        WriteUpPointer.new(fields) if fields
+      end
+
+      # Each field this disposition leaves for the agent still: an action that is not one of the four, the reason
+      # left empty, as the template's placeholder or as the answer guide's sample, and so a fix's reassessment,
+      # which applies to no other action, and a waits_on left as the guide's sample (#788, #789, #791, #794).
+      #: () -> Array[UnfinishedField]
+      def unfinished = [*unchosen_action, *unwritten_text, *waits_on_left_as_sample]
+
+      # The members this disposition claims it changed, refusing it unless its other fields are sound: only a fix
+      # claims any, and each must be among the members that changed. CorrectionAnswer has checked its action and
+      # that it wrote each field.
+      #: (Array[String]) -> Array[untyped]
+      def claimed_members(changed)
+        action = @disposition["action"]
+        checked_fields
+        members = @fields.array(@disposition["changed_members"], "changed_members")
+        entries = @disposition.fetch("changed_map_entries", [])
+        action == "fixed" ? fixed_members(members, entries, changed) : unclaimed(members, entries)
+      end
+
+      private
+
+      # The template leaves each action null, since choosing it is the agent's call; a null or unknown one is
+      # left for the agent, with the four to choose from (#708).
+      #: () -> UnfinishedField?
+      def unchosen_action
+        action = @disposition["action"]
+        return if ACTIONS.include?(action)
+
+        problem = action.nil? ? "is not chosen" : "is #{action.inspect}, not one of the four"
+        UnfinishedField.new(@place.child("action"), "action",
+                            problem:, repair: "Set its action to one of fixed, deferred, accepted or disagreed.")
+      end
+
+      # The reason, and a fix's reassessment, when left empty, as the template's placeholder (#788, #725) or as the
+      # answer guide's sample for this action (#789).
+      #: () -> Array[UnfinishedField]
+      def unwritten_text
+        action = @disposition["action"]
+        required = action == "fixed" ? TEXT_FIELDS : TEXT_FIELDS.slice("reason")
+        required.filter_map do |name, field|
+          field.left_in(@disposition[name], @place.child(name), name, sample: @samples.dig(action, name))
+        end
+      end
+
+      # A deferral's waits_on left as the answer guide's sample, which illustrates the line without saying whom the
+      # finding waits on. It is one line, so WaitsOn would keep it (#789).
+      #: () -> UnfinishedField?
+      def waits_on_left_as_sample
+        sample = @samples.dig(@disposition["action"], "waits_on")
+        return unless sample && @disposition["waits_on"] == sample
+
+        UnfinishedField.new(@place.child("waits_on"), "waits_on", problem: SAMPLE_UNCHANGED, repair: WaitsOn::REPAIR)
+      end
+
+      # A fix's claimed members, each of which must have changed. A fix may claim no member's text when it
+      # claims a map entry instead, which DeclaredMapChanges has checked changed (D40).
+      #: (Array[untyped], Array[untyped], Array[String]) -> Array[untyped]
+      def fixed_members(members, entries, changed)
+        return members unless (members.empty? && entries.empty?) || (members - changed).any?
+
+        raise Error.new("claimed_change_missing",
+                        "Finding #{finding_id} claims changes its members do not show: #{members.join(", ")}",
+                        "Make the authorised change and reassess it, or record a deferral.")
+      end
+
+      # The disposition's evidence and recorded_at, which a deferral must give, if only as null, and the
+      # one line a deferral may give saying what it waits on (D52).
+      #: () -> void
+      def checked_fields
+        locate_pointers
+        unrecorded_deferral if @disposition["action"] == "deferred" && !@disposition.key?("recorded_at")
+        WaitsOn.new(@disposition["waits_on"], action: @disposition["action"])
+               .check(code: "invalid_disposition", subject: "Finding #{finding_id}")
+      end
+
+      # Each piece of evidence, and where the finding is written up, located in the project.
+      #: () -> void
+      def locate_pointers
+        @fields.evidence(@disposition["evidence"], @place.child("evidence"))
+        @fields.pointer(@disposition["recorded_at"], @place.child("recorded_at")) if @disposition["recorded_at"]
+      end
+
+      # A deferral must say where it is written up, or null, so an answer reused from before recorded_at existed
+      # cannot drop the pointer silently (#299).
+      #: () -> bot
+      def unrecorded_deferral
+        raise Error.new("invalid_disposition", "Deferred finding #{finding_id} has no recorded_at",
+                        "Set recorded_at to where the finding is written up, as {\"path\": ..., \"heading\": ...}, " \
+                        "or to null when it is written up nowhere.")
+      end
+
+      #: (Array[untyped], Array[untyped]) -> Array[untyped]
+      def unclaimed(members, entries)
+        unless entries.empty?
+          raise Error.new("invalid_disposition", "Only a fixed disposition may list changed_map_entries",
+                          "Mark it fixed with a reassessment, or omit changed_map_entries.")
+        end
+        return [] if members.empty?
+
+        raise Error.new("invalid_disposition", "Only a fixed disposition may claim changed members",
+                        "Mark it fixed with a reassessment, or omit changed_members.")
+      end
+    end
+  end
+end

data/lib/principles/models/entry_file.rb

@@ -0,0 +1,65 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "../data/project_files"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # One root entry file as the project holds it: the path, the file its links lead to, and its text, or the code
+    # this tool refused it with when it cannot be read. It says whether it links the other entry file: as a symbolic
+    # link to it, or by an import word, @AGENTS.md or @CLAUDE.md, which Claude Code documents as loading the file it
+    # names. That is a fact about the string; a plain mention of the other's name is not a link, and an unread text
+    # shows no import. It says, too, when git does not track it, since such a file may be the owner's alone (#896).
+    class EntryFile
+      # The entry file at path as the project holds it, or nil when there is none; tracked says whether git tracks
+      # it, and is true outside git, where nothing is checked.
+      #: (Data::ProjectFiles, String, tracked: bool) -> EntryFile?
+      def self.read(files, path, tracked:)
+        return nil unless files.file?(path)
+
+        leads_to = files.leads_to(path)
+        begin
+          new(path, leads_to: leads_to, text: files.read_text(path), tracked: tracked)
+        rescue Error => e
+          new(path, leads_to: leads_to, not_read: e.payload.fetch("code"), tracked: tracked)
+        end
+      end
+
+      #: (String, leads_to: String, ?text: String?, ?not_read: String?, ?tracked: bool) -> void
+      def initialize(path, leads_to:, text: nil, not_read: nil, tracked: true)
+        @path = path
+        @leads_to = leads_to
+        @text = text
+        @not_read = not_read
+        @tracked = tracked
+        freeze
+      end
+
+      # What setup reports of the file: that it exists, that git does not track it when it does not, why its text
+      # could not be read when it could not, and how it links other, when it does.
+      #: (String) -> Hash[String, untyped]
+      def facts(other)
+        untracked = @tracked ? {} : { "tracked" => false }
+        unread = @not_read ? { "not_read" => @not_read } : {}
+        { "path" => @path, "exists" => true, **untracked, **unread }.merge(link(other))
+      end
+
+      private
+
+      # How this file links other, or nothing when it does not.
+      #: (String) -> Hash[String, String]
+      def link(other)
+        return { "links_to" => other, "by" => "symbolic_link" } if @leads_to == other
+        return { "links_to" => other, "by" => "import" } if @text.to_s.match?(import_word(other))
+
+        {}
+      end
+
+      # An @ import of path, as one word of the text.
+      #: (String) -> Regexp
+      def import_word(path) = %r{(?:\A|\s)@(?:\./)?#{Regexp.escape(path)}(?=\s|\z)}
+    end
+  end
+end

data/lib/principles/models/entry_files.rb

@@ -0,0 +1,46 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../data/project_files"
+require_relative "entry_file"
+require_relative "project_history"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The project's root entry files, which a host loads in every session: CLAUDE.md for Claude Code and AGENTS.md for
+    # Codex, by each host's documentation. For each it says whether it exists, and, as each EntryFile says, whether it
+    # links the other, and whether git tracks it.
+    class EntryFiles
+      PATHS = %w[CLAUDE.md AGENTS.md].freeze #: Array[String]
+
+      # Each entry file as the project holds it, or nil for one that does not exist. history says which git does not
+      # track: a path whose own file, or a file its links lead to, git does not hold, so a fresh clone would not find
+      # its text there (#695, #896).
+      #: (Data::ProjectFiles, ProjectHistory) -> EntryFiles
+      def self.read(files, history)
+        new(PATHS.to_h { |path| [path, EntryFile.read(files, path, tracked: history.tracks?(path))] })
+      end
+
+      # held maps each entry file's path to the file, or nil when it does not exist.
+      #: (Hash[String, EntryFile?]) -> void
+      def initialize(held)
+        @held = held.freeze #: Hash[String, EntryFile?]
+        freeze
+      end
+
+      # Each entry file's facts, in PATHS order.
+      #: () -> Array[Hash[String, untyped]]
+      def to_a = PATHS.map { |path| facts(path) }
+
+      private
+
+      #: (String) -> Hash[String, untyped]
+      def facts(path)
+        file = @held[path] or return { "path" => path, "exists" => false }
+
+        file.facts((PATHS - [path]).first.to_s)
+      end
+    end
+  end
+end

data/lib/principles/models/evidence_item.rb

@@ -0,0 +1,48 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "locator"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # One item of the evidence a finding was raised with, as its record keeps it: a path, with a heading, passage or
+    # query inside it, or none to name the whole file (D64). It holds that place as the Locator its record's hash
+    # gives, which keeps the hash's keys and order, since the record's bytes depend on it.
+    class EvidenceItem
+      # Where in the project the item points, as MemberFile reads it.
+      #: Locator
+      attr_reader :locator
+
+      #: (Hash[String, untyped]) -> void
+      def initialize(fields)
+        @locator = Locator.new(fields) #: Locator
+        freeze
+      end
+
+      # The file it points into.
+      #: () -> String
+      def path = @locator.path
+
+      # Whether it names its whole file, with no heading, passage or query inside it.
+      #: () -> bool
+      def whole_file? = @locator.whole_file?
+
+      # The lines it names in the project's file at commit, or nil when that commit lacks the file or its place there.
+      #: (ProjectHistory, String) -> Array[String]?
+      def lines_at(history, commit) = history.lines_at(commit, @locator)
+
+      # The lines it names in the project's file now; refused when it no longer resolves.
+      #: (Project) -> Array[String]
+      def lines_now(project) = project.member_file(path).lines_of(@locator)
+
+      # The item as printed, with facts about it beside its fields.
+      #: (Hash[String, untyped]) -> Hash[String, untyped]
+      def with_facts(facts) = to_h.merge(facts)
+
+      # The item as its record holds it.
+      #: () -> Hash[String, untyped]
+      def to_h = @locator.to_h
+    end
+  end
+end