kibi-core 0.6.1 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-core",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "private": false,
   "description": "Core Prolog modules and RDF graph logic for Kibi",
   "type": "module",
@@ -9,7 +9,10 @@
     "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/src/checks.pl

@@ -107,7 +107,7 @@ symbol_coverage_violation(SymbolId, violation(
     'symbol-coverage',
     SymbolId,
     "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.",
+    "Add 'covered_by: TEST-xxx' for production coverage. If the requirement has specified_by a scenario, use verified_by(scenario,test) or validates(test,scenario). Direct verified_by(req,test) does not count when a scenario exists.",
     Source
 )) :-
     violation_source(SymbolId, symbol, Source).
@@ -718,7 +718,7 @@ strict_readiness_issue(
 strict_readiness_issue(
     ReqId,
     "Strict readiness: not-ready (strict-ready). Requirement has strict subject and property facts but no contradiction-ready matched pair, so contradiction checks still skip it.",
-    "Align constrains and requires_property on the same subject_key, and keep the requirement current if it should participate in contradiction checks"
+    "Ensure constrains and requires_property use the same subject_key, and keep the requirement current if it should participate in contradiction checks"
 ) :-
     kb_entity(ReqId, req, _),
     strict_readiness_level(ReqId, strict_ready).

package/src/kb.pl

@@ -10,6 +10,7 @@
     kb_log_entity_upsert/3,
     kb_retract_entity/1,
     kb_retract_entity/3,
+    kb_retract_entity_relationships/1,
     kb_entity/3,
     kb_entities_by_source/2,
     kb_assert_relationship/4,
@@ -279,9 +280,19 @@ kb_assert_entity_no_audit(Type, Props) :-
     % Execute RDF operations with mutex protection
     with_kb_mutex((
         % Create entity URI using prefix notation for namespace expansion
-        format(atom(EntityURI), 'kb:entity/~w', [Id]),
-        % Upsert semantics: remove any existing triples for this entity first.
-        rdf_retractall(EntityURI, _, _, Graph),
+        entity_id_to_uri(Id, EntityURI),
+        % Upsert semantics: remove only property triples, preserving relationships.
+        % Relationship triples have entity URI objects (kb:entity/...);
+        % property triples have typed literal objects (_^^xsd:...).
+        forall(
+            (   rdf(EntityURI, Prop, Obj, Graph),
+                (   atom(Obj)
+                ->  \+ entity_uri_to_id(Obj, _)
+                ;   true
+                )
+            ),
+            rdf_retractall(EntityURI, Prop, Obj, Graph)
+        ),
         % Store type as string literal to prevent URI interpretation
         atom_string(Type, TypeStr),
         rdf_assert(EntityURI, kb:type, TypeStr^^'http://www.w3.org/2001/XMLSchema#string', Graph),
@@ -292,6 +303,22 @@ kb_assert_entity_no_audit(Type, Props) :-
         )
     )).
 
+%% kb_retract_entity_relationships(+Id)
+% Remove all relationship triples for an entity, preserving property triples.
+% Used by projectStagedEntities to clear stale relationships before re-asserting.
+kb_retract_entity_relationships(Id) :-
+    kb_graph(Graph),
+    with_kb_mutex((
+        entity_id_to_uri(Id, EntityURI),
+        forall(
+            (   rdf(EntityURI, RelURI, TargetURI, Graph),
+                atom(TargetURI),
+                entity_uri_to_id(TargetURI, _)
+            ),
+            rdf_retractall(EntityURI, RelURI, TargetURI, Graph)
+        )
+    )).
+
 %% kb_log_entity_upsert(+ChangeKind, +Type, +Properties)
 % Append the audit entry for a successfully committed entity upsert.
 kb_log_entity_upsert(ChangeKind, Type, Props) :-
@@ -319,7 +346,7 @@ kb_retract_entity(Id, Type, AuditProps) :-
     kb_graph(Graph),
     with_kb_mutex((
         % Create entity URI
-        atom_concat('kb:entity/', Id, EntityURI),
+        entity_id_to_uri(Id, EntityURI),
         % Remove all triples for this entity
         rdf_retractall(EntityURI, _, _, Graph),
         % Log to audit
@@ -357,8 +384,8 @@ kb_entity(Id, Type, Props) :-
     % Find entity by pattern - use unquoted namespace term kb:type
     (   var(Id)
     ->  rdf(EntityURI, kb:type, TypeLiteral, Graph),
-        atom_concat('kb:entity/', Id, EntityURI)
-    ;   atom_concat('kb:entity/', Id, EntityURI),
+        entity_uri_to_id(EntityURI, Id)
+    ;   entity_id_to_uri(Id, EntityURI),
         rdf(EntityURI, kb:type, TypeLiteral, Graph)
     ),
     % Extract type - convert string literal to atom
@@ -430,12 +457,24 @@ kb_assert_relationship(RelType, FromId, ToId, Metadata) :-
 % leave partial audit residue.
 kb_assert_relationship_no_audit(RelType, FromId, ToId, _Metadata) :-
     kb_graph(Graph),
-    % Validate entities exist and relationship is valid
-    % Use once/1 to keep this predicate deterministic even if the store
-    % contains duplicate type triples from previous versions.
-    once(kb_entity(FromId, FromType, _)),
-    once(kb_entity(ToId, ToType, _)),
-    validate_relationship(RelType, FromType, ToType),
+    % Validate source entity exists
+    (   once(kb_entity(FromId, FromType, _))
+    ->  true
+    ;   throw(error(existence_error(entity, FromId),
+                context(kb_assert_relationship, 'Source entity does not exist')))
+    ),
+    % Validate target entity exists
+    (   once(kb_entity(ToId, ToType, _))
+    ->  true
+    ;   throw(error(existence_error(entity, ToId),
+                context(kb_assert_relationship, 'Target entity does not exist')))
+    ),
+    % Validate relationship type and direction
+    (   validate_relationship(RelType, FromType, ToType)
+    ->  true
+    ;   throw(error(type_error(relationship, RelType),
+                context(kb_assert_relationship, 'Invalid relationship: ~w from ~w to ~w'-[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.
@@ -444,8 +483,8 @@ kb_assert_relationship_no_audit(RelType, FromId, ToId, _Metadata) :-
     % Execute RDF operations with mutex protection
     with_kb_mutex((
         % Create entity URIs
-        atom_concat('kb:entity/', FromId, FromURI),
-        atom_concat('kb:entity/', ToId, ToURI),
+        entity_id_to_uri(FromId, FromURI),
+        entity_id_to_uri(ToId, ToURI),
         % Create relationship property URI (full URI to match saved/loaded RDF)
         kb_uri(BaseURI),
         atom_concat(BaseURI, RelType, RelURI),
@@ -528,14 +567,45 @@ kb_relationship(RelType, FromId, ToId) :-
     % Create relationship property URI (full URI to match loaded RDF)
     kb_uri(BaseURI),
     atom_concat(BaseURI, RelType, RelURI),
-    % Find matching relationships
+    kb_relationship_with_reluri(RelURI, Graph, FromId, ToId).
+
+kb_relationship_with_reluri(RelURI, Graph, FromId, ToId) :-
+    nonvar(FromId), nonvar(ToId), !,
+    entity_id_to_uri(FromId, FromURI),
+    entity_id_to_uri(ToId, ToURI),
+    rdf(FromURI, RelURI, ToURI, Graph).
+kb_relationship_with_reluri(RelURI, Graph, FromId, ToId) :-
+    nonvar(FromId), var(ToId), !,
+    entity_id_to_uri(FromId, FromURI),
     rdf(FromURI, RelURI, ToURI, Graph),
-    % Extract IDs from URIs
-    atom_concat('kb:entity/', FromId, FromURI),
-    atom_concat('kb:entity/', ToId, ToURI).
+    entity_uri_to_id(ToURI, ToId).
+kb_relationship_with_reluri(RelURI, Graph, FromId, ToId) :-
+    var(FromId), nonvar(ToId), !,
+    entity_id_to_uri(ToId, ToURI),
+    rdf(FromURI, RelURI, ToURI, Graph),
+    entity_uri_to_id(FromURI, FromId).
+kb_relationship_with_reluri(RelURI, Graph, FromId, ToId) :-
+    rdf(FromURI, RelURI, ToURI, Graph),
+    entity_uri_to_id(FromURI, FromId),
+    entity_uri_to_id(ToURI, ToId).
 
 % Helper predicates
 
+%% entity_id_to_uri(+Id, -URI)
+% Build the canonical entity URI used for RDF read/write.
+entity_id_to_uri(Id, URI) :-
+    format(atom(URI), 'kb:entity/~w', [Id]).
+
+%% entity_uri_to_id(+URI, -Id)
+% Extract entity ID from canonical or legacy entity URIs.
+entity_uri_to_id(URI, Id) :-
+    (   kb_uri(BaseURI),
+        atom_concat(BaseURI, 'entity/', Prefix),
+        atom_concat(Prefix, Id, URI)
+    ->  true
+    ;   atom_concat('kb:entity/', Id, URI)
+    ).
+
 %% store_property(+EntityURI, +Key, +Value, +Graph)
 % Store a property as an RDF triple with appropriate datatype.
 % All values are stored as typed string literals to avoid URI interpretation issues.
@@ -1212,8 +1282,8 @@ 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),
+    requirement_test_fallback_allowed(Req),
     test_satisfies_requirement_semantics(Test, Req).
 test_covers_requirement(Test, Req) :-
     kb_relationship(specified_by, Req, Scenario),