principles 0.0.6 → 0.0.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (77) hide show
  1. checksums.yaml +4 -4
  2. data/lib/principles/cli.rb +9 -0
  3. data/lib/principles/command_line.rb +22 -5
  4. data/lib/principles/command_routes.rb +2 -2
  5. data/lib/principles/controllers/acknowledgement.rb +79 -102
  6. data/lib/principles/controllers/answer.rb +7 -6
  7. data/lib/principles/controllers/assessment.rb +13 -21
  8. data/lib/principles/controllers/audit.rb +24 -4
  9. data/lib/principles/controllers/audit_completion.rb +7 -3
  10. data/lib/principles/controllers/correction.rb +13 -6
  11. data/lib/principles/controllers/full_audit_request.rb +7 -2
  12. data/lib/principles/controllers/member_acknowledgement.rb +137 -0
  13. data/lib/principles/controllers/member_problems_report.rb +31 -23
  14. data/lib/principles/data/command-steps.json +9 -9
  15. data/lib/principles/data/schemas/acknowledgement-answer.schema.json +3 -2
  16. data/lib/principles/data/schemas/acknowledgements-answer.schema.json +88 -0
  17. data/lib/principles/data/schemas/assessment-answer.schema.json +15 -1
  18. data/lib/principles/data/schemas/command-steps.schema.json +1 -1
  19. data/lib/principles/data/schemas/correction-answer.schema.json +6 -54
  20. data/lib/principles/invocation_options.rb +5 -4
  21. data/lib/principles/list_open_findings_options.rb +23 -0
  22. data/lib/principles/models/acknowledged_check.rb +94 -0
  23. data/lib/principles/models/acknowledgement.rb +18 -36
  24. data/lib/principles/models/acknowledgement_left_as_printed.rb +25 -4
  25. data/lib/principles/models/acknowledgements.rb +99 -0
  26. data/lib/principles/models/answered_time.rb +9 -0
  27. data/lib/principles/models/assessment_report.rb +13 -13
  28. data/lib/principles/models/audit.rb +17 -4
  29. data/lib/principles/models/audit_record.rb +5 -0
  30. data/lib/principles/models/correction_basis.rb +14 -5
  31. data/lib/principles/models/list_member_problems_check.rb +80 -0
  32. data/lib/principles/models/listed_members.rb +49 -0
  33. data/lib/principles/models/loading_decision.rb +17 -8
  34. data/lib/principles/models/loads_to_check.rb +0 -1
  35. data/lib/principles/models/member_assessments.rb +11 -2
  36. data/lib/principles/models/member_problems.rb +9 -5
  37. data/lib/principles/models/member_sighting.rb +5 -8
  38. data/lib/principles/models/problem_report.rb +19 -4
  39. data/lib/principles/models/project.rb +5 -4
  40. data/lib/principles/models/reported_check.rb +14 -11
  41. data/lib/principles/models/request_id.rb +1 -1
  42. data/lib/principles/models/sent_answer.rb +29 -9
  43. data/lib/principles/positional_arguments.rb +3 -2
  44. data/lib/principles/session_start_options.rb +3 -3
  45. data/lib/principles/start_audit_options.rb +10 -2
  46. data/lib/principles/version.rb +2 -2
  47. data/lib/principles/views/acknowledgement_result.rb +46 -12
  48. data/lib/principles/views/assessed_members.rb +26 -5
  49. data/lib/principles/views/assessment_request.rb +22 -3
  50. data/lib/principles/views/audit_result.rb +9 -1
  51. data/lib/principles/views/check_result_template.rb +18 -17
  52. data/lib/principles/views/correction_request.rb +6 -9
  53. data/lib/principles/views/findings_result.rb +21 -0
  54. data/lib/principles/views/invocation.rb +19 -4
  55. data/lib/principles/views/loads_to_check_result.rb +3 -2
  56. data/lib/principles/views/member_row.rb +61 -0
  57. data/lib/principles/views/members_a_commit_changed.rb +2 -1
  58. data/lib/principles/views/members_with_no_baseline.rb +8 -1
  59. data/lib/principles/views/one_member_check_result_template.rb +21 -9
  60. data/lib/principles/views/open_findings_line.rb +2 -1
  61. data/lib/principles/views/problem_lines.rb +48 -45
  62. data/lib/principles/views/problem_result.rb +55 -26
  63. data/lib/principles/views/prompts/acknowledge-a-change/report-the-exit-status-its-own-listing-gives.md +3 -0
  64. data/lib/principles/views/prompts/acknowledge-a-change/say-whether-each-change-keeps-its-meaning.md +8 -0
  65. data/lib/principles/views/prompts/assess-every-member/decide-each-member-loading.md +2 -1
  66. data/lib/principles/views/prompts/assess-every-member/run-the-check-then-report-it.md +2 -2
  67. data/lib/principles/views/prompts/assess-every-member/run-the-reviewed-check-and-say-what-its-review-rested-on.md +5 -3
  68. data/lib/principles/views/prompts/learn-what-a-command-does/every-command-and-how-they-chain.md +1 -2
  69. data/lib/principles/views/prompts/learn-what-a-command-does/list-member-problems.md +15 -15
  70. data/lib/principles/views/prompts/learn-what-a-command-does/list-open-findings.md +65 -61
  71. data/lib/principles/views/prompts/learn-what-a-command-does/show-answer-check.md +7 -7
  72. data/lib/principles/views/prompts/learn-what-a-command-does/start-audit.md +8 -8
  73. data/lib/principles/views/prompts/learn-what-a-command-does/submit-answer.md +37 -37
  74. data/lib/principles/views/prompts/start-a-session/act-on-the-open-findings.md +1 -1
  75. data/lib/principles/views/prompts/start-a-session/every-loaded-line-costs-every-session.md +1 -0
  76. data/lib/principles/views/prompts/start-a-session/start-with-the-principles-skill.md +1 -0
  77. metadata +13 -1
@@ -0,0 +1,94 @@
1
+ # typed: strict
2
+ # frozen_string_literal: true
3
+
4
+ require_relative "../error"
5
+ require_relative "acknowledgement_refusal"
6
+ require_relative "answer_place"
7
+ require_relative "audit_record"
8
+ require_relative "listed_members"
9
+ require_relative "../prose_list"
10
+ require_relative "member"
11
+ require_relative "reported_check"
12
+
13
+ module Principles
14
+ # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
15
+ module Models
16
+ # The run of its member's check that a one-member audit's answer reports (D30, D33): checked against the check
17
+ # the record ran, carrying the line its last review rested on (D63), and accepted only once it passed, since a
18
+ # check that failed or could not run is a full audit's to judge (#1071).
19
+ class AcknowledgedCheck
20
+ # Where a one-member audit's answer gives its check_result, which a refusal of a field in it points into.
21
+ CHECK_RESULT = AnswerPlace.new("/check_result", "The acknowledgement") #: AnswerPlace
22
+
23
+ # record is the completed record the member is judged against. listed is what the member's check lists now,
24
+ # when it is this tool's own list-member-problems, which exits 3 while it lists the member (#1276).
25
+ #: (member: Member, principle_id: String, record: AuditRecord, ?listed: ListedMembers?) -> void
26
+ def initialize(member:, principle_id:, record:, listed: nil)
27
+ @member = member
28
+ @principle_id = principle_id
29
+ @record = record
30
+ @listed = listed
31
+ freeze
32
+ end
33
+
34
+ # The result the answer reports for the member's check, once it passed; nil for a member without a check,
35
+ # whose answer may report none.
36
+ #: (untyped) -> Hash[String, untyped]?
37
+ def result(answer)
38
+ check = @member.check
39
+ refuse("it has no check, so its answer reports no check_result") if !check && answer.key?("check_result")
40
+ return unless check
41
+
42
+ sent = answer["check_result"]
43
+ passed(ReportedCheck.new(AnswerPlace.new("", "The acknowledgement"), check,
44
+ ran: @record.check_run_for(@member.key), kept: @record.check_review_for(@member.key))
45
+ .result(reported(sent, check)), sent)
46
+ end
47
+
48
+ private
49
+
50
+ # result, once its check exited 0, or 3 for this tool's own list-member-problems while it lists only members
51
+ # this answer acknowledges, which it lists no more once the record is committed (#1276). It always gives an
52
+ # exit status, since the answer's schema refuses not_run_reason (#1115). sent is the check_result as given.
53
+ #: (Hash[String, untyped], Hash[String, untyped]) -> Hash[String, untyped]
54
+ def passed(result, sent)
55
+ status = result.fetch("exit_status")
56
+ command = result.fetch("command")
57
+ return result if status.zero? || (status == 3 && lists_only_the_acknowledged?(command, sent))
58
+
59
+ refuse("its check `#{command}` exited #{status}, so a full audit judges it")
60
+ end
61
+
62
+ # Whether the member's check is this tool's own list-member-problems and lists only members this answer
63
+ # acknowledges, refusing a listed_members that is not what it lists now, and a listing of another member,
64
+ # which it would still list once the record is committed (#1276).
65
+ #: (String, Hash[String, untyped]) -> bool
66
+ def lists_only_the_acknowledged?(command, sent)
67
+ listed = @listed or return false
68
+ misreported(command) unless listed.reported?(sent["listed_members"])
69
+ others = listed.unacknowledged
70
+ return true if others.empty?
71
+
72
+ refuse("its check `#{command}` exited 3 and lists #{ProseList.new(others)}, which this " \
73
+ "answer does not acknowledge, so a full audit judges it")
74
+ end
75
+
76
+ # Refuses a listed_members that is not what the member's own list-member-problems check lists now (#1276).
77
+ #: (String) -> bot
78
+ def misreported(command)
79
+ raise CHECK_RESULT.child("listed_members").refusal(
80
+ Error.new("invalid_answer", "check_result.listed_members is not what `#{command}` lists now",
81
+ "Run `#{command}` and give, under check_result.listed_members, the member id in the second " \
82
+ "column of each line it prints.")
83
+ )
84
+ end
85
+
86
+ # The check_result the answer reports, its command read as the request printed it when left out (#1166).
87
+ #: (untyped, String) -> untyped
88
+ def reported(sent, check) = sent.is_a?(Hash) ? { "command" => check, **sent.except("listed_members") } : sent
89
+
90
+ #: (String) -> bot
91
+ def refuse(why) = AcknowledgementRefusal.new(@member, @principle_id).refuse(why)
92
+ end
93
+ end
94
+ end
@@ -2,6 +2,7 @@
2
2
  # frozen_string_literal: true
3
3
 
4
4
  require_relative "../error"
5
+ require_relative "acknowledged_check"
5
6
  require_relative "acknowledgement_left_as_printed"
6
7
  require_relative "acknowledgement_refusal"
7
8
  require_relative "request_id"
@@ -11,7 +12,6 @@ require_relative "member_lines"
11
12
  require_relative "placement"
12
13
  require_relative "quoted_change"
13
14
  require_relative "reported_check"
14
- require_relative "answer_place"
15
15
  require_relative "template_placeholders"
16
16
 
17
17
  module Principles
@@ -34,7 +34,7 @@ module Principles
34
34
  ) #: TemplatePlaceholders
35
35
  # The text a checked member's template prints where its check's exit status goes, short since the request's
36
36
  # context says how to run the check (#1170).
37
- EXIT_STATUS_PLACEHOLDER = "the check's exit status, an integer" #: String
37
+ EXIT_STATUS_PLACEHOLDER = ReportedCheck::EXIT_STATUS_PLACEHOLDER #: String
38
38
  # The fields an answer may not send back as the template printed them, refused before its shape (#773, #1170).
39
39
  LEFT_AS_PRINTED = AcknowledgementLeftAsPrinted.new(
40
40
  PLACEHOLDERS, exit_status: EXIT_STATUS_PLACEHOLDER
@@ -128,30 +128,26 @@ module Principles
128
128
  # The record with this member's baseline moved to its text now, once the answer is checked against the
129
129
  # member's lines at the baseline commit and now. The change keeps the check run the answer reported, which the
130
130
  # member's check_result cannot show was this run when the last audit's passed with the same command (#1112).
131
- #: (untyped, MemberLines, at: String) -> AuditRecord
132
- def accepted(answer, lines, at:)
131
+ # into is the record the change is made to: the one this member is judged against, unless another member's
132
+ # acknowledgement in the same answer has already changed it. listed is what the member's check lists now, when
133
+ # it is this tool's own list-member-problems (#1276).
134
+ #: (untyped, MemberLines, at: String, ?into: AuditRecord?, ?listed: ListedMembers?) -> AuditRecord
135
+ def accepted(answer, lines, at:, into: nil, listed: nil)
133
136
  checked(answer, lines)
134
- result = check_result(answer)
137
+ result = check_result(answer, listed)
135
138
  run = result ? { "check_result" => result.slice("command", "exit_status") } : {}
136
- acknowledgeable.acknowledged(@member.key, { "from_sha256" => acknowledgeable.members.hash_for(@member.key),
137
- "to_sha256" => @now_sha256, "commit" => @base,
138
- "reason" => answer.fetch("reason"), "acknowledged_at" => at,
139
- **open_findings, **run }, check_result: result)
139
+ from = acknowledgeable.members.hash_for(@member.key)
140
+ (into || acknowledgeable).acknowledged(@member.key, { "from_sha256" => from, "to_sha256" => @now_sha256,
141
+ "commit" => @base, "reason" => answer.fetch("reason"),
142
+ "acknowledged_at" => at, **open_findings, **run },
143
+ check_result: result)
140
144
  end
141
145
 
142
- # The result the answer reports for the member's check, checked against the check the record ran and carrying
143
- # the line its last review rested on (D30, D63), once it passed: a check that failed or could not run is a full
144
- # audit's to judge (#1071). nil for a member without a check, whose answer may report none.
145
- #: (untyped) -> Hash[String, untyped]?
146
- def check_result(answer)
147
- check = @member.check
148
- refuse("it has no check, so its answer reports no check_result") if !check && answer.key?("check_result")
149
- return unless check
150
-
151
- record = acknowledgeable
152
- passed(ReportedCheck.new(AnswerPlace.new("", "The acknowledgement"), check,
153
- ran: record.check_run_for(@member.key), kept: record.check_review_for(@member.key))
154
- .result(reported_check(answer["check_result"], check)))
146
+ # The result the answer reports for the member's check, once it passed; nil for a member without a check.
147
+ #: (untyped, ?ListedMembers?) -> Hash[String, untyped]?
148
+ def check_result(answer, listed = nil)
149
+ AcknowledgedCheck.new(member: @member, principle_id: @principle_id, record: acknowledgeable, listed:)
150
+ .result(answer)
155
151
  end
156
152
 
157
153
  # The first line on each side of the change that the other lacks, which the request hints the quotes from.
@@ -160,20 +156,6 @@ module Principles
160
156
 
161
157
  private
162
158
 
163
- # result, once its check exited 0. It always gives an exit status, since the answer's schema refuses
164
- # not_run_reason (#1115).
165
- #: (Hash[String, untyped]) -> Hash[String, untyped]
166
- def passed(result)
167
- status = result.fetch("exit_status")
168
- return result if status.zero?
169
-
170
- refuse("its check `#{result.fetch("command")}` exited #{status}, so a full audit judges it")
171
- end
172
-
173
- # The check_result the answer reports, its command read as the request printed it when left out (#1166).
174
- #: (untyped, String) -> untyped
175
- def reported_check(reported, check) = reported.is_a?(Hash) ? { "command" => check, **reported } : reported
176
-
177
159
  # The change the answer quotes, between the member's lines at the baseline and now.
178
160
  #: (MemberLines) -> QuotedChange
179
161
  def quoted_change(lines) = QuotedChange.new(lines, member_id: @member.id)
@@ -1,6 +1,7 @@
1
1
  # typed: strict
2
2
  # frozen_string_literal: true
3
3
 
4
+ require_relative "acknowledgements"
4
5
  require_relative "left_as_printed"
5
6
  require_relative "refusal_before_shape"
6
7
  require_relative "template_placeholders"
@@ -18,24 +19,44 @@ module Principles
18
19
  # The field, named as a refusal names it, where a checked member's answer reports its exit status.
19
20
  EXIT_STATUS = "check_result.exit_status" #: String
20
21
 
21
- # judged holds the placeholders of the judgement's fields, exit_status the one printed where the status goes.
22
- #: (TemplatePlaceholders, exit_status: String) -> void
23
- def initialize(judged, exit_status:)
22
+ # judged holds the placeholders of the judgement's fields, exit_status the one printed where the status goes;
23
+ # with each_member, they are read in each entry of an answer to several members' members, keyed by member id
24
+ # (#1169), not in the answer itself.
25
+ #: (TemplatePlaceholders, exit_status: String, ?each_member: bool) -> void
26
+ def initialize(judged, exit_status:, each_member: false)
24
27
  @judged = judged
25
28
  @exit_status = exit_status
29
+ @each_member = each_member
26
30
  freeze
27
31
  end
28
32
 
33
+ # The same fields, read in each entry of an answer to several members (#1169).
34
+ #: () -> AcknowledgementLeftAsPrinted
35
+ def in_each_member = AcknowledgementLeftAsPrinted.new(@judged, exit_status: @exit_status, each_member: true)
36
+
29
37
  # @override
30
38
  #: (untyped, String, Array[Hash[String, String]]) -> void
31
39
  def refuse_in(answer, _source, shape_problems)
32
40
  return unless answer.is_a?(Hash)
33
41
 
34
- LeftAsPrinted.new(left_in(answer).to_h { [it, "/#{it.tr(".", "/")}"] }).refuse(besides: shape_problems)
42
+ LeftAsPrinted.new(pointers_in(answer)).refuse(besides: shape_problems)
35
43
  end
36
44
 
37
45
  private
38
46
 
47
+ # Each field left as printed, by name, beside its pointer: in the answer, or in each entry of its members.
48
+ #: (Hash[String, untyped]) -> Hash[String, String]
49
+ def pointers_in(answer)
50
+ return left_in(answer).to_h { [it, "/#{it.tr(".", "/")}"] } unless @each_member
51
+
52
+ members = answer["members"]
53
+ return {} unless members.is_a?(Hash)
54
+
55
+ members.select { |_id, entry| entry.is_a?(Hash) }.flat_map do |id, entry|
56
+ left_in(entry).map { ["#{id} #{it}", "#{Acknowledgements.entry_pointer(id)}/#{it.tr(".", "/")}"] }
57
+ end.to_h
58
+ end
59
+
39
60
  # Each field answer leaves as printed, by name.
40
61
  #: (Hash[String, untyped]) -> Array[String]
41
62
  def left_in(answer)
@@ -0,0 +1,99 @@
1
+ # typed: strict
2
+ # frozen_string_literal: true
3
+
4
+ require_relative "../error"
5
+ require_relative "audit_record"
6
+ require_relative "request_id"
7
+ require_relative "sent_answer"
8
+
9
+ module Principles
10
+ # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
11
+ module Models
12
+ # Several members of one principle acknowledged in one request and one answer (#1169): each member's entry is
13
+ # judged as its own one-member answer would be, and the answer is accepted for every member, in one record, or
14
+ # refused for all, so no baseline moves unless each does.
15
+ class Acknowledgements
16
+ PHASE = "acknowledgements"
17
+
18
+ # The JSON pointer to member_id's entry in an answer's members.
19
+ #: (String) -> String
20
+ def self.entry_pointer(member_id) = "/members/#{member_id.gsub("~", "~0").gsub("/", "~1")}"
21
+
22
+ # The members as members names them, each id beside its one-member request's id, in the order named; refused
23
+ # when one is named twice, which the answer would then judge once.
24
+ #: (principle_id: String, members: Array[[String, RequestId]]) -> Acknowledgements
25
+ def self.of(principle_id:, members:)
26
+ ids = members.map(&:first)
27
+ twice = ids.find { |id| ids.count(id) > 1 }
28
+ if twice
29
+ raise Error.new("invalid_answer", "#{SentAnswer::NAMED}'s basis names #{twice} twice", SentAnswer::REPAIR,
30
+ fields: [{ "pointer" => "/basis/member_ids", "problem" => "names #{twice} twice" }])
31
+ end
32
+
33
+ new(principle_id:, requests: members.to_h)
34
+ end
35
+
36
+ # requests holds each member's one-member request id under the member's id, in the order they were named.
37
+ #: (principle_id: String, requests: Hash[String, RequestId]) -> void
38
+ def initialize(principle_id:, requests:)
39
+ @principle_id = principle_id
40
+ @requests = requests
41
+ freeze
42
+ end
43
+
44
+ # The request's id: each member's one-member request id, sorted, so it depends on which members it asks
45
+ # about and on everything each of their requests depends on, not on the order they were named in.
46
+ #: () -> RequestId
47
+ def request_id
48
+ RequestId.for(principle_id: @principle_id, phase: PHASE, parts: @requests.values.map(&:to_s).sort)
49
+ end
50
+
51
+ # The record with every member's baseline moved, once the answer holds an entry for each member and no other:
52
+ # accept is given each member's id, its entry and the record the members before it changed, nil for the first,
53
+ # and gives the record with that member's acknowledgement in it too, or refuses the whole answer.
54
+ #: (untyped) { (String, untyped, AuditRecord?) -> AuditRecord } -> AuditRecord
55
+ def accepted(answer, &accept)
56
+ entries = answer.fetch("members")
57
+ refuse_unmatched(entries.keys)
58
+ ids = @requests.keys
59
+ first = ids.fetch(0)
60
+ ids.drop(1).reduce(in_entry(first) { accept.call(first, entries.fetch(first), nil) }) do |record, id|
61
+ in_entry(id) { accept.call(id, entries.fetch(id), record) }
62
+ end
63
+ end
64
+
65
+ private
66
+
67
+ # What the block gives for member_id's entry, a refusal of a field in it pointing at that field in the entry,
68
+ # since a member's acknowledgement points from the entry's root as an answer to one member does (#1276).
69
+ #: (String) { () -> AuditRecord } -> AuditRecord
70
+ def in_entry(member_id, &)
71
+ yield
72
+ rescue Error => e
73
+ fields = e.payload["fields"]
74
+ raise unless fields
75
+
76
+ entry = Acknowledgements.entry_pointer(member_id)
77
+ raise e.including("fields" => fields.map { it.merge("pointer" => entry + it.fetch("pointer")) })
78
+ end
79
+
80
+ # Refuses the answer whole unless its members hold an entry for each member its basis names, and for no other.
81
+ #: (Array[String]) -> void
82
+ def refuse_unmatched(answered)
83
+ missing = (@requests.keys - answered).map { problem(it, "is required, since basis.member_ids names it") }
84
+ extra = (answered - @requests.keys).map { problem(it, "is not a member basis.member_ids names") }
85
+ fields = missing + extra
86
+ return if fields.empty?
87
+
88
+ raise Error.new("invalid_answer", "#{SentAnswer::NAMED} does not answer each member it names, so no member " \
89
+ "is acknowledged", SentAnswer::REPAIR, fields:)
90
+ end
91
+
92
+ # The problem with the answer's entry for member_id, at its JSON pointer.
93
+ #: (String, String) -> Hash[String, String]
94
+ def problem(member_id, text)
95
+ { "pointer" => Acknowledgements.entry_pointer(member_id), "problem" => text }
96
+ end
97
+ end
98
+ end
99
+ end
@@ -48,6 +48,15 @@ module Principles
48
48
  nil
49
49
  end
50
50
 
51
+ # It in audited_at's form when it names a time to the second exactly, with any UTC offset, so a clock's own
52
+ # offset is the same instant (#1187); otherwise as given, a date alone included, for its sighting to refuse.
53
+ #: () -> untyped
54
+ def in_audited_at_form
55
+ return @value if date_alone?
56
+
57
+ exact_utc || @value
58
+ end
59
+
51
60
  # Whether it is later than time, both UTC times in audited_at's form: a sighting is made before the answer that
52
61
  # reports it (#699), so a repair never prints one later (#801).
53
62
  #: (String) -> bool
@@ -11,8 +11,8 @@ module Principles
11
11
  # What an assessment reported beyond its findings, which its audit's record and commit carry: by member id, the
12
12
  # fields of each member's record entry, such as its assessment (D49) and its check's result (D30), and the paths
13
13
  # its recent decision cites, which the record does not keep but the completed audit asks to commit when they
14
- # differ from HEAD (#860). A correction request carries it in its basis, so the completed audit keeps it; this is
15
- # the one owner of how it is carried.
14
+ # differ from HEAD (#860). The open record keeps it for the correction to read back, and the correction's basis
15
+ # carries only those paths and the record's digest (D87); this is the one owner of how it is carried.
16
16
  class AssessmentReport
17
17
  # The report of the answer assessed, each assessment it makes, rather than carries, with the grounds it was
18
18
  # judged on (D49).
@@ -25,12 +25,14 @@ module Principles
25
25
  new(fields, recent_decision_paths: assessed.recent_decision_paths)
26
26
  end
27
27
 
28
- # The report carried in a correction basis, under the ids of any members moves moved.
29
- #: (CorrectionBasis, MemberMoves) -> AssessmentReport
30
- def self.carried(basis, moves)
31
- fields = basis.to_h
32
- new(moves.hashes(fields.fetch("entry_fields", {})),
33
- recent_decision_paths: fields.fetch("recent_decision_paths", []))
28
+ # The report an open record keeps for its correction to read back: each member's entry without the hash and key
29
+ # the record adds, under the ids of any members moves moved, with the recent decision's paths, which the basis
30
+ # carries (D87). A completed record read back so gives the report that completed it, for an identical retry
31
+ # (D24).
32
+ #: (AuditRecord, CorrectionBasis, MemberMoves) -> AssessmentReport
33
+ def self.recorded(record, basis, moves)
34
+ fields = record.to_h.fetch("members").transform_values { |entry| entry.except("sha256", "key") }
35
+ new(moves.hashes(fields), recent_decision_paths: basis.to_h.fetch("recent_decision_paths", []))
34
36
  end
35
37
 
36
38
  # The paths the recent decision cites as evidence.
@@ -49,12 +51,10 @@ module Principles
49
51
  #: (String) -> Hash[String, untyped]
50
52
  def entry_fields_of(id) = @entry_fields.fetch(id, {})
51
53
 
52
- # The fields a correction basis carries it in, leaving out what it does not hold.
54
+ # What a correction basis carries of it: the recent decision's paths, which no record keeps, when there are any.
55
+ # The open record keeps the rest (D87).
53
56
  #: () -> Hash[String, untyped]
54
- def basis_fields
55
- { "entry_fields" => @entry_fields, "recent_decision_paths" => @recent_decision_paths }
56
- .reject { |_key, value| value.empty? }
57
- end
57
+ def basis_fields = @recent_decision_paths.empty? ? {} : { "recent_decision_paths" => @recent_decision_paths }
58
58
 
59
59
  NONE = new #: AssessmentReport
60
60
  end
@@ -101,10 +101,23 @@ module Principles
101
101
  end
102
102
 
103
103
  # What the audit a correction's basis names began from: its base commit, each member's hash then
104
- # (before), and the assessment's report the basis carries, under the ids of any moved members.
105
- #: (CorrectionBasis, Hash[String, String], MemberMoves) -> AuditStart
106
- def resumed(basis, before, moves)
107
- started(basis.base_commit, before, AssessmentReport.carried(basis, moves))
104
+ # (before), and the assessment's report record keeps, under the ids of any moved members (D87). The record is
105
+ # the open one the basis was printed with, or a completed one, which only an identical retry may complete
106
+ # again (D24); none, or another open one, refuses the correction as stale.
107
+ #: (CorrectionBasis, Hash[String, String], MemberMoves, AuditRecord?) -> AuditStart
108
+ def resumed(basis, before, moves, record)
109
+ raise stale_request unless record && (record.completed? || basis.printed_with?(record))
110
+
111
+ started(basis.base_commit, before, AssessmentReport.recorded(record, basis, moves))
112
+ end
113
+
114
+ # Refuses, as stale, a correction read back from a completed record, as resumed allows, unless completing it
115
+ # writes nothing: only an identical retry of the correction that completed it (D24) may read one, never an
116
+ # earlier audit's record that git restore put back in place of the open one (D87). An audit that read no record
117
+ # back, one completed from its assessment, gives none.
118
+ #: (AuditRecord?, Array[AuditRecord]) -> void
119
+ def confirm_read_back(record, changes)
120
+ raise stale_request if record&.completed? && !changes.empty?
108
121
  end
109
122
 
110
123
  # The map the audit began from: the current one when it is unchanged and the answer declares no change; or,
@@ -68,6 +68,11 @@ module Principles
68
68
  @fields.fetch("principle_id")
69
69
  end
70
70
 
71
+ # A digest of what the record says of each member, apart from when its assessment was made: an open record's
72
+ # assessment, which its correction's basis carries so the correction is refused once the record changed (D87).
73
+ #: () -> String
74
+ def assessment_digest = JsonDigest.new(members.undated).to_s
75
+
71
76
  # The hashes the audit began from, kept outside git only.
72
77
  #: () -> Hash[String, String]?
73
78
  def base_members
@@ -16,13 +16,16 @@ module Principles
16
16
  # (D35), which travel to completion as those do. It also carries the last completed record's revision, so a
17
17
  # correction is refused once that record changed (#646).
18
18
  class CorrectionBasis
19
- # The basis printed for a correction of findings, assessed from start: its base, its map's version and the
20
- # assessment's report, as AssessmentReport carries it; revision is the last completed record's.
21
- #: (AuditStart, findings: Array[untyped], revision: String?, ?prior: DecidedPriorFindings) -> CorrectionBasis
22
- def self.printed(start, findings:, revision:, prior: DecidedPriorFindings::NONE)
19
+ # The basis printed for a correction of findings, assessed from start: its base, its map's version, the digest of
20
+ # the assessment the open record keeps, and what else of the assessment's report AssessmentReport carries in a
21
+ # basis (D87); revision is the last completed record's.
22
+ #: (AuditStart, findings: Array[untyped], revision: String?, open_record: AuditRecord,
23
+ #| ?prior: DecidedPriorFindings) -> CorrectionBasis
24
+ def self.printed(start, findings:, revision:, open_record:, prior: DecidedPriorFindings::NONE)
23
25
  basis = { "base_commit" => start.base, "map_version" => start.map_version,
24
26
  "last_completed_revision" => revision,
25
- "findings" => findings.map { |finding| finding.slice(*RecordedFinding::RAISED_FIELDS) } }
27
+ "findings" => findings.map { |finding| finding.slice(*RecordedFinding::RAISED_FIELDS) },
28
+ "assessment_report_sha256" => open_record.assessment_digest }
26
29
  basis = basis.merge(start.reported.basis_fields)
27
30
  new(prior.none? ? basis : basis.merge("prior_findings" => prior.to_h))
28
31
  end
@@ -61,6 +64,12 @@ module Principles
61
64
  RequestId.handing_back(principle_id: principle_id, phase: "correction", handed: @fields, parts: [before])
62
65
  end
63
66
 
67
+ # Whether record is the open record this basis was printed with, its assessment unchanged since (D87).
68
+ #: (AuditRecord?) -> bool
69
+ def printed_with?(record)
70
+ !record.nil? && !record.completed? && record.assessment_digest == @fields["assessment_report_sha256"]
71
+ end
72
+
64
73
  # The last completed record's revision when the request was printed, which refuses a correction once that
65
74
  # record changed (#646).
66
75
  #: () -> LastCompletedRevision
@@ -0,0 +1,80 @@
1
+ # typed: strict
2
+ # frozen_string_literal: true
3
+
4
+ require "shellwords"
5
+ require_relative "listed_members"
6
+ require_relative "problem_report"
7
+
8
+ module Principles
9
+ # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
10
+ module Models
11
+ # A member's check that is this tool's own list-member-problems --short, which exits 3 while it lists the member
12
+ # itself, until the acknowledgement of its edit is committed (dogfooding D28b, #1276). Only a check whose words
13
+ # map exactly to that command's is one: any other check passes on exit 0 alone.
14
+ class ListMemberProblemsCheck
15
+ COMMAND = "list-member-problems"
16
+ SHORT = "--short"
17
+ # Characters a shell reads as more than one command's words, or as a redirection or substitution, which leave
18
+ # what ran no longer this command alone.
19
+ SHELL_CONTROL = /[;&|<>()`$]/
20
+ # The words that may run this tool before its executable, which is any path to `principles`.
21
+ RUNNERS = [[], ["ruby"], %w[bundle exec]].freeze #: Array[Array[String]]
22
+
23
+ # The check command reads as, or nil when its words do not map exactly to list-member-problems --short with at
24
+ # most one principle id, run as this tool by any path to it, with no word of shell control.
25
+ #: (String) -> ListMemberProblemsCheck?
26
+ def self.of(command)
27
+ ids = principle_ids(words_after_the_command(command))
28
+ new(ids.first) if ids
29
+ end
30
+
31
+ # The words after the command name, or nil unless command runs this tool alone.
32
+ #: (String) -> Array[String]?
33
+ def self.words_after_the_command(command)
34
+ words = Shellwords.split(command)
35
+ at = words.index(COMMAND)
36
+ words.drop(at + 1) if at && words.none? { SHELL_CONTROL.match?(it) } && this_tool?(words.take(at))
37
+ rescue ArgumentError
38
+ nil
39
+ end
40
+
41
+ # The principle ids the words after the command name give, at most one, or nil unless they are --short once and
42
+ # that id.
43
+ #: (Array[String]?) -> Array[String]?
44
+ def self.principle_ids(after)
45
+ return unless after
46
+
47
+ ids = after - [SHORT]
48
+ ids if after.count(SHORT) == 1 && ids.length <= 1 && ids.none? { it.start_with?("-") }
49
+ end
50
+
51
+ # Whether words run this tool: its executable last, after nothing or a runner.
52
+ #: (Array[String]) -> bool
53
+ def self.this_tool?(words)
54
+ *runner, executable = words
55
+ executable&.split("/")&.last == "principles" && RUNNERS.include?(runner)
56
+ end
57
+ private_class_method :words_after_the_command, :principle_ids, :this_tool?
58
+
59
+ # The principle whose map the check reads, or nil for every map.
60
+ #: String?
61
+ attr_reader :principle_id
62
+
63
+ #: (String?) -> void
64
+ def initialize(principle_id)
65
+ @principle_id = principle_id
66
+ freeze
67
+ end
68
+
69
+ # What the check lists in project now, read through the report the command prints from, over the same scope:
70
+ # each member, as its principle id and member id, and by principle the count of members no audit has assessed
71
+ # (#1254), beside the members acknowledging names of principle_id.
72
+ #: (Project, principle_id: String, acknowledging: Array[String]) -> ListedMembers
73
+ def listed(project, principle_id:, acknowledging:)
74
+ report = ProblemReport.for(project, @principle_id)
75
+ ListedMembers.new(listed: report.checked.fetch("members").map { it.values_at("principle", "id") },
76
+ principle_id:, acknowledging:, never_assessed: report.never_assessed)
77
+ end
78
+ end
79
+ end
80
+ end
@@ -0,0 +1,49 @@
1
+ # typed: strict
2
+ # frozen_string_literal: true
3
+
4
+ module Principles
5
+ # The domain logic, and the mediation of persistence. models/CLAUDE.md owns the boundary.
6
+ module Models
7
+ # The members a member's own list-member-problems check lists now, beside those one answer acknowledges: the check
8
+ # exits 3 until that answer's record is committed, and lists none then only if it acknowledges every one (#1276).
9
+ class ListedMembers
10
+ # listed is each member the check lists, as its principle id and member id; acknowledging is the ids of
11
+ # principle_id's members the answer acknowledges; never_assessed counts, by principle, the members no audit has
12
+ # assessed, which the check counts and no acknowledgement clears (#1254).
13
+ #: (listed: Array[[String, String]], principle_id: String, acknowledging: Array[String],
14
+ #| ?never_assessed: Hash[String, Integer]) -> void
15
+ def initialize(listed:, principle_id:, acknowledging:, never_assessed: {})
16
+ @listed = listed
17
+ @principle_id = principle_id
18
+ @acknowledging = acknowledging
19
+ @never_assessed = never_assessed
20
+ freeze
21
+ end
22
+
23
+ # Whether ids, as an answer reports them, are the ids of the members listed, each once, in any order.
24
+ #: (untyped) -> bool
25
+ def reported?(ids) = ids.is_a?(Array) ? ids.sort == @listed.map(&:last).sort : false
26
+
27
+ # The members listed that the answer does not acknowledge, which the check would still list: each by its id,
28
+ # with its principle when that is another, since an id is unique only within its map; then each principle's
29
+ # members no audit has assessed, by count.
30
+ #: () -> Array[String]
31
+ def unacknowledged
32
+ listed = @listed.filter_map do |principle, id|
33
+ next "#{id} of #{principle}" unless principle == @principle_id
34
+
35
+ id unless @acknowledging.include?(id)
36
+ end
37
+ listed + @never_assessed.map { |principle, count| never_assessed(principle, count) }
38
+ end
39
+
40
+ private
41
+
42
+ # count members of principle no audit has assessed, as a refusal names them.
43
+ #: (String, Integer) -> String
44
+ def never_assessed(principle, count)
45
+ "#{count} member#{"s" unless count == 1} of #{principle} no audit has assessed"
46
+ end
47
+ end
48
+ end
49
+ end