fuli-context 0.7.3 → 0.7.4-beta.1

package/graph-provider/fuli_graph/project_action_models.py

@@ -29,6 +29,7 @@ KnowledgeProjectMatchKind = Literal[
     'exact_duplicate',
     'conflict',
 ]
+PersonalProjectRelationStatus = Literal['pending', 'active', 'rejected']
 
 
 class KnowledgeProjectPreviewRequest(StrictModel):
@@ -140,3 +141,24 @@ class KnowledgeProjectActionResult(StrictModel):
     match: KnowledgeProjectMatch
     reference: KnowledgeProjectReferenceRecord | None = None
     conflict: KnowledgeConflictRecord | None = None
+
+
+class PersonalProjectRelationReviewRequest(StrictModel):
+    decision: Literal['activate', 'reject']
+    decision_revision: int = Field(ge=0)
+    reason: str = Field(min_length=1, max_length=2000)
+
+
+class PersonalProjectRelationReviewRecord(StrictModel):
+    relation_id: str
+    personal_space_id: str
+    source_project_id: str
+    target_project_id: str
+    relation_type: ProjectRelationType
+    status: PersonalProjectRelationStatus
+    confirmation_authority: Literal['human_review'] | None = None
+    decision_revision: int = Field(ge=1)
+    reviewed_by: str
+    reviewed_at: datetime
+    review_reason: str
+    review_event_id: str

package/graph-provider/fuli_graph/project_knowledge.py

@@ -23,8 +23,11 @@ from .project_action_models import (
     KnowledgeProjectMatch,
     KnowledgeProjectPreviewRecord,
     KnowledgeProjectPreviewRequest,
+    PersonalProjectRelationReviewRecord,
+    PersonalProjectRelationReviewRequest,
 )
 from .provider_values import (
+    native_datetime as _native_datetime,
     normalized_text as _normalized,
     stable_uuid as _stable_uuid,
 )
@@ -209,7 +212,10 @@ async def _record_project_action_if_human(
     item_id,
     request,
 ):
-    if request.operation_actor != 'human':
+    if (
+        request.operation_actor != 'human'
+        or actor.get('_human_review_verified') is not True
+    ):
         return
     await record_human_change(
         store,
@@ -295,6 +301,70 @@ async def read_personal_project_relations(store, space_id: str) -> list[dict]:
     ]
 
 
+async def review_personal_project_relation(
+    store,
+    actor: dict,
+    space_id: str,
+    relation_id: str,
+    request: PersonalProjectRelationReviewRequest,
+) -> PersonalProjectRelationReviewRecord:
+    store._require_personal()
+    space = await store.authorize(actor, space_id, 'maintainer')
+    if space['kind'] != 'personal':
+        raise HTTPException(
+            status_code=422,
+            detail='personal project relation review is personal-only',
+        )
+    reviewed_at = datetime.now(timezone.utc)
+    next_revision = request.decision_revision + 1
+    status = 'active' if request.decision == 'activate' else 'rejected'
+    review_event_id = _stable_uuid(
+        space_id,
+        'personal-project-relation-review',
+        relation_id,
+        str(next_revision),
+        request.decision,
+    )
+    records, _, _ = await store.runtime.driver.execute_query(
+        _REVIEW_PERSONAL_PROJECT_RELATION_QUERY,
+        space_id=space_id,
+        relation_id=relation_id,
+        expected_revision=request.decision_revision,
+        next_revision=next_revision,
+        status=status,
+        confirmation_authority=(
+            'human_review' if status == 'active' else None
+        ),
+        reviewed_by=actor['id'],
+        reviewed_at=reviewed_at,
+        review_reason=request.reason,
+        review_event_id=review_event_id,
+    )
+    if not records:
+        raise HTTPException(
+            status_code=409,
+            detail=(
+                'personal project relation is missing or its review revision '
+                'changed; refresh before deciding'
+            ),
+        )
+    value = dict(records[0])
+    return PersonalProjectRelationReviewRecord(
+        relation_id=value['relation_id'],
+        personal_space_id=space_id,
+        source_project_id=value['source_project_id'],
+        target_project_id=value['target_project_id'],
+        relation_type=value['relation_type'],
+        status=value['status'],
+        confirmation_authority=value.get('confirmation_authority'),
+        decision_revision=int(value['decision_revision']),
+        reviewed_by=value['reviewed_by'],
+        reviewed_at=_native_datetime(value['reviewed_at']),
+        review_reason=value['review_reason'],
+        review_event_id=value['review_event_id'],
+    )
+
+
 async def _authorize_item(store, actor, item_id, request):
     store._require_personal()
     space = await store.authorize(actor, request.personal_space_id, 'maintainer')
@@ -631,7 +701,13 @@ async def _maybe_create_project_relation(
           relation_type: $relation_type
         }]->(target)
         ON CREATE SET relation.created_at = $changed_at,
-                      relation.created_by = $created_by
+                      relation.created_by = $created_by,
+                      relation.status = 'pending',
+                      relation.confirmation_authority = null,
+                      relation.decision_revision = 0,
+                      relation.reviewed_by = null,
+                      relation.reviewed_at = null,
+                      relation.review_reason = null
         SET relation.updated_at = $changed_at
         RETURN relation.id AS id
         ''',
@@ -646,6 +722,49 @@ async def _maybe_create_project_relation(
     return bool(records)
 
 
+_REVIEW_PERSONAL_PROJECT_RELATION_QUERY = '''
+/* fuli:review-personal-project-relation */
+MATCH (space:FuliSpace {id: $space_id, kind: 'personal'})-
+      [:CONTAINS_PROJECT]->
+      (source:FuliPersonalProject)-
+      [relation:PERSONAL_PROJECT_RELATION {id: $relation_id}]->
+      (target:FuliPersonalProject)
+SET relation.cas_lock = coalesce(relation.cas_lock, 0) + 1
+WITH space, source, target, relation
+WHERE coalesce(relation.decision_revision, 0) = $expected_revision
+SET relation.status = $status,
+    relation.confirmation_authority = $confirmation_authority,
+    relation.decision_revision = $next_revision,
+    relation.reviewed_by = $reviewed_by,
+    relation.reviewed_at = $reviewed_at,
+    relation.review_reason = $review_reason,
+    relation.updated_at = $reviewed_at
+CREATE (review:FuliPersonalProjectRelationReview {
+  id: $review_event_id,
+  space_id: $space_id,
+  relation_id: $relation_id,
+  decision_revision: $next_revision,
+  decision: $status,
+  confirmation_authority: 'human_review',
+  reason: $review_reason,
+  reviewed_by: $reviewed_by,
+  reviewed_at: $reviewed_at
+})
+MERGE (space)-[:HAS_PERSONAL_PROJECT_RELATION_REVIEW]->(review)
+RETURN relation.id AS relation_id,
+       source.project_id AS source_project_id,
+       target.project_id AS target_project_id,
+       relation.relation_type AS relation_type,
+       relation.status AS status,
+       relation.confirmation_authority AS confirmation_authority,
+       relation.decision_revision AS decision_revision,
+       relation.reviewed_by AS reviewed_by,
+       relation.reviewed_at AS reviewed_at,
+       relation.review_reason AS review_reason,
+       review.id AS review_event_id
+'''
+
+
 def _relation_endpoints(source_project_id, target_project_id, request):
     """Keep an extracted project as the child side of directional relations."""
     if request.mode == 'create':

package/graph-provider/fuli_graph/provider_values.py

@@ -36,5 +36,29 @@ def json_object(value) -> dict:
     return parsed if isinstance(parsed, dict) else {}
 
 
+_PREFERENCE_QUALIFIER_EXCLUSIONS = frozenset({
+    'preferenceKey',
+    'preference_key',
+    'searchTerms',
+    'search_terms',
+    'weight',
+})
+
+
+def preference_qualifiers(value) -> dict:
+    """Project content qualifiers safe to expose and bind to review state.
+
+    Retrieval aliases, ranking hints, and the separately projected semantic key
+    are intentionally omitted. Remaining JSON attributes preserve source-level
+    qualifications such as language, audience, conditions, and rationale.
+    """
+    attributes = json_object(value)
+    return {
+        str(key): attributes[key]
+        for key in sorted(attributes, key=str)
+        if key not in _PREFERENCE_QUALIFIER_EXCLUSIONS
+    }
+
+
 def normalized_text(value) -> str:
     return ' '.join(str(value or '').strip().casefold().split())

package/graph-provider/fuli_graph/runtime.py

@@ -181,6 +181,60 @@ class GraphitiRuntime:
             'CREATE CONSTRAINT fuli_knowledge_review_decision_id IF NOT EXISTS '
             'FOR (n:FuliKnowledgeReviewDecision) REQUIRE n.id IS UNIQUE'
         )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_workflow_candidate_id IF NOT EXISTS '
+            'FOR (n:FuliWorkflowCandidate) REQUIRE n.id IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_workflow_review_event_id IF NOT EXISTS '
+            'FOR (n:FuliWorkflowReviewEvent) REQUIRE n.id IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_workflow_review_preview_id IF NOT EXISTS '
+            'FOR (n:FuliWorkflowReviewPreview) REQUIRE n.id IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_workflow_review_preview_token IF NOT EXISTS '
+            'FOR (n:FuliWorkflowReviewPreview) REQUIRE n.token_hash IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_workflow_rule_id IF NOT EXISTS '
+            'FOR (n:FuliWorkflowRule) REQUIRE n.id IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_workflow_authorization_id IF NOT EXISTS '
+            'FOR (n:FuliWorkflowAuthorization) REQUIRE n.id IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_personal_global_preference_decision '
+            'IF NOT EXISTS '
+            'FOR (n:FuliPersonalGlobalPreferenceDecision) '
+            'REQUIRE (n.space_id, n.candidate_id) IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_personal_global_preference_event '
+            'IF NOT EXISTS '
+            'FOR (n:FuliPersonalGlobalPreferenceDecisionEvent) '
+            'REQUIRE n.id IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_personal_global_preference_preview '
+            'IF NOT EXISTS '
+            'FOR (n:FuliPersonalGlobalPreferenceDecisionPreview) '
+            'REQUIRE n.id IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_personal_global_preference_preview_token '
+            'IF NOT EXISTS '
+            'FOR (n:FuliPersonalGlobalPreferenceDecisionPreview) '
+            'REQUIRE n.token_hash IS UNIQUE'
+        )
+        await self.driver.execute_query(
+            'CREATE CONSTRAINT fuli_personal_project_relation_review '
+            'IF NOT EXISTS '
+            'FOR (n:FuliPersonalProjectRelationReview) '
+            'REQUIRE n.id IS UNIQUE'
+        )
         for query in (
             'CREATE INDEX fuli_entity_confirmation IF NOT EXISTS '
             'FOR (n:Entity) ON (n.group_id, n.fuli_confirmation_status)',
@@ -208,10 +262,34 @@ class GraphitiRuntime:
         ):
             await self.driver.execute_query(query)
         await self._migrate_knowledge_lifecycle_defaults()
+        await self._migrate_personal_project_relation_review_defaults()
         await self._migrate_space_visibility_and_owners()
         await self._migrate_project_releases()
         await self._migrate_legacy_group_ids()
 
+    async def _migrate_personal_project_relation_review_defaults(self) -> None:
+        await self.driver.execute_query(
+            '''
+            MATCH ()-[relation:PERSONAL_PROJECT_RELATION]->()
+            WHERE relation.status IS NULL
+               OR relation.decision_revision IS NULL
+               OR relation.confirmation_authority IS NULL
+            SET relation.status = CASE
+                  WHEN relation.status IN ['active', 'rejected']
+                    THEN relation.status
+                  ELSE 'pending'
+                END,
+                relation.decision_revision =
+                  coalesce(relation.decision_revision, 0),
+                relation.confirmation_authority = CASE
+                  WHEN relation.status = 'active'
+                    AND relation.confirmation_authority = 'human_review'
+                    THEN 'human_review'
+                  ELSE null
+                END
+            '''
+        )
+
     async def _migrate_space_visibility_and_owners(self) -> None:
         await self.driver.execute_query(
             "MATCH (s:FuliSpace) WHERE s.visibility IS NULL "

package/graph-provider/fuli_graph/search_projection.py

@@ -7,7 +7,11 @@ from .models import (
     FactResult,
     _validate_confirmation_state,
 )
-from .provider_values import json_object, native_datetime as _native_datetime
+from .provider_values import (
+    json_object,
+    native_datetime as _native_datetime,
+    preference_qualifiers,
+)
 
 
 def is_default_retrievable(metadata: dict) -> bool:
@@ -54,6 +58,7 @@ async def read_edge_epistemic_metadata(store, edge_ids: list[str]) -> dict[str,
                     AS preference_scope,
                edge.fuli_preference_project_id AS preference_project_id,
                edge.fuli_key AS key,
+               edge.fuli_attributes_json AS attributes_json,
                coalesce(edge.fuli_inheritance_mode, 'local_only')
                  AS inheritance_mode,
                coalesce(edge.fuli_inherited_project_ids, [])
@@ -111,6 +116,7 @@ def fact_result(
     epistemic: dict | None = None,
 ) -> FactResult:
     metadata = epistemic or {}
+    attributes = json_object(metadata.get('attributes_json'))
     return FactResult(
         id=edge.uuid,
         space_id=space_id,
@@ -135,6 +141,13 @@ def fact_result(
         preference_scope=metadata.get('preference_scope'),
         preference_project_id=metadata.get('preference_project_id'),
         key=metadata.get('key'),
+        preference_key=(
+            attributes.get('preferenceKey')
+            or attributes.get('preference_key')
+            or metadata.get('key')
+            or edge.uuid
+        ),
+        preference_qualifiers=preference_qualifiers(attributes),
         defined_project_id=metadata.get('defined_project_id'),
         inheritance_mode=metadata.get('inheritance_mode') or 'local_only',
         inherited_project_ids=metadata.get('inherited_project_ids') or [],

package/graph-provider/fuli_graph/store_knowledge.py

@@ -17,6 +17,7 @@ from .models import (
 )
 from .personal_project_access import authorize_personal_project
 from .provider_values import now_utc, stable_uuid
+from .workflow_candidates import materialize_workflow_candidates
 
 
 class StoreKnowledge:
@@ -35,6 +36,29 @@ class StoreKnowledge:
             personal_project_id=request.personal_project_id,
         )
 
+    async def commit_workflow_observation(
+        self,
+        actor: dict,
+        request: KnowledgeCommit,
+    ) -> CommitResult:
+        self._require_personal()
+        space = await self.authorize(actor, request.space_id, 'maintainer')
+        if space['kind'] != 'personal':
+            raise HTTPException(
+                status_code=422,
+                detail='workflow observations are personal-only',
+            )
+        if request.personal_project_id:
+            await authorize_personal_project(
+                self, actor, space, request.personal_project_id
+            )
+        return await self._commit_episode(
+            space,
+            request.episode,
+            personal_project_id=request.personal_project_id,
+            workflow_session_authority='mcp_host',
+        )
+
     async def search(self, actor: dict, request: SearchRequest) -> SearchResult:
         return await search_knowledge(self, actor, request)
 
@@ -71,6 +95,7 @@ class StoreKnowledge:
         episode: StructuredEpisode,
         *,
         personal_project_id: str | None = None,
+        workflow_session_authority: str | None = None,
     ) -> CommitResult:
         group_id = space['group_id']
         lock = self._group_locks.setdefault(group_id, asyncio.Lock())
@@ -90,6 +115,12 @@ class StoreKnowledge:
                 )
                 for entity in episode.entities
             ]
+            entity_id_by_key = {
+                entity.key: entity_id
+                for entity, entity_id in zip(
+                    episode.entities, entity_ids, strict=True
+                )
+            }
             relationship_ids = [
                 _relationship_id(
                     group_id,
@@ -98,10 +129,40 @@ class StoreKnowledge:
                     relationship.key,
                     relationship.fact,
                     (relationship.valid_at or episode.reference_time).isoformat(),
+                    workflow_session_authority=workflow_session_authority,
                 )
                 for relationship in episode.relationships
             ]
+            entity_input_by_key = {
+                entity.key: entity for entity in episode.entities
+            }
+            workflow_pairs = [
+                {
+                    'workflow_key': relationship.key,
+                    'source_step_id': entity_id_by_key[relationship.source],
+                    'source_step_key': relationship.source,
+                    'source_step_name': (
+                        entity_input_by_key[relationship.source].name
+                    ),
+                    'target_step_id': entity_id_by_key[relationship.target],
+                    'target_step_key': relationship.target,
+                    'target_step_name': (
+                        entity_input_by_key[relationship.target].name
+                    ),
+                    'condition_json': _workflow_condition_json(
+                        relationship.attributes
+                    ),
+                }
+                for relationship in episode.relationships
+                if relationship.type == 'RECOMMENDS_NEXT'
+            ]
             if existing:
+                await materialize_workflow_candidates(
+                    self,
+                    space,
+                    personal_project_id=personal_project_id,
+                    pairs=workflow_pairs,
+                )
                 return CommitResult(
                     status='duplicate',
                     space_id=space['id'],
@@ -210,6 +271,15 @@ class StoreKnowledge:
                         'attributes_json': json.dumps(
                             relationship.attributes, ensure_ascii=False, sort_keys=True
                         ),
+                        'workflow_condition_json': _workflow_condition_json(
+                            relationship.attributes
+                        ),
+                        'workflow_confirmation_authority': (
+                            _workflow_confirmation_authority(relationship)
+                        ),
+                        'workflow_session_authority': (
+                            workflow_session_authority
+                        ),
                     }
                 )
 
@@ -276,7 +346,9 @@ class StoreKnowledge:
                   fuli_summary: $summary,
                   fuli_sensitivity: $sensitivity,
                   fuli_personal_project_id: $personal_project_id,
-                  fuli_idempotency_key: $idempotency_key
+                  fuli_idempotency_key: $idempotency_key,
+                  fuli_workflow_session_authority:
+                    $workflow_session_authority
                 })
                 WITH episode
                 UNWIND $entities AS row
@@ -316,7 +388,13 @@ class StoreKnowledge:
                     edge.fuli_inherited_project_ids = row.inherited_project_ids,
                     edge.fuli_preference_scope = row.preference_scope,
                     edge.fuli_preference_project_id = row.preference_project_id,
-                    edge.fuli_attributes_json = row.attributes_json
+                    edge.fuli_attributes_json = row.attributes_json,
+                    edge.fuli_workflow_condition_json =
+                      row.workflow_condition_json,
+                    edge.fuli_workflow_confirmation_authority =
+                      row.workflow_confirmation_authority,
+                    edge.fuli_workflow_session_authority =
+                      row.workflow_session_authority
                 SET edge.episodes =
                   CASE WHEN $episode_id IN coalesce(edge.episodes, [])
                        THEN edge.episodes
@@ -400,8 +478,15 @@ class StoreKnowledge:
                 summary=episode.summary,
                 sensitivity=episode.sensitivity,
                 personal_project_id=personal_project_id,
+                workflow_session_authority=workflow_session_authority,
                 idempotency_key=episode.idempotency_key,
             )
+            await materialize_workflow_candidates(
+                self,
+                space,
+                personal_project_id=personal_project_id,
+                pairs=workflow_pairs,
+            )
             return CommitResult(
                 status='committed',
                 space_id=space['id'],
@@ -419,6 +504,28 @@ def _initial_confidence(status: str) -> float:
     }[status]
 
 
+def _workflow_condition_json(attributes: dict) -> str:
+    condition = attributes.get(
+        'workflowCondition',
+        attributes.get('workflow_condition', {}),
+    )
+    if not isinstance(condition, dict):
+        condition = {}
+    return json.dumps(condition, ensure_ascii=False, sort_keys=True)
+
+
+def _workflow_confirmation_authority(relationship) -> str:
+    basis = relationship.confirmation_basis
+    if relationship.confirmation_status == 'confirmed' and basis.confirmed_by:
+        return basis.confirmed_by.kind
+    return {
+        'agent': 'agent_proposed',
+        'import': 'import_proposed',
+        'user': 'user',
+        'authoritative_source': 'authoritative_source',
+    }[basis.proposed_by.kind]
+
+
 def _entity_id(
     group_id: str,
     space_kind: str,
@@ -443,8 +550,15 @@ def _relationship_id(
     key: str,
     fact: str,
     reference_time: str,
+    *,
+    workflow_session_authority: str | None = None,
 ) -> str:
     parts = [group_id, 'relationship']
     if space_kind == 'personal' and personal_project_id:
         parts.extend(['personal-project', personal_project_id])
+    if workflow_session_authority:
+        parts.extend([
+            'workflow-session-authority',
+            workflow_session_authority,
+        ])
     return stable_uuid(*parts, key, fact, reference_time)