kibi-core 0.5.2 → 0.6.0

package/package.json

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

@@ -16,6 +16,7 @@
     check_domain_contradictions/1,  % Returns list of contradiction violations
     check_strict_fact_shape/1,      % Returns list of malformed strict fact violations
     check_strict_req_fact_pairing/1,% Returns list of malformed strict req/fact pairing violations
+    check_strict_readiness/1,       % Returns list of strict readiness audit violations
     run_checks_json/0,              % Entry point for JSON output
     violation_id_text/2             % Extract text from entity ID term (exported for testing)
 ]).
@@ -32,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)
@@ -50,6 +51,7 @@ check_all(ViolationsDict) :-
     check_domain_contradictions(Contradictions),
     check_strict_fact_shape(StrictFactShape),
     check_strict_req_fact_pairing(StrictReqFactPairing),
+    check_strict_readiness(StrictReadiness),
     ViolationsDict = _{
         must_priority_coverage: MustPriority,
         symbol_coverage: SymbolCoverage,
@@ -60,7 +62,8 @@ check_all(ViolationsDict) :-
         deprecated_adr_no_successor: DeprecatedADRs,
         domain_contradictions: Contradictions,
         strict_fact_shape: StrictFactShape,
-        strict_req_fact_pairing: StrictReqFactPairing
+        strict_req_fact_pairing: StrictReqFactPairing,
+        strict_readiness: StrictReadiness
     }.
 
 %% check_must_priority_coverage(-Violations)
@@ -384,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)
@@ -432,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) :-
@@ -445,7 +526,7 @@ check_domain_contradictions(Violations) :-
         ),
         (   contradicting_reqs(ReqA, ReqB, Reason),
             format(string(EntityId), "~w/~w", [ReqA, ReqB]),
-            Description = Reason
+            format(string(Description), "~w [strict-readiness: contradiction-ready]", [Reason])
         ),
         Violations
     ).
@@ -582,6 +663,118 @@ 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]).
 
+%% check_strict_readiness(-Violations)
+% Reports current strict-readiness levels for requirements that are still not
+% contradiction-ready. Legacy and prose-only requirements remain audit-only and
+% are intentionally not treated as contradictions.
+check_strict_readiness(Violations) :-
+    findall(
+        Violation,
+        strict_readiness_violation(Violation),
+        Violations0
+    ),
+    sort(Violations0, Violations).
+
+strict_readiness_violation(violation(
+    'strict-readiness',
+    ReqId,
+    Description,
+    Suggestion,
+    Source
+)) :-
+    strict_readiness_issue(ReqId, Description, Suggestion),
+    violation_source(ReqId, req, Source).
+
+strict_readiness_issue(
+    ReqId,
+    "Strict readiness: not-ready (prose-only). Requirement has no fact links, so contradiction checks skip it.",
+    "Add a subject fact via constrains and a property_value fact via requires_property to model contradiction-safe semantics"
+) :-
+    kb_entity(ReqId, req, _),
+    strict_readiness_level(ReqId, prose_only).
+
+strict_readiness_issue(
+    ReqId,
+    "Strict readiness: not-ready (traceable). Requirement is linked to facts only through legacy or non-strict links, so contradiction checks skip it.",
+    "Replace prose or legacy fact links with a subject fact via constrains and a property_value fact via requires_property"
+) :-
+    kb_entity(ReqId, req, _),
+    strict_readiness_level(ReqId, traceable).
+
+strict_readiness_issue(
+    ReqId,
+    Description,
+    "Add a matching property_value fact via requires_property for the same subject_key"
+) :-
+    kb_entity(ReqId, req, _),
+    strict_readiness_level(ReqId, has_subject),
+    strict_readiness_primary_subject(ReqId, SubjectFactId, SubjectKey),
+    format(
+        string(Description),
+        "Strict readiness: not-ready (has-subject). Requirement constrains ~w (~w) but has no matching strict requires_property fact, so contradiction checks skip it.",
+        [SubjectFactId, SubjectKey]
+    ).
+
+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"
+) :-
+    kb_entity(ReqId, req, _),
+    strict_readiness_level(ReqId, strict_ready).
+
+strict_readiness_level(ReqId, contradiction_ready) :-
+    kb:current_req(ReqId),
+    kb:effective_req_property_fact(
+        ReqId,
+        _SubjectKey,
+        _FactId,
+        _PropertyKey,
+        _Operator,
+        _ValueType,
+        _Value,
+        _Unit,
+        _Scope,
+        _Polarity,
+        _ValidFrom,
+        _ValidTo
+    ),
+    !.
+strict_readiness_level(ReqId, strict_ready) :-
+    strict_readiness_has_strict_subject(ReqId),
+    strict_readiness_has_strict_property(ReqId),
+    !.
+strict_readiness_level(ReqId, has_subject) :-
+    strict_readiness_has_strict_subject(ReqId),
+    !.
+strict_readiness_level(ReqId, traceable) :-
+    strict_readiness_has_fact_link(ReqId),
+    !.
+strict_readiness_level(_ReqId, prose_only).
+
+strict_readiness_has_fact_link(ReqId) :-
+    kb_relationship(constrains, ReqId, FactId),
+    kb_entity(FactId, fact, _),
+    !.
+strict_readiness_has_fact_link(ReqId) :-
+    kb_relationship(requires_property, ReqId, FactId),
+    kb_entity(FactId, fact, _),
+    !.
+
+strict_readiness_has_strict_subject(ReqId) :-
+    strict_readiness_primary_subject(ReqId, _FactId, _SubjectKey),
+    !.
+
+strict_readiness_primary_subject(ReqId, FactId, SubjectKey) :-
+    kb_relationship(constrains, ReqId, FactId),
+    strict_req_fact_pairing_fact_kind(FactId, subject),
+    kb:fact_subject_key(FactId, SubjectKey).
+
+strict_readiness_has_strict_property(ReqId) :-
+    kb_relationship(requires_property, ReqId, FactId),
+    strict_req_fact_pairing_fact_kind(FactId, property_value),
+    !.
+
 %% run_checks_json
 % Entry point for JSON output. Prints all violations as JSON to stdout.
 run_checks_json :-
@@ -630,6 +823,7 @@ check_all_with_options(ViolationsDict, RequireAdr) :-
     check_domain_contradictions(Contradictions),
     check_strict_fact_shape(StrictFactShape),
     check_strict_req_fact_pairing(StrictReqFactPairing),
+    check_strict_readiness(StrictReadiness),
     ViolationsDict = _{
         must_priority_coverage: MustPriority,
         symbol_coverage: SymbolCoverage,
@@ -640,7 +834,8 @@ check_all_with_options(ViolationsDict, RequireAdr) :-
         deprecated_adr_no_successor: DeprecatedADRs,
         domain_contradictions: Contradictions,
         strict_fact_shape: StrictFactShape,
-        strict_req_fact_pairing: StrictReqFactPairing
+        strict_req_fact_pairing: StrictReqFactPairing,
+        strict_readiness: StrictReadiness
     }.
 
 %% violations_dict_to_json(+ViolationsDict, -JsonDict)

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) :-