kibi-core 0.4.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-core",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": false,
   "description": "Core Prolog modules and RDF graph logic for Kibi",
   "type": "module",
@@ -9,10 +9,7 @@
     "bun": ">=1.0"
   },
   "main": "./src/kb.pl",
-  "files": [
-    "src/**/*.pl",
-    "schema/**/*.pl"
-  ],
+  "files": ["src/**/*.pl", "schema/**/*.pl"],
   "license": "AGPL-3.0-or-later",
   "author": "Piotr Franczyk",
   "repository": {

package/schema/entities.pl

@@ -28,6 +28,7 @@ entity_property(_, priority, atom).
 entity_property(_, severity, atom).
 entity_property(_, links, list).
 entity_property(_, text_ref, uri).
+entity_property(_, sourceFile, uri).
 
 % Typed fact fields - only valid for fact entities
 entity_property(fact, fact_kind, atom).
@@ -47,6 +48,10 @@ entity_property(fact, valid_from, datetime).
 entity_property(fact, valid_to, datetime).
 entity_property(fact, canonical_key, string).
 
+% Typed test verification fields - only valid for test entities
+entity_property(test, verification_scope, atom).
+entity_property(test, verification_perspective, atom).
+
 % Required properties for all entity types
 required_property(Type, id) :- entity_type(Type).
 required_property(Type, title) :- entity_type(Type).
@@ -62,6 +67,8 @@ 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(test, verification_scope).
+optional_property(test, verification_perspective).
 
 % Documentation helpers
 % list all entity types

package/schema/relationships.pl

@@ -4,6 +4,7 @@
 
 % Relationship types
 relationship_type(depends_on).
+relationship_type(executable_for).
 relationship_type(specified_by).
 relationship_type(verified_by).
 relationship_type(validates).
@@ -20,9 +21,12 @@ relationship_type(requires_property).
 
 % valid_relationship(RelType, FromType, ToType).
 valid_relationship(depends_on, req, req).
+valid_relationship(executable_for, symbol, test).
 valid_relationship(specified_by, req, scenario).
 valid_relationship(verified_by, req, test).
+valid_relationship(verified_by, scenario, test).
 valid_relationship(validates, test, req).
+valid_relationship(validates, test, scenario).
 valid_relationship(implements, symbol, req).
 valid_relationship(covered_by, symbol, test).
 valid_relationship(constrained_by, symbol, adr).

package/schema/validation.pl

@@ -60,10 +60,16 @@ validate_entity_shape(fact, Props) :-
     valid_optional_fact_enums(Props),
     valid_polarity_in_props(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(Type, Props) :-
     Type \= fact,
-    % Non-fact entities cannot have fact-only fields
-    forall(member(Key=_Val, Props), \+ is_fact_only_field(Key)).
+    Type \= test,
+    % 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)).
 
 % is_fact_only_field(+Key) - true if Key is a fact-specific field
 is_fact_only_field(fact_kind).
@@ -83,6 +89,10 @@ is_fact_only_field(valid_from).
 is_fact_only_field(valid_to).
 is_fact_only_field(canonical_key).
 
+% is_test_only_field(+Key) - true if Key is a test-specific field
+is_test_only_field(verification_scope).
+is_test_only_field(verification_perspective).
+
 % validate_fact_shape(+Kind, +Props)
 validate_fact_shape(subject, Props) :-
     memberchk(subject_key=_Val, Props),
@@ -136,10 +146,25 @@ valid_optional_fact_enums(Props) :-
     ( memberchk(operator=Op, Props) -> valid_operator(Op) ; true ),
     ( memberchk(value_type=VT, Props) -> valid_value_type(VT) ; true ).
 
+% valid_optional_test_enums(+Props)
+% Validates enum-typed test fields whenever they are present
+valid_optional_test_enums(Props) :-
+    ( memberchk(verification_scope=Scope, Props) -> valid_verification_scope(Scope) ; true ),
+    ( memberchk(verification_perspective=Perspective, Props) -> valid_verification_perspective(Perspective) ; true ).
+
 % valid_polarity(+P)
 valid_polarity(require).
 valid_polarity(forbid).
 
+% valid_verification_scope(+Scope)
+valid_verification_scope(unit).
+valid_verification_scope(integration).
+valid_verification_scope(end_to_end).
+
+% valid_verification_perspective(+Perspective)
+valid_verification_perspective(internal).
+valid_verification_perspective(consumer).
+
 % exactly_one_value_field(+Props)
 exactly_one_value_field(Props) :-
     findall(F, (member(F=_, Props), is_value_field(F)), Fields),

package/src/checks.pl

@@ -90,7 +90,7 @@ coverage_gap_suggestion(missing_scenario, "Create scenario that specifies this r
 coverage_gap_suggestion(missing_scenario_and_test, "Create scenario that specifies and test that validates this requirement").
 
 %% check_symbol_coverage(-Violations)
-% Finds all symbols not traceable to any functional requirement.
+% Finds all production symbols lacking qualifying production coverage.
 check_symbol_coverage(Violations) :-
     findall(SymbolId, symbol_no_req_coverage(SymbolId, _), SymbolIds0),
     sort(SymbolIds0, SymbolIds),
@@ -99,15 +99,15 @@ check_symbol_coverage(Violations) :-
 symbol_coverage_violation(SymbolId, violation(
     'symbol-coverage',
     SymbolId,
-    "Code symbol is not traceable to any functional requirement.",
-    "Update symbols.yaml to link this symbol to a related requirement.",
+    "Production symbol lacks qualifying requirement coverage.",
+    "Add 'covered_by: TEST-xxx' for production coverage, and ensure that test reaches the requirement through a scenario->test path or direct req->test fallback when no scenario exists.",
     Source
 )) :-
     violation_source(SymbolId, symbol, Source).
 
 %% check_symbol_traceability(+RequireAdr, -Violations)
-% Finds all symbols lacking supported requirement traceability:
-% - Every symbol must have at least one supported requirement traceability path
+% Finds all symbols lacking direct requirement ownership:
+% - Every symbol must have at least one direct implements ownership path
 % - If RequireAdr=true, the symbol must also have at least one 'constrained_by' relationship to an ADR
 check_symbol_traceability(RequireAdr, Violations) :-
     findall(
@@ -125,8 +125,9 @@ symbol_traceability_violation(RequireAdr, violation(
     Source
 )) :-
     kb_entity(SymbolId, symbol, _),
-    % Check if symbol has a supported requirement traceability path
-    (   transitively_implements(SymbolId, ReqId),
+    \+ executable_test_symbol(SymbolId),
+    % Check if symbol has direct requirement ownership
+    (   symbol_owns_requirement(SymbolId, ReqId),
         kb_entity(ReqId, req, _)
     ->  HasReq = true
     ;   HasReq = false
@@ -142,11 +143,11 @@ symbol_traceability_violation(RequireAdr, violation(
     ),
     % Determine what is missing
     (   HasReq = false, HasAdr = false, RequireAdr = true ->
-        Description = "Symbol has no supported requirement traceability path and no ADR constraint.",
-        Suggestion = "Add a direct 'implements: REQ-xxx' link or a test-backed 'covered_by' + 'validates'/'verified_by' path, and add 'constrained_by: ADR-xxx' in symbols.yaml."
+        Description = "Symbol has no direct requirement ownership and no ADR constraint.",
+        Suggestion = "Add a direct 'implements: REQ-xxx' link for ownership, use 'covered_by' only for production coverage, use 'executable_for' only for executable test code, and add 'constrained_by: ADR-xxx' in symbols.yaml."
     ;   HasReq = false ->
-        Description = "Symbol has no supported requirement traceability path.",
-        Suggestion = "Add a direct 'implements: REQ-xxx' link or a test-backed 'covered_by' + 'validates'/'verified_by' path."
+        Description = "Symbol has no direct requirement ownership.",
+        Suggestion = "Add a direct 'implements: REQ-xxx' link for ownership. Use 'covered_by' for production coverage and 'executable_for' for executable test code identity."
     ;   HasAdr = false ->
         Description = "Symbol has no ADR constraint.",
         Suggestion = "Add 'constrained_by: ADR-xxx' in symbols.yaml."
@@ -177,7 +178,7 @@ dangling_ref_violation(Type, violation(
     "Remove relationship or create missing entity",
     ""
 )) :-
-    kb_relationship(Type, FromId, ToId),
+    kb_relationship(Type, FromId, _ToId),
     \+ kb_entity(FromId, _, _),  % From doesn't exist
     format(string(Description), "Relationship references non-existent entity: ~w", [FromId]).
 
@@ -297,7 +298,7 @@ missing_required_field(Required, violation(
     Suggestion,
     Source
 )) :-
-    kb_entity(EntityId, Type, Props),
+    kb_entity(EntityId, _Type, Props),
     member(Field, Required),
     \+ memberchk(Field=_, Props),
     

package/src/kb.pl

@@ -15,6 +15,14 @@
     kb_assert_relationship_no_audit/4,
     kb_log_relationship_upsert/4,
     kb_relationship/3,
+    symbol_owns_requirement/2,
+    scenario_verified_by_test/2,
+    requirement_test_fallback_allowed/1,
+    test_satisfies_requirement_semantics/2,
+    production_symbol_covered_for_requirement/2,
+    production_symbol_untested/1,
+    executable_test_symbol/1,
+    mixed_role_symbol/1,
     transitively_implements/2,
     transitively_depends/2,
     impacted_by_change/2,
@@ -382,6 +390,7 @@ kb_assert_relationship_no_audit(RelType, FromId, ToId, _Metadata) :-
     once(kb_entity(FromId, FromType, _)),
     once(kb_entity(ToId, ToType, _)),
     validate_relationship(RelType, FromType, ToType),
+    validate_symbol_role_compatibility(RelType, FromId, ToId),
     % NOTE: Strict-lane fact_kind pairing is validated at the MCP layer
     % via validateStrictLanePairing() before the transaction begins.
     % Prolog-level validation is deferred to avoid potential issues with
@@ -400,6 +409,25 @@ kb_assert_relationship_no_audit(RelType, FromId, ToId, _Metadata) :-
         rdf_assert(FromURI, RelURI, ToURI, Graph)
     )).
 
+validate_symbol_role_compatibility(RelType, FromId, _ToId) :-
+    memberchk(RelType, [implements, covered_by, executable_for]),
+    !,
+    (   mixed_symbol_role(RelType, FromId)
+    ->  format(atom(Msg), 'symbol ~w cannot mix executable_for with production ownership/coverage relationships', [FromId]),
+        throw(error(validation_error(Msg), Msg))
+    ;   true
+    ).
+validate_symbol_role_compatibility(_, _, _).
+
+mixed_symbol_role(executable_for, SymbolId) :-
+    (   kb_relationship(implements, SymbolId, _)
+    ;   kb_relationship(covered_by, SymbolId, _)
+    ).
+mixed_symbol_role(implements, SymbolId) :-
+    kb_relationship(executable_for, SymbolId, _).
+mixed_symbol_role(covered_by, SymbolId) :-
+    kb_relationship(executable_for, SymbolId, _).
+
 %% kb_log_relationship_upsert(+Type, +From, +To, +Metadata)
 % Append the audit entry for a successfully committed relationship upsert.
 kb_log_relationship_upsert(RelType, FromId, ToId, _Metadata) :-
@@ -567,18 +595,85 @@ uri_to_key(URI, Key) :-
 %% Inference predicates (Phase 1)
 %% ------------------------------------------------------------------
 
-%% transitively_implements(+Symbol, +Req)
-% A symbol transitively implements a requirement if it directly implements it,
-% or if it is covered by a test that validates/verifies the requirement.
-transitively_implements(Symbol, Req) :-
+%% symbol_owns_requirement(+Symbol, +Req)
+% Direct requirement ownership for production code.
+symbol_owns_requirement(Symbol, Req) :-
     kb_relationship(implements, Symbol, Req).
+
+%% transitively_implements(+Symbol, +Req)
+% Ownership is direct only; coverage/test traceability is handled separately.
 transitively_implements(Symbol, Req) :-
-    kb_relationship(covered_by, Symbol, Test),
+    symbol_owns_requirement(Symbol, Req).
+
+%% scenario_verified_by_test(+Scenario, +Test)
+% Canonical scenario-to-test verification path.
+scenario_verified_by_test(Scenario, Test) :-
+    kb_relationship(validates, Test, Scenario).
+scenario_verified_by_test(Scenario, Test) :-
+    kb_relationship(verified_by, Scenario, Test).
+
+%% requirement_test_fallback_allowed(+Req)
+% Direct requirement-to-test fallback is only allowed when no scenario exists.
+requirement_test_fallback_allowed(Req) :-
+    \+ has_scenario(Req).
+
+%% executable_test_symbol(+Symbol)
+% Symbol represents executable test code rather than production code.
+executable_test_symbol(Symbol) :-
+    kb_relationship(executable_for, Symbol, _).
+
+%% mixed_role_symbol(+Symbol)
+% Invalid symbol carrying both executable test identity and production semantics.
+mixed_role_symbol(Symbol) :-
+    executable_test_symbol(Symbol),
+    (   kb_relationship(implements, Symbol, _)
+    ;   kb_relationship(covered_by, Symbol, _)
+    ).
+
+%% production_symbol(+Symbol)
+% Internal helper for production-only symbol checks.
+production_symbol(Symbol) :-
+    kb_entity(Symbol, symbol, _),
+    \+ executable_test_symbol(Symbol).
+
+%% requirement_verified_by_test(+Req, +Test)
+% Direct req<->test compatibility path.
+requirement_verified_by_test(Req, Test) :-
     kb_relationship(validates, Test, Req).
-transitively_implements(Symbol, Req) :-
-    kb_relationship(covered_by, Symbol, Test),
+requirement_verified_by_test(Req, Test) :-
     kb_relationship(verified_by, Req, Test).
 
+%% test_satisfies_requirement_semantics(+Test, +Req)
+% Matches requirement verification facts against typed test fields when present.
+% If the requirement declares no verification semantics, compatibility passes.
+test_satisfies_requirement_semantics(Test, Req) :-
+    findall(Key-Expected,
+            required_test_semantic(Req, Key, Expected),
+            RequiredPairs0),
+    sort(RequiredPairs0, RequiredPairs),
+    (   RequiredPairs = []
+    ->  true
+    ;   kb_entity(Test, test, TestProps),
+        forall(member(Key-Expected, RequiredPairs),
+               test_matches_required_semantic(TestProps, Key, Expected))
+    ).
+
+required_test_semantic(Req, Key, Expected) :-
+    memberchk(Key, [verification_scope, verification_perspective]),
+    verification_subject_key(Req, SubjectKey),
+    effective_req_property(Req, SubjectKey, Key, Operator, _ValueType, Value, _Unit, _Scope, Polarity),
+    Operator == eq,
+    Polarity == require,
+    normalize_term_atom(Value, Expected).
+
+verification_subject_key(Req, SubjectKey) :-
+    format(atom(SubjectKey), 'requirement.~w.verification', [Req]).
+
+test_matches_required_semantic(TestProps, Key, Expected) :-
+    memberchk(Key=ActualRaw, TestProps),
+    normalize_term_atom(ActualRaw, Actual),
+    Actual == Expected.
+
 %% transitively_depends(+Req1, +Req2)
 % Req1 transitively depends on Req2 through depends_on chains.
 transitively_depends(Req1, Req2) :-
@@ -658,14 +753,17 @@ has_test(Req) :-
     once(kb_relationship(validates, _, Req)).
 has_test(Req) :-
     once(kb_relationship(verified_by, Req, _)).
+has_test(Req) :-
+    kb_relationship(specified_by, Req, Scenario),
+    once(kb_relationship(validates, _, Scenario)).
+has_test(Req) :-
+    kb_relationship(specified_by, Req, Scenario),
+    once(kb_relationship(verified_by, Scenario, _)).
 
 %% untested_symbols(-Symbols)
-% Returns symbols with no test coverage relationship.
+% Returns production symbols with no test coverage relationship.
 untested_symbols(Symbols) :-
-    setof(Symbol,
-          (kb_entity(Symbol, symbol, _),
-           \+ kb_relationship(covered_by, Symbol, _)),
-          Symbols),
+    setof(Symbol, production_symbol_untested(Symbol), Symbols),
     !.
 untested_symbols([]).
 
@@ -683,9 +781,9 @@ stale(Entity, MaxAgeDays) :-
     AgeDays > MaxAgeDays.
 
 %% orphaned(+Symbol)
-% Symbol is orphaned if it has no core traceability links.
+% Production symbol is orphaned if it has no core traceability links.
 orphaned(Symbol) :-
-    kb_entity(Symbol, symbol, _),
+    production_symbol(Symbol),
     \+ kb_relationship(implements, Symbol, _),
     \+ kb_relationship(covered_by, Symbol, _),
     \+ kb_relationship(constrained_by, Symbol, _).
@@ -1001,15 +1099,40 @@ normalize_uri_atom(Value, Atom) :-
     ).
 
 %% symbol_no_req_coverage(+Symbol, -Reason)
-% Find symbols that are not traceable to any functional requirement.
-symbol_no_req_coverage(Symbol, no_path_to_req) :-
-    kb_entity(Symbol, symbol, _),
-    \+ transitively_implements(Symbol, _).
+% Find symbols that lack canonical production requirement coverage.
+symbol_no_req_coverage(Symbol, no_qualifying_production_coverage) :-
+    production_symbol(Symbol),
+    \+ production_symbol_covered_for_requirement(Symbol, _).
+
+%% production_symbol_covered_for_requirement(+Symbol, +Req)
+% Production coverage requires a covered_by edge and a canonical requirement/test path.
+production_symbol_covered_for_requirement(Symbol, Req) :-
+    production_symbol(Symbol),
+    kb_relationship(covered_by, Symbol, Test),
+    test_covers_requirement(Test, Req).
+
+symbol_has_req_coverage(Symbol, Req) :-
+    production_symbol_covered_for_requirement(Symbol, Req).
+
+test_covers_requirement(Test, Req) :-
+    requirement_test_fallback_allowed(Req),
+    requirement_verified_by_test(Req, Test),
+    test_satisfies_requirement_semantics(Test, Req).
+test_covers_requirement(Test, Req) :-
+    kb_relationship(specified_by, Req, Scenario),
+    scenario_verified_by_test(Scenario, Test),
+    test_satisfies_requirement_semantics(Test, Req).
+
+%% production_symbol_untested(+Symbol)
+% Production symbol with no covered_by test evidence at all.
+production_symbol_untested(Symbol) :-
+    production_symbol(Symbol),
+    \+ kb_relationship(covered_by, Symbol, _).
 
 % Helper predicate for readability - symbols with no traceability
 symbol_uncovered(Symbol) :-
-    kb_entity(Symbol, symbol, _),
-    \+ transitively_implements(Symbol, _).
+    production_symbol(Symbol),
+    \+ production_symbol_covered_for_requirement(Symbol, _).
 
 
 coerce_timestamp_atom(Val^^_Type, Atom) :-
@@ -1045,7 +1168,8 @@ coerce_timestamp_atom(Val, Atom) :-
 % counted so that `// implements: REQ-001` can satisfy the gate.
 changed_symbol_missing_req(Symbol, MinLinks, Count) :-
     changed_symbol(Symbol),
-    (   setof(Req, transitively_implements(Symbol, Req), KbReqs)
+    \+ executable_test_symbol(Symbol),
+    (   setof(Req, symbol_owns_requirement(Symbol, Req), KbReqs)
     ->  true
     ;   KbReqs = []
     ),