fuli-context 0.8.0 → 0.8.2

package/graph-provider/fuli_graph/agent_quality_policy.py

@@ -0,0 +1,151 @@
+"""Deterministic quality gate and capability routing, without I/O or model calls.
+
+The caller owns trusted evidence collection and persists ordered attempts. A
+selected model is only a recommendation: selection never proves execution or
+successful verification. Artifact revisions must identify the checked artifact.
+"""
+from collections.abc import Mapping
+from copy import deepcopy
+from math import isfinite
+
+
+COMPLEXITY_TIERS = {'simple': 1, 'standard': 2, 'complex': 3}
+STRATEGY_TIERS = {'fast': 1, 'balanced': 2, 'deep': 3, 'adaptive': 1}
+
+
+def _tier(value):
+    return type(value) is int and 1 <= value <= 3
+
+
+def _text(value):
+    return isinstance(value, str) and bool(value.strip())
+
+
+def _unique_attempts(attempts):
+    seen = {}
+    unique = []
+    for attempt in attempts:
+        if not isinstance(attempt, Mapping):
+            raise ValueError('Each verification attempt must be an object')
+        identifier = attempt.get('attempt_id')
+        refs = attempt.get('evidence_refs')
+        if not _text(identifier) or not _text(attempt.get('artifact_revision')):
+            raise ValueError('attempt_id and artifact_revision must be nonempty strings')
+        if attempt.get('outcome') not in ('pass', 'fail'):
+            raise ValueError('Attempt outcome must be pass or fail')
+        if not _tier(attempt.get('capability_tier')):
+            raise ValueError('Attempt capability_tier must be an observed integer from 1 to 3')
+        if not isinstance(refs, (list, tuple)) or not all(_text(ref) for ref in refs):
+            raise ValueError('evidence_refs must contain nonempty string references')
+        if identifier in seen:
+            if seen[identifier] != attempt:
+                raise ValueError(f'Conflicting attempt_id: {identifier}')
+            continue
+        seen[identifier] = attempt
+        unique.append(attempt)
+    return unique
+
+
+def _select_model(models, minimum):
+    eligible = []
+    for model in models:
+        if not isinstance(model, Mapping):
+            continue
+        tier, cost = model.get('capability_tier'), model.get('cost_rank')
+        if model.get('available') is not True or not _tier(tier) or tier < minimum:
+            continue
+        if type(cost) not in (int, float) or cost < 0:
+            continue
+        if type(cost) is float and not isfinite(cost):
+            continue
+        if not _text(model.get('provider')) or not _text(model.get('model')):
+            continue
+        eligible.append(model)
+    if not eligible:
+        return None
+    selected = min(eligible, key=lambda item: (
+        item['cost_rank'], item['provider'], item['model'], -item['capability_tier'],
+    ))
+    # Return only routing metadata, detached from the caller's mutable catalog.
+    return deepcopy({key: selected[key] for key in (
+        'provider', 'model', 'capability_tier', 'cost_rank', 'available',
+    )})
+
+
+def evaluate_quality_policy(*, complexity, current_strategy, artifact_revision,
+                            attempts=(), available_models=(), current_capability_tier=None):
+    """Return a quality gate and the cheapest observed model meeting its floor.
+
+    ``current_strategy`` is a mode string or a mapping containing ``mode``.
+    Unproven attempts are retained in the count but cannot pass the gate, reset
+    failure streaks, or trigger escalation. Distinct evidence-backed failures
+    accumulate per capability tier across artifact revisions. A proved pass
+    resets its tier's streak, without erasing an already-earned capability floor.
+
+    Status is one of ``verification_required``, ``passed``, ``needs_human``, or
+    ``blocked``. Two failures at tier 3 stop automatic selection. A later valid
+    tier-3 pass can resolve that gate, for example after human-directed repair.
+    ``escalation_required`` means the floor rose above the declared current
+    capability; it does not mean an upgraded executor has already run.
+    """
+    mode = current_strategy.get('mode') if isinstance(current_strategy, Mapping) else current_strategy
+    if not isinstance(complexity, str) or complexity not in COMPLEXITY_TIERS:
+        raise ValueError('Unknown task complexity')
+    if not isinstance(mode, str) or mode not in STRATEGY_TIERS:
+        raise ValueError('Unknown model strategy')
+    if not _text(artifact_revision):
+        raise ValueError('artifact_revision must be a nonempty string')
+    if current_capability_tier is not None and not _tier(current_capability_tier):
+        raise ValueError('current_capability_tier must be an integer from 1 to 3')
+    declared_tier = max(STRATEGY_TIERS[mode], current_capability_tier or 1)
+    minimum = max(COMPLEXITY_TIERS[complexity], declared_tier)
+    consecutive = {1: 0, 2: 0, 3: 0}
+    unique = _unique_attempts(attempts)
+    ignored = []
+    last_current = None
+    escalation_attempt_ids = []
+    needs_human = False
+    for attempt in unique:
+        if not attempt['evidence_refs']:
+            ignored.append(attempt['attempt_id'])
+            continue
+        tier = attempt['capability_tier']
+        # Evidence that a higher tier already ran prevents a silent downgrade.
+        minimum = max(minimum, tier)
+        if attempt['outcome'] == 'fail':
+            consecutive[tier] += 1
+            if consecutive[tier] == 2:
+                minimum = max(minimum, min(3, tier + 1))
+                escalation_attempt_ids.append(attempt['attempt_id'])
+                if tier == 3:
+                    needs_human = True
+        else:
+            consecutive[tier] = 0
+            if tier == 3 and attempt['artifact_revision'] == artifact_revision:
+                needs_human = False
+        if attempt['artifact_revision'] == artifact_revision:
+            last_current = attempt
+
+    result = {
+        'status': 'verification_required',
+        'minimum_capability_tier': minimum,
+        'escalation_required': minimum > declared_tier,
+        'selected_model': None,
+        'artifact_revision': artifact_revision,
+        'verified_attempt_id': None,
+        'attempt_count': len(unique),
+        'ignored_attempt_ids': ignored,
+        'consecutive_failures': consecutive,
+        'escalation_attempt_ids': escalation_attempt_ids,
+    }
+    if needs_human:
+        result['status'] = 'needs_human'
+    elif (last_current is not None and last_current['outcome'] == 'pass'
+          and last_current['capability_tier'] >= minimum):
+        result['status'] = 'passed'
+        result['verified_attempt_id'] = last_current['attempt_id']
+    else:
+        result['selected_model'] = _select_model(available_models, minimum)
+        if result['selected_model'] is None:
+            result['status'] = 'blocked'
+    return result

package/graph-provider/fuli_graph/agent_verification_models.py

@@ -0,0 +1,22 @@
+from typing import Annotated, Literal
+from pydantic import Field
+from .models import StrictModel, SourceApplication
+
+
+class AgentQualityQuery(StrictModel):
+    personal_space_id: str = Field(min_length=1, max_length=128)
+    personal_project_id: str = Field(min_length=1, max_length=128)
+    task_id: str = Field(min_length=1, max_length=128)
+    artifact_revision: str = Field(min_length=1, max_length=160)
+
+
+class AgentVerification(AgentQualityQuery):
+    run_id: str = Field(min_length=1, max_length=128)
+    task_context_token: str = Field(min_length=1, max_length=160)
+    source_application: SourceApplication
+    attempt_id: str = Field(min_length=8, max_length=128)
+    outcome: Literal['pass', 'fail']
+    evidence_refs: list[Annotated[str, Field(min_length=1, max_length=512, pattern=r'\S')]] = Field(min_length=1, max_length=12)
+    executor_id: str = Field(min_length=1, max_length=128)
+    provider: str = Field(min_length=1, max_length=128)
+    model: str = Field(min_length=1, max_length=256)

package/graph-provider/fuli_graph/conversation_context.py

@@ -0,0 +1,30 @@
+"""Deterministic recovery: no model calls, conservative UTF-8 byte accounting."""
+import json
+from datetime import datetime, timezone
+
+
+def archived(last_activity, idle_days, *, now=None):
+    current = datetime.fromisoformat(now) if now else datetime.now(timezone.utc)
+    previous = datetime.fromisoformat(last_activity)
+    return (current - previous).total_seconds() >= idle_days * 86400
+
+
+def pack_context(summary, events, budget):
+    result = {'summary': '', 'messages': [], 'truncated': False}
+    def size():
+        return len(json.dumps(result, ensure_ascii=False, separators=(',', ':')).encode())
+    result['summary'] = summary or ''
+    # Reserve half for recent messages; Unicode slicing never splits codepoints.
+    while len(result['summary'].encode()) > budget // 2:
+        result['summary'] = result['summary'][:max(0, len(result['summary']) - 64)]
+        result['truncated'] = True
+    for event in reversed(events):
+        if event['role'] not in ('user', 'assistant') or event.get('kind', 'message') != 'message':
+            continue
+        item = {'role': event['role'], 'content': event['content']}
+        result['messages'].insert(0, item)
+        if size() > budget:
+            result['messages'].pop(0)
+            result['truncated'] = True
+            break
+    return result

package/graph-provider/fuli_graph/knowledge_search.py

@@ -496,21 +496,6 @@ def _item_scope_metadata(
     project_scopes: dict[str, dict],
     include_personal_global: bool,
 ) -> dict | None:
-    if not any(
-        field in record
-        for field in (
-            'profile_aspect',
-            'preference_agent_id',
-            'assignment_project_id',
-            'episode_project_ids',
-            'episode_project_agent_ids',
-            'reference_project_ids',
-            'has_global_episode',
-        )
-    ):
-        # Backward-compatible projection for older Provider clients that returned
-        # only already-filtered item IDs.
-        return _global_scope_metadata()
     profile_aspect = record.get('profile_aspect')
     if profile_aspect:
         preference_scope = record.get('preference_scope') or 'global'
@@ -592,7 +577,14 @@ def _item_scope_metadata(
             ),
         )
         return _project_scope_metadata(project_id, scope)
-    if include_personal_global and record.get('has_global_episode'):
+    # A later project assignment, or an existing project origin, takes
+    # precedence over a historical unscoped episode. It is not global access.
+    if (
+        include_personal_global
+        and record.get('has_global_episode')
+        and not assignment_project_id
+        and not episode_project_ids
+    ):
         return _global_scope_metadata()
     return None
 

package/graph-provider/fuli_graph/project_agent_executor_models.py

@@ -150,6 +150,8 @@ class ProjectAgentExecutorModelRecord(StrictModel):
     provider: str = Field(min_length=1, max_length=128)
     model: str = Field(min_length=1, max_length=256)
     capabilities: list[str] = Field(default_factory=list, max_length=32)
+    capability_tier: int | None = Field(default=None, ge=1, le=3)
+    cost_rank: float | None = Field(default=None, ge=0, allow_inf_nan=False)
     strategy_modes: list[Literal['adaptive', 'fast', 'balanced', 'deep']] = Field(
         default_factory=list,
         max_length=4,
@@ -456,6 +458,7 @@ class ProjectAgentExecutorSelection(StrictModel):
 
 
 class ProjectAgentExecutorActualReport(StrictModel):
+    artifact_revision: str | None = Field(default=None, min_length=1, max_length=160)
     personal_space_id: str = Field(min_length=1, max_length=128)
     personal_project_id: str = Field(min_length=1, max_length=128)
     task_id: str = Field(min_length=1, max_length=128)

package/graph-provider/fuli_graph/project_agent_memory_routes.py

@@ -12,11 +12,13 @@ from .project_agent_memory_models import (
 from .project_agent_context_models import (
     ProjectAgentContextRequest, ProjectAgentContextResolution,
 )
+from .agent_conversation_routes import register_agent_conversation_routes
 from .task_context_routes import register_task_context_routes
 
 
 def register_project_agent_memory_routes(application, store, Actor):
     register_task_context_routes(application, store, Actor)
+    register_agent_conversation_routes(application, store, Actor)
     @application.post(
         '/v1/project-agent-context/resolve', response_model=ProjectAgentContextResolution,
     )

package/graph-provider/fuli_graph/project_agent_models.py

@@ -88,6 +88,14 @@ class ProjectAgentExecutorPolicy(StrictModel):
         return self
 
 
+class ProjectAgentCharacter(StrictModel):
+    """Configured role intent, not a claim about demonstrated performance."""
+
+    judgment: str = Field(default='', max_length=2048)
+    taste: str = Field(default='', max_length=2048)
+    personality: str = Field(default='', max_length=2048)
+
+
 class ProjectAgentProfile(StrictModel):
     name: str = Field(min_length=1, max_length=160)
     display_name: str | None = Field(default=None, min_length=1, max_length=160)
@@ -101,6 +109,8 @@ class ProjectAgentProfile(StrictModel):
         validation_alias=AliasChoices('occupation_emoji', 'occupationEmoji'),
     )
     responsibility: str = Field(min_length=1, max_length=4096)
+    character: ProjectAgentCharacter = Field(default_factory=ProjectAgentCharacter)
+    expectations: str = Field(default='', max_length=4096)
     agent_type: ProjectAgentType = 'durable'
     work_kinds: list[str] = Field(default_factory=list, max_length=32)
     capabilities: list[str] = Field(default_factory=list, max_length=32)

package/graph-provider/fuli_graph/project_agent_routes.py

@@ -253,13 +253,17 @@ def register_project_agent_routes(
             str | None,
             Query(min_length=1, max_length=128),
         ] = None,
+        include_events: bool = True,
     ) -> ProjectAgentTaskRecord:
-        return await store.get_project_agent_task(
+        task = await store.get_project_agent_task(
             actor,
             personal_space_id,
             task_id,
             personal_project_id=personal_project_id,
         )
+        # Derive execution evidence before omitting history from the response.
+        # Never mutate the durable record or erase worker state in compact reads.
+        return task if include_events else task.model_copy(update={'events': []})
 
     @application.post(
         '/v1/project-agent-tasks/{task_id}/events',

package/graph-provider/fuli_graph/project_agent_task_models.py

@@ -141,6 +141,9 @@ class ProjectAgentParallelPlan(StrictModel):
 
 
 class ProjectAgentTaskSubmit(StrictModel):
+    # All newly submitted tasks use the quality gate, including legacy public
+    # entry points. Existing graph records without this field remain readable.
+    verification_required: Literal[True] = True
     personal_space_id: str = Field(min_length=1, max_length=128)
     personal_project_id: str = Field(min_length=1, max_length=128)
     idempotency_key: str = Field(min_length=8, max_length=256)
@@ -486,6 +489,7 @@ class ProjectAgentTaskRecord(StrictModel):
 
 
 class ProjectAgentTaskActivityCreate(StrictModel):
+    artifact_revision: str | None = Field(default=None, min_length=1, max_length=160)
     personal_space_id: str = Field(min_length=1, max_length=128)
     personal_project_id: str = Field(min_length=1, max_length=128)
     task_id: str = Field(min_length=1, max_length=128)

package/graph-provider/fuli_graph/runtime.py

@@ -269,6 +269,20 @@ class GraphitiRuntime:
         # safe for upgraded stores as well as fresh databases.
         await self._migrate_project_agent_executor_learning_buckets()
         for query in (
+            'CREATE CONSTRAINT fuli_agent_verification_id IF NOT EXISTS '
+            'FOR (n:FuliAgentVerification) REQUIRE n.id IS UNIQUE',
+            'CREATE CONSTRAINT fuli_agent_loan_id IF NOT EXISTS '
+            'FOR (n:FuliAgentLoan) REQUIRE n.id IS UNIQUE',
+            'CREATE CONSTRAINT fuli_transcript_cursor_id IF NOT EXISTS '
+            'FOR (n:FuliTranscriptCursor) REQUIRE n.id IS UNIQUE',
+            'CREATE CONSTRAINT fuli_conversation_id IF NOT EXISTS '
+            'FOR (n:FuliConversation) REQUIRE n.id IS UNIQUE',
+            'CREATE CONSTRAINT fuli_conversation_event IF NOT EXISTS '
+            'FOR (n:FuliConversationEvent) REQUIRE n.id IS UNIQUE',
+            'CREATE CONSTRAINT fuli_conversation_binding IF NOT EXISTS '
+            'FOR (n:FuliConversationBinding) REQUIRE n.id IS UNIQUE',
+            'CREATE CONSTRAINT fuli_conversation_policy IF NOT EXISTS '
+            'FOR (n:FuliConversationPolicy) REQUIRE n.id IS UNIQUE',
             'CREATE CONSTRAINT fuli_project_agent_id IF NOT EXISTS '
             'FOR (n:FuliProjectAgent) REQUIRE n.id IS UNIQUE',
             'CREATE CONSTRAINT fuli_agent_attention_id IF NOT EXISTS '

package/graph-provider/fuli_graph/store.py

@@ -2,6 +2,9 @@ from .config import Settings
 from .provider_values import graphiti_group_id, native_datetime
 from .runtime import GraphitiRuntime
 from .store_identity import StoreIdentity
+from .store_agent_conversations import StoreAgentConversations
+from .store_agent_loans import StoreAgentLoans
+from .store_agent_verification import StoreAgentVerification
 from .store_knowledge import StoreKnowledge
 from .store_project_agent_executors import StoreProjectAgentExecutors
 from .store_project_agent_memory import StoreProjectAgentMemory
@@ -17,6 +20,9 @@ from .store_task_contexts import StoreTaskContexts
 
 class GraphStore(
     StoreIdentity,
+    StoreAgentConversations,
+    StoreAgentLoans,
+    StoreAgentVerification,
     StoreProjects,
     StoreProjectAgents,
     StoreProjectAgentAttention,

package/graph-provider/fuli_graph/store_agent_conversations.py

@@ -0,0 +1,206 @@
+"""Transactional conversation journal in the private graph; no LLM/embeddings."""
+import base64
+import gzip
+import hashlib
+import json
+from fastapi import HTTPException
+from .agent_conversation_models import ConversationPolicy
+from .conversation_context import archived, pack_context
+from .project_agent_access import authorize_project_agent
+from .provider_values import now_utc, stable_uuid
+from .store_transactions import query_store_transaction
+
+
+def encode_event(event):
+    raw = json.dumps(event.model_dump(), ensure_ascii=False, sort_keys=True).encode()
+    return hashlib.sha256(raw).hexdigest(), base64.b64encode(gzip.compress(raw, mtime=0)).decode()
+
+
+def decode_event(row):
+    return {**json.loads(gzip.decompress(base64.b64decode(row['payload']))), 'sequence': row['sequence']}
+
+
+class StoreAgentConversations:
+    async def _conversation_scope(self, actor, request, *, write=False):
+        self._require_personal()
+        space = await self.authorize(actor, request.personal_space_id, 'maintainer' if write else 'reader')
+        agent = await authorize_project_agent(self, actor, space, request.personal_project_id,
+            request.agent_id, require_active=write, require_memory=True)
+        if request.source_application is not None and request.source_application not in json.loads(agent['profile_json']).get('allowed_clients', []):
+            raise HTTPException(403, 'Agent is not allowed in this client')
+        return stable_uuid('conversation-scope', space['id'], request.personal_project_id, agent['agent_id'])
+
+    async def _conversation_task(self, actor, request):
+        await self.runtime.driver.execute_query(
+            'MATCH (s:FuliTaskContextSession {id: $id}) SET s.conversation_serial=coalesce(s.conversation_serial,0)+1',
+            id=self._task_session_id(request.personal_space_id, request.source_application, request.session_id))
+        task = await self.get_task_context(actor, request.personal_space_id,
+            request.task_context_token, request.source_application)
+        if (task['session_id'], task['personal_project_id'], task['project_agent_id']) != (
+            request.session_id, request.personal_project_id, request.agent_id):
+            raise HTTPException(409, 'Conversation does not match the current task Agent and session')
+
+    async def _conversation_policy(self, scope):
+        rows, _, _ = await self.runtime.driver.execute_query(
+            'MATCH (p:FuliConversationPolicy {id: $scope}) RETURN p.policy AS policy', scope=scope)
+        return ConversationPolicy.model_validate_json(rows[0]['policy']) if rows else ConversationPolicy()
+
+    async def write_conversation_policy(self, actor, request):
+        scope = await self._conversation_scope(actor, request, write=True)
+        await self.runtime.driver.execute_query(
+            'MERGE (p:FuliConversationPolicy {id: $scope}) SET p.policy=$policy',
+            scope=scope, policy=request.policy.model_dump_json())
+        return request.policy.model_dump()
+
+    async def query_conversations(self, actor, request):
+        scope = await self._conversation_scope(actor, request)
+        policy = await self._conversation_policy(scope)
+        if request.mode == 'policy':
+            return policy.model_dump()
+        if request.mode == 'session':
+            rows, _, _ = await self.runtime.driver.execute_query(
+                'OPTIONAL MATCH (b:FuliConversationBinding {id: $id}) '
+                'OPTIONAL MATCH (s:FuliTranscriptCursor {id: $stream}) '
+                'RETURN b.conversation_id AS conversation_id, coalesce(s.cursor,0) AS cursor, '
+                'coalesce(s.initialized, s.cursor > 0, false) AS initialized',
+                stream=stable_uuid(request.personal_space_id, request.source_application, request.session_id or ''),
+                id=stable_uuid(scope, request.source_application, request.session_id or ''))
+            return dict(rows[0]) if rows else {'conversation_id': None, 'cursor': 0, 'initialized': False}
+        if request.mode == 'list':
+            rows, _, _ = await self.runtime.driver.execute_query(
+                'MATCH (c:FuliConversation {scope: $scope}) RETURN c ORDER BY c.last_activity DESC, c.id LIMIT $limit',
+                scope=scope, limit=request.limit)
+            return {'conversations': [self._conversation_view(dict(r['c']), policy) for r in rows]}
+        rows, _, _ = await self.runtime.driver.execute_query(
+            'MATCH (c:FuliConversation {scope: $scope, id: $id}) RETURN c', scope=scope, id=request.conversation_id)
+        if not rows:
+            raise HTTPException(404, 'Conversation not found in this Agent and project')
+        record = dict(rows[0]['c'])
+        view = self._conversation_view(record, policy)
+        if request.mode == 'context' and view['archived']:
+            return {**view, 'context': pack_context(record.get('summary', ''), [], policy.context_budget)}
+        order = 'DESC' if request.mode == 'context' else 'ASC'
+        events, _, _ = await self.runtime.driver.execute_query(
+            'MATCH (c:FuliConversation {id: $id})-[:HAS_EVENT]->(e:FuliConversationEvent) '
+            'WHERE e.sequence > $after RETURN e.payload AS payload, e.sequence AS sequence '
+            f'ORDER BY e.sequence {order} LIMIT $limit', id=record['id'], after=request.after,
+            limit=20 if request.mode == 'context' else request.limit)
+        decoded = []
+        total = 0
+        for event in events:
+            value = decode_event(event)
+            total += len(json.dumps(value, ensure_ascii=False).encode())
+            if total > 512 * 1024 and decoded:
+                break
+            decoded.append(value)
+        if request.mode == 'context':
+            return {**view, 'context': pack_context(record.get('summary', ''), list(reversed(decoded)), policy.context_budget)}
+        cursor = decoded[-1]['sequence'] if decoded else request.after
+        return {**view, 'events': decoded, 'next_cursor': cursor, 'has_more': cursor < record['revision']}
+
+    def _conversation_view(self, record, policy):
+        return {key: record.get(key) for key in ('id', 'summary', 'status', 'revision', 'last_activity')} | {
+            'archived': archived(record['last_activity'], policy.idle_days),
+            'policy': policy.model_dump(), 'raw_retained': True}
+
+    async def append_conversation(self, actor, request):
+        if request.initialize_cursor:
+            raise HTTPException(422, 'Initialize transcripts only at a verified task boundary')
+        async with query_store_transaction(self) as store:
+            scope = await store._conversation_scope(actor, request, write=True)
+            await store._conversation_task(actor, request)
+            policy = await store._conversation_policy(scope)
+            if not policy.enabled:
+                return {'status': 'capture_disabled'}
+            stream = stable_uuid(request.personal_space_id, request.source_application, request.session_id)
+            streams, _, _ = await store.runtime.driver.execute_query(
+                'MERGE (s:FuliTranscriptCursor {id: $id}) ON CREATE SET s.cursor=0, s.owner_scope=$scope '
+                'SET s.serial=coalesce(s.serial,0)+1 RETURN s.cursor AS cursor, s.owner_scope AS owner_scope, '
+                'coalesce(s.initialized, s.cursor > 0, false) AS initialized', id=stream, scope=scope)
+            binding = stable_uuid(scope, request.source_application, request.session_id)
+            rows, _, _ = await store.runtime.driver.execute_query(
+                'MERGE (b:FuliConversationBinding {id: $id}) '
+                'ON CREATE SET b.conversation_id=$conversation_id, b.cursor=0 '
+                'SET b.serial=coalesce(b.serial,0)+1 RETURN b.conversation_id AS id, b.cursor AS cursor',
+                id=binding, conversation_id=stable_uuid('conversation', binding))
+            conversation_id = rows[0]['id']
+            cursor = streams[0]['cursor']
+            if request.expected_cursor is not None and not streams[0]['initialized']:
+                raise HTTPException(409, 'Transcript must start at a verified task boundary')
+            if request.expected_cursor is not None and streams[0]['owner_scope'] not in (None, scope):
+                raise HTTPException(409, 'Transcript scope changed without a verified prompt boundary; do not import the old tail')
+            if request.expected_cursor is not None and cursor != request.expected_cursor:
+                raise HTTPException(409, 'Transcript cursor changed; reload before retrying')
+            now = now_utc().isoformat()
+            await store.runtime.driver.execute_query(
+                'MERGE (c:FuliConversation {id: $id}) ON CREATE SET c.scope=$scope, c.revision=0, '
+                "c.last_activity=$now, c.summary='', c.status='reported' "
+                'SET c.serial=coalesce(c.serial,0)+1', id=conversation_id, scope=scope, now=now)
+            new_summary = False
+            for event in request.events:
+                digest, payload = encode_event(event)
+                event_id = stable_uuid(conversation_id, request.source_application, request.session_id, event.event_id)
+                existing, _, _ = await store.runtime.driver.execute_query(
+                    'MATCH (e:FuliConversationEvent {id: $id}) RETURN e.digest AS digest', id=event_id)
+                if existing:
+                    if existing[0]['digest'] != digest:
+                        raise HTTPException(409, 'Conversation event ID has different content')
+                    continue
+                if event.kind == 'checkpoint':
+                    new_summary = True
+                await store.runtime.driver.execute_query(
+                    'MATCH (c:FuliConversation {id: $id}) SET c.revision=c.revision+1, c.last_activity=$now '
+                    'CREATE (e:FuliConversationEvent {id: $event_id, digest: $digest, payload: $payload, '
+                    'sequence: c.revision, source_application: $source, task_context_token: $task}) '
+                    'CREATE (c)-[:HAS_EVENT]->(e)', id=conversation_id, event_id=event_id,
+                    digest=digest, payload=payload, now=now, source=request.source_application,
+                    task=request.task_context_token)
+            if request.summary is not None and new_summary:
+                await store.runtime.driver.execute_query(
+                    'MATCH (c:FuliConversation {id: $id}) SET c.summary=$summary, c.status=$status',
+                    id=conversation_id, summary=request.summary, status=request.status or 'reported')
+            if request.cursor is not None:
+                await store.runtime.driver.execute_query(
+                    'MATCH (s:FuliTranscriptCursor {id: $id}) SET s.cursor=$cursor, s.owner_scope=$scope', id=stream, cursor=request.cursor, scope=scope)
+            rows, _, _ = await store.runtime.driver.execute_query(
+                'MATCH (c:FuliConversation {id: $id}) RETURN c.revision AS revision', id=conversation_id)
+            return {'status': 'saved', 'conversation_id': conversation_id, 'revision': rows[0]['revision']}
+
+    async def resume_conversation(self, actor, request):
+        async with query_store_transaction(self) as store:
+            scope = await store._conversation_scope(actor, request, write=True)
+            await store._conversation_task(actor, request)
+            rows, _, _ = await store.runtime.driver.execute_query(
+                'MATCH (c:FuliConversation {id: $id, scope: $scope}) RETURN c.id AS id',
+                id=request.conversation_id, scope=scope)
+            if not rows:
+                raise HTTPException(404, 'Conversation not found in this Agent and project')
+            await store.runtime.driver.execute_query(
+                'MERGE (b:FuliConversationBinding {id: $id}) ON CREATE SET b.cursor=0 '
+                'SET b.conversation_id=$conversation_id', id=stable_uuid(scope, request.source_application, request.session_id),
+                conversation_id=request.conversation_id)
+            return {'status': 'resumed', 'conversation_id': request.conversation_id}
+
+    async def claim_conversation_boundary(self, actor, request):
+        if request.events or request.cursor is None or (not request.initialize_cursor and request.cursor != request.expected_cursor):
+            raise HTTPException(422, 'A scope boundary cannot import events or skip bytes')
+        async with query_store_transaction(self) as store:
+            scope = await store._conversation_scope(actor, request, write=True)
+            await store._conversation_task(actor, request)
+            stream = stable_uuid(request.personal_space_id, request.source_application, request.session_id)
+            if request.initialize_cursor:
+                # First hook sync has no journal entry yet. Create only after authorization;
+                # a failed CAS rolls this back in the same transaction.
+                await store.runtime.driver.execute_query(
+                    'MERGE (s:FuliTranscriptCursor {id:$id}) '
+                    'ON CREATE SET s.cursor=0, s.initialized=false', id=stream)
+            rows, _, _ = await store.runtime.driver.execute_query(
+                'MATCH (s:FuliTranscriptCursor {id:$id}) SET s.serial=coalesce(s.serial,0)+1 '
+                'WITH s WHERE s.cursor=$expected AND '
+                '($initialize=false OR (s.cursor=0 AND coalesce(s.initialized,false)=false)) '
+                'SET s.owner_scope=$scope, s.cursor=$cursor, s.initialized=true RETURN s.cursor AS cursor',
+                id=stream,
+                cursor=request.cursor, expected=request.expected_cursor, initialize=request.initialize_cursor, scope=scope)
+            if not rows:
+                raise HTTPException(409, 'Transcript cursor changed before scope boundary')
+            return {'status': 'bound', 'cursor': request.cursor}