kibi-core 0.14.1 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-core",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "private": false,
   "description": "Core Prolog modules and RDF graph logic for Kibi",
   "type": "module",
@@ -8,7 +8,10 @@
     "node": ">=18"
   },
   "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

@@ -30,6 +30,9 @@ entity_property(_, severity, atom).
 entity_property(_, links, list).
 entity_property(_, text_ref, uri).
 entity_property(_, sourceFile, uri).
+% Provenance of any authored entity: a JSON object (kind, ref, approved_by,
+% recorded_at) naming who authored it and on what authority.
+entity_property(_, origin, list_or_json).
 entity_property(req, semantic_text, string).
 entity_property(req, logic_claims, list).
 entity_property(req, semantic_clauses, list).
@@ -39,6 +42,17 @@ entity_property(req, semantic_source_hash, string).
 entity_property(req, semantic_inventory, list_or_json).
 entity_property(req, proof_exempt, boolean).
 entity_property(req, proof_exempt_reason, string).
+% Human approval of an exception requirement (one that `exempts` another).
+% Only an approved exception makes a success scenario feasible.
+entity_property(req, approved_by, string).
+entity_property(req, approval_ref, string).
+% Why the requirement exists, in the words of whoever stated the intent.
+% Explanation only: it is never part of the checked meaning.
+entity_property(req, rationale, string).
+% Claim keys of the exempted requirement an exception waives (all when absent).
+entity_property(req, exempts_claims, list).
+% Intended outcome of a scenario: success, rejection or error.
+entity_property(scenario, expects, atom).
 
 % Typed fact fields - only valid for fact entities
 entity_property(fact, fact_kind, atom).
@@ -65,6 +79,9 @@ entity_property(fact, predicate_arity, integer).
 entity_property(fact, argument_names, list).
 entity_property(fact, argument_types, list).
 entity_property(fact, argument_descriptions, list).
+% Predicate-schema functional dependency: the named arguments determine the
+% remaining ones, so two atoms with equal keys describe the same fact.
+entity_property(fact, key_arguments, list).
 % Predicate-schema vocabularies are JSON objects serialized as strings.
 entity_property(fact, argument_constants, string).
 entity_property(fact, argument_aliases, string).
@@ -112,6 +129,7 @@ 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(Type, origin) :- entity_type(Type).
 optional_property(req, semantic_text).
 optional_property(req, logic_claims).
 optional_property(req, semantic_clauses).
@@ -121,6 +139,10 @@ optional_property(req, semantic_source_hash).
 optional_property(req, semantic_inventory).
 optional_property(req, proof_exempt).
 optional_property(req, proof_exempt_reason).
+optional_property(req, approved_by).
+optional_property(req, approval_ref).
+optional_property(req, rationale).
+optional_property(req, exempts_claims).
 optional_property(test, verification_scope).
 optional_property(test, verification_perspective).
 optional_property(test, proof_contract).

package/schema/relationships.pl

@@ -22,6 +22,8 @@ relationship_type(constrains).
 relationship_type(requires_property).
 relationship_type(requires_predicate).
 relationship_type(requires_rule).
+relationship_type(assumes).
+relationship_type(exempts).
 
 % valid_relationship(RelType, FromType, ToType).
 valid_relationship(depends_on, req, req).
@@ -45,6 +47,18 @@ valid_relationship(requires_property, req, fact).
 valid_relationship(requires_predicate, req, fact).
 valid_relationship(requires_rule, req, fact).
 
+%% assumes(+ScenarioId, +FactId)
+%% The scenario's outcome depends on the property_value fact holding (for
+%% example "the order total is 0"). Checked against current requirements by
+%% the scenario-feasibility rule.
+% implements REQ-kibi-scenario-feasibility-v2
+valid_relationship(assumes, scenario, fact).
+
+%% exempts(+ExceptionReqId, +BaseReqId)
+%% An approved exception requirement exempts the scenarios it specifies from
+%% BaseReqId's property constraints. BaseReqId stays current and unchanged.
+valid_relationship(exempts, req, req).
+
 %% supersedes(+NewAdrId, +OldAdrId)
 %% NewAdrId is the decision that replaces OldAdrId.
 %% OldAdrId's status should be archived or deprecated as a consequence.

package/schema/validation.pl

@@ -8,6 +8,7 @@
 
 :- use_module('entities.pl').
 :- use_module('relationships.pl').
+:- use_module(library(http/json)).
 
 % validate_entity(+Type, +Props:list)
 % Props is a list of Property=Value pairs (e.g. id=ID, title=Title)
@@ -19,7 +20,9 @@ validate_entity(Type, Props) :-
     % all properties have correct types
     forall(member(Key=Val, Props), validate_property_type(Type, Key, Val)),
     % validate entity-specific shape constraints
-    validate_entity_shape(Type, Props).
+    validate_entity_shape(Type, Props),
+    % provenance, when present, names a known origin kind
+    valid_origin_in_props(Props).
 
 % validate_relationship(+RelType, +From, +To)
 % From and To are pairs Type=Id or structures type(Type) - allow Type or Type=Id
@@ -105,6 +108,7 @@ 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(key_arguments).
 is_fact_only_field(argument_constants).
 is_fact_only_field(argument_aliases).
 is_fact_only_field(aliases).
@@ -156,6 +160,7 @@ validate_fact_shape(predicate_schema, Props) :-
     memberchk(argument_types=ArgumentTypes, Props),
     same_length(ArgumentNames, ArgumentTypes),
     length(ArgumentNames, Arity),
+    valid_key_arguments(Props, ArgumentNames),
     valid_optional_fact_enums(Props),
     valid_polarity_in_props(Props), !.
 validate_fact_shape(predicate, Props) :-
@@ -185,6 +190,24 @@ validate_fact_shape(Kind, _Props) :-
     \+ memberchk(Kind, [subject, property_value, observation, meta, predicate_schema, predicate, rule_schema, rule]),
     fail.
 
+% valid_key_arguments(+Props, +ArgumentNames)
+% Optional key_arguments must be a non-empty list of distinct declared
+% argument names.
+valid_key_arguments(Props, ArgumentNames) :-
+    (   memberchk(key_arguments=Keys, Props)
+    ->  is_list(Keys),
+        Keys \= [],
+        maplist(text_atom, ArgumentNames, NameAtoms),
+        maplist(text_atom, Keys, KeyAtoms),
+        sort(KeyAtoms, UniqueKeys),
+        same_length(KeyAtoms, UniqueKeys),
+        forall(member(Key, KeyAtoms), memberchk(Key, NameAtoms))
+    ;   true
+    ).
+
+text_atom(Value, Atom) :- atom(Value), !, Atom = Value.
+text_atom(Value, Atom) :- string(Value), atom_string(Atom, Value).
+
 % valid_operator(+Op)
 valid_operator(Op) :- memberchk(Op, [eq, neq, lt, lte, gt, gte]), !.
 
@@ -256,3 +279,24 @@ 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), !.
+
+% valid_origin_in_props(+Props)
+% Entity provenance travels as a JSON object string (or a dict). When present
+% its kind must be human, agent, migration or import.
+valid_origin_in_props(Props) :-
+    (   memberchk(origin=Raw, Props)
+    ->  origin_kind(Raw, Kind),
+        memberchk(Kind, [human, agent, migration, import])
+    ;   true
+    ).
+
+origin_kind(Raw, Kind) :-
+    (   is_dict(Raw)
+    ->  Dict = Raw
+    ;   (atom(Raw) ; string(Raw)),
+        catch(atom_json_dict(Raw, Dict, []), _, fail),
+        is_dict(Dict)
+    ),
+    get_dict(kind, Dict, RawKind),
+    (atom(RawKind) ; string(RawKind)),
+    atom_string(Kind, RawKind).