Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

37.7 KB
Raw Blame
"""MCP tool wrappers — call them directly with seeded data and a fake
CallContext (skipping HTTP/JWT, which is covered by test_agents_jwt.py).

Tools that depend on services Securo already tests heavily (reports,
dashboard) just check that the wrapper returns a serializable shape, not
the full numeric correctness of those services.
"""
import uuid

import pytest
import pytest_asyncio
from sqlalchemy.ext.asyncio import AsyncSession

# Importing this package registers all tools into mcp_server.registry.REGISTRY.
import mcp_server.tools  # noqa: F401
from mcp_server.auth import CallContext
from mcp_server.registry import REGISTRY


@pytest_asyncio.fixture
async def ctx(test_user) -> CallContext:
    return CallContext(user_id=test_user.id, conversation_id=uuid.uuid4())


# --- Registry shape --------------------------------------------------------

def test_registry_contains_v1_tools():
    """We promised these in the design — keep the contract."""
    expected = {
        "list_transactions",
        "list_accounts",
        "get_account_summary",
        "list_categories",
        "list_payees",
        "get_budget_vs_actual",
        "list_budgets",
        "get_net_worth",
        "get_income_expenses",
        "get_cash_flow",
        "get_dashboard_snapshot",
        "search_all",
        "aggregate",
        "propose_categorize",
        "propose_create_category",
        "propose_create_budget",
        "propose_create_payee_rule",
        "propose_create_transaction",
        "propose_create_recurring_transaction",
        "propose_update_recurring_transaction",
        "propose_cancel_recurring_transaction",
        "propose_create_goal",
        "search_knowledge_base",
        "list_recurring_transactions",
        "list_assets",
        "list_goals",
    }
    assert expected.issubset(set(REGISTRY.keys())), (
        f"missing: {expected - set(REGISTRY.keys())}"
    )


def test_proposal_tools_marked_is_proposal():
    for name in ("propose_categorize", "propose_create_category", "propose_create_budget", "propose_create_payee_rule"):
        spec = REGISTRY[name]
        assert spec.is_proposal, f"{name} should have is_proposal=True"


def test_each_tool_has_input_schema():
    for name, spec in REGISTRY.items():
        assert spec.parameters.get("type") == "object", f"{name} schema must be object"
        assert "properties" in spec.parameters


@pytest.mark.parametrize(
    "tool_name",
    [
        "propose_create_recurring_transaction",
        "propose_update_recurring_transaction",
    ],
    ids=["create", "update"],
)
def test_recurring_proposal_frequency_schema_includes_new_values(tool_name):
    advertised = set(
        REGISTRY[tool_name].parameters["properties"]["frequency"]["enum"]
    )
    assert {"biweekly", "semiannual"} <= advertised


# --- Read tools (with real seeded data) -----------------------------------

async def test_list_transactions_returns_seeded_data(
    session: AsyncSession, ctx: CallContext, test_transactions
):
    handler = REGISTRY["list_transactions"].handler
    result = await handler(session=session, ctx=ctx)
    assert isinstance(result, dict)
    assert "items" in result and "total" in result
    assert result["total"] >= len(test_transactions)
    sample = result["items"][0]
    for k in ("id", "date", "description", "amount", "currency"):
        assert k in sample


async def test_list_transactions_with_search_filter(
    session: AsyncSession, ctx: CallContext, test_transactions
):
    handler = REGISTRY["list_transactions"].handler
    result = await handler(session=session, ctx=ctx, search="UBER")
    assert all("UBER" in x["description"] for x in result["items"])


async def test_list_transactions_default_sort_is_purchase_date_desc(
    session: AsyncSession, ctx: CallContext, test_transactions
):
    """Regression: the default sort must be by purchase date desc so
    'what's my last transaction?' returns the most recent one.
    Previously we sorted by COALESCE(effective_bill_date, date), which
    floats credit-card transactions whose bill is due in the future to
    the top — pushing the actual latest transaction down."""
    handler = REGISTRY["list_transactions"].handler
    result = await handler(session=session, ctx=ctx, limit=5)
    items = result["items"]
    assert items, "fixture has transactions; default query must return them"
    # Each item's date >= the next item's date (desc).
    dates = [x["date"] for x in items if x["date"]]
    assert dates == sorted(dates, reverse=True), f"not sorted desc by purchase date: {dates}"
    assert result["sort_by"] == "transaction_date"


async def test_list_transactions_exposes_extra_fields(
    session: AsyncSession, ctx: CallContext, test_transactions, test_account, test_categories
):
    """Make sure the LLM gets enough context per row — names, not just
    ids — so it can answer "from which account?" without a second call."""
    handler = REGISTRY["list_transactions"].handler
    result = await handler(session=session, ctx=ctx, limit=5)
    sample = result["items"][0]
    for key in ("id", "date", "description", "amount", "currency", "type", "account_id", "account_name"):
        assert key in sample, f"missing key {key} in row"
    # account_name should resolve when category/account are seeded.
    assert any(x.get("account_name") == "Conta Corrente" for x in result["items"])


async def test_list_transactions_tx_type_filter(
    session: AsyncSession, ctx: CallContext, test_transactions
):
    handler = REGISTRY["list_transactions"].handler
    debits = await handler(session=session, ctx=ctx, tx_type="debit")
    credits = await handler(session=session, ctx=ctx, tx_type="credit")
    assert all(x["type"] == "debit" for x in debits["items"])
    assert all(x["type"] == "credit" for x in credits["items"])
    assert debits["total"] + credits["total"] >= len(debits["items"])  # sanity


async def test_list_transactions_currency_filter_matches_native(
    session: AsyncSession, ctx: CallContext, test_transactions
):
    """The Transaction.currency column defaults to USD in the fixture
    (independent of the account's BRL currency), so 'USD' should return
    everything and any narrower filter returns ≤ that count."""
    handler = REGISTRY["list_transactions"].handler
    usd = await handler(session=session, ctx=ctx, currency="USD")
    assert usd["total"] >= 1
    assert all(x["currency"] == "USD" for x in usd["items"])


async def test_list_transactions_currency_filter_returns_zero_for_unused(
    session: AsyncSession, ctx: CallContext, test_transactions
):
    """Regression for the 'do I have any EUR transactions?' bug — the
    answer should be a clean 0, not a 0 from text-searching 'EUR' in
    descriptions."""
    handler = REGISTRY["list_transactions"].handler
    eur = await handler(session=session, ctx=ctx, currency="EUR")
    assert eur["total"] == 0
    assert eur["items"] == []


async def test_list_transactions_currency_filter_is_case_insensitive(
    session: AsyncSession, ctx: CallContext, test_transactions
):
    handler = REGISTRY["list_transactions"].handler
    a = await handler(session=session, ctx=ctx, currency="usd")
    b = await handler(session=session, ctx=ctx, currency="USD")
    assert a["total"] == b["total"]


async def test_list_transactions_min_amount_filter(
    session: AsyncSession, ctx: CallContext, test_transactions
):
    handler = REGISTRY["list_transactions"].handler
    big = await handler(session=session, ctx=ctx, min_amount=100)
    # Fixture has transactions of 25.50, 45.00, 8000.00, 150.00, 39.90
    # Primary-currency stamping isn't computed in tests so this falls back
    # to native amount. Three rows >= 100: 8000, 150 (and zero with stamping
    # rules in our test setup we keep this lenient).
    assert big["total"] >= 1
    for it in big["items"]:
        # All returned amounts must be >= 100 (in their primary view).
        amt = it.get("amount_primary") or it.get("amount") or 0
        assert amt >= 100, f"row {it} slipped under min_amount"


async def test_list_transactions_max_amount_filter(
    session: AsyncSession, ctx: CallContext, test_transactions
):
    handler = REGISTRY["list_transactions"].handler
    small = await handler(session=session, ctx=ctx, max_amount=50)
    for it in small["items"]:
        amt = it.get("amount_primary") or it.get("amount") or 0
        assert amt <= 50


async def test_list_recurring_transactions_returns_empty_dict_with_no_data(
    session: AsyncSession, ctx: CallContext
):
    """When there are no recurring transactions the tool must still return
    a stable {items, total} shape, not raise."""
    handler = REGISTRY["list_recurring_transactions"].handler
    r = await handler(session=session, ctx=ctx)
    assert r == {"items": [], "total": 0}


async def test_list_assets_empty(session: AsyncSession, ctx: CallContext):
    handler = REGISTRY["list_assets"].handler
    r = await handler(session=session, ctx=ctx)
    assert r["total"] == 0


async def test_list_goals_empty(session: AsyncSession, ctx: CallContext):
    handler = REGISTRY["list_goals"].handler
    r = await handler(session=session, ctx=ctx)
    assert r["total"] == 0


async def test_list_budgets_empty(session: AsyncSession, ctx: CallContext):
    handler = REGISTRY["list_budgets"].handler
    r = await handler(session=session, ctx=ctx)
    assert r == {"items": [], "total": 0}


async def test_aggregate_payee_filter(
    session: AsyncSession, ctx: CallContext, test_transactions
):
    """The new payee_id filter on aggregate makes 'how much did I spend at X?'
    a single tool call instead of the agent's old 4-call dance."""
    handler = REGISTRY["aggregate"].handler
    r = await handler(session=session, ctx=ctx, payee_id=str(uuid.uuid4()))
    # Filtering by a non-existent payee returns no buckets — but the call
    # should still succeed (no error key).
    assert "error" not in r
    assert r["items"] == []


async def test_aggregate_currency_filter(
    session: AsyncSession, ctx: CallContext, test_transactions
):
    handler = REGISTRY["aggregate"].handler
    usd = await handler(session=session, ctx=ctx, currency="USD", group_by="category")
    assert "error" not in usd
    eur = await handler(session=session, ctx=ctx, currency="EUR", group_by="category")
    assert "error" not in eur and eur["items"] == []


async def test_list_transactions_account_types_filter(
    session: AsyncSession, ctx: CallContext, test_transactions, test_account
):
    """fixture's test_account is 'checking' — filtering on 'credit_card' returns nothing."""
    handler = REGISTRY["list_transactions"].handler
    cc = await handler(session=session, ctx=ctx, account_types=["credit_card"])
    assert cc["total"] == 0
    checking = await handler(session=session, ctx=ctx, account_types=["checking"])
    assert checking["total"] >= 1


async def test_list_accounts(session: AsyncSession, ctx: CallContext, test_account):
    handler = REGISTRY["list_accounts"].handler
    result = await handler(session=session, ctx=ctx)
    assert result["total"] >= 1
    found = next((a for a in result["items"] if a["id"] == str(test_account.id)), None)
    assert found is not None
    assert found["currency"] == "BRL"


async def test_get_account_summary(session: AsyncSession, ctx: CallContext, test_account, test_transactions):
    handler = REGISTRY["get_account_summary"].handler
    result = await handler(session=session, ctx=ctx, account_id=str(test_account.id))
    assert isinstance(result, dict)
    assert "error" not in result or result.get("error") is None
    assert set(result) == {
        "account_id",
        "current_balance",
        "opening_balance",
        "monthly_income",
        "monthly_expenses",
        "projected_income",
        "projected_expenses",
    }
    income = float(sum(t.amount for t in test_transactions if t.type == "credit"))
    expenses = float(sum(t.amount for t in test_transactions if t.type == "debit"))
    current_balance = float(test_account.balance)
    assert result["account_id"] == str(test_account.id)
    assert result["current_balance"] == pytest.approx(current_balance)
    assert result["opening_balance"] == pytest.approx(current_balance - (income - expenses))
    assert result["monthly_income"] == pytest.approx(income)
    assert result["monthly_expenses"] == pytest.approx(expenses)
    assert result["projected_income"] == pytest.approx(income)
    assert result["projected_expenses"] == pytest.approx(expenses)


async def test_get_account_summary_unknown_account(session: AsyncSession, ctx: CallContext):
    handler = REGISTRY["get_account_summary"].handler
    result = await handler(session=session, ctx=ctx, account_id=str(uuid.uuid4()))
    assert result.get("error") == "account not found"


async def test_list_categories(session: AsyncSession, ctx: CallContext, test_categories):
    handler = REGISTRY["list_categories"].handler
    result = await handler(session=session, ctx=ctx)
    names = {c["name"] for c in result["items"]}
    assert "Alimentação" in names
    # Check the IDs round-trip as strings (LLM consumes via JSON).
    for c in result["items"]:
        uuid.UUID(c["id"])  # raises if not a UUID


async def test_list_payees_empty(session: AsyncSession, ctx: CallContext):
    handler = REGISTRY["list_payees"].handler
    result = await handler(session=session, ctx=ctx)
    assert result["total"] == 0
    assert result["items"] == []


async def test_get_dashboard_snapshot(session: AsyncSession, ctx: CallContext, test_transactions):
    handler = REGISTRY["get_dashboard_snapshot"].handler
    result = await handler(session=session, ctx=ctx)
    assert isinstance(result, dict)
    # Snapshot is a Pydantic model dumped to dict — at minimum should be non-empty.
    assert result


# --- aggregate -------------------------------------------------------------

async def test_aggregate_by_category(
    session: AsyncSession, ctx: CallContext, test_transactions, test_categories
):
    handler = REGISTRY["aggregate"].handler
    result = await handler(
        session=session, ctx=ctx,
        metric="sum", group_by="category", tx_type="expense",
    )
    assert "items" in result
    # We have UBER (Transporte) and IFOOD (Alimentação) as expenses.
    labels = {item.get("label") for item in result["items"]}
    assert "Transporte" in labels or "Alimentação" in labels


async def test_aggregate_unknown_group_by(session: AsyncSession, ctx: CallContext):
    handler = REGISTRY["aggregate"].handler
    result = await handler(session=session, ctx=ctx, group_by="bogus")
    assert "error" in result


# --- search_all ------------------------------------------------------------

async def test_search_all(session: AsyncSession, ctx: CallContext, test_transactions):
    handler = REGISTRY["search_all"].handler
    result = await handler(session=session, ctx=ctx, query="UBER")
    assert result["total"] >= 1


# --- Proposal tools (no DB writes) ----------------------------------------

async def test_propose_categorize_returns_preview(
    session: AsyncSession, ctx: CallContext, test_transactions, test_categories
):
    handler = REGISTRY["propose_categorize"].handler
    target_cat = test_categories[0]  # Alimentação
    tx_ids = [str(t.id) for t in test_transactions[:2]]
    result = await handler(
        session=session, ctx=ctx,
        transaction_ids=tx_ids,
        category_id=str(target_cat.id),
    )
    assert result["kind"] == "categorize"
    assert result["target_category"]["id"] == str(target_cat.id)
    assert result["affected_count"] == 2
    assert "apply_endpoint" in result


async def test_propose_categorize_unknown_category(
    session: AsyncSession, ctx: CallContext, test_transactions
):
    handler = REGISTRY["propose_categorize"].handler
    result = await handler(
        session=session, ctx=ctx,
        transaction_ids=[str(test_transactions[0].id)],
        category_id=str(uuid.uuid4()),
    )
    assert result["error"] == "category not found"


async def test_propose_create_category_detects_collision(
    session: AsyncSession, ctx: CallContext, test_categories
):
    handler = REGISTRY["propose_create_category"].handler
    # Use the same name as an existing category — should flag collision.
    result = await handler(session=session, ctx=ctx, name=test_categories[0].name)
    assert result["kind"] == "create_category"
    assert result["name_collision"] is not None
    assert result["name_collision"]["name"] == test_categories[0].name


async def test_propose_create_category_no_collision(
    session: AsyncSession, ctx: CallContext, test_categories
):
    handler = REGISTRY["propose_create_category"].handler
    result = await handler(session=session, ctx=ctx, name="UniqueNewCategoryX9Z")
    assert result["name_collision"] is None
    assert result["proposed"]["name"] == "UniqueNewCategoryX9Z"


async def test_propose_create_budget(
    session: AsyncSession, ctx: CallContext, test_categories
):
    handler = REGISTRY["propose_create_budget"].handler
    result = await handler(
        session=session, ctx=ctx,
        category_id=str(test_categories[0].id),
        month="2026-05-15",
        amount=500.0,
        currency="BRL",
    )
    assert result["kind"] == "create_budget"
    assert result["proposed"]["amount"] == 500.0
    assert result["proposed"]["month"] == "2026-05-01"  # snapped to month start


async def test_propose_create_transaction_full(
    session: AsyncSession, ctx: CallContext, test_account, test_categories
):
    handler = REGISTRY["propose_create_transaction"].handler
    r = await handler(
        session=session, ctx=ctx,
        description="Almoço",
        amount=50.0,
        type="debit",
        account_id=str(test_account.id),
        category_id=str(test_categories[0].id),
    )
    assert r["kind"] == "create_transaction"
    p = r["proposed"]
    assert p["description"] == "Almoço"
    assert p["amount"] == 50.0
    assert p["type"] == "debit"
    assert p["account_id"] == str(test_account.id)
    assert p["category_name"] == test_categories[0].name
    assert p["currency"] == "BRL"  # inherited from account
    assert p["date"]  # default to today


async def test_propose_create_transaction_unknown_account(
    session: AsyncSession, ctx: CallContext
):
    handler = REGISTRY["propose_create_transaction"].handler
    r = await handler(
        session=session, ctx=ctx,
        description="x", amount=1.0, type="debit", account_id=str(uuid.uuid4()),
    )
    assert r["error"] == "account not found"


async def test_propose_create_recurring_monthly_requires_day(
    session: AsyncSession, ctx: CallContext, test_account
):
    handler = REGISTRY["propose_create_recurring_transaction"].handler
    r = await handler(
        session=session, ctx=ctx,
        description="Netflix", amount=55.0, type="debit",
        frequency="monthly", account_id=str(test_account.id),
    )
    assert "day_of_month" in r.get("error", "")


async def test_propose_create_recurring_semiannual_requires_day(
    session: AsyncSession, ctx: CallContext, test_account
):
    handler = REGISTRY["propose_create_recurring_transaction"].handler
    result = await handler(
        session=session,
        ctx=ctx,
        description="Insurance",
        amount=600.0,
        type="debit",
        frequency="semiannual",
        account_id=str(test_account.id),
    )
    assert "day_of_month" in result.get("error", "")


async def test_propose_create_recurring_monthly_full(
    session: AsyncSession, ctx: CallContext, test_account
):
    handler = REGISTRY["propose_create_recurring_transaction"].handler
    r = await handler(
        session=session, ctx=ctx,
        description="Netflix", amount=55.0, type="debit",
        frequency="monthly", day_of_month=10,
        weekend_adjustment="previous_friday",
        account_id=str(test_account.id),
    )
    assert r["kind"] == "create_recurring_transaction"
    assert r["proposed"]["day_of_month"] == 10
    assert r["proposed"]["frequency"] == "monthly"
    assert r["proposed"]["weekend_adjustment"] == "previous_friday"


async def test_propose_update_recurring_no_changes(
    session: AsyncSession, ctx: CallContext, test_user
):
    """If the LLM calls without any change fields, the tool should refuse
    with a clear error rather than build an empty 'changes' object."""
    from app.models.recurring_transaction import RecurringTransaction
    from decimal import Decimal
    from datetime import date

    rt = RecurringTransaction(
        id=uuid.uuid4(), user_id=test_user.id,
        description="Salary", amount=Decimal("4000"), currency="BRL",
        type="credit", frequency="monthly", day_of_month=1,
        start_date=date(2026, 1, 1), next_occurrence=date(2026, 5, 1), is_active=True,
    )
    session.add(rt)
    await session.commit()

    handler = REGISTRY["propose_update_recurring_transaction"].handler
    r = await handler(session=session, ctx=ctx, recurring_id=str(rt.id))
    assert r["error"] == "no changes provided"


async def test_propose_update_recurring_amount_change(
    session: AsyncSession, ctx: CallContext, test_user
):
    """'Update my salary to R$8,000' — change amount only, current values
    are echoed back so the user sees the diff."""
    from app.models.recurring_transaction import RecurringTransaction
    from decimal import Decimal
    from datetime import date

    rt = RecurringTransaction(
        id=uuid.uuid4(), user_id=test_user.id,
        description="Salary", amount=Decimal("4000"), currency="BRL",
        type="credit", frequency="monthly", day_of_month=1,
        start_date=date(2026, 1, 1), next_occurrence=date(2026, 5, 1), is_active=True,
    )
    session.add(rt)
    await session.commit()

    handler = REGISTRY["propose_update_recurring_transaction"].handler
    r = await handler(session=session, ctx=ctx, recurring_id=str(rt.id), amount=8000)
    assert r["kind"] == "update_recurring_transaction"
    assert r["target"]["amount"] == 4000.0  # current value visible
    assert r["changes"] == {"amount": 8000.0}


async def test_propose_cancel_recurring_default_mode_is_deactivate(
    session: AsyncSession, ctx: CallContext, test_user
):
    from app.models.recurring_transaction import RecurringTransaction
    from decimal import Decimal
    from datetime import date

    rt = RecurringTransaction(
        id=uuid.uuid4(), user_id=test_user.id,
        description="Spotify", amount=Decimal("23.90"), currency="BRL",
        type="debit", frequency="monthly", day_of_month=15,
        start_date=date(2026, 1, 1), next_occurrence=date(2026, 5, 15), is_active=True,
    )
    session.add(rt)
    await session.commit()

    handler = REGISTRY["propose_cancel_recurring_transaction"].handler
    r = await handler(session=session, ctx=ctx, recurring_id=str(rt.id))
    assert r["mode"] == "deactivate"
    assert r["target"]["description"] == "Spotify"


async def test_propose_create_goal(session: AsyncSession, ctx: CallContext):
    handler = REGISTRY["propose_create_goal"].handler
    r = await handler(
        session=session, ctx=ctx,
        name="Viagem para o Japão", target_amount=10000, deadline="2026-12-31",
    )
    assert r["kind"] == "create_goal"
    assert r["proposed"]["target_amount"] == 10000.0
    assert r["proposed"]["deadline"] == "2026-12-31"
    assert r["proposed"]["initial_amount"] == 0.0


async def test_propose_create_payee_rule_unknown_category(
    session: AsyncSession, ctx: CallContext
):
    handler = REGISTRY["propose_create_payee_rule"].handler
    result = await handler(
        session=session, ctx=ctx,
        match_pattern="UBER",
        category_id=str(uuid.uuid4()),
    )
    assert result["error"] == "category not found"


# --- search_knowledge_base ------------------------------------------------

async def test_search_knowledge_base_requires_agent_id(
    session: AsyncSession, test_user
):
    """Without agent_id in context, the tool refuses (covers a misconfigured caller)."""
    handler = REGISTRY["search_knowledge_base"].handler
    bare_ctx = CallContext(user_id=test_user.id)  # no agent_id
    result = await handler(session=session, ctx=bare_ctx, query="anything")
    assert "error" in result
    assert "agent_id" in result["error"]


# --- _can_apply gate -------------------------------------------------------
# Authorization-critical: writes must only happen when the caller is external
# AND set apply=True. Internal callers never write through propose_* tools.

def test_can_apply_truth_table(test_user):
    from mcp_server.tools.proposals import _can_apply

    internal = CallContext(user_id=test_user.id, external=False)
    external = CallContext(user_id=test_user.id, external=True)

    assert _can_apply(internal, apply=False) is False
    assert _can_apply(internal, apply=True) is False  # internal+apply still blocked
    assert _can_apply(external, apply=False) is False
    assert _can_apply(external, apply=True) is True


async def test_propose_categorize_internal_apply_does_not_write(
    session: AsyncSession, test_user, test_transactions, test_categories
):
    """Internal callers (Securo's own runtime) must never mutate, even if
    apply=True is somehow passed through."""
    from sqlalchemy import select
    from app.models.transaction import Transaction

    handler = REGISTRY["propose_categorize"].handler
    internal_ctx = CallContext(user_id=test_user.id, external=False)
    tx = test_transactions[3]  # uncategorized PIX RECEBIDO
    target = test_categories[0]
    assert tx.category_id is None

    result = await handler(
        session=session, ctx=internal_ctx,
        transaction_ids=[str(tx.id)],
        category_id=str(target.id),
        apply=True,
    )
    assert "applied" not in result  # preview only

    refreshed = (await session.execute(
        select(Transaction).where(Transaction.id == tx.id)
    )).scalar_one()
    assert refreshed.category_id is None


async def test_propose_categorize_external_no_apply_returns_preview(
    session: AsyncSession, test_user, test_transactions, test_categories
):
    """External caller without apply=True still gets a preview, no write."""
    from sqlalchemy import select
    from app.models.transaction import Transaction

    handler = REGISTRY["propose_categorize"].handler
    external_ctx = CallContext(user_id=test_user.id, external=True)
    tx = test_transactions[3]
    target = test_categories[0]

    result = await handler(
        session=session, ctx=external_ctx,
        transaction_ids=[str(tx.id)],
        category_id=str(target.id),
        apply=False,
    )
    assert "applied" not in result

    refreshed = (await session.execute(
        select(Transaction).where(Transaction.id == tx.id)
    )).scalar_one()
    assert refreshed.category_id is None


async def test_propose_categorize_external_apply_writes(
    session: AsyncSession, test_user, test_transactions, test_categories
):
    """External caller with apply=True commits the change."""
    from sqlalchemy import select
    from app.models.transaction import Transaction

    handler = REGISTRY["propose_categorize"].handler
    external_ctx = CallContext(user_id=test_user.id, external=True)
    tx = test_transactions[3]
    target = test_categories[0]

    result = await handler(
        session=session, ctx=external_ctx,
        transaction_ids=[str(tx.id)],
        category_id=str(target.id),
        apply=True,
    )
    assert result.get("applied") is True
    assert result.get("updated_count") == 1

    refreshed = (await session.execute(
        select(Transaction).where(Transaction.id == tx.id)
    )).scalar_one()
    assert refreshed.category_id == target.id


# --- Apply mode for the remaining propose_* tools --------------------------
# One happy-path test per tool to catch regressions in the per-service write
# wiring. The _can_apply gate is shared across all of them and is already
# exercised by test_can_apply_truth_table + the propose_categorize trio.

def test_every_propose_tool_advertises_apply_parameter():
    """Schema contract: every propose_* tool must expose `apply` in its
    JSON Schema so external clients can opt into write mode."""
    for name, spec in REGISTRY.items():
        if not name.startswith("propose_"):
            continue
        assert "apply" in spec.parameters["properties"], (
            f"{name} is missing the `apply` parameter"
        )
        assert spec.parameters["properties"]["apply"]["type"] == "boolean"
        assert spec.parameters["properties"]["apply"].get("default") is False


async def test_propose_create_category_external_apply_writes(
    session: AsyncSession, test_user
):
    from sqlalchemy import select
    from app.models.category import Category

    handler = REGISTRY["propose_create_category"].handler
    ctx = CallContext(user_id=test_user.id, external=True)

    result = await handler(
        session=session, ctx=ctx,
        name="Doações", icon="heart", color="#EF4444",
        apply=True,
    )
    assert result.get("applied") is True
    new_id = uuid.UUID(result["id"])

    row = (await session.execute(
        select(Category).where(Category.id == new_id, Category.user_id == test_user.id)
    )).scalar_one()
    assert row.name == "Doações"
    assert row.icon == "heart"


async def test_propose_create_category_external_apply_blocks_collision(
    session: AsyncSession, test_user, test_categories
):
    """When the name collides with an existing category, apply must NOT
    create a duplicate — the preview already flagged it."""
    from sqlalchemy import select, func
    from app.models.category import Category

    handler = REGISTRY["propose_create_category"].handler
    ctx = CallContext(user_id=test_user.id, external=True)
    existing = test_categories[0]

    before = (await session.execute(
        select(func.count()).select_from(Category).where(Category.user_id == test_user.id)
    )).scalar_one()

    result = await handler(
        session=session, ctx=ctx,
        name=existing.name,
        apply=True,
    )
    assert "applied" not in result
    assert "error" in result

    after = (await session.execute(
        select(func.count()).select_from(Category).where(Category.user_id == test_user.id)
    )).scalar_one()
    assert after == before


async def test_propose_create_budget_external_apply_writes(
    session: AsyncSession, test_user, test_categories
):
    from datetime import date
    from sqlalchemy import select
    from app.models.budget import Budget

    handler = REGISTRY["propose_create_budget"].handler
    ctx = CallContext(user_id=test_user.id, external=True)
    cat = test_categories[0]

    result = await handler(
        session=session, ctx=ctx,
        category_id=str(cat.id),
        month=date.today().replace(day=1).isoformat(),
        amount=500.0,
        apply=True,
    )
    assert result.get("applied") is True

    row = (await session.execute(
        select(Budget).where(Budget.id == uuid.UUID(result["id"]))
    )).scalar_one()
    assert row.category_id == cat.id
    assert float(row.amount) == 500.0


async def test_propose_create_transaction_external_apply_writes(
    session: AsyncSession, test_user, test_account, test_categories
):
    from sqlalchemy import select
    from app.models.transaction import Transaction

    handler = REGISTRY["propose_create_transaction"].handler
    ctx = CallContext(user_id=test_user.id, external=True)

    result = await handler(
        session=session, ctx=ctx,
        description="Sushi delivery",
        amount=78.50,
        type="debit",
        account_id=str(test_account.id),
        category_id=str(test_categories[0].id),
        apply=True,
    )
    assert result.get("applied") is True

    row = (await session.execute(
        select(Transaction).where(Transaction.id == uuid.UUID(result["id"]))
    )).scalar_one()
    assert row.description == "Sushi delivery"
    assert float(row.amount) == 78.50
    assert row.account_id == test_account.id


async def test_propose_create_recurring_transaction_external_apply_writes(
    session: AsyncSession, test_user, test_account
):
    from sqlalchemy import select
    from app.models.recurring_transaction import RecurringTransaction

    handler = REGISTRY["propose_create_recurring_transaction"].handler
    ctx = CallContext(user_id=test_user.id, external=True)

    result = await handler(
        session=session, ctx=ctx,
        description="Netflix",
        amount=55.90,
        type="debit",
        frequency="monthly",
        day_of_month=10,
        account_id=str(test_account.id),
        weekend_adjustment="next_monday",
        apply=True,
    )
    assert result.get("applied") is True

    row = (await session.execute(
        select(RecurringTransaction).where(
            RecurringTransaction.id == uuid.UUID(result["id"])
        )
    )).scalar_one()
    assert row.description == "Netflix"
    assert row.frequency == "monthly"
    assert row.day_of_month == 10
    assert row.weekend_adjustment == "next_monday"


async def test_propose_update_recurring_transaction_external_apply_writes(
    session: AsyncSession, test_user, test_account
):
    """Seed a recurring tx directly, then drive an update via apply=True."""
    from datetime import date
    from decimal import Decimal
    from app.models.recurring_transaction import RecurringTransaction

    rt = RecurringTransaction(
        id=uuid.uuid4(),
        user_id=test_user.id,
        account_id=test_account.id,
        description="Spotify",
        amount=Decimal("21.90"),
        currency="BRL",
        type="debit",
        frequency="monthly",
        day_of_month=15,
        start_date=date.today(),
        next_occurrence=date.today(),
        is_active=True,
    )
    session.add(rt)
    await session.commit()

    handler = REGISTRY["propose_update_recurring_transaction"].handler
    ctx = CallContext(user_id=test_user.id, external=True)

    result = await handler(
        session=session, ctx=ctx,
        recurring_id=str(rt.id),
        amount=27.90,
        weekend_adjustment="previous_friday",
        apply=True,
    )
    assert result.get("applied") is True

    await session.refresh(rt)
    assert float(rt.amount) == 27.90
    assert rt.weekend_adjustment == "previous_friday"


async def test_propose_cancel_recurring_transaction_deactivate_apply(
    session: AsyncSession, test_user, test_account
):
    """The default (and recommended) cancel mode flips is_active to False
    rather than deleting the row."""
    from datetime import date
    from decimal import Decimal
    from app.models.recurring_transaction import RecurringTransaction

    rt = RecurringTransaction(
        id=uuid.uuid4(),
        user_id=test_user.id,
        account_id=test_account.id,
        description="Old subscription",
        amount=Decimal("10.00"),
        currency="BRL",
        type="debit",
        frequency="monthly",
        day_of_month=1,
        start_date=date.today(),
        next_occurrence=date.today(),
        is_active=True,
    )
    session.add(rt)
    await session.commit()

    handler = REGISTRY["propose_cancel_recurring_transaction"].handler
    ctx = CallContext(user_id=test_user.id, external=True)

    result = await handler(
        session=session, ctx=ctx,
        recurring_id=str(rt.id),
        mode="deactivate",
        apply=True,
    )
    assert result.get("applied") is True
    assert result.get("is_active") is False

    await session.refresh(rt)
    assert rt.is_active is False


async def test_propose_cancel_recurring_transaction_delete_apply(
    session: AsyncSession, test_user, test_account
):
    """The 'delete' mode removes the row entirely."""
    from datetime import date
    from decimal import Decimal
    from sqlalchemy import select
    from app.models.recurring_transaction import RecurringTransaction

    rt = RecurringTransaction(
        id=uuid.uuid4(),
        user_id=test_user.id,
        account_id=test_account.id,
        description="Throwaway",
        amount=Decimal("5.00"),
        currency="BRL",
        type="debit",
        frequency="monthly",
        day_of_month=1,
        start_date=date.today(),
        next_occurrence=date.today(),
        is_active=True,
    )
    session.add(rt)
    await session.commit()
    rt_id = rt.id

    handler = REGISTRY["propose_cancel_recurring_transaction"].handler
    ctx = CallContext(user_id=test_user.id, external=True)

    result = await handler(
        session=session, ctx=ctx,
        recurring_id=str(rt_id),
        mode="delete",
        apply=True,
    )
    assert result.get("applied") is True
    assert result.get("deleted") is True

    gone = (await session.execute(
        select(RecurringTransaction).where(RecurringTransaction.id == rt_id)
    )).scalar_one_or_none()
    assert gone is None


async def test_propose_create_goal_external_apply_writes(
    session: AsyncSession, test_user
):
    from sqlalchemy import select
    from app.models.goal import Goal

    handler = REGISTRY["propose_create_goal"].handler
    ctx = CallContext(user_id=test_user.id, external=True)

    result = await handler(
        session=session, ctx=ctx,
        name="Travel fund",
        target_amount=10000.0,
        currency="BRL",
        apply=True,
    )
    assert result.get("applied") is True

    row = (await session.execute(
        select(Goal).where(Goal.id == uuid.UUID(result["id"]))
    )).scalar_one()
    assert row.name == "Travel fund"
    assert float(row.target_amount) == 10000.0


async def test_propose_create_payee_rule_external_apply_writes(
    session: AsyncSession, test_user, test_categories
):
    """The rule wrapper translates (match_pattern, category_id) into the
    conditions/actions shape RuleCreate expects."""
    from sqlalchemy import select
    from app.models.rule import Rule

    handler = REGISTRY["propose_create_payee_rule"].handler
    ctx = CallContext(user_id=test_user.id, external=True)
    cat = test_categories[0]

    result = await handler(
        session=session, ctx=ctx,
        match_pattern="UBER",
        category_id=str(cat.id),
        apply=True,
    )
    assert result.get("applied") is True

    row = (await session.execute(
        select(Rule).where(Rule.id == uuid.UUID(result["id"]))
    )).scalar_one()
    assert any(c.get("value") == "UBER" for c in row.conditions)
    assert any(a.get("value") == str(cat.id) for a in row.actions)