kibi-core 0.22.4 → 0.23.0

package/src/kb_consistency.pl

@@ -0,0 +1,213 @@
+% Module: kb_consistency
+% implements REQ-kibi-kb-certificates
+% The kb-consistency check rules.  Each run produces the certificate bundle
+% (certificates.pl), round-trips it through JSON exactly as a saved bundle
+% would be read, and re-checks it with the independent checker
+% (certificate_check.pl).  Only what the checker accepts becomes a finding:
+%
+%   kb-consistency             a re-verified contradiction (an irreducible
+%                              core of property facts, two facts that
+%                              disagree on an atom or a decision, or a
+%                              negation cycle among stored rules), or a
+%                              certificate the checker rejects
+%   kb-consistency-unresolved  a context the checker cannot compare (mixed
+%                              types or units, unsupported operators or
+%                              polarities, windows that never overlap)
+:- module(kb_consistency, [
+    check_kb_consistency/1,
+    check_kb_consistency_unresolved/1
+]).
+
+:- encoding(utf8).
+
+:- use_module(library(apply)).
+:- use_module(library(lists)).
+:- use_module(library(http/json)).
+:- use_module('kb.pl', [kb_entity/3, kb_relationship/3]).
+:- use_module('certificates.pl', [kb_certificates/1]).
+:- use_module('certificate_check.pl', [verify_certificates/2]).
+
+%% check_kb_consistency(-Violations)
+check_kb_consistency(Violations) :-
+    consistency_verification(Bundle, Report),
+    numbered_certificates(Bundle, Numbered),
+    findall(Index, (member(Failure, Report.rejected), get_dict(certificate, Failure, Index)), Rejected),
+    findall(Violation,
+        (   member(Index-Certificate, Numbered),
+            \+ memberchk(Index, Rejected),
+            contradiction_violation(Certificate, Violation)
+        ),
+        Contradictions),
+    findall(Violation,
+        (   member(Failure, Report.rejected),
+            rejected_violation(Failure, Violation)
+        ),
+        RejectedViolations),
+    append(Contradictions, RejectedViolations, Unsorted),
+    sort(Unsorted, Violations).
+
+%% check_kb_consistency_unresolved(-Violations)
+check_kb_consistency_unresolved(Violations) :-
+    consistency_verification(_Bundle, Report),
+    findall(Violation,
+        (   member(Theorem, Report.theorems),
+            get_dict(unresolved, Theorem, Entries),
+            member(Entry, Entries),
+            unresolved_violation(Theorem.theorem, Entry, Violation)
+        ),
+        Unsorted),
+    sort(Unsorted, Violations).
+
+consistency_verification(Bundle, Report) :-
+    kb_certificates(Produced),
+    with_output_to(string(Json), json_write_dict(current_output, Produced, [width(0)])),
+    open_string(Json, Stream),
+    json_read_dict(Stream, Bundle, [value_string_as(string)]),
+    verify_certificates(Bundle, Report).
+
+numbered_certificates(Bundle, Numbered) :-
+    findall(Index-Certificate, nth1(Index, Bundle.certificates, Certificate), Numbered).
+
+% ------------------------------------------------------------------
+% Re-verified contradictions
+% ------------------------------------------------------------------
+
+contradiction_violation(Certificate, violation('kb-consistency', EntityId, Description, Suggestion, "", _{certificate: Certificate})) :-
+    get_dict(kind, Certificate, KindText),
+    atom_string(Kind, KindText),
+    contradiction_text(Kind, Certificate, Facts, Description),
+    fact_requirements(Facts, Requirements),
+    entity_label(Requirements, Facts, EntityId),
+    suggestion_text(Kind, Requirements, Suggestion).
+
+contradiction_text(property_contradiction, Certificate, Facts, Description) :-
+    Facts = Certificate.core,
+    context_text(Certificate, Context),
+    atomic_list_concat(Facts, ', ', FactText),
+    findall(Text,
+        (   member(Drop, Certificate.dropModels),
+            format(string(Text), "~w: ~w", [Drop.factId, Drop.value])
+        ),
+        DropTexts),
+    atomic_list_concat(DropTexts, ', ', DropText),
+    format(string(Description),
+        "Facts ~w cannot all hold for ~w: no value satisfies them together, and dropping any one leaves a value (~w)",
+        [FactText, Context, DropText]).
+contradiction_text(predicate_contradiction, Certificate, Facts, Description) :-
+    Facts = Certificate.core,
+    Facts = [FactA, FactB],
+    atom_text(Certificate, Atom),
+    format(string(Description),
+        "Facts ~w and ~w give ~w opposite truth values", [FactA, FactB, Atom]).
+contradiction_text(decision_contradiction, Certificate, Facts, Description) :-
+    Facts = Certificate.core,
+    Facts = [FactA, FactB],
+    decision_text(Certificate, Decision),
+    format(string(Description),
+        "Facts ~w and ~w decide ~w differently: one allows it and the other denies it", [FactA, FactB, Decision]).
+contradiction_text(rule_negation_cycle, Certificate, [], Description) :-
+    findall(Text,
+        (   member(Edge, Certificate.cycle),
+            signature_text(Edge.head, Head),
+            signature_text(Edge.body, Body),
+            (   atom_string(negative, Edge.sign) -> Arrow = "depends on not" ; Arrow = "depends on" ),
+            format(string(Text), "~w ~w ~w", [Head, Arrow, Body])
+        ),
+        Texts),
+    atomic_list_concat(Texts, "; ", CycleText),
+    format(string(Description),
+        "Stored rules are not stratified: a predicate depends on its own negation (~w)", [CycleText]).
+
+suggestion_text(rule_negation_cycle, _Requirements,
+    "Break the cycle: change one rule so no predicate depends on its own negation, or supersede the requirement that stores it") :- !.
+suggestion_text(_Kind, Requirements, Suggestion) :-
+    atomic_list_concat(Requirements, ', ', RequirementText),
+    format(string(Suggestion),
+        "Supersede or change one of ~w so the facts can hold together; kibi check --write-certificates <file> saves the certificate",
+        [RequirementText]).
+
+% ------------------------------------------------------------------
+% Rejected certificates and unresolved contexts
+% ------------------------------------------------------------------
+
+rejected_violation(Failure, violation('kb-consistency', "kb-certificates", Description,
+        "Kibi produced a certificate its own checker rejects. Report it with the bundle from kibi check --write-certificates <file>", "")) :-
+    (   get_dict(group, Failure, Group)
+    ->  group_text(Group, Where)
+    ;   format(string(Where), "certificate ~w (~w)", [Failure.certificate, Failure.kind])
+    ),
+    format(string(Description),
+        "The independent checker rejected ~w: ~w", [Where, Failure.reason]).
+
+unresolved_violation(_Theorem, Entry, violation('kb-consistency-unresolved', EntityId, Description, Suggestion, "")) :-
+    group_text(Entry, Where),
+    (   get_dict(reason, Entry, Reason)
+    ->  true
+    ;   Reason = "the contradicting facts' validity windows never overlap"
+    ),
+    entry_facts(Entry, Facts),
+    fact_requirements(Facts, Requirements),
+    entity_label(Requirements, Facts, EntityId0),
+    (   EntityId0 == "" -> EntityId = Where ; EntityId = EntityId0 ),
+    format(string(Description),
+        "Kibi cannot decide whether the facts for ~w hold together: ~w. It never counts as consistent", [Where, Reason]),
+    Suggestion = "Align the facts' value_type, unit, operator or polarity so they can be compared, or accept that this context stays unchecked".
+
+entry_facts(Entry, Facts) :-
+    get_dict(subjectKey, Entry, Subject),
+    !,
+    get_dict(propertyKey, Entry, Property),
+    findall(Fact,
+        (   kb:current_req(Req),
+            kb:effective_req_property_fact(Req, Subject, Fact, Property, _, _, _, _, _, _, _, _)
+        ),
+        Facts0),
+    sort(Facts0, Facts).
+entry_facts(_Entry, []).
+
+% ------------------------------------------------------------------
+% Text helpers
+% ------------------------------------------------------------------
+
+fact_requirements(Facts, Requirements) :-
+    findall(Req,
+        (   member(FactText, Facts),
+            atom_string(Fact, FactText),
+            member(Type, [requires_property, requires_predicate, requires_rule]),
+            kb_relationship(Type, Req, Fact),
+            kb:current_req(Req)
+        ),
+        Requirements0),
+    sort(Requirements0, Requirements).
+
+entity_label([], [], "") :- !.
+entity_label([], Facts, Label) :- !, atomic_list_concat(Facts, '/', Label0), atom_string(Label0, Label).
+entity_label(Requirements, _Facts, Label) :- atomic_list_concat(Requirements, '/', Label0), atom_string(Label0, Label).
+
+context_text(Label, Text) :-
+    (   get_dict(scope, Label, Scope0) -> atom_string(Scope0, Scope) ; Scope = "" ),
+    (   Scope == ""
+    ->  format(string(Text), "~w.~w", [Label.subjectKey, Label.propertyKey])
+    ;   format(string(Text), "~w.~w (scope ~w)", [Label.subjectKey, Label.propertyKey, Scope])
+    ).
+
+group_text(Group, Text) :-
+    (   get_dict(subjectKey, Group, _)
+    ->  context_text(Group, Text)
+    ;   get_dict(args, Group, _)
+    ->  atom_text(Group, Text)
+    ;   get_dict(key, Group, _)
+    ->  decision_text(Group, Text)
+    ;   format(string(Text), "~w", [Group])
+    ).
+
+atom_text(Label, Text) :-
+    atomic_list_concat(Label.args, ', ', Args),
+    format(string(Text), "~w:~w(~w)", [Label.namespace, Label.name, Args]).
+
+decision_text(Label, Text) :-
+    atomic_list_concat(Label.key, ', ', Key),
+    format(string(Text), "~w:~w/~w for (~w)", [Label.namespace, Label.name, Label.arity, Key]).
+
+signature_text(Signature, Text) :-
+    format(string(Text), "~w:~w/~w", [Signature.namespace, Signature.name, Signature.arity]).

package/src/requirement_proof.pl

@@ -25,7 +25,7 @@
 ]).
 :- use_module('logic_ir.pl', [logic_rule_safety/2]).
 
-proof_version('kibi.requirement-proof.v3').
+proof_version('kibi.requirement-proof.v4').
 
 requirement_proof_context(Context) :-
     requirement_proof_context(unknown, '1970-01-01T00:00:00Z', 604800, Context).
@@ -71,12 +71,12 @@ requirement_proof(ReqId, ReqProps, _Context, Proof) :-
     kb:current_req(ReqId),
     proof_exempt(ReqProps, Reason),
     !,
-    exempt_requirement_proof(Reason, Proof).
-requirement_proof(ReqId, _ReqProps, _Context, Proof) :-
+    exempt_requirement_proof(Reason, ReqProps, Proof).
+requirement_proof(ReqId, ReqProps, _Context, Proof) :-
     \+ kb:current_req(ReqId),
     !,
     applicability_exclusion_reason(ReqId, Reason),
-    exempt_requirement_proof(Reason, Proof).
+    exempt_requirement_proof(Reason, ReqProps, Proof).
 requirement_proof(ReqId, ReqProps, Context, Proof) :-
     semantic_inventory_stage(ReqProps, SemanticStage, Inventory),
     logic_grounding_stage(ReqId, ReqProps, Inventory, Context, LogicStage),
@@ -101,10 +101,13 @@ requirement_proof(ReqId, ReqProps, Context, Proof) :-
     proof_issues(Stages, Gaps, Advisories),
     proof_repairs(Gaps, Repairs),
     proof_status(Stages, Status),
+    requirement_evidence(ReqProps, Status, PassingE2eTests, EvidenceLevel, Evidence),
     proof_version(Version),
     Proof = _{
         proofVersion: Version,
         proofStatus: Status,
+        evidenceLevel: EvidenceLevel,
+        evidence: Evidence,
         proofGaps: Gaps,
         proofAdvisories: Advisories,
         proofRepairs: Repairs,
@@ -112,11 +115,14 @@ requirement_proof(ReqId, ReqProps, Context, Proof) :-
         testResolutions: ScenarioTestStage.resolutions
     }.
 
-exempt_requirement_proof(Reason, Proof) :-
+exempt_requirement_proof(Reason, ReqProps, Proof) :-
+    requirement_evidence(ReqProps, not_applicable, [], EvidenceLevel, Evidence),
     proof_version(Version),
     Proof = _{
         proofVersion: Version,
         proofStatus: not_applicable,
+        evidenceLevel: EvidenceLevel,
+        evidence: Evidence,
         proofGaps: [],
         proofAdvisories: [],
         proofRepairs: [],
@@ -1674,7 +1680,84 @@ proof_status(Stages, unresolved) :-
     stage_dict(Stages, Stage),
     memberchk(Stage.status, [unresolved, blocked]),
     !.
-proof_status(_, proven).
+proof_status(_, tested).
+
+% implements REQ-kibi-evidence-levels
+%% requirement_evidence(+Props, +ProofStatus, +PassingE2eTests, -Level, -Evidence)
+% How strong the evidence behind a requirement is, never stronger than what
+% backs it.  Levels, strongest first: proved (a re-checkable certificate
+% covers every case), tested (passing E2E receipts cover every linked
+% scenario: proofStatus tested), asserted (a person stands behind the
+% statement but nothing current checks it), unverified (an agent wrote it and
+% no person approved it).  No proof kind issues certificates yet, so proved
+% is never reached here.  Evidence lists what earned the level and anything
+% weaker that also holds, each entry naming its kind and scope.
+requirement_evidence(Props, ProofStatus, PassingE2eTests, Level, Evidence) :-
+    findall(Entry, evidence_entry(Props, ProofStatus, PassingE2eTests, Entry), Evidence),
+    evidence_level(Evidence, Level).
+
+evidence_entry(_Props, tested, PassingE2eTests, _{kind: e2e, scope: code, level: tested, tests: PassingE2eTests}).
+evidence_entry(Props, _ProofStatus, _PassingE2eTests, Entry) :-
+    human_intent(Props, Basis, Ref),
+    (   Ref == ''
+    ->  Entry = _{kind: human_intent, scope: intent, level: asserted, basis: Basis}
+    ;   Entry = _{kind: human_intent, scope: intent, level: asserted, basis: Basis, ref: Ref}
+    ).
+
+evidence_level(Evidence, Level) :-
+    (   member(Level0, [proved, tested, asserted]),
+        member(Entry, Evidence),
+        get_dict(level, Entry, Level0)
+    ->  Level = Level0
+    ;   Level = unverified
+    ).
+
+%% human_intent(+Props, -Basis, -Ref)
+% A person stands behind the requirement: someone approved it
+% (origin.approved_by, the field agent-requirement-unapproved reads), or it
+% reads as firm (firmness: firm, or no firmness and an origin other than
+% agent, as for decision firmness).  The top-level approved_by approves an
+% exception; an agent can write it, so on its own it approves nothing here.
+human_intent(Props, approved, Ref) :-
+    origin_field(Props, approved_by, _),
+    !,
+    intent_ref(Props, Ref).
+human_intent(Props, firm, Ref) :-
+    effective_firmness(Props, firm),
+    !,
+    intent_ref(Props, Ref).
+
+effective_firmness(Props, Firmness) :-
+    (   memberchk(firmness=Raw, Props),
+        normalize_atom(Raw, Explicit),
+        memberchk(Explicit, [firm, default, exploratory])
+    ->  Firmness = Explicit
+    ;   origin_field(Props, kind, agent)
+    ->  Firmness = default
+    ;   Firmness = firm
+    ).
+
+intent_ref(Props, Ref) :-
+    (   origin_field(Props, ref, Ref0)
+    ->  Ref = Ref0
+    ;   prop_text(Props, approval_ref, Ref0)
+    ->  Ref = Ref0
+    ;   Ref = ''
+    ).
+
+prop_text(Props, Key, Text) :-
+    Prop =.. [=, Key, Raw],
+    memberchk(Prop, Props),
+    normalize_atom(Raw, Text),
+    Text \== ''.
+
+origin_field(Props, Key, Value) :-
+    memberchk(origin=Raw, Props),
+    normalize_atom(Raw, Json),
+    catch(atom_json_dict(Json, Origin, [value_string_as(atom)]), _, fail),
+    get_dict(Key, Origin, Value0),
+    normalize_atom(Value0, Value),
+    Value \== ''.
 
 stage_dict(Stages, Stage) :-
     dict_pairs(Stages, _, Pairs),
@@ -1690,7 +1773,7 @@ proof_advisories(Stages, Advisories) :-
 % Every linked scenario is a mandatory proof obligation. Receipt-completeness
 % failures therefore remain blocking even when another scenario has a passing
 % receipt; unit/integration-only evidence stays nonblocking in the E2E lane.
-% Invariant: proofStatus == proven implies proofGaps == [].
+% Invariant: proofStatus == tested implies proofGaps == [].
 proof_issues(Stages, Gaps, Advisories) :-
     findall(Gap,
         (gap_definition(Gap, _, _, _),

package/src/rule_registry.pl

@@ -67,6 +67,8 @@ known_rule('supersedes-reason-missing').
 known_rule('supersedes-reason-acknowledged').
 known_rule('policy-ownership').
 known_rule('policy-markers').
+known_rule('kb-consistency').
+known_rule('kb-consistency-unresolved').
 
 rule_enforcement_class('must-priority-coverage', canonical).
 rule_enforcement_class('symbol-coverage', canonical).
@@ -121,6 +123,8 @@ rule_enforcement_class('supersedes-reason-missing', canonical).
 rule_enforcement_class('supersedes-reason-acknowledged', advisory).
 rule_enforcement_class('policy-ownership', canonical).
 rule_enforcement_class('policy-markers', canonical).
+rule_enforcement_class('kb-consistency', canonical).
+rule_enforcement_class('kb-consistency-unresolved', advisory).
 
 rule_implementation('must-priority-coverage', prolog).
 rule_implementation('symbol-coverage', prolog).
@@ -175,6 +179,8 @@ rule_implementation('supersedes-reason-missing', typescript).
 rule_implementation('supersedes-reason-acknowledged', typescript).
 rule_implementation('policy-ownership', typescript).
 rule_implementation('policy-markers', typescript).
+rule_implementation('kb-consistency', prolog).
+rule_implementation('kb-consistency-unresolved', prolog).
 
 rule_predicate('must-priority-coverage', check_must_priority_coverage).
 rule_predicate('symbol-coverage', check_symbol_coverage).
@@ -210,6 +216,8 @@ rule_predicate('ontology-quality', check_ontology_quality).
 rule_predicate('symbol-owner-superseded', check_symbol_owner_superseded).
 rule_predicate('adr-unlinked', check_adr_unlinked).
 rule_predicate('adr-proposed', check_adr_proposed).
+rule_predicate('kb-consistency', check_kb_consistency).
+rule_predicate('kb-consistency-unresolved', check_kb_consistency_unresolved).
 
 rule_predicate_arity('must-priority-coverage', 1).
 rule_predicate_arity('symbol-coverage', 1).
@@ -245,6 +253,8 @@ rule_predicate_arity('ontology-quality', 1).
 rule_predicate_arity('symbol-owner-superseded', 1).
 rule_predicate_arity('adr-unlinked', 1).
 rule_predicate_arity('adr-proposed', 1).
+rule_predicate_arity('kb-consistency', 1).
+rule_predicate_arity('kb-consistency-unresolved', 1).
 
 rule_description('must-priority-coverage', 'Every current must-priority requirement (not superseded, retired, or closed without the implemented tag) must have a scenario and a test').
 rule_description('symbol-coverage', 'Production symbols need qualifying coverage via covered_by plus a canonical requirement/scenario test path').
@@ -299,3 +309,5 @@ rule_description('supersedes-reason-missing', 'A current requirement or ADR that
 rule_description('supersedes-reason-acknowledged', 'Informational: how many current superseding requirements and ADRs have only supersede edges the schema 9 migration acknowledged without a \'Why this changed\' section; one summary finding per check').
 rule_description('policy-ownership', 'When a plugin activated for kibi.check-policy.v1 declares ownership rules, every production symbol in a rule\'s file set must implement a current requirement grounded (requires_predicate) in one of the rule\'s predicates; projects without an activated check policy are unaffected').
 rule_description('policy-markers', 'When a plugin activated for kibi.check-policy.v1 declares marker rules, every file implementing a requirement grounded in the rule\'s pattern predicate (with its declared sibling files) must contain each marker the KB declares for that pattern').
+rule_description('kb-consistency', 'The facts current requirements name must hold together, jointly and not only pairwise: every property context needs a value that satisfies all its facts, every atom and decision key one truth value, and stored rules a stratification. Each finding is a contradiction certificate (an irreducible core, two disagreeing facts or a negation cycle) re-verified by the independent checker, or a certificate that checker rejects').
+rule_description('kb-consistency-unresolved', 'Advisory: a property context, atom or decision key whose facts the consistency checker cannot compare (mixed value types or units, an unsupported operator or polarity, or a contradiction whose validity windows never overlap); it never counts as consistent').