principles 0.0.1

data/lib/principles/models/assessment_answer.rb

@@ -0,0 +1,131 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "answer_fields"
+require_relative "loads_to_check"
+require_relative "member_assessments"
+require_relative "misspelt_member_id"
+require_relative "record_judged_against"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # An agent's answer to an assessment request: one assessment per member, an assessment of the set, a
+    # recent decision under it, and findings. The block locates each piece of evidence in the project and
+    # refuses one that does not resolve. members are the audited members, each checked one's assessment reporting
+    # its check's result (D30); judged_against is the principle's record as it stands, which lists the members
+    # whose loading it must decide (#355) and the assessments it may carry (D49); answered_at is when it came, which
+    # no sighting it reports is after (#699).
+    class AssessmentAnswer
+      #: (untyped, MapMembers, answered_at: String, ?judged_against: RecordJudgedAgainst?)
+      #|   { (Locator) -> Hash[String, untyped] } -> void
+      def initialize(response, members, answered_at:, judged_against: nil, &locate)
+        @response = response
+        @members = members
+        @answered_at = answered_at
+        @judged_against = judged_against
+        @loads = judged_against&.loads #: LoadsToCheck?
+        @locate = locate #: ^(Locator) -> Hash[String, untyped]
+        @fields = AnswerFields.new(locate) #: AnswerFields
+      end
+
+      # The answer's findings, once every member assessment, the collective assessment, the recent
+      # decision and each finding have been checked.
+      #: () -> Array[untyped]
+      def findings
+        member_assessments.check
+        @fields.text(@response["collective_assessment"], "collective_assessment")
+        recent_decision
+        checked_findings
+      end
+
+      # The result reported for each checked member's check, by member id, once each has been checked.
+      #: () -> Hash[String, Hash[String, untyped]]
+      def check_results = member_assessments.check_results
+
+      # By member id, the fields this answer reports for each member's record entry: its assessment, which the next
+      # full audit may carry forward (D49), its check's result (D30) and its accepted loading decision (#355), once
+      # each listed member's is checked against loads.
+      #: () -> Hash[String, Hash[String, untyped]]
+      def entry_fields
+        checked = check_results.transform_values do |result|
+          { "check_result" => result }
+        end #: Hash[String, Hash[String, untyped]]
+        accepted = (@loads&.decided(@response["loading_decisions"]) || {}).transform_values do |kept|
+          { "loading_accepted" => kept }
+        end
+        reported = checked.merge(accepted) { |_id, check, loading| check.merge(loading) }
+        member_assessments.kept(&@locate).merge(reported) { |_id, assessment, fields| assessment.merge(fields) }
+      end
+
+      # The paths the recent decision's evidence cites, which the record does not keep but a completed audit asks to
+      # commit when they differ from HEAD (#860); none when the decision was unavailable.
+      #: () -> Array[String]
+      def recent_decision_paths
+        decision = @response.fetch("recent_decision")
+        return [] if decision["unavailable_reason"]
+
+        decision.fetch("evidence").map { |item| item.fetch("path") }.uniq
+      end
+
+      private
+
+      #: () -> MemberAssessments
+      def member_assessments
+        MemberAssessments.new(@response["member_assessments"], @members, fields: @fields,
+                                                                         judged_against: @judged_against,
+                                                                         answered_at: @answered_at)
+      end
+
+      #: () -> void
+      def recent_decision
+        decision = @response.fetch("recent_decision")
+        if decision["unavailable_reason"]
+          @fields.text(decision["unavailable_reason"], "recent_decision.unavailable_reason")
+        else
+          @fields.text(decision["assessment"], "recent_decision.assessment")
+          @fields.evidence(decision["evidence"], AnswerPlace.new("/recent_decision/evidence", "Recent decision"))
+        end
+      end
+
+      #: () -> Array[untyped]
+      def checked_findings
+        findings = @fields.array(@response["findings"], "findings")
+        finding_ids = findings.each_with_index.map { |finding, index| finding_id(finding, index) }
+        unless finding_ids.uniq == finding_ids
+          raise Error.new("duplicate_finding", "Finding ids repeat",
+                          "Give each finding a unique id.")
+        end
+
+        findings
+      end
+
+      # The id of finding, once its fields, members and evidence have been checked.
+      #: (untyped, Integer) -> untyped
+      def finding_id(finding, index)
+        @fields.text(finding["id"], "finding.id")
+        %w[problem consequence proposed_action].each { |field| @fields.text(finding[field], "finding.#{field}") }
+        affected_members(finding)
+        place = AnswerPlace.new("/findings/#{index}", "Finding #{finding["id"]}")
+        @fields.evidence(finding["evidence"], place.child("evidence"))
+        finding.fetch("id")
+      end
+
+      # Refuses a finding that names no member, or one the map does not have.
+      #: (untyped) -> void
+      def affected_members(finding)
+        affected = @fields.array(finding["member_ids"], "finding.member_ids")
+        ids = @members.ids
+        return unless affected.empty? || (affected - ids).any?
+
+        raise Error.new("unknown_member", "Finding #{finding["id"]} names unknown or no members",
+                        [*near_misses(affected - ids), "Use one or more of #{ids.join(", ")}."].join(" "))
+      end
+
+      # A hint for each unmapped id that differs from a mapped one only in punctuation, case or spacing.
+      #: (Array[untyped]) -> Array[String]
+      def near_misses(unknown) = unknown.grep(String).filter_map { |id| MisspeltMemberId.new(id).hint(@members.ids) }
+    end
+  end
+end

data/lib/principles/models/assessment_basis.rb

@@ -0,0 +1,47 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "audit_record"
+require_relative "last_completed_revision"
+
+module Principles
+  # The domain logic, which loads and saves itself through data/. models/CLAUDE.md owns the boundary.
+  module Models
+    # What an assessment request prints as its basis, which the agent hands back with the answer: the commit the
+    # audit is based on, nil outside git, and the revision of the last completed audit record when the request was
+    # printed, nil when there was none, so the answer is refused once that record changed (#653, D50).
+    class AssessmentBasis
+      # The basis printed for an audit based on base, after record, the principle's audit record now, if any.
+      #: (String?, AuditRecord?) -> AssessmentBasis
+      def self.printed(base, record)
+        new("base_commit" => base, "last_completed_revision" => record&.last_completed&.revision)
+      end
+
+      #: (Hash[String, untyped]) -> void
+      def initialize(fields)
+        @fields = fields
+        freeze
+      end
+
+      #: () -> Hash[String, untyped]
+      def to_h = @fields
+
+      # The commit the audit is based on, nil outside git.
+      #: () -> String?
+      def base = @fields["base_commit"]
+
+      # The last completed record's revision when the request was printed, nil when there was none, which the
+      # correction the assessment prints carries forward (D50).
+      #: () -> String?
+      def revision = @fields["last_completed_revision"]
+
+      # The last completed record's revision when the request was printed, which refuses the answer once it changed.
+      #: () -> LastCompletedRevision
+      def printed_after = LastCompletedRevision.new(revision)
+
+      # What the request id digests of the basis, in a fixed order, so how the answer orders its keys changes nothing.
+      #: () -> Array[String?]
+      def digested = [base, revision]
+    end
+  end
+end

data/lib/principles/models/assessment_report.rb

@@ -0,0 +1,62 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "assessment_answer"
+require_relative "member_grounds"
+require_relative "member_moves"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # What an assessment reported beyond its findings, which its audit's record and commit carry: by member id, the
+    # fields of each member's record entry, such as its assessment (D49) and its check's result (D30), and the paths
+    # its recent decision cites, which the record does not keep but the completed audit asks to commit when they
+    # differ from HEAD (#860). A correction request carries it in its basis, so the completed audit keeps it; this is
+    # the one owner of how it is carried.
+    class AssessmentReport
+      # The report of the answer assessed, each assessment it makes, rather than carries, with the grounds it was
+      # judged on (D49).
+      #: (AssessmentAnswer, MemberGrounds) -> AssessmentReport
+      def self.answered(assessed, grounds)
+        fields = assessed.entry_fields.to_h do |id, entry|
+          kept = entry["assessment"]
+          [id, kept && !kept["carried_forward"] ? entry.merge("assessment" => kept.merge(grounds.of(id))) : entry]
+        end
+        new(fields, recent_decision_paths: assessed.recent_decision_paths)
+      end
+
+      # The report carried in a correction basis, under the ids of any members moves moved.
+      #: (CorrectionBasis, MemberMoves) -> AssessmentReport
+      def self.carried(basis, moves)
+        fields = basis.to_h
+        new(moves.hashes(fields.fetch("entry_fields", {})),
+            recent_decision_paths: fields.fetch("recent_decision_paths", []))
+      end
+
+      # The paths the recent decision cites as evidence.
+      #: Array[String]
+      attr_reader :recent_decision_paths
+
+      # entry_fields are, by member id, the fields the assessment reported for that member's record entry.
+      #: (?Hash[String, Hash[String, untyped]], ?recent_decision_paths: Array[String]) -> void
+      def initialize(entry_fields = {}, recent_decision_paths: [])
+        @entry_fields = entry_fields #: Hash[String, Hash[String, untyped]]
+        @recent_decision_paths = recent_decision_paths
+        freeze
+      end
+
+      # The fields the assessment reported for the record entry of the member known by id, or none.
+      #: (String) -> Hash[String, untyped]
+      def entry_fields_of(id) = @entry_fields.fetch(id, {})
+
+      # The fields a correction basis carries it in, leaving out what it does not hold.
+      #: () -> Hash[String, untyped]
+      def basis_fields
+        { "entry_fields" => @entry_fields, "recent_decision_paths" => @recent_decision_paths }
+          .reject { |_key, value| value.empty? }
+      end
+
+      NONE = new #: AssessmentReport
+    end
+  end
+end

data/lib/principles/models/audit.rb

@@ -0,0 +1,200 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "member_map"
+require_relative "declared_map_changes"
+require_relative "request_id"
+require_relative "correction_basis"
+require_relative "assessment_basis"
+require_relative "assessment_answer"
+require_relative "audit_start"
+require_relative "assessment_report"
+require_relative "loads_to_check"
+require_relative "member_grounds"
+require_relative "carried_assessments"
+require_relative "prior_findings"
+require_relative "decided_prior_findings"
+require_relative "disposition"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # One principle's audit as its map and members are now. Nothing about a request is stored (D25): each
+    # request id digests what the request depends on, so an answer is refused when what it was asked about
+    # has changed since. A correction is based on the map's version and each finding's members, never on
+    # the agent's prose.
+    class Audit
+      #: MemberMap
+      attr_reader :map
+      # Each member's hash now.
+      #: Hash[String, String]
+      attr_reader :now
+
+      #: (map: MemberMap, now: Hash[String, String]) -> void
+      def initialize(map:, now:)
+        @map = map
+        @now = now
+      end
+
+      # The principle audited, as its map names it.
+      #: () -> String
+      def id = @map.id
+
+      #: () -> String
+      def map_version = @map.version
+
+      # The id of the assessment request printed with basis: its base commit, nil outside git, and the last
+      # completed record's revision, so an answer cannot point the request at a later record (#653).
+      # prior is what PriorFindings#digested gives, empty when the last audit left no finding to decide (D35);
+      # loads is what LoadsToCheck#listed gives, nil when the activation lists nothing to check (#355).
+      #: (AssessmentBasis, ?Array[Hash[String, untyped]], ?Hash[String, untyped]?) -> RequestId
+      def assessment_id(basis, prior = [], loads = nil)
+        parts = [map_version, basis.digested, @now]
+        parts = [*parts, prior] unless prior.empty?
+        parts = [*parts, { "loads_to_check" => loads }] if loads
+        RequestId.for(principle_id: id, phase: "assessment", parts: parts)
+      end
+
+      # Refuses an assessment unless request_id is the one printed with basis for the map and members as they are
+      # now, and, in git, the members are as its base holds them (committed).
+      # It returns the findings the last audit, whose record is given, left for this one to decide (D35); loads is
+      # what the audit lists to check now, so a change to what lists a member to check makes the request stale (#355).
+      #: (RequestId, basis: AssessmentBasis, committed: Hash[String, String]?, record: AuditRecord?,
+      #|  loads: LoadsToCheck) -> PriorFindings
+      def check_assessment_request(request_id, basis:, committed:, record:, loads:)
+        prior = prior_findings(record)
+        now_id = assessment_id(basis, prior.digested, loads.listed)
+        raise stale_request unless now_id == request_id && (basis.base.nil? || committed == @now)
+
+        prior
+      end
+
+      # The answer to this audit's assessment request, checked against each member, each member's check (D30)
+      # and each member the listing names to check against the activation (#355); the block locates each piece of
+      # evidence, giving where it is and the hash of its text.
+      # judged_against is the principle's record as it stands, which says which members' last assessments the
+      # answer may carry forward (D49); answered_at is when the answer came, which no sighting it reports is after
+      # (#699).
+      #: (untyped, RecordJudgedAgainst, String) { (Locator) -> Hash[String, untyped] }
+      #|  -> AssessmentAnswer
+      def assessment(response, judged_against, answered_at, &)
+        AssessmentAnswer.new(response, map_members, answered_at: answered_at, judged_against: judged_against, &)
+      end
+
+      # A digest of what this audit's assessments answer: its description and question (D49).
+      #: (String) -> String
+      def judged_against(question) = started(nil, {}).judged_against(question)
+
+      # What this audit began from: base (nil outside git), each member's hash then and what the assessment reported
+      # beyond its findings.
+      #: (String?, Hash[String, String], ?AssessmentReport) -> AuditStart
+      def started(base, before, reported = AssessmentReport::NONE)
+        AuditStart.new(map: @map, base: base, before: before, reported: reported)
+      end
+
+      # What an audit answered by assessed began from: base, each member's hash now, and what the answer reported
+      # beyond its findings, each assessment with the grounds it was judged on (D49).
+      #: (String?, AssessmentAnswer, MemberGrounds) -> AuditStart
+      def assessed_start(base, assessed, grounds)
+        started(base, @now, AssessmentReport.answered(assessed, grounds))
+      end
+
+      # What the audit a correction's basis names began from: its base commit, each member's hash then
+      # (before), and the assessment's report the basis carries, under the ids of any moved members.
+      #: (CorrectionBasis, Hash[String, String], MemberMoves) -> AuditStart
+      def resumed(basis, before, moves)
+        started(basis.base_commit, before, AssessmentReport.carried(basis, moves))
+      end
+
+      # The map the audit began from: the current one when it is unchanged and the answer declares no change; or,
+      # in git, the map at the base commit, which the block reads, refused unless the declared changes and any
+      # members added explain every change. Outside git, a map that changed is refused.
+      #: (CorrectionBasis, DeclaredMapChanges, map_file: String) { (String) -> MemberMap } -> MemberMap
+      def map_started_from(basis, changes, map_file:, &)
+        base = changes.base_to_read(basis.base_commit, @map, map_version: basis.map_version, map_file: map_file)
+        return @map unless base
+
+        started = yield(base)
+        changes.check(started, @map, map_version: basis.map_version, map_file: map_file)
+        started
+      end
+
+      # The hashes the audit began from (before), refused unless they were found and request_id is the one
+      # printed for them and basis.
+      #: (RequestId, CorrectionBasis, Hash[String, String]?) -> Hash[String, String]
+      def confirmed_start(request_id, basis, before)
+        raise stale_request unless before && basis.request_id(id, before) == request_id
+
+        before
+      end
+
+      # Each finding's outcome: its members and its disposition's action, where it is recorded, if anywhere, and
+      # what a deferral says it waits on, if anything (D52).
+      # Then each prior finding kept (D35); a new finding that raises one again keeps when it was first raised.
+      #: (Array[untyped], Array[Disposition], ?DecidedPriorFindings) -> Array[untyped]
+      def outcomes(findings, dispositions, prior = DecidedPriorFindings::NONE)
+        findings.map do |finding|
+          id = finding.fetch("id")
+          disposition = dispositions.find { |each| each.finding_id == id } or raise KeyError, id
+          finding.slice(*RecordedFinding::RAISED_FIELDS).merge(disposition.recorded_outcome, prior.first_raised(id))
+        end + prior.kept
+      end
+
+      # What each member's assessment is judged on beside its text, from each member's loads: its map entry and when
+      # it loads (D49).
+      #: (Hash[String, MemberLoads]) -> MemberGrounds
+      def grounds(loads) = MemberGrounds.new(map_members, loads)
+
+      # Which members' last assessments this audit carries forward, from the principle's record now, grounds, and the
+      # question the request asks (D49).
+      #: (AuditRecord?, grounds: MemberGrounds, question: String) -> CarriedAssessments
+      def carried_assessments(record, grounds:, question:)
+        CarriedAssessments.new(record, members: map_members, judged_against: judged_against(question), now: @now,
+                                       grounds: grounds)
+      end
+
+      # The members this audit lists to check against the map's activation, from each member's loads (#355), each
+      # with the decision the last completed audit, whose record is given, accepted on its loading (#502).
+      #: (Hash[String, MemberLoads], ?AuditRecord?) -> LoadsToCheck
+      def loads_to_check(loads, record = nil)
+        completed = record&.last_completed
+        LoadsToCheck.new(activation: @map.activation, loads: loads, hashes: @now,
+                         accepted: completed ? completed.members.loading_accepted(map_members) : {})
+      end
+
+      # The findings the last audit left for this one to decide (D35), from its record.
+      #: (AuditRecord?) -> PriorFindings
+      def prior_findings(record)
+        PriorFindings.new(record: record, now: @now, members: map_members)
+      end
+
+      # The project files the dispositions say changed: each fixed member's file, then each file where a
+      # finding is recorded.
+      #: (Array[Disposition]) -> Array[String]
+      def changed_files(dispositions)
+        fixed = dispositions.select(&:fixed?).flat_map(&:changed_members).map { |member| path_of(member) }
+        (fixed + dispositions.filter_map(&:recorded_path)).uniq
+      end
+
+      # The path of the member with member_id in the map, refused as unknown_member when no member has it (#778).
+      #: (String) -> String
+      def path_of(member_id) = map_members.found(member_id).path
+
+      private
+
+      # The members as the map lists them, which say each one's id and check.
+      #: () -> MapMembers
+      def map_members = @map.members
+
+      #: () -> Error
+      def stale_request
+        Error.new("stale_request", "This request no longer matches #{id}: its map, a member, the commit it " \
+                                   "was based on, or what says when a listed member loads and how big it is " \
+                                   "(project settings, frontmatter or a listed file), has changed since it was " \
+                                   "printed",
+                  "Start the audit again and answer the new request: #{Error::EXECUTABLE} start-audit #{id}")
+      end
+    end
+  end
+end