Feature (optional): store context hydration helper

[lwyBZss8924d]

Summary

Provide a helper API to hydrate context lines for ranked results, simplifying CLI/orchestrator code that needs to render snippets.

Motivation

• Multiple callers (CLI, agents) need to read files and extract n_lines context around a matched line.
• Centralizing this logic improves consistency and reduces duplication.

Proposed API (Rust)

// File: src/workspace/store.rs
use anyhow::Result;
use crate::workspace::store::RankedLine;

pub async fn hydrate_context(
    &self,
    ranked: &[RankedLine],
    n_lines: usize,
) -> Result<Vec<(RankedLine, Vec<String>)>> {
    // Reads each file once, extracts [start..end) lines, returns alongside RankedLine
}

Notes

• This is an optional helper; not required for JSON output features.
• search CLI could reuse it when --output json to include the lines field consistently for workspace-backed results.

Acceptance criteria

• Helper compiles and is covered by a basic test reading temp files.
• No change to defaults unless explicitly used by callers.

[lwyBZss8924d]

Intent: standardize snippet packaging for citations and verification in agentic flows.

Why a context hydration helper matters:

• Many callers independently re-implement "read file → slice [start..end) → return lines"; centralizing prevents drift and subtle off-by-one bugs.
• For hierarchical navigation, agents need consistent, paragraph/line windows for citations (file:start::end) and judge steps.
• Single pass I/O (read each file once) also avoids redundant disk ops when top-K spans multiple lines in the same file.

Scope

• Optional helper only, does not alter existing APIs or defaults.

Outcome

• Consistent evidence packaging across CLI and programmatic use, improving reliability of autonomous, recursive retrieval loops.

[lwyBZss8924d]

Reference: OpenAI Model Selection Guide — Long-Context Agentic RAG

• https://cookbook.openai.com/examples/partners/model_selection_guide/model_selection_guide#7-takeaways

Why a context hydration helper aligns with the Cookbook approach:

• The hierarchical loop produces a small set of paragraph/line windows that need consistent packaging for citations (file:start::end) and LLM-as-judge verification.
• Centralizing the "read once → slice [start..end) → return lines" logic avoids drift across CLI/programmatic callers and reduces redundant file I/O.

Agent example (excerpt) that consumes such snippets:

---
name: document-retriever
model: opus
---
# Depth-0/1/2 routing yields a shortlist of evidence windows per file.
# The agent emits citations and snippets into run artifacts, then verifies over cited text only.

A small helper in Store makes the evidence step straightforward and consistent across the ecosystem.

[logan-markewich]

I'm not sure I totally understand the proposal here

The --n-lines param already provides the lines around the match hit. Is there something more that can be done here? Any example of usage/output would help!