kibi-core 0.5.3 → 0.6.0

package/package.json

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

@@ -47,6 +47,15 @@ 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, predicate_name, string).
+entity_property(fact, predicate_namespace, string).
+entity_property(fact, predicate_arity, integer).
+entity_property(fact, argument_names, list).
+entity_property(fact, argument_types, list).
+entity_property(fact, argument_descriptions, list).
+entity_property(fact, aliases, list).
+entity_property(fact, examples, list).
+entity_property(fact, predicate_args, list).
 
 % Typed test verification fields - only valid for test entities
 entity_property(test, verification_scope, atom).

package/schema/relationships.pl

@@ -18,6 +18,7 @@ relationship_type(relates_to).
 relationship_type(supersedes).
 relationship_type(constrains).
 relationship_type(requires_property).
+relationship_type(requires_predicate).
 
 % valid_relationship(RelType, FromType, ToType).
 valid_relationship(depends_on, req, req).
@@ -38,6 +39,7 @@ valid_relationship(publishes, symbol, event).
 valid_relationship(consumes, symbol, event).
 valid_relationship(constrains, req, fact).
 valid_relationship(requires_property, req, fact).
+valid_relationship(requires_predicate, req, fact).
 
 %% supersedes(+NewAdrId, +OldAdrId)
 %% NewAdrId is the decision that replaces OldAdrId.

package/schema/validation.pl

@@ -88,6 +88,15 @@ 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(predicate_name).
+is_fact_only_field(predicate_namespace).
+is_fact_only_field(predicate_arity).
+is_fact_only_field(argument_names).
+is_fact_only_field(argument_types).
+is_fact_only_field(argument_descriptions).
+is_fact_only_field(aliases).
+is_fact_only_field(examples).
+is_fact_only_field(predicate_args).
 
 % is_test_only_field(+Key) - true if Key is a test-specific field
 is_test_only_field(verification_scope).
@@ -97,7 +106,7 @@ is_test_only_field(verification_perspective).
 validate_fact_shape(subject, Props) :-
     memberchk(subject_key=_Val, Props),
     valid_optional_fact_enums(Props),
-    valid_polarity_in_props(Props).
+    valid_strict_polarity_in_props(Props).
 validate_fact_shape(property_value, Props) :-
     memberchk(subject_key=_Subject, Props),
     memberchk(property_key=_Property, Props),
@@ -108,7 +117,7 @@ validate_fact_shape(property_value, Props) :-
     exactly_one_value_field(Props),
     value_type_matches_field(VT, Props),
     valid_optional_fact_enums(Props),
-    valid_polarity_in_props(Props).
+    valid_strict_polarity_in_props(Props).
 validate_fact_shape(observation, Props) :-
     valid_optional_fact_enums(Props),
     valid_polarity_in_props(Props).
@@ -116,9 +125,26 @@ 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(predicate_schema, Props) :-
+    memberchk(predicate_name=_Name, Props),
+    memberchk(predicate_arity=Arity, Props),
+    Arity >= 1,
+    memberchk(argument_names=ArgumentNames, Props),
+    memberchk(argument_types=ArgumentTypes, Props),
+    same_length(ArgumentNames, ArgumentTypes),
+    length(ArgumentNames, Arity),
+    valid_optional_fact_enums(Props),
+    valid_polarity_in_props(Props).
+validate_fact_shape(predicate, Props) :-
+    memberchk(predicate_name=_Name, Props),
+    memberchk(predicate_args=Args, Props),
+    Args \= [],
+    memberchk(canonical_key=_CanonicalKey, Props),
+    valid_optional_fact_enums(Props),
+    valid_predicate_polarity_in_props(Props).
 validate_fact_shape(Kind, _Props) :-
     % Unknown fact_kind values fail validation
-    \+ memberchk(Kind, [subject, property_value, observation, meta]),
+    \+ memberchk(Kind, [subject, property_value, observation, meta, predicate_schema, predicate]),
     fail.
 
 % valid_operator(+Op)
@@ -140,6 +166,12 @@ valid_value_type(bool).
 valid_polarity_in_props(Props) :-
     ( memberchk(polarity=P, Props) -> valid_polarity(P) ; true ).
 
+valid_strict_polarity_in_props(Props) :-
+    ( memberchk(polarity=P, Props) -> valid_strict_polarity(P) ; true ).
+
+valid_predicate_polarity_in_props(Props) :-
+    ( memberchk(polarity=P, Props) -> valid_predicate_polarity(P) ; true ).
+
 % valid_optional_fact_enums(+Props)
 % Validates enum-typed fact fields whenever they are present
 valid_optional_fact_enums(Props) :-
@@ -155,6 +187,14 @@ valid_optional_test_enums(Props) :-
 % valid_polarity(+P)
 valid_polarity(require).
 valid_polarity(forbid).
+valid_polarity(assert).
+valid_polarity(deny).
+
+valid_strict_polarity(require).
+valid_strict_polarity(forbid).
+
+valid_predicate_polarity(assert).
+valid_predicate_polarity(deny).
 
 % valid_verification_scope(+Scope)
 valid_verification_scope(unit).

package/src/checks.pl

@@ -33,7 +33,7 @@ required_fields([id, title, status, created_at, updated_at, source]).
 % Relationship types to check for dangling references
 all_relationship_types([
     depends_on, verified_by, validates, specified_by,
-    constrains, requires_property, supersedes, relates_to
+    constrains, requires_property, requires_predicate, supersedes, relates_to
 ]).
 
 %% check_all(-ViolationsDict)
@@ -387,9 +387,25 @@ strict_fact_shape_violation(violation(
     ->  fail  % Observation facts have no required fields beyond fact_kind
     ;   Kind = meta
     ->  fail  % Meta facts have no required fields beyond fact_kind
+    ;   Kind = predicate_schema
+    ->  findall(Msg, predicate_schema_shape_error(Props, Msg), Errors),
+        (   Errors = []
+        ->  fail
+        ;   Errors = [First|_],
+            Description = First,
+            Suggestion = "Ensure predicate_schema facts have predicate_name, predicate_arity, argument_names, and argument_types with matching arity"
+        )
+    ;   Kind = predicate
+    ->  findall(Msg, predicate_shape_error(Props, Msg), Errors),
+        (   Errors = []
+        ->  fail
+        ;   Errors = [First|_],
+            Description = First,
+            Suggestion = "Ensure predicate facts have predicate_name, non-empty predicate_args, canonical_key, and assert/deny polarity when present"
+        )
     ;   % Unknown fact_kind - report as malformed
         format(string(Description), "Unknown fact_kind: ~w", [Kind]),
-        Suggestion = "Use one of: subject, property_value, observation, meta"
+        Suggestion = "Use one of: subject, property_value, observation, meta, predicate_schema, predicate"
     ),
     
     (   memberchk(source=Source0, Props)
@@ -435,6 +451,68 @@ 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), !.
 
+predicate_schema_shape_error(Props, "Predicate schema fact missing required field: predicate_name") :-
+    \+ memberchk(predicate_name=_, Props).
+predicate_schema_shape_error(Props, "Predicate schema fact missing required field: predicate_arity") :-
+    memberchk(predicate_name=_, Props),
+    \+ memberchk(predicate_arity=_, Props).
+predicate_schema_shape_error(Props, "Predicate schema fact missing required field: argument_names") :-
+    memberchk(predicate_arity=_, Props),
+    \+ memberchk(argument_names=_, Props).
+predicate_schema_shape_error(Props, "Predicate schema fact missing required field: argument_types") :-
+    memberchk(argument_names=_, Props),
+    \+ memberchk(argument_types=_, Props).
+predicate_schema_shape_error(Props, "Predicate schema fact argument_names length must match predicate_arity") :-
+    memberchk(predicate_arity=RawArity, Props),
+    checks_normalize_integer(RawArity, Arity),
+    memberchk(argument_names=RawNames, Props),
+    checks_normalize_atom_list(RawNames, Names),
+    length(Names, Count),
+    Count =\= Arity.
+predicate_schema_shape_error(Props, "Predicate schema fact argument_types length must match predicate_arity") :-
+    memberchk(predicate_arity=RawArity, Props),
+    checks_normalize_integer(RawArity, Arity),
+    memberchk(argument_types=RawTypes, Props),
+    checks_normalize_atom_list(RawTypes, Types),
+    length(Types, Count),
+    Count =\= Arity.
+
+predicate_shape_error(Props, "Predicate fact missing required field: predicate_name") :-
+    \+ memberchk(predicate_name=_, Props).
+predicate_shape_error(Props, "Predicate fact missing required field: predicate_args") :-
+    memberchk(predicate_name=_, Props),
+    \+ memberchk(predicate_args=_, Props).
+predicate_shape_error(Props, "Predicate fact predicate_args must be non-empty") :-
+    memberchk(predicate_args=RawArgs, Props),
+    checks_normalize_atom_list(RawArgs, Args),
+    Args = [].
+predicate_shape_error(Props, "Predicate fact missing required field: canonical_key") :-
+    memberchk(predicate_args=_, Props),
+    \+ memberchk(canonical_key=_, Props).
+predicate_shape_error(Props, "Predicate fact polarity must be assert or deny") :-
+    memberchk(polarity=RawPolarity, Props),
+    normalize_term_atom(RawPolarity, Polarity),
+    \+ memberchk(Polarity, [assert, deny]).
+
+checks_normalize_integer(Raw, Integer) :-
+    (   Raw = ^^(Value, _Type)
+    ->  checks_normalize_integer(Value, Integer)
+    ;   integer(Raw)
+    ->  Integer = Raw
+    ;   atom(Raw)
+    ->  atom_number(Raw, Integer)
+    ;   string(Raw)
+    ->  number_string(Integer, Raw)
+    ).
+
+checks_normalize_atom_list(Raw, Atoms) :-
+    (   Raw = ^^(Value, _Type)
+    ->  checks_normalize_atom_list(Value, Atoms)
+    ;   is_list(Raw)
+    ->  maplist(normalize_term_atom, Raw, Atoms)
+    ;   Atoms = []
+    ).
+
 %% check_domain_contradictions(-Violations)
 % Finds all pairs of requirements with contradicting required properties.
 check_domain_contradictions(Violations) :-

package/src/kb.pl

@@ -39,6 +39,8 @@
     adr_chain/2,
     deprecated_no_successor/1,
     symbol_no_req_coverage/2,
+    predicate_schema/6,
+    predicate_fact/5,
     contradicting_reqs/3,
     check_req_contradiction/1,
     normalize_term_atom/2,
@@ -962,6 +964,57 @@ fact_property_tuple(FactId, Subject, Property, Op, ValType, Value, Unit, Scope,
     ( memberchk(scope=ScopeRaw, Props) -> normalize_term_atom(ScopeRaw, Scope) ; Scope = '' ),
     ( memberchk(polarity=PolarityRaw, Props) -> normalize_term_atom(PolarityRaw, Polarity) ; Polarity = require ).
 
+%% predicate_schema(+FactId, -Namespace, -Name, -Arity, -ArgumentNames, -ArgumentTypes)
+% Read one project-local ontology predicate schema fact.
+predicate_schema(FactId, Namespace, Name, Arity, ArgumentNames, ArgumentTypes) :-
+    kb_entity(FactId, fact, Props),
+    memberchk(fact_kind=KindRaw, Props),
+    normalize_term_atom(KindRaw, predicate_schema),
+    memberchk(predicate_name=NameRaw, Props),
+    normalize_term_atom(NameRaw, Name),
+    ( memberchk(predicate_namespace=NamespaceRaw, Props) -> normalize_term_atom(NamespaceRaw, Namespace) ; Namespace = default ),
+    memberchk(predicate_arity=ArityRaw, Props),
+    normalize_term_integer(ArityRaw, Arity),
+    memberchk(argument_names=ArgumentNamesRaw, Props),
+    normalize_term_atom_list(ArgumentNamesRaw, ArgumentNames),
+    memberchk(argument_types=ArgumentTypesRaw, Props),
+    normalize_term_atom_list(ArgumentTypesRaw, ArgumentTypes).
+
+%% predicate_fact(+FactId, -Namespace, -Name, -Args, -Polarity)
+% Read one ground ontology predicate fact.
+predicate_fact(FactId, Namespace, Name, Args, Polarity) :-
+    kb_entity(FactId, fact, Props),
+    memberchk(fact_kind=KindRaw, Props),
+    normalize_term_atom(KindRaw, predicate),
+    memberchk(predicate_name=NameRaw, Props),
+    normalize_term_atom(NameRaw, Name),
+    ( memberchk(predicate_namespace=NamespaceRaw, Props) -> normalize_term_atom(NamespaceRaw, Namespace) ; Namespace = default ),
+    memberchk(predicate_args=ArgsRaw, Props),
+    normalize_term_atom_list(ArgsRaw, Args),
+    ( memberchk(polarity=PolarityRaw, Props) -> normalize_term_atom(PolarityRaw, Polarity) ; Polarity = assert ).
+
+normalize_term_atom_list(List, Atoms) :-
+    is_list(List),
+    !,
+    maplist(normalize_term_atom, List, Atoms).
+normalize_term_atom_list(Raw, Atoms) :-
+    unwrap_rdf_value(Raw, Value),
+    is_list(Value),
+    !,
+    maplist(normalize_term_atom, Value, Atoms).
+
+normalize_term_integer(Raw, Integer) :-
+    unwrap_rdf_value(Raw, Value),
+    (   integer(Value)
+    ->  Integer = Value
+    ;   atom(Value)
+    ->  atom_number(Value, Integer)
+    ;   string(Value)
+    ->  number_string(Integer, Value)
+    ;   Value = ^^(Nested, _Type)
+    ->  normalize_term_integer(Nested, Integer)
+    ).
+
 %% fact_valid_interval(+FactId, -ValidFrom, -ValidTo)
 % Extract optional validity bounds for property_value facts.
 fact_valid_interval(FactId, ValidFrom, ValidTo) :-