Initial curated RAGcore source from c16667f0c9397e2bfc8dd0255b114fba23c8d05e

tests/contract/sdk/python/conftest.py

@@ -0,0 +1,399 @@
+"""Fixture FastAPI apps for the SDK contract tests.
+
+Mirrors the same fixture-construction pattern used by the existing
+`tests/contract/api/{search,context,answers}` contract tests (real
+`RetrievalAuthorizationService`, a fixture executor/generator standing in
+only for the retrieval backend/model provider) -- these tests exist to
+prove the SDK's HTTP layer (request shape, response typing, SSE parsing,
+Problem Details mapping, retries), not to re-prove authorization/retrieval
+business logic that is already covered there.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import re
+import socket
+import sys
+import threading
+import time
+from collections.abc import Iterator
+from dataclasses import dataclass, replace
+from datetime import UTC, datetime
+from typing import Any
+from uuid import UUID, uuid4
+
+import uvicorn
+from fastapi import FastAPI
+
+from ragcore.api.v1.answers.dependencies import get_answer_application, get_answer_principal
+from ragcore.api.v1.answers.service import AnswerService
+from ragcore.api.v1.context.dependencies import get_context_application, get_context_principal
+from ragcore.api.v1.context.service import (
+    ContextExecutionRequest,
+    ContextExecutionResult,
+    ContextService,
+)
+from ragcore.api.v1.search.dependencies import get_search_application, get_search_principal
+from ragcore.api.v1.search.service import SearchHit, SearchQuery, SearchService
+from ragcore.application.retrieval.authorization import RetrievalAuthorizationService
+from ragcore.domain.authorization import Principal, PrincipalType
+from ragcore.domain.citations import Citation
+from ragcore.domain.control import Application, Role, Workspace
+from ragcore.main import create_app
+from ragcore.retrieval.context import ContextCandidate
+from ragcore.retrieval.ranking import FusedCandidate
+from ragcore.retrieval.search.models import Candidate, CandidateBackendKind, CandidateProvenance
+
+EVIDENCE_EXCERPT = "The refund window is thirty days from the original purchase date."
+
+
+class _FixtureInputs:
+    def __init__(self, workspace: Workspace, space_id: UUID, space_name: str) -> None:
+        self.workspace = workspace
+        self.space_id = space_id
+        self.space_name = space_name
+
+    async def load(self, principal: Principal) -> Any:
+        space = self.workspace.create_knowledge_space(
+            id=self.space_id, name=self.space_name, slug=self.space_name.lower().replace(" ", "-")
+        )
+        return type(
+            "Inputs",
+            (),
+            {
+                "spaces": (space,),
+                "grants": (),
+                "user_grants": (
+                    self.workspace.grant_user(
+                        id=uuid4(), user_id=principal.id, knowledge_space=space, role=Role.EDITOR
+                    ),
+                ),
+                "application": Application(
+                    id=uuid4(),
+                    workspace_id=self.workspace.id,
+                    name=f"{self.space_name} application",
+                    default_knowledge_space_ids=frozenset({self.space_id}),
+                ),
+            },
+        )()
+
+
+@dataclass
+class SearchFixture:
+    app: FastAPI
+    principal: Principal
+    space_id: UUID
+    calls: list[SearchQuery]
+
+
+def build_search_app() -> SearchFixture:
+    workspace = Workspace(uuid4(), "SDK search workspace", "sdk-search-workspace")
+    space_id = uuid4()
+    principal = Principal(uuid4(), workspace.id, PrincipalType.HUMAN, frozenset({Role.VIEWER}))
+    document_id, version_id, chunk_id = uuid4(), uuid4(), uuid4()
+    citation = Citation.create(
+        workspace_id=workspace.id,
+        space_id=space_id,
+        document_id=document_id,
+        document_version_id=version_id,
+        chunk_id=chunk_id,
+        parent_chunk_id=None,
+        location={"page_start": 4, "page_end": 4, "section": "Refunds"},
+        excerpt=EVIDENCE_EXCERPT,
+        source_uri="https://example.test/policy.md",
+        acquired_at=datetime(2026, 8, 1, 12, tzinfo=UTC),
+        retrieval_run_id=uuid4(),
+        index_alias="rag_dense_hybrid_active",
+        profile_version="hybrid-v1",
+    )
+    candidate = Candidate(
+        point_id=uuid4(),
+        score=0.87,
+        rank=1,
+        backend=CandidateBackendKind.DENSE,
+        provenance=CandidateProvenance(
+            workspace_id=workspace.id,
+            space_id=space_id,
+            document_id=document_id,
+            document_version_id=version_id,
+            chunk_id=chunk_id,
+            source_id=uuid4(),
+            parent_chunk_id=None,
+            status="published",
+            content_type="text/markdown",
+            language="en",
+            trust_level="trusted_internal",
+        ),
+    )
+    hit = SearchHit(
+        fused=FusedCandidate(candidate, 1 / 61, 1, None),
+        text=EVIDENCE_EXCERPT,
+        title="Refund policy",
+        citation=citation,
+        dense_score=0.87,
+    )
+    calls: list[SearchQuery] = []
+
+    class _Executor:
+        async def execute(self, request: Any) -> Any:
+            refreshed = replace(
+                hit,
+                citation=Citation.create(
+                    workspace_id=hit.citation.workspace_id,
+                    space_id=hit.citation.space_id,
+                    document_id=hit.citation.document_id,
+                    document_version_id=hit.citation.document_version_id,
+                    chunk_id=hit.citation.chunk_id,
+                    parent_chunk_id=hit.citation.parent_chunk_id,
+                    location=hit.citation.location,
+                    excerpt=hit.citation.excerpt,
+                    source_uri=hit.citation.source_uri,
+                    acquired_at=hit.citation.acquired_at,
+                    retrieval_run_id=request.retrieval_run_id,
+                    index_alias=hit.citation.index_alias,
+                    profile_version=hit.citation.profile_version,
+                ),
+            )
+            return type(
+                "Result",
+                (),
+                {
+                    "hits": (refreshed,),
+                    "degraded": False,
+                    "degradation_codes": (),
+                    "timings_ms": {},
+                },
+            )()
+
+    application = Application(
+        id=uuid4(),
+        workspace_id=workspace.id,
+        name="SDK search application",
+        default_knowledge_space_ids=frozenset({space_id}),
+    )
+
+    class _Inputs(_FixtureInputs):
+        async def load(self, principal: Principal) -> Any:
+            base = await super().load(principal)
+            return type(
+                "Inputs",
+                (),
+                {
+                    "spaces": base.spaces,
+                    "grants": base.grants,
+                    "user_grants": base.user_grants,
+                    "application": application,
+                },
+            )()
+
+    service = SearchService(
+        authorization=RetrievalAuthorizationService(),
+        inputs=_Inputs(workspace, space_id, "SDK search space"),
+        executor=_Executor(),
+    )
+    app = create_app()
+    app.dependency_overrides[get_search_principal] = lambda: principal
+    app.dependency_overrides[get_search_application] = lambda: service
+    return SearchFixture(app=app, principal=principal, space_id=space_id, calls=calls)
+
+
+@dataclass
+class ContextFixture:
+    app: FastAPI
+    principal: Principal
+    space_id: UUID
+
+
+def build_context_app() -> ContextFixture:
+    workspace = Workspace(uuid4(), "SDK context workspace", "sdk-context-workspace")
+    space_id = uuid4()
+    principal = Principal(uuid4(), workspace.id, PrincipalType.HUMAN, frozenset({Role.EDITOR}))
+    citation = Citation.create(
+        workspace_id=workspace.id,
+        space_id=space_id,
+        document_id=uuid4(),
+        document_version_id=uuid4(),
+        chunk_id=uuid4(),
+        parent_chunk_id=None,
+        location={"page_start": 1},
+        excerpt=EVIDENCE_EXCERPT,
+        source_uri="https://example.test/context.md",
+        acquired_at=datetime(2026, 8, 1, 12, tzinfo=UTC),
+        retrieval_run_id=uuid4(),
+        index_alias="rag_dense_hybrid_active",
+        profile_version="hybrid-v1",
+    )
+    candidate = ContextCandidate(citation, EVIDENCE_EXCERPT, 1, 1.0)
+
+    class _Executor:
+        async def execute(self, request: ContextExecutionRequest) -> ContextExecutionResult:
+            refreshed = Citation.create(
+                workspace_id=citation.workspace_id,
+                space_id=citation.space_id,
+                document_id=citation.document_id,
+                document_version_id=citation.document_version_id,
+                chunk_id=citation.chunk_id,
+                parent_chunk_id=citation.parent_chunk_id,
+                location=citation.location,
+                excerpt=citation.excerpt,
+                source_uri=citation.source_uri,
+                acquired_at=citation.acquired_at,
+                retrieval_run_id=request.retrieval_run_id,
+                index_alias=citation.index_alias,
+                profile_version=citation.profile_version,
+            )
+            return ContextExecutionResult(candidates=(replace(candidate, citation=refreshed),))
+
+    service = ContextService(
+        authorization=RetrievalAuthorizationService(),
+        inputs=_FixtureInputs(workspace, space_id, "SDK context space"),
+        executor=_Executor(),
+    )
+    app = create_app()
+    app.dependency_overrides[get_context_principal] = lambda: principal
+    app.dependency_overrides[get_context_application] = lambda: service
+    return ContextFixture(app=app, principal=principal, space_id=space_id)
+
+
+_CITATION_ID = re.compile(r"citation_ids=([0-9a-fA-F-]{36})")
+
+
+@dataclass
+class AnswerFixture:
+    app: FastAPI
+    principal: Principal
+    space_id: UUID
+
+
+def build_answer_app(*, generator_responses: list[str | None] | None = None) -> AnswerFixture:
+    workspace = Workspace(uuid4(), "SDK answers workspace", "sdk-answers-workspace")
+    space_id = uuid4()
+    principal = Principal(uuid4(), workspace.id, PrincipalType.HUMAN, frozenset({Role.EDITOR}))
+    citation = Citation.create(
+        workspace_id=workspace.id,
+        space_id=space_id,
+        document_id=uuid4(),
+        document_version_id=uuid4(),
+        chunk_id=uuid4(),
+        parent_chunk_id=None,
+        location={"page_start": 1},
+        excerpt=EVIDENCE_EXCERPT,
+        source_uri="https://example.test/answers.md",
+        acquired_at=datetime(2026, 8, 1, 12, tzinfo=UTC),
+        retrieval_run_id=uuid4(),
+        index_alias="rag_dense_hybrid_active",
+        profile_version="hybrid-v1",
+    )
+    candidate = ContextCandidate(citation, EVIDENCE_EXCERPT, 1, 1.0)
+
+    class _ContextExecutor:
+        async def execute(self, request: ContextExecutionRequest) -> ContextExecutionResult:
+            refreshed = Citation.create(
+                workspace_id=citation.workspace_id,
+                space_id=citation.space_id,
+                document_id=citation.document_id,
+                document_version_id=citation.document_version_id,
+                chunk_id=citation.chunk_id,
+                parent_chunk_id=citation.parent_chunk_id,
+                location=citation.location,
+                excerpt=citation.excerpt,
+                source_uri=citation.source_uri,
+                acquired_at=citation.acquired_at,
+                retrieval_run_id=request.retrieval_run_id,
+                index_alias=citation.index_alias,
+                profile_version=citation.profile_version,
+            )
+            return ContextExecutionResult(candidates=(replace(candidate, citation=refreshed),))
+
+    responses = list(generator_responses if generator_responses is not None else [None])
+
+    class _Generator:
+        async def generate(self, *, prompt: str, generation_profile: str, spaces: Any) -> str:
+            response = responses.pop(0) if responses else None
+            if response is not None:
+                return response
+            match = _CITATION_ID.search(prompt)
+            assert match is not None
+            return json.dumps(
+                {
+                    "status": "answerable",
+                    "answer": "The refund window is thirty days from purchase.",
+                    "citations": [match.group(1)],
+                }
+            )
+
+    service = AnswerService(
+        authorization=RetrievalAuthorizationService(),
+        inputs=_FixtureInputs(workspace, space_id, "SDK answers space"),
+        context_executor=_ContextExecutor(),
+        generator=_Generator(),
+    )
+    app = create_app()
+    app.dependency_overrides[get_answer_principal] = lambda: principal
+    app.dependency_overrides[get_answer_application] = lambda: service
+    return AnswerFixture(app=app, principal=principal, space_id=space_id)
+
+
+def _serve_forever(server: uvicorn.Server, sock: socket.socket) -> None:
+    # Deliberately not `server.run()`: that wraps `server.serve()` in
+    # `asyncio.run(..., loop_factory=...)`, and uvicorn's own loop factory
+    # (`uvicorn.loops.asyncio.asyncio_loop_factory`) hardcodes
+    # `asyncio.ProactorEventLoop` on Windows -- which the real app's
+    # lifespan (an async psycopg connection) refuses to run under, no
+    # matter what global event-loop policy is set beforehand. Driving the
+    # loop directly sidesteps uvicorn's own hardcoded choice.
+    loop = asyncio.SelectorEventLoop() if sys.platform == "win32" else asyncio.new_event_loop()
+    asyncio.set_event_loop(loop)
+    try:
+        loop.run_until_complete(server.serve(sockets=[sock]))
+    finally:
+        loop.close()
+
+
+@contextlib.contextmanager
+def run_app(app: FastAPI) -> Iterator[str]:
+    """Serve `app` over a real local TCP socket for the duration of the block.
+
+    `RAGCoreClient` (sync) needs this rather than `httpx.ASGITransport`:
+    ASGITransport only implements httpx's *async* transport interface, so a
+    sync `httpx.Client` can't use it at all (`AsyncRAGCoreClient` tests use
+    ASGITransport directly instead, which is the supported combination).
+    """
+    # Hand uvicorn the already-bound socket itself, rather than closing it
+    # and passing the port number for uvicorn to rebind: closing and
+    # rebinding is a real race (another process, or even this same
+    # process's next bind, can win the port first), which is what
+    # produced Windows `STARTUP_FAILURE`s here in practice.
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+    sock.bind(("127.0.0.1", 0))
+    sock.listen(128)
+    port = sock.getsockname()[1]
+    config = uvicorn.Config(app, log_level="warning")
+    server = uvicorn.Server(config)
+    thread = threading.Thread(target=_serve_forever, args=(server, sock), daemon=True)
+    thread.start()
+    deadline = time.monotonic() + 10
+    while not server.started and time.monotonic() < deadline:
+        time.sleep(0.01)
+    try:
+        yield f"http://127.0.0.1:{port}"
+    finally:
+        server.should_exit = True
+        thread.join(timeout=10)
+        with contextlib.suppress(OSError):
+            sock.close()
+
+
+__all__ = [
+    "AnswerFixture",
+    "ContextFixture",
+    "SearchFixture",
+    "build_answer_app",
+    "build_context_app",
+    "build_search_app",
+    "run_app",
+]

tests/contract/sdk/python/test_answers.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from ragcore_sdk import AnswerStreamEventType, RAGCoreClient
+
+from conftest import build_answer_app, run_app
+
+
+@contextmanager
+def _client(app: object) -> Iterator[RAGCoreClient]:
+    with run_app(app) as base_url, RAGCoreClient(base_url=base_url, token="sdk-test-token") as client:  # type: ignore[arg-type]  # noqa: E501
+        yield client
+
+
+def test_answer_sync_returns_typed_response() -> None:
+    fixture = build_answer_app()
+    with _client(fixture.app) as client:
+        response = client.answer(query="refund window", requested_space_ids=[fixture.space_id])
+
+    assert response.answer
+    assert response.citations
+    assert all(claim.citation_ids for claim in response.claims)
+
+
+def test_answer_stream_emits_metadata_then_done_in_order() -> None:
+    fixture = build_answer_app()
+    with _client(fixture.app) as client:
+        events = list(
+            client.answer_stream(query="refund window", requested_space_ids=[fixture.space_id])
+        )
+
+    assert [event.type for event in events] == [
+        AnswerStreamEventType.RETRIEVAL_METADATA,
+        AnswerStreamEventType.DONE,
+    ]
+    done_answer = events[1].as_done_answer()
+    assert done_answer is not None
+    assert done_answer.citations
+    assert "refund" in done_answer.answer.lower()
+    assert events[0].as_done_answer() is None
+
+
+def test_answer_stream_reports_terminal_error_event_on_invalid_generation() -> None:
+    fixture = build_answer_app(generator_responses=["not json", "still not json"])
+    with _client(fixture.app) as client:
+        events = list(
+            client.answer_stream(query="refund window", requested_space_ids=[fixture.space_id])
+        )
+
+    assert [event.type for event in events] == [
+        AnswerStreamEventType.RETRIEVAL_METADATA,
+        AnswerStreamEventType.ERROR,
+    ]
+    assert events[1].data["code"] == "validation_retries_exhausted"

tests/contract/sdk/python/test_async_client.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import httpx
+from ragcore_sdk import AnswerStreamEventType, AsyncRAGCoreClient
+
+from conftest import build_answer_app, build_search_app
+
+
+def _async_client(app: object) -> AsyncRAGCoreClient:
+    return AsyncRAGCoreClient(
+        base_url="http://testserver",
+        token="sdk-test-token",
+        transport=httpx.ASGITransport(app=app),  # type: ignore[arg-type]
+    )
+
+
+async def test_async_search_returns_typed_results() -> None:
+    fixture = build_search_app()
+    async with _async_client(fixture.app) as client:
+        response = await client.search(query="refund", requested_space_ids=[fixture.space_id])
+
+    assert response.results[0].citation.excerpt_sha256
+
+
+async def test_async_answer_stream_emits_metadata_then_done() -> None:
+    fixture = build_answer_app()
+    async with _async_client(fixture.app) as client:
+        events = [
+            event
+            async for event in client.answer_stream(
+                query="refund window", requested_space_ids=[fixture.space_id]
+            )
+        ]
+
+    assert [event.type for event in events] == [
+        AnswerStreamEventType.RETRIEVAL_METADATA,
+        AnswerStreamEventType.DONE,
+    ]
+    assert events[1].as_done_answer() is not None

tests/contract/sdk/python/test_context.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+import pytest
+from ragcore_sdk import RAGCoreAPIError, RAGCoreClient
+
+from conftest import build_context_app, run_app
+
+
+@contextmanager
+def _client(app: object) -> Iterator[RAGCoreClient]:
+    with run_app(app) as base_url, RAGCoreClient(base_url=base_url, token="sdk-test-token") as client:  # type: ignore[arg-type]  # noqa: E501
+        yield client
+
+
+def test_context_returns_typed_blocks_and_citations() -> None:
+    fixture = build_context_app()
+    with _client(fixture.app) as client:
+        response = client.context(query="refund", requested_space_ids=[fixture.space_id])
+
+    assert response.answerability.value in {
+        "answerable",
+        "partially_answerable",
+        "not_answerable",
+        "conflicting_evidence",
+    }
+    assert response.token_count >= 0
+    if response.blocks:
+        assert response.blocks[0].citation_ids
+        assert response.citations
+
+
+def test_context_token_budget_below_minimum_raises_typed_problem() -> None:
+    fixture = build_context_app()
+    with _client(fixture.app) as client, pytest.raises(RAGCoreAPIError) as excinfo:
+        client.context(
+            query="refund",
+            requested_space_ids=[fixture.space_id],
+            max_context_tokens=1,
+        )
+
+    problem = excinfo.value.problem
+    assert problem.status == 422
+    assert problem.code == "VALIDATION_ERROR"

tests/contract/sdk/python/test_retries.py

@@ -0,0 +1,108 @@
+"""Retry behavior: only ever on connection failures or a `503`, never on a
+`4xx`, and never inside a started SSE stream. See `ragcore_sdk.client`'s
+module docstring for the reasoning.
+"""
+
+from __future__ import annotations
+
+import httpx
+import pytest
+from ragcore_sdk import RAGCoreAPIError, RAGCoreClient, RAGCoreConnectionError
+
+from conftest import build_search_app, run_app
+
+
+class FlakyTransport(httpx.BaseTransport):
+    """Returns a synthetic 503 for the first `fail_times` requests, then
+    delegates to a real HTTP transport pointed at the real running server.
+    Counts every request it sees.
+    """
+
+    def __init__(self, *, fail_times: int) -> None:
+        self._inner = httpx.HTTPTransport()
+        self._fail_times = fail_times
+        self.call_count = 0
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        self.call_count += 1
+        if self.call_count <= self._fail_times:
+            return httpx.Response(
+                503,
+                json={
+                    "type": "https://ragcore.example.test/problems/search_unavailable",
+                    "title": "Search unavailable",
+                    "status": 503,
+                    "code": "SEARCH_UNAVAILABLE",
+                    "detail": "synthetic failure for retry test",
+                    "trace_id": "test-trace",
+                },
+            )
+        return self._inner.handle_request(request)
+
+
+class AlwaysDownTransport(httpx.BaseTransport):
+    def __init__(self) -> None:
+        self.call_count = 0
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        self.call_count += 1
+        raise httpx.ConnectError("synthetic connection failure", request=request)
+
+
+def test_retries_on_503_then_succeeds() -> None:
+    fixture = build_search_app()
+    with run_app(fixture.app) as base_url:
+        transport = FlakyTransport(fail_times=2)
+        client = RAGCoreClient(
+            base_url=base_url,
+            token="sdk-test-token",
+            transport=transport,
+            max_retries=3,
+        )
+        try:
+            response = client.search(query="refund", requested_space_ids=[fixture.space_id])
+        finally:
+            client.close()
+
+    assert transport.call_count == 3
+    assert response.results
+
+
+def test_does_not_retry_a_client_error() -> None:
+    fixture = build_search_app()
+    with run_app(fixture.app) as base_url:
+        # fail_times=0: every request goes straight through to the real app,
+        # so this only counts calls -- the 422 below comes from the app's
+        # own request validation, not from the transport.
+        counting = FlakyTransport(fail_times=0)
+        client = RAGCoreClient(
+            base_url=base_url,
+            token="sdk-test-token",
+            transport=counting,
+            max_retries=3,
+        )
+        try:
+            with pytest.raises(RAGCoreAPIError) as excinfo:
+                client.search(query="   ")
+        finally:
+            client.close()
+
+    assert excinfo.value.problem.status == 422
+    assert counting.call_count == 1
+
+
+def test_connection_failure_exhausts_retries_then_raises() -> None:
+    transport = AlwaysDownTransport()
+    client = RAGCoreClient(
+        base_url="http://127.0.0.1:1",
+        token="sdk-test-token",
+        transport=transport,
+        max_retries=2,
+    )
+    try:
+        with pytest.raises(RAGCoreConnectionError):
+            client.search(query="refund")
+    finally:
+        client.close()
+
+    assert transport.call_count == 3

tests/contract/sdk/python/test_search.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from uuid import uuid4
+
+import pytest
+from ragcore_sdk import RAGCoreAPIError, RAGCoreClient
+
+from conftest import build_search_app, run_app
+
+
+@contextmanager
+def _client(app: object, *, token: str = "sdk-test-token") -> Iterator[RAGCoreClient]:  # noqa: S107
+    with run_app(app) as base_url, RAGCoreClient(base_url=base_url, token=token) as client:  # type: ignore[arg-type]
+        yield client
+
+
+def test_search_returns_typed_results() -> None:
+    fixture = build_search_app()
+    with _client(fixture.app) as client:
+        response = client.search(query="refund", requested_space_ids=[fixture.space_id])
+
+    assert response.effective_space_ids == [fixture.space_id]
+    assert response.results[0].citation.excerpt_sha256
+    assert response.results[0].rank == 1
+    assert response.degraded is False
+
+
+def test_search_out_of_scope_space_narrows_silently_to_empty() -> None:
+    fixture = build_search_app()
+    forbidden_space = uuid4()
+    with _client(fixture.app) as client:
+        response = client.search(query="refund", requested_space_ids=[forbidden_space])
+
+    assert response.effective_space_ids == []
+    assert response.results == []
+
+
+def test_search_validation_error_raises_typed_problem() -> None:
+    fixture = build_search_app()
+    with _client(fixture.app) as client, pytest.raises(RAGCoreAPIError) as excinfo:
+        client.search(query="   ")
+
+    problem = excinfo.value.problem
+    assert problem.status == 422
+    assert problem.code == "VALIDATION_ERROR"
+    assert problem.trace_id
+    assert problem.errors
+
+
+def test_bearer_token_never_appears_in_client_repr_or_error_message() -> None:
+    fixture = build_search_app()
+    secret_token = "super-secret-bearer-value-should-never-leak"
+    with _client(fixture.app, token=secret_token) as client:
+        assert secret_token not in repr(client)
+        with pytest.raises(RAGCoreAPIError) as excinfo:
+            client.search(query="   ")
+        assert secret_token not in str(excinfo.value)
+        problem = excinfo.value.problem
+        for field in problem.__slots__:
+            assert secret_token not in repr(getattr(problem, field))

tests/contract/sdk/typescript/answers.test.ts

@@ -0,0 +1,54 @@
+import { randomUUID } from "node:crypto";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { asDoneAnswer, RAGCoreClient } from "../../../../sdk/typescript/src/index.js";
+import { FIXTURE_TRIGGER_ANSWER_ERROR, startFixtureServer, type FixtureServer } from "./fixtureServer.js";
+
+describe("answers", () => {
+  let server: FixtureServer;
+  let client: RAGCoreClient;
+
+  beforeEach(async () => {
+    server = await startFixtureServer();
+    client = new RAGCoreClient(server.url, "sdk-test-token");
+  });
+
+  afterEach(async () => {
+    await server.close();
+  });
+
+  it("returns a typed response for a non-streaming answer", async () => {
+    const spaceId = randomUUID();
+    const response = await client.answer("refund window", { requestedSpaceIds: [spaceId] });
+
+    expect(response.answer).toBeTruthy();
+    expect(response.citations.length).toBeGreaterThan(0);
+    expect(response.claims.every((claim) => claim.citation_ids.length > 0)).toBe(true);
+  });
+
+  it("streams retrieval_metadata then done in order", async () => {
+    const spaceId = randomUUID();
+    const events = [];
+    for await (const event of client.answerStream("refund window", { requestedSpaceIds: [spaceId] })) {
+      events.push(event);
+    }
+
+    expect(events.map((event) => event.type)).toEqual(["retrieval_metadata", "done"]);
+    const doneAnswer = asDoneAnswer(events[1]!);
+    expect(doneAnswer).not.toBeNull();
+    expect(doneAnswer?.citations.length).toBeGreaterThan(0);
+    expect(asDoneAnswer(events[0]!)).toBeNull();
+  });
+
+  it("streams a terminal error event on a generation failure", async () => {
+    const spaceId = randomUUID();
+    const events = [];
+    for await (const event of client.answerStream(`refund window ${FIXTURE_TRIGGER_ANSWER_ERROR}`, {
+      requestedSpaceIds: [spaceId],
+    })) {
+      events.push(event);
+    }
+
+    expect(events.map((event) => event.type)).toEqual(["retrieval_metadata", "error"]);
+    expect(events[1]?.data["code"]).toBe("validation_retries_exhausted");
+  });
+});

tests/contract/sdk/typescript/context.test.ts

@@ -0,0 +1,44 @@
+import { randomUUID } from "node:crypto";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { RAGCoreAPIError, RAGCoreClient } from "../../../../sdk/typescript/src/index.js";
+import { startFixtureServer, type FixtureServer } from "./fixtureServer.js";
+
+describe("context", () => {
+  let server: FixtureServer;
+  let client: RAGCoreClient;
+
+  beforeEach(async () => {
+    server = await startFixtureServer();
+    client = new RAGCoreClient(server.url, "sdk-test-token");
+  });
+
+  afterEach(async () => {
+    await server.close();
+  });
+
+  it("returns typed blocks and citations", async () => {
+    const spaceId = randomUUID();
+    const response = await client.context("refund", { requestedSpaceIds: [spaceId] });
+
+    expect(["answerable", "partially_answerable", "not_answerable", "conflicting_evidence"]).toContain(
+      response.answerability
+    );
+    expect(response.token_count).toBeGreaterThanOrEqual(0);
+    if (response.blocks.length > 0) {
+      expect(response.blocks[0]?.citation_ids.length).toBeGreaterThan(0);
+      expect(response.citations.length).toBeGreaterThan(0);
+    }
+  });
+
+  it("raises a typed problem on a validation failure", async () => {
+    let caught: unknown;
+    try {
+      await client.context("   ");
+    } catch (error) {
+      caught = error;
+    }
+
+    expect(caught).toBeInstanceOf(RAGCoreAPIError);
+    expect((caught as RAGCoreAPIError).problem.status).toBe(422);
+  });
+});

tests/contract/sdk/typescript/fixtureServer.ts

@@ -0,0 +1,284 @@
+/**
+ * A minimal, real local HTTP server standing in for RAGCore's own
+ * `/v1/{search,context,answers}` routes, used only to test the TypeScript
+ * SDK's own HTTP layer (request shape, response typing, SSE parsing,
+ * Problem Details mapping, retries) -- not to re-prove RAGCore's
+ * authorization/retrieval business logic, which the real Python contract
+ * tests (`tests/contract/api/**`) and the Python SDK's own real-backend
+ * tests (`tests/contract/sdk/python/**`, M7-01) already cover against the
+ * actual FastAPI app.
+ *
+ * Response shapes here are copied verbatim from the real Pydantic schemas
+ * (`ragcore.api.v1.{search,context,answers}.schemas`) and the real SSE wire
+ * format (`ragcore.api.v1.answers.routes._sse_body`:
+ * `event: <type>\ndata: <json>\n\n`), including the real (fixed) RFC7807
+ * Problem Details shape with a populated `errors` array on a 422.
+ */
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import { randomUUID } from "node:crypto";
+
+export interface FixtureServerOptions {
+  /** Return a synthetic 503 for this many requests before serving normally. */
+  failFirstNRequests?: number;
+}
+
+export interface FixtureServer {
+  url: string;
+  requestCount: () => number;
+  close: () => Promise<void>;
+}
+
+const FORBIDDEN_SPACE_ID = "00000000-0000-0000-0000-000000000fff";
+const TRIGGER_ANSWER_ERROR = "TRIGGER_ERROR";
+
+function readBody(req: IncomingMessage): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => chunks.push(chunk));
+    req.on("end", () => {
+      const raw = Buffer.concat(chunks).toString("utf8");
+      if (raw.length === 0) {
+        resolve({});
+        return;
+      }
+      try {
+        resolve(JSON.parse(raw));
+      } catch (error) {
+        reject(error);
+      }
+    });
+    req.on("error", reject);
+  });
+}
+
+function sendJson(res: ServerResponse, status: number, body: unknown, contentType = "application/json"): void {
+  const payload = JSON.stringify(body);
+  res.writeHead(status, { "content-type": contentType });
+  res.end(payload);
+}
+
+function sendValidationProblem(res: ServerResponse, field: string, message: string): void {
+  sendJson(
+    res,
+    422,
+    {
+      type: "https://ragcore.example.test/problems/validation_error",
+      title: "Request validation failed",
+      status: 422,
+      code: "VALIDATION_ERROR",
+      detail: "The request did not satisfy the API contract.",
+      trace_id: randomUUID(),
+      errors: [{ field, message }],
+    },
+    "application/problem+json"
+  );
+}
+
+function fixtureCitation(id: string): Record<string, unknown> {
+  return {
+    id,
+    document_id: randomUUID(),
+    document_version_id: randomUUID(),
+    title: "Refund policy",
+    section: "Refunds",
+    page_start: 4,
+    page_end: 4,
+    line_start: null,
+    line_end: null,
+    excerpt: "The refund window is thirty days from the original purchase date.",
+    excerpt_sha256: "a".repeat(64),
+    source_uri: "https://example.test/policy.md",
+  };
+}
+
+export function startFixtureServer(options: FixtureServerOptions = {}): Promise<FixtureServer> {
+  let requestCount = 0;
+  let failuresRemaining = options.failFirstNRequests ?? 0;
+
+  const server: Server = createServer((req, res) => {
+    void (async () => {
+      requestCount += 1;
+      if (failuresRemaining > 0) {
+        failuresRemaining -= 1;
+        sendJson(
+          res,
+          503,
+          {
+            type: "https://ragcore.example.test/problems/search_unavailable",
+            title: "Search unavailable",
+            status: 503,
+            code: "SEARCH_UNAVAILABLE",
+            detail: "synthetic failure for retry test",
+            trace_id: randomUUID(),
+            errors: [],
+          },
+          "application/problem+json"
+        );
+        return;
+      }
+
+      const auth = req.headers["authorization"];
+      if (typeof auth !== "string" || !auth.startsWith("Bearer ")) {
+        sendJson(
+          res,
+          401,
+          {
+            type: "https://ragcore.example.test/problems/authentication_required",
+            title: "Authentication required",
+            status: 401,
+            code: "AUTHENTICATION_REQUIRED",
+            detail: "Authentication is required.",
+            trace_id: randomUUID(),
+            errors: [],
+          },
+          "application/problem+json"
+        );
+        return;
+      }
+
+      const body = (await readBody(req)) as Record<string, unknown>;
+      const query = typeof body["query"] === "string" ? body["query"] : "";
+      if (query.trim() === "") {
+        sendValidationProblem(res, "body.query", "String should match pattern '.*\\S.*'");
+        return;
+      }
+
+      const requestedSpaceIds = Array.isArray(body["requested_space_ids"])
+        ? (body["requested_space_ids"] as string[])
+        : [];
+      const forbidden = requestedSpaceIds.includes(FORBIDDEN_SPACE_ID);
+      const effectiveSpaceIds = forbidden ? [] : requestedSpaceIds.length > 0 ? requestedSpaceIds : [randomUUID()];
+      const retrievalRunId = randomUUID();
+      const citationId = randomUUID();
+
+      if (req.url === "/v1/search") {
+        sendJson(res, 200, {
+          retrieval_run_id: retrievalRunId,
+          effective_space_ids: effectiveSpaceIds,
+          results:
+            effectiveSpaceIds.length === 0
+              ? []
+              : [
+                  {
+                    chunk_id: randomUUID(),
+                    parent_chunk_id: null,
+                    text: "The refund window is thirty days from the original purchase date.",
+                    rank: 1,
+                    scores: { dense: 0.87, sparse: 0.41, fused: 1 / 61, rerank: null },
+                    citation: fixtureCitation(citationId),
+                  },
+                ],
+          degraded: false,
+          degradation_codes: [],
+          timings_ms: { dense: 12.5 },
+        });
+        return;
+      }
+
+      if (req.url === "/v1/context") {
+        sendJson(res, 200, {
+          retrieval_run_id: retrievalRunId,
+          answerability: effectiveSpaceIds.length === 0 ? "not_answerable" : "partially_answerable",
+          answerability_reasons: [],
+          blocks:
+            effectiveSpaceIds.length === 0
+              ? []
+              : [{ text: "Refund evidence.", citation_ids: [citationId], token_count: 4 }],
+          citations: effectiveSpaceIds.length === 0 ? [] : [fixtureCitation(citationId)],
+          token_count: effectiveSpaceIds.length === 0 ? 0 : 4,
+        });
+        return;
+      }
+
+      if (req.url === "/v1/answers") {
+        const stream = body["stream"] === true;
+        const answerable = effectiveSpaceIds.length > 0;
+        const errored = query.includes(TRIGGER_ANSWER_ERROR);
+
+        if (!stream) {
+          if (errored) {
+            sendJson(
+              res,
+              503,
+              {
+                type: "https://ragcore.example.test/problems/generation_unavailable",
+                title: "Answers unavailable",
+                status: 503,
+                code: "GENERATION_UNAVAILABLE",
+                detail: "The answer service is temporarily unavailable.",
+                trace_id: randomUUID(),
+                errors: [],
+              },
+              "application/problem+json"
+            );
+            return;
+          }
+          sendJson(res, 200, {
+            answer_id: randomUUID(),
+            retrieval_run_id: retrievalRunId,
+            answerability: answerable ? "partially_answerable" : "not_answerable",
+            answer: answerable ? "The refund window is thirty days from purchase." : "",
+            citations: answerable ? [fixtureCitation(citationId)] : [],
+            claims: answerable ? [{ text: "Thirty days.", citation_ids: [citationId] }] : [],
+            degraded: false,
+          });
+          return;
+        }
+
+        res.writeHead(200, { "content-type": "text/event-stream" });
+        const metadata = {
+          retrieval_run_id: retrievalRunId,
+          effective_space_ids: effectiveSpaceIds,
+          answerability: answerable ? "partially_answerable" : "not_answerable",
+          answerability_reasons: [],
+        };
+        res.write(`event: retrieval_metadata\ndata: ${JSON.stringify(metadata)}\n\n`);
+        if (errored) {
+          res.write(`event: error\ndata: ${JSON.stringify({ code: "validation_retries_exhausted" })}\n\n`);
+        } else {
+          const done = {
+            answer_id: randomUUID(),
+            retrieval_run_id: retrievalRunId,
+            answerability: answerable ? "partially_answerable" : "not_answerable",
+            answer: answerable ? "The refund window is thirty days from purchase." : "",
+            citations: answerable ? [fixtureCitation(citationId)] : [],
+            claims: answerable ? [{ text: "Thirty days.", citation_ids: [citationId] }] : [],
+            degraded: false,
+          };
+          res.write(`event: done\ndata: ${JSON.stringify(done)}\n\n`);
+        }
+        res.end();
+        return;
+      }
+
+      sendJson(res, 404, {
+        type: "about:blank",
+        title: "Not Found",
+        status: 404,
+        code: "NOT_FOUND",
+        detail: null,
+        trace_id: randomUUID(),
+        errors: [],
+      });
+    })();
+  });
+
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (address === null || typeof address === "string") {
+        reject(new Error("failed to bind fixture server"));
+        return;
+      }
+      resolve({
+        url: `http://127.0.0.1:${address.port}`,
+        requestCount: () => requestCount,
+        close: () => new Promise((res) => server.close(() => res())),
+      });
+    });
+  });
+}
+
+export const FIXTURE_FORBIDDEN_SPACE_ID = FORBIDDEN_SPACE_ID;
+export const FIXTURE_TRIGGER_ANSWER_ERROR = TRIGGER_ANSWER_ERROR;

tests/contract/sdk/typescript/retries.test.ts

@@ -0,0 +1,53 @@
+import { randomUUID } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { RAGCoreAPIError, RAGCoreClient, RAGCoreConnectionError } from "../../../../sdk/typescript/src/index.js";
+import { startFixtureServer } from "./fixtureServer.js";
+
+describe("retries", () => {
+  it("retries a 503 twice then succeeds", async () => {
+    const server = await startFixtureServer({ failFirstNRequests: 2 });
+    try {
+      const client = new RAGCoreClient(server.url, "sdk-test-token", { maxRetries: 3 });
+      const response = await client.search("refund", { requestedSpaceIds: [randomUUID()] });
+
+      expect(server.requestCount()).toBe(3);
+      expect(response.results.length).toBeGreaterThan(0);
+    } finally {
+      await server.close();
+    }
+  });
+
+  it("never retries a real 4xx client error", async () => {
+    const server = await startFixtureServer();
+    try {
+      const client = new RAGCoreClient(server.url, "sdk-test-token", { maxRetries: 3 });
+      let caught: unknown;
+      try {
+        await client.search("   ");
+      } catch (error) {
+        caught = error;
+      }
+
+      expect(caught).toBeInstanceOf(RAGCoreAPIError);
+      expect((caught as RAGCoreAPIError).problem.status).toBe(422);
+      expect(server.requestCount()).toBe(1);
+    } finally {
+      await server.close();
+    }
+  });
+
+  it("exhausts retries on a connection failure and raises RAGCoreConnectionError", async () => {
+    // Port 1 is a privileged port nothing is listening on in this sandbox --
+    // fetch fails at the connection stage every time, deterministically.
+    const client = new RAGCoreClient("http://127.0.0.1:1", "sdk-test-token", { maxRetries: 2, timeoutMs: 2000 });
+
+    let caught: unknown;
+    try {
+      await client.search("refund");
+    } catch (error) {
+      caught = error;
+    }
+
+    expect(caught).toBeInstanceOf(RAGCoreConnectionError);
+  });
+});

tests/contract/sdk/typescript/search.test.ts

@@ -0,0 +1,67 @@
+import { randomUUID } from "node:crypto";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { RAGCoreAPIError, RAGCoreClient } from "../../../../sdk/typescript/src/index.js";
+import { FIXTURE_FORBIDDEN_SPACE_ID, startFixtureServer, type FixtureServer } from "./fixtureServer.js";
+
+describe("search", () => {
+  let server: FixtureServer;
+  let client: RAGCoreClient;
+
+  beforeEach(async () => {
+    server = await startFixtureServer();
+    client = new RAGCoreClient(server.url, "sdk-test-token");
+  });
+
+  afterEach(async () => {
+    await server.close();
+  });
+
+  it("returns typed results", async () => {
+    const spaceId = randomUUID();
+    const response = await client.search("refund", { requestedSpaceIds: [spaceId] });
+
+    expect(response.effective_space_ids).toEqual([spaceId]);
+    expect(response.results[0]?.citation.excerpt_sha256).toBeTruthy();
+    expect(response.results[0]?.rank).toBe(1);
+    expect(response.degraded).toBe(false);
+  });
+
+  it("narrows a forbidden space to an empty result silently", async () => {
+    const response = await client.search("refund", { requestedSpaceIds: [FIXTURE_FORBIDDEN_SPACE_ID] });
+
+    expect(response.effective_space_ids).toEqual([]);
+    expect(response.results).toEqual([]);
+  });
+
+  it("raises a typed problem with populated errors on a validation failure", async () => {
+    let caught: unknown;
+    try {
+      await client.search("   ");
+    } catch (error) {
+      caught = error;
+    }
+
+    expect(caught).toBeInstanceOf(RAGCoreAPIError);
+    const problem = (caught as RAGCoreAPIError).problem;
+    expect(problem.status).toBe(422);
+    expect(problem.code).toBe("VALIDATION_ERROR");
+    expect(problem.trace_id).toBeTruthy();
+    expect(problem.errors.length).toBeGreaterThan(0);
+  });
+
+  it("never leaks the bearer token through the client or a thrown error", async () => {
+    const secretToken = "super-secret-bearer-value-should-never-leak";
+    const secretClient = new RAGCoreClient(server.url, secretToken);
+
+    expect(String(secretClient)).not.toContain(secretToken);
+    expect(JSON.stringify(secretClient)).not.toContain(secretToken);
+
+    try {
+      await secretClient.search("   ");
+      throw new Error("expected search to reject");
+    } catch (error) {
+      expect(String(error)).not.toContain(secretToken);
+      expect(JSON.stringify((error as RAGCoreAPIError).problem)).not.toContain(secretToken);
+    }
+  });
+});