principles 0.0.1

data/lib/principles/models/loading_facts.rb

@@ -0,0 +1,45 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "member_loads"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # What a member's loads say about when it loads and what, at any depth, without the file's or the member's size.
+    # A file's size moves with every edit elsewhere in a shared file, so a judgement weighed on a member's loading
+    # compares these facts, not the sizes (second alpha user on 5bedec4, #515).
+    class LoadingFacts
+      # loads is a member's loads as MemberLoads#to_h gives them, or as a record keeps them.
+      #: (Hash[String, untyped]) -> void
+      def initialize(loads)
+        @facts = without_sizes(loads) #: untyped
+        freeze
+      end
+
+      #: () -> untyped
+      def to_h = @facts
+
+      #: (untyped) -> bool
+      def ==(other) = other.is_a?(LoadingFacts) && other.to_h == @facts
+
+      alias eql? ==
+
+      #: () -> Integer
+      def hash = @facts.hash
+
+      private
+
+      #: (untyped) -> untyped
+      def without_sizes(value)
+        case value
+        when Hash
+          value.except(*MemberLoads::FILE_SIZE_FIELDS, *MemberLoads::MEMBER_SIZE_FIELDS)
+               .transform_values { |each| without_sizes(each) }
+        when Array then value.map { |each| without_sizes(each) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/principles/models/loads_to_check.rb

@@ -0,0 +1,93 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "member_loads"
+require_relative "loading_decision"
+require_relative "accepted_loading"
+require_relative "activation"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The members a full audit lists for the agent to weigh against the principle's activation, each with the
+    # facts that put it there (#355 slice 3, brief 2026-11-09-1322). It lists by fact and compares no globs, so
+    # whether a member loads outside the activation is the agent's judgement.
+    class LoadsToCheck
+      # activation is the map's, or nil when none is declared; loads is each member's MemberLoads by id; accepted
+      # is, by id, the decision the last completed audit accepted on a member's loading; hashes is each member's
+      # text hash now, by id.
+      #: (activation: Hash[String, untyped]?, loads: Hash[String, MemberLoads],
+      #|  ?accepted: Hash[String, AcceptedLoading], ?hashes: Hash[String, String]) -> void
+      def initialize(activation:, loads:, accepted: {}, hashes: {})
+        @activation = activation
+        @loads = loads
+        @accepted = accepted
+        @hashes = hashes
+        freeze
+      end
+
+      # The activation, each listed member with what put it there and its loads, and the members this tool knows no
+      # carrier for; nil when the activation lists nothing to check.
+      #: () -> Hash[String, untyped]?
+      def listed
+        activation = @activation
+        return unless activation && Activation.new(activation).full_audit_lists == "session_start_members"
+
+        { "activation" => activation, "rows" => rows,
+          "not_listed_no_known_carrier" => @loads.select { |_, loads| loads.moments == ["no_known_carrier"] }.keys }
+      end
+
+      # Each listed member's accepted decision, by id, as the record keeps it: its reason and the loads it accepted;
+      # refused unless each listed member is decided exactly once, each accepted with a one-line reason.
+      #: (untyped) -> Hash[String, Hash[String, untyped]]
+      def decided(decisions)
+        given = loading_decisions(decisions)
+        expected = listed_by_id
+        raise incomplete(expected.keys) unless given.map(&:member_id).sort == expected.keys.sort
+
+        given.each(&:check)
+        given.to_h { |decision| [decision.member_id, decision.kept(expected.fetch(decision.member_id))] }
+      end
+
+      private
+
+      # Each of the answer's loading decisions, none when it gives no list.
+      #: (untyped) -> Array[LoadingDecision]
+      def loading_decisions(decisions)
+        given = decisions.is_a?(Array) ? decisions : []
+        given.each_with_index.map { |decision, index| LoadingDecision.new(decision, index) }
+      end
+
+      # Each listed member's row, by its id; none when the activation lists nothing to check.
+      #: () -> Hash[String, Hash[String, untyped]]
+      def listed_by_id = (listed&.fetch("rows") || []).to_h { |row| [row.fetch("member_id"), row] }
+
+      #: (Array[String]) -> Error
+      def incomplete(expected)
+        Error.new("incomplete_loading_decisions",
+                  "Decide each member listed in loads_to_check_against_activation exactly once: " \
+                  "#{expected.empty? ? "none is listed" : expected.join(", ")}",
+                  "Give loading_decisions one {member_id, decision} for each listed member, and none for another.")
+      end
+
+      #: () -> Array[Hash[String, untyped]]
+      def rows
+        @loads.filter_map do |id, loads|
+          listed_for = loads.moments & ["session_start"]
+          next if listed_for.empty?
+
+          { "member_id" => id, "listed_for" => listed_for, "loads" => loads.to_h }.merge(last_accepted(id, loads.to_h))
+        end
+      end
+
+      # What the last audit accepted on the member's loading, and whether what it weighed changed since; nothing
+      # when no audit accepted it.
+      #: (String, Hash[String, untyped]) -> Hash[String, untyped]
+      def last_accepted(id, now)
+        accepted = @accepted[id] or return {}
+        { "last_accepted" => accepted.last_accepted(now, @hashes[id]) }
+      end
+    end
+  end
+end

data/lib/principles/models/locate_refusal.rb

@@ -0,0 +1,23 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "member_file"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # A refusal to locate a member, as its payload gives it, and what it makes of the member's state: lost in its
+    # file when its place there is gone, or else unavailable, as when its file cannot be read.
+    class LocateRefusal
+      #: (Hash[String, untyped]) -> void
+      def initialize(payload)
+        @payload = payload
+        freeze
+      end
+
+      # locator_lost when its code says the member's place in its file is gone, or else unavailable.
+      #: () -> String
+      def member_state = MemberFile::PLACE_LOST.include?(@payload["code"]) ? "locator_lost" : "unavailable"
+    end
+  end
+end

data/lib/principles/models/located_text.rb

@@ -0,0 +1,43 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "line_span"
+
+module Principles
+  # The domain logic, which loads and saves itself through data/. models/CLAUDE.md owns the boundary.
+  module Models
+    # The text a locator found now: its file, the lines it spans and the hash of what it says. A Locator says where
+    # to look; this is what was found there, as Project#locate finds it (#909).
+    class LocatedText
+      # The text found, from what Project#locate gives.
+      #: (Hash[String, untyped]) -> LocatedText
+      def self.of(found)
+        new(path: found.fetch("path"), first_line: found.fetch("first_line"), last_line: found.fetch("last_line"),
+            sha256: found.fetch("sha256"))
+      end
+
+      #: String
+      attr_reader :path, :sha256
+
+      #: Integer
+      attr_reader :first_line, :last_line
+
+      #: (path: String, first_line: Integer, last_line: Integer, sha256: String) -> void
+      def initialize(path:, first_line:, last_line:, sha256:)
+        @path = path
+        @first_line = first_line
+        @last_line = last_line
+        @sha256 = sha256
+        freeze
+      end
+
+      # The lines it spans, whole_file when it is its whole file.
+      #: (?whole_file: bool) -> LineSpan
+      def span(whole_file: false) = LineSpan.new(@first_line, @last_line, whole_file:)
+
+      # Its first and last lines, as a request prints them.
+      #: () -> Hash[String, Integer]
+      def lines = { "first_line" => @first_line, "last_line" => @last_line }
+    end
+  end
+end

data/lib/principles/models/locator.rb

@@ -0,0 +1,52 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # Where some text is in the project: a path, with a heading, a passage between starting_at and ending_at, or a
+    # frontmatter query inside it, or none of those to name the whole file. A member's reference, an evidence item
+    # and a write-up pointer each name text this way. It keeps the hash it was given, keys and order, since request
+    # ids and record bytes digest it.
+    class Locator
+      # What narrows a locator within its path, as references and the answer schemas name them; a locator naming
+      # none of them names its whole file. A member map calls the heading "section", which Member#reference
+      # translates.
+      KEYS = %w[heading starting_at ending_at query].freeze #: Array[String]
+
+      #: (Hash[String, untyped]) -> void
+      def initialize(fields)
+        @fields = fields.dup.freeze #: Hash[String, untyped]
+        freeze
+      end
+
+      # The file it points into.
+      #: () -> String
+      def path = @fields.fetch("path")
+
+      # The heading of the section it names, if it names one.
+      #: () -> String?
+      def heading = @fields["heading"]
+
+      # The opening text of the passage it names, if it names one.
+      #: () -> String?
+      def starting_at = @fields["starting_at"]
+
+      # The closing text of the passage it names, if it gives one.
+      #: () -> String?
+      def ending_at = @fields["ending_at"]
+
+      # The frontmatter field it names, as a JSONPath query, if it names one.
+      #: () -> String?
+      def query = @fields["query"]
+
+      # Whether it names its whole file, with no heading, passage or query inside it.
+      #: () -> bool
+      def whole_file? = KEYS.none? { |key| @fields.key?(key) }
+
+      # The locator as it was given.
+      #: () -> Hash[String, untyped]
+      def to_h = @fields
+    end
+  end
+end

data/lib/principles/models/map_members.rb

@@ -0,0 +1,171 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "member"
+require_relative "misspelt_member_id"
+
+module Principles
+  # The domain logic, which loads and saves itself through data/. models/CLAUDE.md owns the boundary.
+  module Models
+    # One principle map's members, as Members: finding one by its id, and the rules on ids and keys among them,
+    # which MemberMap asks as it changes the map. It is Enumerable over its members, in the map's order.
+    #: [out Elem = Member]
+    class MapMembers
+      include Enumerable
+
+      # The principle whose map these are.
+      #: String
+      attr_reader :principle_id
+
+      #: (String, Array[Member]) -> void
+      def initialize(principle_id, list)
+        @principle_id = principle_id
+        @list = list.freeze #: Array[Member]
+        freeze
+      end
+
+      # Each member, in the map's order, which every Enumerable method iterates.
+      # @override
+      #: () { (Member) -> void } -> void
+      def each(&) = @list.each(&)
+
+      # The members as the frozen list they are held in, without the copy Enumerable#to_a would make.
+      #: () -> Array[Member]
+      def to_a = @list
+
+      # Whether there are none, as in a map with no members yet.
+      #: () -> bool
+      def empty? = @list.empty?
+
+      # Each member's id, in the map's order.
+      #: () -> Array[String]
+      def ids = @list.map(&:id)
+
+      # Each member's key, in the map's order: its stored key, or its id when it has none.
+      #: () -> Array[String]
+      def keys = @list.map(&:key)
+
+      # Each member by its id.
+      #: () -> Hash[String, Member]
+      def by_id = @list.to_h { |member| [member.id, member] }
+
+      # Each file a member is in, once, in the map's order.
+      #: () -> Array[String]
+      def paths = @list.map(&:path).uniq
+
+      # Each member in one of paths, in the map's order.
+      #: (Array[String]) -> Array[Member]
+      def in_files(paths) = @list.select { |member| paths.include?(member.path) }
+
+      # The member with member_id now, or nil when none has it.
+      #: (untyped) -> Member?
+      def with_id(member_id) = @list.find { |member| member.id == member_id }
+
+      # The member known by key, its id before its first move or its id when it never moved, or nil when none is.
+      # The first is the only one, since a map whose members share a key is refused (repeated_keys).
+      #: (String) -> Member?
+      def with_key(key) = @list.find { |member| member.key == key }
+
+      # The check of the member with member_id, or nil when it has none or no member has that id (D30).
+      #: (untyped) -> String?
+      def check(member_id) = with_id(member_id)&.check
+
+      # Each key more than one member is known by, a member with no stored key being known by its id, with the ids of
+      # the members that share it. An audit record files each member under its key, so one would stand for the other.
+      #: () -> Hash[String, Array[String]]
+      def repeated_keys
+        @list.group_by(&:key).select { |_, sharing| sharing.length > 1 }.transform_values { it.map(&:id) }
+      end
+
+      # Refuses these members when two share an id or a key, as a hand edit or a merge can leave them. where names the
+      # map as read, and file the map file the refusal points at.
+      #: (where: String, file: String) -> void
+      def refuse_repeats(where:, file:)
+        refuse_repeated_ids(where, file)
+        refuse_repeated_keys(where, file)
+      end
+
+      # Each member's key by id, for the members whose key is not their id because they have moved.
+      #: () -> Hash[String, String]
+      def moved_keys = @list.to_h { |member| [member.id, member.key] }.reject { |id, key| id == key }
+
+      # The member with member_id, refused unless one has it.
+      #: (String) -> Member
+      def found(member_id)
+        with_id(member_id) || raise(unknown(member_id))
+      end
+
+      #: (String) -> bool
+      def taken?(member_id) = !with_id(member_id).nil?
+
+      # member, with a key of its own when its id is already the key of a member that moved away from there;
+      # otherwise the new member would inherit that member's audit.
+      #: (Member) -> Member
+      def keyed(member)
+        return member unless keys.include?(member.id)
+
+        free = (2..).lazy.map { |n| "#{member.id}~#{n}" }.find { |key| !keys.include?(key) }
+        member.keyed_as(free || raise(KeyError, "no free key for #{member.id}"))
+      end
+
+      # The refusal for an id no member has now, naming the member that had it before it moved, since a member keeps
+      # its id from before its first move as its key (#552). A member moved twice is not found by its middle id.
+      #: (String) -> Error
+      def unknown(member_id)
+        ids = "To see each member's id: #{Error::EXECUTABLE} show-principle #{@principle_id}"
+        moved = @list.select { |each| each.key == member_id }
+        return misspelt(member_id, ids) unless moved.one?
+
+        now = moved.fetch(0).id
+        Error.new("unknown_member", "#{member_id} is not a member of #{@principle_id}: it moved, and its id is now " \
+                                    "#{now}", "Give its id now, #{now}, in place of #{member_id}.\n#{ids}")
+      end
+
+      # The refusal for an id no member has or had, naming the one mapped id it is spelled like apart from case and
+      # punctuation, if any, under did_you_mean, so the controller can print the command again with it. The near miss
+      # itself is never accepted (D56, #729).
+      #: (String, String) -> Error
+      def misspelt(member_id, ids)
+        unknown = "#{member_id} is not a member of #{@principle_id}"
+        closest = MisspeltMemberId.new(member_id).closest(@list.map(&:id))
+        return Error.new("unknown_member", unknown, ids) unless closest
+
+        Error.new("unknown_member", "#{unknown}; did you mean #{closest}?", ids).including("did_you_mean" => closest)
+      end
+
+      # The oldest map format that holds every member: 1 unless a member uses a later field.
+      #: () -> Integer
+      def format = @list.map(&:map_format).max || 1
+
+      private
+
+      # The ids more than one member has, which a hand edit or a merge can leave.
+      #: () -> Array[String]
+      def repeated_ids = @list.map(&:id).tally.select { |_, count| count > 1 }.keys
+
+      # Every member is found and recorded by its id, so of two sharing one, one would silently stand for both.
+      #: (String, String) -> void
+      def refuse_repeated_ids(where, file)
+        shared = repeated_ids
+        return if shared.empty?
+
+        raise Error.new("duplicate_member", "#{where} has more than one member with id #{shared.join(", ")}",
+                        "Keep one of each: edit the map file so that no two members point at the same place, " \
+                        "then commit it.", file)
+      end
+
+      # Two members with ids of their own known by one key (#647): which keeps it decides which keeps the audit filed
+      # under it, so the repair leaves that to the agent.
+      #: (String, String) -> void
+      def refuse_repeated_keys(where, file)
+        key, ids = repeated_keys.first
+        return unless ids
+
+        raise Error.new("duplicate_member", "#{where} has more than one member known by key #{key}: #{ids.join(", ")}",
+                        "Keep one key per member: the member that keeps #{key} keeps the audit filed under it, so " \
+                        "give the other a key of its own, such as #{key}~2, then commit the map.", file)
+      end
+    end
+  end
+end

data/lib/principles/models/markdown_file.rb

@@ -0,0 +1,92 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "member_file"
+require_relative "frontmatter_fields"
+
+module Principles
+  # The domain logic, which loads and saves itself through data/. models/CLAUDE.md owns the boundary.
+  module Models
+    # A Markdown file, where a member may be a section: a heading and what follows it, up to the next heading
+    # at its level or above.
+    class MarkdownFile < MemberFile
+      private
+
+      # The frontmatter field the reference's query names, or the section under its heading, or the whole text.
+      #: (Array[String], Locator) -> [Integer, Integer]
+      def region(lines, locator)
+        query = locator.query
+        return FrontmatterFields.new(path: @path, lines: lines).field(query) if query
+
+        section(lines, locator.heading)
+      end
+
+      # The line range of the Markdown section under heading, or the whole text without one. A section runs
+      # to the next heading at its level or above, so its subsections come with it.
+      #: (Array[String], String?) -> [Integer, Integer]
+      def section(lines, heading)
+        return [0, lines.length] unless heading
+
+        headings = heading_lines(lines)
+        first = only_heading(lines, headings, heading)
+        level = lines.fetch(first)[/\A\#+/].to_s.length
+        [first, headings.find { |i| i > first && lines.fetch(i).match?(/\A\#{1,#{level}}\s/) } || lines.length]
+      end
+
+      # The indexes of lines that are Markdown headings: a # line outside the leading frontmatter and outside
+      # fenced code, where # starts a comment.
+      #: (Array[String]) -> Array[Integer]
+      def heading_lines(lines)
+        fence = nil #: String?
+        (frontmatter_end(lines)...lines.length).select do |i|
+          marker = lines.fetch(i)[/\A {0,3}(`{3,}|~{3,})/, 1]
+          fence = fenced_after(fence, marker) if marker
+          !marker && fence.nil? && lines.fetch(i).match?(/\A\#{1,6}\s/)
+        end
+      end
+
+      # The fence still open after a line that starts with marker: it opens one, or closes the one open
+      # when it repeats that fence's character at least as many times.
+      #: (String?, String) -> String?
+      def fenced_after(fence, marker)
+        return marker unless fence
+
+        marker.start_with?(fence) ? nil : fence
+      end
+
+      # The index of the first line after the frontmatter, which runs from a first line of --- to the next.
+      #: (Array[String]) -> Integer
+      def frontmatter_end(lines)
+        return 0 unless lines.first&.chomp == "---"
+
+        closing = (1...lines.length).find { |i| lines.fetch(i).chomp == "---" }
+        closing ? closing + 1 : 0
+      end
+
+      # Whether line is a heading of one to six #s, then whitespace, whose text is heading. It compares strings
+      # rather than building a pattern from heading, so a heading from a map cannot make the match slow.
+      #: (String, String) -> bool
+      def titled?(line, heading)
+        marks = line[/\A#+/].to_s.length
+        return false unless (1..6).cover?(marks)
+
+        rest = line[marks..].to_s
+        rest.match?(/\A\s/) && rest.strip == heading
+      end
+
+      #: (Array[String], Array[Integer], String) -> Integer
+      def only_heading(lines, headings, heading)
+        matches = headings.select { |i| titled?(lines.fetch(i), heading) }
+        return matches.fetch(0) if matches.length == 1
+        if matches.empty?
+          raise Error.new("section_not_found", "No Markdown heading #{heading.inspect}",
+                          "Give the heading's exact text without its # marks, " \
+                          "or leave out the heading to point at the whole file.", @path)
+        end
+
+        raise Error.new("ambiguous_heading", "Heading #{heading.inspect} has #{matches.length} matches",
+                        "Use a unique Markdown heading, or leave out the heading to point at the whole file.", @path)
+      end
+    end
+  end
+end