kibi-core 0.23.0 → 0.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-core",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "private": false,
   "description": "Core Prolog modules and RDF graph logic for Kibi",
   "type": "module",

package/schema/entities.pl

@@ -56,6 +56,9 @@ entity_property(req, exempts_claims, list).
 % Absent reads as default.
 entity_property(req, firmness, atom).
 entity_property(adr, firmness, atom).
+% The weakest evidence level a current requirement accepts: proved, tested,
+% asserted or unverified. Absent: tested when firm, otherwise unverified.
+entity_property(req, required_evidence, atom).
 % Intended outcome of a scenario: success, rejection or error.
 entity_property(scenario, expects, atom).
 
@@ -69,6 +72,8 @@ entity_property(fact, value_string, string).
 entity_property(fact, value_int, integer).
 entity_property(fact, value_number, number).
 entity_property(fact, value_bool, boolean).
+% The exact members of a set fact (value_type set).
+entity_property(fact, value_set, list).
 entity_property(fact, unit, string).
 entity_property(fact, scope, string).
 entity_property(fact, polarity, atom).
@@ -150,6 +155,7 @@ optional_property(req, rationale).
 optional_property(req, exempts_claims).
 optional_property(req, firmness).
 optional_property(adr, firmness).
+optional_property(req, required_evidence).
 optional_property(test, verification_scope).
 optional_property(test, verification_perspective).
 optional_property(test, proof_contract).

package/schema/validation.pl

@@ -108,6 +108,7 @@ is_fact_only_field(value_string).
 is_fact_only_field(value_int).
 is_fact_only_field(value_number).
 is_fact_only_field(value_bool).
+is_fact_only_field(value_set).
 is_fact_only_field(unit).
 is_fact_only_field(scope).
 is_fact_only_field(polarity).
@@ -227,7 +228,7 @@ text_atom(Value, Atom) :- string(Value), atom_string(Atom, Value).
 valid_operator(Op) :- memberchk(Op, [eq, neq, lt, lte, gt, gte]), !.
 
 % valid_value_type(+VT)
-valid_value_type(ValueType) :- memberchk(ValueType, [string, int, number, bool]), !.
+valid_value_type(ValueType) :- memberchk(ValueType, [string, int, number, bool, set]), !.
 
 % valid_polarity_in_props(+Props)
 % Validates polarity if present; succeeds if no polarity in props
@@ -299,6 +300,7 @@ is_value_field(value_string).
 is_value_field(value_int).
 is_value_field(value_number).
 is_value_field(value_bool).
+is_value_field(value_set).
 
 % value_type_matches_field(+ValueType, +Props)
 % Ensures that value_type matches the actual value field present
@@ -306,6 +308,7 @@ value_type_matches_field(string, Props) :- memberchk(value_string=_, Props), !.
 value_type_matches_field(int, Props) :- memberchk(value_int=_, Props), !.
 value_type_matches_field(number, Props) :- memberchk(value_number=_, Props), !.
 value_type_matches_field(bool, Props) :- memberchk(value_bool=_, Props), !.
+value_type_matches_field(set, Props) :- memberchk(value_set=_, Props), !.
 
 % valid_origin_in_props(+Props)
 % Entity provenance travels as a JSON object string (or a dict). When present

package/src/certificate_check.pl

@@ -38,6 +38,7 @@
     certificate_rule_edges/1,
     certificate_member_holds/3,
     certificate_members_satisfiable/2,
+    set_texts/2,
     verify_certificates/2,
     kb_verify_certificates_file/2
 ]).
@@ -148,7 +149,7 @@ kind_is(Certificate, Kind) :-
 % Every comparable context: context(Subject, Property, Scope, Domain, Members)
 % or unresolved(Subject, Property, Scope, Reason).  A member is
 % m(FactId, Op, Value, ValidFrom, ValidTo) with the operator already negated
-% for a forbid fact; Domain is int, number, bool or string.
+% for a forbid fact; Domain is int, number, bool, string or set.
 certificate_property_contexts(Contexts) :-
     findall(Fact-tuple(Subject, Property, Op, Type, Value, Unit, Scope, Polarity, From, To),
         (   kb:current_req(Req),
@@ -202,6 +203,8 @@ context_domain(Members, Domain, Reason) :-
     ->  Domain = bool, context_scalar_reason(Members, Reason)
     ;   Types == [string]
     ->  Domain = string, context_scalar_reason(Members, Reason)
+    ;   Types == [set]
+    ->  Domain = set, context_scalar_reason(Members, Reason)
     ;   Types = [_, _|_]
     ->  Domain = none, Reason = "the facts use different value types"
     ;   Domain = none, Reason = "the value type is not supported"
@@ -247,6 +250,22 @@ certificate_member_holds(Domain, m(_, Op, Bound, _, _), Value) :-
     ;   Op == neq -> ValueText \== BoundText
     ).
 
+% A set value is the exact set of allowed values: eq holds for the same
+% members in any order, neq for any other set.
+certificate_member_holds(set, m(_, Op, Bound, _, _), Value) :-
+    set_texts(Value, ValueTexts),
+    set_texts(Bound, BoundTexts),
+    (   Op == eq -> ValueTexts == BoundTexts
+    ;   Op == neq -> ValueTexts \== BoundTexts
+    ).
+
+%% set_texts(+Value, -Texts)
+% The sorted, unique member texts of a set value.
+set_texts(Value, Texts) :-
+    is_list(Value),
+    maplist(text_of, Value, Texts0),
+    sort(Texts0, Texts).
+
 numeric_domain(int).
 numeric_domain(number).
 
@@ -282,6 +301,14 @@ scalar_candidates(string, Members, Candidates) :-
     atomic_list_concat(["kibi:fresh"|Texts], '|', FreshAtom),
     atom_string(FreshAtom, Fresh),
     append(Texts, [Fresh], Candidates).
+scalar_candidates(set, Members, Candidates) :-
+    findall(Texts, (member(m(_, _, Bound, _, _), Members), set_texts(Bound, Texts)), Sets0),
+    sort(Sets0, Sets),
+    findall(Text, (member(Set, Sets), member(Text, Set)), Texts0),
+    sort(Texts0, Texts),
+    atomic_list_concat(["kibi:fresh"|Texts], '|', FreshAtom),
+    atom_string(FreshAtom, Fresh),
+    append(Sets, [[Fresh]], Candidates).
 
 property_theorem(Contexts, Numbered, Theorem, Used, Rejected) :-
     findall(Index-Certificate,

package/src/certificates.pl

@@ -27,7 +27,8 @@
     certificate_decision_groups/1,
     certificate_rule_edges/1,
     certificate_member_holds/3,
-    certificate_members_satisfiable/2
+    certificate_members_satisfiable/2,
+    set_texts/2
 ]).
 
 %% kb_write_certificates(+Path, -JsonString)
@@ -121,6 +122,13 @@ model_candidates(string, Members, Candidates) :-
     fresh_text(Bounds, 0, Fresh),
     append(Bounds, [Fresh], Candidates).
 
+model_candidates(set, Members, Candidates) :-
+    findall(Set, (member(m(_, _, Bound, _, _), Members), set_texts(Bound, Set)), Sets0),
+    sort(Sets0, Sets),
+    findall(Text, (member(Set, Sets), member(Text, Set)), Texts),
+    fresh_text(Texts, 0, Fresh),
+    append(Sets, [[Fresh]], Candidates).
+
 fresh_text(Bounds, Index, Fresh) :-
     format(string(Candidate), "kibi:model:~w", [Index]),
     (   member(Bound, Bounds), text_value(Bound, Candidate)

package/src/checks.pl

@@ -2377,7 +2377,7 @@ property_value_shape_error(Props, "Property value fact missing required field: o
 property_value_shape_error(Props, "Property value fact missing required field: value_type") :-
     memberchk(operator=_, Props),
     \+ memberchk(value_type=_, Props).
-property_value_shape_error(Props, "Property value fact missing value field (value_string, value_int, value_number, or value_bool)") :-
+property_value_shape_error(Props, "Property value fact missing value field (value_string, value_int, value_number, value_bool, or value_set)") :-
     memberchk(value_type=_, Props),
     \+ has_value_field(Props).
 property_value_shape_error(Props, "Property value fact has multiple value fields (should have exactly one)") :-
@@ -2394,17 +2394,20 @@ is_value_field(value_string).
 is_value_field(value_int).
 is_value_field(value_number).
 is_value_field(value_bool).
+is_value_field(value_set).
 
 has_value_field(Props) :- memberchk(value_string=_, Props), !.
 has_value_field(Props) :- memberchk(value_int=_, Props), !.
 has_value_field(Props) :- memberchk(value_number=_, Props), !.
 has_value_field(Props) :- memberchk(value_bool=_, Props), !.
+has_value_field(Props) :- memberchk(value_set=_, Props), !.
 
 % value_type_matches_field(+ValueType, +Props)
 value_type_matches_field(string, Props) :- memberchk(value_string=_, Props), !.
 value_type_matches_field(int, Props) :- memberchk(value_int=_, Props), !.
 value_type_matches_field(number, Props) :- memberchk(value_number=_, Props), !.
 value_type_matches_field(bool, Props) :- memberchk(value_bool=_, Props), !.
+value_type_matches_field(set, Props) :- memberchk(value_set=_, Props), !.
 
 predicate_schema_shape_error(Props, "Predicate schema fact missing required field: predicate_name") :-
     \+ memberchk(predicate_name=_, Props).

package/src/claim_obligations.pl

@@ -0,0 +1,378 @@
+% Module: claim_obligations
+% implements REQ-kibi-claim-bound-proofs
+%
+% What a certificate has to establish for it to prove one requirement claim.
+% A claim is grounded by exactly one typed fact; the obligation is derived
+% from that fact, so a certificate proves the claim's own content instead of
+% a label its test chose:
+%
+%   set fact (value_type set, or the legacy allowed_values string "a|b|c")
+%       exhaustive, typecheck  the domain is exactly the fact's set
+%   numeric fact (value_type int or number, a comparison operator)
+%       arithmetic, smt        the certificate's claim is the fact's constraint
+%                              (negated for polarity forbid)
+%
+% Any other pairing that appears in the table with a different proof kind is
+% incompatible (a set fact under arithmetic, a numeric fact under
+% exhaustive).  A fact kind with no derivation at all (boolean placeholders,
+% predicates, rules, other strings) can only be attested: the test author
+% says the certificate expresses the claim, and Kibi never counts that as
+% proved.
+
+:- module(claim_obligations, [
+    claim_obligation/3,
+    fact_obligation/3,
+    obligation_equal/2,
+    proof_contract_claim_candidates_json/1,
+    proof_contract_claim_issues_json/1,
+    test_claim_obligations_json/4
+]).
+
+:- use_module(library(http/json)).
+:- use_module(library(apply)).
+:- use_module(library(lists)).
+:- use_module('kb.pl').
+
+%% fact_obligation(+FactId, +ProofKind, -Result)
+% Result is obligation(Dict), attested, or incompatible(Reason).
+fact_obligation(FactId, ProofKind, Result) :-
+    (   fact_set(FactId, Members)
+    ->  (   memberchk(ProofKind, [exhaustive, typecheck])
+        ->  Result = obligation(_{kind: "set_equals", members: Members})
+        ;   format(string(Reason),
+                   "~w is a set fact, which an ~w certificate cannot express (use exhaustive or typecheck)",
+                   [FactId, ProofKind]),
+            Result = incompatible(Reason)
+        )
+    ;   fact_numeric_constraint(FactId, Variable, ValueType, Operator, Value)
+    ->  (   memberchk(ProofKind, [arithmetic, smt])
+        ->  Result = obligation(_{kind: "numeric_constraint", variable: Variable,
+                                  value_type: ValueType, operator: Operator, value: Value})
+        ;   (   ProofKind == typecheck -> Article = a ; Article = an ),
+            format(string(Reason),
+                   "~w is a numeric fact, which ~w ~w certificate cannot express (use arithmetic or smt)",
+                   [FactId, Article, ProofKind]),
+            Result = incompatible(Reason)
+        )
+    ;   Result = attested
+    ).
+
+%% claim_obligation(+ReqId, +ClaimKey, +ProofKind, -Result)
+% As fact_obligation/3 for the fact grounding ClaimKey in ReqId, with the
+% fact id: obligation(FactId, Dict), attested(FactId), incompatible(FactId,
+% Reason), or unresolved(Reason) when the claim cannot be named by a proof.
+claim_obligation(ReqId-ClaimKey, ProofKind, Result) :-
+    (   \+ requirement_claim_status(ReqId, ClaimKey, _)
+    ->  format(string(Reason), "~w is not a claim of ~w", [ClaimKey, ReqId]),
+        Result = unresolved(Reason)
+    ;   requirement_claim_status(ReqId, ClaimKey, nonlogical)
+    ->  format(string(Reason),
+               "claim ~w of ~w is nonlogical: a nonlogical span is context, not a claim to prove",
+               [ClaimKey, ReqId]),
+        Result = unresolved(Reason)
+    ;   requirement_claim_status(ReqId, ClaimKey, Status),
+        Status \== modeled
+    ->  format(string(Reason), "claim ~w of ~w is ~w; resolve it before proving it",
+               [ClaimKey, ReqId, Status]),
+        Result = unresolved(Reason)
+    ;   \+ claim_fact(ReqId, ClaimKey, _)
+    ->  format(string(Reason), "claim ~w of ~w has no grounding fact", [ClaimKey, ReqId]),
+        Result = unresolved(Reason)
+    ;   claim_fact(ReqId, ClaimKey, FactId),
+        fact_obligation(FactId, ProofKind, FactResult),
+        (   FactResult = obligation(Dict)
+        ->  Result = obligation(FactId, Dict)
+        ;   FactResult == attested
+        ->  Result = attested(FactId)
+        ;   FactResult = incompatible(Reason)
+        ->  Result = incompatible(FactId, Reason)
+        )
+    ).
+
+%% obligation_equal(+Left, +Right)
+% Two obligations (dicts, possibly read back from a receipt) ask the same.
+obligation_equal(Left, Right) :-
+    obligation_key(Left, Key),
+    obligation_key(Right, Key).
+
+obligation_key(Obligation, set(Members)) :-
+    dict_text(Obligation, kind, "set_equals"),
+    get_dict(members, Obligation, Raw),
+    is_list(Raw),
+    maplist(text_string, Raw, Strings),
+    sort(Strings, Members),
+    !.
+obligation_key(Obligation, numeric(Variable, Type, Operator, Value)) :-
+    dict_text(Obligation, kind, "numeric_constraint"),
+    dict_text(Obligation, variable, Variable),
+    dict_text(Obligation, value_type, Type),
+    dict_text(Obligation, operator, Operator),
+    get_dict(value, Obligation, Raw),
+    number_value(Raw, Value).
+
+dict_text(Dict, Key, String) :-
+    is_dict(Dict),
+    get_dict(Key, Dict, Raw),
+    text_string(Raw, String).
+
+number_value(Raw, Value) :- number(Raw), !, Value is Raw * 1.0.
+number_value(Raw, Value) :-
+    text_string(Raw, String),
+    number_string(Number, String),
+    Value is Number * 1.0.
+
+text_string(Raw, String) :- string(Raw), !, String = Raw.
+text_string(Raw, String) :- atom(Raw), !, atom_string(Raw, String).
+text_string(Raw, String) :- number(Raw), !, number_string(Raw, String).
+text_string(^^(Raw, _), String) :- !, text_string(Raw, String).
+
+% The members of a set fact, sorted and unique.
+fact_set(FactId, Members) :-
+    kb_entity(FactId, fact, Props),
+    prop_atom(Props, fact_kind, property_value),
+    (   prop_atom(Props, value_type, set)
+    ->  memberchk(value_set=Raw, Props),
+        kb:normalize_term_atom_list(Raw, Atoms)
+    ;   prop_atom(Props, property_key, allowed_values),
+        \+ (memberchk(value_type=RawType, Props),
+            kb:normalize_term_atom(RawType, Type),
+            Type \== string),
+        memberchk(value_string=RawValue, Props),
+        kb:unwrap_rdf_value(RawValue, Value),
+        text_string(Value, Joined),
+        split_string(Joined, "|", " ", Parts),
+        exclude(==(""), Parts, NonEmpty),
+        maplist([S, A]>>atom_string(A, S), NonEmpty, Atoms)
+    ),
+    (   prop_atom(Props, operator, Operator) -> Operator == eq ; true ),
+    \+ prop_atom(Props, polarity, forbid),
+    maplist([A, S]>>atom_string(A, S), Atoms, Strings),
+    sort(Strings, Members),
+    Members \== [].
+
+% A numeric property_value fact as one constraint on its property, negated
+% for polarity forbid (forbid gt 5 means the value must be at most 5).
+fact_numeric_constraint(FactId, Variable, ValueType, Operator, Value) :-
+    kb:fact_property_tuple(FactId, _Subject, Property, Op0, Type0, Raw, _Unit, _Scope, Polarity),
+    memberchk(Type0-ValueType, [int-"int", number-"real"]),
+    memberchk(Op0, [eq, neq, lt, lte, gt, gte]),
+    number_value(Raw, Float),
+    (   ValueType == "int", Float =:= truncate(Float)
+    ->  Value is truncate(Float)
+    ;   Value = Float
+    ),
+    (   Polarity == forbid
+    ->  negated_operator(Op0, Op)
+    ;   Op = Op0
+    ),
+    atom_string(Op, Operator),
+    atom_string(Property, Variable).
+
+negated_operator(eq, neq).
+negated_operator(neq, eq).
+negated_operator(lt, gte).
+negated_operator(lte, gt).
+negated_operator(gt, lte).
+negated_operator(gte, lt).
+
+prop_atom(Props, Key, Atom) :-
+    memberchk(Key=Raw, Props),
+    kb:normalize_term_atom(Raw, Atom).
+
+% The status of a claim in the requirement's semantic inventory.
+% With ClaimKey unbound it enumerates the claims; the first entry for a key
+% wins.
+requirement_claim_status(ReqId, ClaimKey, Status) :-
+    nonvar(ClaimKey),
+    !,
+    once(inventory_claim_status(ReqId, ClaimKey, Status0)),
+    Status = Status0.
+requirement_claim_status(ReqId, ClaimKey, Status) :-
+    findall(Key-S, inventory_claim_status(ReqId, Key, S), Pairs),
+    first_per_key(Pairs, [], Unique),
+    member(ClaimKey-Status, Unique).
+
+first_per_key([], Acc, Unique) :- reverse(Acc, Unique).
+first_per_key([Key-S|Rest], Acc, Unique) :-
+    (   memberchk(Key-_, Acc)
+    ->  first_per_key(Rest, Acc, Unique)
+    ;   first_per_key(Rest, [Key-S|Acc], Unique)
+    ).
+
+inventory_claim_status(ReqId, ClaimKey, Status) :-
+    kb_entity(ReqId, req, Props),
+    memberchk(semantic_inventory=Raw, Props),
+    inventory_list(Raw, Entries),
+    member(Entry, Entries),
+    entry_field(Entry, claim_key, RawKey),
+    kb:normalize_term_atom(RawKey, ClaimKey),
+    entry_field(Entry, status, RawStatus),
+    kb:normalize_term_atom(RawStatus, Status).
+
+inventory_list(Raw, Entries) :- is_list(Raw), !, Entries = Raw.
+inventory_list(^^(Raw, _), Entries) :- !, inventory_list(Raw, Entries).
+inventory_list(Raw, Entries) :-
+    (   string(Raw) ; atom(Raw) ),
+    catch(atom_json_dict(Raw, Parsed, [value_string_as(string)]), _, fail),
+    is_list(Parsed),
+    !,
+    Entries = Parsed.
+inventory_list(Raw, Entries) :-
+    (   string(Raw) ; atom(Raw) ),
+    catch(term_string(Parsed, Raw), _, fail),
+    is_list(Parsed),
+    !,
+    Entries = Parsed.
+inventory_list(_, []).
+
+entry_field(Entry, Key, Value) :-
+    is_dict(Entry), !,
+    get_dict(Key, Entry, Value).
+entry_field(Entry, Key, Value) :-
+    is_list(Entry),
+    memberchk(Key=Value, Entry).
+
+% The fact grounding a claim: the same claim_key, linked from the
+% requirement through requires_property, requires_predicate or requires_rule.
+claim_fact(ReqId, ClaimKey, FactId) :-
+    member(Relation, [requires_property, requires_predicate, requires_rule]),
+    kb_relationship(Relation, ReqId, FactId),
+    kb_entity(FactId, fact, Props),
+    prop_atom(Props, claim_key, ClaimKey),
+    !.
+
+% Current requirements a test reaches through the scenarios it verifies.
+test_requirement(TestId, ReqId) :-
+    (   kb_relationship(validates, TestId, ScenarioId)
+    ;   kb_relationship(verified_by, ScenarioId, TestId)
+    ),
+    kb_relationship(specified_by, ReqId, ScenarioId),
+    kb:current_req(ReqId).
+
+%% test_claim_obligations_json(+TestId, +ClaimKeysJson, +ProofKind, -Json)
+% For `kibi prove`: one row per claim key and requirement the test reaches,
+% {claim_key, requirement_id, fact_id?, result, obligation?, reason?}, with
+% result obligation, attested, incompatible or unresolved.  A key no reached
+% requirement declares gives one unresolved row without requirement_id.
+test_claim_obligations_json(TestId0, KeysJson, Kind0, Json) :-
+    kb:normalize_term_atom(TestId0, TestId),
+    kb:normalize_term_atom(Kind0, Kind),
+    atom_json_term(KeysJson, Keys0, []),
+    maplist([K, A]>>(text_string(K, S), atom_string(A, S)), Keys0, Keys),
+    findall(ReqId, test_requirement(TestId, ReqId), ReqIds0),
+    sort(ReqIds0, ReqIds),
+    foldl(key_rows(Kind, ReqIds), Keys, [], RowsRev),
+    reverse(RowsRev, Rows),
+    with_output_to(string(Json), json_write_dict(current_output, Rows, [width(0)])).
+
+key_rows(Kind, ReqIds, Key, Acc0, Acc) :-
+    findall(ReqId,
+        (member(ReqId, ReqIds), requirement_claim_status(ReqId, Key, _)),
+        Owners),
+    atom_string(Key, KeyString),
+    (   Owners == []
+    ->  format(string(Reason),
+               "claim ~w is not a claim of any current requirement this test reaches through its scenarios",
+               [Key]),
+        Acc = [_{claim_key: KeyString, result: "unresolved", reason: Reason}|Acc0]
+    ;   foldl(owner_row(Kind, Key, KeyString), Owners, Acc0, Acc)
+    ).
+
+owner_row(Kind, Key, KeyString, ReqId, Acc0, [Row|Acc0]) :-
+    atom_string(ReqId, ReqString),
+    claim_obligation(ReqId-Key, Kind, Result),
+    Base = _{claim_key: KeyString, requirement_id: ReqString},
+    (   Result = obligation(FactId, Obligation)
+    ->  atom_string(FactId, FactString),
+        Row = Base.put(_{result: "obligation", fact_id: FactString, obligation: Obligation})
+    ;   Result = attested(FactId)
+    ->  atom_string(FactId, FactString),
+        Row = Base.put(_{result: "attested", fact_id: FactString})
+    ;   Result = incompatible(FactId, Reason)
+    ->  atom_string(FactId, FactString),
+        Row = Base.put(_{result: "incompatible", fact_id: FactString, reason: Reason})
+    ;   Result = unresolved(Reason),
+        Row = Base.put(_{result: "unresolved", reason: Reason})
+    ).
+
+%% proof_contract_claim_issues_json(-Json)
+% For the proof-contract-claims rule: one row {test_id, claim_key?, reason}
+% per certificate-kind proof contract that names no claims in proves, and
+% per claim key it names that no certificate of its kind could prove
+% (not a modeled claim of a reached requirement, no grounding fact, or a
+% fact the kind cannot express).  An attested claim is not an issue here:
+% it is reported as attested, and never counts as proved.
+proof_contract_claim_issues_json(Json) :-
+    findall(Row, proof_contract_claim_issue(Row), Rows0),
+    sort(Rows0, Rows),
+    with_output_to(string(Json), json_write_dict(current_output, Rows, [width(0)])).
+
+certificate_kind(exhaustive).
+certificate_kind(typecheck).
+certificate_kind(arithmetic).
+certificate_kind(smt).
+
+test_certificate_contract(TestId, Kind, Contract) :-
+    kb_entity(TestId, test, Props),
+    memberchk(proof_contract=Raw, Props),
+    contract_dict(Raw, Contract),
+    get_dict(kind, Contract, RawKind),
+    text_string(RawKind, KindString),
+    atom_string(Kind, KindString),
+    certificate_kind(Kind).
+
+contract_dict(^^(Raw, _), Dict) :- !, contract_dict(Raw, Dict).
+contract_dict(Dict, Dict) :- is_dict(Dict), !.
+contract_dict(Raw, Dict) :-
+    (   atom(Raw) ; string(Raw) ),
+    catch(atom_json_dict(Raw, Dict, [value_string_as(string)]), _, fail),
+    is_dict(Dict).
+
+proof_contract_claim_issue(_{test_id: TestString, reason: Reason}) :-
+    test_certificate_contract(TestId, Kind, Contract),
+    \+ ( get_dict(proves, Contract, Proves), is_list(Proves), Proves \== [] ),
+    atom_string(TestId, TestString),
+    format(string(Reason),
+           "the ~w proof contract names no claims in proves, so its certificate proves nothing about a requirement",
+           [Kind]).
+proof_contract_claim_issue(_{test_id: TestString, claim_key: KeyString, reason: Reason}) :-
+    test_certificate_contract(TestId, Kind, Contract),
+    get_dict(proves, Contract, Proves),
+    is_list(Proves),
+    Proves \== [],
+    atom_json_term(KeysJson, Proves, []),
+    test_claim_obligations_json(TestId, KeysJson, Kind, RowsJson),
+    atom_json_dict(RowsJson, Rows, [value_string_as(string)]),
+    member(Row, Rows),
+    get_dict(result, Row, Result),
+    memberchk(Result, ["unresolved", "incompatible"]),
+    atom_string(TestId, TestString),
+    get_dict(claim_key, Row, KeyString),
+    get_dict(reason, Row, Reason).
+
+%% proof_contract_claim_candidates_json(-Json)
+% For the schema 12 migration: one row {test_id, kind, candidates} per
+% certificate-kind proof contract without proves, where candidates are the
+% claims {claim_key, requirement_id, fact_id} of current requirements the
+% test reaches whose grounding fact derives an obligation for its kind.  The
+% migration pins proves only when exactly one claim is a candidate.
+proof_contract_claim_candidates_json(Json) :-
+    findall(Row, proof_contract_claim_candidates(Row), Rows0),
+    sort(Rows0, Rows),
+    with_output_to(string(Json), json_write_dict(current_output, Rows, [width(0)])).
+
+proof_contract_claim_candidates(_{test_id: TestString, kind: KindString, candidates: Candidates}) :-
+    test_certificate_contract(TestId, Kind, Contract),
+    \+ ( get_dict(proves, Contract, Proves), is_list(Proves), Proves \== [] ),
+    findall(_{claim_key: KeyString, requirement_id: ReqString, fact_id: FactString},
+        (   test_requirement(TestId, ReqId),
+            requirement_claim_status(ReqId, ClaimKey, modeled),
+            claim_obligation(ReqId-ClaimKey, Kind, obligation(FactId, _)),
+            atom_string(ClaimKey, KeyString),
+            atom_string(ReqId, ReqString),
+            atom_string(FactId, FactString)
+        ),
+        Candidates0),
+    sort(Candidates0, Candidates),
+    atom_string(TestId, TestString),
+    atom_string(Kind, KindString).