"""reflect() must return recall facts in a back-compatible envelope, never
call the harmony synthesis model, and never emit scaffolding tokens."""
import asyncio
import types

import pytest

import services.memory as memsvc


class _Session:
    device_code = "dev-1"
    agent_name = "test-agent"


class _VaultCtx:
    bank_id = "bank-1"
    actor_id = "user-1"
    team_id = None


@pytest.fixture
def stub_recall(monkeypatch):
    """Stub services.memory.recall to return two fact rows; fail if
    provider.reflect (the harmony model) is ever called."""
    facts = [
        {"id": "f1", "text": "Picked Kafka for the event store.",
         "type": "experience", "occurred_at": "2026-06-01T00:00:00Z",
         "document_id": "d1", "source": "personal", "score": 0.9},
        {"id": "f2", "text": "Earlier chose Postgres.",
         "type": "experience", "occurred_at": "2026-05-01T00:00:00Z",
         "document_id": "d2", "source": "personal", "score": 0.7},
    ]

    async def fake_recall(vault_ctx, session, **kwargs):
        return facts

    monkeypatch.setattr(memsvc, "recall", fake_recall)

    # Trip-wire: if reflect ever reaches the provider, fail loudly.
    def _boom(*a, **k):
        raise AssertionError("provider.reflect must not be called")

    prov = memsvc.get_memory_provider()
    monkeypatch.setattr(prov, "reflect", _boom, raising=False)
    # background loggers are fire-and-forget; stub to no-op
    monkeypatch.setattr(memsvc, "get_dashboard_store", lambda: types.SimpleNamespace(log_agent_event=lambda **k: None))
    monkeypatch.setattr(memsvc, "get_session_store", lambda: types.SimpleNamespace(update_last_active=lambda *a, **k: None))
    return facts


def test_reflect_returns_facts_envelope(stub_recall):
    out = asyncio.run(memsvc.reflect(
        vault_ctx=_VaultCtx(), session=_Session(), query="event store decision",
    ))
    # Back-compat envelope present
    assert set(out) >= {"answer", "confidence", "citations", "facts"}
    # facts are the raw recall rows
    assert [f["id"] for f in out["facts"]] == ["f1", "f2"]
    # citations carry fact ids
    assert {c["id"] for c in out["citations"]} == {"f1", "f2"}
    # answer is a plain-text digest, never scaffolding
    for marker in ("<|channel|>", "to=functions", "<|call|>", "<|start|>"):
        assert marker not in out["answer"]
    # confidence derived from count (2 facts -> medium)
    assert out["confidence"] == "medium"


def test_reflect_empty_recall_low_confidence(stub_recall, monkeypatch):
    async def empty_recall(vault_ctx, session, **kwargs):
        return []
    monkeypatch.setattr(memsvc, "recall", empty_recall)
    out = asyncio.run(memsvc.reflect(
        vault_ctx=_VaultCtx(), session=_Session(), query="nothing here",
    ))
    assert out["facts"] == []
    assert out["citations"] == []
    assert out["confidence"] == "low"
    assert out["answer"] == ""

async def reflect(
    vault_ctx: VaultContext,
    session: DeviceSession,
    *,
    query: str,
    budget: str = "mid",
    response_schema: dict[str, Any] | None = None,
    tags: list[str] | None = None,
) -> dict[str, Any]:
    """
    Return memory facts for the caller to synthesize, in a back-compatible
    envelope. As of the reflect-to-recall change (2026-06-18) this NO LONGER
    calls the provider's harmony synthesis model — that model intermittently
    leaked raw scaffolding tokens, and every consumer is an LLM that
    re-articulates anyway. We retrieve via the same path as ``recall`` and
    wrap the facts so existing ``answer``/``confidence``/``citations`` readers
    keep working.

    ``response_schema`` is accepted but ignored (deprecated): the downstream
    agent produces structured output itself.
    """
    # reflect is a READ — allowed even if write quota is reached.
    facts = await recall(
        vault_ctx=vault_ctx,
        session=session,
        query=query,
        budget=budget,
        tags=tags,
        # "what is true now" lean: reflect historically resolved contradictions,
        # so prefer conflict-resolved observations, same as the old behavior.
        types=["observation"],
    )

    # recall() may return an error dict on failure; pass it straight through.
    if isinstance(facts, dict):
        return facts

    citations: list[dict[str, Any]] = []
    digest_lines: list[str] = []
    for f in facts:
        fid = f.get("id")
        if fid:
            citations.append({
                "id":             fid,
                "type":           f.get("type"),
                "context":        f.get("context"),
                "occurred_start": f.get("occurred_at"),
                "occurred_end":   f.get("occurred_at"),
                "document_id":    f.get("document_id"),
            })
        text = (f.get("text") or "").strip()
        if text:
            digest_lines.append(f"- {text}")

    n = len(citations)
    confidence = "high" if n >= 5 else ("medium" if n >= 2 else "low")

    return {
        "answer": "\n".join(digest_lines),
        "confidence": confidence,
        "citations": citations,
        "facts": facts,
    }

source ~/miniconda3/etc/profile.d/conda.sh && conda activate xysq && cd backend && \
git add services/memory.py tests/skill/test_reflect_returns_facts.py && \
git commit -m "feat: reflect() returns recall facts, not harmony synthesis

Re-point services.memory.reflect at the recall retrieval path and wrap the
facts in a back-compatible answer/confidence/citations envelope plus a new
facts[] field. No harmony model in the path -> no scaffolding leak.
provider.reflect + the harmony guard are left in place, now unused.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

def test_rest_reflect_route_uses_service(monkeypatch):
    """The /reflect REST route must delegate to services.reflect (facts path),
    not provider.reflect (harmony)."""
    import api.routes.memories as memroute

    called = {}

    async def fake_service_reflect(**kwargs):
        called["service"] = True
        return {"answer": "", "confidence": "low", "citations": [], "facts": []}

    def boom_provider(*a, **k):
        raise AssertionError("route must not call provider.reflect")

    monkeypatch.setattr(memroute, "reflect", fake_service_reflect, raising=False)
    prov = memsvc.get_memory_provider()
    monkeypatch.setattr(prov, "reflect", boom_provider, raising=False)
    # the test only asserts wiring; see Step 3 for the import the route needs.
    assert hasattr(memroute, "reflect")

@router.post("/reflect")
async def reflect_memories(
    body: ReflectRequest,
    user: UserClaims = Depends(require_auth0_user),
) -> dict[str, Any]:
    """
    Return grounded memory facts for the caller to synthesize (or a team vault).

    Equivalent to the MCP ``memory_reflect`` tool. As of 2026-06-18 this returns
    facts plus a back-compatible answer/confidence/citations envelope — it does
    not run server-side synthesis. Pass ``team_id`` to scope to a team vault; the
    caller must be a member with at least 'ro' role.
    """
    from auth.deps import VaultContext
    from dependencies import get_session_store
    from services.memory import reflect

    if not body.query.strip():
        raise HTTPException(status_code=422, detail="query must not be empty.")

    vault_ctx = VaultContext(
        bank_id=user.user_id,
        actor_id=user.user_id,
        team_id=None,
        role="personal",
    )
    if body.team_id:
        from api.deps.agent_auth import resolve_team_vault
        vault_ctx = await resolve_team_vault(vault_ctx, body.team_id, min_role="ro")

    session = get_session_store().find_or_create_api_key_session(
        vault_ctx.actor_id, agent_name="dashboard", client_id=None
    )
    return await reflect(
        vault_ctx=vault_ctx,
        session=session,
        query=body.query,
        budget=body.budget,
        response_schema=body.response_schema,
        tags=None,
    )

source ~/miniconda3/etc/profile.d/conda.sh && conda activate xysq && cd backend && \
git add api/routes/memories.py tests/skill/test_reflect_returns_facts.py && \
git commit -m "fix: REST /reflect delegates to services.reflect (facts path)

The route called provider.reflect directly, bypassing the new facts path and
still hitting the harmony model. Route through services.reflect so it returns
the back-compatible facts envelope.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

        """
        Return memory facts relevant to a question, for you to synthesize.

        As of 2026-06-18 this returns the same kind of facts as memory_recall,
        wrapped in a convenience envelope — it does NOT pre-synthesize an answer.
        Read the ``facts`` list and write the answer yourself.

        Returns:
            facts:      List of memory rows (id, text, type, occurred_at,
                        document_id, source) — the ground truth to reason over.
            answer:     A plain-text digest of the facts (one bullet per fact).
                        Convenience only; prefer synthesizing from ``facts``.
            confidence: "high" | "medium" | "low" — based on how many facts matched.
            citations:  `{id, type, context, occurred_start, occurred_end,
                        document_id}` per fact. Pass `document_id` into
                        memory_get_document for the verbatim source.

        ``response_schema`` is accepted but ignored (deprecated): produce any
        structured output yourself.

        VAULT ROUTING:
        - Omit team_id → reads from YOUR PERSONAL vault.
        - Provide team_id → reads from THAT TEAM's vault (requires ro+).
        - 403 means not authorized; it does not reveal whether the team exists.

        Args:
            query:           Question to answer using stored memories.
            budget:          Retrieval depth: "low", "mid" (default), "high".
            response_schema: Deprecated, ignored.
            tags:            Optional tag filter, e.g. ``["memory_kind:decision"]``.
            team_id:         Optional team UUID. Reads team vault if provided.
        """

source ~/miniconda3/etc/profile.d/conda.sh && conda activate xysq && cd backend && \
git add tools/memory.py && \
git commit -m "docs: memory_reflect docstring reflects facts-not-synthesis behavior

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

## If reflect fails, fall back to recall
`memory_reflect` can return a malformed or empty result - an `answer` that is
empty, that is low `confidence` with no `citations`, or that contains raw model
scaffolding (e.g. text with `<|channel|>`, `to=functions`, `<|call|>`, or other
token markers instead of prose). Treat ANY of these as a failed reflect.
When reflect fails: do NOT present its output and do NOT invent an answer.
Re-run the same query with `memory_recall` (it returns raw facts reliably),
then synthesize the result yourself following the output contract below.
Recall is the dependable floor; reflect is an optimization on top of it.

cd xysq-skills && \
git add _shared/recall-recipe.md recap/claude-code/SKILL.md decisions/claude-code/SKILL.md blockers/claude-code/SKILL.md actionables/claude-code/SKILL.md prep/claude-code/SKILL.md && \
git commit -m "refactor(skills): drop harmony-fallback block — reflect returns facts now

The 'if reflect fails, fall back to recall' contract is obsolete: reflect is
recall-backed and cannot emit scaffolding. Removed from the shared recipe and
all 5 claude-code recall skills.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

## How to recall
Use `mcp__xysq__memory_reflect` with `tags: ["memory_kind:decision"]` and
`personal_only: true`.

- Query: the user's stated topic or "decisions and choices" for the window.
- Set `query_timestamp` to today's ISO date for relative windows; post-filter
  by `occurred_start` to stay inside the stated period.
- If the tag-filtered result is thin, fall back to untagged reflect with the
  same query and filter manually for decision-shaped content.

## Mission
You are surfacing decisions the user made. Be precise and literal: report the
choice and its stated rationale, nothing inferred. If a decision has no clear
rationale in the facts, present it as "rationale unknown" rather than inventing
one.

## How to recall
Use `mcp__xysq__memory_recall` with `tags: ["memory_kind:decision"]` and
`types: ["observation"]` (so a superseded decision resolves to the current one).

- Scope: default to the user's personal vault (`personal_only: true`). If the
  request names a team, pass that team's `team_id` instead; if it's genuinely
  ambiguous and permitted, omit `personal_only` to fan out across personal +
  recall-enabled teams and label each item by its `source`.
- Query: the user's stated topic or "decisions and choices" for the window.
- Set `query_timestamp` to today's ISO date for relative windows; post-filter
  by each row's `occurred_at` to stay inside the stated period.
- If the tag-filtered result is thin, re-run untagged recall with the same query
  and filter manually for decision-shaped content.

## How to recall
Use `mcp__xysq__memory_reflect` with `personal_only: true`.

- Default query: the user's stated topic or "recent activity" for the window.
- For "why" context, also reflect with `tags: ["memory_kind:decision"]`.
- For "what happened" detail, also reflect with `tags: ["memory_kind:event"]`.
- Set `query_timestamp` to today's ISO date and raise `budget` to over-fetch when
  a relative window ("this week", "yesterday") is given - then post-filter by
  `occurred_start` from results.

## Mission
You are a neutral narrator summarizing what happened in a period. Cover the
ground evenly; do not over-weight any single thread. Stay grounded in the facts.

## How to recall
Use `mcp__xysq__memory_recall` with `personal_only: true` by default.

- Scope: if the request names a team, pass that `team_id` instead of
  `personal_only`; if ambiguous and permitted, omit `personal_only` to fan out
  across personal + recall-enabled teams and label items by `source`.
- Default query: the user's stated topic or "recent activity" for the window.
- For "why" context, also recall with `tags: ["memory_kind:decision"]`.
- For "what happened" detail, also recall with `tags: ["memory_kind:event"]`.
- Set `query_timestamp` to today's ISO date and raise `budget` to over-fetch when
  a relative window ("this week", "yesterday") is given - then post-filter by
  each row's `occurred_at`.

## Mission
You are listing what is stuck. Be direct: for each item name exactly what or who
it is waiting on. Lean skeptical — only call something a blocker if the facts
show it cannot proceed, and drop anything the facts show was resolved.

## How to recall
Use `mcp__xysq__memory_recall` with `tags: ["memory_kind:blocker"]` and
`personal_only: true` by default.

- Scope: if the request names a team, pass that `team_id` instead of
  `personal_only`; if ambiguous and permitted, omit `personal_only` to fan out
  across personal + recall-enabled teams and label items by `source`.
- Query: the user's stated topic or "blocked items waiting on external dependency".
- Do NOT restrict by time window - a blocker may have been logged weeks ago and
  still be active.
- If a recalled memory signals the blocker was resolved (e.g., a follow-up note
  says "unblocked", "approved", "done"), do NOT list it as active.
- If the tag-filtered result is thin, re-run untagged recall with a query shaped
  around stuck/waiting/on-hold wording.

## Mission
You are surfacing the user's open, self-owned work — tasks they still need to
do. Forward-looking only; surface long-pending items prominently. Stay grounded.

## Mission
You are assembling context for an upcoming meeting or call. Pull broadly across
the topic regardless of age; favor recent but keep essential background. Neutral.

cd xysq-skills && \
git add recap/claude-code/SKILL.md decisions/claude-code/SKILL.md blockers/claude-code/SKILL.md actionables/claude-code/SKILL.md prep/claude-code/SKILL.md catalog.json && \
git commit -m "feat(skills): claude-code recall skills call recall + carry a mission

recap/decisions/blockers now call memory_recall (not reflect); all 5 get a
mission line (identity + disposition) ported from Hindsight's reflect recipe,
plus an explicit scope step (personal default, team-overridable). Versions bumped.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

cd xysq-skills && \
git add core/ catalog.json && \
git commit -m "docs(skills): core variants describe reflect as facts-not-synthesis

All 9 platform variants reworded via exact string replacements: reflect returns
facts (+ a digest) for the agent to synthesize, no longer 'a direct answer that
cites its sources'. 8 tool-call variants + the chatgpt REST variant.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"

        """Retrieve memory facts to synthesize from.

        As of xysq backend 2026-06-18 this returns facts plus a convenience
        digest in ``answer`` — it no longer runs server-side synthesis. Your
        agent should synthesize from the facts. ``response_schema`` is accepted
        but ignored (deprecated); produce structured output yourself.
        """

source ~/miniconda3/etc/profile.d/conda.sh && conda activate xysq && cd python_sdk && \
git add xysq/memory.py && \
git commit -m "docs(sdk): synthesize() returns facts+digest; response_schema deprecated

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>"