kibi-core 0.5.0 → 0.5.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-core",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "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

@@ -15,7 +15,9 @@
     check_deprecated_adrs/1,        % Returns list of deprecated ADR violations
     check_domain_contradictions/1,  % Returns list of contradiction violations
     check_strict_fact_shape/1,      % Returns list of malformed strict fact violations
-    run_checks_json/0               % Entry point for JSON output
+    check_strict_req_fact_pairing/1,% Returns list of malformed strict req/fact pairing violations
+    run_checks_json/0,              % Entry point for JSON output
+    violation_id_text/2             % Extract text from entity ID term (exported for testing)
 ]).
 
 :- use_module(library(http/json)).
@@ -47,6 +49,7 @@ check_all(ViolationsDict) :-
     check_deprecated_adrs(DeprecatedADRs),
     check_domain_contradictions(Contradictions),
     check_strict_fact_shape(StrictFactShape),
+    check_strict_req_fact_pairing(StrictReqFactPairing),
     ViolationsDict = _{
         must_priority_coverage: MustPriority,
         symbol_coverage: SymbolCoverage,
@@ -56,7 +59,8 @@ check_all(ViolationsDict) :-
         required_fields: RequiredFields,
         deprecated_adr_no_successor: DeprecatedADRs,
         domain_contradictions: Contradictions,
-        strict_fact_shape: StrictFactShape
+        strict_fact_shape: StrictFactShape,
+        strict_req_fact_pairing: StrictReqFactPairing
     }.
 
 %% check_must_priority_coverage(-Violations)
@@ -412,7 +416,8 @@ property_value_shape_error(Props, "Property value fact has multiple value fields
     length(Fields, Count),
     Count > 1.
 property_value_shape_error(Props, "Property value fact value_type does not match value field") :-
-    memberchk(value_type=VT, Props),
+    memberchk(value_type=RawVT, Props),
+    normalize_term_atom(RawVT, VT),
     \+ value_type_matches_field(VT, Props).
 
 % is_value_field(+Field)
@@ -445,6 +450,138 @@ check_domain_contradictions(Violations) :-
         Violations
     ).
 
+%% check_strict_req_fact_pairing(-Violations)
+% Finds current requirements attempting strict-lane modeling with incomplete
+% subject/property pairing or wrong-lane fact targets.
+check_strict_req_fact_pairing(Violations) :-
+    findall(
+        Violation,
+        strict_req_fact_pairing_violation(Violation),
+        Violations0
+    ),
+    sort(Violations0, Violations).
+
+strict_req_fact_pairing_violation(violation(
+    'strict-req-fact-pairing',
+    ReqId,
+    Description,
+    Suggestion,
+    Source
+)) :-
+    strict_req_fact_pairing_issue(ReqId, Description, Suggestion),
+    violation_source(ReqId, req, Source).
+
+strict_req_fact_pairing_issue(
+    ReqId,
+    Description,
+    "Add a property_value fact via requires_property for the same subject_key"
+) :-
+    kb:current_req(ReqId),
+    kb_relationship(constrains, ReqId, SubjectFactId),
+    strict_req_fact_pairing_fact_kind(SubjectFactId, subject),
+    kb:fact_subject_key(SubjectFactId, SubjectKey),
+    \+ kb:effective_req_property_fact(
+        ReqId,
+        SubjectKey,
+        _PropertyFactId,
+        _PropertyKey,
+        _Operator,
+        _ValueType,
+        _Value,
+        _Unit,
+        _Scope,
+        _Polarity,
+        _ValidFrom,
+        _ValidTo
+    ),
+    format(
+        string(Description),
+        "Requirement constrains ~w (~w) but has no matching strict requires_property fact",
+        [SubjectFactId, SubjectKey]
+    ).
+
+strict_req_fact_pairing_issue(
+    ReqId,
+    Description,
+    "Add a subject fact via constrains for the same subject_key or remove the mismatched requires_property link"
+) :-
+    kb:current_req(ReqId),
+    kb_relationship(requires_property, ReqId, PropertyFactId),
+    strict_req_fact_pairing_fact_kind(PropertyFactId, property_value),
+    kb:fact_property_tuple(
+        PropertyFactId,
+        SubjectKey,
+        _PropertyKey,
+        _Operator,
+        _ValueType,
+        _Value,
+        _Unit,
+        _Scope,
+        _Polarity
+    ),
+    \+ kb:effective_req_property_fact(
+        ReqId,
+        SubjectKey,
+        PropertyFactId,
+        _MatchedPropertyKey,
+        _MatchedOperator,
+        _MatchedValueType,
+        _MatchedValue,
+        _MatchedUnit,
+        _MatchedScope,
+        _MatchedPolarity,
+        _MatchedValidFrom,
+        _MatchedValidTo
+    ),
+    format(
+        string(Description),
+        "Requirement requires_property ~w (~w) but has no matching strict subject fact via constrains",
+        [PropertyFactId, SubjectKey]
+    ).
+
+strict_req_fact_pairing_issue(
+    ReqId,
+    Description,
+    "Use a subject fact with constrains for contradiction-safe semantics; keep non-subject facts out of strict pairing"
+) :-
+    kb:current_req(ReqId),
+    kb_relationship(constrains, ReqId, FactId),
+    strict_req_fact_pairing_fact_kind(FactId, Kind),
+    Kind \= subject,
+    strict_req_fact_pairing_kind_label(Kind, KindLabel),
+    format(
+        string(Description),
+        "Requirement links ~w via constrains using ~w; contradiction-safe constrains links must target subject facts",
+        [FactId, KindLabel]
+    ).
+
+strict_req_fact_pairing_issue(
+    ReqId,
+    Description,
+    "Use a property_value fact with requires_property for contradiction-safe semantics; keep non-property facts out of strict pairing"
+) :-
+    kb:current_req(ReqId),
+    kb_relationship(requires_property, ReqId, FactId),
+    strict_req_fact_pairing_fact_kind(FactId, Kind),
+    Kind \= property_value,
+    strict_req_fact_pairing_kind_label(Kind, KindLabel),
+    format(
+        string(Description),
+        "Requirement links ~w via requires_property using ~w; contradiction-safe requires_property links must target property_value facts",
+        [FactId, KindLabel]
+    ).
+
+strict_req_fact_pairing_fact_kind(FactId, Kind) :-
+    kb_entity(FactId, fact, Props),
+    (   memberchk(fact_kind=RawKind, Props)
+    ->  normalize_term_atom(RawKind, Kind)
+    ;   Kind = legacy
+    ).
+
+strict_req_fact_pairing_kind_label(legacy, "a legacy fact without fact_kind").
+strict_req_fact_pairing_kind_label(Kind, Label) :-
+    format(string(Label), "a fact_kind=~w fact", [Kind]).
+
 %% run_checks_json
 % Entry point for JSON output. Prints all violations as JSON to stdout.
 run_checks_json :-
@@ -492,6 +629,7 @@ check_all_with_options(ViolationsDict, RequireAdr) :-
     check_deprecated_adrs(DeprecatedADRs),
     check_domain_contradictions(Contradictions),
     check_strict_fact_shape(StrictFactShape),
+    check_strict_req_fact_pairing(StrictReqFactPairing),
     ViolationsDict = _{
         must_priority_coverage: MustPriority,
         symbol_coverage: SymbolCoverage,
@@ -501,7 +639,8 @@ check_all_with_options(ViolationsDict, RequireAdr) :-
         required_fields: RequiredFields,
         deprecated_adr_no_successor: DeprecatedADRs,
         domain_contradictions: Contradictions,
-        strict_fact_shape: StrictFactShape
+        strict_fact_shape: StrictFactShape,
+        strict_req_fact_pairing: StrictReqFactPairing
     }.
 
 %% violations_dict_to_json(+ViolationsDict, -JsonDict)
@@ -552,8 +691,22 @@ violation_text(Val, Text) :-
     term_string(Val, Text).
 
 violation_id_text(Val, Text) :-
-    normalize_term_atom(Val, Atom),
-    atom_string(Atom, Text).
+    nonvar(Val),
+    Val =.. ['^^', Inner, _Type],
+    !,
+    violation_id_text(Inner, Text).
+violation_id_text(literal(type(_, Val)), Text) :-
+    !,
+    violation_id_text(Val, Text).
+violation_id_text(Val, Val) :-
+    string(Val),
+    !.
+violation_id_text(Val, Text) :-
+    atom(Val),
+    !,
+    atom_string(Val, Text).
+violation_id_text(Val, Text) :-
+    term_string(Val, Text).
 
 violation_source(EntityId, Type, Source) :-
     (   kb_entity(EntityId, Type, Props),

package/src/kb.pl

@@ -7,8 +7,9 @@
     with_kb_mutex/1,
     kb_assert_entity/2,
     kb_assert_entity_no_audit/2,
-    kb_log_entity_upsert/2,
+    kb_log_entity_upsert/3,
     kb_retract_entity/1,
+    kb_retract_entity/3,
     kb_entity/3,
     kb_entities_by_source/2,
     kb_assert_relationship/4,
@@ -254,8 +255,13 @@ load_kb_pl_files(Directory) :-
 % Assert an entity into the KB with audit logging.
 % Properties is a list of Key=Value pairs.
 kb_assert_entity(Type, Props) :-
+    memberchk(id=Id, Props),
+    (   once(kb_entity(Id, _, _))
+    ->  ChangeKind = updated
+    ;   ChangeKind = created
+    ),
     kb_assert_entity_no_audit(Type, Props),
-    kb_log_entity_upsert(Type, Props).
+    kb_log_entity_upsert(ChangeKind, Type, Props).
 
 %% kb_assert_entity_no_audit(+Type, +Properties)
 % Assert an entity RDF payload without recording audit side effects.
@@ -284,19 +290,30 @@ kb_assert_entity_no_audit(Type, Props) :-
         )
     )).
 
-%% kb_log_entity_upsert(+Type, +Properties)
+%% kb_log_entity_upsert(+ChangeKind, +Type, +Properties)
 % Append the audit entry for a successfully committed entity upsert.
-kb_log_entity_upsert(Type, Props) :-
+kb_log_entity_upsert(ChangeKind, Type, Props) :-
     memberchk(id=Id, Props),
+    memberchk(ChangeKind, [created, updated]),
     with_kb_mutex((
         get_time(Timestamp),
         format_time(atom(TS), '%FT%T%:z', Timestamp),
-        assert_changeset(TS, upsert, Id, Type-Props)
+        assert_changeset(TS, upsert, Id, Type-[change_kind=ChangeKind|Props])
     )).
 
 %% kb_retract_entity(+Id)
 % Remove an entity from the KB with audit logging.
 kb_retract_entity(Id) :-
+    (   once(kb_entity(Id, Type, Props))
+    ->  entity_delete_audit_props(Id, Props, AuditProps)
+    ;   Type = unknown,
+        AuditProps = [id=Id]
+    ),
+    kb_retract_entity(Id, Type, AuditProps).
+
+%% kb_retract_entity(+Id, +Type, +AuditProps)
+% Remove an entity from the KB and log the provided delete payload.
+kb_retract_entity(Id, Type, AuditProps) :-
     kb_graph(Graph),
     with_kb_mutex((
         % Create entity URI
@@ -306,9 +323,30 @@ kb_retract_entity(Id) :-
         % Log to audit
         get_time(Timestamp),
         format_time(atom(TS), '%FT%T%:z', Timestamp),
-        assert_changeset(TS, delete, Id, null)
+        assert_changeset(TS, delete, Id, Type-AuditProps)
     )).
 
+entity_delete_audit_props(Id, Props, AuditProps) :-
+    findall(Key=Value,
+        (   member(Key, [title, source, text_ref]),
+            memberchk(Key=RawValue, Props),
+            audit_property_value(RawValue, Value)
+        ),
+        OptionalProps),
+    AuditProps = [id=Id|OptionalProps].
+
+audit_property_value(RawValue, Value) :-
+    (   RawValue = ^^(Inner, _)
+    ->  Value = Inner
+    ;   RawValue = literal(type(_, Inner))
+    ->  Value = Inner
+    ;   RawValue = literal(lang(_, Inner))
+    ->  Value = Inner
+    ;   RawValue = literal(Inner)
+    ->  Value = Inner
+    ;   Value = RawValue
+    ).
+
 %% kb_entity(?Id, ?Type, ?Properties)
 % Query entities from the KB.
 % Properties is unified with a list of Key=Value pairs.
@@ -356,12 +394,18 @@ convert_legacy_prop(Prop, Prop, true).
 kb_entities_by_source(SourcePath, Ids) :-
     findall(Id,
         (kb_entity(Id, _Type, Props),
-         memberchk(source=RawSource, Props),
-         source_value_atom(RawSource, SourceAtom),
+         entity_source_atom(Props, SourceAtom),
          sub_atom(SourceAtom, _, _, _, SourcePath)),
         RawIds),
     sort(RawIds, Ids).
 
+entity_source_atom(Props, SourceAtom) :-
+    (   memberchk(sourceFile=RawSourceFile, Props)
+    ->  source_value_atom(RawSourceFile, SourceAtom)
+    ;   memberchk(source=RawSource, Props),
+        source_value_atom(RawSource, SourceAtom)
+    ).
+
 source_value_atom(Value, Atom) :-
     (   atom(Value)
     ->  Atom = Value

package/src/status.pl

@@ -61,7 +61,8 @@ synced_at(DataFile, SyncedAt) :-
     !,
     time_file(DataFile, Timestamp),
     format_time(atom(SyncedAt), '%FT%TZ', Timestamp).
-synced_at(_, @(null)).
+% Before the first successful sync there is no kb.rdf, so the public JSON contract must expose syncedAt: null.
+synced_at(_, null).
 
 freshness_state(DataFile, true, stale) :-
     exists_file(DataFile),