principles 0.0.1

data/lib/principles/models/member_sighting.rb

@@ -0,0 +1,176 @@
+# typed: strict
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require_relative "../error"
+require_relative "answer_place"
+require_relative "answer_text"
+require_relative "answered_time"
+require_relative "carried_assessments"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # One member assessment's sighting: whether its delivery was observed, what was seen, and when, as the last full
+    # audit's sighting of the member bears on it (#680, #716). Its delivery picks its kind: Observed, or NotObserved.
+    class MemberSighting
+      # The sighting of assessment, one of the answer's member_assessments at the place at, of the kind its
+      # delivery names; carried knows the last full audit's sightings, and answered_at is when the answer came. A
+      # delivery other than observed or not_observed is refused here, before the evidence, as the refusals have always
+      # come.
+      #: (Hash[String, untyped], carried: CarriedAssessments?, answered_at: String, at: AnswerPlace) -> MemberSighting
+      def self.for(assessment, carried:, answered_at:, at:)
+        case assessment["delivery"]
+        when "observed" then Observed.new(assessment, carried: carried, answered_at: answered_at, at: at)
+        when "not_observed" then NotObserved.new(assessment, at: at)
+        else raise Error.new("invalid_delivery", "Use observed or not_observed",
+                             "Record unavailable delivery as not_observed.")
+        end
+      end
+
+      #: (Hash[String, untyped], at: AnswerPlace) -> void
+      def initialize(assessment, at:)
+        @assessment = assessment
+        @at = at
+      end
+
+      # Refuses the sighting unless it holds to its kind's rules.
+      #: () -> void
+      def check = raise(NotImplementedError, "#{self.class} has no rules of its own")
+
+      private
+
+      #: () -> untyped
+      def id = @assessment["member_id"]
+
+      # The JSON pointer to field of this assessment.
+      #: (String) -> String
+      def pointer(field) = @at.child(field).pointer
+
+      # A delivery not observed has no sighting, so it gives no observed_at (#680).
+      class NotObserved < MemberSighting
+        #: (Hash[String, untyped], at: AnswerPlace) -> void
+        def initialize(assessment, at:)
+          super
+          freeze
+        end
+
+        #: () -> void
+        def check
+          return unless @assessment.key?("observed_at")
+
+          raise Error.new("invalid_answer", "Member #{id} is not observed but gives observed_at",
+                          "Drop observed_at, or record delivery as observed with what you saw in observation.",
+                          fields: [{ "pointer" => pointer("observed_at"),
+                                     "problem" => "only an observed delivery has a sighting to date" }])
+        end
+      end
+
+      # An observed delivery says what was seen, and when, as a time the record can compare, and no word-for-word
+      # repeat of the last full audit's but as that sighting or one in this audit.
+      class Observed < MemberSighting
+        SHAPE_EXAMPLE = "2026-11-01T09:30:00Z" #: String
+        # A record that gives only its date gives it at midnight UTC, the observation saying the time is unknown (#785).
+        DATE_ALONE_EXAMPLE = "2026-11-01T00:00:00Z" #: String
+        OR_NULL_FOR_THIS_AUDIT = "or null for a sighting in this audit." #: String
+        # The repair for an observed_at naming no UTC time exactly, which shows the form to follow.
+        FORM_REPAIR = %(Give "observed_at" like "#{SHAPE_EXAMPLE}", in UTC, #{OR_NULL_FOR_THIS_AUDIT} If the ) +
+                      "record gives only a date, give it at 00:00:00Z, such as #{DATE_ALONE_EXAMPLE}, and say in " \
+                      "observation that the time is unknown." #: String
+
+        # answered_at is when the answer reporting it came, a UTC time like audited_at, no later than the audit it
+        # completes is dated.
+        #: (Hash[String, untyped], carried: CarriedAssessments?, answered_at: String, at: AnswerPlace) -> void
+        def initialize(assessment, carried:, answered_at:, at:)
+          super(assessment, at: at)
+          @carried = carried
+          @answered_at = answered_at
+          freeze
+        end
+
+        #: () -> void
+        def check
+          refuse_missing_observation
+          refuse_unshaped_observed_at
+          refuse_observed_after_answer
+          refuse_repeated_observation
+        end
+
+        private
+
+        # An observed delivery needs what was seen (D29: a rule across fields stays in the model).
+        #: () -> void
+        def refuse_missing_observation
+          return if AnswerText.new(@assessment["observation"]).written?
+
+          raise Error.new("invalid_answer", "Member #{id} is observed but has no observation",
+                          "Give observation: what you saw the member do, where you saw it, and what you did not see; " \
+                          "if you did not see it act, record delivery as not_observed.",
+                          fields: [{ "pointer" => pointer("observation"), "problem" => "must be a nonempty string" }])
+        end
+
+        # An observed_at is a UTC time in audited_at's form, as the record dates every other sighting, to compare; a
+        # date alone, an offset or fractional seconds cannot, nor a time no calendar has (#699). Null or none is this
+        # audit's.
+        #: () -> void
+        def refuse_unshaped_observed_at
+          observed_at = @assessment["observed_at"]
+          return if observed_at.nil? || AnsweredTime.new(observed_at).utc?
+
+          raise Error.new("invalid_answer",
+                          "Member #{id}'s observed_at #{observed_at.to_json} is not a UTC time like audited_at",
+                          shape_repair(AnsweredTime.new(observed_at)),
+                          fields: [{ "pointer" => pointer("observed_at"),
+                                     "problem" => "must be a UTC time like #{SHAPE_EXAMPLE}" }])
+        end
+
+        # The repair for an observed_at not in audited_at's form: the value it names exactly, to copy, when that is no
+        # later than the answer, which would refuse it in turn; otherwise the form, and how to date a date alone (#801).
+        #: (AnsweredTime) -> String
+        def shape_repair(given)
+          exact = given.exact_utc
+          return FORM_REPAIR if exact.nil? || AnsweredTime.new(exact).after?(@answered_at)
+          unless given.date_alone?
+            return %(Give "observed_at" as "#{exact}", the same time in UTC, #{OR_NULL_FOR_THIS_AUDIT})
+          end
+
+          %(Give "observed_at" as "#{exact}", that date at 00:00:00Z, and say in observation that the time is ) +
+            "unknown, #{OR_NULL_FOR_THIS_AUDIT}"
+        end
+
+        # A sighting is made before the answer that reports it, so its observed_at is no later than answered_at
+        # (#699). Checked once its form is, so the two compare as times.
+        #: () -> void
+        def refuse_observed_after_answer
+          observed_at = @assessment["observed_at"]
+          return if observed_at.nil? || !AnsweredTime.new(observed_at).after?(@answered_at)
+
+          raise Error.new("invalid_answer", "Member #{id}'s observed_at, #{observed_at}, is after this answer",
+                          %(Give "observed_at" as when you saw it, no later than #{@answered_at}, ) +
+                          OR_NULL_FOR_THIS_AUDIT,
+                          fields: [{ "pointer" => pointer("observed_at"),
+                                     "problem" => "must not be after this answer, #{@answered_at}" }])
+        end
+
+        # A fresh observation that repeats the last full audit's word for word describes that audit's sighting or one
+        # made in this audit; only the agent knows which, so it gives the recorded date or null, copied from the repair
+        # so it never types a clock time (#680, #716). Any other date is another sighting, described in its own words.
+        #: () -> void
+        def refuse_repeated_observation
+          seen = @carried&.repeated_sighting(id, @assessment["observation"]) or return
+          return if @assessment.key?("observed_at") && [seen, nil].include?(@assessment["observed_at"])
+
+          raise Error.new("observation_repeats_last_audit",
+                          "#{id}'s observation repeats the last full audit's word for word, a sighting dated #{seen}",
+                          %(Give "observed_at": "#{seen}" if you kept that sighting. If you saw the member again, ) +
+                          "describe what you saw this time in your own words, with \"observed_at\": null for a " \
+                          "sighting in this audit, or the date of another, such as a dated record.",
+                          fields: [{ "pointer" => pointer("observed_at"),
+                                     "problem" => "must be the last full audit's date or null when observation " \
+                                                  "repeats its text" }])
+        end
+      end
+    end
+  end
+end

data/lib/principles/models/member_snapshots.rb

@@ -0,0 +1,36 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "audited_member_lines"
+require_relative "located_text"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # Each of a map's members by id, where it is in its file now and the hash of what it says there, as
+    # Project#snapshots located them all.
+    class MemberSnapshots
+      #: (Hash[String, Hash[String, untyped]]) -> void
+      def initialize(by_id)
+        @by_id = by_id.freeze #: Hash[String, Hash[String, untyped]]
+        freeze
+      end
+
+      # Each member's snapshot by id.
+      #: () -> Hash[String, Hash[String, untyped]]
+      def to_h = @by_id
+
+      # Where the member id is in its file now, and the hash of what it says there.
+      #: (String) -> LocatedText
+      def of(id) = LocatedText.of(@by_id.fetch(id))
+
+      # Each member's id and the hash of its text now.
+      #: () -> Hash[String, String]
+      def hashes = @by_id.transform_values { |snapshot| snapshot.fetch("sha256") }
+
+      # The lines the members span now, against which another principle's evidence is said to share them (D64).
+      #: () -> AuditedMemberLines
+      def audited_lines = AuditedMemberLines.new(@by_id.transform_values { LocatedText.of(it) })
+    end
+  end
+end

data/lib/principles/models/member_state.rb

@@ -0,0 +1,35 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # One member by its id, with its state now as list-member-problems reports it, which a completed audit names for
+    # another principle sharing a file its fixes changed (#410, #823).
+    class MemberState
+      # The states that mean a member's reference is broken, so an audit would refuse it. unreadable_map is a map's
+      # state, which MemberProblems#broken reads over its entries; no MemberState holds it, since a map that cannot be
+      # read has no members to name.
+      BROKEN = %w[locator_lost unavailable unreadable_map].freeze #: Array[String]
+
+      #: (String, String) -> void
+      def initialize(id, state)
+        @id = id
+        @state = state
+        freeze
+      end
+
+      # Whether its own text changed or its reference broke, so the principle it belongs to needs auditing again.
+      #: () -> bool
+      def changed_or_broken? = @state == "changed" || broken?
+
+      # Whether its reference is broken, so an audit would refuse it.
+      #: () -> bool
+      def broken? = BROKEN.include?(@state)
+
+      # The member as printed: its id and state.
+      #: () -> Hash[String, String]
+      def to_h = { "id" => @id, "state" => @state }
+    end
+  end
+end

data/lib/principles/models/members_elsewhere.rb

@@ -0,0 +1,46 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "member_elsewhere"
+require_relative "open_finding"
+
+module Principles
+  # The domain logic, which loads and saves itself through data/. models/CLAUDE.md owns the boundary.
+  module Models
+    # The members of other principles' maps sharing a line with one located member, as MembersSharingLines finds
+    # them: what each result prints of them under mapped_elsewhere, and whether the agent should check the text
+    # where their lines meet (#756, #776).
+    class MembersElsewhere
+      #: (Array[MemberElsewhere]) -> void
+      def initialize(members)
+        @members = members
+        freeze
+      end
+
+      # Each as add-member, show-principle and a full audit's request print it under mapped_elsewhere.
+      #: () -> Array[Hash[String, untyped]]
+      def shown = @members.map(&:to_h)
+
+      # Whether one of them holds the located member's lines, or lies within them, without either being a whole file.
+      #: () -> bool
+      def text_check_needed? = @members.any?(&:text_check_needed?)
+
+      # The principles whose maps hold them, each once.
+      #: () -> Array[String]
+      def principle_ids = @members.map(&:principle_id).uniq
+
+      # Each as a full audit's request prints it, naming the findings left_open_by_principle gives its principle that
+      # name it (#772, D62).
+      #: (Hash[String, Array[OpenFinding]]) -> Array[Hash[String, untyped]]
+      def naming(left_open_by_principle)
+        @members.map { |member| member.naming(left_open_by_principle.fetch(member.principle_id, [])) }
+      end
+
+      # The findings left_open_by_principle gives their principles that name any of them.
+      #: (Hash[String, Array[OpenFinding]]) -> Array[OpenFinding]
+      def open_among(left_open_by_principle)
+        @members.flat_map { |member| member.open_among(left_open_by_principle.fetch(member.principle_id, [])) }
+      end
+    end
+  end
+end

data/lib/principles/models/members_sharing_lines.rb

@@ -0,0 +1,116 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "line_span"
+require_relative "located_text"
+require_relative "member"
+require_relative "member_elsewhere"
+require_relative "members_elsewhere"
+
+module Principles
+  # The domain logic, which loads and saves itself through data/. models/CLAUDE.md owns the boundary.
+  module Models
+    # The members whose text shares a line with one member located in its file, so one edit there shows on
+    # each. The project locates the others; a member this tool cannot find now is left out, since show-principle
+    # reports it.
+    class MembersSharingLines
+      # The members sharing a line with member, located where it is now; refuses as Project#locate does when it
+      # cannot be found.
+      #: (Project, Member) -> MembersSharingLines
+      def self.of(project, member)
+        new(project, project.located_text(member.locator), id: member.id, whole_file: member.whole_file?)
+      end
+
+      # located is the text found for one member, its path and lines, id is that member's id, and whole_file whether
+      # it is its whole file.
+      #: (Project, LocatedText, id: String, ?whole_file: bool) -> void
+      def initialize(project, located, id:, whole_file: false)
+        @project = project
+        @located = located
+        @span = located.span(whole_file:) #: LineSpan
+        @id = id
+        freeze
+      end
+
+      # The ids of members of its own map whose text shares a line with the located member, which is not among
+      # them. A member of another map may have the same id and is another member, so elsewhere keeps it.
+      #: (Array[Member]) -> Array[String]
+      def ids_in(members)
+        sharing(others(members)).map { |member, _found| member.id }
+      end
+
+      # The ids of members whose text spans exactly the located member's first and last lines, so the agent sees
+      # it may be mapping the same lines twice (#442). Equal lines are not equal text: a passage can end within
+      # its last line.
+      #: (Array[Member]) -> Array[String]
+      def same_lines_ids_in(members)
+        sharing(others(members)).filter_map { |member, found| member.id if same_lines?(found) }
+      end
+
+      # The members sharing a line with the located one, beside map, its own: those in map, those of them on exactly
+      # its lines, and those in the other maps, as plain values, with whether the agent should check the text where
+      # one of those holds the other's lines without being a whole file (#756).
+      #: (MemberMap)
+      #|  -> { overlaps: Array[String], same_lines_as: Array[String], mapped_elsewhere: Array[Hash[String, untyped]],
+      #|       text_check: bool }
+      def facts_beside(map)
+        others = elsewhere(except: map.id)
+        members = map.members.to_a
+        { overlaps: ids_in(members), same_lines_as: same_lines_ids_in(members),
+          mapped_elsewhere: others.shown, text_check: others.text_check_needed? }
+      end
+
+      # Each member of a map other than except whose text shares a line with the located member, with its map, its
+      # role there and its lines, so the agent sees that one edit changes both, checks the roles fit (#383) and how
+      # much of the located member it holds, which no other part of the page shows (#610): same_lines when it spans
+      # exactly the located member's lines (#442), spans_these_lines when its lines include all of them, and
+      # within_these_lines when they include all of its, so the agent can tell which member an edit reaches (#718). A
+      # partial overlap is marked neither way. A map that cannot be read is left out; list-member-problems
+      # reports it.
+      #: (except: String) -> MembersElsewhere
+      def elsewhere(except:)
+        maps = @project.member_maps
+        MembersElsewhere.new((maps.ids - [except]).flat_map { |id| sharing_in(maps, id) })
+      end
+
+      private
+
+      # The members of map id sharing a line with the located member, or none when that map cannot be read.
+      #: (MemberMaps, String) -> Array[MemberElsewhere]
+      def sharing_in(maps, id)
+        sharing(maps.find(id).members.to_a).map do |member, found|
+          MemberElsewhere.new(principle_id: id, member:, span: found.span(whole_file: member.whole_file?),
+                              located: @span)
+        end
+      rescue Error
+        []
+      end
+
+      # Each member that shares a line with the located member, with where it is found now: in the same file, by
+      # its own path or through a symbolic link (#695).
+      #: (Array[Member]) -> Array[[Member, LocatedText]]
+      def sharing(members)
+        members.filter_map do |member|
+          next unless @project.same_file?(member.path, @located.path)
+
+          found = @project.located_text(member.locator)
+          [member, found] if found.span.shares_a_line_with?(@span)
+        rescue Error
+          nil
+        end
+      end
+
+      # The members of its own map but the located one.
+      #: (Array[Member]) -> Array[Member]
+      def others(members)
+        members.reject { |member| member.id == @id }
+      end
+
+      #: (LocatedText) -> bool
+      def same_lines?(found)
+        found.span.same_lines_as?(@span)
+      end
+    end
+  end
+end

data/lib/principles/models/meta_principle.rb

@@ -0,0 +1,51 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "activation"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The principle that keeps every other principle held, which setting principles up maps first (D67, D68). It is
+    # this product's own principle, not an example, so what its map starts with ships with the tool; once mapped, the
+    # project owns the map like any other.
+    module MetaPrinciple
+      ID = "sticking-to-your-principles"
+
+      DESCRIPTION = "Every other principle stays held: each place that carries one is mapped, a change to any of " \
+                    "them is judged against the rest before work goes on, and the agent loads only the guidance its " \
+                    "task needs, so harness drift and debt stay visible and an agent can be trusted with longer, " \
+                    "wider unsupervised work."
+
+      # Its work is in hand in every session, since it brings the other principles back into attention.
+      ACTIVATION = Activation.new({ "when" => "always" }) #: Activation
+
+      # The heading of the passage this tool proposes, which the add-member command it prints names as the section.
+      PASSAGE_HEADING = "Stick to your principles"
+
+      # The part the passage plays as the principle's first member. It carries no check: a command stored in the
+      # committed map runs on every machine that reads it, where principles may not be installed or may run from
+      # another path (D71).
+      PASSAGE_ROLE = "States the practice of keeping every principle held, in every session"
+
+      # The part a passage the project already has plays when it carries one of the passage's steps in its place,
+      # so the step is said once (#895, #911).
+      STEP_ROLE = "Says, for this project, one of the keeping steps"
+
+      # The part any other place that keeps the principles held plays as a member, such as a timer or the committed
+      # setting that enables the plugin: the agent replaces STEP with the keeping step it runs and TRIGGER with what
+      # starts it, a hook, a timer or a reader (D75).
+      KEEPING_PLACE_ROLE = "Runs STEP, started by TRIGGER"
+
+      # The repair line that sets this principle up, for a refusal of its id before its map exists: setup writes no
+      # map, and the add-member it prints creates the map with its first member (T74).
+      SET_UP = "To set it up: #{Error::EXECUTABLE} show-meta-principle-passage".freeze #: String
+
+      # The fields this principle's map starts with as setup starts it, with no members; the add-member setup prints
+      # writes the map with its first member (T74).
+      #: () -> Hash[String, untyped]
+      def self.starting_fields = { "description" => DESCRIPTION, "members" => [], "activation" => ACTIVATION.to_h }
+    end
+  end
+end

data/lib/principles/models/missing_files.rb

@@ -0,0 +1,85 @@
+# typed: strict
+# frozen_string_literal: true
+
+require_relative "../error"
+require_relative "project_history"
+
+module Principles
+  # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
+  module Models
+    # The files that broken members name but that cannot be read, each with the members it held, so one rename
+    # reads as one new path to find (#273). Each member still takes its own move: whether every one of them
+    # landed in the same place is the agent's judgement. Beside a path, git_detected_rename gives any rename git
+    # detects for it, which the agent checks before using (#276).
+    class MissingFiles
+      # How to read a git_detected_rename, wherever this tool gives one beside a missing file.
+      RENAME_MATCH = "check before you use it: its similarity is git's percentage of the old file found in the " \
+                     "new one, and 50 is git's default cut-off for calling it a rename."
+      # What a broken_members repair says of missing_files, so each refusal says it the same way.
+      REPAIR = "missing_files groups the members of each file that cannot be read: a renamed file usually takes " \
+               "one new path for all of them. git_detected_rename, when given, is git's match for that path, to " \
+               "#{RENAME_MATCH}".freeze #: String
+      # broken holds each broken member's entry: its "id", any "principle", and its refusal's "code" and "path".
+      #: (Array[Hash[String, untyped]], ?principle: String?, ?history: ProjectHistory?) -> void
+      def initialize(broken, principle: nil, history: nil)
+        @broken = broken
+        @principle = principle
+        @history = history
+        freeze
+      end
+
+      # The broken members, each whose file is missing with a repair that points to its missing_files entry, so
+      # a reader of the member alone sees any rename git detected (#285).
+      #: () -> Array[Hash[String, untyped]]
+      def members
+        @broken.map do |entry|
+          next entry unless missing?(entry)
+
+          entry.merge("repair" => "Its file, #{entry.fetch("path")}, is missing: see that path in missing_files, " \
+                                  "with any rename git detected, then run a command from repair_with.")
+        end
+      end
+
+      # The broken_members refusal for these members, saying how to repair each. note comes before what
+      # missing_files says, and rerun names what to run once they are repaired.
+      # rerun is the command to run once the members are repaired, or nil when it is the one the agent ran.
+      #: (String, ?rerun: String?, ?note: String) -> Error
+      def refusal(message, rerun: nil, note: "")
+        Error.new("broken_members", message,
+                  "For each member listed, say whether it moved or is gone, and run the matching command in its " \
+                  "repair_with: the move-member, with its NEW_PATH, HEADING or QUERY filled in, if it moved, or the " \
+                  "remove-member if it is gone. #{note}#{REPAIR}" \
+                  "#{rerun ? "\nThen run it again: #{rerun}" : " Then run the command again."}")
+             .including(**({ "principle" => @principle } if @principle), "members" => members, "missing_files" => to_a)
+      end
+
+      # Each missing path, in the order first named, with the members that name it.
+      #: () -> Array[Hash[String, untyped]]
+      def to_a
+        missing = @broken.select { |entry| missing?(entry) }
+        missing.group_by { |entry| entry.fetch("path") }.map do |path, entries|
+          { "path" => path, "members" => entries.map { |entry| named(entry) } }.merge(renamed(path))
+        end
+      end
+
+      private
+
+      #: (Hash[String, untyped]) -> bool
+      def missing?(entry)
+        entry["code"] == "unreadable_file" && !entry["path"].nil?
+      end
+
+      # git_detected_rename for path, when git detects one.
+      #: (String) -> Hash[String, untyped]
+      def renamed(path)
+        rename = @history&.rename_of(path)
+        rename ? { "git_detected_rename" => rename } : {}
+      end
+
+      #: (Hash[String, untyped]) -> Hash[String, String]
+      def named(entry)
+        { "principle" => entry["principle"] || @principle, "id" => entry["id"] }.compact
+      end
+    end
+  end
+end

data/lib/principles/models/misspelt_member_id.rb

@@ -0,0 +1,45 @@
+# typed: strict
+# frozen_string_literal: true
+
+module Principles
+  # The domain logic, which loads and saves itself through data/. models/CLAUDE.md owns the boundary.
+  module Models
+    # A member id an answer named that the map does not hold. A member id copies its heading exactly, so
+    # an agent typing it may use a straight apostrophe for a curly one, a hyphen for a dash, or other
+    # case and spacing (alpha 011 friction 12). This finds the mapped id it differs from only so, to name
+    # in the refusal; this tool never accepts the misspelt id itself.
+    class MisspeltMemberId
+      APOSTROPHES = /[‘’‚‛′ʼ`´]/
+      QUOTES = /[“”„‟″]/
+      DASHES = /[‐-―−]/
+
+      #: (String) -> void
+      def initialize(id)
+        @id = id
+        freeze
+      end
+
+      # The one mapped id spelled like this one apart from punctuation, case and spacing, or nil.
+      #: (Array[String]) -> String?
+      def closest(mapped)
+        matches = mapped.select { |each| loose(each) == loose(@id) }
+        matches.first if matches.one?
+      end
+
+      # What a refusal says of this id: that it is not mapped, and the mapped id it is spelled like; nil when none.
+      #: (Array[String]) -> String?
+      def hint(mapped)
+        closest = closest(mapped) or return nil
+        "#{@id} is not mapped; did you mean #{closest}?"
+      end
+
+      private
+
+      #: (String) -> String
+      def loose(text)
+        text.unicode_normalize(:nfkc).gsub(APOSTROPHES, "'").gsub(QUOTES, '"').gsub(DASHES, "-")
+            .downcase.split.join(" ")
+      end
+    end
+  end
+end