"""cortex/api/routes/memory — Memory CRUD endpoints.

Canonical paths for remember/retrieve (issue #297):
  POST /api/v1/memories/remember  ← preferred (was /remember/v2)
  POST /api/v1/memories/retrieve  ← preferred (was /retrieve/v2)
  POST /api/v1/memories/feedback  ← preferred (was /feedback)
  POST /api/v1/memories/retrieve/explain  ← preferred (was /retrieve/explain)

Deprecated paths (sunset 2026-06-01):
  POST /api/v1/remember      → /memories/remember
  POST /api/v1/retrieve      → /memories/retrieve
  POST /api/v1/remember/v2   → /memories/remember
  POST /api/v1/retrieve/v2   → /memories/retrieve
  POST /api/v1/feedback      → /memories/feedback
  POST /api/v1/retrieve/explain → /memories/retrieve/explain

Split into sub-modules for maintainability (issue #944):
  - helpers.py   — shared validation, shadow mode, constants
  - legacy.py    — deprecated v1 /remember and /retrieve
  - browse.py    — read-only browse, detail, categories, timeline, entities
  - manage.py    — delete, restore, patch
  - feedback.py  — feedback endpoints
  - retrieve.py  — retrieve, retrieve/explain (canonical + deprecated)
  - search.py    — semantic memory search
  - remember.py  — remember (canonical + deprecated v2)
  - review.py    — review queue: flag, approve, reject, bulk flag
"""

from __future__ import annotations

from fastapi import APIRouter

router = APIRouter()


def _make_routes(verify_api_key):
    """Register all memory routes with the given auth dependency.

    Delegates to sub-module _register() functions. Registration order matters
    for FastAPI path matching — static paths (e.g. /memories/categories) MUST
    be registered before parameterised paths (e.g. /memories/{memory_id}).
    """
    from cortex.api.routes.memory import (
        belief_history,
        browse,
        feedback,
        legacy,
        manage,
        remember,
        retrieve,
        review,
        search,
    )

    # Order matters! Static/prefixed paths MUST be registered before parameterised
    # paths (e.g. /memories/{memory_id}) so FastAPI matches them correctly.

    # 1. Deprecated v1 endpoints (POST /remember, POST /retrieve)
    legacy._register(router, verify_api_key)

    # 2. Belief history (MUST be before browse which registers {memory_id})
    #    /memories/belief-history and /memories/belief-history/entity would
    #    otherwise be matched as memory_id="belief-history" (#1280).
    belief_history._register(router, verify_api_key)

    # 3. Browse & detail (categories, browse, review-queue, timeline BEFORE {memory_id})
    browse._register(router, verify_api_key)

    # 4. CRUD write ops (DELETE, POST restore, PATCH on {memory_id})
    manage._register(router, verify_api_key)

    # 5. Feedback (canonical + deprecated)
    feedback._register(router, verify_api_key)

    # 6. Retrieve/explain (canonical + deprecated) — must come before /memories/retrieve
    #    because /memories/retrieve/explain is more specific
    retrieve._register(router, verify_api_key)

    # 7. Search
    search._register(router, verify_api_key)

    # 8. Remember (canonical + deprecated v2)
    remember._register(router, verify_api_key)

    # 9. Review queue (flag, approve, reject, bulk flag)
    review._register(router, verify_api_key)
