"""Rule-based extractors for typed Eventloom events.

Each function is registered into the core registry via @register; importing
this module (done by zaxy.extract.__init__) populates the registry.
"""

from __future__ import annotations

import copy
from collections.abc import Mapping
from typing import Any

from zaxy.causal import CausalEdge, causal_relation_to_graph_relation
from zaxy.consolidation import (
    CONSOLIDATION_INITIAL_REVIEW_STATUS,
    CONSOLIDATION_REVIEW_STATUSES,
)
from zaxy.event import Event
from zaxy.extract.core import (
    _CONSOLIDATION_AUTHORITY_STATUS,
    ExtractedEdge,
    ExtractedEntity,
    ExtractionResult,
    _bounded_float,
    _compact_properties,
    _coordination_finding_id,
    _coordination_mission_id,
    _coordination_proof_row_id,
    _coordination_worker_id,
    _dict_list,
    _document_session_context,
    _entity_reference,
    _entity_reference_from_mapping,
    _event_ref,
    _extract_skill_version_event,
    _feedback_purpose_properties,
    _join_summary,
    _longmemeval_document_properties,
    _merge_properties,
    _neutral_audit_projection,
    _non_negative_int,
    _optional_text,
    _positive_int,
    _preference_summary,
    _refresh_transform_properties,
    _required_causal_graph_relation_type,
    _required_confidence,
    _required_consolidation_authority_status,
    _required_consolidation_candidate_id,
    _required_consolidation_candidate_type,
    _required_consolidation_confidence,
    _required_consolidation_text,
    _required_numeric_confidence,
    _required_reasoning_phase,
    _required_reasoning_text,
    _required_strict_text,
    _required_text,
    _retention_properties,
    _retrieval_salience_properties,
    _skill_entities,
    _skill_id,
    _skill_version,
    _skill_version_edge,
    _snapshot_consolidation_source_events,
    _source_sha256_property,
    _string_list,
    _synthesis_candidate_id,
    _synthesis_ledger_row_id,
    _task_identity_properties,
    _with_explicit_task_observation,
    register,
)
from zaxy.neutral import (
    neutral_document_record,
    neutral_transcript_record,
)


@register("goal.created")
def _extract_goal_created(event: Event) -> ExtractionResult:
    """Extract a goal entity from a goal.created event."""
    title = event.payload.get("title", "untitled")
    goal = ExtractedEntity(
        name=title,
        entity_type="goal",
        observed_at=event.timestamp,
        summary=_optional_text(event.payload.get("description")),
        properties=_retention_properties(event.payload),
    )
    actor = ExtractedEntity(
        name=event.actor,
        entity_type="actor",
        observed_at=event.timestamp,
    )
    edge = ExtractedEdge(
        source=event.actor,
        target=title,
        relation_type="created_goal",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[goal, actor],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("task.proposed")
def _extract_task_proposed(event: Event) -> ExtractionResult:
    """Extract task and actor from task.proposed."""
    tid = event.payload.get("taskId", f"task_{event.seq}")
    goal_title = _optional_text(event.payload.get("goalTitle"))
    task = ExtractedEntity(
        name=tid,
        entity_type="task",
        observed_at=event.timestamp,
        summary=_optional_text(event.payload.get("summary") or event.payload.get("title")),
        properties=_merge_properties(
            _task_identity_properties(event.payload),
            _retention_properties(event.payload),
        ),
    )
    actor = ExtractedEntity(
        name=event.actor,
        entity_type="actor",
        observed_at=event.timestamp,
    )
    edge = ExtractedEdge(
        source=event.actor,
        target=tid,
        relation_type="proposed_task",
        valid_from=event.timestamp,
    )
    entities = [task, actor]
    edges = [edge]
    if goal_title:
        entities.append(
            ExtractedEntity(
                name=goal_title,
                entity_type="goal",
                observed_at=event.timestamp,
            )
        )
        edges.append(
            ExtractedEdge(
                source=goal_title,
                target=tid,
                relation_type="has_task",
                valid_from=event.timestamp,
            )
        )
    return ExtractionResult(
        entities=entities,
        edges=edges,
        source_event_seq=event.seq,
    )


@register("task.claimed")
def _extract_task_claimed(event: Event) -> ExtractionResult:
    """Link actor to claimed task."""
    tid = event.payload.get("taskId", "unknown")
    actor = ExtractedEntity(
        name=event.actor,
        entity_type="actor",
        observed_at=event.timestamp,
    )
    edge = ExtractedEdge(
        source=event.actor,
        target=tid,
        relation_type="claimed_task",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[actor],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("task.completed")
def _extract_task_completed(event: Event) -> ExtractionResult:
    """Mark task as completed."""
    tid = _optional_text(event.payload.get("taskId") or event.payload.get("task")) or "unknown"
    summary = _optional_text(event.payload.get("summary"))
    task = ExtractedEntity(
        name=tid,
        entity_type="task",
        observed_at=event.timestamp,
        summary=summary,
        properties=_merge_properties(
            _task_identity_properties(event.payload),
            _retention_properties(event.payload),
        ),
    )
    actor = ExtractedEntity(
        name=event.actor,
        entity_type="actor",
        observed_at=event.timestamp,
    )
    edge = ExtractedEdge(
        source=event.actor,
        target=tid,
        relation_type="completed_task",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[task, actor],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("decision.made")
def _extract_decision_made(event: Event) -> ExtractionResult:
    """Extract an agent decision with rationale into searchable graph context."""
    decision = _optional_text(event.payload.get("decision")) or f"decision:{event.seq}"
    entity = ExtractedEntity(
        name=decision,
        entity_type="decision",
        observed_at=event.timestamp,
        summary=_join_summary(
            event.payload.get("summary"),
            event.payload.get("rationale"),
            event.payload.get("alternatives_considered"),
        ),
        properties=_retention_properties(event.payload),
    )
    actor = ExtractedEntity(
        name=event.actor,
        entity_type="actor",
        observed_at=event.timestamp,
    )
    edge = ExtractedEdge(
        source=event.actor,
        target=decision,
        relation_type="made_decision",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[entity, actor],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("context.policy")
def _extract_context_policy(event: Event) -> ExtractionResult:
    """Extract durable project/session guidance into searchable graph context."""
    source = _optional_text(event.payload.get("source")) or "context"
    project = _optional_text(event.payload.get("project"))
    name = f"{project}:{source}" if project else source
    entity = ExtractedEntity(
        name=name,
        entity_type="context_policy",
        observed_at=event.timestamp,
        summary=_join_summary(
            event.payload.get("status"),
            event.payload.get("instructions"),
        ),
        properties=_merge_properties({
            "source": source,
            "project": project,
        }, _retention_properties(event.payload)),
    )
    actor = ExtractedEntity(
        name=event.actor,
        entity_type="actor",
        observed_at=event.timestamp,
    )
    edge = ExtractedEdge(
        source=event.actor,
        target=name,
        relation_type="set_context_policy",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[entity, actor],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("memory.reinforced")
def _extract_memory_reinforced(event: Event) -> ExtractionResult:
    """Extract reinforcement metadata for an existing memory entity."""
    entity_name = _optional_text(event.payload.get("entity_name")) or f"memory:{event.seq}"
    entity_type = _optional_text(event.payload.get("entity_type")) or "memory"
    properties = _merge_properties(
        _retention_properties(event.payload),
        _feedback_purpose_properties(event.payload),
        {
            "last_reinforced_at": event.timestamp,
            "reinforcement_count": _positive_int(event.payload.get("reinforcement_count"), default=1),
        },
    )
    entity = ExtractedEntity(
        name=entity_name,
        entity_type=entity_type,
        observed_at=event.timestamp,
        summary=_optional_text(event.payload.get("summary")),
        properties=properties,
    )
    actor = ExtractedEntity(
        name=event.actor,
        entity_type="actor",
        observed_at=event.timestamp,
    )
    edge = ExtractedEdge(
        source=event.actor,
        target=entity_name,
        relation_type="reinforced_memory",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[entity, actor],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("memory.evidence.reinforced")
@register("memory.evidence.excluded")
def _extract_memory_evidence_feedback(event: Event) -> ExtractionResult:
    """Extract row-level synthesis evidence feedback for cited facts."""
    fact_id = _optional_text(event.payload.get("fact_id"))
    source_group = _optional_text(event.payload.get("source_group"))
    citation = _optional_text(event.payload.get("citation"))
    entity_name = fact_id or source_group or citation or f"synthesis_evidence:{event.seq}"
    outcome = _optional_text(event.payload.get("outcome"))
    timestamp_key = "last_reinforced_at" if event.type == "memory.evidence.reinforced" else "last_excluded_at"
    feedback_properties = {
        key: value
        for key, value in {
            "outcome": outcome,
            "source_group": source_group,
            "citation": citation,
            timestamp_key: event.timestamp,
        }.items()
        if value is not None
    }
    properties = _merge_properties(
        _retention_properties(event.payload),
        feedback_properties,
    )
    entity = ExtractedEntity(
        name=entity_name,
        entity_type="synthesis_evidence",
        observed_at=event.timestamp,
        summary=_optional_text(event.payload.get("reason")) or _optional_text(event.payload.get("query")),
        properties=properties,
    )
    actor = ExtractedEntity(
        name=event.actor,
        entity_type="actor",
        observed_at=event.timestamp,
    )
    relation_type = (
        "reinforced_synthesis_evidence"
        if event.type == "memory.evidence.reinforced"
        else "excluded_synthesis_evidence"
    )
    edges = [
        ExtractedEdge(
            source=event.actor,
            target=entity_name,
            relation_type=relation_type,
            valid_from=event.timestamp,
        )
    ]
    entities = [entity, actor]
    if source_group:
        entities.append(
            ExtractedEntity(
                name=source_group,
                entity_type="source_group",
                observed_at=event.timestamp,
            )
        )
        edges.append(
            ExtractedEdge(
                source=entity_name,
                target=source_group,
                relation_type="cites_source_group",
                valid_from=event.timestamp,
            )
        )
    return ExtractionResult(
        entities=entities,
        edges=edges,
        source_event_seq=event.seq,
    )


@register("memory.synthesis.artifact.created")
def _extract_memory_synthesis_artifact_created(event: Event) -> ExtractionResult:
    """Extract a deterministic Memory Checkout synthesis artifact."""
    artifact_id = _optional_text(event.payload.get("artifact_id")) or f"synthesis_artifact:{event.seq}"
    session_id = _optional_text(event.payload.get("session_id") or event.thread)
    candidates = _dict_list(event.payload.get("answer_candidates"))
    ledger_rows = _dict_list(event.payload.get("ledger_rows"))
    support_packet = event.payload.get("support_packet")
    source_groups = _string_list(support_packet.get("source_groups")) if isinstance(support_packet, dict) else []
    artifact = ExtractedEntity(
        name=artifact_id,
        entity_type="synthesis_artifact",
        observed_at=event.timestamp,
        summary=_optional_text(event.payload.get("query")),
        properties=_compact_properties(
            {
                "schema_version": _optional_text(event.payload.get("schema_version")),
                "session_id": session_id,
                "answer_candidate_count": len(candidates),
                "ledger_row_count": len(ledger_rows),
                "support_source_group_count": len(source_groups),
            }
        ),
    )
    actor = ExtractedEntity(name=event.actor, entity_type="actor", observed_at=event.timestamp)
    entities = [artifact, actor]
    edges = [
        ExtractedEdge(
            source=event.actor,
            target=artifact_id,
            relation_type="created_synthesis_artifact",
            valid_from=event.timestamp,
        )
    ]
    for candidate in candidates:
        candidate_id = _synthesis_candidate_id(artifact_id, candidate)
        entities.append(
            ExtractedEntity(
                name=candidate_id,
                entity_type="synthesis_answer_candidate",
                observed_at=event.timestamp,
                summary=_optional_text(candidate.get("answer")),
                properties=_compact_properties(
                    {
                        "artifact_id": artifact_id,
                        "rank": candidate.get("rank"),
                        "type": _optional_text(candidate.get("type")),
                        "answer_key": _optional_text(candidate.get("answer_key")),
                        "confidence": _bounded_float(candidate.get("confidence")),
                    }
                ),
            )
        )
        edges.append(
            ExtractedEdge(
                source=artifact_id,
                target=candidate_id,
                relation_type="artifact_has_answer_candidate",
                valid_from=event.timestamp,
            )
        )
        for source_group in _string_list(candidate.get("support_source_ids")):
            entities.append(ExtractedEntity(name=source_group, entity_type="source_group", observed_at=event.timestamp))
            edges.append(
                ExtractedEdge(
                    source=candidate_id,
                    target=source_group,
                    relation_type="candidate_supported_by_source_group",
                    valid_from=event.timestamp,
                )
            )
    for row in ledger_rows:
        row_id = _synthesis_ledger_row_id(artifact_id, row)
        if row_id is None:
            continue
        entities.append(
            ExtractedEntity(
                name=row_id,
                entity_type="synthesis_ledger_row",
                observed_at=event.timestamp,
                summary=_join_summary(row.get("kind"), row.get("value"), row.get("label")),
                properties=_compact_properties(
                    {
                        "artifact_id": artifact_id,
                        "fact_id": _optional_text(row.get("fact_id")),
                        "source_group": _optional_text(row.get("source_group")),
                        "citation": _optional_text(row.get("citation")),
                        "include_reason": _optional_text(row.get("include_reason")),
                        "exclude_reason": _optional_text(row.get("exclude_reason")),
                        "confidence": _bounded_float(row.get("confidence")),
                    }
                ),
            )
        )
        edges.append(
            ExtractedEdge(
                source=artifact_id,
                target=row_id,
                relation_type="artifact_has_ledger_row",
                valid_from=event.timestamp,
            )
        )
    return ExtractionResult(entities=entities, edges=edges, source_event_seq=event.seq)


@register("memory.synthesis.used")
@register("memory.synthesis.rejected")
@register("memory.synthesis.corrected")
def _extract_memory_synthesis_outcome(event: Event) -> ExtractionResult:
    """Extract answer-candidate outcome feedback."""
    candidate = event.payload.get("answer_candidate")
    candidate = candidate if isinstance(candidate, dict) else {}
    candidate_id = _synthesis_candidate_id("candidate_feedback", candidate)
    outcome = _optional_text(event.payload.get("outcome")) or event.type.removeprefix("memory.synthesis.")
    entity = ExtractedEntity(
        name=candidate_id,
        entity_type="synthesis_answer_candidate",
        observed_at=event.timestamp,
        summary=_optional_text(candidate.get("answer")) or _optional_text(event.payload.get("reason")),
        properties=_compact_properties(
            {
                "outcome": outcome,
                "last_outcome_at": event.timestamp,
                "rank": candidate.get("rank"),
                "type": _optional_text(candidate.get("type")),
                "answer_key": _optional_text(candidate.get("answer_key")),
                "confidence": _bounded_float(candidate.get("confidence")),
            }
        ),
    )
    actor = ExtractedEntity(name=event.actor, entity_type="actor", observed_at=event.timestamp)
    edges = [
        ExtractedEdge(
            source=event.actor,
            target=candidate_id,
            relation_type=f"recorded_synthesis_{outcome}",
            valid_from=event.timestamp,
        )
    ]
    entities = [entity, actor]
    for source_group in _string_list(event.payload.get("support_source_ids")):
        entities.append(ExtractedEntity(name=source_group, entity_type="source_group", observed_at=event.timestamp))
        edges.append(
            ExtractedEdge(
                source=candidate_id,
                target=source_group,
                relation_type="candidate_supported_by_source_group",
                valid_from=event.timestamp,
            )
        )
    return ExtractionResult(entities=entities, edges=edges, source_event_seq=event.seq)


@register("skill.proposed")
def _extract_skill_proposed(event: Event) -> ExtractionResult:
    """Extract a proposed reusable procedural skill and its version."""
    return _extract_skill_version_event(event, status="proposed", relation_type="proposed_skill")


@register("skill.validated")
def _extract_skill_validated(event: Event) -> ExtractionResult:
    """Extract a validated reusable procedural skill version."""
    return _extract_skill_version_event(event, status="validated", relation_type="validated_skill")


@register("skill.revised")
def _extract_skill_revised(event: Event) -> ExtractionResult:
    """Extract a revised skill version while preserving earlier versions."""
    return _extract_skill_version_event(event, status="revised", relation_type="revised_skill")


@register("skill.deprecated")
def _extract_skill_deprecated(event: Event) -> ExtractionResult:
    """Extract skill deprecation metadata without deleting old versions."""
    return _extract_skill_version_event(event, status="deprecated", relation_type="deprecated_skill")


@register("skill.contradicted")
def _extract_skill_contradicted(event: Event) -> ExtractionResult:
    """Extract a contradicted skill version for audit and rollback."""
    return _extract_skill_version_event(event, status="contradicted", relation_type="contradicted_skill")


@register("skill.applied")
def _extract_skill_applied(event: Event) -> ExtractionResult:
    """Extract a task application of a skill version."""
    skill_id = _skill_id(event)
    version = _skill_version(event.payload)
    skill, version_entity = _skill_entities(event, skill_id=skill_id, version=version, status="applied")
    application_name = f"skill:{skill_id}:v{version}:application:{event.seq}"
    application = ExtractedEntity(
        name=application_name,
        entity_type="skill_application",
        observed_at=event.timestamp,
        summary=_join_summary(event.payload.get("task"), event.payload.get("summary")),
        properties=_compact_properties(
            {
                "skill_id": skill_id,
                "version": version,
                "task": _optional_text(event.payload.get("task")),
                "task_id": _optional_text(event.payload.get("task_id") or event.payload.get("taskId")),
                "context": _optional_text(event.payload.get("context")),
            }
        ),
    )
    return ExtractionResult(
        entities=[skill, version_entity, application],
        edges=[
            _skill_version_edge(skill, version_entity, event),
            ExtractedEdge(
                source=version_entity.name,
                target=application.name,
                relation_type="applied_to_task",
                valid_from=event.timestamp,
            ),
        ],
        source_event_seq=event.seq,
    )


@register("skill.outcome_recorded")
def _extract_skill_outcome_recorded(event: Event) -> ExtractionResult:
    """Extract outcome metrics for an applied skill version."""
    skill_id = _skill_id(event)
    version = _skill_version(event.payload)
    skill, version_entity = _skill_entities(event, skill_id=skill_id, version=version, status="outcome_recorded")
    outcome_name = f"skill:{skill_id}:v{version}:outcome:{event.seq}"
    outcome = ExtractedEntity(
        name=outcome_name,
        entity_type="skill_outcome",
        observed_at=event.timestamp,
        summary=_join_summary(event.payload.get("task"), event.payload.get("feedback")),
        properties=_compact_properties(
            {
                "skill_id": skill_id,
                "version": version,
                "task": _optional_text(event.payload.get("task")),
                "success_score": _bounded_float(event.payload.get("success_score")),
                "feedback": _optional_text(event.payload.get("feedback")),
                "evidence": _string_list(event.payload.get("evidence")),
            }
        ),
    )
    return ExtractionResult(
        entities=[skill, version_entity, outcome],
        edges=[
            _skill_version_edge(skill, version_entity, event),
            ExtractedEdge(
                source=version_entity.name,
                target=outcome.name,
                relation_type="recorded_outcome",
                valid_from=event.timestamp,
            ),
        ],
        source_event_seq=event.seq,
    )


@register("hook.checkpoint")
def _extract_hook_checkpoint(event: Event) -> ExtractionResult:
    """Extract a searchable observer checkpoint."""
    session_id = _optional_text(event.thread) or _optional_text(event.payload.get("session_id")) or "default"
    source = _optional_text(event.payload.get("source")) or "hook"
    reason = _optional_text(event.payload.get("reason")) or "checkpoint"
    turn_count = _positive_int(event.payload.get("turn_count"), default=0)
    workspace = _optional_text(event.payload.get("workspace"))
    checkpoint = ExtractedEntity(
        name=f"{session_id}:checkpoint:{event.seq}",
        entity_type="hook_checkpoint",
        observed_at=event.timestamp,
        summary=_optional_text(event.payload.get("summary")),
        properties={
            "session_id": session_id,
            "source": source,
            "reason": reason,
            "turn_count": turn_count,
            "workspace": workspace,
        },
    )
    session = ExtractedEntity(
        name=session_id,
        entity_type="session",
        observed_at=event.timestamp,
    )
    edge = ExtractedEdge(
        source=session.name,
        target=checkpoint.name,
        relation_type="recorded_checkpoint",
        valid_from=event.timestamp,
    )
    entities, edges = _with_explicit_task_observation(
        event,
        [session, checkpoint],
        [edge],
        target=checkpoint.name,
        relation_type="has_checkpoint",
    )
    return ExtractionResult(
        entities=entities,
        edges=edges,
        source_event_seq=event.seq,
    )


@register("issue.diagnosed")
def _extract_issue_diagnosed(event: Event) -> ExtractionResult:
    """Extract a diagnosed issue with root cause and supporting evidence."""
    issue = _optional_text(event.payload.get("issue")) or f"issue:{event.seq}"
    entity = ExtractedEntity(
        name=issue,
        entity_type="issue",
        observed_at=event.timestamp,
        summary=_join_summary(
            event.payload.get("root_cause"),
            event.payload.get("evidence"),
            event.payload.get("fix"),
        ),
        properties={"status": "diagnosed"},
    )
    actor = ExtractedEntity(
        name=event.actor,
        entity_type="actor",
        observed_at=event.timestamp,
    )
    edge = ExtractedEdge(
        source=event.actor,
        target=issue,
        relation_type="diagnosed_issue",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[entity, actor],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("verification.recorded")
def _extract_verification_recorded(event: Event) -> ExtractionResult:
    """Extract verification evidence such as test, lint, build, or smoke checks."""
    command = _optional_text(event.payload.get("command")) or f"verification:{event.seq}"
    outcome = _optional_text(event.payload.get("outcome")) or "unknown"
    entity = ExtractedEntity(
        name=command,
        entity_type="verification",
        observed_at=event.timestamp,
        summary=_join_summary(
            outcome,
            event.payload.get("summary"),
            event.payload.get("evidence"),
        ),
        properties={"outcome": outcome},
    )
    actor = ExtractedEntity(
        name=event.actor,
        entity_type="actor",
        observed_at=event.timestamp,
    )
    edge = ExtractedEdge(
        source=event.actor,
        target=command,
        relation_type="recorded_verification",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[entity, actor],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("handoff.created")
def _extract_handoff_created(event: Event) -> ExtractionResult:
    """Extract a handoff summary with next steps and residual risks."""
    name = _optional_text(event.payload.get("title")) or f"handoff:{event.seq}"
    entity = ExtractedEntity(
        name=name,
        entity_type="handoff",
        observed_at=event.timestamp,
        summary=_join_summary(
            event.payload.get("summary"),
            event.payload.get("next_steps"),
            event.payload.get("risks"),
        ),
        properties={"status": "created"},
    )
    actor = ExtractedEntity(
        name=event.actor,
        entity_type="actor",
        observed_at=event.timestamp,
    )
    edge = ExtractedEdge(
        source=event.actor,
        target=name,
        relation_type="created_handoff",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[entity, actor],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("coordination.mission.created")
def _extract_coordination_mission_created(event: Event) -> ExtractionResult:
    """Extract a high-level coordinator mission."""
    mission_id = _coordination_mission_id(event)
    status = _optional_text(event.payload.get("status")) or "active"
    mission = ExtractedEntity(
        name=mission_id,
        entity_type="mission",
        observed_at=event.timestamp,
        summary=_optional_text(event.payload.get("objective")),
        properties=_compact_properties({"status": status}),
    )
    actor = ExtractedEntity(name=event.actor, entity_type="actor", observed_at=event.timestamp)
    edge = ExtractedEdge(
        source=event.actor,
        target=mission_id,
        relation_type="started_mission",
        valid_from=event.timestamp,
    )
    return ExtractionResult(entities=[mission, actor], edges=[edge], source_event_seq=event.seq)


@register("coordination.worker.created")
def _extract_coordination_worker_created(event: Event) -> ExtractionResult:
    """Extract a registered worker under a mission."""
    mission_id = _coordination_mission_id(event)
    worker_id = _coordination_worker_id(event)
    mission = ExtractedEntity(name=mission_id, entity_type="mission", observed_at=event.timestamp)
    worker = ExtractedEntity(
        name=worker_id,
        entity_type="worker",
        observed_at=event.timestamp,
        properties=_compact_properties(
            {
                "mission_id": mission_id,
                "status": _optional_text(event.payload.get("status")) or "active",
            }
        ),
    )
    edge = ExtractedEdge(
        source=mission_id,
        target=worker_id,
        relation_type="mission_has_worker",
        valid_from=event.timestamp,
    )
    return ExtractionResult(entities=[mission, worker], edges=[edge], source_event_seq=event.seq)


@register("coordination.assignment.created")
def _extract_coordination_assignment_created(event: Event) -> ExtractionResult:
    """Extract a worker assignment."""
    mission_id = _coordination_mission_id(event)
    worker_id = _coordination_worker_id(event)
    assignment_id = (
        _optional_text(event.payload.get("assignment_id"))
        or f"{mission_id}:{worker_id}:assignment:{event.seq}"
    )
    assignment = ExtractedEntity(
        name=assignment_id,
        entity_type="assignment",
        observed_at=event.timestamp,
        summary=_optional_text(event.payload.get("assignment")),
        properties=_compact_properties(
            {
                "status": _optional_text(event.payload.get("status")) or "assigned",
                "mission_id": mission_id,
                "worker_id": worker_id,
            }
        ),
    )
    worker = ExtractedEntity(name=worker_id, entity_type="worker", observed_at=event.timestamp)
    edge = ExtractedEdge(
        source=worker_id,
        target=assignment_id,
        relation_type="worker_has_assignment",
        valid_from=event.timestamp,
    )
    return ExtractionResult(entities=[worker, assignment], edges=[edge], source_event_seq=event.seq)


@register("coordination.finding.reported")
def _extract_coordination_finding_reported(event: Event) -> ExtractionResult:
    """Extract a worker-local finding with evidence metadata."""
    mission_id = _coordination_mission_id(event)
    worker_id = _coordination_worker_id(event)
    finding_id = _coordination_finding_id(event)
    evidence = event.payload.get("evidence")
    evidence_count = len(evidence) if isinstance(evidence, list) else 0
    finding = ExtractedEntity(
        name=finding_id,
        entity_type="finding",
        observed_at=event.timestamp,
        summary=_optional_text(event.payload.get("summary")),
        properties=_compact_properties(
            {
                "status": _optional_text(event.payload.get("status")) or "pending",
                "mission_id": mission_id,
                "worker_id": worker_id,
                "evidence_count": evidence_count,
                "confidence": _bounded_float(event.payload.get("confidence")),
                "claim_key": _optional_text(event.payload.get("claim_key")),
                "claim_value": _optional_text(event.payload.get("claim_value")),
            }
        ),
    )
    worker = ExtractedEntity(name=worker_id, entity_type="worker", observed_at=event.timestamp)
    edge = ExtractedEdge(
        source=worker_id,
        target=finding_id,
        relation_type="worker_reported_finding",
        valid_from=event.timestamp,
    )
    return ExtractionResult(entities=[worker, finding], edges=[edge], source_event_seq=event.seq)


@register("coordination.finding.reviewed")
def _extract_coordination_finding_reviewed(event: Event) -> ExtractionResult:
    """Extract a coordinator review of a worker finding."""
    mission_id = _coordination_mission_id(event)
    worker_id = _coordination_worker_id(event)
    finding_id = _coordination_finding_id(event)
    status = _optional_text(event.payload.get("status")) or "reviewed"
    review_id = f"{mission_id}:{finding_id}:review:{event.seq}"
    review = ExtractedEntity(
        name=review_id,
        entity_type="finding_review",
        observed_at=event.timestamp,
        summary=_join_summary(status, event.payload.get("rationale")),
        properties=_compact_properties({"status": status, "mission_id": mission_id, "worker_id": worker_id}),
    )
    finding = ExtractedEntity(name=finding_id, entity_type="finding", observed_at=event.timestamp)
    edge = ExtractedEdge(
        source=event.actor,
        target=finding_id,
        relation_type="coordinator_reviewed_finding",
        valid_from=event.timestamp,
    )
    return ExtractionResult(entities=[finding, review], edges=[edge], source_event_seq=event.seq)


@register("coordination.finding.promoted")
def _extract_coordination_finding_promoted(event: Event) -> ExtractionResult:
    """Extract accepted parent state promoted from a worker finding."""
    mission_id = _coordination_mission_id(event)
    finding_id = _coordination_finding_id(event)
    promotion_id = f"{mission_id}:{finding_id}:promotion:{event.seq}"
    promotion = ExtractedEntity(
        name=promotion_id,
        entity_type="promotion",
        observed_at=event.timestamp,
        summary=_optional_text(event.payload.get("summary")),
        properties=_compact_properties(
            {
                "status": _optional_text(event.payload.get("status")) or "accepted",
                "mission_id": mission_id,
                "worker_id": _optional_text(event.payload.get("worker_id")),
                "finding_id": finding_id,
                "source_event_seq": event.payload.get("source_event_seq"),
                "source_event_hash": _optional_text(event.payload.get("source_event_hash")),
                "claim_key": _optional_text(event.payload.get("claim_key")),
                "claim_value": _optional_text(event.payload.get("claim_value")),
            }
        ),
    )
    mission = ExtractedEntity(name=mission_id, entity_type="mission", observed_at=event.timestamp)
    edge = ExtractedEdge(
        source=finding_id,
        target=promotion_id,
        relation_type="finding_promoted_to_parent",
        valid_from=event.timestamp,
    )
    return ExtractionResult(entities=[mission, promotion], edges=[edge], source_event_seq=event.seq)


@register("coordination.conflict.detected")
def _extract_coordination_conflict_detected(event: Event) -> ExtractionResult:
    """Extract a deterministic conflict between worker findings."""
    mission_id = _coordination_mission_id(event)
    conflict_id = _optional_text(event.payload.get("conflict_id")) or f"{mission_id}:conflict:{event.seq}"
    finding_ids = _string_list(event.payload.get("finding_ids"))
    conflict = ExtractedEntity(
        name=conflict_id,
        entity_type="conflict",
        observed_at=event.timestamp,
        summary=_optional_text(event.payload.get("summary")),
        properties=_compact_properties(
            {
                "mission_id": mission_id,
                "claim_key": _optional_text(event.payload.get("claim_key")),
                "conflict_type": _optional_text(event.payload.get("conflict_type")) or "exact_claim",
                "reason": _optional_text(event.payload.get("reason")),
                "source_reference": _optional_text(event.payload.get("source_reference")),
                "finding_count": len(finding_ids),
            }
        ),
    )
    mission = ExtractedEntity(name=mission_id, entity_type="mission", observed_at=event.timestamp)
    entities = [mission, conflict]
    edges = [
        ExtractedEdge(
            source=mission_id,
            target=conflict_id,
            relation_type="mission_has_conflict",
            valid_from=event.timestamp,
        )
    ]
    for finding_id in finding_ids:
        entities.append(ExtractedEntity(name=finding_id, entity_type="finding", observed_at=event.timestamp))
        edges.append(
            ExtractedEdge(
                source=finding_id,
                target=conflict_id,
                relation_type="finding_conflicts_with",
                valid_from=event.timestamp,
            )
        )
    return ExtractionResult(entities=entities, edges=edges, source_event_seq=event.seq)


@register("coordination.decision.recorded")
def _extract_coordination_decision_recorded(event: Event) -> ExtractionResult:
    """Extract a coordinator decision."""
    mission_id = _coordination_mission_id(event)
    decision_id = _optional_text(event.payload.get("decision_id")) or f"{mission_id}:decision:{event.seq}"
    decision = ExtractedEntity(
        name=decision_id,
        entity_type="decision",
        observed_at=event.timestamp,
        summary=_join_summary(event.payload.get("decision"), event.payload.get("rationale")),
        properties=_compact_properties({"mission_id": mission_id}),
    )
    mission = ExtractedEntity(name=mission_id, entity_type="mission", observed_at=event.timestamp)
    edge = ExtractedEdge(
        source=mission_id,
        target=decision_id,
        relation_type="mission_has_decision",
        valid_from=event.timestamp,
    )
    return ExtractionResult(entities=[mission, decision], edges=[edge], source_event_seq=event.seq)


@register("coordination.handoff.created")
def _extract_coordination_handoff_created(event: Event) -> ExtractionResult:
    """Extract a final mission handoff."""
    mission_id = _coordination_mission_id(event)
    handoff_id = _optional_text(event.payload.get("handoff_id")) or f"{mission_id}:handoff:{event.seq}"
    handoff = ExtractedEntity(
        name=handoff_id,
        entity_type="handoff",
        observed_at=event.timestamp,
        summary=_join_summary(event.payload.get("summary"), event.payload.get("next_steps"), event.payload.get("risks")),
        properties=_compact_properties({"mission_id": mission_id, "status": "created"}),
    )
    mission = ExtractedEntity(name=mission_id, entity_type="mission", observed_at=event.timestamp)
    edge = ExtractedEdge(
        source=mission_id,
        target=handoff_id,
        relation_type="mission_has_handoff",
        valid_from=event.timestamp,
    )
    return ExtractionResult(entities=[mission, handoff], edges=[edge], source_event_seq=event.seq)


@register("coordination.proof_packet.created")
def _extract_coordination_proof_packet_created(event: Event) -> ExtractionResult:
    """Extract a mission-scoped synthesis proof packet for coordinator memory."""
    mission_id = _coordination_mission_id(event)
    artifact_id = _optional_text(event.payload.get("artifact_id"))
    proof_id = artifact_id or f"{mission_id}:proof_packet:{event.seq}"
    accepted_ids = _string_list(event.payload.get("accepted_finding_ids"))
    diagnostic_pending_ids = _string_list(event.payload.get("diagnostic_pending_ids"))
    conflict_ids = _string_list(event.payload.get("conflict_ids"))
    non_authoritative_rows = _dict_list(event.payload.get("non_authoritative_rows"))
    excluded_row_reasons = _dict_list(event.payload.get("excluded_row_reasons"))
    handoff_ref = event.payload.get("handoff_event_ref")
    handoff_id = _optional_text(handoff_ref.get("handoff_id")) if isinstance(handoff_ref, dict) else None
    proof = ExtractedEntity(
        name=proof_id,
        entity_type="coordination_proof_packet",
        observed_at=event.timestamp,
        summary=_join_summary(event.payload.get("query"), event.payload.get("decision_scope")),
        properties=_compact_properties(
            {
                "mission_id": mission_id,
                "schema_version": _optional_text(event.payload.get("schema_version")),
                "artifact_id": artifact_id,
                "decision_scope": _optional_text(event.payload.get("decision_scope")),
                "authority_scope": _optional_text(event.payload.get("authority_scope")),
                "accepted_finding_count": len(accepted_ids),
                "diagnostic_pending_count": len(diagnostic_pending_ids),
                "conflict_count": len(conflict_ids),
                "non_authoritative_row_count": len(non_authoritative_rows),
                "excluded_row_reason_count": len(excluded_row_reasons),
                "handoff_id": handoff_id,
            }
        ),
    )
    mission = ExtractedEntity(name=mission_id, entity_type="mission", observed_at=event.timestamp)
    entities = [mission, proof]
    edges = [
        ExtractedEdge(
            source=mission_id,
            target=proof_id,
            relation_type="mission_has_proof_packet",
            valid_from=event.timestamp,
        )
    ]
    if artifact_id:
        entities.append(ExtractedEntity(name=artifact_id, entity_type="synthesis_artifact", observed_at=event.timestamp))
        edges.append(
            ExtractedEdge(
                source=proof_id,
                target=artifact_id,
                relation_type="proof_links_synthesis_artifact",
                valid_from=event.timestamp,
            )
        )
    for finding_id in accepted_ids:
        entities.append(ExtractedEntity(name=finding_id, entity_type="finding", observed_at=event.timestamp))
        edges.append(
            ExtractedEdge(
                source=proof_id,
                target=finding_id,
                relation_type="proof_uses_accepted_finding",
                valid_from=event.timestamp,
            )
        )
    for row in non_authoritative_rows:
        row_id = _coordination_proof_row_id(proof_id, row)
        if row_id is None:
            continue
        entities.append(
            ExtractedEntity(
                name=row_id,
                entity_type="coordination_non_authoritative_row",
                observed_at=event.timestamp,
                summary=_join_summary(row.get("status"), row.get("include_reason"), row.get("exclude_reason")),
                properties=_compact_properties(
                    {
                        "mission_id": mission_id,
                        "proof_packet_id": proof_id,
                        "source_group": _optional_text(row.get("source_group")),
                        "fact_id": _optional_text(row.get("fact_id")),
                        "status": _optional_text(row.get("status")),
                        "include_reason": _optional_text(row.get("include_reason")),
                        "exclude_reason": _optional_text(row.get("exclude_reason")),
                    }
                ),
            )
        )
        edges.append(
            ExtractedEdge(
                source=proof_id,
                target=row_id,
                relation_type="proof_excludes_non_authoritative_row",
                valid_from=event.timestamp,
            )
        )
    for conflict_id in conflict_ids:
        entities.append(ExtractedEntity(name=conflict_id, entity_type="conflict", observed_at=event.timestamp))
        edges.append(
            ExtractedEdge(
                source=proof_id,
                target=conflict_id,
                relation_type="proof_diagnoses_conflict",
                valid_from=event.timestamp,
            )
        )
    if handoff_id:
        entities.append(ExtractedEntity(name=handoff_id, entity_type="handoff", observed_at=event.timestamp))
        edges.append(
            ExtractedEdge(
                source=proof_id,
                target=handoff_id,
                relation_type="proof_binds_handoff",
                valid_from=event.timestamp,
            )
        )
    return ExtractionResult(entities=entities, edges=edges, source_event_seq=event.seq)


@register("user.preference_changed")
def _extract_preference_changed(event: Event) -> ExtractionResult:
    """Extract user preference as a persistent entity property."""
    user_id = event.payload.get("userId", event.actor)
    key = event.payload.get("key", "preference")
    user = ExtractedEntity(
        name=user_id,
        entity_type="user",
        observed_at=event.timestamp,
    )
    pref = ExtractedEntity(
        name=f"{user_id}:{key}",
        entity_type="preference",
        observed_at=event.timestamp,
        summary=_preference_summary(key, event.payload.get("value")),
    )
    edge = ExtractedEdge(
        source=user_id,
        target=f"{user_id}:{key}",
        relation_type=f"has_{key}",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[user, pref],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("document.indexed")
def _extract_document_indexed(event: Event) -> ExtractionResult:
    """Extract a cited document chunk from filesystem ingestion."""
    path = _optional_text(event.payload.get("path")) or "document"
    start_line = _positive_int(event.payload.get("start_line"), default=1)
    end_line = _positive_int(event.payload.get("end_line"), default=start_line)
    content = _optional_text(event.payload.get("content")) or ""
    sha256 = _optional_text(event.payload.get("sha256"))
    document_name = f"{path}:{start_line}-{end_line}"
    entity = ExtractedEntity(
        name=document_name,
        entity_type="document",
        observed_at=event.timestamp,
        summary=content,
        properties=_merge_properties(
            {
                "source_path": path,
                "source_start_line": start_line,
                "source_end_line": end_line,
                "source_sha256": sha256,
                **_refresh_transform_properties(event.payload),
            },
            _longmemeval_document_properties(event.payload),
            _retrieval_salience_properties(event.payload),
        )
        or {},
    )
    neutral = neutral_document_record(
        actor=event.actor,
        timestamp=event.timestamp,
        path=path,
        start_line=start_line,
        end_line=end_line,
        content=content,
        source_event_ref=_event_ref(event),
        permission_scope=_optional_text(event.payload.get("permission_scope")),
        uncertainty=_optional_text(event.payload.get("uncertainty")),
        candidate_claim=_optional_text(event.payload.get("candidate_claim")),
    )
    neutral_entity = ExtractedEntity(
        name=neutral.substrate_id,
        entity_type="neutral_substrate",
        observed_at=event.timestamp,
        summary=neutral.quote,
        properties=neutral.to_properties(),
    )
    neutral_edge = ExtractedEdge(
        source=neutral.substrate_id,
        target=document_name,
        relation_type="neutral_substrate_cites_source",
        valid_from=event.timestamp,
    )
    audit_entity, audit_edge = _neutral_audit_projection(event, neutral.substrate_id)
    entities, edges = _document_session_context(
        event,
        document_name=document_name,
    )
    return ExtractionResult(
        entities=[entity, neutral_entity, *([audit_entity] if audit_entity is not None else []), *entities],
        edges=[neutral_edge, *([audit_edge] if audit_edge is not None else []), *edges],
        source_event_seq=event.seq,
    )


@register("code.file.indexed")
def _extract_code_file_indexed(event: Event) -> ExtractionResult:
    """Extract a code file inventory node from codebase indexing."""
    path = _optional_text(event.payload.get("path")) or "code-file"
    language = _optional_text(event.payload.get("language")) or "unknown"
    sha256 = _optional_text(event.payload.get("sha256"))
    byte_count = _positive_int(event.payload.get("bytes"), default=0)
    line_count = _positive_int(event.payload.get("lines"), default=0)
    actor = ExtractedEntity(
        name=event.actor,
        entity_type="actor",
        observed_at=event.timestamp,
    )
    code_file = ExtractedEntity(
        name=path,
        entity_type="code_file",
        observed_at=event.timestamp,
        summary=f"{language} source file with {line_count} lines",
        properties={
            "source_path": path,
            "language": language,
            "source_sha256": sha256,
            "bytes": byte_count,
            "lines": line_count,
            **_refresh_transform_properties(event.payload),
        },
    )
    edge = ExtractedEdge(
        source=actor.name,
        target=code_file.name,
        relation_type="indexed_code_file",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[actor, code_file],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("source.discovered")
@register("source.changed")
@register("source.unchanged")
@register("source.deleted")
def _extract_source_refresh_event(event: Event) -> ExtractionResult:
    """Extract source freshness metadata from context refresh events."""
    path = _optional_text(event.payload.get("path")) or "source"
    source_kind = _optional_text(event.payload.get("source_kind")) or "unknown"
    sha256 = _optional_text(event.payload.get("sha256"))
    previous_sha256 = _optional_text(event.payload.get("previous_sha256"))
    byte_count = _positive_int(event.payload.get("bytes"), default=0)
    status = event.type.removeprefix("source.")
    refresh_properties = _refresh_transform_properties(event.payload)
    if refresh_reason := _optional_text(event.payload.get("refresh_reason")):
        refresh_properties["refresh_reason"] = refresh_reason
    entity = ExtractedEntity(
        name=path,
        entity_type="source",
        observed_at=event.timestamp,
        summary=f"{source_kind} source {path} {status}",
        properties=_merge_properties(
            {
                "source_path": path,
                "source_kind": source_kind,
                "source_sha256": sha256,
                "previous_sha256": previous_sha256,
                "bytes": byte_count,
                "refresh_status": status,
                **refresh_properties,
            },
            {},
        )
        or {},
    )
    return ExtractionResult(entities=[entity], edges=[], source_event_seq=event.seq)


@register("projection.updated")
@register("projection.retired")
def _extract_projection_refresh_event(event: Event) -> ExtractionResult:
    """Extract projection lifecycle metadata from context refresh events."""
    path = _optional_text(event.payload.get("path")) or "source"
    source_kind = _optional_text(event.payload.get("source_kind")) or "unknown"
    projection = _optional_text(event.payload.get("projection")) or "memory"
    status = event.type.removeprefix("projection.")
    projection_properties = _refresh_transform_properties(event.payload)
    if source_sha256 := _optional_text(event.payload.get("source_sha256")):
        projection_properties["source_sha256"] = source_sha256
    source = ExtractedEntity(
        name=path,
        entity_type="source",
        observed_at=event.timestamp,
        properties={
            "source_path": path,
            "source_kind": source_kind,
        },
    )
    projection_entity = ExtractedEntity(
        name=f"projection:{source_kind}:{path}",
        entity_type="projection",
        observed_at=event.timestamp,
        summary=f"{projection} projection {status} for {path}",
        properties={
            "source_path": path,
            "source_kind": source_kind,
            "projection": projection,
            "projection_status": status,
            "source_event": _optional_text(event.payload.get("source_event")),
            "reason": _optional_text(event.payload.get("reason")),
            **projection_properties,
        },
    )
    edge = ExtractedEdge(
        source=source.name,
        target=projection_entity.name,
        relation_type=f"projection_{status}",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[source, projection_entity],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("memory.feedback")
def _extract_memory_feedback(event: Event) -> ExtractionResult:
    """Extract negative or neutral context feedback without mutating target memory."""
    entity_name = _optional_text(event.payload.get("entity_name")) or f"memory:{event.seq}"
    entity_type = _optional_text(event.payload.get("entity_type")) or "memory"
    feedback = _optional_text(event.payload.get("feedback")) or "unknown"
    citation = _optional_text(event.payload.get("citation"))
    feedback_entity = ExtractedEntity(
        name=f"{entity_type}:{entity_name}:feedback:{event.seq}",
        entity_type="memory_feedback",
        observed_at=event.timestamp,
        summary=_optional_text(event.payload.get("reason")) or f"{feedback} feedback for {entity_name}",
        properties=_merge_properties(
            _feedback_purpose_properties(event.payload),
            {
                "feedback": feedback,
                "citation": citation,
                "last_feedback_at": event.timestamp,
            },
        )
        or {},
    )
    target = ExtractedEntity(
        name=entity_name,
        entity_type=entity_type,
        observed_at=event.timestamp,
        properties=_merge_properties(
            _feedback_purpose_properties(event.payload),
            {
                "feedback": feedback,
                "citation": citation,
                "last_feedback_at": event.timestamp,
            },
        )
        or {},
    )
    actor = ExtractedEntity(name=event.actor, entity_type="actor", observed_at=event.timestamp)
    edges = [
        ExtractedEdge(
            source=event.actor,
            target=feedback_entity.name,
            relation_type="recorded_memory_feedback",
            valid_from=event.timestamp,
        ),
        ExtractedEdge(
            source=feedback_entity.name,
            target=entity_name,
            relation_type="feedback_about_memory",
            valid_from=event.timestamp,
        ),
    ]
    return ExtractionResult(
        entities=[feedback_entity, target, actor],
        edges=edges,
        source_event_seq=event.seq,
    )


@register("memory.bootstrap.shown")
@register("memory.checkout.completed")
@register("memory.feedback.recorded")
def _extract_memory_activity_event(event: Event) -> ExtractionResult:
    """Extract model-facing memory activity markers."""
    activity = _optional_text(event.payload.get("activity")) or event.type.removeprefix("memory.").replace(".", "_")
    source = _optional_text(event.payload.get("source")) or event.actor
    query = _optional_text(event.payload.get("query"))
    entity = ExtractedEntity(
        name=f"{event.thread}:memory:{activity}:{event.seq}",
        entity_type="memory_activity",
        observed_at=event.timestamp,
        summary=f"{activity} memory activity from {source}",
        properties=_merge_properties(
            {
                "activity": activity,
                "source": source,
                "session_id": event.thread,
            },
            {"query": query} if query else None,
        )
        or {},
    )
    return ExtractionResult(entities=[entity], edges=[], source_event_seq=event.seq)


@register("memory.reinforcement")
def _extract_memory_reinforcement(event: Event) -> ExtractionResult:
    """Skip projection for non-authoritative salience reinforcement markers.

    Reinforcement events are observability state replayed by the salience
    ledger; projecting them as entities would let reinforcement bookkeeping
    leak into ranked retrieval.
    """
    return ExtractionResult(entities=[], edges=[], source_event_seq=event.seq)


@register("memory.reminder.suggested")
def _extract_memory_reminder_suggested(event: Event) -> ExtractionResult:
    """Extract suggested memory reminders for agent recall hardening."""
    trigger = _optional_text(event.payload.get("trigger")) or "unknown"
    recommended_tool = _optional_text(event.payload.get("recommended_tool")) or "memory_checkout"
    query = _optional_text(event.payload.get("query"))
    entity = ExtractedEntity(
        name=f"{event.thread}:memory-reminder:{event.seq}",
        entity_type="memory_reminder",
        observed_at=event.timestamp,
        summary=f"Memory reminder suggested after {trigger}: call {recommended_tool}",
        properties=_merge_properties(
            {
                "trigger": trigger,
                "recommended_tool": recommended_tool,
                "session_id": event.thread,
            },
            {"query": query} if query else None,
        )
        or {},
    )
    return ExtractionResult(entities=[entity], edges=[], source_event_seq=event.seq)


@register("code.symbol.indexed")
def _extract_code_symbol_indexed(event: Event) -> ExtractionResult:
    """Extract a code symbol and connect it to the defining file."""
    path = _optional_text(event.payload.get("path")) or "code-file"
    language = _optional_text(event.payload.get("language")) or "unknown"
    name = _optional_text(event.payload.get("name")) or "symbol"
    qualified_name = _optional_text(event.payload.get("qualified_name")) or name
    kind = _optional_text(event.payload.get("kind")) or "symbol"
    start_line = _positive_int(event.payload.get("start_line"), default=1)
    end_line = _positive_int(event.payload.get("end_line"), default=start_line)
    code_file = ExtractedEntity(
        name=path,
        entity_type="code_file",
        observed_at=event.timestamp,
        properties={
            "source_path": path,
            "language": language,
        },
    )
    symbol = ExtractedEntity(
        name=f"{path}::{qualified_name}",
        entity_type="code_symbol",
        observed_at=event.timestamp,
        summary=f"{language} {kind} {qualified_name} defined in {path}:{start_line}-{end_line}",
        properties={
            "source_path": path,
            "language": language,
            "symbol_name": name,
            "qualified_name": qualified_name,
            "symbol_kind": kind,
            "source_start_line": start_line,
            "source_end_line": end_line,
            **_source_sha256_property(event.payload),
            **_refresh_transform_properties(event.payload),
        },
    )
    edge = ExtractedEdge(
        source=code_file.name,
        target=symbol.name,
        relation_type="defines_symbol",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[code_file, symbol],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("code.import.indexed")
def _extract_code_import_indexed(event: Event) -> ExtractionResult:
    """Extract a code import and connect it to the importing file."""
    path = _optional_text(event.payload.get("path")) or "code-file"
    language = _optional_text(event.payload.get("language")) or "unknown"
    module = _optional_text(event.payload.get("module")) or "unknown"
    name = _optional_text(event.payload.get("name")) or module
    kind = _optional_text(event.payload.get("kind")) or "import"
    start_line = _positive_int(event.payload.get("start_line"), default=1)
    code_file = ExtractedEntity(
        name=path,
        entity_type="code_file",
        observed_at=event.timestamp,
        properties={
            "source_path": path,
            "language": language,
        },
    )
    imported = ExtractedEntity(
        name=f"import:{module}:{name}",
        entity_type="code_import",
        observed_at=event.timestamp,
        summary=f"{language} {kind} {name} from {module} in {path}:{start_line}",
        properties={
            "source_path": path,
            "language": language,
            "module": module,
            "import_name": name,
            "import_kind": kind,
            "source_start_line": start_line,
            **_source_sha256_property(event.payload),
            **_refresh_transform_properties(event.payload),
        },
    )
    edge = ExtractedEdge(
        source=code_file.name,
        target=imported.name,
        relation_type="imports",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[code_file, imported],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("code.dependency.indexed")
def _extract_code_dependency_indexed(event: Event) -> ExtractionResult:
    """Extract a resolved local code dependency between files."""
    source_path = _optional_text(event.payload.get("source_path")) or "source-code-file"
    target_path = _optional_text(event.payload.get("target_path")) or "target-code-file"
    language = _optional_text(event.payload.get("language")) or "unknown"
    module = _optional_text(event.payload.get("module")) or "unknown"
    import_name = _optional_text(event.payload.get("import_name")) or module
    start_line = _positive_int(event.payload.get("start_line"), default=1)
    resolution = _optional_text(event.payload.get("resolution")) or "unknown"
    source_file = ExtractedEntity(
        name=source_path,
        entity_type="code_file",
        observed_at=event.timestamp,
        properties={
            "source_path": source_path,
            "language": language,
        },
    )
    target_file = ExtractedEntity(
        name=target_path,
        entity_type="code_file",
        observed_at=event.timestamp,
        properties={
            "source_path": target_path,
            "language": language,
        },
    )
    edge = ExtractedEdge(
        source=source_path,
        target=target_path,
        relation_type="depends_on_file",
        valid_from=event.timestamp,
    )
    dependency = ExtractedEntity(
        name=f"{source_path}->{target_path}:{start_line}",
        entity_type="code_dependency",
        observed_at=event.timestamp,
        summary=f"{source_path} imports {import_name} from {module} via {target_path}:{start_line}",
        properties={
            "source_path": source_path,
            "target_path": target_path,
            "language": language,
            "module": module,
            "import_name": import_name,
            "source_start_line": start_line,
            "resolution": resolution,
            **_source_sha256_property(event.payload),
            **_refresh_transform_properties(event.payload),
        },
    )
    return ExtractionResult(
        entities=[source_file, target_file, dependency],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("code.call.indexed")
def _extract_code_call_indexed(event: Event) -> ExtractionResult:
    """Extract a code call-site and resolved call edge when available."""
    path = _optional_text(event.payload.get("path")) or "code-file"
    language = _optional_text(event.payload.get("language")) or "unknown"
    caller = _optional_text(event.payload.get("caller")) or "caller"
    callee = _optional_text(event.payload.get("callee")) or "callee"
    callee_qualified_name = _optional_text(event.payload.get("callee_qualified_name")) or callee
    target_path = _optional_text(event.payload.get("target_path"))
    target_qualified_name = _optional_text(event.payload.get("target_qualified_name"))
    start_line = _positive_int(event.payload.get("start_line"), default=1)
    resolution = _optional_text(event.payload.get("resolution")) or "unresolved"
    caller_symbol = ExtractedEntity(
        name=f"{path}::{caller}",
        entity_type="code_symbol",
        observed_at=event.timestamp,
        properties={
            "source_path": path,
            "language": language,
            "qualified_name": caller,
        },
    )
    call = ExtractedEntity(
        name=f"{path}::{caller}->{callee_qualified_name}:{start_line}",
        entity_type="code_call",
        observed_at=event.timestamp,
        summary=f"{caller} calls {callee_qualified_name} in {path}:{start_line}",
        properties={
            "source_path": path,
            "language": language,
            "caller": caller,
            "callee": callee,
            "callee_qualified_name": callee_qualified_name,
            "target_path": target_path,
            "target_qualified_name": target_qualified_name,
            "source_start_line": start_line,
            "resolution": resolution,
            **_source_sha256_property(event.payload),
            **_refresh_transform_properties(event.payload),
        },
    )
    entities = [caller_symbol, call]
    edges: list[ExtractedEdge] = []
    if target_path and target_qualified_name:
        target_symbol = ExtractedEntity(
            name=f"{target_path}::{target_qualified_name}",
            entity_type="code_symbol",
            observed_at=event.timestamp,
            properties={
                "source_path": target_path,
                "language": language,
                "qualified_name": target_qualified_name,
            },
        )
        entities.append(target_symbol)
        edges.append(
            ExtractedEdge(
                source=caller_symbol.name,
                target=target_symbol.name,
                relation_type="calls_symbol",
                valid_from=event.timestamp,
            )
        )
    return ExtractionResult(
        entities=entities,
        edges=edges,
        source_event_seq=event.seq,
    )


@register("code.coverage.indexed")
def _extract_code_coverage_indexed(event: Event) -> ExtractionResult:
    """Extract a test-to-production symbol coverage link."""
    test_path = _optional_text(event.payload.get("test_path")) or "test-code-file"
    test_name = _optional_text(event.payload.get("test_name")) or "test"
    test_qualified_name = _optional_text(event.payload.get("test_qualified_name")) or test_name
    target_path = _optional_text(event.payload.get("target_path")) or "target-code-file"
    target_name = _optional_text(event.payload.get("target_name")) or "target"
    target_qualified_name = _optional_text(event.payload.get("target_qualified_name")) or target_name
    language = _optional_text(event.payload.get("language")) or "unknown"
    start_line = _positive_int(event.payload.get("start_line"), default=1)
    resolution = _optional_text(event.payload.get("resolution")) or "unknown"
    test_symbol = ExtractedEntity(
        name=f"{test_path}::{test_qualified_name}",
        entity_type="code_symbol",
        observed_at=event.timestamp,
        properties={
            "source_path": test_path,
            "language": language,
            "symbol_name": test_name,
            "qualified_name": test_qualified_name,
            "symbol_kind": "test",
        },
    )
    target_symbol = ExtractedEntity(
        name=f"{target_path}::{target_qualified_name}",
        entity_type="code_symbol",
        observed_at=event.timestamp,
        properties={
            "source_path": target_path,
            "language": language,
            "symbol_name": target_name,
            "qualified_name": target_qualified_name,
        },
    )
    coverage = ExtractedEntity(
        name=f"{test_symbol.name}=>{target_symbol.name}:{start_line}",
        entity_type="code_coverage",
        observed_at=event.timestamp,
        summary=f"{test_qualified_name} tests {target_qualified_name} at {test_path}:{start_line}",
        properties={
            "test_path": test_path,
            "test_name": test_name,
            "test_qualified_name": test_qualified_name,
            "target_path": target_path,
            "target_name": target_name,
            "target_qualified_name": target_qualified_name,
            "language": language,
            "source_start_line": start_line,
            "resolution": resolution,
        },
    )
    edge = ExtractedEdge(
        source=test_symbol.name,
        target=target_symbol.name,
        relation_type="tests_symbol",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[test_symbol, target_symbol, coverage],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("session.genesis")
def _extract_session_genesis(event: Event) -> ExtractionResult:
    """Extract workspace genesis metadata."""
    root = _optional_text(event.payload.get("root")) or "workspace"
    workspace_type = _optional_text(event.payload.get("workspace_type")) or "generic_workspace"
    instructions_profile = _optional_text(event.payload.get("instructions_profile")) or "generic"
    session_id = _optional_text(event.payload.get("session_id")) or event.thread or "default"
    confidence = event.payload.get("confidence", 0.0)
    signals = event.payload.get("signals")
    if not isinstance(signals, list):
        signals = []
    workspace = ExtractedEntity(
        name=root,
        entity_type="workspace",
        observed_at=event.timestamp,
        summary=f"{workspace_type} workspace profile {instructions_profile}",
        properties={
            "root": root,
            "workspace_type": workspace_type,
            "confidence": confidence,
            "signals": signals,
            "instructions_profile": instructions_profile,
            "session_id": session_id,
        },
    )
    session = ExtractedEntity(
        name=session_id,
        entity_type="session",
        observed_at=event.timestamp,
    )
    edge = ExtractedEdge(
        source=session.name,
        target=workspace.name,
        relation_type="initialized_workspace",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[session, workspace],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("session.profile.corrected")
def _extract_session_profile_corrected(event: Event) -> ExtractionResult:
    """Extract a durable workspace profile correction."""
    session_id = _optional_text(event.payload.get("session_id")) or event.thread or "default"
    from_profile = _optional_text(event.payload.get("from")) or "unknown"
    to_profile = _optional_text(event.payload.get("to")) or "unknown"
    reason = _optional_text(event.payload.get("reason"))
    root = _optional_text(event.payload.get("root"))
    correction = ExtractedEntity(
        name=f"{session_id}:{from_profile}->{to_profile}",
        entity_type="workspace_profile_correction",
        observed_at=event.timestamp,
        summary=reason,
        properties={
            "session_id": session_id,
            "root": root,
            "from": from_profile,
            "to": to_profile,
            "reason": reason,
        },
    )
    session = ExtractedEntity(
        name=session_id,
        entity_type="session",
        observed_at=event.timestamp,
    )
    edge = ExtractedEdge(
        source=session.name,
        target=correction.name,
        relation_type="corrected_workspace_profile",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[session, correction],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("workspace.instructions.discovered")
@register("workspace.instructions.updated")
def _extract_workspace_instructions_discovered(event: Event) -> ExtractionResult:
    """Extract a workspace instruction snapshot."""
    session_id = _optional_text(event.payload.get("session_id")) or event.thread or "default"
    root = _optional_text(event.payload.get("root")) or "workspace"
    signature = _optional_text(event.payload.get("signature")) or str(event.seq)
    summary = _optional_text(event.payload.get("summary"))
    files = event.payload.get("files")
    if not isinstance(files, list):
        files = []
    file_paths = [
        path
        for file in files
        if isinstance(file, dict) and (path := _optional_text(file.get("path")))
    ]
    file_kinds = [
        kind
        for file in files
        if isinstance(file, dict) and (kind := _optional_text(file.get("kind")))
    ]
    instruction = ExtractedEntity(
        name=f"{root}:instructions:{signature}",
        entity_type="workspace_instructions",
        observed_at=event.timestamp,
        summary=summary,
        properties={
            "session_id": session_id,
            "root": root,
            "signature": signature,
            "file_count": len(files),
            "file_paths": file_paths,
            "file_kinds": file_kinds,
        },
    )
    session = ExtractedEntity(
        name=session_id,
        entity_type="session",
        observed_at=event.timestamp,
    )
    edge = ExtractedEdge(
        source=session.name,
        target=instruction.name,
        relation_type="uses_workspace_instructions",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[session, instruction],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("tool.call.completed")
def _extract_tool_call_completed(event: Event) -> ExtractionResult:
    """Extract a completed tool call lifecycle event."""
    session_id = _optional_text(event.payload.get("session_id")) or event.thread or "default"
    tool_name = _optional_text(event.payload.get("tool_name")) or "tool"
    status = _optional_text(event.payload.get("status")) or "unknown"
    call_id = _optional_text(event.payload.get("call_id"))
    name = f"{session_id}:{tool_name}:{call_id or event.seq}"
    tool_call = ExtractedEntity(
        name=name,
        entity_type="tool_call",
        observed_at=event.timestamp,
        summary=_join_summary(status, event.payload.get("result_summary")),
        properties={
            "tool_name": tool_name,
            "status": status,
            "session_id": session_id,
            "call_id": call_id,
        },
    )
    session = ExtractedEntity(name=session_id, entity_type="session", observed_at=event.timestamp)
    edge = ExtractedEdge(
        source=session.name,
        target=tool_call.name,
        relation_type="completed_tool_call",
        valid_from=event.timestamp,
    )
    entities, edges = _with_explicit_task_observation(
        event,
        [session, tool_call],
        [edge],
        target=tool_call.name,
        relation_type="observed_tool_call",
    )
    return ExtractionResult(entities=entities, edges=edges, source_event_seq=event.seq)


@register("command.completed")
def _extract_command_completed(event: Event) -> ExtractionResult:
    """Extract a completed shell/process command lifecycle event."""
    session_id = _optional_text(event.payload.get("session_id")) or event.thread or "default"
    command_text = _optional_text(event.payload.get("command")) or "command"
    outcome = _optional_text(event.payload.get("outcome")) or "unknown"
    command = ExtractedEntity(
        name=f"{session_id}:{command_text}:{event.seq}",
        entity_type="command_run",
        observed_at=event.timestamp,
        summary=_join_summary(outcome, command_text),
        properties={
            "command": command_text,
            "exit_code": event.payload.get("exit_code"),
            "outcome": outcome,
            "session_id": session_id,
        },
    )
    session = ExtractedEntity(name=session_id, entity_type="session", observed_at=event.timestamp)
    edge = ExtractedEdge(
        source=session.name,
        target=command.name,
        relation_type="completed_command",
        valid_from=event.timestamp,
    )
    entities, edges = _with_explicit_task_observation(
        event,
        [session, command],
        [edge],
        target=command.name,
        relation_type="observed_command",
    )
    return ExtractionResult(entities=entities, edges=edges, source_event_seq=event.seq)


@register("file.edit.applied")
def _extract_file_edit_applied(event: Event) -> ExtractionResult:
    """Extract a file-edit lifecycle event without source content."""
    session_id = _optional_text(event.payload.get("session_id")) or event.thread or "default"
    path = _optional_text(event.payload.get("path")) or "file"
    operation = _optional_text(event.payload.get("operation")) or "modified"
    edit = ExtractedEntity(
        name=f"{session_id}:{path}:{event.seq}",
        entity_type="file_edit",
        observed_at=event.timestamp,
        summary=_join_summary(operation, event.payload.get("summary")),
        properties={
            "path": path,
            "operation": operation,
            "session_id": session_id,
            "line_count": event.payload.get("line_count"),
        },
    )
    session = ExtractedEntity(name=session_id, entity_type="session", observed_at=event.timestamp)
    edge = ExtractedEdge(
        source=session.name,
        target=edit.name,
        relation_type="applied_file_edit",
        valid_from=event.timestamp,
    )
    entities, edges = _with_explicit_task_observation(
        event,
        [session, edit],
        [edge],
        target=edit.name,
        relation_type="observed_file_edit",
    )
    return ExtractionResult(entities=entities, edges=edges, source_event_seq=event.seq)


@register("compaction.completed")
def _extract_compaction_completed(event: Event) -> ExtractionResult:
    """Extract a completed compaction lifecycle event."""
    session_id = _optional_text(event.payload.get("session_id")) or event.thread or "default"
    mode = _optional_text(event.payload.get("mode")) or "unknown"
    status = _optional_text(event.payload.get("status")) or "unknown"
    log_path = _optional_text(event.payload.get("log_path")) or "eventloom"
    compaction = ExtractedEntity(
        name=f"{session_id}:compaction:{event.seq}",
        entity_type="compaction_run",
        observed_at=event.timestamp,
        summary=_join_summary(status, mode, log_path),
        properties={
            "session_id": session_id,
            "mode": mode,
            "status": status,
            "log_path": log_path,
            "event_count": event.payload.get("event_count"),
            "output_path": event.payload.get("output_path"),
            "projection_path": event.payload.get("projection_path"),
            "snapshot_path": event.payload.get("snapshot_path"),
            "strategy": event.payload.get("strategy"),
        },
    )
    session = ExtractedEntity(name=session_id, entity_type="session", observed_at=event.timestamp)
    edge = ExtractedEdge(
        source=session.name,
        target=compaction.name,
        relation_type="completed_compaction",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[session, compaction],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("subagent.completed")
def _extract_subagent_completed(event: Event) -> ExtractionResult:
    """Extract a completed subagent lifecycle event."""
    parent_session_id = _optional_text(event.payload.get("parent_session_id")) or "default"
    subagent_session_id = _optional_text(event.payload.get("subagent_session_id")) or event.thread or "subagent"
    status = _optional_text(event.payload.get("status")) or "unknown"
    summary = _optional_text(event.payload.get("summary"))
    subagent = ExtractedEntity(
        name=f"{parent_session_id}:{subagent_session_id}:{event.seq}",
        entity_type="subagent_run",
        observed_at=event.timestamp,
        summary=_join_summary(status, summary),
        properties={
            "parent_session_id": parent_session_id,
            "subagent_session_id": subagent_session_id,
            "status": status,
        },
    )
    parent = ExtractedEntity(
        name=parent_session_id,
        entity_type="session",
        observed_at=event.timestamp,
    )
    edge = ExtractedEdge(
        source=parent.name,
        target=subagent.name,
        relation_type="completed_subagent",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[parent, subagent],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("session.ended")
def _extract_session_ended(event: Event) -> ExtractionResult:
    """Extract a session-end lifecycle event."""
    session_id = _optional_text(event.payload.get("session_id")) or event.thread or "default"
    reason = _optional_text(event.payload.get("reason")) or "ended"
    status = _optional_text(event.payload.get("status")) or "unknown"
    ended = ExtractedEntity(
        name=f"{session_id}:session-ended:{event.seq}",
        entity_type="session_end",
        observed_at=event.timestamp,
        summary=_join_summary(status, reason),
        properties={
            "session_id": session_id,
            "reason": reason,
            "status": status,
        },
    )
    session = ExtractedEntity(name=session_id, entity_type="session", observed_at=event.timestamp)
    edge = ExtractedEdge(
        source=session.name,
        target=ended.name,
        relation_type="ended_session",
        valid_from=event.timestamp,
    )
    return ExtractionResult(entities=[session, ended], edges=[edge], source_event_seq=event.seq)


@register("transcript.turn")
def _extract_transcript_turn(event: Event) -> ExtractionResult:
    """Extract a sanitized session transcript turn."""
    source = _optional_text(event.payload.get("source")) or "transcript"
    turn_index = _positive_int(event.payload.get("turn_index"), default=event.seq)
    role = _optional_text(event.payload.get("role")) or event.actor
    content = _optional_text(event.payload.get("content")) or ""
    redacted_paths = event.payload.get("redacted_paths")
    if not isinstance(redacted_paths, list):
        redacted_paths = []
    entity = ExtractedEntity(
        name=f"{source}:turn-{turn_index}",
        entity_type="transcript_turn",
        observed_at=event.timestamp,
        summary=f"{role}: {content}",
        properties={
            "transcript_source": source,
            "transcript_role": role,
            "transcript_turn_index": turn_index,
            "redacted_paths": redacted_paths,
        },
    )
    neutral = neutral_transcript_record(
        actor=event.actor,
        timestamp=event.timestamp,
        source=source,
        turn_index=turn_index,
        role=role,
        content=content,
        source_event_ref=_event_ref(event),
        permission_scope=_optional_text(event.payload.get("permission_scope")),
        uncertainty=_optional_text(event.payload.get("uncertainty")),
        candidate_claim=_optional_text(event.payload.get("candidate_claim")),
    )
    neutral_entity = ExtractedEntity(
        name=neutral.substrate_id,
        entity_type="neutral_substrate",
        observed_at=event.timestamp,
        summary=neutral.quote,
        properties=neutral.to_properties(),
    )
    neutral_edge = ExtractedEdge(
        source=neutral.substrate_id,
        target=entity.name,
        relation_type="neutral_substrate_cites_source",
        valid_from=event.timestamp,
    )
    audit_entity, audit_edge = _neutral_audit_projection(event, neutral.substrate_id)
    return ExtractionResult(
        entities=[entity, neutral_entity, *([audit_entity] if audit_entity is not None else [])],
        edges=[neutral_edge, *([audit_edge] if audit_edge is not None else [])],
        source_event_seq=event.seq,
    )


@register("llm.packet.projected")
def _extract_llm_packet_projected(event: Event) -> ExtractionResult:
    """Extract a cold-path LLM packet projection."""
    session_id = _optional_text(event.payload.get("session_id")) or event.thread
    source_event_seq = _positive_int(event.payload.get("source_event_seq"), default=event.seq)
    source_event_hash = _optional_text(event.payload.get("source_event_hash"))
    provider_path = _optional_text(event.payload.get("provider_path")) or "unknown-provider-path"
    status_code = _positive_int(event.payload.get("status_code"), default=0)
    model = _optional_text(event.payload.get("model"))
    usage_counts = event.payload.get("usage_counts")
    if not isinstance(usage_counts, dict):
        usage_counts = {}
    packet = ExtractedEntity(
        name=f"{session_id}:llm-packet:{source_event_seq}",
        entity_type="llm_packet_projection",
        observed_at=event.timestamp,
        summary=_optional_text(event.payload.get("summary")),
        properties={
            "session_id": session_id,
            "source_event_seq": source_event_seq,
            "source_event_hash": source_event_hash,
            "provider_path": provider_path,
            "status_code": status_code,
            "model": model,
            "prompt_tokens": usage_counts.get("prompt"),
            "completion_tokens": usage_counts.get("completion"),
            "total_tokens": usage_counts.get("total"),
        },
    )
    session = ExtractedEntity(
        name=session_id,
        entity_type="session",
        observed_at=event.timestamp,
    )
    edge = ExtractedEdge(
        source=session.name,
        target=packet.name,
        relation_type="projected_llm_packet",
        valid_from=event.timestamp,
    )
    return ExtractionResult(
        entities=[session, packet],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("inference.edge.generated")
def _extract_inference_edge_generated(event: Event) -> ExtractionResult:
    """Project an explicit, auditable inferred relationship event."""
    source = _entity_reference(
        event.payload.get("source"),
        role="source",
        event_seq=event.seq,
        observed_at=event.timestamp,
    )
    target = _entity_reference(
        event.payload.get("target"),
        role="target",
        event_seq=event.seq,
        observed_at=event.timestamp,
    )
    relation_type = _required_text(
        event.payload.get("relation_type"),
        field="relation_type",
        event_seq=event.seq,
    )
    inference_method = _required_text(
        event.payload.get("inference_method"),
        field="inference_method",
        event_seq=event.seq,
    )
    confidence = _required_confidence(event.payload.get("confidence"), event_seq=event.seq)
    evidence = event.payload.get("evidence")
    edge = ExtractedEdge(
        source=source.name,
        target=target.name,
        relation_type=relation_type,
        valid_from=event.timestamp,
        inferred=True,
        confidence=confidence,
        inference_method=inference_method,
        evidence=evidence if isinstance(evidence, dict) else {},
    )
    return ExtractionResult(
        entities=[source, target],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("inference.edge.retracted")
def _extract_inference_edge_retracted(event: Event) -> ExtractionResult:
    """Project a contradicted inferred edge as a closed validity interval."""
    source = _entity_reference(
        event.payload.get("source"),
        role="source",
        event_seq=event.seq,
        observed_at=event.timestamp,
    )
    target = _entity_reference(
        event.payload.get("target"),
        role="target",
        event_seq=event.seq,
        observed_at=event.timestamp,
    )
    relation_type = _required_text(
        event.payload.get("relation_type"),
        field="relation_type",
        event_seq=event.seq,
    )
    inference_method = _required_text(
        event.payload.get("inference_method"),
        field="inference_method",
        event_seq=event.seq,
    )
    valid_from = _required_text(
        event.payload.get("valid_from"),
        field="valid_from",
        event_seq=event.seq,
    )
    valid_to = _required_text(
        event.payload.get("valid_to"),
        field="valid_to",
        event_seq=event.seq,
    )
    confidence = _required_confidence(event.payload.get("confidence"), event_seq=event.seq)
    evidence = event.payload.get("evidence")
    edge = ExtractedEdge(
        source=source.name,
        target=target.name,
        relation_type=relation_type,
        valid_from=valid_from,
        valid_to=valid_to,
        inferred=True,
        confidence=confidence,
        inference_method=inference_method,
        evidence=evidence if isinstance(evidence, dict) else {},
    )
    return ExtractionResult(
        entities=[source, target],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("causal.edge.generated")
def _extract_causal_edge_generated(event: Event) -> ExtractionResult:
    """Project an explicit, cited causal edge as non-authoritative graph evidence."""
    graph_relation_type = _required_causal_graph_relation_type(event.payload, event_seq=event.seq)
    source_payload = event.payload.get("source")
    target_payload = event.payload.get("target")
    evidence_payload = event.payload.get("evidence")
    if not isinstance(source_payload, Mapping):
        raise ValueError(f"causal.edge.generated event {event.seq} missing source entity")
    if not isinstance(target_payload, Mapping):
        raise ValueError(f"causal.edge.generated event {event.seq} missing target entity")
    if not isinstance(evidence_payload, Mapping):
        raise ValueError(f"causal.edge.generated event {event.seq} missing evidence")
    edge_contract = CausalEdge(
        source=source_payload,
        target=target_payload,
        relation_type=_required_text(
            event.payload.get("relation_type"),
            field="relation_type",
            event_seq=event.seq,
            event_type="causal.edge.generated",
        ),
        graph_relation_type=graph_relation_type,
        confidence=_required_numeric_confidence(
            event.payload.get("confidence"),
            event_seq=event.seq,
            event_type="causal.edge.generated",
        ),
        method=_required_strict_text(
            event.payload.get("causal_method"),
            field="causal method",
            event_seq=event.seq,
            event_type="causal.edge.generated",
        ),
        review_status=event.payload.get("review_status", "proposed"),
        authority_status=event.payload.get("authority_status", "non_authoritative"),
        evidence=evidence_payload,
    )
    source = _entity_reference_from_mapping(
        edge_contract.source,
        role="source",
        event_seq=event.seq,
        observed_at=event.timestamp,
        event_type="causal.edge.generated",
    )
    target = _entity_reference_from_mapping(
        edge_contract.target,
        role="target",
        event_seq=event.seq,
        observed_at=event.timestamp,
        event_type="causal.edge.generated",
    )
    edge = ExtractedEdge(
        source=source.name,
        target=target.name,
        relation_type=causal_relation_to_graph_relation(edge_contract.relation_type),
        valid_from=event.timestamp,
        inferred=True,
        confidence=edge_contract.confidence,
        inference_method=edge_contract.method,
        evidence={
            **copy.deepcopy(dict(edge_contract.evidence)),
            "causal_relation_type": edge_contract.relation_type,
            "review_status": edge_contract.review_status,
            "authority_status": edge_contract.authority_status,
        },
    )
    return ExtractionResult(
        entities=[source, target],
        edges=[edge],
        source_event_seq=event.seq,
    )


@register("consolidation.candidate.created")
def _extract_consolidation_candidate_created(event: Event) -> ExtractionResult:
    """Project a cited, review-pending consolidation candidate."""
    candidate_id = _required_consolidation_candidate_id(event.payload.get("candidate_id"))
    candidate_type = _required_consolidation_candidate_type(event.payload.get("candidate_type"))
    if not candidate_id.startswith(f"consolidation:{candidate_type}:"):
        raise ValueError("candidate_id candidate_type must match candidate_type")
    title = _required_consolidation_text(event.payload.get("title"), field="title")
    summary = _required_consolidation_text(event.payload.get("summary"), field="summary")
    source_events = _snapshot_consolidation_source_events(event.payload.get("source_events"))
    source_event_refs = [f"{source_event['seq']}:{source_event['hash']}" for source_event in source_events]
    source_event_seqs = [source_event["seq"] for source_event in source_events]
    source_event_hashes = [source_event["hash"] for source_event in source_events]
    confidence = _required_consolidation_confidence(event.payload.get("confidence"))
    method = _required_consolidation_text(event.payload.get("method"), field="method")
    review_status = event.payload.get("review_status")
    if review_status != CONSOLIDATION_INITIAL_REVIEW_STATUS:
        raise ValueError(
            "review_status must be "
            f"{CONSOLIDATION_INITIAL_REVIEW_STATUS!r} for consolidation candidates"
        )
    authority_status = _required_consolidation_authority_status(event.payload.get("authority_status"))
    purpose = event.payload.get("purpose")
    if purpose is not None:
        purpose = _required_consolidation_text(purpose, field="purpose")

    properties: dict[str, Any] = {
        "candidate_type": candidate_type,
        "title": title,
        "confidence": confidence,
        "method": method,
        "review_status": review_status,
        "authority_status": authority_status,
        "source_event_count": len(source_events),
        "source_event_refs": source_event_refs,
        "source_event_seqs": source_event_seqs,
        "source_event_hashes": source_event_hashes,
        "source_events": source_events,
    }
    if purpose is not None:
        properties["purpose"] = purpose

    candidate = ExtractedEntity(
        name=candidate_id,
        entity_type="consolidation_candidate",
        observed_at=event.timestamp,
        summary=summary,
        properties=properties,
    )
    return ExtractionResult(entities=[candidate], edges=[], source_event_seq=event.seq)


@register("consolidation.candidate.reviewed")
def _extract_consolidation_candidate_reviewed(event: Event) -> ExtractionResult:
    """Project a human review outcome without promoting candidate authority."""
    candidate_id = _required_consolidation_candidate_id(event.payload.get("candidate_id"))
    status = event.payload.get("status")
    if status not in CONSOLIDATION_REVIEW_STATUSES:
        valid = ", ".join(sorted(CONSOLIDATION_REVIEW_STATUSES))
        raise ValueError(f"status must be one of: {valid}")
    authority_status = _required_consolidation_authority_status(event.payload.get("authority_status"))
    rationale = _required_consolidation_text(event.payload.get("rationale"), field="rationale")

    review_id = f"consolidation_review:{candidate_id}:{event.seq}"
    review = ExtractedEntity(
        name=review_id,
        entity_type="consolidation_review",
        observed_at=event.timestamp,
        summary=rationale,
        properties={
            "candidate_id": candidate_id,
            "status": status,
            "authority_status": authority_status,
            "rationale": rationale,
        },
    )
    candidate = ExtractedEntity(
        name=candidate_id,
        entity_type="consolidation_candidate",
        observed_at=event.timestamp,
        properties={
            "review_status": status,
            "authority_status": authority_status,
        },
    )
    edge = ExtractedEdge(
        source=review_id,
        target=candidate_id,
        relation_type="reviewed_consolidation_candidate",
        valid_from=event.timestamp,
    )
    return ExtractionResult(entities=[review, candidate], edges=[edge], source_event_seq=event.seq)


@register("metacognition.unknown.recorded")
def _extract_metacognition_unknown_recorded(event: Event) -> ExtractionResult:
    """Project an open known-unknown diagnostic without granting authority."""
    unknown_id = _required_reasoning_text(event.payload.get("unknown_id"), field="unknown_id")
    question = _required_reasoning_text(event.payload.get("question"), field="question")
    reason = _required_reasoning_text(event.payload.get("reason"), field="reason")
    claim_key = _required_reasoning_text(event.payload.get("claim_key"), field="claim_key")
    gap_type = _required_reasoning_text(event.payload.get("gap_type"), field="gap_type")
    status = _required_reasoning_text(event.payload.get("status"), field="status")
    if status != "open":
        raise ValueError("status must be 'open' for known unknowns")
    authority_status = _required_consolidation_authority_status(event.payload.get("authority_status"))
    source_events = _snapshot_consolidation_source_events(event.payload.get("source_events"))
    source_event_refs = [f"{source_event['seq']}:{source_event['hash']}" for source_event in source_events]
    source_event_seqs = [source_event["seq"] for source_event in source_events]
    source_event_hashes = [source_event["hash"] for source_event in source_events]
    unknown = ExtractedEntity(
        name=unknown_id,
        entity_type="known_unknown",
        observed_at=event.timestamp,
        summary=question,
        properties=_compact_properties(
            {
                "event_type": event.type,
                "question": question,
                "reason": reason,
                "claim_key": claim_key,
                "gap_type": gap_type,
                "status": status,
                "reverify_query": _optional_text(event.payload.get("reverify_query")),
                "source_event_count": len(source_events),
                "source_event_refs": source_event_refs,
                "source_event_seqs": source_event_seqs,
                "source_event_hashes": source_event_hashes,
                "source_events": source_events,
                "authority_status": authority_status,
            }
        ),
    )
    actor = ExtractedEntity(name=event.actor, entity_type="actor", observed_at=event.timestamp)
    edge = ExtractedEdge(
        source=event.actor,
        target=unknown_id,
        relation_type="recorded_known_unknown",
        valid_from=event.timestamp,
    )
    return ExtractionResult(entities=[unknown, actor], edges=[edge], source_event_seq=event.seq)


@register("metacognition.confidence.assessed")
def _extract_metacognition_confidence_assessed(event: Event) -> ExtractionResult:
    """Project an append-only confidence trajectory point as diagnostic state."""
    assessment_id = _required_reasoning_text(event.payload.get("assessment_id"), field="assessment_id")
    claim = _required_reasoning_text(event.payload.get("claim"), field="claim")
    claim_key = _required_reasoning_text(event.payload.get("claim_key"), field="claim_key")
    confidence = _required_consolidation_confidence(event.payload.get("confidence"))
    support_count = _non_negative_int(event.payload.get("support_count"), default=0)
    conflict_count = _non_negative_int(event.payload.get("conflict_count"), default=0)
    method = _required_reasoning_text(event.payload.get("method"), field="method")
    authority_status = _required_consolidation_authority_status(event.payload.get("authority_status"))
    evidence = _dict_list(event.payload.get("evidence"))
    assessment = ExtractedEntity(
        name=assessment_id,
        entity_type="confidence_assessment",
        observed_at=event.timestamp,
        summary=claim,
        properties=_compact_properties(
            {
                "event_type": event.type,
                "claim": claim,
                "claim_key": claim_key,
                "confidence": confidence,
                "support_count": support_count,
                "conflict_count": conflict_count,
                "requires_reverify": bool(event.payload.get("requires_reverify")),
                "method": method,
                "evidence_count": len(evidence),
                "evidence": evidence,
                "authority_status": authority_status,
            }
        ),
    )
    actor = ExtractedEntity(name=event.actor, entity_type="actor", observed_at=event.timestamp)
    edge = ExtractedEdge(
        source=event.actor,
        target=assessment_id,
        relation_type="assessed_confidence",
        valid_from=event.timestamp,
    )
    return ExtractionResult(entities=[assessment, actor], edges=[edge], source_event_seq=event.seq)


@register("metacognition.conflict.clustered")
def _extract_metacognition_conflict_clustered(event: Event) -> ExtractionResult:
    """Project unresolved support/conflict clusters as diagnostic state."""
    cluster_id = _required_reasoning_text(event.payload.get("cluster_id"), field="cluster_id")
    claim_key = _required_reasoning_text(event.payload.get("claim_key"), field="claim_key")
    claim = _required_reasoning_text(event.payload.get("claim"), field="claim")
    confidence = _required_consolidation_confidence(event.payload.get("confidence"))
    reason = _required_reasoning_text(event.payload.get("reason"), field="reason")
    resolution_status = _required_reasoning_text(
        event.payload.get("resolution_status"),
        field="resolution_status",
    )
    if resolution_status != "unresolved":
        raise ValueError("resolution_status must be 'unresolved' for conflict clusters")
    authority_status = _required_consolidation_authority_status(event.payload.get("authority_status"))
    supporting_source_events = _snapshot_consolidation_source_events(
        event.payload.get("supporting_source_events")
    )
    conflicting_source_events = _snapshot_consolidation_source_events(
        event.payload.get("conflicting_source_events")
    )
    cluster = ExtractedEntity(
        name=cluster_id,
        entity_type="conflict_cluster",
        observed_at=event.timestamp,
        summary=claim,
        properties={
            "event_type": event.type,
            "claim_key": claim_key,
            "claim": claim,
            "confidence": confidence,
            "reason": reason,
            "resolution_status": resolution_status,
            "supporting_source_event_count": len(supporting_source_events),
            "supporting_source_event_refs": [
                f"{source_event['seq']}:{source_event['hash']}"
                for source_event in supporting_source_events
            ],
            "supporting_source_event_seqs": [source_event["seq"] for source_event in supporting_source_events],
            "supporting_source_event_hashes": [source_event["hash"] for source_event in supporting_source_events],
            "supporting_source_events": supporting_source_events,
            "conflicting_source_event_count": len(conflicting_source_events),
            "conflicting_source_event_refs": [
                f"{source_event['seq']}:{source_event['hash']}"
                for source_event in conflicting_source_events
            ],
            "conflicting_source_event_seqs": [source_event["seq"] for source_event in conflicting_source_events],
            "conflicting_source_event_hashes": [source_event["hash"] for source_event in conflicting_source_events],
            "conflicting_source_events": conflicting_source_events,
            "authority_status": authority_status,
        },
    )
    actor = ExtractedEntity(name=event.actor, entity_type="actor", observed_at=event.timestamp)
    edge = ExtractedEdge(
        source=event.actor,
        target=cluster_id,
        relation_type="clustered_conflicting_evidence",
        valid_from=event.timestamp,
    )
    return ExtractionResult(entities=[cluster, actor], edges=[edge], source_event_seq=event.seq)


@register("metacognition.reverify.requested")
def _extract_metacognition_reverify_requested(event: Event) -> ExtractionResult:
    """Project an open re-verification request as non-authoritative diagnostic state."""
    reverify_id = _required_reasoning_text(event.payload.get("reverify_id"), field="reverify_id")
    query = _required_reasoning_text(event.payload.get("query"), field="query")
    reason = _required_reasoning_text(event.payload.get("reason"), field="reason")
    claim_key = _required_reasoning_text(event.payload.get("claim_key"), field="claim_key")
    priority = _required_reasoning_text(event.payload.get("priority"), field="priority")
    status = _required_reasoning_text(event.payload.get("status"), field="status")
    if status != "open":
        raise ValueError("status must be 'open' for reverify requests")
    authority_status = _required_consolidation_authority_status(event.payload.get("authority_status"))
    source_events = _snapshot_consolidation_source_events(event.payload.get("source_events"))
    source_event_refs = [f"{source_event['seq']}:{source_event['hash']}" for source_event in source_events]
    request = ExtractedEntity(
        name=reverify_id,
        entity_type="reverify_request",
        observed_at=event.timestamp,
        summary=query,
        properties={
            "event_type": event.type,
            "query": query,
            "reason": reason,
            "claim_key": claim_key,
            "priority": priority,
            "status": status,
            "source_event_count": len(source_events),
            "source_event_refs": source_event_refs,
            "source_event_seqs": [source_event["seq"] for source_event in source_events],
            "source_event_hashes": [source_event["hash"] for source_event in source_events],
            "source_events": source_events,
            "authority_status": authority_status,
        },
    )
    actor = ExtractedEntity(name=event.actor, entity_type="actor", observed_at=event.timestamp)
    edge = ExtractedEdge(
        source=event.actor,
        target=reverify_id,
        relation_type="requested_reverification",
        valid_from=event.timestamp,
    )
    return ExtractionResult(entities=[request, actor], edges=[edge], source_event_seq=event.seq)


@register("reasoning.primitive.called")
def _extract_reasoning_primitive_called(event: Event) -> ExtractionResult:
    """Project an observable reasoning-loop primitive call as trace evidence."""
    primitive = _required_reasoning_text(event.payload.get("primitive"), field="primitive")
    phase = _required_reasoning_phase(event.payload.get("phase"))
    status = _optional_text(event.payload.get("status")) or "succeeded"
    result_count = _non_negative_int(event.payload.get("result_count"), default=0)
    evidence_count = _non_negative_int(event.payload.get("evidence_count"), default=0)
    citations = _string_list(event.payload.get("citations"))
    observation_id = f"reasoning:{primitive}:{event.seq}"
    observation = ExtractedEntity(
        name=observation_id,
        entity_type="reasoning_primitive_observation",
        observed_at=event.timestamp,
        summary=_optional_text(event.payload.get("query")),
        properties=_compact_properties(
            {
                "event_type": event.type,
                "primitive": primitive,
                "phase": phase,
                "status": status,
                "result_count": result_count,
                "evidence_count": evidence_count,
                "citations": citations,
                "authority_status": _CONSOLIDATION_AUTHORITY_STATUS,
            }
        ),
    )
    actor = ExtractedEntity(name=event.actor, entity_type="actor", observed_at=event.timestamp)
    edge = ExtractedEdge(
        source=event.actor,
        target=observation_id,
        relation_type="called_reasoning_primitive",
        valid_from=event.timestamp,
    )
    return ExtractionResult(entities=[observation, actor], edges=[edge], source_event_seq=event.seq)


@register("belief.update.proposed")
def _extract_belief_update_proposed(event: Event) -> ExtractionResult:
    """Project a review-pending belief proposal without granting authority."""
    claim = _required_reasoning_text(event.payload.get("claim"), field="claim")
    rationale = _required_reasoning_text(event.payload.get("rationale"), field="rationale")
    phase = _required_reasoning_phase(event.payload.get("phase"))
    confidence = _required_consolidation_confidence(event.payload.get("confidence"))
    source_events = _snapshot_consolidation_source_events(event.payload.get("source_events"))
    source_event_refs = [f"{source_event['seq']}:{source_event['hash']}" for source_event in source_events]
    source_event_seqs = [source_event["seq"] for source_event in source_events]
    source_event_hashes = [source_event["hash"] for source_event in source_events]
    authority_status = _required_consolidation_authority_status(event.payload.get("authority_status"))
    review_status = event.payload.get("review_status")
    if review_status != "pending":
        raise ValueError("review_status must be 'pending' for belief update proposals")
    proposal_id = f"belief:proposal:{event.seq}"
    proposal = ExtractedEntity(
        name=proposal_id,
        entity_type="belief_update_proposal",
        observed_at=event.timestamp,
        summary=claim,
        properties={
            "event_type": event.type,
            "claim": claim,
            "rationale": rationale,
            "phase": phase,
            "confidence": confidence,
            "source_event_count": len(source_events),
            "source_event_refs": source_event_refs,
            "source_event_seqs": source_event_seqs,
            "source_event_hashes": source_event_hashes,
            "authority_status": authority_status,
            "review_status": review_status,
        },
    )
    actor = ExtractedEntity(name=event.actor, entity_type="actor", observed_at=event.timestamp)
    edge = ExtractedEdge(
        source=event.actor,
        target=proposal_id,
        relation_type="proposed_belief_update",
        valid_from=event.timestamp,
    )
    return ExtractionResult(entities=[proposal, actor], edges=[edge], source_event_seq=event.seq)
