kibi-core 0.7.0 → 0.7.1

package/package.json

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

package/schema/entities.pl

@@ -29,6 +29,7 @@ entity_property(_, severity, atom).
 entity_property(_, links, list).
 entity_property(_, text_ref, uri).
 entity_property(_, sourceFile, uri).
+entity_property(req, logic_claims, list).
 
 % Typed fact fields - only valid for fact entities
 entity_property(fact, fact_kind, atom).
@@ -47,6 +48,8 @@ entity_property(fact, closed_world, boolean).
 entity_property(fact, valid_from, datetime).
 entity_property(fact, valid_to, datetime).
 entity_property(fact, canonical_key, string).
+entity_property(fact, claim_key, string).
+entity_property(fact, claim_text, string).
 entity_property(fact, predicate_name, string).
 entity_property(fact, predicate_namespace, string).
 entity_property(fact, predicate_arity, integer).
@@ -80,6 +83,7 @@ optional_property(Type, priority) :- entity_type(Type).
 optional_property(Type, severity) :- entity_type(Type).
 optional_property(Type, links) :- entity_type(Type).
 optional_property(Type, text_ref) :- entity_type(Type).
+optional_property(req, logic_claims).
 optional_property(test, verification_scope).
 optional_property(test, verification_perspective).
 

package/schema/validation.pl

@@ -59,17 +59,24 @@ validate_entity_shape(fact, Props) :-
     !,
     valid_optional_fact_enums(Props),
     valid_polarity_in_props(Props),
+    valid_claim_provenance(Props),
     ( memberchk(fact_kind=RawKind, Props) -> validate_fact_shape(RawKind, Props) ; true ).
 validate_entity_shape(test, Props) :-
     !,
     valid_optional_test_enums(Props),
     forall(member(Key=_, Props), \+ is_fact_only_field(Key)).
+validate_entity_shape(req, Props) :-
+    !,
+    forall(member(Key=_, Props), \+ is_fact_only_field(Key)),
+    forall(member(Key=_, Props), \+ is_test_only_field(Key)).
 validate_entity_shape(Type, Props) :-
     Type \= fact,
     Type \= test,
+    Type \= req,
     % Non-fact/non-test entities cannot have type-specific fields
     forall(member(Key=_, Props), \+ is_fact_only_field(Key)),
-    forall(member(Key=_, Props), \+ is_test_only_field(Key)).
+    forall(member(Key=_, Props), \+ is_test_only_field(Key)),
+    forall(member(Key=_, Props), Key \= logic_claims).
 
 % is_fact_only_field(+Key) - true if Key is a fact-specific field
 is_fact_only_field(fact_kind).
@@ -88,6 +95,8 @@ is_fact_only_field(closed_world).
 is_fact_only_field(valid_from).
 is_fact_only_field(valid_to).
 is_fact_only_field(canonical_key).
+is_fact_only_field(claim_key).
+is_fact_only_field(claim_text).
 is_fact_only_field(predicate_name).
 is_fact_only_field(predicate_namespace).
 is_fact_only_field(predicate_arity).
@@ -172,6 +181,18 @@ valid_strict_polarity_in_props(Props) :-
 valid_predicate_polarity_in_props(Props) :-
     ( memberchk(polarity=P, Props) -> valid_predicate_polarity(P) ; true ).
 
+% claim_key and claim_text form one auditable provenance pair.
+valid_claim_provenance(Props) :-
+    (   memberchk(claim_key=Key, Props)
+    ->  memberchk(claim_text=Text, Props),
+        nonempty_claim_value(Key),
+        nonempty_claim_value(Text)
+    ;   \+ memberchk(claim_text=_, Props)
+    ).
+
+nonempty_claim_value(Value) :- string(Value), Value \= "".
+nonempty_claim_value(Value) :- atom(Value), Value \= ''.
+
 % valid_optional_fact_enums(+Props)
 % Validates enum-typed fact fields whenever they are present
 valid_optional_fact_enums(Props) :-

package/src/checks.pl

@@ -18,6 +18,7 @@
     check_strict_req_fact_pairing/1,% Returns list of malformed strict req/fact pairing violations
     check_strict_readiness/1,       % Returns list of strict readiness audit violations
     check_predicate_verifiability/1,% Returns list of unverifiable predicate-lane requirement links
+    check_logic_coverage/1,         % Returns list of incomplete declared logical claim manifests
     run_checks_json/0,              % Entry point for JSON output
     violation_id_text/2             % Extract text from entity ID term (exported for testing)
 ]).
@@ -54,6 +55,7 @@ check_all(ViolationsDict) :-
     check_strict_req_fact_pairing(StrictReqFactPairing),
     check_strict_readiness(StrictReadiness),
     check_predicate_verifiability(PredicateVerifiability),
+    check_logic_coverage(LogicCoverage),
     ViolationsDict = _{
         must_priority_coverage: MustPriority,
         symbol_coverage: SymbolCoverage,
@@ -66,7 +68,8 @@ check_all(ViolationsDict) :-
         strict_fact_shape: StrictFactShape,
         strict_req_fact_pairing: StrictReqFactPairing,
         strict_readiness: StrictReadiness,
-        predicate_verifiability: PredicateVerifiability
+        predicate_verifiability: PredicateVerifiability,
+        logic_coverage: LogicCoverage
     }.
 
 %% check_must_priority_coverage(-Violations)
@@ -800,6 +803,133 @@ predicate_verifiability_kind_label(legacy, "a legacy fact without fact_kind").
 predicate_verifiability_kind_label(Kind, Label) :-
     format(string(Label), "fact_kind=~w", [Kind]).
 
+%% check_logic_coverage(-Violations)
+% Validates explicitly declared atomic requirement claim manifests. Legacy
+% requirements without logic_claims remain eligible for gradual backfill; once
+% a manifest exists, every key must be grounded by a linked strict-property or
+% predicate fact carrying the same claim_key.
+check_logic_coverage(Violations) :-
+    findall(Violation, logic_coverage_violation(Violation), Violations0),
+    sort(Violations0, Violations).
+
+logic_coverage_violation(violation(
+    'logic-coverage',
+    ReqId,
+    Description,
+    "Ground every declared claim with a property_value fact via requires_property or a predicate fact via requires_predicate, preserving the same claim_key",
+    Source
+)) :-
+    kb:current_req(ReqId),
+    requirement_logic_claims(ReqId, ClaimKeys),
+    member(ClaimKey, ClaimKeys),
+    \+ grounded_requirement_claim(ReqId, ClaimKey),
+    format(
+        string(Description),
+        "Requirement declares logical claim ~w but has no matching ground fact",
+        [ClaimKey]
+    ),
+    violation_source(ReqId, req, Source).
+
+logic_coverage_violation(violation(
+    'logic-coverage',
+    ReqId,
+    Description,
+    "Keep a one-to-one mapping between each atomic claim key and its linked ground fact; split compound clauses before grounding",
+    Source
+)) :-
+    kb:current_req(ReqId),
+    grounded_requirement_claim_fact(ReqId, ClaimKey, FactA),
+    grounded_requirement_claim_fact(ReqId, ClaimKey, FactB),
+    FactA @< FactB,
+    format(
+        string(Description),
+        "Requirement grounds logical claim ~w more than once through ~w and ~w",
+        [ClaimKey, FactA, FactB]
+    ),
+    violation_source(ReqId, req, Source).
+
+logic_coverage_violation(violation(
+    'logic-coverage',
+    ReqId,
+    Description,
+    "Remove punctuation or wording variants from the atomic inventory and keep one claim key for each distinct logical term",
+    Source
+)) :-
+    kb:current_req(ReqId),
+    grounded_requirement_claim_fact(ReqId, ClaimA, FactA),
+    grounded_requirement_claim_fact(ReqId, ClaimB, FactB),
+    ClaimA \= ClaimB,
+    FactA @< FactB,
+    logical_ground_signature(FactA, Signature),
+    logical_ground_signature(FactB, Signature),
+    format(
+        string(Description),
+        "Requirement declares duplicate logical ground term ~w through claim keys ~w and ~w",
+        [Signature, ClaimA, ClaimB]
+    ),
+    violation_source(ReqId, req, Source).
+
+logic_coverage_violation(violation(
+    'logic-coverage',
+    ReqId,
+    Description,
+    "Append the linked fact claim_key to the requirement logic_claims manifest, or remove the stale logical link",
+    Source
+)) :-
+    kb:current_req(ReqId),
+    requirement_logic_claims(ReqId, ClaimKeys),
+    grounded_requirement_claim(ReqId, ClaimKey),
+    \+ memberchk(ClaimKey, ClaimKeys),
+    format(
+        string(Description),
+        "Requirement links ground logical claim ~w but omits it from logic_claims",
+        [ClaimKey]
+    ),
+    violation_source(ReqId, req, Source).
+
+requirement_logic_claims(ReqId, ClaimKeys) :-
+    kb_entity(ReqId, req, Props),
+    memberchk(logic_claims=RawClaimKeys, Props),
+    kb:normalize_term_atom_list(RawClaimKeys, ClaimKeys).
+
+grounded_requirement_claim(ReqId, ClaimKey) :-
+    grounded_requirement_claim_fact(ReqId, ClaimKey, _FactId).
+
+grounded_requirement_claim_fact(ReqId, ClaimKey, FactId) :-
+    kb_relationship(requires_property, ReqId, FactId),
+    ground_fact_claim_key(FactId, property_value, ClaimKey).
+grounded_requirement_claim_fact(ReqId, ClaimKey, FactId) :-
+    kb_relationship(requires_predicate, ReqId, FactId),
+    ground_fact_claim_key(FactId, predicate, ClaimKey).
+
+logical_ground_signature(FactId, predicate(Namespace, Name, Args, Polarity)) :-
+    kb:predicate_fact(FactId, Namespace, Name, Args, Polarity).
+logical_ground_signature(
+    FactId,
+    property(Subject, Property, Operator, ValueType, Value, Unit, Scope, Polarity)
+) :-
+    kb:fact_property_tuple(
+        FactId,
+        Subject,
+        Property,
+        Operator,
+        ValueType,
+        Value,
+        Unit,
+        Scope,
+        Polarity
+    ).
+
+ground_fact_claim_key(FactId, ExpectedKind, ClaimKey) :-
+    kb_entity(FactId, fact, Props),
+    memberchk(fact_kind=RawKind, Props),
+    normalize_term_atom(RawKind, ExpectedKind),
+    memberchk(claim_key=RawClaimKey, Props),
+    normalize_term_atom(RawClaimKey, ClaimKey),
+    memberchk(claim_text=RawClaimText, Props),
+    normalize_term_atom(RawClaimText, ClaimText),
+    ClaimText \= ''.
+
 strict_readiness_has_fact_link(ReqId) :-
     kb_relationship(constrains, ReqId, FactId),
     kb_entity(FactId, fact, _),
@@ -873,6 +1003,7 @@ check_all_with_options(ViolationsDict, RequireAdr) :-
     check_strict_req_fact_pairing(StrictReqFactPairing),
     check_strict_readiness(StrictReadiness),
     check_predicate_verifiability(PredicateVerifiability),
+    check_logic_coverage(LogicCoverage),
     ViolationsDict = _{
         must_priority_coverage: MustPriority,
         symbol_coverage: SymbolCoverage,
@@ -885,7 +1016,8 @@ check_all_with_options(ViolationsDict, RequireAdr) :-
         strict_fact_shape: StrictFactShape,
         strict_req_fact_pairing: StrictReqFactPairing,
         strict_readiness: StrictReadiness,
-        predicate_verifiability: PredicateVerifiability
+        predicate_verifiability: PredicateVerifiability,
+        logic_coverage: LogicCoverage
     }.
 
 %% violations_dict_to_json(+ViolationsDict, -JsonDict)

package/src/kb.pl

@@ -45,6 +45,7 @@
     contradicting_reqs/3,
     check_req_contradiction/1,
     normalize_term_atom/2,
+    normalize_term_atom_list/2,
     changeset/4, % Export for testing
     kb_uri/1
 ]).
@@ -636,7 +637,7 @@ value_to_literal(Key, Value, Literal) :-
     ;   string(Value)
     ->  Literal = Value^^'http://www.w3.org/2001/XMLSchema#string'
     ;   is_list(Value)
-    ->  format(atom(ListStr), '~w', [Value]),
+    ->  with_output_to(atom(ListStr), write_term(Value, [quoted(true)])),
         Literal = ListStr^^'http://www.w3.org/2001/XMLSchema#string'
     ;   format(atom(Str), '~w', [Value]),
         Literal = Str^^'http://www.w3.org/2001/XMLSchema#string'
@@ -1005,6 +1006,26 @@ req_conflict(ReqA, ReqB, Reason) :-
     ;   property_conflict(SubjectKey, PropertyKey, OpA, ValTypeA, ValA, UnitA, PolarityA,
                           OpB, ValTypeB, ValB, UnitB, PolarityB, Reason)
     ).
+req_conflict(ReqA, ReqB, Reason) :-
+    effective_req_predicate(ReqA, FactA, Namespace, Name, Args, PolarityA),
+    effective_req_predicate(ReqB, FactB, Namespace, Name, Args, PolarityB),
+    FactA \= FactB,
+    opposite_predicate_polarity(PolarityA, PolarityB),
+    atomic_list_concat(Args, ',', ArgsText),
+    format(
+        string(Reason),
+        "Predicate conflict on ~w:~w(~w): ~w asserts ~w while ~w asserts ~w",
+        [Namespace, Name, ArgsText, ReqA, PolarityA, ReqB, PolarityB]
+    ).
+
+%% effective_req_predicate(+ReqId, -FactId, -Namespace, -Name, -Args, -Polarity)
+% Ground predicate claim required by a requirement.
+effective_req_predicate(ReqId, FactId, Namespace, Name, Args, Polarity) :-
+    kb_relationship(requires_predicate, ReqId, FactId),
+    predicate_fact(FactId, Namespace, Name, Args, Polarity).
+
+opposite_predicate_polarity(assert, deny).
+opposite_predicate_polarity(deny, assert).
 
 %% fact_subject_key(+FactId, -SubjectKey)
 % Extract the normalized subject key for strict subject facts.

package/src/sparql_client.pl

@@ -44,7 +44,10 @@ validate_remote_endpoint(Endpoint) :-
 
 validate_select_query(Query) :-
     normalize_space(atom(Normalized), Query),
-    downcase_atom(Normalized, Lower),
+    split_string(Normalized, "\n", " \t\r", RawLines),
+    strip_sparql_prelude(RawLines, RemainingLines),
+    atomic_list_concat(RemainingLines, ' ', Remainder),
+    downcase_atom(Remainder, Lower),
     sub_atom(Lower, 0, 6, After, 'select'),
     (   After =:= 0
     ;   sub_atom(Lower, 6, 1, _, ' ')
@@ -54,6 +57,25 @@ validate_select_query(Query) :-
 validate_select_query(Query) :-
     throw(error(domain_error(sparql_select_query, Query), _)).
 
+strip_sparql_prelude([], []).
+strip_sparql_prelude([Line | Rest], Result) :-
+    normalize_space(atom(Trimmed), Line),
+    (   Trimmed == ''
+    ->  strip_sparql_prelude(Rest, Result)
+    ;   is_prelude_line(Trimmed)
+    ->  strip_sparql_prelude(Rest, Result)
+    ;   Result = [Trimmed | Rest]
+    ).
+
+is_prelude_line(Line) :-
+    downcase_atom(Line, Lower),
+    split_string(Lower, " ", " \t", Tokens0),
+    exclude(=("") , Tokens0, Tokens),
+    Tokens = [FirstToken | _],
+    (   FirstToken == "prefix"
+    ;   FirstToken == "base"
+    ).
+
 endpoint_host(Endpoint, Host) :-
     strip_endpoint_scheme(Endpoint, WithoutScheme),
     segment_before(WithoutScheme, '/', WithoutPath),

package/src/status.pl

@@ -117,6 +117,7 @@ documentation_markdown_untracked(WorkspaceRoot) :-
 documentation_markdown_file(Path, Path) :-
     exists_file(Path),
     file_name_extension(_, md, Path),
+    entity_documentation_file(Path),
     \+ ignored_documentation_file(Path),
     !.
 documentation_markdown_file(Path, FilePath) :-
@@ -140,6 +141,7 @@ known_source_path(RelativePath) :-
 
 directory_tree_newer(Path, SnapshotTime) :-
     exists_file(Path),
+    entity_documentation_file(Path),
     \+ ignored_documentation_file(Path),
     time_file(Path, EntryTime),
     EntryTime > SnapshotTime,
@@ -218,5 +220,12 @@ source_value_atom(Val, Atom) :-
 ignored_documentation_file(Path) :-
     file_base_name(Path, 'README.md').
 
+entity_documentation_file(Path) :-
+    read_file_to_string(Path, Content, []),
+    sub_string(Content, 0, 3, _, "---"),
+    sub_string(Content, _, _, _, "id:"),
+    sub_string(Content, _, _, _, "title:"),
+    sub_string(Content, _, _, _, "status:").
+
 dict_json_string(Dict, JsonString) :-
     with_output_to(string(JsonString), json_write_dict(current_output, Dict, [])).