kibi-core 0.1.10 → 0.3.0

package/package.json

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

package/schema/entities.pl

@@ -29,6 +29,24 @@ entity_property(_, severity, atom).
 entity_property(_, links, list).
 entity_property(_, text_ref, uri).
 
+% Typed fact fields - only valid for fact entities
+entity_property(fact, fact_kind, atom).
+entity_property(fact, subject_key, string).
+entity_property(fact, property_key, string).
+entity_property(fact, operator, atom).
+entity_property(fact, value_type, atom).
+entity_property(fact, value_string, string).
+entity_property(fact, value_int, integer).
+entity_property(fact, value_number, number).
+entity_property(fact, value_bool, boolean).
+entity_property(fact, unit, string).
+entity_property(fact, scope, string).
+entity_property(fact, polarity, atom).
+entity_property(fact, closed_world, boolean).
+entity_property(fact, valid_from, datetime).
+entity_property(fact, valid_to, datetime).
+entity_property(fact, canonical_key, string).
+
 % Required properties for all entity types
 required_property(Type, id) :- entity_type(Type).
 required_property(Type, title) :- entity_type(Type).

package/schema/validation.pl

@@ -17,7 +17,9 @@ validate_entity(Type, Props) :-
     % required properties present
     forall(required_property(Type, P), memberchk(P=_Val, Props)),
     % all properties have correct types
-    forall(member(Key=Val, Props), validate_property_type(Type, Key, Val)).
+    forall(member(Key=Val, Props), validate_property_type(Type, Key, Val)),
+    % validate entity-specific shape constraints
+    validate_entity_shape(Type, Props).
 
 % validate_relationship(+RelType, +From, +To)
 % From and To are pairs Type=Id or structures type(Type) - allow Type or Type=Id
@@ -33,9 +35,8 @@ type_of(Type, Type) :- atom(Type), entity_type(Type), !.
 type_of(Type=_Id, Type) :- atom(Type), entity_type(Type), !.
 
 % validate_property_type(+EntityType, +Prop, +Value)
-validate_property_type(_Type, Prop, Value) :-
-    % find declared property type, default to atom
-    ( entity_property(_Any, Prop, Kind) -> true ; Kind = atom ),
+validate_property_type(Type, Prop, Value) :-
+    entity_property(Type, Prop, Kind),
     check_kind(Kind, Value), !.
 
 % check_kind(Kind, Value) succeeds if Value matches Kind
@@ -44,6 +45,115 @@ check_kind(string, V) :- string(V).
 check_kind(datetime, V) :- string(V). % accept ISO strings for now
 check_kind(list, V) :- is_list(V).
 check_kind(uri, V) :- string(V).
+check_kind(integer, V) :- integer(V).
+check_kind(number, V) :- number(V).
+check_kind(boolean, true).
+check_kind(boolean, false).
 
 % Fallback false
 check_kind(_, _) :- fail.
+
+% validate_entity_shape(+Type, +Props)
+% Validates entity-specific shape constraints (e.g., strict fact shapes)
+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(Type, Props) :-
+    Type \= fact,
+    % Non-fact entities cannot have fact-only fields
+    forall(member(Key=_Val, Props), \+ is_fact_only_field(Key)).
+
+% is_fact_only_field(+Key) - true if Key is a fact-specific field
+is_fact_only_field(fact_kind).
+is_fact_only_field(subject_key).
+is_fact_only_field(property_key).
+is_fact_only_field(operator).
+is_fact_only_field(value_type).
+is_fact_only_field(value_string).
+is_fact_only_field(value_int).
+is_fact_only_field(value_number).
+is_fact_only_field(value_bool).
+is_fact_only_field(unit).
+is_fact_only_field(scope).
+is_fact_only_field(polarity).
+is_fact_only_field(closed_world).
+is_fact_only_field(valid_from).
+is_fact_only_field(valid_to).
+is_fact_only_field(canonical_key).
+
+% validate_fact_shape(+Kind, +Props)
+validate_fact_shape(subject, Props) :-
+    memberchk(subject_key=_Val, Props),
+    valid_optional_fact_enums(Props),
+    valid_polarity_in_props(Props).
+validate_fact_shape(property_value, Props) :-
+    memberchk(subject_key=_Subject, Props),
+    memberchk(property_key=_Property, Props),
+    memberchk(operator=Op, Props),
+    valid_operator(Op),
+    memberchk(value_type=VT, Props),
+    valid_value_type(VT),
+    exactly_one_value_field(Props),
+    value_type_matches_field(VT, Props),
+    valid_optional_fact_enums(Props),
+    valid_polarity_in_props(Props).
+validate_fact_shape(observation, Props) :-
+    valid_optional_fact_enums(Props),
+    valid_polarity_in_props(Props).
+validate_fact_shape(meta, Props) :-
+    % Meta facts are allowed but don't require full strict property tuple yet
+    valid_optional_fact_enums(Props),
+    valid_polarity_in_props(Props).
+validate_fact_shape(Kind, _Props) :-
+    % Unknown fact_kind values fail validation
+    \+ memberchk(Kind, [subject, property_value, observation, meta]),
+    fail.
+
+% valid_operator(+Op)
+valid_operator(eq).
+valid_operator(neq).
+valid_operator(lt).
+valid_operator(lte).
+valid_operator(gt).
+valid_operator(gte).
+
+% valid_value_type(+VT)
+valid_value_type(string).
+valid_value_type(int).
+valid_value_type(number).
+valid_value_type(bool).
+
+% valid_polarity_in_props(+Props)
+% Validates polarity if present; succeeds if no polarity in props
+valid_polarity_in_props(Props) :-
+    ( memberchk(polarity=P, Props) -> valid_polarity(P) ; true ).
+
+% valid_optional_fact_enums(+Props)
+% Validates enum-typed fact fields whenever they are present
+valid_optional_fact_enums(Props) :-
+    ( memberchk(operator=Op, Props) -> valid_operator(Op) ; true ),
+    ( memberchk(value_type=VT, Props) -> valid_value_type(VT) ; true ).
+
+% valid_polarity(+P)
+valid_polarity(require).
+valid_polarity(forbid).
+
+% exactly_one_value_field(+Props)
+exactly_one_value_field(Props) :-
+    findall(F, (member(F=_, Props), is_value_field(F)), Fields),
+    length(Fields, 1).
+
+% is_value_field(+Field)
+is_value_field(value_string).
+is_value_field(value_int).
+is_value_field(value_number).
+is_value_field(value_bool).
+
+% value_type_matches_field(+ValueType, +Props)
+% Ensures that value_type matches the actual value field present
+value_type_matches_field(string, Props) :- memberchk(value_string=_, Props), !.
+value_type_matches_field(int, Props) :- memberchk(value_int=_, Props), !.
+value_type_matches_field(number, Props) :- memberchk(value_number=_, Props), !.
+value_type_matches_field(bool, Props) :- memberchk(value_bool=_, Props), !.

package/src/checks.pl

@@ -14,6 +14,7 @@
     check_required_fields/1,        % Returns list of missing required field violations
     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
 ]).
 
@@ -45,6 +46,7 @@ check_all(ViolationsDict) :-
     check_required_fields(RequiredFields),
     check_deprecated_adrs(DeprecatedADRs),
     check_domain_contradictions(Contradictions),
+    check_strict_fact_shape(StrictFactShape),
     ViolationsDict = _{
         must_priority_coverage: MustPriority,
         symbol_coverage: SymbolCoverage,
@@ -53,7 +55,8 @@ check_all(ViolationsDict) :-
         no_cycles: Cycles,
         required_fields: RequiredFields,
         deprecated_adr_no_successor: DeprecatedADRs,
-        domain_contradictions: Contradictions
+        domain_contradictions: Contradictions,
+        strict_fact_shape: StrictFactShape
     }.
 
 %% check_must_priority_coverage(-Violations)
@@ -334,6 +337,95 @@ deprecated_adr_violation(violation(
     ;   Source = ""
     ).
 
+%% check_strict_fact_shape(-Violations)
+% Finds all strict facts (with fact_kind) that have malformed shape.
+% Only checks facts with fact_kind present; legacy facts without fact_kind are ignored.
+% implements REQ-006
+check_strict_fact_shape(Violations) :-
+    findall(
+        Violation,
+        strict_fact_shape_violation(Violation),
+        Violations0
+    ),
+    sort(Violations0, Violations).
+
+strict_fact_shape_violation(violation(
+    'strict-fact-shape',
+    FactId,
+    Description,
+    Suggestion,
+    Source
+)) :-
+    kb_entity(FactId, fact, Props),
+    memberchk(fact_kind=RawKind, Props),  % Only check facts with fact_kind
+    normalize_term_atom(RawKind, Kind),   % Handle typed literals like ^^(subject, xsd:string)
+    
+    % Check for malformed shape based on fact kind
+    (   Kind = subject
+    ->  (   memberchk(subject_key=_, Props)
+        ->  fail  % Well-formed, no violation
+        ;   Description = "Subject fact missing required field: subject_key",
+            Suggestion = "Add subject_key to define the subject domain key"
+        )
+    ;   Kind = property_value
+    ->  findall(Msg, property_value_shape_error(Props, Msg), Errors),
+        (   Errors = []
+        ->  fail  % Well-formed, no violation
+        ;   Errors = [First|_],
+            Description = First,
+            Suggestion = "Ensure property_value facts have subject_key, property_key, operator, value_type, and exactly one value field"
+        )
+    ;   Kind = observation
+    ->  fail  % Observation facts have no required fields beyond fact_kind
+    ;   Kind = meta
+    ->  fail  % Meta facts have no required fields beyond fact_kind
+    ;   % Unknown fact_kind - report as malformed
+        format(string(Description), "Unknown fact_kind: ~w", [Kind]),
+        Suggestion = "Use one of: subject, property_value, observation, meta"
+    ),
+    
+    (   memberchk(source=Source0, Props)
+    ->  normalize_term_atom(Source0, Source)
+    ;   Source = ""
+    ).
+
+% property_value_shape_error(+Props, -ErrorMsg)
+% Returns an error message if the property_value fact has a shape error.
+property_value_shape_error(Props, "Property value fact missing required field: subject_key") :-
+    \+ memberchk(subject_key=_, Props).
+property_value_shape_error(Props, "Property value fact missing required field: property_key") :-
+    memberchk(subject_key=_, Props),
+    \+ memberchk(property_key=_, Props).
+property_value_shape_error(Props, "Property value fact missing required field: operator") :-
+    memberchk(property_key=_, Props),
+    \+ memberchk(operator=_, Props).
+property_value_shape_error(Props, "Property value fact missing required field: value_type") :-
+    memberchk(operator=_, Props),
+    \+ memberchk(value_type=_, Props).
+property_value_shape_error(Props, "Property value fact missing value field (value_string, value_int, value_number, or value_bool)") :-
+    memberchk(value_type=_, Props),
+    \+ (memberchk(value_string=_, Props); memberchk(value_int=_, Props); 
+        memberchk(value_number=_, Props); memberchk(value_bool=_, Props)).
+property_value_shape_error(Props, "Property value fact has multiple value fields (should have exactly one)") :-
+    findall(F, (member(F=_, Props), is_value_field(F)), 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),
+    \+ value_type_matches_field(VT, Props).
+
+% is_value_field(+Field)
+is_value_field(value_string).
+is_value_field(value_int).
+is_value_field(value_number).
+is_value_field(value_bool).
+
+% value_type_matches_field(+ValueType, +Props)
+value_type_matches_field(string, Props) :- memberchk(value_string=_, Props), !.
+value_type_matches_field(int, Props) :- memberchk(value_int=_, Props), !.
+value_type_matches_field(number, Props) :- memberchk(value_number=_, Props), !.
+value_type_matches_field(bool, Props) :- memberchk(value_bool=_, Props), !.
+
 %% check_domain_contradictions(-Violations)
 % Finds all pairs of requirements with contradicting required properties.
 check_domain_contradictions(Violations) :-
@@ -398,6 +490,7 @@ check_all_with_options(ViolationsDict, RequireAdr) :-
     check_required_fields(RequiredFields),
     check_deprecated_adrs(DeprecatedADRs),
     check_domain_contradictions(Contradictions),
+    check_strict_fact_shape(StrictFactShape),
     ViolationsDict = _{
         must_priority_coverage: MustPriority,
         symbol_coverage: SymbolCoverage,
@@ -406,7 +499,8 @@ check_all_with_options(ViolationsDict, RequireAdr) :-
         no_cycles: Cycles,
         required_fields: RequiredFields,
         deprecated_adr_no_successor: DeprecatedADRs,
-        domain_contradictions: Contradictions
+        domain_contradictions: Contradictions,
+        strict_fact_shape: StrictFactShape
     }.
 
 %% violations_dict_to_json(+ViolationsDict, -JsonDict)