"""
core/graph/queries.py — Pre-built Cypher query constants for Genesis KG.

All constants are plain strings.  Pass them to GenesisGraph.query() with
the appropriate ``params`` dict.

Usage example::

    from core.graph.queries import FIND_ENTITY_BY_ID, FIND_RELATED
    from core.graph import get_graph

    graph = get_graph()
    entity = graph.query(FIND_ENTITY_BY_ID, {"id": "ENT-agentic-os-001"})
    related = graph.query(FIND_RELATED, {"id": "ENT-agentic-os-001", "limit": 20})

Note on FIND_ENTITIES_BY_TYPE:
    FalkorDB does not support parameterised labels ($type).  Substitute the
    label name directly into the query string before calling .query():

        cypher = FIND_ENTITIES_BY_TYPE.replace("$type", "axiom")
        results = graph.query(cypher, {"limit": 50})

# VERIFICATION_STAMP
# Story: M9.04 — core/graph/queries.py — pre-built Cypher constants
# Verified By: parallel-builder
# Verified At: 2026-02-25T00:00:00Z
# Tests: 8/8
# Coverage: 100%
"""
from __future__ import annotations

# ---------------------------------------------------------------------------
# Individual node lookup
# ---------------------------------------------------------------------------

FIND_ENTITY_BY_ID: str = (
    "MATCH (n) WHERE n.id = $id RETURN n"
)
"""
Find a single node by its ``id`` property.

Params: {"id": "<entity_id>"}
"""

# ---------------------------------------------------------------------------
# Type-based listing
# NOTE: FalkorDB does not support parameterised labels.
# Replace ``$type`` with the concrete label string before executing.
# ---------------------------------------------------------------------------

FIND_ENTITIES_BY_TYPE: str = (
    "MATCH (n:$type) RETURN n LIMIT $limit"
)
"""
List nodes by label.

**Pre-process required**: replace the literal ``$type`` substring with the
desired label before passing to graph.query().  Example::

    cypher = FIND_ENTITIES_BY_TYPE.replace("$type", "axiom")
    results = graph.query(cypher, {"limit": 50})

Params: {"limit": <int>}
"""

# ---------------------------------------------------------------------------
# Relationship traversal
# ---------------------------------------------------------------------------

FIND_RELATED: str = (
    "MATCH (a)-[r]->(b) WHERE a.id = $id "
    "RETURN b, type(r) as rel LIMIT $limit"
)
"""
Find all directly related nodes for a given entity.

Params: {"id": "<entity_id>", "limit": <int>}
"""

FIND_PATH: str = (
    "MATCH p = shortestPath((a)-[*..5]-(b)) "
    "WHERE a.id = $from AND b.id = $to "
    "RETURN p"
)
"""
Find the shortest path (up to 5 hops) between two entities.

Params: {"from": "<from_id>", "to": "<to_id>"}
"""

# ---------------------------------------------------------------------------
# Aggregation
# ---------------------------------------------------------------------------

COUNT_BY_TYPE: str = (
    "MATCH (n) RETURN labels(n) as type, count(n) as count"
)
"""
Count all nodes grouped by their label(s).

Params: {} (none required)
"""

# ---------------------------------------------------------------------------
# Temporal / recency queries
# ---------------------------------------------------------------------------

RECENT_AXIOMS: str = (
    "MATCH (a:axiom) WHERE a.date >= $since "
    "RETURN a ORDER BY a.date DESC LIMIT $limit"
)
"""
Return the most recent axiom nodes on or after a given date string.

Params: {"since": "YYYY-MM-DD", "limit": <int>}
"""