docs(research): complementary-architecture one-pager (three-layer handoff)

[SoundMindsAI]

What

Adds a runtime-agnostic positioning one-pager at docs/07_research/complementary-architecture.md, beside the existing comparison.md.

It frames RelyLoop as the offline, query-time middle layer of a three-layer search pipeline:

1. Ingest / index-time — owned by the team (RelyLoop never touches schema/mappings/analyzers)
2. Query-time configuration — owned by RelyLoop (offline Bayesian optimization, shipped as a Git PR)
3. Runtime / serving — owned by the team (reranking, LLM-judge gates, RAG, agentic orchestration, etc.)

Thesis: whatever a team runs at ingest or serving, they still need a well-tuned query-time baseline — which RelyLoop finds automatically and proposes as a reviewable PR. Because it's strictly offline + query-time, it's orthogonal to every runtime choice and can never become a production dependency.

Why

Positioning asset for partnership/outreach conversations: lets any search-engineering team see the value regardless of their serving stack.

Scope / constraints

• Docs-only; no code, no behavior change.
• Deliberately generic — no named third parties, companies, or specific runtime products — so it speaks to any team.
• Grounded in RelyLoop's real posture (offline, query-time, Git-PR apply path, three engines, Apache-2.0).

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request implements the studies-list convergence visibility feature (Story 1.1), extending the StudySummary schema and list endpoints to return the non-baseline trial_count and a convergence_verdict per study. To prevent N+1 queries, batched database helpers and a bulk-classification service helper are introduced. The feedback highlights critical robustness issues: a potential AttributeError in the API layer if row.objective is not a dictionary, and potential KeyError or key mismatch bugs in the repository layer if study_id is returned as a UUID object rather than a string.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Defensive programming check: row.objective can be None or not a dictionary in degenerate cases (as handled in resolve_list_convergence_verdicts via isinstance(study.objective, dict)). Calling .get() directly on row.objective without a guard can raise an AttributeError and crash the entire studies list response. We should safely default it to an empty dictionary or guard the access.

    objective = row.objective if isinstance(row.objective, dict) else {}
    raw_direction = objective.get("direction", "maximize")
    direction = raw_direction if raw_direction in ("maximize", "minimize") else "maximize"

[gemini-code-assist]

Type safety and defensive programming: row.study_id can be a uuid.UUID object depending on the database dialect and model definition. Since the function is typed to return dict[str, TrialCounts] and the caller lookup uses stringified IDs (e.g., str(r.id)), we should explicitly stringify row.study_id to prevent key mismatch issues.

Suggested change

	result: dict[str, TrialCounts] = {
	row.study_id: TrialCounts(total=int(row.total), complete=int(row.complete)) for row in rows
	}
	result: dict[str, TrialCounts] = {
	str(row.study_id): TrialCounts(total=int(row.total), complete=int(row.complete)) for row in rows
	}

[gemini-code-assist]

KeyError prevention: trial.study_id can be a uuid.UUID object. Since grouped is initialized with string keys from study_ids (which are stringified via str(s.id) in the service layer), accessing grouped[trial.study_id] directly will raise a KeyError at runtime. We should explicitly stringify trial.study_id when accessing the dictionary.

Suggested change

	grouped: dict[str, list[Trial]] = {sid: [] for sid in study_ids}
	for trial in (await db.execute(stmt)).scalars().all():
	grouped[trial.study_id].append(trial)
	grouped: dict[str, list[Trial]] = {sid: [] for sid in study_ids}
	for trial in (await db.execute(stmt)).scalars().all():
	grouped[str(trial.study_id)].append(trial)