kibi-core 0.8.1 → 0.10.0

package/src/kb.pl

@@ -4,13 +4,27 @@
     kb_attach/1,
     kb_detach/0,
     kb_save/0,
+    kb_sync_checkpoint/0,
+    kb_storage_status/1,
+    kb_storage_compact/0,
+    kb_storage_compact_if_needed/0,
+    kb_storage_export/1,
+    kb_migrate_legacy/2,
     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,
     kb_retract_entity_relationships/1,
+    kb_retract_relationship/3,
+    kb_retract_all_relationships/0,
+    kb_entities_by_tag/2,
+    kb_indexed_sources/1,
+    kb_query_entities/8,
+    kb_search_entities/6,
+    kb_rebuild_indexes/0,
     kb_entity/3,
     kb_entities_by_source/2,
     kb_assert_relationship/4,
@@ -43,6 +57,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,
@@ -51,9 +66,13 @@
 ]).
 
 :- use_module(library(semweb/rdf11)).
+:- use_module(library(semweb/rdf_persistency)).
 :- use_module(library(persistency)).
 :- use_module(library(thread)).
 :- use_module(library(filesex)).
+:- use_module(library(readutil)).
+:- use_module(library(aggregate), [aggregate_all/3]).
+:- use_module(library(lists), [sum_list/2]).
 :- use_module(library(ordsets)).
 :- use_module('../schema/entities.pl', [entity_type/1, entity_property/3, required_property/2]).
 :- use_module('../schema/relationships.pl', [relationship_type/1, valid_relationship/3]).
@@ -78,10 +97,31 @@ kb_uri('urn-kibi:').
 :- dynamic kb_audit_db/1.
 :- dynamic kb_graph/1.
 :- dynamic kb_attached_snapshot/1.
+:- dynamic kb_storage_mode/1.           % legacy | journaled
+:- dynamic kb_persistency_directory/1.
+:- dynamic kb_commit_sequence/1.
+:- dynamic kb_generation/1.
+:- dynamic kb_legacy_sentinel_stamp/1.
+:- dynamic kb_audit_sequence/1.
+:- dynamic kb_dirty/0.
+% Rebuildable read indexes. RDF remains authoritative; a dirty marker causes
+% the next unbound discovery query to rebuild these daemon-lifetime indexes.
+:- dynamic kb_index_ready/0.
+:- dynamic kb_index_dirty/0.
+:- dynamic kb_index_entity/2.
+:- dynamic kb_index_type/2.
+:- dynamic kb_index_tag/2.
+:- dynamic kb_index_source/2.
+:- dynamic kb_index_token/2.
+:- dynamic kb_index_symbol_coordinate/5.
+:- dynamic kb_index_entity_count/1.
+:- dynamic kb_index_triple_count/1.
 :- dynamic entity/4.  % Support legacy .pl file format (Type, Id, Title, Props)
 
 %% kb_attach(+Directory)
-% Attach to a KB directory with RDF persistence and file locking.
+% Attach to a KB directory.  New stores use SWI's journaled RDF persistence;
+% unmarked directories retain the legacy RDF/XML path for migration and
+% backwards-compatible temporary KBs.
 % Creates directory if it doesn't exist.
 kb_attach(Directory) :-
     (   kb_attached(_)
@@ -93,6 +133,67 @@ kb_attach(Directory) :-
     ->  true
     ;   make_directory_path(Directory)
     ),
+    (   journaled_store(Directory)
+    ->  kb_attach_journaled(Directory)
+    ;   kb_attach_legacy(Directory)
+    ).
+
+journaled_store(Directory) :-
+    atom_concat(Directory, '/storage.json', Marker),
+    exists_file(Marker),
+    catch(
+        read_file_to_string(Marker, Contents, []),
+        _,
+        fail
+    ),
+    sub_string(Contents, _, _, _, "kibi.rdf-journal.v1").
+
+% implements REQ-core-journaled-engine-persistence
+kb_attach_journaled(Directory) :-
+    atom_concat(Directory, '/rdf', PersistencyDirectory),
+    (   exists_directory(PersistencyDirectory)
+    ->  true
+    ;   make_directory_path(PersistencyDirectory)
+    ),
+    % rdf_persistency owns the database lock for the lifetime of the engine.
+    rdf_attach_db(PersistencyDirectory,
+                  [access(read_write), silent(true), concurrency(4)]),
+    % Create RDF graph name from directory.  Do not unload a graph here:
+    % rdf_attach_db has already restored it from its snapshot/journal.  A
+    % staged migration can have been atomically moved after the graph was
+    % first persisted, so accept the single restored graph URI as well.
+    journal_graph_uri(Directory, GraphURI),
+    read_journal_metadata(Directory, Generation, Sequence),
+    assert(kb_attached(Directory)),
+    assert(kb_graph(GraphURI)),
+    assert(kb_storage_mode(journaled)),
+    assert(kb_persistency_directory(PersistencyDirectory)),
+    assert(kb_generation(Generation)),
+    assert(kb_commit_sequence(Sequence)),
+    assert(kb_attached_snapshot(journal_snapshot(Generation, Sequence))),
+    retractall(kb_dirty),
+    initialize_journal_audit_sequence(GraphURI),
+    atom_concat(Directory, '/kb.rdf', SentinelFile),
+    current_data_stamp(SentinelFile, SentinelStamp),
+    assert(kb_legacy_sentinel_stamp(SentinelStamp)),
+
+    load_kb_pl_files(Directory),
+    kb_rebuild_indexes.
+
+journal_graph_uri(Directory, GraphURI) :-
+    atom_concat('file://', Directory, Expected),
+    (   rdf_graph(Expected)
+    ->  GraphURI = Expected
+    ;   findall(G,
+                (rdf_graph(G), rdf(_, _, _, G)),
+                Graphs),
+        (   Graphs = [GraphURI|_]
+        ->  true
+        ;   GraphURI = Expected
+        )
+    ).
+
+kb_attach_legacy(Directory) :-
     % Create RDF graph name from directory
     atom_concat('file://', Directory, GraphURI),
     % If a graph with this URI is already present, unload it to avoid duplicates.
@@ -111,16 +212,21 @@ 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)),
     assert(kb_audit_db(AuditLog)),
     assert(kb_graph(GraphURI)),
+    assert(kb_storage_mode(legacy)),
     assert(kb_attached_snapshot(SnapshotStamp)),
 
     % Load legacy .pl entity files if present
-    load_kb_pl_files(Directory).
+    load_kb_pl_files(Directory),
+    kb_rebuild_indexes.
 
 
 %% kb_detach
@@ -130,6 +236,11 @@ kb_attach(Directory) :-
 kb_detach :-
     (   kb_attached(_Directory)
     ->  (
+            (   kb_storage_mode(journaled)
+            ->  catch(rdf_flush_journals([min_size(16384)]), _, true),
+                catch(rdf_detach_db, _, true)
+            ;   true
+            ),
             % Unload RDF graph from memory to prevent duplication on reattach
             (   kb_graph(GraphURI)
             ->  rdf_unload_graph(GraphURI)
@@ -143,7 +254,24 @@ kb_detach :-
             retractall(kb_attached(_)),
             retractall(kb_audit_db(_)),
             retractall(kb_graph(_)),
-            retractall(kb_attached_snapshot(_))
+            retractall(kb_attached_snapshot(_)),
+            retractall(kb_storage_mode(_)),
+            retractall(kb_persistency_directory(_)),
+            retractall(kb_commit_sequence(_)),
+            retractall(kb_generation(_)),
+            retractall(kb_legacy_sentinel_stamp(_)),
+            retractall(kb_audit_sequence(_)),
+            retractall(kb_dirty),
+            retractall(kb_index_ready),
+            retractall(kb_index_dirty),
+            retractall(kb_index_entity(_, _)),
+            retractall(kb_index_type(_, _)),
+            retractall(kb_index_tag(_, _)),
+            retractall(kb_index_source(_, _)),
+            retractall(kb_index_token(_, _)),
+            retractall(kb_index_symbol_coordinate(_, _, _, _, _)),
+            retractall(kb_index_entity_count(_)),
+            retractall(kb_index_triple_count(_))
         )
     ;   true
     ).
@@ -152,7 +280,9 @@ kb_detach :-
 % Save RDF graph and sync audit log to disk
 % implements REQ-009
 kb_save :-
-    (   kb_attached(Directory)
+    (   kb_storage_mode(journaled)
+    ->  kb_save_journaled
+    ;   kb_attached(Directory)
     ->  with_kb_mutex(with_kb_file_lock(Directory, kb_save_locked(Directory)))
     ;   true
     ).
@@ -166,17 +296,29 @@ with_kb_file_lock(Directory, Goal) :-
     ).
 
 kb_save_locked(Directory) :-
+    (   kb_storage_mode(journaled)
+    ->  kb_save_journaled_locked(Directory)
+    ;   kb_save_legacy_locked(Directory)
+    ).
+
+kb_save_legacy_locked(Directory) :-
     atom_concat(Directory, '/kb.rdf', DataFile),
     temp_rdf_file(Directory, TempFile),
     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,
         (
@@ -185,6 +327,486 @@ kb_save_locked(Directory) :-
         )
     ).
 
+% Journaled stores never rewrite kb.rdf on the hot path.  SWI's monitor
+% appends RDF edits to a per-source journal; flushing with min_size(16384)
+% makes a compact binary snapshot only after a journal reaches 16 MiB.
+kb_save_journaled :-
+    (   kb_attached(Directory)
+    ->  with_kb_mutex(kb_save_journaled_locked(Directory))
+    ;   true
+    ).
+
+%% kb_sync_checkpoint
+% Publish compiler freshness even when a successful sync has no RDF delta.
+% The commit sequence remains the durable ordering boundary used by status;
+% shutdown still uses kb_save/0 and therefore does not mint phantom commits.
+kb_sync_checkpoint :-
+    kb_mark_dirty,
+    kb_save_journaled.
+
+% implements REQ-core-journaled-engine-persistence
+kb_save_journaled_locked(Directory) :-
+    ensure_journal_sentinel_current(Directory),
+    (   kb_dirty
+    ->  kb_stage(journal_flush),
+        rdf_flush_journals([min_size(16384)]),
+        next_journal_commit(Generation, Sequence),
+        write_journal_head(Directory, Generation, Sequence),
+        retractall(kb_attached_snapshot(_)),
+        assert(kb_attached_snapshot(journal_snapshot(Generation, Sequence))),
+        retractall(kb_dirty)
+    ;   true
+    ).
+
+kb_mark_dirty :-
+    (kb_dirty -> true ; assertz(kb_dirty)).
+
+kb_mark_index_dirty :-
+    (kb_index_dirty -> true ; assertz(kb_index_dirty)).
+
+drop_entity_index_rows(Id) :-
+    retractall(kb_index_entity(Id, _)),
+    retractall(kb_index_type(_, Id)),
+    retractall(kb_index_tag(_, Id)),
+    retractall(kb_index_source(_, Id)),
+    retractall(kb_index_token(_, Id)),
+    retractall(kb_index_symbol_coordinate(Id, _, _, _, _)).
+
+kb_refresh_entity_index(Id) :-
+    (   kb_index_ready,
+        \+ kb_index_dirty,
+        kb_index_entity_count(Count)
+    ->  (kb_index_entity(Id, _) -> WasIndexed = true ; WasIndexed = false),
+        drop_entity_index_rows(Id),
+        (   once(kb_entity_raw(Id, Type, Props))
+        ->  index_entity_row(Id, Type, Props),
+            (WasIndexed == true -> NextCount = Count ; NextCount is Count + 1)
+        ;   (WasIndexed == true -> NextCount is max(0, Count - 1) ; NextCount = Count)
+        ),
+        retractall(kb_index_entity_count(_)),
+        assertz(kb_index_entity_count(NextCount))
+    ;   kb_mark_index_dirty
+    ).
+
+kb_remove_entity_index(Id) :-
+    (   kb_index_ready,
+        \+ kb_index_dirty,
+        kb_index_entity_count(Count)
+    ->  (kb_index_entity(Id, _) -> WasIndexed = true ; WasIndexed = false),
+        drop_entity_index_rows(Id),
+        (WasIndexed == true -> NextCount is max(0, Count - 1) ; NextCount = Count),
+        retractall(kb_index_entity_count(_)),
+        assertz(kb_index_entity_count(NextCount))
+    ;   kb_mark_index_dirty
+    ).
+
+ensure_journal_sentinel_current(Directory) :-
+    atom_concat(Directory, '/kb.rdf', SentinelFile),
+    current_data_stamp(SentinelFile, CurrentStamp),
+    (   kb_legacy_sentinel_stamp(ExpectedStamp)
+    ->  (   CurrentStamp == ExpectedStamp
+        ->  true
+        ;   throw(error(permission_error(save, kb, stale_snapshot), kb_save/0))
+        )
+    ;   true
+    ).
+
+next_journal_commit(Generation, Sequence) :-
+    (   kb_generation(CurrentGeneration)
+    ->  Generation = CurrentGeneration
+    ;   Generation = 'generation-1'
+    ),
+    (   kb_commit_sequence(CurrentSequence)
+    ->  Sequence is CurrentSequence + 1
+    ;   Sequence = 1
+    ),
+    retractall(kb_generation(_)),
+    assert(kb_generation(Generation)),
+    retractall(kb_commit_sequence(_)),
+    assert(kb_commit_sequence(Sequence)).
+
+read_journal_metadata(Directory, Generation, Sequence) :-
+    atom_concat(Directory, '/CURRENT', HeadFile),
+    (   exists_file(HeadFile),
+        catch(read_file_to_string(HeadFile, Contents, []), _, fail),
+        split_string(Contents, ':\n\r', ' \t', Parts),
+        Parts = [GenerationString, SequenceString|_],
+        atom_string(Generation, GenerationString),
+        catch(number_string(Sequence, SequenceString), _, fail)
+    ->  true
+    ;   Generation = 'generation-1',
+        Sequence = 0
+    ).
+
+write_journal_head(Directory, Generation, Sequence) :-
+    atom_concat(Directory, '/CURRENT.tmp', TempFile),
+    atom_concat(Directory, '/CURRENT', HeadFile),
+    setup_call_cleanup(
+        open(TempFile, write, Stream, [encoding(utf8)]),
+        format(Stream, '~w:~w~n', [Generation, Sequence]),
+        close(Stream)
+    ),
+    rename_file(TempFile, HeadFile).
+
+%% kb_storage_status(-Status)
+% Return a compact operational view without scanning the RDF graph.
+kb_storage_status(Status) :-
+    kb_storage_mode(Mode),
+    kb_attached(Directory),
+    (kb_generation(Generation) -> true ; Generation = unknown),
+    (kb_commit_sequence(Sequence) -> true ; Sequence = 0),
+    journal_bytes(Directory, JournalBytes),
+    Status = _{
+        mode: Mode,
+        directory: Directory,
+        generation: Generation,
+        sequence: Sequence,
+        journalBytes: JournalBytes
+    }.
+
+journal_bytes(Directory, Bytes) :-
+    (   kb_persistency_directory(_PersistencyDirectory)
+    ->  (   findall(Size,
+                    ( rdf_journal_file(_Graph, JournalFile),
+                      size_file(JournalFile, Size) ),
+                Sizes),
+            sum_list(Sizes, Bytes)
+        )
+    ;   atom_concat(Directory, '/audit.log', AuditLog),
+        (exists_file(AuditLog) -> size_file(AuditLog, Bytes) ; Bytes = 0)
+    ).
+
+directory_size(Directory, Bytes) :-
+    (   exists_directory(Directory)
+    ->  directory_files(Directory, Files),
+        directory_size_files(Directory, Files, 0, Bytes)
+    ;   Bytes = 0
+    ).
+
+directory_size_files(_, [], Total, Total).
+directory_size_files(Directory, [File|Rest], Acc, Total) :-
+    (   memberchk(File, ['.', '..'])
+    ->  Next = Acc
+    ;   atom_concat(Directory, '/', Prefix),
+        atom_concat(Prefix, File, FullPath),
+        (   exists_directory(FullPath)
+        ->  directory_size(FullPath, ChildSize), Next is Acc + ChildSize
+        ;   exists_file(FullPath), size_file(FullPath, Size)
+        ->  Next is Acc + Size
+        ;   Next = Acc
+        )
+    ),
+    directory_size_files(Directory, Rest, Next, Total).
+
+%% kb_storage_compact
+kb_storage_compact :-
+    kb_storage_mode(journaled),
+    kb_attached(Directory),
+    with_kb_mutex(kb_storage_compact_locked(Directory)).
+
+%% kb_storage_compact_if_needed
+% Compact only when the live journal has crossed the 16 MiB idle-compaction
+% threshold.  The engine invokes this predicate after the client queue drains;
+% ordinary writes only append durable journal records and never rewrite a
+% snapshot on the hot path.
+kb_storage_compact_if_needed :-
+    kb_storage_mode(journaled),
+    kb_attached(Directory),
+    with_kb_mutex((
+        journal_bytes(Directory, JournalBytes),
+        (   JournalBytes >= 16777216
+        ->  kb_storage_compact_locked(Directory)
+        ;   true
+        )
+    )).
+
+kb_storage_compact_locked(Directory) :-
+    % A caller may explicitly compact immediately after a low-level mutation
+    % that has not gone through kb_save/0. Publish that dirty transaction
+    % first so CURRENT never points at an older commit sequence.
+    kb_save_journaled_locked(Directory),
+    rdf_flush_journals([min_size(0)]),
+    (   kb_generation(Generation) -> true ; Generation = 'generation-1' ),
+    (   kb_commit_sequence(Sequence) -> true ; Sequence = 0 ),
+    write_journal_head(Directory, Generation, Sequence).
+
+%% kb_storage_export(+TargetDirectory)
+% Export a journaled branch to the legacy RDF/XML shape without changing the
+% active store.  The human-readable audit export is intentionally derived.
+kb_storage_export(TargetDirectory) :-
+    kb_graph(GraphURI),
+    (   exists_directory(TargetDirectory)
+    ->  true
+    ;   make_directory_path(TargetDirectory)
+    ),
+    atom_concat(TargetDirectory, '/kb.rdf', TargetFile),
+    rdf_save(TargetFile,
+             [graph(GraphURI), base_uri('urn-kibi:'), namespaces([kb, xsd])]),
+    atom_concat(TargetDirectory, '/audit.log', AuditFile),
+    setup_call_cleanup(
+        open(AuditFile, write, Stream, [encoding(utf8)]),
+        export_audit_events(Stream, GraphURI),
+        close(Stream)
+    ).
+
+%% kb_migrate_legacy(+SourceDirectory, +TargetDirectory)
+% Copy a legacy RDF/audit graph into a fresh journaled directory.  The caller
+% publishes the staged directory atomically; this predicate deliberately
+% leaves the source untouched on failure.
+% implements REQ-core-journaled-engine-persistence
+kb_migrate_legacy(SourceDirectory, TargetDirectory) :-
+    kb_attached(SourceDirectory),
+    kb_storage_mode(legacy),
+    % Hold the legacy branch lock for the complete import and audit copy so a
+    % pre-cutover writer cannot change the source between validation and
+    % publication.
+    with_kb_file_lock_nowait(
+        SourceDirectory,
+        kb_migrate_legacy_locked(SourceDirectory, TargetDirectory)
+    ).
+
+% Migration is a cutover operation, not a background writer.  Never leave a
+% CLI/engine request blocked indefinitely behind an old MCP process that still
+% owns the legacy lock; surface the lock owner to the caller so it can stop the
+% old client and retry.  Ordinary legacy saves retain their blocking lock
+% semantics for compatibility.
+with_kb_file_lock_nowait(Directory, Goal) :-
+    atom_concat(Directory, '/kb.lock', LockFile),
+    setup_call_cleanup(
+        open(LockFile, append, LockStream, [lock(write), wait(false)]),
+        call(Goal),
+        close(LockStream)
+    ).
+
+kb_migrate_legacy_locked(_SourceDirectory, TargetDirectory) :-
+    kb_graph(SourceGraph),
+    findall(
+        t(S, P, O),
+        (   rdf(S, P, O, SourceGraph),
+            \+ audit_resource(S)
+        ),
+        Triples
+    ),
+    findall(c(TS, Op, Entity, Data),
+            changeset(TS, Op, Entity, Data),
+            Audits),
+    canonical_triple_digest(Triples, SourceDigest),
+    length(Triples, TripleCount),
+    length(Audits, AuditCount),
+    kb_detach,
+    (   exists_directory(TargetDirectory)
+    ->  true
+    ;   make_directory_path(TargetDirectory)
+    ),
+    write_journal_marker(TargetDirectory),
+    kb_attach(TargetDirectory),
+    kb_graph(TargetGraph),
+    forall(member(t(S, P, O), Triples), rdf_assert(S, P, O, TargetGraph)),
+    assert_migration_audits(Audits, 1),
+    kb_mark_dirty,
+    kb_mark_index_dirty,
+    validate_migrated_graph(
+        TargetGraph,
+        SourceDigest,
+        TripleCount,
+        AuditCount
+    ),
+    kb_save_journaled,
+    kb_detach.
+
+canonical_triple_digest(Triples, Digest) :-
+    sort(Triples, Canonical),
+    term_hash(Canonical, Digest).
+
+validate_migrated_graph(Graph, ExpectedDigest, ExpectedTriples, ExpectedAudits) :-
+    findall(
+        t(S, P, O),
+        (   rdf(S, P, O, Graph),
+            \+ audit_resource(S)
+        ),
+        Triples
+    ),
+    length(Triples, ActualTriples),
+    (   ActualTriples =:= ExpectedTriples
+    ->  true
+    ;   throw(error(migration_validation(triple_count, ExpectedTriples, ActualTriples),
+                    kb_migrate_legacy/2))
+    ),
+    canonical_triple_digest(Triples, ActualDigest),
+    (   ActualDigest == ExpectedDigest
+    ->  true
+    ;   throw(error(migration_validation(triple_digest, ExpectedDigest, ActualDigest),
+                    kb_migrate_legacy/2))
+    ),
+    findall(Audit,
+            rdf(Audit, 'urn:kibi:audit/operation', _, Graph),
+            AuditResources),
+    length(AuditResources, ActualAudits),
+    (   ActualAudits =:= ExpectedAudits
+    ->  true
+    ;   throw(error(migration_validation(audit_count, ExpectedAudits, ActualAudits),
+                    kb_migrate_legacy/2))
+    ),
+    % Re-run the schema and relationship invariants before publication. This
+    % catches missing required fields and dangling edges while the staged
+    % generation is still disposable.
+    findall(
+        problem(Id, Type),
+        (   kb_entity(Id, Type, Props),
+            normalize_migration_props(Type, Props, ValidationProps),
+            \+ catch(validate_entity(Type, ValidationProps), _, fail)
+        ),
+        EntityProblems
+    ),
+    (   EntityProblems == []
+    ->  true
+    ;   throw(error(migration_validation(entity_schema, EntityProblems),
+                    kb_migrate_legacy/2))
+    ),
+    findall(
+        problem(RelType, FromId, ToId),
+        (   relationship_type(RelType),
+            kb_relationship(RelType, FromId, ToId),
+            (   \+ once(kb_entity(FromId, _, _))
+            ;   \+ once(kb_entity(ToId, _, _))
+            ;   once(kb_entity(FromId, FromType, _)),
+                once(kb_entity(ToId, ToType, _)),
+                \+ catch(validate_relationship(RelType, FromType, ToType), _, fail)
+            )
+        ),
+        RelationshipProblems
+    ),
+    (   RelationshipProblems == []
+    ->  true
+    ;   throw(error(migration_validation(relationships, RelationshipProblems),
+                    kb_migrate_legacy/2))
+    ).
+
+assert_migration_audits([], _).
+assert_migration_audits([c(TS, Op, Entity, Data)|Rest], Index) :-
+    kb_assert_audit_event_with_timestamp(TS, Op, Entity, Data, Index),
+    NextIndex is Index + 1,
+    assert_migration_audits(Rest, NextIndex).
+
+normalize_migration_props(_, [], []).
+normalize_migration_props(Type, [Key=Value|Rest], NormalizedProps) :-
+    normalize_migration_props(Type, Rest, RestProps),
+    (   entity_property(Type, Key, _)
+    ->  normalize_migration_value(Type, Key, Value, Normalized),
+        NormalizedProps = [Key=Normalized|RestProps]
+    ;   % Preserve unknown legacy RDF fields in the copied graph, but do not
+        % reject an otherwise valid entity merely because an older schema
+        % version stored an extension that the current validator no longer
+        % models. Required/currently typed fields are still validated below.
+        NormalizedProps = RestProps
+    ).
+
+% Legacy RDF reads intentionally preserve typed literal wrappers for the
+% public query API.  Validation, however, needs the schema-level value (atom,
+% string, number, boolean, or list) that an upsert would have received.  Use
+% the entity schema as the decoder instead of maintaining another list of
+% fields that can drift as the schema evolves.
+normalize_migration_value(Type, Key, Raw, Normalized) :-
+    migration_unwrap_literal(Raw, Value),
+    (   entity_property(Type, Key, Kind)
+    ->  normalize_migration_kind(Kind, Value, Normalized)
+    ;   Normalized = Value
+    ).
+
+migration_unwrap_literal(^^(Value, _Type), Value) :- !.
+migration_unwrap_literal(literal(type(_, Value)), Value) :- !.
+migration_unwrap_literal(literal(lang(_, Value)), Value) :- !.
+migration_unwrap_literal(literal(Value), Value) :- !.
+migration_unwrap_literal(Value, Value).
+
+normalize_migration_kind(atom, Value, Normalized) :-
+    !,
+    normalize_term_atom(Value, Normalized).
+normalize_migration_kind(atom_or_string, Value, Normalized) :-
+    !,
+    (atom(Value) ; string(Value)),
+    Normalized = Value.
+normalize_migration_kind(string, Value, Normalized) :-
+    !,
+    migration_string(Value, Normalized).
+normalize_migration_kind(uri, Value, Normalized) :-
+    !,
+    migration_string(Value, Normalized).
+normalize_migration_kind(datetime, Value, Normalized) :-
+    !,
+    migration_string(Value, Normalized).
+normalize_migration_kind(list, Value, Normalized) :-
+    !,
+    (   is_list(Value)
+    ->  maplist(normalize_migration_list_value, Value, Normalized)
+    ;   Normalized = Value
+    ).
+normalize_migration_kind(list_or_json, Value, Value) :- !.
+normalize_migration_kind(integer, Value, Normalized) :-
+    !,
+    (integer(Value) -> Normalized = Value ; atom_number(Value, Normalized)).
+normalize_migration_kind(number, Value, Normalized) :-
+    !,
+    (number(Value) -> Normalized = Value ; atom_number(Value, Normalized)).
+normalize_migration_kind(boolean, Value, Value) :- !.
+normalize_migration_kind(_, Value, Value).
+
+migration_string(Value, Value) :- string(Value), !.
+migration_string(Value, String) :- atom(Value), !, atom_string(Value, String).
+migration_string(Value, String) :- number(Value), !, number_string(Value, String).
+migration_string(Value, String) :- term_string(Value, String).
+
+normalize_migration_list_value(Value, Normalized) :-
+    (atom(Value) -> Normalized = Value ; string(Value) -> Normalized = Value ; Normalized = Value).
+
+migration_atom_key(id).
+migration_atom_key(status).
+migration_atom_key(owner).
+migration_atom_key(priority).
+migration_atom_key(severity).
+migration_atom_key(symbol_role).
+migration_atom_key(granularity_reason).
+migration_atom_key(fact_kind).
+migration_atom_key(operator).
+migration_atom_key(value_type).
+migration_atom_key(polarity).
+
+audit_resource(Resource) :-
+    atom(Resource),
+    sub_atom(Resource, 0, _, _, 'urn:kibi:audit/').
+
+write_journal_marker(Directory) :-
+    atom_concat(Directory, '/storage.json', Marker),
+    setup_call_cleanup(
+        open(Marker, write, Stream, [encoding(utf8)]),
+        format(Stream,
+               '{"format":"kibi.rdf-journal.v1","schemaVersion":1}~n',
+               []),
+        close(Stream)
+    ),
+    get_time(Now),
+    Millis is floor(Now * 1000),
+    (current_prolog_flag(pid, Pid) -> true ; Pid = 0),
+    format(atom(Generation), 'generation-~w-~w', [Pid, Millis]),
+    atom_concat(Directory, '/CURRENT', HeadFile),
+    setup_call_cleanup(
+        open(HeadFile, write, HeadStream, [encoding(utf8)]),
+        format(HeadStream, '~w:0~n', [Generation]),
+        close(HeadStream)
+    ).
+
+export_audit_events(Stream, GraphURI) :-
+    forall(
+        rdf(Audit, 'urn:kibi:audit/operation', Operation, GraphURI),
+        (
+            rdf(Audit, 'urn:kibi:audit/timestamp', Timestamp, GraphURI),
+            rdf(Audit, 'urn:kibi:audit/entity', Entity, GraphURI),
+            rdf(Audit, 'urn:kibi:audit/data', Data, GraphURI),
+            format(Stream, 'changeset(~q, ~q, ~q, ~q).~n',
+                   [Timestamp, Operation, Entity, Data])
+        )
+    ).
+
 temp_rdf_file(Directory, TempFile) :-
     get_time(Timestamp),
     Millis is floor(Timestamp * 1000),
@@ -234,6 +856,22 @@ ensure_snapshot_current(DataFile) :-
 with_kb_mutex(Goal) :-
     with_mutex(kb_lock, Goal).
 
+% Run a journaled RDF mutation atomically and only mark the branch dirty after
+% the transaction commits.  A failed validation/contradiction check therefore
+% cannot make a later shutdown publish a phantom commit sequence.  Preserve a
+% pre-existing dirty bit for callers that intentionally batch several writes
+% before an explicit kb_save/0.
+kb_run_journaled_mutation(Goal) :-
+    (   kb_dirty -> WasDirty = true ; WasDirty = false ),
+    catch(
+        rdf_transaction(Goal),
+        Error,
+        (   (WasDirty == false -> retractall(kb_dirty) ; true),
+            throw(Error)
+        )
+    ),
+    kb_mark_dirty.
+
 %% load_kb_pl_files(+Directory)
 % Load legacy .pl entity files from the KB directory.
 % These files use entity/4 format: entity(Type, Id, Title, Props).
@@ -264,8 +902,15 @@ kb_assert_entity(Type, Props) :-
     ->  ChangeKind = updated
     ;   ChangeKind = created
     ),
-    kb_assert_entity_no_audit(Type, Props),
-    kb_log_entity_upsert(ChangeKind, Type, Props).
+    (   kb_storage_mode(journaled)
+    ->  kb_run_journaled_mutation((
+            kb_assert_entity_no_audit(Type, Props),
+            kb_log_entity_upsert(ChangeKind, Type, Props)
+        ))
+    ;   kb_mark_dirty,
+        kb_assert_entity_no_audit(Type, Props),
+        kb_log_entity_upsert(ChangeKind, Type, Props)
+    ).
 
 %% kb_assert_entity_no_audit(+Type, +Properties)
 % Assert an entity RDF payload without recording audit side effects.
@@ -302,26 +947,229 @@ kb_assert_entity_no_audit(Type, Props) :-
             member(Key=Value, Props),
             store_property(EntityURI, Key, Value, Graph)
         )
+    )),
+    kb_refresh_entity_index(Id).
+
+%% 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) :-
+    kb_storage_mode(journaled),
+    !,
+    memberchk(id=Id, Props),
+    memberchk(SkipContradiction, [true, false]),
+    upsert_change_kind(Id, ChangeKind),
+    with_kb_mutex((
+        (   kb_dirty -> WasDirty = true ; WasDirty = false ),
+        catch(
+            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)
+            )),
+            Error,
+            (   (WasDirty == false -> retractall(kb_dirty) ; true),
+                throw(Error)
+            )
+        ),
+        kb_mark_dirty,
+        kb_save_journaled
+    )).
+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.
 kb_retract_entity_relationships(Id) :-
     kb_graph(Graph),
-    with_kb_mutex((
-        entity_id_to_uri(Id, EntityURI),
-        forall(
-            (   rdf(EntityURI, RelURI, TargetURI, Graph),
-                atom(TargetURI),
-                entity_uri_to_id(TargetURI, _)
-            ),
-            rdf_retractall(EntityURI, RelURI, TargetURI, Graph)
+    (   kb_storage_mode(journaled)
+    ->  kb_run_journaled_mutation(with_kb_mutex((
+            entity_id_to_uri(Id, EntityURI),
+            forall(
+                (   rdf(EntityURI, RelURI, TargetURI, Graph),
+                    atom(TargetURI),
+                    entity_uri_to_id(TargetURI, _)
+                ),
+                rdf_retractall(EntityURI, RelURI, TargetURI, Graph)
+            )
+        )))
+    ;   kb_mark_dirty,
+        with_kb_mutex((
+            entity_id_to_uri(Id, EntityURI),
+            forall(
+                (   rdf(EntityURI, RelURI, TargetURI, Graph),
+                    atom(TargetURI),
+                    entity_uri_to_id(TargetURI, _)
+                ),
+                rdf_retractall(EntityURI, RelURI, TargetURI, Graph)
+            )
+        ))
+    ).
+
+%% kb_retract_relationship(+Type, +From, +To)
+% Retract one compiled edge and its audit record atomically. This is used by
+% relationship-shard deltas so a small shard edit never requires clearing and
+% rebuilding every edge in the graph.
+kb_retract_relationship(RelType, FromId, ToId) :-
+    kb_graph(Graph),
+    entity_id_to_uri(FromId, FromURI),
+    entity_id_to_uri(ToId, ToURI),
+    kb_uri(BaseURI),
+    atom_concat(BaseURI, RelType, RelURI),
+    (   kb_storage_mode(journaled)
+    ->  kb_run_journaled_mutation(with_kb_mutex((
+            rdf_retractall(FromURI, RelURI, ToURI, Graph),
+            format(atom(RelId), '~w->~w', [FromId, ToId]),
+            kb_assert_audit_event(delete_rel, RelId,
+                                  RelType-[from=FromId, to=ToId])
+        )))
+    ;   kb_mark_dirty,
+        with_kb_mutex(rdf_retractall(FromURI, RelURI, ToURI, Graph))
+    ).
+
+%% kb_retract_all_relationships/0
+% Remove only entity-to-entity edges. This is used when a relationship shard
+% changes: RDF property literals and audit resources remain untouched, while
+% the current shard contents can be asserted again in one transaction.
+% implements REQ-core-journaled-engine-persistence
+kb_retract_all_relationships :-
+    kb_graph(Graph),
+    (   kb_storage_mode(journaled)
+    ->  kb_run_journaled_mutation(with_kb_mutex(
+            forall(
+                (   rdf(SubjectURI, RelURI, ObjectURI, Graph),
+                    atom(SubjectURI),
+                    atom(ObjectURI),
+                    entity_uri_to_id(SubjectURI, _),
+                    entity_uri_to_id(ObjectURI, _)
+                ),
+                rdf_retractall(SubjectURI, RelURI, ObjectURI, Graph)
+            )
+        ))
+    ;   kb_mark_dirty,
+        with_kb_mutex(
+            forall(
+                (   rdf(SubjectURI, RelURI, ObjectURI, Graph),
+                    atom(SubjectURI),
+                    atom(ObjectURI),
+                    entity_uri_to_id(SubjectURI, _),
+                    entity_uri_to_id(ObjectURI, _)
+                ),
+                rdf_retractall(SubjectURI, RelURI, ObjectURI, Graph)
+            )
         )
-    )).
+    ).
 
 %% kb_log_entity_upsert(+ChangeKind, +Type, +Properties)
 % Append the audit entry for a successfully committed entity upsert.
+kb_log_entity_upsert(ChangeKind, Type, Props) :-
+    kb_storage_mode(journaled),
+    !,
+    memberchk(id=Id, Props),
+    kb_assert_audit_event(upsert, Id, Type-[change_kind=ChangeKind|Props]).
 kb_log_entity_upsert(ChangeKind, Type, Props) :-
     memberchk(id=Id, Props),
     memberchk(ChangeKind, [created, updated]),
@@ -343,6 +1191,26 @@ kb_retract_entity(Id) :-
 
 %% kb_retract_entity(+Id, +Type, +AuditProps)
 % Remove an entity from the KB and log the provided delete payload.
+kb_retract_entity(Id, Type, AuditProps) :-
+    kb_storage_mode(journaled),
+    !,
+    kb_graph(Graph),
+    kb_run_journaled_mutation(with_kb_mutex((
+        entity_id_to_uri(Id, EntityURI),
+        % A source delta may replace an entity that is still referenced by
+        % another source. Remove both directions so the transaction cannot
+        % leave a dangling relationship behind. The compiler re-adds valid
+        % edges from the current source shards in the same sync.
+        forall(
+            (   rdf(SubjectURI, RelURI, EntityURI, Graph),
+                entity_uri_to_id(SubjectURI, _)
+            ),
+            rdf_retractall(SubjectURI, RelURI, EntityURI, Graph)
+        ),
+        rdf_retractall(EntityURI, _, _, Graph),
+        kb_assert_audit_event(delete, Id, Type-AuditProps),
+        kb_remove_entity_index(Id)
+    ))).
 kb_retract_entity(Id, Type, AuditProps) :-
     kb_graph(Graph),
     with_kb_mutex((
@@ -353,12 +1221,13 @@ kb_retract_entity(Id, Type, AuditProps) :-
         % Log to audit
         get_time(Timestamp),
         format_time(atom(TS), '%FT%T%:z', Timestamp),
-        assert_changeset(TS, delete, Id, Type-AuditProps)
+        assert_changeset(TS, delete, Id, Type-AuditProps),
+        kb_remove_entity_index(Id)
     )).
 
 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)
         ),
@@ -381,6 +1250,20 @@ audit_property_value(RawValue, Value) :-
 % Query entities from the KB.
 % Properties is unified with a list of Key=Value pairs.
 kb_entity(Id, Type, Props) :-
+    (   nonvar(Id)
+    ->  kb_entity_raw(Id, Type, Props)
+    ;   kb_ensure_indexes,
+        (   nonvar(Type)
+        ->  kb_index_type(Type, IndexedId),
+            kb_entity_raw(IndexedId, Type, Props),
+            Id = IndexedId
+        ;   kb_entity_raw(Id, Type, Props)
+        )
+    ).
+
+% Raw RDF/entity facts are kept separate from the index wrapper.  Rebuilding
+% an index must never recurse through the indexed query path.
+kb_entity_raw(Id, Type, Props) :-
     kb_graph(Graph),
     % Find entity by pattern - use unquoted namespace term kb:type
     (   var(Id)
@@ -398,14 +1281,115 @@ 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
-kb_entity(Id, Type, Props) :-
+kb_entity_raw(Id, Type, Props) :-
     entity(Type, Id, _Title, PropList),
     convert_legacy_props(PropList, Props).
 
+kb_ensure_indexes :-
+    (   kb_index_ready,
+        \+ kb_index_dirty,
+        kb_index_entity_count(Expected),
+        current_entity_index_count(Expected)
+    ->  true
+    ;   kb_rebuild_indexes
+    ).
+
+% Rebuild all acceleration structures from RDF/entity facts.  This is
+% intentionally disposable: no query result is written back to RDF when an
+% index is stale or externally invalidated.
+kb_rebuild_indexes :-
+    kb_attached(_),
+    with_kb_mutex((
+        retractall(kb_index_entity(_, _)),
+        retractall(kb_index_type(_, _)),
+        retractall(kb_index_tag(_, _)),
+        retractall(kb_index_source(_, _)),
+        retractall(kb_index_token(_, _)),
+        retractall(kb_index_symbol_coordinate(_, _, _, _, _)),
+        findall(Id-Type-Props, kb_entity_raw(Id, Type, Props), Rows),
+        forall(member(Id-Type-Props, Rows), index_entity_row(Id, Type, Props)),
+        length(Rows, EntityCount),
+        retractall(kb_index_entity_count(_)),
+        assertz(kb_index_entity_count(EntityCount)),
+        rdf_statistics(triples(TripleCount)),
+        retractall(kb_index_triple_count(_)),
+        assertz(kb_index_triple_count(TripleCount)),
+        retractall(kb_index_dirty),
+        retractall(kb_index_ready),
+        assertz(kb_index_ready)
+    )).
+
+current_entity_index_count(Count) :-
+    aggregate_all(count,
+                  rdf(_, kb:type, _, _),
+                  RdfCount),
+    aggregate_all(count,
+                  entity(_, _, _, _),
+                  LegacyCount),
+    Count is RdfCount + LegacyCount.
+
+index_entity_row(Id, Type, Props) :-
+    assertz(kb_index_entity(Id, Type)),
+    assertz(kb_index_type(Type, Id)),
+    (   entity_source_atom(Props, Source)
+    ->  assertz(kb_index_source(Source, Id)),
+        index_text_tokens(Source, SourceTokens),
+        forall(member(Token, SourceTokens), assertz(kb_index_token(Token, Id)))
+    ;   true
+    ),
+    (   memberchk(title=TitleValue, Props)
+    ->  normalize_term_atom(TitleValue, Title),
+        index_text_tokens(Title, TitleTokens),
+        forall(member(Token, TitleTokens), assertz(kb_index_token(Token, Id)))
+    ;   true
+    ),
+    index_text_tokens(Id, IdTokens),
+    forall(member(Token, IdTokens), assertz(kb_index_token(Token, Id))),
+    index_text_tokens(Type, TypeTokens),
+    forall(member(Token, TypeTokens), assertz(kb_index_token(Token, Id))),
+    forall(
+        ( member(SearchKey, [owner, priority, severity, text_ref, semantic_text]),
+          memberchk(SearchKey=SearchValue, Props) ),
+        ( index_text_tokens(SearchValue, SearchTokens),
+          forall(member(Token, SearchTokens), assertz(kb_index_token(Token, Id))) )
+    ),
+    (   memberchk(tags=RawTags, Props), is_list(RawTags)
+    ->  forall(member(RawTag, RawTags),
+               ( normalize_term_atom(RawTag, Tag),
+                 assertz(kb_index_tag(Tag, Id)),
+                 index_text_tokens(Tag, TagTokens),
+                 forall(member(Token, TagTokens), assertz(kb_index_token(Token, Id)))
+               ))
+    ;   true
+    ),
+    (   Type == symbol,
+        memberchk(sourceLine=Line, Props),
+        memberchk(sourceColumn=Column, Props),
+        memberchk(sourceEndLine=EndLine, Props),
+        memberchk(sourceEndColumn=EndColumn, Props)
+    ->  assertz(kb_index_symbol_coordinate(Id, Line, Column, EndLine, EndColumn))
+    ;   true
+    ).
+
+index_text_tokens(Value, Tokens) :-
+    normalize_term_atom(Value, Atom),
+    downcase_atom(Atom, Lower),
+    atomic_list_concat(Parts, ' ', Lower),
+    findall(Token,
+            ( member(Part, Parts),
+              atom_string(Part, PartString),
+              split_string(PartString, "-_./:#", "-_./:#", Strings),
+              member(String, Strings),
+              String \= '',
+              atom_string(Token, String)
+            ),
+            RawTokens),
+    sort(RawTokens, Tokens).
+
 % Convert legacy property list format to Key=Value pairs
 convert_legacy_props([], []).
 convert_legacy_props([Prop|Rest], [Key=Value|OutRest]) :-
@@ -422,13 +1406,130 @@ convert_legacy_prop(Prop, Prop, true).
 %% kb_entities_by_source(+SourcePath, -Ids)
 % Returns all entity IDs whose source property matches SourcePath (substring match).
 kb_entities_by_source(SourcePath, Ids) :-
+    kb_ensure_indexes,
+    source_value_atom(SourcePath, SourceQuery),
     findall(Id,
-        (kb_entity(Id, _Type, Props),
-         entity_source_atom(Props, SourceAtom),
-         sub_atom(SourceAtom, _, _, _, SourcePath)),
-        RawIds),
+            ( kb_index_source(SourceAtom, Id),
+              sub_atom(SourceAtom, _, _, _, SourceQuery) ),
+            RawIds),
+    sort(RawIds, Ids).
+
+%% kb_entities_by_tag(+Tag, -Ids)
+% Index-backed tag lookup used by exact/paginated discovery queries.
+kb_entities_by_tag(Tag, Ids) :-
+    kb_ensure_indexes,
+    normalize_term_atom(Tag, NormalizedTag),
+    findall(Id, kb_index_tag(NormalizedTag, Id), RawIds),
     sort(RawIds, Ids).
 
+%% kb_indexed_sources(-Sources)
+% Return unique normalized source paths for freshness checks without
+% materializing every entity property list.
+kb_indexed_sources(Sources) :-
+    kb_ensure_indexes,
+    (   setof(Source, Id^kb_index_source(Source, Id), Sources)
+    ->  true
+    ;   Sources = []
+    ).
+
+%% kb_query_entities(+Type, +Id, +Tags, +Source, +Limit, +Offset, -Rows, -Count)
+% Index-backed exact/paginated discovery.  Only the requested page is
+% materialized into full property lists; RDF remains authoritative for the
+% final rows and the index only supplies candidate IDs.
+kb_query_entities(TypeFilter, IdFilter, Tags, SourceFilter, Limit, Offset, Rows, Count) :-
+    integer(Limit),
+    integer(Offset),
+    Limit >= 0,
+    Offset >= 0,
+    is_list(Tags),
+    kb_ensure_indexes,
+    findall(Id,
+            indexed_entity_match(TypeFilter, IdFilter, Tags, SourceFilter, Id),
+            RawIds),
+    sort(RawIds, Ids),
+    length(Ids, Count),
+    drop_index_ids(Offset, Ids, Remaining),
+    take_index_ids(Limit, Remaining, PageIds),
+    findall([Id, Type, Props],
+            ( member(Id, PageIds),
+              kb_entity(Id, Type, Props) ),
+            Rows).
+
+indexed_entity_match(TypeFilter, IdFilter, Tags, SourceFilter, Id) :-
+    (   IdFilter == none
+    ->  kb_index_entity(Id, _)
+    ;   Id = IdFilter,
+        kb_index_entity(Id, _)
+    ),
+    (   TypeFilter == none
+    ->  true
+    ;   kb_index_type(TypeFilter, Id)
+    ),
+    (   Tags == []
+    ->  true
+    ;   member(Tag, Tags),
+        kb_index_tag(Tag, Id)
+    ),
+    (   SourceFilter == none
+    ->  true
+    ;   source_value_atom(SourceFilter, SourceQuery),
+        kb_index_source(Source, Id),
+        sub_atom(Source, _, _, _, SourceQuery)
+    ).
+
+drop_index_ids(0, Ids, Ids) :- !.
+drop_index_ids(_, [], []) :- !.
+drop_index_ids(Offset, [_|Rest], Remaining) :-
+    Next is Offset - 1,
+    drop_index_ids(Next, Rest, Remaining).
+
+take_index_ids(0, _, []) :- !.
+take_index_ids(_, [], []) :- !.
+take_index_ids(Limit, [Id|Rest], [Id|Page]) :-
+    Next is Limit - 1,
+    take_index_ids(Next, Rest, Page).
+
+%% kb_search_entities(+Type, +Query, +Limit, +Offset, -Rows, -Count)
+% Return an index-filtered page for the higher-level deterministic ranking
+% contract. Every normalized query token must match at least one indexed token
+% for the entity. The TypeScript ranker remains responsible for scores,
+% reasons, snippets, and final ordering.
+kb_search_entities(TypeFilter, Query, Limit, Offset, Rows, Count) :-
+    integer(Limit),
+    integer(Offset),
+    Limit >= 0,
+    Offset >= 0,
+    kb_ensure_indexes,
+    index_text_tokens(Query, QueryTokens),
+    QueryTokens \= [],
+    findall(Id,
+            ( kb_index_entity(Id, _),
+              (TypeFilter == none -> true ; kb_index_type(TypeFilter, Id)),
+              ( indexed_markdown_source(Id)
+              ; forall(member(QueryToken, QueryTokens),
+                       indexed_token_match(QueryToken, Id)) ) ),
+            RawIds),
+    sort(RawIds, Ids),
+    length(Ids, Count),
+    drop_index_ids(Offset, Ids, Remaining),
+    take_index_ids(Limit, Remaining, PageIds),
+    findall([Id, Type, Props],
+            ( member(Id, PageIds), kb_entity(Id, Type, Props) ),
+            Rows).
+
+indexed_token_match(QueryToken, Id) :-
+    kb_index_token(IndexedToken, Id),
+    sub_atom(IndexedToken, _, _, _, QueryToken),
+    !.
+
+% Markdown bodies remain outside RDF and are ranked by the Node discovery
+% layer. Keep those usually-small document entities in the candidate set so
+% indexed search does not change the public body-search contract. Large symbol
+% manifests still take the fast token-index path.
+indexed_markdown_source(Id) :-
+    kb_index_source(Source, Id),
+    sub_atom(Source, _, _, _, '.md').
+
 entity_source_atom(Props, SourceAtom) :-
     (   memberchk(sourceFile=RawSourceFile, Props)
     ->  source_value_atom(RawSourceFile, SourceAtom)
@@ -449,8 +1550,15 @@ source_value_atom(Value, Atom) :-
 %% kb_assert_relationship(+Type, +From, +To, +Metadata)
 % Assert a relationship between two entities with validation.
 kb_assert_relationship(RelType, FromId, ToId, Metadata) :-
-    kb_assert_relationship_no_audit(RelType, FromId, ToId, Metadata),
-    kb_log_relationship_upsert(RelType, FromId, ToId, Metadata).
+    (   kb_storage_mode(journaled)
+    ->  kb_run_journaled_mutation((
+            kb_assert_relationship_no_audit(RelType, FromId, ToId, Metadata),
+            kb_log_relationship_upsert(RelType, FromId, ToId, Metadata)
+        ))
+    ;   kb_mark_dirty,
+        kb_assert_relationship_no_audit(RelType, FromId, ToId, Metadata),
+        kb_log_relationship_upsert(RelType, FromId, ToId, Metadata)
+    ).
 
 %% kb_assert_relationship_no_audit(+Type, +From, +To, +Metadata)
 % Assert a relationship RDF payload without recording audit side effects.
@@ -516,6 +1624,12 @@ mixed_symbol_role(covered_by, SymbolId) :-
 
 %% kb_log_relationship_upsert(+Type, +From, +To, +Metadata)
 % Append the audit entry for a successfully committed relationship upsert.
+kb_log_relationship_upsert(RelType, FromId, ToId, _Metadata) :-
+    kb_storage_mode(journaled),
+    !,
+    format(atom(RelId), '~w->~w', [FromId, ToId]),
+    kb_assert_audit_event(upsert_rel, RelId,
+                          RelType-[from=FromId, to=ToId]).
 kb_log_relationship_upsert(RelType, FromId, ToId, _Metadata) :-
     with_kb_mutex((
         get_time(Timestamp),
@@ -524,6 +1638,65 @@ kb_log_relationship_upsert(RelType, FromId, ToId, _Metadata) :-
         assert_changeset(TS, upsert_rel, RelId, RelType-[from=FromId, to=ToId])
     )).
 
+% Journaled audit records live in the same RDF graph and transaction as the
+% domain mutation.  This keeps audit durability atomic without a second
+% persistency lock or a second authoritative database.
+kb_assert_audit_event(Operation, EntityId, Data) :-
+    kb_graph(Graph),
+    get_time(Timestamp),
+    format_time(atom(TS), '%FT%T%:z', Timestamp),
+    term_to_atom(Data, DataAtom),
+    term_to_atom(EntityId, EntityAtom),
+    term_to_atom(Operation, OperationAtom),
+    next_audit_sequence(Sequence),
+    format(atom(AuditURI), 'urn:kibi:audit/~16f-~w-~w-~w',
+           [Timestamp, EntityId, Operation, Sequence]),
+    with_kb_mutex((
+        rdf_assert(AuditURI, 'urn:kibi:audit/operation',
+                   OperationAtom^^'http://www.w3.org/2001/XMLSchema#string', Graph),
+        rdf_assert(AuditURI, 'urn:kibi:audit/timestamp',
+                   TS^^'http://www.w3.org/2001/XMLSchema#string', Graph),
+        rdf_assert(AuditURI, 'urn:kibi:audit/entity',
+                   EntityAtom^^'http://www.w3.org/2001/XMLSchema#string', Graph),
+        rdf_assert(AuditURI, 'urn:kibi:audit/data',
+                   DataAtom^^'http://www.w3.org/2001/XMLSchema#string', Graph)
+    )).
+
+initialize_journal_audit_sequence(GraphURI) :-
+    aggregate_all(count,
+                  rdf(_, 'urn:kibi:audit/operation', _, GraphURI),
+                  Count),
+    retractall(kb_audit_sequence(_)),
+    assert(kb_audit_sequence(Count)).
+
+next_audit_sequence(Sequence) :-
+    (   retract(kb_audit_sequence(Previous))
+    ->  Sequence is Previous + 1
+    ;   Sequence = 1
+    ),
+    assertz(kb_audit_sequence(Sequence)).
+
+kb_assert_audit_event_with_timestamp(TS, Operation, EntityId, Data) :-
+    kb_assert_audit_event_with_timestamp(TS, Operation, EntityId, Data, 0).
+
+kb_assert_audit_event_with_timestamp(TS, Operation, EntityId, Data, Index) :-
+    kb_graph(Graph),
+    term_to_atom(Data, DataAtom),
+    term_to_atom(EntityId, EntityAtom),
+    term_to_atom(Operation, OperationAtom),
+    format(atom(AuditURI), 'urn:kibi:audit/~w-~w-~w-~w',
+           [TS, EntityId, Operation, Index]),
+    with_kb_mutex((
+        rdf_assert(AuditURI, 'urn:kibi:audit/operation',
+                   OperationAtom^^'http://www.w3.org/2001/XMLSchema#string', Graph),
+        rdf_assert(AuditURI, 'urn:kibi:audit/timestamp',
+                   TS^^'http://www.w3.org/2001/XMLSchema#string', Graph),
+        rdf_assert(AuditURI, 'urn:kibi:audit/entity',
+                   EntityAtom^^'http://www.w3.org/2001/XMLSchema#string', Graph),
+        rdf_assert(AuditURI, 'urn:kibi:audit/data',
+                   DataAtom^^'http://www.w3.org/2001/XMLSchema#string', Graph)
+    )).
+
 %% validate_strict_lane_pairing(+RelType, +FromId, +ToId)
 % Validate that constrains/requires_property relationships target facts
 % with the correct fact_kind for strict-lane semantics.
@@ -600,6 +1773,7 @@ entity_id_to_uri(Id, URI) :-
 %% entity_uri_to_id(+URI, -Id)
 % Extract entity ID from canonical or legacy entity URIs.
 entity_uri_to_id(URI, Id) :-
+    atom(URI),
     (   kb_uri(BaseURI),
         atom_concat(BaseURI, 'entity/', Prefix),
         atom_concat(Prefix, Id, URI)
@@ -625,7 +1799,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 +1817,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 +1872,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 +2179,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 +2207,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 +2233,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)