principles 0.0.1

data/lib/principles/models/carried_assessments.rb

@@ -0,0 +1,76 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "audit_record"
+require_relative "member"
+require_relative "member_grounds"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # Which members a full audit carries forward the last full audit's assessment of, and why it asks the agent to
+    # judge each other one (D48, D49). A member is carried only when the last completed record kept its assessment
+    # and judged it against the same description and question, and its text, id, map entry and loads are as that
+    # audit judged them. Each test compares stored values, so it is this tool's to make; whether the set still
+    # holds, and whether to re-judge a carried member, is the agent's.
+    class CarriedAssessments
+      # record is the principle's audit record now, if any; members are the map's members now, with their hashes in
+      # now and their grounds; judged_against digests the description and question this audit asks.
+      #: (AuditRecord?, members: MapMembers, judged_against: String, now: Hash[String, String],
+      #|  grounds: MemberGrounds) -> void
+      def initialize(record, members:, judged_against:, now:, grounds:)
+        @last = record&.last_completed #: AuditRecord?
+        @members = members
+        @judged_against = judged_against
+        @now = now
+        @grounds = grounds
+        freeze
+      end
+
+      # Why the member id must be judged again, or nil when its last assessment is carried forward. A record from
+      # before assessments were kept assessed each member it recorded, but kept none to carry (#701).
+      #: (String) -> String?
+      def judge_because(id)
+        last = @last or return "not_assessed_before"
+        entry = recorded(id)
+        return reason_in_record_before_assessments_were_kept(entry) unless last.kept_assessments?
+        return "description_or_question_changed" unless last.judged_against?(@judged_against)
+
+        entry ? entry.judge_because(id: id, sha256: @now[id], grounds: @grounds.of(id)) : "not_assessed_before"
+      end
+
+      # Whether the member id's last assessment is carried forward.
+      #: (String) -> bool
+      def carried?(id) = judge_because(id).nil?
+
+      # What the request shows beside the member id: the assessment carried forward, with whether any evidence it
+      # cited changed since, which the block says from each evidence item's hash then; or why it is judged again, and
+      # where it was if it moved.
+      #: (String) { (Locator, String) -> bool } -> Hash[String, untyped]
+      def shown(id, &)
+        reason = judge_because(id)
+        return { "judge_because" => reason, "moved_from" => recorded(id)&.moved_from(id) }.compact if reason
+
+        entry = recorded(id) or return {}
+        { "carried_forward" => entry.carried_forward(&) }
+      end
+
+      # When the last full audit's sighting of the member id was, if a fresh observation repeats that audit's word for
+      # word; nil when it does not, or there was none. Whether the sighting is the same is the agent's to say (#680).
+      #: (String, String) -> String?
+      def repeated_sighting(id, observation) = recorded(id)&.repeated_sighting(observation)
+
+      private
+
+      # Why a member of a record from before assessments were kept is judged again: that audit assessed it, if the
+      # record holds its entry, but kept no assessment to carry.
+      #: (RecordedEntry?) -> String
+      def reason_in_record_before_assessments_were_kept(entry)
+        entry ? "assessed_before_assessments_were_kept" : "not_assessed_before"
+      end
+
+      #: (String) -> RecordedEntry?
+      def recorded(id) = @last&.members&.recorded(@members.found(id).key)
+    end
+  end
+end

data/lib/principles/models/check_since_last_audit.rb

@@ -0,0 +1,61 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "audit_record"
+require_relative "member"
+require_relative "member_map_history"
+require_relative "member_maps"
+require_relative "project_history"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # Whether a member's check is the one the principle's last audit was given an exit status for, and, when
+    # it is not, the commit that made it what it is now. A check is a command any collaborator can change in the
+    # committed map, and the audit asks the agent to run it, so a check no audit has seen needs a review
+    # first (#227). This tool states the fact; the review is the agent's step.
+    class CheckSinceLastAudit
+      #: (id: String, history: ProjectHistory, member_maps: MemberMaps, record: AuditRecord?) -> void
+      def initialize(id:, history:, member_maps:, record:)
+        @id = id
+        @history = history
+        @member_maps = member_maps
+        @record = record
+        freeze
+      end
+
+      # "unchanged" when the last audit was given an exit status for this same check; otherwise "new" or
+      # "changed", with changed_in the oldest commit of the unbroken run, back from HEAD, whose map holds it,
+      # and, when changed, last_run, the command the last audit ran. Beside an unchanged check, the line saying what its
+      # last review rested on and since when; beside a changed one, last_run_review_basis, that line for the command
+      # the last audit ran, not this one (D63).
+      # changed_in is nil outside git, or when no commit holds it. The walk stops at a map it cannot read, so
+      # changed_in may then name a later commit than the one that set the check: the review is still asked for.
+      #: (Member, String) -> Hash[String, untyped]
+      def of(member, check)
+        ran = @record&.check_run_for(member.key)
+        review = review_of(member.key)
+        return { "status" => "unchanged", **review } if ran == check
+
+        changed_in = commit_that_set(member.key, check)
+        return { "status" => "new", "changed_in" => changed_in } unless ran
+
+        last_run_review = review.slice("review_basis").transform_keys { "last_run_review_basis" }
+        { "status" => "changed", "last_run" => ran, **last_run_review, "changed_in" => changed_in }
+      end
+
+      private
+
+      # The line the last audit's record keeps for what the review of its run rested on, and since when (D63).
+      #: (String) -> Hash[String, untyped]
+      def review_of(key) = @record&.check_review_for(key) || {}
+
+      #: (String, String) -> String?
+      def commit_that_set(key, check)
+        run = MemberMapHistory.new(id: @id, history: @history, member_maps: @member_maps).runs([key]).fetch(key)
+        run.take_while { |_sha, fields| Member.new(fields).check == check }.last&.first
+      end
+    end
+  end
+end

data/lib/principles/models/cited_files.rb

@@ -0,0 +1,39 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "assessment_report"
+require_relative "project_history"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The files an audit record cites, through its assessments' evidence and its findings' evidence and write-ups, as
+    # the project holds them now: which go with the record when its completed audit is committed, since a clone needs
+    # every file the record points at (#724), and which no longer exist, though the record still points at them (#861).
+    class CitedFiles
+      # paths are the files the record cites; in_git says whether its audit had a base commit to compare with.
+      #: (Array[String], ProjectHistory, in_git: bool) -> void
+      def initialize(paths, history, in_git:)
+        @paths = paths
+        @history = history
+        @in_git = in_git
+        freeze
+      end
+
+      # The files to commit with the record, sorted once each: each file the audit changed; in git, with each cited
+      # file, only those that still differ from HEAD, since a fix the agent already committed needs nothing. A cited
+      # file deleted since is left out, since adding it would stage a deletion the audit never made (#842); a file its
+      # fixes deleted stays. What reported cites that the record does not keep, as the answer's recent decision's
+      # paths, is cited too (#860).
+      #: (Array[String], ?AssessmentReport) -> Array[String]
+      def committed_with(changed, reported = AssessmentReport::NONE)
+        changed = @history.uncommitted(changed + @history.existing(@paths + reported.recent_decision_paths)) if @in_git
+        changed.uniq.sort
+      end
+
+      # Each cited file that no longer exists, in git or outside it (#861).
+      #: () -> Array[String]
+      def missing = @paths - @history.existing(@paths)
+    end
+  end
+end

data/lib/principles/models/command_steps.rb

@@ -0,0 +1,270 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "../data/command_steps_file"
+
+module Principles
+  # Values built from validated data, and the rules a schema cannot express. models/CLAUDE.md owns the
+  # boundary.
+  module Models
+    # The steps each command runs: which are this tool's and which are the agent's, the refusals each of
+    # this tool's steps can raise, and where each step leads. Each command's --help and the workflow diagram
+    # are drawn from it (ticket 001 D15). It is built from data Data::CommandStepsFile has already checked
+    # against its schema, and checks what a schema cannot: every step a branch names exists, every refusal
+    # group exists, and every command a step hands over to is real. The prompts it names are checked by
+    # spec/unit/principles/views/prompts_spec.rb, because the domain reads no files.
+    class CommandSteps
+      # Where a step leads when it branches.
+      class Branch
+        #: String
+        attr_reader :to
+        #: String
+        attr_reader :condition
+
+        # A step's branches, from its "next" list.
+        #: (Array[Hash[String, String]]) -> Array[Branch]
+        def self.all(edges)
+          edges.map { |edge| new(edge.fetch("to"), edge.fetch("when")) }.freeze
+        end
+
+        #: (String, String) -> void
+        def initialize(to, condition)
+          @to = to
+          @condition = condition
+          freeze
+        end
+      end
+
+      # What an agent's step hands back: what this tool then checks, what it cannot, and the command the agent
+      # answers with.
+      class Handover
+        #: String?
+        attr_reader :checks
+        #: String?
+        attr_reader :cannot_check
+        #: String?
+        attr_reader :answer_with
+        # When the agent runs answer_with, where that is the agent's to time, as a first full audit is (#627).
+        #: String?
+        attr_reader :answer_when
+        # The form of answer_with the step hands to, where its whole usage would mislead, as a first full audit
+        # that --member would make a refused one-member audit (#635).
+        #: String?
+        attr_reader :answer_usage
+
+        #: (Hash[String, untyped]) -> void
+        def initialize(data)
+          @checks = data["checks"] #: String?
+          @cannot_check = data["cannot_check"] #: String?
+          @answer_with = data["answer_with"] #: String?
+          @answer_when = data["answer_when"] #: String?
+          @answer_usage = data["answer_usage"] #: String?
+          freeze
+        end
+
+        # Whether answer_usage, if given, is a form of the command answer_with names, so it cannot drift to another.
+        #: () -> bool
+        def usage_names_its_command?
+          usage = @answer_usage
+          usage.nil? || usage == @answer_with || usage.start_with?("#{@answer_with} ")
+        end
+      end
+
+      # One step: this tool's ("cli") or the agent's ("agent").
+      class Step
+        #: String
+        attr_reader :id
+        #: String
+        attr_reader :does
+        #: Array[String]
+        attr_reader :refusals
+        #: String?
+        attr_reader :prompt
+        #: Handover
+        attr_reader :handover
+        #: Array[Branch]
+        attr_reader :branches
+
+        #: (Hash[String, untyped], Array[String]) -> void
+        def initialize(data, refusals)
+          @id = data.fetch("id") #: String
+          @agent = data.fetch("actor") == "agent" #: bool
+          @does = data.fetch("does") #: String
+          @refusals = refusals.freeze #: Array[String]
+          @prompt = data["prompt"] #: String?
+          @handover = Handover.new(data) #: Handover
+          @branches = Branch.all(data.fetch("next", [])) #: Array[Branch]
+          freeze
+        end
+
+        #: () -> bool
+        def agent?
+          @agent
+        end
+      end
+
+      # A heading the overview lists commands under, and what every command under it writes.
+      class Group
+        #: String
+        attr_reader :id
+        #: String
+        attr_reader :heading
+        #: String
+        attr_reader :writes
+
+        #: (Hash[String, untyped]) -> void
+        def initialize(data)
+          @id = data.fetch("id") #: String
+          @heading = data.fetch("heading") #: String
+          @writes = data.fetch("writes") #: String
+          freeze
+        end
+      end
+
+      # One command, with its steps in the order they run.
+      class Command
+        #: String
+        attr_reader :name
+        #: String
+        attr_reader :usage
+        #: String
+        attr_reader :group
+        # The named options it takes, without their dashes, besides --project and --help.
+        #: Array[String]
+        attr_reader :options
+        #: String
+        attr_reader :summary
+        #: String
+        attr_reader :help
+        #: Array[Step]
+        attr_reader :steps
+
+        #: (Hash[String, untyped], Array[Step]) -> void
+        def initialize(data, steps)
+          @name = data.fetch("name") #: String
+          @usage = data.fetch("usage") #: String
+          @group = data.fetch("group") #: String
+          @options = data.fetch("options").freeze #: Array[String]
+          @summary = data.fetch("summary") #: String
+          @help = data.fetch("help") #: String
+          @steps = steps.freeze #: Array[Step]
+          freeze
+        end
+
+        # The steps a step leads to: its branches, or else the next step unless it hands over to a command.
+        #: (Step) -> Array[Step]
+        def successors(step)
+          return step.branches.map { |branch| find(branch.to) } if step.branches.any?
+          return [] if step.handover.answer_with
+
+          following = @steps[@steps.index(step).to_i + 1]
+          following ? [following] : []
+        end
+
+        #: (String) -> Step
+        def find(id)
+          @steps.find { |step| step.id == id } || raise(KeyError, "#{@name} has no step #{id}")
+        end
+      end
+
+      # The overview's headings, in the order it lists them.
+      #: Array[Group]
+      attr_reader :groups
+      #: Array[String]
+      attr_reader :every_command_refuses
+      #: Array[Command]
+      attr_reader :commands
+
+      # Every command's steps, read from the command-steps.json the gem ships.
+      #: () -> CommandSteps
+      def self.load
+        new(Data::CommandStepsFile.new.read, Data::CommandStepsFile::PATH)
+      end
+
+      # data is the validated content of command-steps.json; source names it in a refusal.
+      #: (untyped, String) -> void
+      def initialize(data, source)
+        @source = source
+        @groups = data.fetch("groups").map { |group| Group.new(group) }.freeze #: Array[Group]
+        @refusal_groups = data.fetch("refusal_groups") #: Hash[String, Array[String]]
+        @every_command_refuses = @refusal_groups.fetch("any-command") #: Array[String]
+        @commands = data.fetch("commands").map { |command| build(command) }.freeze #: Array[Command]
+        check_references
+        freeze
+      end
+
+      #: (String) -> Command?
+      def command(name)
+        @commands.find { |command| command.name == name }
+      end
+
+      # What a command writes, which every command in its group shares.
+      #: (Command) -> String
+      def writes(command)
+        @groups.find { |group| group.id == command.group }&.writes || refuse("#{command.name} is in no group")
+      end
+
+      # Every refusal code some step, or every command, can raise.
+      #: () -> Array[String]
+      def refusal_codes
+        (@every_command_refuses + @commands.flat_map { |command| command.steps.flat_map(&:refusals) }).uniq.sort
+      end
+
+      # Every prompt this file names: each command's help and each step's prompt.
+      #: () -> Array[String]
+      def prompt_names
+        @commands.flat_map { |command| [command.help, *command.steps.filter_map(&:prompt)] }.uniq.sort
+      end
+
+      private
+
+      #: (Hash[String, untyped]) -> Command
+      def build(data)
+        steps = data.fetch("steps").map do |step|
+          Step.new(step, (step.fetch("refuses", []) + step.fetch("refuses_like", []).flat_map do |group|
+            refusal_group(group)
+          end).uniq)
+        end
+        Command.new(data, steps)
+      end
+
+      #: (String) -> Array[String]
+      def refusal_group(name)
+        @refusal_groups.fetch(name) { refuse("No refusal group #{name}") }
+      end
+
+      #: () -> void
+      def check_references
+        names = @commands.map(&:name)
+        refuse("Command names repeat") unless names.uniq == names
+        @commands.each { |command| check_command(command, names) }
+      end
+
+      #: (Command, Array[String]) -> void
+      def check_command(command, names)
+        writes(command)
+        ids = command.steps.map(&:id)
+        refuse("#{command.name} repeats a step id") unless ids.uniq == ids
+        command.steps.each { |step| check_step("#{command.name}/#{step.id}", step, names, ids) }
+      end
+
+      #: (String, Step, Array[String], Array[String]) -> void
+      def check_step(where, step, names, ids)
+        target = step.handover.answer_with
+        refuse("#{where} answers with unknown command #{target}") if target && !names.include?(target)
+        unless step.handover.usage_names_its_command?
+          refuse("#{where}'s handover form #{step.handover.answer_usage} does not name #{target}")
+        end
+        unknown = step.branches.map(&:to) - ids
+        refuse("#{where} branches to unknown step #{unknown.join(", ")}") if unknown.any?
+      end
+
+      #: (String) -> bot
+      def refuse(message)
+        raise Error.new("invalid_command_steps", message,
+                        "Repair the file so every step it names exists.", @source)
+      end
+    end
+  end
+end

data/lib/principles/models/commits_brought_in.rb

@@ -0,0 +1,27 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The commits one move of HEAD brought in, by abbreviated id, as the after-commit hook asks about them (D73): one
+    # for a commit or an amend, a lane for a fast-forward, the rewritten commits for a rebase. git chooses how long an
+    # abbreviated id is, so two name the same commit when one starts with the other (review R4).
+    class CommitsBroughtIn
+      #: (Array[String]) -> void
+      def initialize(commits)
+        @commits = commits
+        freeze
+      end
+
+      # The members, as list-member-problems lists them, whose newest changing commit the move brought in, in order.
+      #: (Array[Hash[String, untyped]]) -> Array[Hash[String, untyped]]
+      def changed_by(members)
+        members.select do |member|
+          newest = member.dig("history", "commits", 0, "commit")
+          newest && @commits.any? { |commit| commit.start_with?(newest) || newest.start_with?(commit) }
+        end
+      end
+    end
+  end
+end

data/lib/principles/models/commits_since_base.rb

@@ -0,0 +1,32 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # In git, what landed after a completed audit's base commit: for each member the audit changed, the commits
+    # since the base that touched it, and HEAD now. When HEAD differs from the base and none touched one, an empty
+    # list alone left the agent unsure why an answer on an older base was accepted, so it says so (#740).
+    class CommitsSinceBase
+      #: (base: String, head: String?, by_member: Hash[String, Array[Hash[String, String]]]) -> void
+      def initialize(base:, head:, by_member:)
+        @base = base
+        @head = head
+        @by_member = by_member
+        freeze
+      end
+
+      # The commits since the base that touched each member the audit changed, by member id.
+      #: Hash[String, Array[Hash[String, String]]]
+      attr_reader :by_member
+
+      # The base and HEAD, when HEAD differs from the base and no commit since the base touched a member the audit
+      # changed; nil otherwise.
+      #: () -> [String, String]?
+      def head_past_base
+        head = @head
+        [@base, head] unless head.nil? || head == @base || @by_member.values.any?(&:any?)
+      end
+    end
+  end
+end

data/lib/principles/models/correction_answer.rb

@@ -0,0 +1,66 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "../prose_list"
+require_relative "answer_fields"
+require_relative "disposition"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # An agent's answer to a correction request: one disposition for each finding the assessment raised, each
+    # checked as a Disposition, and no member changed that no fix claims. The block locates each piece of
+    # evidence, and where a finding is recorded, in the project. samples is the answer guide's disposition for
+    # each action, whose text no field may give back unchanged (#789).
+    class CorrectionAnswer
+      #: (untyped, Array[untyped], samples: Hash[String, untyped]) { (Locator) -> void } -> void
+      def initialize(response, findings, samples:, &locate)
+        @response = response
+        @samples = samples
+        @finding_ids = findings.map { |finding| finding.fetch("id") } #: Array[untyped]
+        @fields = AnswerFields.new(locate) #: AnswerFields
+      end
+
+      # The dispositions, once each is checked against changed, the members that changed since the audit began, as
+      # AuditStart#changed names them, those added included (T69).
+      #: (changed: Array[String]) -> Array[Disposition]
+      def dispositions(changed:)
+        dispositions = one_per_finding
+        unclaimed = changed - dispositions.flat_map { |disposition| disposition.claimed_members(changed) }
+        return dispositions if unclaimed.empty?
+
+        raise Error.new("unassessed_changes", "Other members changed: #{unclaimed.join(", ")}",
+                        "Start a fresh audit, or include their reassessment in a fixed disposition.")
+      end
+
+      private
+
+      #: () -> Array[Disposition]
+      def one_per_finding
+        given = @fields.array(@response["dispositions"], "dispositions")
+        dispositions = given.each_with_index.map do |disposition, index|
+          Disposition.new(disposition, @fields, at: "/dispositions/#{index}", samples: @samples)
+        end
+        unless dispositions.map(&:finding_id).sort == @finding_ids.sort
+          raise Error.new("incomplete_dispositions",
+                          "Dispose of each finding exactly once: #{@finding_ids.join(", ")}", "Complete dispositions.")
+        end
+
+        refuse_unfinished(dispositions)
+        dispositions
+      end
+
+      # Refuses every field the dispositions leave empty, as the template's placeholder or as the answer guide's
+      # sample in one refusal, so a copied template takes one repair, not one submit per field (#789, #791).
+      #: (Array[Disposition]) -> void
+      def refuse_unfinished(dispositions)
+        unfinished = dispositions.flat_map(&:unfinished)
+        return if unfinished.empty?
+
+        raise Error.new("invalid_disposition", "Still to write: #{ProseList.new(unfinished.map(&:to_s))}",
+                        unfinished.map(&:repair).uniq.join(" "), fields: unfinished.map(&:field))
+      end
+    end
+  end
+end

data/lib/principles/models/correction_basis.rb

@@ -0,0 +1,70 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "request_id"
+require_relative "decided_prior_findings"
+require_relative "audit_start"
+require_relative "last_completed_revision"
+require_relative "recorded_finding"
+
+module Principles
+  # The domain logic, which loads and saves itself through data/. models/CLAUDE.md owns the boundary.
+  module Models
+    # What a correction request depends on, which it prints as its basis and the agent hands back with the answer:
+    # the base commit, the map's version, each finding's members and problem, what the assessment reported beyond its
+    # findings, as AssessmentReport carries it for the completed record to keep, and the decisions on prior findings
+    # (D35), which travel to completion as those do. It also carries the last completed record's revision, so a
+    # correction is refused once that record changed (#646).
+    class CorrectionBasis
+      # The basis printed for a correction of findings, assessed from start: its base, its map's version and the
+      # assessment's report, as AssessmentReport carries it; revision is the last completed record's.
+      #: (AuditStart, findings: Array[untyped], revision: String?, ?prior: DecidedPriorFindings) -> CorrectionBasis
+      def self.printed(start, findings:, revision:, prior: DecidedPriorFindings::NONE)
+        basis = { "base_commit" => start.base, "map_version" => start.map_version,
+                  "last_completed_revision" => revision,
+                  "findings" => findings.map { |finding| finding.slice(*RecordedFinding::RAISED_FIELDS) } }
+        basis = basis.merge(start.reported.basis_fields)
+        new(prior.none? ? basis : basis.merge("prior_findings" => prior.to_h))
+      end
+
+      #: (untyped) -> void
+      def initialize(fields)
+        @fields = fields #: untyped
+        freeze
+      end
+
+      #: () -> untyped
+      def to_h = @fields
+
+      # The commit the audit it corrects began from, or nil outside git.
+      #: () -> String?
+      def base_commit = @fields.fetch("base_commit")
+
+      # The version of the map the audit it corrects began from.
+      #: () -> String
+      def map_version = @fields.fetch("map_version")
+
+      # The findings it asks the correction to dispose of, each with the fields RecordedFinding::RAISED_FIELDS names.
+      #: () -> Array[Hash[String, untyped]]
+      def findings = @fields.fetch("findings")
+
+      # The decisions on prior findings it carries to completion, or none (D35).
+      #: () -> DecidedPriorFindings
+      def prior_decided
+        decided = @fields["prior_findings"]
+        decided ? DecidedPriorFindings.new(decided) : DecidedPriorFindings::NONE
+      end
+
+      # The id of the correction request of principle_id for this basis, with each member's hash when the audit began.
+      #: (String, Hash[String, String]) -> RequestId
+      def request_id(principle_id, before)
+        RequestId.for(principle_id: principle_id, phase: "correction", parts: [@fields, before])
+      end
+
+      # The last completed record's revision when the request was printed, which refuses a correction once that
+      # record changed (#646).
+      #: () -> LastCompletedRevision
+      def printed_after = LastCompletedRevision.new(@fields["last_completed_revision"])
+    end
+  end
+end

data/lib/principles/models/dated_line.rb

@@ -0,0 +1,29 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # A line an answer gives that a record keeps under field, with field_since, the date it was first given, beside
+    # it: the same line keeps its date, a new line is dated afresh by the audit that records it, and null drops it
+    # (D52).
+    class DatedLine
+      # line is what the answer gave, nil for none; field is the name the record keeps it under.
+      #: (untyped, field: String) -> void
+      def initialize(line, field:)
+        @line = line
+        @field = field
+        freeze
+      end
+
+      # The line as the record keeps it, given had, the line and date it carried: had when the line is unchanged, so
+      # it keeps its date; this line alone, which the record's audited_at dates, when new; nothing when it is null.
+      #: (Hash[String, untyped]) -> Hash[String, untyped]
+      def kept_over(had)
+        return had if @line == had[@field]
+
+        @line.nil? ? {} : { @field => @line }
+      end
+    end
+  end
+end