kibi-core 0.8.1 → 0.9.1

package/src/kb.pl

@@ -7,6 +7,7 @@
     with_kb_mutex/1,
     kb_assert_entity/2,
     kb_assert_entity_no_audit/2,
+    kb_commit_upsert/5,
     kb_log_entity_upsert/3,
     kb_retract_entity/1,
     kb_retract_entity/3,
@@ -43,6 +44,7 @@
     predicate_schema/6,
     predicate_fact/5,
     contradicting_reqs/3,
+    req_conflict_witness/3,
     check_req_contradiction/1,
     normalize_term_atom/2,
     normalize_term_atom_list/2,
@@ -111,7 +113,10 @@ kb_attach(Directory) :-
     atom_concat(Directory, '/audit.log', AuditLog),
     (   db_attached(AuditLog)
     ->  true  % Already attached
-    ;   db_attach(AuditLog, [])
+    ;   % Close the journal stream after each write.  The default `flush`
+        % mode retains an exclusive write lock for the lifetime of a
+        % long-running MCP process and blocks writers in other runtimes.
+        db_attach(AuditLog, [sync(close)])
     ),
     % Track attachment state
     assert(kb_attached(Directory)),
@@ -171,12 +176,18 @@ kb_save_locked(Directory) :-
     catch(
         (
             ensure_snapshot_current(DataFile),
+            kb_stage(snapshot_save),
             save_rdf_snapshot(TempFile),
+            kb_stage(audit_sync),
+            sync_audit_log,
+            % Keep the durable RDF rename after audit synchronization.  The
+            % temporary snapshot can be discarded if an audit-stage failure
+            % occurs, so a failed commit cannot publish new RDF state.
+            kb_stage(snapshot_save),
             rename_file(TempFile, DataFile),
             current_data_stamp(DataFile, UpdatedStamp),
             retractall(kb_attached_snapshot(_)),
-            assert(kb_attached_snapshot(UpdatedStamp)),
-            sync_audit_log
+            assert(kb_attached_snapshot(UpdatedStamp))
         ),
         Error,
         (
@@ -304,6 +315,109 @@ kb_assert_entity_no_audit(Type, Props) :-
         )
     )).
 
+%% kb_commit_upsert(+Type, +Properties, +Relationships, +SkipContradiction, -ChangeKind)
+% Commit an entity upsert, its relationships, audit entries, and RDF snapshot
+% as one bounded operation.  The branch lock is held before any RDF mutation,
+% so concurrent runtimes cannot observe or publish an intermediate upsert.
+% Relationships use rel(Type, FromId, ToId, Metadata) terms.  Metadata is
+% retained for the caller's serialization contract; the audit schema records
+% only the relationship endpoints and type, as before.
+kb_commit_upsert(Type, Props, Relationships, SkipContradiction, ChangeKind) :-
+    memberchk(id=Id, Props),
+    memberchk(SkipContradiction, [true, false]),
+    kb_attached(Directory),
+    atom_concat(Directory, '/kb.rdf', DataFile),
+    kb_stage(runtime),
+    kb_runtime_diagnostic,
+    % Emit the lock marker before waiting so a timeout identifies a branch
+    % lock held by another runtime instead of reporting only the prior stage.
+    kb_stage(lock),
+    with_kb_file_lock(Directory, (
+        audit_store_writable,
+        ensure_snapshot_current(DataFile),
+        upsert_change_kind(Id, ChangeKind),
+        rdf_transaction((
+            kb_stage(rdf_mutation),
+            kb_assert_entity_no_audit(Type, Props),
+            kb_commit_relationships_no_audit(Relationships),
+            kb_maybe_check_req_contradiction(Type, Id, SkipContradiction),
+            kb_stage(entity_audit),
+            kb_log_entity_upsert(ChangeKind, Type, Props),
+            kb_stage(relationship_audit),
+            kb_commit_relationship_audits(Relationships),
+            kb_save_locked(Directory)
+        ))
+    )).
+
+upsert_change_kind(Id, updated) :-
+    once(kb_entity(Id, _, _)),
+    !.
+upsert_change_kind(_, created).
+
+kb_commit_relationships_no_audit([]).
+kb_commit_relationships_no_audit([
+    rel(RelType, FromId, ToId, Metadata)|Rest
+]) :-
+    kb_assert_relationship_no_audit(RelType, FromId, ToId, Metadata),
+    kb_commit_relationships_no_audit(Rest).
+
+kb_maybe_check_req_contradiction(req, Id, false) :-
+    !,
+    kb_stage(contradiction_check),
+    check_req_contradiction(Id).
+kb_maybe_check_req_contradiction(_, _, _).
+
+kb_commit_relationship_audits([]).
+kb_commit_relationship_audits([
+    rel(RelType, FromId, ToId, _Metadata)|Rest
+]) :-
+    kb_log_relationship_upsert(RelType, FromId, ToId, []),
+    kb_commit_relationship_audits(Rest).
+
+% Probe the existing journal without waiting.  A process running code from
+% before the sync(close) fix may still retain the journal's write lock; fail
+% before touching RDF so callers receive a safe, retryable diagnostic.
+audit_store_writable :-
+    kb_audit_db(AuditLog),
+    (   exists_file(AuditLog)
+    ->  catch(
+        setup_call_cleanup(
+                open(AuditLog, append, Stream,
+                     [lock(write), wait(false), encoding(utf8)]),
+                true,
+                close(Stream)
+            ),
+            Error,
+            throw(error(permission_error(lock, audit_log, AuditLog),
+                        context(kb_commit_upsert/5, Error)))
+        )
+    ;   true
+    ).
+
+% Reserved stderr markers are consumed by PrologProcess diagnostics and never
+% form part of the JSON result.  They make timeout errors stage-specific even
+% when the child is blocked inside a filesystem primitive.
+kb_stage(Stage) :-
+    format(user_error, '__KIBI_STAGE__:~w~n', [Stage]),
+    flush_output(user_error).
+
+kb_runtime_diagnostic :-
+    (   current_prolog_flag(pid, Pid) -> true ; Pid = unknown ),
+    (   kb_audit_db(AuditLog) -> true ; AuditLog = unknown ),
+    kb_environment_value('KIBI_RUNTIME_NAME', RuntimeName),
+    kb_environment_value('KIBI_RUNTIME_VERSION', RuntimeVersion),
+    kb_environment_value('KIBI_PACKAGE_VERSIONS', PackageVersions),
+    format(user_error,
+           '__KIBI_RUNTIME__:pid=~w;audit=~w;runtime=~w@~w;packages=~w~n',
+           [Pid, AuditLog, RuntimeName, RuntimeVersion, PackageVersions]),
+    flush_output(user_error).
+
+kb_environment_value(Name, Value) :-
+    (   getenv(Name, Value)
+    ->  true
+    ;   Value = unknown
+    ).
+
 %% kb_retract_entity_relationships(+Id)
 % Remove all relationship triples for an entity, preserving property triples.
 % Used by projectStagedEntities to clear stale relationships before re-asserting.
@@ -358,7 +472,7 @@ kb_retract_entity(Id, Type, AuditProps) :-
 
 entity_delete_audit_props(Id, Props, AuditProps) :-
     findall(Key=Value,
-        (   member(Key, [title, source, text_ref]),
+        (   member(Key, [title, source, text_ref, semantic_text]),
             memberchk(Key=RawValue, Props),
             audit_property_value(RawValue, Value)
         ),
@@ -398,7 +512,7 @@ kb_entity(Id, Type, Props) :-
         atom_concat(BaseURI, type, TypeURI),
         PropURI \= TypeURI,
         uri_to_key(PropURI, Key),
-        literal_to_value(ValueLiteral, Value)
+        literal_to_value(Key, ValueLiteral, Value)
 ), Props).
 
 % Fallback: read from legacy entity/4 facts loaded from .pl files
@@ -625,7 +739,7 @@ store_property(EntityURI, Key, Value, Graph) :-
 % Key-aware: typed fact fields get specific XSD datatypes.
 value_to_literal(Key, Value, Literal) :-
     % Typed fact fields with specific XSD datatypes
-    (   Key == value_int, integer(Value)
+    (   integer_property_key(Key), integer(Value)
     ->  Literal = Value^^'http://www.w3.org/2001/XMLSchema#integer'
     ;   Key == value_number, number(Value)
     ->  Literal = Value^^'http://www.w3.org/2001/XMLSchema#decimal'
@@ -643,9 +757,29 @@ value_to_literal(Key, Value, Literal) :-
         Literal = Str^^'http://www.w3.org/2001/XMLSchema#string'
     ).
 
-%% literal_to_value(+Literal, -Value)
-% Extract value from RDF literal, parse list syntax back to Prolog lists.
-literal_to_value(Literal, Value) :-
+integer_property_key(Key) :-
+    memberchk(Key, [
+        value_int,
+        predicate_arity,
+        claim_span_start,
+        claim_span_end,
+        sourceLine,
+        sourceColumn,
+        sourceEndLine,
+        sourceEndColumn
+    ]).
+
+%% literal_to_value(+Key, +Literal, -Value)
+% Extract a property value from an RDF literal. JSON-backed fields must remain
+% intact: JSON arrays are also valid Prolog list syntax, but parsing them as
+% Prolog terms corrupts their object entries before the JSON decoder sees them.
+literal_to_value(semantic_inventory, Literal, Value) :-
+    !,
+    structured_literal_value(Literal, Value).
+literal_to_value(verification_receipts, Literal, Value) :-
+    !,
+    structured_literal_value(Literal, Value).
+literal_to_value(_Key, Literal, Value) :-
     (   % Handle ^^/2 functor (RDF typed literal shorthand)
         Literal = ^^(StrVal, 'http://www.w3.org/2001/XMLSchema#string')
     ->  (   % Preserve RDF typed literal functor for string values so callers
@@ -678,6 +812,12 @@ literal_to_value(Literal, Value) :-
     ;   Value = Literal
     ).
 
+structured_literal_value(^^(Value, _), Value) :- !.
+structured_literal_value(literal(type(_, Value)), Value) :- !.
+structured_literal_value(literal(lang(_, Value)), Value) :- !.
+structured_literal_value(literal(Value), Value) :- !.
+structured_literal_value(Value, Value).
+
 %% literal_to_atom(+Literal, -Atom)
 % Convert RDF literal to atom (for type field).
 literal_to_atom(Literal, Atom) :-
@@ -979,19 +1119,21 @@ current_req(Id) :-
 % semantic conflicts (same subject/property but incompatible values or polarities).
 % Checks in order of specificity: polarity conflicts, then value conflicts.
 contradicting_reqs(ReqA, ReqB, Reason) :-
-    current_req(ReqA),
-    current_req(ReqB),
-    ReqA @< ReqB,
-    req_conflict(ReqA, ReqB, Reason).
+    req_conflict_witness(ReqA, ReqB, Witness),
+    Reason = Witness.reason.
 
 %% ------------------------------------------------------------------
 %% Semantic Contradiction Helpers (Task 4)
 %% ------------------------------------------------------------------
 
-%% req_conflict(+ReqA, +ReqB, -Reason)
-% Detects conflicts between requirements via shared subject facts and
-% incompatible property_value facts linked through requires_property.
-req_conflict(ReqA, ReqB, Reason) :-
+%% req_conflict_witness(+ReqA, +ReqB, -Witness)
+% Return exact, source-bound evidence for one proven strict or predicate
+% contradiction.  This remains deliberately syntactic: differently shaped
+% terms are never treated as equivalent merely because their prose is similar.
+req_conflict_witness(ReqA, ReqB, Witness) :-
+    current_req(ReqA),
+    current_req(ReqB),
+    ReqA @< ReqB,
     kb_relationship(constrains, ReqA, SubjectFactA),
     kb_relationship(constrains, ReqB, SubjectFactB),
     fact_subject_key(SubjectFactA, SubjectKey),
@@ -1005,8 +1147,23 @@ req_conflict(ReqA, ReqB, Reason) :-
                           OpB, ValTypeB, ValB, UnitB, ScopeB, PolarityB, Reason)
     ;   property_conflict(SubjectKey, PropertyKey, OpA, ValTypeA, ValA, UnitA, PolarityA,
                           OpB, ValTypeB, ValB, UnitB, PolarityB, Reason)
-    ).
-req_conflict(ReqA, ReqB, Reason) :-
+    ),
+    property_conflict_side(ReqA, FactA, SubjectKey, PropertyKey, OpA, ValTypeA, ValA, UnitA, ScopeA, PolarityA, ValidFromA, ValidToA, Left),
+    property_conflict_side(ReqB, FactB, SubjectKey, PropertyKey, OpB, ValTypeB, ValB, UnitB, ScopeB, PolarityB, ValidFromB, ValidToB, Right),
+    Witness = _{
+        kind: strict_property,
+        status: contradiction,
+        requirements: [ReqA, ReqB],
+        reason: Reason,
+        subjectKey: SubjectKey,
+        propertyKey: PropertyKey,
+        left: Left,
+        right: Right
+    }.
+req_conflict_witness(ReqA, ReqB, Witness) :-
+    current_req(ReqA),
+    current_req(ReqB),
+    ReqA @< ReqB,
     effective_req_predicate(ReqA, FactA, Namespace, Name, Args, PolarityA),
     effective_req_predicate(ReqB, FactB, Namespace, Name, Args, PolarityB),
     FactA \= FactB,
@@ -1016,6 +1173,86 @@ req_conflict(ReqA, ReqB, Reason) :-
         string(Reason),
         "Predicate conflict on ~w:~w(~w): ~w asserts ~w while ~w asserts ~w",
         [Namespace, Name, ArgsText, ReqA, PolarityA, ReqB, PolarityB]
+    ),
+    predicate_conflict_side(ReqA, FactA, Namespace, Name, Args, PolarityA, Left),
+    predicate_conflict_side(ReqB, FactB, Namespace, Name, Args, PolarityB, Right),
+    length(Args, Arity),
+    findall(SchemaId, predicate_schema(SchemaId, Namespace, Name, Arity, _ArgumentNames, _ArgumentTypes), SchemaIds0),
+    sort(SchemaIds0, SchemaIds),
+    Witness = _{
+        kind: predicate,
+        status: contradiction,
+        requirements: [ReqA, ReqB],
+        reason: Reason,
+        predicateNamespace: Namespace,
+        predicateName: Name,
+        predicateArgs: Args,
+        schemaIds: SchemaIds,
+        left: Left,
+        right: Right
+    }.
+
+property_conflict_side(ReqId, FactId, SubjectKey, PropertyKey, Operator, ValueType, Value, Unit, Scope, Polarity, ValidFrom, ValidTo, Side) :-
+    entity_evidence_source(ReqId, req, RequirementSource),
+    fact_evidence_fields(FactId, FactSource, ClaimKey, ClaimText, _CanonicalKey),
+    Side = _{
+        requirementId: ReqId,
+        requirementSource: RequirementSource,
+        factId: FactId,
+        factSource: FactSource,
+        claimKey: ClaimKey,
+        claimText: ClaimText,
+        term: _{
+            subjectKey: SubjectKey,
+            propertyKey: PropertyKey,
+            operator: Operator,
+            valueType: ValueType,
+            value: Value,
+            unit: Unit,
+            scope: Scope,
+            polarity: Polarity,
+            validFrom: ValidFrom,
+            validTo: ValidTo
+        }
+    }.
+
+predicate_conflict_side(ReqId, FactId, Namespace, Name, Args, Polarity, Side) :-
+    entity_evidence_source(ReqId, req, RequirementSource),
+    fact_evidence_fields(FactId, FactSource, ClaimKey, ClaimText, CanonicalKey),
+    Side = _{
+        requirementId: ReqId,
+        requirementSource: RequirementSource,
+        factId: FactId,
+        factSource: FactSource,
+        claimKey: ClaimKey,
+        claimText: ClaimText,
+        term: _{
+            namespace: Namespace,
+            name: Name,
+            args: Args,
+            polarity: Polarity,
+            canonicalKey: CanonicalKey
+        }
+    }.
+
+entity_evidence_source(EntityId, Type, Source) :-
+    kb_entity(EntityId, Type, Props),
+    (memberchk(source=RawSource, Props) -> evidence_term_atom(RawSource, Source) ; Source = '').
+
+fact_evidence_fields(FactId, Source, ClaimKey, ClaimText, CanonicalKey) :-
+    kb_entity(FactId, fact, Props),
+    (memberchk(source=RawSource, Props) -> evidence_term_atom(RawSource, Source) ; Source = ''),
+    (memberchk(claim_key=RawClaimKey, Props) -> evidence_term_atom(RawClaimKey, ClaimKey) ; ClaimKey = ''),
+    (memberchk(claim_text=RawClaimText, Props) -> evidence_term_atom(RawClaimText, ClaimText) ; ClaimText = ''),
+    (memberchk(canonical_key=RawCanonicalKey, Props) -> evidence_term_atom(RawCanonicalKey, CanonicalKey) ; CanonicalKey = '').
+
+evidence_term_atom(Raw, Atom) :-
+    unwrap_rdf_value(Raw, Value),
+    (   atom(Value)
+    ->  Atom = Value
+    ;   string(Value)
+    ->  atom_string(Atom, Value)
+    ;   term_string(Value, String), atom_string(Atom, String)
     ).
 
 %% effective_req_predicate(+ReqId, -FactId, -Namespace, -Name, -Args, -Polarity)