principles 0.0.1

data/lib/principles/models/project_history.rb

@@ -0,0 +1,203 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "../data/repository"
+require_relative "../data/project_files"
+require_relative "../data/principles_subfolder"
+require_relative "map_members"
+require_relative "member"
+require_relative "member_file"
+require_relative "commits_brought_in"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # What an audit needs from the project's git history, read through Data::Repository: the commit an audit
+    # is based on, each member as that commit holds it, and what changed since. Outside git there is no
+    # history, and an audit has no base commit. A path that is a symbolic link, or lies below one, is read at
+    # each commit in the file its links lead to, and whether it is committed, and which commits touched it, cover
+    # every link on the way, since git holds a link as its target's name (#695). uncommitted_outside alone asks by
+    # the paths given: start-audit asks it only once base_commit found every file they lead to committed.
+    class ProjectHistory
+      # This tool's folder as git names a folder, now and under its earlier name.
+      OWN_FOLDERS = [Data::PrinciplesSubfolder::FOLDER, Data::PrinciplesSubfolder::EARLIER_FOLDER]
+                    .map { |folder| "#{folder}/" }.freeze #: Array[String]
+
+      #: (Data::Repository, Data::ProjectFiles) -> void
+      def initialize(repository, files)
+        @repository = repository
+        @files = files
+      end
+
+      # Which of paths, and of the links and files they lead through, git does not track, which an audit refuses as
+      # members until committed (#386, #695). nil outside git, where nothing is checked.
+      #: (Array[String]) -> Array[String]?
+      def untracked(paths) = (@repository.untracked(through_links(paths)) if @repository.inside?)
+
+      # Whether git tracks path and every file its links lead to, so a fresh clone finds its text; an ignored file is
+      # not tracked either (#896). True outside git, where nothing is checked.
+      #: (String) -> bool
+      def tracks?(path) = !@repository.inside? || @repository.not_tracked(through_links([path])).empty?
+
+      # Whether the project is in git, so it has a history at all.
+      #: () -> bool
+      def inside_git? = @repository.inside?
+
+      # The project's files, other than paths, that differ from HEAD or are untracked, ignored ones aside; nil
+      # outside git or when there are none. A check and an answer's evidence read them as they are now (#409).
+      #: (Array[String]) -> Array[String]?
+      def uncommitted_outside(paths)
+        return unless @repository.inside?
+
+        outside = @repository.changed_files - paths
+        outside unless outside.empty?
+      end
+
+      # Refuses a write-up's path while it, or a file its links lead to, differs from HEAD: the record is committed
+      # pointing at it, so a fresh clone would find nothing there (#760). Nothing outside git.
+      #: (String) -> void
+      def refuse_uncommitted_write_up(path)
+        return unless @repository.inside?
+
+        dirty = uncommitted([path])
+        return if dirty.empty?
+
+        linked = dirty - [path]
+        raise Error.new("uncommitted_files",
+                        "The write-up at #{path} differs from the last commit" +
+                        (linked.empty? ? "" : ", through #{linked.join(", ")}"),
+                        "The record will point at the write-up as committed.\n" \
+                        "Commit the write-up, then submit the same answer again.")
+      end
+
+      # The commit an audit of id is based on: HEAD, refused while any of files, or a file their links lead to,
+      # differs from it. nil outside git.
+      #: (String, Array[String]) -> String?
+      def base_commit(id, files)
+        return unless @repository.inside?
+
+        dirty = uncommitted(files)
+        unless dirty.empty?
+          raise Error.new("uncommitted_files", "The map or members of #{id} differ from the last commit: " \
+                                               "#{dirty.join(", ")}",
+                          "An audit assesses the map and members as committed, so its record can name the commit " \
+                          "it began from.\nCommit them, then start it again: #{Error::EXECUTABLE} start-audit #{id}")
+        end
+
+        @repository.head
+      end
+
+      # path's text at commit, or nil when commit does not hold it.
+      #: (String, String) -> String?
+      def text_at(commit, path)
+        @repository.text_at(commit, @files.leads_to(path))
+      end
+
+      # The lines of the member at locator in its file at commit, or nil when commit lacks the file or the
+      # locator finds nothing in its text there, as after a move; any other refusal still refuses (#457).
+      #: (String, Locator) -> Array[String]?
+      def lines_at(commit, locator)
+        path = locator.path
+        text = text_at(commit, path) or return nil
+        MemberFile.for(path: path, text: text).lines_of(locator)
+      rescue Error => e
+        raise unless MemberFile::PLACEMENT_REFUSALS.include?(e.payload.fetch("code"))
+
+        nil
+      end
+
+      # Each member's id and the hash of its text at commit, or nil when commit lacks a member's file or the
+      # member's place in it.
+      #: (String, MapMembers) -> Hash[String, String]?
+      def hashes_at(commit, members)
+        members.to_h do |member|
+          path = member.path
+          text = text_at(commit, path)
+          return nil unless text
+
+          [member.id, MemberFile.for(path: path, text: text).locate(member.locator).fetch("sha256")]
+        end
+      rescue Error
+        nil
+      end
+
+      # The rename git detects for path, a file absent from the working tree, as {"to", "similarity",
+      # "deleted_in"}: the last commit that touched path, or nil while the move is not yet committed. It is
+      # git's similarity match, which can pair a deleted file with an unrelated similar one, so the agent checks
+      # it (#276). nil outside git, for a file that exists, or when git detects none.
+      #: (String) -> Hash[String, untyped]?
+      def rename_of(path)
+        return unless @repository.inside? && @repository.absent?(path)
+
+        deleted_in = @repository.text_at("HEAD", path) ? nil : @repository.last_commit(path)
+        base = deleted_in ? "#{deleted_in}^" : "HEAD"
+        found = @repository.renames_since(base).find { |each| each["from"] == path } or return nil
+        found.slice("to", "similarity").merge("deleted_in" => deleted_in)
+      end
+
+      # Each member's key and the hash of its text at commit, leaving out a member that commit cannot find.
+      #: (String, Array[Hash[String, untyped]]) -> Hash[String, String]
+      def hashes_by_key_at(commit, members)
+        members.map { |fields| Member.new(fields) }.each_with_object({}) do |member, found|
+          path = member.path
+          text = text_at(commit, path) or next
+          found[member.key] = MemberFile.for(path: path, text: text).locate(member.locator).fetch("sha256")
+        rescue Error
+          next
+        end
+      end
+
+      # Which of paths, and of the links and files they lead through, differ from HEAD, or are not yet committed.
+      #: (Array[String]) -> Array[String]
+      def uncommitted(paths)
+        @repository.uncommitted(through_links(paths))
+      end
+
+      # Which of paths name a file in the project now, so a file deleted since an audit cited it is not committed as a
+      # deletion (#842).
+      #: (Array[String]) -> Array[String]
+      def existing(paths) = paths.select { |path| @files.file?(path) }
+
+      # The commit at HEAD now; nil outside git.
+      #: () -> String?
+      def head = (@repository.head if @repository.inside?)
+
+      # The commits after commit that changed path, a link on the way to it or the file they lead to, newest
+      # first.
+      #: (String, String) -> Array[Hash[String, String]]
+      def commits_since(commit, path)
+        @repository.commits_since(commit, through_links([path]))
+      end
+
+      # Every commit on HEAD's first-parent line that changed any of paths, newest first; with since, only those
+      # after it.
+      #: (Array[String], ?since: String?) -> Array[Hash[String, String]]
+      def commits_touching(paths, since: nil)
+        @repository.commits_touching(through_links(paths), since: since)
+      end
+
+      # The commits after commit, up to HEAD, that one move of HEAD brought in, whatever they changed (D73).
+      #: (String) -> CommitsBroughtIn
+      def commits_brought_in(commit)
+        CommitsBroughtIn.new(@repository.commits_since(commit, []).map { |each| each.fetch("commit") })
+      end
+
+      # Whether any commit after commit changed this tool's own folder, under its name now or its earlier one, or one
+      # of paths, a link on the way to one or the file they lead to: the only changes that could make a command
+      # refuse that did not refuse before (review R8).
+      #: (String, Array[String]) -> bool
+      def touched_since?(commit, paths)
+        !@repository.commits_since(commit, [*OWN_FOLDERS, *through_links(paths)]).empty?
+      end
+
+      private
+
+      # paths, each with the links on the way to it and the file they lead to, once each.
+      #: (Array[String]) -> Array[String]
+      def through_links(paths)
+        paths.flat_map { |path| @files.text_paths(path) }.uniq
+      end
+    end
+  end
+end

data/lib/principles/models/record_judged_against.rb

@@ -0,0 +1,42 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "audit_record"
+require_relative "carried_assessments"
+require_relative "loads_to_check"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The principle's audit record as it stands when an assessment answer is judged against it, each part read from
+    # that one record: the members whose loads the answer must decide (#355), the assessments it may carry
+    # forward (D49), and the command it ran for each member's check (D63).
+    class RecordJudgedAgainst
+      # record is the principle's stored record, open or completed, nil when it has none.
+      #: (loads: LoadsToCheck, carried: CarriedAssessments, record: AuditRecord?) -> void
+      def initialize(loads:, carried:, record:)
+        @loads = loads
+        @carried = carried
+        @record = record
+        freeze
+      end
+
+      # The members whose loading the answer decides, and the decisions the record accepted.
+      #: LoadsToCheck
+      attr_reader :loads
+
+      # Which members' last assessments the answer may carry forward.
+      #: CarriedAssessments
+      attr_reader :carried
+
+      # The command the stored record was given an exit status for, for the member known by key, as
+      # check_since_last_audit reads it: nil when it ran none for that member.
+      #: (String) -> String?
+      def check_run_for(key) = @record&.check_run_for(key)
+
+      # The line saying what the review of that run rested on, and since when, as check_since_last_audit shows it.
+      #: (String) -> Hash[String, untyped]
+      def check_review_for(key) = @record&.check_review_for(key) || {}
+    end
+  end
+end

data/lib/principles/models/recorded_entry.rb

@@ -0,0 +1,93 @@
+# 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 member's entry in a completed audit record, filed under the id the member had then: its hash, any
+    # acknowledgements since (D33), and the assessment that audit kept for it, with what it was judged on (D49).
+    class RecordedEntry
+      #: (String, Hash[String, untyped]) -> void
+      def initialize(filed_id, entry)
+        @filed_id = filed_id
+        @entry = entry
+        freeze
+      end
+
+      # The assessment the audit kept, with when it was made and what it was judged on; nil when it kept none.
+      #: () -> Hash[String, untyped]?
+      def assessment = @entry["assessment"]
+
+      # The path of each file the kept assessment cites as evidence; none when it kept none (#724).
+      #: () -> Array[String]
+      def cited_paths = (assessment&.fetch("evidence", nil) || []).map { it.fetch("path") }
+
+      # The kept assessment as the next full audit shows it carried forward, an observed delivery's sighting dated
+      # beside it (#680), with whether any evidence it cited changed since, which the block says from each evidence
+      # item's hash then (D49).
+      #: () { (Locator, String) -> bool } -> Hash[String, untyped]
+      def carried_forward(&changed)
+        kept = assessment || {}
+        evidence = kept.fetch("evidence").zip(kept.fetch("evidence_sha256"))
+        kept.slice("assessment", "delivery").merge(sighting(kept), kept.slice("observation", "evidence", "assessed_at"))
+            .merge("evidence_changed" => evidence.any? { |each, sha| changed.call(Locator.new(each), sha) })
+      end
+
+      # When the sighting the kept assessment observed was, if observation repeats its observation word for word:
+      # its observed_at, or for a record from before sightings were dated, its assessed_at (#680). Nil otherwise.
+      #: (String) -> String?
+      def repeated_sighting(observation)
+        kept = assessment or return nil
+        sighted_at(kept) if kept["observation"] == observation
+      end
+
+      # The id the member had when the audit recorded it, when that differs from id, its id now.
+      #: (String) -> String?
+      def moved_from(id) = (@filed_id unless @filed_id == id)
+
+      # Why the member, now id with its text hashing to sha256 and judged on grounds, must be judged again, or nil
+      # when its kept assessment still describes it: the same text the audit judged, under the same id, map entry
+      # and loads (D49). An acknowledged edit is judged again, unless it was undone.
+      #: (id: String, sha256: String?, grounds: Hash[String, String]) -> String?
+      def judge_because(id:, sha256:, grounds:)
+        return "changed_during_last_audit" if @entry["changed_during_last_audit"]
+
+        kept = assessment or return "not_assessed_before"
+        return text_changed if audited_sha256 != sha256
+        return "moved" if moved_from(id)
+        return "role_or_check_changed" if kept["entry_sha256"] != grounds["entry_sha256"]
+
+        "loads_changed" if kept["loads_sha256"] != grounds["loads_sha256"]
+      end
+
+      private
+
+      # When kept's observed delivery was seen, as shown beside it: its observed_at, or for a record from before
+      # sightings were dated, its assessed_at, saying so. Empty for a delivery not observed (#680).
+      #: (Hash[String, untyped]) -> Hash[String, untyped]
+      def sighting(kept)
+        return {} unless kept["delivery"] == "observed"
+
+        { "observed_at" => sighted_at(kept), "observed_at_from_assessed_at" => (true unless kept["observed_at"]) }
+          .compact
+      end
+
+      # When the sighting kept was: its observed_at, or its assessed_at in a record from before sightings were dated.
+      #: (Hash[String, untyped]) -> String?
+      def sighted_at(kept) = kept["observed_at"] || kept["assessed_at"]
+
+      # The hash of the text the audit judged: the first acknowledgement's starting point when the member has been
+      # acknowledged since, since an acknowledgement moves the recorded hash, or else the recorded hash.
+      #: () -> String
+      def audited_sha256 = acknowledgements.first&.fetch("from_sha256") || @entry.fetch("sha256")
+
+      #: () -> String
+      def text_changed = acknowledgements.empty? ? "text_changed" : "acknowledged_since_last_audit"
+
+      #: () -> Array[Hash[String, untyped]]
+      def acknowledgements = @entry.fetch("acknowledgements", [])
+    end
+  end
+end

data/lib/principles/models/recorded_finding.rb

@@ -0,0 +1,97 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "write_up_pointer"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # One finding as an audit record holds it: its id, what the audit did about it and where it is written up.
+    # AuditRecord reads its findings only through this value (#768).
+    class RecordedFinding
+      # What a finding an assessment raised carries to its record, through the correction's basis: the one list of
+      # those fields, so the basis and the record cannot carry different ones.
+      RAISED_FIELDS = %w[id member_ids problem evidence].freeze #: Array[String]
+
+      #: (Hash[String, untyped]) -> void
+      def initialize(fields)
+        @fields = fields.freeze #: Hash[String, untyped]
+        freeze
+      end
+
+      #: () -> String
+      def id = @fields.fetch("id")
+
+      # The ids of the members it is on, as its audit recorded them.
+      #: () -> Array[String]
+      def member_ids = @fields.fetch("member_ids")
+
+      # What it says is wrong, or nil when the record kept no text for it.
+      #: () -> String?
+      def problem = @fields["problem"]
+
+      # What its audit did about it: fixed, deferred or accepted.
+      #: () -> String?
+      def action = @fields["action"]
+
+      # Where its write-up is, or nil when it was never written up.
+      #: () -> WriteUpPointer?
+      def recorded_at
+        fields = @fields["recorded_at"]
+        WriteUpPointer.new(fields) if fields
+      end
+
+      # When it was first raised, when an earlier audit raised it; nil when its own audit did.
+      #: () -> String?
+      def first_raised_at = @fields["first_raised_at"]
+
+      # The locators of the evidence it was raised with, or nil when its record keeps none (D64).
+      #: () -> Array[Hash[String, untyped]]?
+      def evidence = @fields["evidence"]
+
+      # Whether its record keeps the evidence it was raised with; one written before this tool kept evidence, or kept
+      # by a still_holds decision that gave none, keeps none (D64, #856).
+      #: () -> bool
+      def evidence_kept? = !evidence.nil?
+
+      # The path of each file it points at: its evidence and its write-up (#724).
+      #: () -> Array[String]
+      def cited_paths = [*evidence&.map { it.fetch("path") }, recorded_at&.path].compact.uniq
+
+      # The commit whose record an audit cited for an earlier first_raised_at, when one did (D53).
+      #: () -> String?
+      def raised_in = @fields["raised_in"]
+
+      # The one line saying whom it waits on and to decide what, when its deferral says (D52).
+      #: () -> String?
+      def waits_on = @fields["waits_on"]
+
+      # Since when it has waited on that, when an earlier audit asked it; nil when its own audit did.
+      #: () -> String?
+      def waits_on_since = @fields["waits_on_since"]
+
+      # Whether its audit left it open, deferred or accepted, for the next full audit to decide (D35).
+      #: () -> bool
+      def open? = %w[deferred accepted].include?(action)
+
+      # Whether its audit fixed it.
+      #: () -> bool
+      def fixed? = action == "fixed"
+
+      # This finding pointed at recorded_at, the move from where it pointed appended to its repointed with when and
+      # why (D59), or itself when it already points there, so an identical retry writes nothing (D24).
+      #: (WriteUpPointer, at: String, reason: String) -> RecordedFinding
+      def moved_to(pointer, at:, reason:)
+        return self if recorded_at == pointer
+
+        moved = { "from" => @fields["recorded_at"], "to" => pointer.to_h, "at" => at, "reason" => reason }
+        RecordedFinding.new(@fields.merge("recorded_at" => pointer.to_h,
+                                          "repointed" => [*@fields["repointed"], moved]))
+      end
+
+      # The finding as its record's file holds it.
+      #: () -> Hash[String, untyped]
+      def to_h = @fields
+    end
+  end
+end

data/lib/principles/models/recorded_findings.rb

@@ -0,0 +1,58 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "open_finding"
+require_relative "recorded_finding"
+require_relative "recorded_members"
+require_relative "write_up_repoint"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The findings an audit record's own audit recorded, whatever it did about each, with the principle, audit time
+    # and members that audit recorded them under. AuditRecord#left_open decides whose findings are open; these are
+    # only its own. Callers reach them through AuditRecord.
+    class RecordedFindings
+      #: (Array[Hash[String, untyped]], principle_id: String, audited_at: String?, members: RecordedMembers) -> void
+      def initialize(entries, principle_id:, audited_at:, members:)
+        @findings = entries.map { |finding| RecordedFinding.new(finding) } #: Array[RecordedFinding]
+        @principle_id = principle_id
+        @audited_at = audited_at
+        @members = members
+        freeze
+      end
+
+      # The findings as the record's file holds them.
+      #: () -> Array[Hash[String, untyped]]
+      def to_a = @findings.map(&:to_h)
+
+      # Those its audit deferred or accepted, each with the members as it recorded them.
+      #: () -> Array[OpenFinding]
+      def left_open
+        @findings.select(&:open?).map do |finding|
+          OpenFinding.new(finding, principle_id: @principle_id, audited_at: @audited_at, members: @members)
+        end
+      end
+
+      # The ids of those its audit fixed.
+      #: () -> Array[String]
+      def fixed_ids = @findings.select(&:fixed?).map(&:id)
+
+      # These findings with each one a repoint names moved by it, dated at (D59); the last repoint naming one wins.
+      #: (Array[WriteUpRepoint], at: String) -> RecordedFindings
+      def repointed(repoints, at:)
+        by_finding = repoints.to_h { |repoint| [repoint.finding_id, repoint] }
+        moved = @findings.map do |finding|
+          repoint = by_finding[finding.id]
+          repoint ? repoint.applied_to(finding, at: at) : finding
+        end
+        RecordedFindings.new(moved.map(&:to_h), principle_id: @principle_id, audited_at: @audited_at,
+                                                members: @members)
+      end
+
+      # The path of each file they point at: their evidence and write-ups (#724).
+      #: () -> Array[String]
+      def cited_paths = @findings.flat_map(&:cited_paths).uniq
+    end
+  end
+end

data/lib/principles/models/recorded_members.rb

@@ -0,0 +1,149 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "accepted_loading"
+require_relative "member"
+require_relative "recorded_entry"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The members an audit record assessed: each filed under the id it had then, with its key beside it when the
+    # two differ, holding its hash then, the result reported for its check (D30), its accepted loading decision
+    # and the acknowledgements made for it since (D33). Callers reach them through AuditRecord#members.
+    class RecordedMembers
+      #: (Hash[String, untyped]) -> void
+      def initialize(entries)
+        @entries = entries
+        freeze
+      end
+
+      # The entries as the record's file holds them.
+      #: () -> Hash[String, untyped]
+      def to_h = @entries
+
+      # The entries without when each assessment was made, or when a sighting it gave no date for was dated, which a
+      # record made again from the same answer dates anew (#680).
+      #: () -> Hash[String, untyped]
+      def undated
+        @entries.transform_values do |entry|
+          kept = entry["assessment"]
+          kept ? entry.merge("assessment" => kept.except("assessed_at", "observed_at")) : entry
+        end
+      end
+
+      # The path of each file an assessment kept here cites as evidence, carried forward or made now (#724).
+      #: () -> Array[String]
+      def cited_paths
+        @entries.flat_map { |id, entry| RecordedEntry.new(id, entry).cited_paths }.uniq
+      end
+
+      # Whether the text of the member known by key, whose hash is now sha, is the text the record assessed.
+      #: (String, String) -> String
+      def freshness(key, sha)
+        recorded = hash_for(key)
+        return "unassessed" unless recorded
+
+        recorded == sha ? "current" : "changed"
+      end
+
+      # Each hash the record assessed, by the key of the member it belongs to.
+      #: () -> Hash[String, String]
+      def hashes_by_key
+        @entries.to_h { |id, entry| [entry["key"] || id, entry.fetch("sha256")] }
+      end
+
+      # The hash the record assessed for the member known by key, or nil when it assessed no such member.
+      #: (String) -> String?
+      def hash_for(key)
+        entry_for(key)&.fetch("sha256")
+      end
+
+      # The check the record's audit was given an exit status for, for the member known by key: nil when the
+      # member had no check then, or its check was reported as not run, so no audit has run it (D30, #227).
+      #: (String) -> String?
+      def check_run_for(key)
+        result = entry_for(key)&.fetch("check_result", nil) or return nil
+        result.key?("exit_status") ? result.fetch("command") : nil
+      end
+
+      # What the review of that run rested on, for the member known by key, as the record keeps it: its review_basis
+      # and any review_basis_since, or nothing when the record ran no check for it or kept no line (D63).
+      #: (String) -> Hash[String, untyped]
+      def check_review_as_kept(key)
+        return {} unless check_run_for(key)
+
+        entry_for(key)&.fetch("check_result")&.slice("review_basis", "review_basis_since") || {}
+      end
+
+      # Each member's accepted loading decision, by its id now, found by the key it keeps through moves (#502).
+      #: (MapMembers) -> Hash[String, AcceptedLoading]
+      def loading_accepted(members)
+        members.to_h do |member|
+          entry = entry_for(member.key)
+          [member.id, entry&.key?("loading_accepted") ? AcceptedLoading.new(entry) : nil]
+        end.compact
+      end
+
+      # The acknowledgements made for the member known by key since the record's audit, oldest first (D33).
+      #: (String) -> Array[Hash[String, untyped]]
+      def acknowledgements_for(key)
+        entry_for(key)&.fetch("acknowledgements", nil) || []
+      end
+
+      # The member acknowledged most recently and when, as [id, acknowledged_at], or nil when none was since the
+      # record's audit (#668). The times compare as text, which orders them only because every writer gives UTC in
+      # ISO 8601.
+      #: () -> [String, String]?
+      def latest_acknowledgement
+        @entries.flat_map do |id, entry|
+          (entry["acknowledgements"] || []).map { |change| [id, change.fetch("acknowledged_at")] }
+        end.max_by(&:last)
+      end
+
+      # These entries with the member known by key moved to change's to_sha256, and change kept beside it (D33).
+      #: (String, Hash[String, untyped]) -> RecordedMembers
+      def acknowledged(key, change)
+        RecordedMembers.new(@entries.to_h do |id, entry|
+          next [id, entry] unless (entry["key"] || id) == key
+
+          [id, entry.merge("sha256" => change.fetch("to_sha256"),
+                           "acknowledgements" => [*entry["acknowledgements"], change])]
+        end)
+      end
+
+      # The key of the member filed under id: its stored key when it had moved, or else id.
+      #: (String) -> String
+      def key_of(id)
+        @entries.dig(id, "key") || id
+      end
+
+      # The entry of the member known by key, under the id it was filed under, or nil when the record has none.
+      #: (String) -> RecordedEntry?
+      def recorded(key)
+        id, entry = @entries.find { |filed, each| (each["key"] || filed) == key }
+        RecordedEntry.new(id, entry) if id && entry
+      end
+
+      # These entries with each assessment an answer carried forward, marked {"carried_forward": true}, replaced by
+      # the one last kept for the same member, so the record keeps it with its first date (D49).
+      #: (RecordedMembers?) -> RecordedMembers
+      def carrying(last)
+        RecordedMembers.new(@entries.to_h do |id, entry|
+          next [id, entry] unless entry.dig("assessment", "carried_forward")
+
+          [id, entry.merge("assessment" => last&.recorded(entry["key"] || id)&.assessment).compact]
+        end)
+      end
+
+      private
+
+      # The entry for the member known by key: filed under the id it had then, with its key beside it when the
+      # two differ.
+      #: (String) -> Hash[String, untyped]?
+      def entry_for(key)
+        @entries.find { |id, entry| (entry["key"] || id) == key }&.last
+      end
+    end
+  end
+end