fuli-context 0.11.1 → 0.12.0

package/graph-provider/fuli_graph/knowledge_management.py

@@ -211,11 +211,25 @@ async def reassign_knowledge_item(
     assignment_id = existing.id if existing else _stable_uuid(
         space['id'], 'knowledge-assignment', request.item_kind, item_id
     )
+    item_match = (
+        'MATCH (item:Entity {uuid: $item_id, group_id: $group_id})'
+        if request.item_kind == 'entity'
+        else (
+            'MATCH ()-[item:RELATES_TO '
+            '{uuid: $item_id, group_id: $group_id}]->()'
+        )
+    )
     records, _, _ = await store.runtime.driver.execute_query(
         '''
         MATCH (space:FuliSpace {id: $space_id, kind: 'personal'})
         MATCH (space)-[:CONTAINS_PROJECT]->
               (target:FuliPersonalProject {project_id: $target_project_id})
+        '''
+        + item_match
+        + '''
+        SET item.fuli_ai_review_lock_version =
+              coalesce(item.fuli_ai_review_lock_version, 0) + 1
+        WITH space, target
         MERGE (assignment:FuliKnowledgeAssignment {
           space_id: $space_id,
           item_kind: $item_kind,
@@ -236,6 +250,7 @@ async def reassign_knowledge_item(
         RETURN assignment
         ''',
         space_id=space['id'],
+        group_id=space['group_id'],
         target_project_id=request.target_project_id,
         item_kind=request.item_kind,
         item_id=item_id,
@@ -712,6 +727,8 @@ async def _update_item(store, space, item_id, item_kind, value, embedding):
     if item_kind == 'entity':
         query = '''
         MATCH (item:Entity {uuid: $item_id, group_id: $group_id})
+        SET item.fuli_ai_review_lock_version =
+              coalesce(item.fuli_ai_review_lock_version, 0) + 1
         SET item.name = $name,
             item.summary = $summary,
             item.fuli_invalid_at = $invalid_at,
@@ -744,6 +761,8 @@ async def _update_item(store, space, item_id, item_kind, value, embedding):
     else:
         query = '''
         MATCH ()-[item:RELATES_TO {uuid: $item_id, group_id: $group_id}]->()
+        SET item.fuli_ai_review_lock_version =
+              coalesce(item.fuli_ai_review_lock_version, 0) + 1
         SET item.fact = $fact,
             item.invalid_at = $invalid_at,
             item.fuli_origin_quadrant = $origin_quadrant,
@@ -844,12 +863,16 @@ async def _update_preference_scope(
     if item_kind == 'entity':
         query = '''
         MATCH (item:Entity {uuid: $item_id, group_id: $group_id})
+        SET item.fuli_ai_review_lock_version =
+              coalesce(item.fuli_ai_review_lock_version, 0) + 1
         SET item.fuli_preference_scope = $scope,
             item.fuli_preference_project_id = $project_id
         '''
     else:
         query = '''
         MATCH ()-[item:RELATES_TO {uuid: $item_id, group_id: $group_id}]->()
+        SET item.fuli_ai_review_lock_version =
+              coalesce(item.fuli_ai_review_lock_version, 0) + 1
         SET item.fuli_preference_scope = $scope,
             item.fuli_preference_project_id = $project_id
         '''

package/graph-provider/fuli_graph/knowledge_review.py

@@ -4,6 +4,7 @@ from typing import Any
 from fastapi import HTTPException
 
 from .knowledge_review_models import (
+    KnowledgeReviewAIAssessment,
     KnowledgeReviewCandidate,
     KnowledgeReviewCandidatePage,
     KnowledgeReviewCandidateRequest,
@@ -13,8 +14,10 @@ from .knowledge_review_models import (
     KnowledgeReviewRun,
     KnowledgeReviewStart,
 )
+from .ai_review import ai_review_evidence_token
 from .personal_project_access import authorize_personal_project
 from .provider_values import native_datetime, stable_uuid
+from .store_transactions import query_store_transaction
 
 # These are Provider ranking conventions, not product requirements. Keeping them
 # here gives every Agent the same deterministic policy and makes tuning explicit.
@@ -37,6 +40,8 @@ async def start_knowledge_review(
             store, actor, space, request.personal_project_id
         )
     scope_key = _scope_key(request.scope, request.personal_project_id)
+    if request.reviewer == 'tonborg':
+        scope_key += ':tonborg'
     changed_at = started_at or datetime.now(timezone.utc)
     active_records, _, _ = await store.runtime.driver.execute_query(
         '''
@@ -84,6 +89,10 @@ async def start_knowledge_review(
         completed_records[0].get('previous_completed_at')
         if completed_records else None
     )
+    # Tonborg has its own paginated queue and versioned decision ledger. It must
+    # not advance the human review watermark or lose items beyond one batch.
+    if request.reviewer == 'tonborg':
+        previous_completed_at = None
     review_id = stable_uuid(
         space['id'], 'knowledge-review', scope_key, changed_at.isoformat()
     )
@@ -96,6 +105,7 @@ async def start_knowledge_review(
                       run.scope = $scope,
                       run.personal_project_id = $personal_project_id,
                       run.scope_key = $scope_key,
+                      run.reviewer = $reviewer,
                       run.status = 'active',
                       run.previous_completed_at = $previous_completed_at,
                       run.review_cutoff_at = $started_at,
@@ -112,6 +122,7 @@ async def start_knowledge_review(
         scope=request.scope,
         personal_project_id=request.personal_project_id,
         scope_key=scope_key,
+        reviewer=request.reviewer,
         previous_completed_at=previous_completed_at,
         started_at=changed_at,
     )
@@ -148,6 +159,7 @@ async def list_knowledge_review_candidates(
     conflict_rows, _, _ = await store.runtime.driver.execute_query(
         _CONFLICT_ITEM_QUERY,
         space_id=space['id'],
+        project_id=run.personal_project_id,
         routing_='r',
     )
     decision_rows, _, _ = await store.runtime.driver.execute_query(
@@ -187,12 +199,12 @@ async def list_knowledge_review_candidates(
             if key
         },
     )
-    selected = candidates[:request.limit]
+    selected = candidates[request.offset:request.offset + request.limit]
     return KnowledgeReviewCandidatePage(
         review=run,
         candidates=selected,
         total_candidate_count=len(candidates),
-        remaining_candidate_count=max(len(candidates) - len(selected), 0),
+        remaining_candidate_count=max(len(candidates) - request.offset - len(selected), 0),
     )
 
 
@@ -204,7 +216,7 @@ async def record_knowledge_review_progress(
     changed_at: datetime | None = None,
 ) -> KnowledgeReviewDecision:
     store._require_personal()
-    await _personal_space(store, actor, request.personal_space_id, 'maintainer')
+    space = await _personal_space(store, actor, request.personal_space_id, 'maintainer')
     updated_at = changed_at or datetime.now(timezone.utc)
     decision_id = stable_uuid(
         request.personal_space_id,
@@ -212,6 +224,15 @@ async def record_knowledge_review_progress(
         request.review_id,
         request.candidate_key,
     )
+    if request.outcome == 'ai_reviewed':
+        return await _record_ai_review_progress(
+            store,
+            space,
+            request,
+            decision_id=decision_id,
+            updated_at=updated_at,
+        )
+
     records, _, _ = await store.runtime.driver.execute_query(
         '''
         MATCH (space:FuliSpace {id: $space_id, kind: 'personal'})-
@@ -241,6 +262,97 @@ async def record_knowledge_review_progress(
     return _review_decision(dict(records[0]['decision']))
 
 
+async def _record_ai_review_progress(
+    store,
+    space: dict,
+    request: KnowledgeReviewProgress,
+    *,
+    decision_id: str,
+    updated_at: datetime,
+) -> KnowledgeReviewDecision:
+    """CAS an AI result against a locked, freshly-read item snapshot."""
+
+    item_kind, separator, item_id = request.candidate_key.partition(':')
+    if not separator or item_kind not in {'entity', 'relationship'} or not item_id:
+        raise HTTPException(status_code=422, detail='invalid review candidate')
+
+    async with query_store_transaction(store) as scoped:
+        run_records, _, _ = await scoped.runtime.driver.execute_query(
+            _AI_REVIEW_RUN_QUERY,
+            space_id=space['id'],
+            review_id=request.review_id,
+        )
+        if not run_records:
+            raise HTTPException(status_code=404, detail='active knowledge review not found')
+        run = dict(run_records[0]['run'])
+        if run.get('reviewer') != 'tonborg' and not str(
+            run.get('scope_key', '')
+        ).endswith(':tonborg'):
+            raise HTTPException(
+                status_code=403,
+                detail='AI review progress is only valid for a Tonborg review run',
+            )
+        if run.get('status') not in {'active', 'paused'}:
+            raise HTTPException(status_code=404, detail='active knowledge review not found')
+
+        current_records, _, _ = await scoped.runtime.driver.execute_query(
+            _AI_REVIEW_CURRENT_ENTITY_QUERY
+            if item_kind == 'entity' else _AI_REVIEW_CURRENT_RELATIONSHIP_QUERY,
+            space_id=space['id'],
+            group_id=space['group_id'],
+            item_id=item_id,
+            project_id=run.get('personal_project_id'),
+        )
+        if not current_records:
+            raise HTTPException(status_code=404, detail='review candidate not found')
+        current = dict(current_records[0])
+        normalized = _normalize_item_row(current)
+        if not _item_in_scope(
+            normalized,
+            run['scope'],
+            run.get('personal_project_id'),
+        ):
+            raise HTTPException(
+                status_code=409,
+                detail='review candidate is outside the current project scope',
+            )
+        has_conflict = bool(current.get('has_conflict'))
+        current_token = ai_review_evidence_token(
+            normalized,
+            scope=run['scope'],
+            personal_project_id=run.get('personal_project_id'),
+            has_conflict=has_conflict,
+        )
+        if current_token != request.ai_review_evidence_token:
+            raise HTTPException(
+                status_code=409,
+                detail='knowledge review evidence changed; reload candidate',
+            )
+
+        assessment_json = request.ai_assessment.model_dump_json()
+        write_query = (
+            _AI_REVIEW_ENTITY_WRITE_QUERY
+            if item_kind == 'entity' else _AI_REVIEW_RELATIONSHIP_WRITE_QUERY
+        )
+        records, _, _ = await scoped.runtime.driver.execute_query(
+            write_query,
+            space_id=space['id'],
+            group_id=space['group_id'],
+            item_id=item_id,
+            review_id=request.review_id,
+            decision_id=decision_id,
+            candidate_key=request.candidate_key,
+            outcome=request.outcome,
+            note=request.note,
+            ai_review_evidence_token=current_token,
+            ai_assessment_json=assessment_json,
+            updated_at=updated_at,
+        )
+        if not records:
+            raise HTTPException(status_code=404, detail='active knowledge review not found')
+        return _review_decision(dict(records[0]['decision']))
+
+
 async def finish_knowledge_review(
     store,
     actor: dict,
@@ -300,6 +412,12 @@ def build_review_candidates(
         ):
             continue
         normalized['_candidate_key'] = candidate_key
+        normalized['ai_review_evidence_token'] = ai_review_evidence_token(
+            normalized,
+            scope=scope,
+            personal_project_id=personal_project_id,
+            has_conflict=candidate_key in conflict_item_keys,
+        )
         prepared.append(normalized)
 
     # One stable entity usually accumulates several sessions, while repeated
@@ -389,6 +507,10 @@ def _review_run(value: dict, *, resumed: bool = False) -> KnowledgeReviewRun:
         scope=value['scope'],
         personal_project_id=value.get('personal_project_id'),
         scope_key=value['scope_key'],
+        reviewer=value.get('reviewer') or (
+            'tonborg' if str(value.get('scope_key', '')).endswith(':tonborg')
+            else 'human'
+        ),
         status=value['status'],
         previous_completed_at=native_datetime(value.get('previous_completed_at')),
         review_cutoff_at=native_datetime(
@@ -402,6 +524,17 @@ def _review_run(value: dict, *, resumed: bool = False) -> KnowledgeReviewRun:
 
 
 def _review_decision(value: dict) -> KnowledgeReviewDecision:
+    assessment = value.get('ai_assessment')
+    if assessment is None:
+        assessment = value.get('ai_assessment_json')
+    if isinstance(assessment, str):
+        try:
+            import json
+            assessment = json.loads(assessment)
+        except (TypeError, ValueError):
+            assessment = None
+    if assessment is not None:
+        assessment = KnowledgeReviewAIAssessment.model_validate(assessment)
     return KnowledgeReviewDecision(
         decision_id=value['id'],
         review_id=value['review_id'],
@@ -410,6 +543,10 @@ def _review_decision(value: dict) -> KnowledgeReviewDecision:
         note=value.get('note'),
         created_at=native_datetime(value['created_at']),
         updated_at=native_datetime(value['updated_at']),
+        ai_review_evidence_token=value.get('ai_review_evidence_token'),
+        ai_assessment=assessment,
+        ai_review_scope=value.get('ai_review_scope'),
+        ai_review_project_id=value.get('ai_review_project_id'),
     )
 
 
@@ -420,7 +557,12 @@ def _scope_key(scope: str, personal_project_id: str | None) -> str:
 def _normalize_item_row(row: dict[str, Any]) -> dict[str, Any]:
     project_ids = sorted({
         value
-        for key in ('project_ids', 'assigned_project_ids', 'evidence_project_ids')
+        for key in (
+            'project_ids',
+            'assigned_project_ids',
+            'reference_project_ids',
+            'evidence_project_ids',
+        )
         for value in (row.get(key) or [])
         if value
     })
@@ -439,8 +581,11 @@ def _normalize_item_row(row: dict[str, Any]) -> dict[str, Any]:
         'profile_aspect': row.get('profile_aspect'),
         'preference_scope': row.get('preference_scope'),
         'preference_project_id': row.get('preference_project_id'),
+        'preference_agent_id': row.get('preference_agent_id'),
+        'inheritance_mode': row.get('inheritance_mode') or 'local_only',
         'project_ids': project_ids,
         'confirmation_status': row.get('confirmation_status') or 'pending',
+        'confirmation_basis_json': row.get('confirmation_basis_json'),
         'current_quadrant': row.get('current_quadrant') or 'known_known',
         'utility_score': _float_or_default(row.get('utility_score'), 0),
         'confidence_score': _float_or_default(row.get('confidence_score'), 0.5),
@@ -451,6 +596,10 @@ def _normalize_item_row(row: dict[str, Any]) -> dict[str, Any]:
         'last_feedback_kind': row.get('last_feedback_kind'),
         'distinct_session_count': len(session_ids),
         'changed_at': changed_at,
+        'valid_at': row.get('valid_at'),
+        'invalid_at': row.get('invalid_at'),
+        'human_change_version': int(row.get('human_change_version') or 0),
+        'attributes_json': row.get('attributes_json'),
         '_session_ids': session_ids,
     }
 
@@ -550,6 +699,10 @@ OPTIONAL MATCH (episode:Episodic {group_id: $group_id})-[:MENTIONS]->(item)
 OPTIONAL MATCH (assignment:FuliKnowledgeAssignment {
   space_id: $space_id, item_kind: 'entity', item_id: item.uuid
 })
+OPTIONAL MATCH (:FuliSpace {id: $space_id})-[:HAS_KNOWLEDGE_REFERENCE]->
+              (reference:FuliKnowledgeProjectReference {
+                item_kind: 'entity', item_id: item.uuid, status: 'active'
+              })
 OPTIONAL MATCH (:FuliSpace {id: $space_id})-[:HAS_KNOWLEDGE_REVISION]->
               (revision:FuliKnowledgeRevision {item_kind: 'entity', item_id: item.uuid})
 RETURN item.uuid AS item_id,
@@ -559,12 +712,20 @@ RETURN item.uuid AS item_id,
        item.fuli_profile_aspect AS profile_aspect,
        item.fuli_preference_scope AS preference_scope,
        item.fuli_preference_project_id AS preference_project_id,
+       item.fuli_preference_agent_id AS preference_agent_id,
+       coalesce(item.fuli_inheritance_mode, 'local_only') AS inheritance_mode,
        coalesce(
          item.fuli_current_quadrant,
          item.fuli_origin_quadrant,
          'known_known'
        ) AS current_quadrant,
+       item.fuli_confirmation_basis_json AS confirmation_basis_json,
+       NULL AS valid_at,
+       item.fuli_invalid_at AS invalid_at,
+       coalesce(item.fuli_human_change_version, 0) AS human_change_version,
+       coalesce(item.fuli_attributes_json, '{}') AS attributes_json,
        collect(DISTINCT assignment.project_id) AS assigned_project_ids,
+       collect(DISTINCT reference.project_id) AS reference_project_ids,
        collect(DISTINCT episode.fuli_personal_project_id) AS evidence_project_ids,
        collect(DISTINCT episode.fuli_session_id) AS session_ids,
        coalesce(item.fuli_confirmation_status, 'pending') AS confirmation_status,
@@ -590,6 +751,10 @@ WHERE episode.uuid IN coalesce(item.episodes, [])
 OPTIONAL MATCH (assignment:FuliKnowledgeAssignment {
   space_id: $space_id, item_kind: 'relationship', item_id: item.uuid
 })
+OPTIONAL MATCH (:FuliSpace {id: $space_id})-[:HAS_KNOWLEDGE_REFERENCE]->
+              (reference:FuliKnowledgeProjectReference {
+                item_kind: 'relationship', item_id: item.uuid, status: 'active'
+              })
 OPTIONAL MATCH (:FuliSpace {id: $space_id})-[:HAS_KNOWLEDGE_REVISION]->
               (revision:FuliKnowledgeRevision {
                 item_kind: 'relationship', item_id: item.uuid
@@ -601,12 +766,20 @@ RETURN item.uuid AS item_id,
        item.fuli_profile_aspect AS profile_aspect,
        item.fuli_preference_scope AS preference_scope,
        item.fuli_preference_project_id AS preference_project_id,
+       item.fuli_preference_agent_id AS preference_agent_id,
+       coalesce(item.fuli_inheritance_mode, 'local_only') AS inheritance_mode,
        coalesce(
          item.fuli_current_quadrant,
          item.fuli_origin_quadrant,
          'known_known'
        ) AS current_quadrant,
+       item.fuli_confirmation_basis_json AS confirmation_basis_json,
+       item.valid_at AS valid_at,
+       item.invalid_at AS invalid_at,
+       coalesce(item.fuli_human_change_version, 0) AS human_change_version,
+       coalesce(item.fuli_attributes_json, '{}') AS attributes_json,
        collect(DISTINCT assignment.project_id) AS assigned_project_ids,
+       collect(DISTINCT reference.project_id) AS reference_project_ids,
        collect(DISTINCT episode.fuli_personal_project_id) AS evidence_project_ids,
        collect(DISTINCT episode.fuli_session_id) AS session_ids,
        coalesce(item.fuli_confirmation_status, 'pending') AS confirmation_status,
@@ -628,6 +801,9 @@ _CONFLICT_ITEM_QUERY = '''
 MATCH (space:FuliSpace {id: $space_id, kind: 'personal'})
 OPTIONAL MATCH (space)-[:HAS_KNOWLEDGE_CONFLICT]->
               (knowledge:FuliKnowledgeConflict {status: 'pending'})
+WHERE ($project_id IS NULL
+       OR knowledge.target_project_id = $project_id
+       OR knowledge.source_project_id = $project_id)
 WITH space, collect(DISTINCT 'entity:' + knowledge.item_id) +
      collect(DISTINCT 'relationship:' + knowledge.item_id) +
      collect(DISTINCT 'entity:' + knowledge.target_item_id) +
@@ -635,6 +811,7 @@ WITH space, collect(DISTINCT 'entity:' + knowledge.item_id) +
      AS knowledge_keys
 OPTIONAL MATCH (space)-[:HAS_PREFERENCE_CONFLICT]->
               (preference:FuliPreferenceConflict {status: 'ai_pending'})
+WHERE $project_id IS NULL OR preference.preference_project_id = $project_id
 WITH knowledge_keys,
      collect(DISTINCT preference.left_item_kind + ':' + preference.left_item_id) +
      collect(DISTINCT preference.right_item_kind + ':' + preference.right_item_id)
@@ -655,3 +832,205 @@ WITH candidate_key, collect(decision)[0] AS latest_decision
 WHERE latest_decision.outcome = 'deferred'
 RETURN collect(candidate_key) AS candidate_keys
 '''
+
+
+# These queries intentionally perform a property write before the dependent
+# read. Neo4j then holds a write lock on the item until the surrounding
+# query_store_transaction commits or rolls back, closing the read/decision CAS
+# window even when a knowledge edit has not yet written its revision metadata.
+_AI_REVIEW_CURRENT_ENTITY_QUERY = '''
+MATCH (item:Entity {uuid: $item_id, group_id: $group_id})
+SET item.fuli_ai_review_lock_version =
+      coalesce(item.fuli_ai_review_lock_version, 0) + 1
+WITH item
+OPTIONAL MATCH (episode:Episodic {group_id: $group_id})-[:MENTIONS]->(item)
+OPTIONAL MATCH (assignment:FuliKnowledgeAssignment {
+  space_id: $space_id, item_kind: 'entity', item_id: item.uuid
+})
+OPTIONAL MATCH (:FuliSpace {id: $space_id})-[:HAS_KNOWLEDGE_REFERENCE]->
+               (reference:FuliKnowledgeProjectReference {
+                 item_kind: 'entity', item_id: item.uuid, status: 'active'
+               })
+WITH item,
+     collect(DISTINCT assignment.project_id) +
+     collect(DISTINCT reference.project_id) +
+     collect(DISTINCT episode.fuli_personal_project_id) AS project_ids
+OPTIONAL MATCH (space:FuliSpace {id: $space_id, kind: 'personal'})-
+               [:HAS_KNOWLEDGE_CONFLICT]->
+               (knowledge:FuliKnowledgeConflict {status: 'pending'})
+WHERE (knowledge.item_id = item.uuid OR knowledge.target_item_id = item.uuid)
+  AND ($project_id IS NULL
+       OR knowledge.target_project_id = $project_id
+       OR knowledge.source_project_id = $project_id)
+WITH item, project_ids, collect(DISTINCT knowledge.id) AS knowledge_conflicts
+OPTIONAL MATCH (space:FuliSpace {id: $space_id, kind: 'personal'})-
+               [:HAS_PREFERENCE_CONFLICT]->
+               (preference:FuliPreferenceConflict {status: 'ai_pending'})
+WHERE (preference.left_item_id = item.uuid OR preference.right_item_id = item.uuid)
+  AND ($project_id IS NULL OR preference.preference_project_id = $project_id)
+WITH item, project_ids, knowledge_conflicts,
+     collect(DISTINCT preference.id) AS preference_conflicts
+RETURN item.uuid AS item_id,
+       'entity' AS item_kind,
+       item.name AS title,
+       coalesce(item.summary, '') AS content,
+       item.fuli_profile_aspect AS profile_aspect,
+       item.fuli_preference_scope AS preference_scope,
+       item.fuli_preference_project_id AS preference_project_id,
+       item.fuli_preference_agent_id AS preference_agent_id,
+       coalesce(item.fuli_inheritance_mode, 'local_only') AS inheritance_mode,
+       coalesce(item.fuli_current_quadrant, item.fuli_origin_quadrant,
+                'known_known') AS current_quadrant,
+       item.fuli_confirmation_status AS confirmation_status,
+       item.fuli_confirmation_basis_json AS confirmation_basis_json,
+       NULL AS valid_at,
+       item.fuli_invalid_at AS invalid_at,
+       coalesce(item.fuli_utility_score, 0.0) AS utility_score,
+       coalesce(item.fuli_confidence_score, 0.5) AS confidence_score,
+       coalesce(item.fuli_qualified_use_count, 0) AS qualified_use_count,
+       coalesce(item.fuli_distinct_task_count, 0) AS distinct_task_count,
+       coalesce(item.fuli_negative_evidence_count, 0) AS negative_evidence_count,
+       coalesce(item.fuli_requires_attention, false) AS requires_attention,
+       coalesce(item.fuli_human_change_version, 0) AS human_change_version,
+       coalesce(item.fuli_attributes_json, '{}') AS attributes_json,
+       project_ids,
+       CASE WHEN size(knowledge_conflicts) + size(preference_conflicts) > 0
+            THEN true ELSE false END AS has_conflict,
+       item.created_at AS created_at,
+       item.fuli_last_human_changed_at AS last_human_changed_at,
+       item.fuli_last_feedback_at AS last_feedback_at,
+       item.fuli_last_feedback_kind AS last_feedback_kind,
+       [] AS session_ids
+'''
+
+
+_AI_REVIEW_CURRENT_RELATIONSHIP_QUERY = '''
+MATCH ()-[item:RELATES_TO {uuid: $item_id, group_id: $group_id}]->()
+SET item.fuli_ai_review_lock_version =
+      coalesce(item.fuli_ai_review_lock_version, 0) + 1
+WITH item
+OPTIONAL MATCH (episode:Episodic {group_id: $group_id})
+WHERE episode.uuid IN coalesce(item.episodes, [])
+OPTIONAL MATCH (assignment:FuliKnowledgeAssignment {
+  space_id: $space_id, item_kind: 'relationship', item_id: item.uuid
+})
+OPTIONAL MATCH (:FuliSpace {id: $space_id})-[:HAS_KNOWLEDGE_REFERENCE]->
+               (reference:FuliKnowledgeProjectReference {
+                 item_kind: 'relationship', item_id: item.uuid, status: 'active'
+               })
+WITH item,
+     collect(DISTINCT assignment.project_id) +
+     collect(DISTINCT reference.project_id) +
+     collect(DISTINCT episode.fuli_personal_project_id) AS project_ids
+OPTIONAL MATCH (space:FuliSpace {id: $space_id, kind: 'personal'})-
+               [:HAS_KNOWLEDGE_CONFLICT]->
+               (knowledge:FuliKnowledgeConflict {status: 'pending'})
+WHERE (knowledge.item_id = item.uuid OR knowledge.target_item_id = item.uuid)
+  AND ($project_id IS NULL
+       OR knowledge.target_project_id = $project_id
+       OR knowledge.source_project_id = $project_id)
+WITH item, project_ids, collect(DISTINCT knowledge.id) AS knowledge_conflicts
+OPTIONAL MATCH (space:FuliSpace {id: $space_id, kind: 'personal'})-
+               [:HAS_PREFERENCE_CONFLICT]->
+               (preference:FuliPreferenceConflict {status: 'ai_pending'})
+WHERE (preference.left_item_id = item.uuid OR preference.right_item_id = item.uuid)
+  AND ($project_id IS NULL OR preference.preference_project_id = $project_id)
+WITH item, project_ids, knowledge_conflicts,
+     collect(DISTINCT preference.id) AS preference_conflicts
+RETURN item.uuid AS item_id,
+       'relationship' AS item_kind,
+       coalesce(item.name, 'RELATES_TO') AS title,
+       coalesce(item.fact, '') AS content,
+       item.fuli_profile_aspect AS profile_aspect,
+       item.fuli_preference_scope AS preference_scope,
+       item.fuli_preference_project_id AS preference_project_id,
+       item.fuli_preference_agent_id AS preference_agent_id,
+       coalesce(item.fuli_inheritance_mode, 'local_only') AS inheritance_mode,
+       coalesce(item.fuli_current_quadrant, item.fuli_origin_quadrant,
+                'known_known') AS current_quadrant,
+       item.fuli_confirmation_status AS confirmation_status,
+       item.fuli_confirmation_basis_json AS confirmation_basis_json,
+       item.valid_at AS valid_at,
+       item.invalid_at AS invalid_at,
+       coalesce(item.fuli_utility_score, 0.0) AS utility_score,
+       coalesce(item.fuli_confidence_score, 0.5) AS confidence_score,
+       coalesce(item.fuli_qualified_use_count, 0) AS qualified_use_count,
+       coalesce(item.fuli_distinct_task_count, 0) AS distinct_task_count,
+       coalesce(item.fuli_negative_evidence_count, 0) AS negative_evidence_count,
+       coalesce(item.fuli_requires_attention, false) AS requires_attention,
+       coalesce(item.fuli_human_change_version, 0) AS human_change_version,
+       coalesce(item.fuli_attributes_json, '{}') AS attributes_json,
+       project_ids,
+       CASE WHEN size(knowledge_conflicts) + size(preference_conflicts) > 0
+            THEN true ELSE false END AS has_conflict,
+       item.created_at AS created_at,
+       item.fuli_last_human_changed_at AS last_human_changed_at,
+       item.fuli_last_feedback_at AS last_feedback_at,
+       item.fuli_last_feedback_kind AS last_feedback_kind,
+       [] AS session_ids
+'''
+
+
+_AI_REVIEW_RUN_QUERY = '''
+MATCH (:FuliSpace {id: $space_id, kind: 'personal'})-
+      [:HAS_KNOWLEDGE_REVIEW]->(run:FuliKnowledgeReviewRun {id: $review_id})
+RETURN run
+'''
+
+
+_AI_REVIEW_ENTITY_WRITE_QUERY = '''
+MATCH (space:FuliSpace {id: $space_id, kind: 'personal'})-
+      [:HAS_KNOWLEDGE_REVIEW]->(run:FuliKnowledgeReviewRun {id: $review_id})
+MATCH (item:Entity {uuid: $item_id, group_id: $group_id})
+WHERE run.status IN ['active', 'paused']
+MERGE (decision:FuliKnowledgeReviewDecision {id: $decision_id})
+ON CREATE SET decision.created_at = $updated_at
+SET item.fuli_ai_review_evidence_token = $ai_review_evidence_token,
+    item.fuli_ai_assessment_json = $ai_assessment_json,
+    item.fuli_ai_review_scope = run.scope,
+    item.fuli_ai_review_project_id = run.personal_project_id,
+    item.fuli_ai_reviewed_at = $updated_at,
+    item.fuli_ai_review_id = $review_id,
+    item.fuli_ai_review_decision_id = $decision_id,
+    decision.review_id = $review_id,
+    decision.candidate_key = $candidate_key,
+    decision.outcome = $outcome,
+    decision.note = $note,
+    decision.ai_review_evidence_token = $ai_review_evidence_token,
+    decision.ai_assessment_json = $ai_assessment_json,
+    decision.ai_review_scope = run.scope,
+    decision.ai_review_project_id = run.personal_project_id,
+    decision.updated_at = $updated_at,
+    run.updated_at = $updated_at
+MERGE (run)-[:HAS_REVIEW_DECISION]->(decision)
+RETURN decision
+'''
+
+
+_AI_REVIEW_RELATIONSHIP_WRITE_QUERY = '''
+MATCH (space:FuliSpace {id: $space_id, kind: 'personal'})-
+      [:HAS_KNOWLEDGE_REVIEW]->(run:FuliKnowledgeReviewRun {id: $review_id})
+MATCH ()-[item:RELATES_TO {uuid: $item_id, group_id: $group_id}]->()
+WHERE run.status IN ['active', 'paused']
+MERGE (decision:FuliKnowledgeReviewDecision {id: $decision_id})
+ON CREATE SET decision.created_at = $updated_at
+SET item.fuli_ai_review_evidence_token = $ai_review_evidence_token,
+    item.fuli_ai_assessment_json = $ai_assessment_json,
+    item.fuli_ai_review_scope = run.scope,
+    item.fuli_ai_review_project_id = run.personal_project_id,
+    item.fuli_ai_reviewed_at = $updated_at,
+    item.fuli_ai_review_id = $review_id,
+    item.fuli_ai_review_decision_id = $decision_id,
+    decision.review_id = $review_id,
+    decision.candidate_key = $candidate_key,
+    decision.outcome = $outcome,
+    decision.note = $note,
+    decision.ai_review_evidence_token = $ai_review_evidence_token,
+    decision.ai_assessment_json = $ai_assessment_json,
+    decision.ai_review_scope = run.scope,
+    decision.ai_review_project_id = run.personal_project_id,
+    decision.updated_at = $updated_at,
+    run.updated_at = $updated_at
+MERGE (run)-[:HAS_REVIEW_DECISION]->(decision)
+RETURN decision
+'''