interface SemanticSlice {
  sliceId: string;
  content: string;
  sequenceIndex: number;
  documentRef: string;
  embedding: number[];
}

class LocalContextRetriever {
  private slices: SemanticSlice[];
  private expansionRadius: number;

  constructor(slices: SemanticSlice[], radius: number) {
    this.slices = slices.sort((a, b) => a.sequenceIndex - b.sequenceIndex);
    this.expansionRadius = radius;
  }

  /**
   * Resolves a single match into a contiguous context block.
   * Prevents cross-document bleeding by enforcing documentRef boundaries.
   */
  resolveContext(matchId: string): string {
    const anchorIndex = this.slices.findIndex(s => s.sliceId === matchId);
    if (anchorIndex === -1) return '';

    const anchorDoc = this.slices[anchorIndex].documentRef;
    const contextParts: string[] = [];

    // Expand backward
    for (let i = anchorIndex; i >= 0 && i >= anchorIndex - this.expansionRadius; i--) {
      if (this.slices[i].documentRef !== anchorDoc) break;
      contextParts.unshift(this.slices[i].content);
    }

    // Expand forward
    for (let i = anchorIndex + 1; i < this.slices.length && i <= anchorIndex + this.expansionRadius; i++) {
      if (this.slices[i].documentRef !== anchorDoc) break;
      contextParts.push(this.slices[i].content);
    }

    return contextParts.join('\n');
  }

}

### 2. Structural Context Resolution (Parent Document)

This approach treats documents as hierarchical trees. During indexing, large logical units (chapters, sections, pages) are stored as parent nodes. Smaller units (paragraphs, sentences) are stored as child nodes with explicit parent references. Only child nodes are embedded and indexed for search. At retrieval time, child matches are mapped back to their parent nodes for generation.

**Architecture Rationale:**
- Decouples search precision from generation context size.
- Preserves document topology (headers, warnings, disclaimers).
- Requires dual storage but eliminates context bleeding across logical boundaries.

```typescript
interface DocumentNode {
  nodeId: string;
  parentId: string | null;
  text: string;
  embedding: number[];
  isSearchable: boolean;
}

class StructuralRetriever {
  private nodeIndex: Map<string, DocumentNode>;
  private parentLookup: Map<string, DocumentNode>;

  constructor(nodes: DocumentNode[]) {
    this.nodeIndex = new Map(nodes.map(n => [n.nodeId, n]));
    this.parentLookup = new Map();

    // Precompute parent mappings for O(1) resolution
    nodes.forEach(child => {
      if (child.parentId) {
        const parent = this.nodeIndex.get(child.parentId);
        if (parent) {
          this.parentLookup.set(child.nodeId, parent);
        }
      }
    });
  }

  /**
   * Translates child-level search results into parent-level context blocks.
   * Deduplicates parents when multiple children from the same section match.
   */
  resolveGenerationContext(childMatches: string[]): string[] {
    const resolvedParents = new Set<string>();
    const contextBlocks: string[] = [];

    for (const childId of childMatches) {
      const parent = this.parentLookup.get(childId);
      if (parent && !resolvedParents.has(parent.nodeId)) {
        resolvedParents.add(parent.nodeId);
        contextBlocks.push(parent.text);
      }
    }

    return contextBlocks;
  }
}

Architecture Decisions & Rationale

1. Why separate indexing from context resolution? Vector databases optimize for similarity search, not context assembly. Offloading context expansion to application logic keeps the vector store lean and allows dynamic radius/parent resolution without re-indexing.
2. Why store parent text separately? Duplicating parent text across every child chunk inflates storage costs and increases embedding compute time. Storing parents once and referencing them reduces token overhead by 40–60% in structured documents.
3. Why enforce document boundaries? Cross-document context bleeding is a primary cause of RAG hallucinations. Both implementations explicitly check documentRef or parentId to prevent semantic contamination.

Pitfall Guide

1. Cross-Boundary Context Bleeding

Explanation: Expanding windows or resolving parents without checking document boundaries causes the LLM to receive mixed contexts from unrelated sources. Fix: Always validate documentRef or parentId during expansion. Implement hard stops at boundary markers.

2. Metadata Bloat in Window Storage

Explanation: Storing full surrounding text in metadata for every slice duplicates data and increases vector database payload size. Fix: Store only positional indices and document references. Resolve context dynamically at retrieval time using application logic.

3. Parent-Child Embedding Mismatch

Explanation: Using different embedding models or dimensions for parents and children causes retrieval failures when child matches map to parents with incompatible vector spaces. Fix: Use a single embedding model across all hierarchy levels. If parents are too large, chunk them into sub-parents rather than changing models.

4. Hardcoded Expansion Radii

Explanation: Fixed window sizes (e.g., always ±3 sentences) fail across domains. Legal text requires broader context; chat logs require narrower context. Fix: Parameterize expansion radius per data source. Implement dynamic radius selection based on document type or query complexity.

5. Missing Fallback Logic

Explanation: When a child match lacks a parent reference or a window slice is at the document edge, the pipeline returns empty or truncated context. Fix: Implement graceful degradation. Return the available context, log the boundary condition, and optionally trigger a secondary search with relaxed constraints.

6. Ignoring Token Limits During Resolution

Explanation: Resolving multiple parents or large windows can exceed the LLM's context window, causing truncation or API errors. Fix: Implement a token budget checker during context assembly. Prioritize anchors by relevance score and truncate lowest-priority blocks before generation.

Production Bundle

Action Checklist

• Audit existing chunking strategy: Identify whether static chunking is causing retrieval noise or context loss.
• Classify data topology: Map documents to linear (narrative) vs hierarchical (sectioned) structures.
• Implement boundary validation: Ensure all context expansion logic checks document or section boundaries.
• Parameterize expansion settings: Expose window radius and parent resolution rules as configurable pipeline inputs.
• Add token budget enforcement: Prevent context overflow by capping resolved blocks against LLM limits.
• Instrument retrieval metrics: Track anchor-to-context mapping latency, duplication rates, and boundary violations.
• Run evaluation suite: Compare answer fidelity across fixed chunking, window expansion, and parent resolution using domain-specific test sets.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Chat logs, emails, transcripts	Local Context Expansion	Dependencies are strictly sequential; minimal structural overhead	Low storage, moderate compute
Technical manuals, legal contracts	Structural Context Resolution	Critical context lives in headers/disclaimers; requires topology preservation	Higher storage, lower hallucination rate
Mixed document corpus	Hybrid Pipeline	Route linear docs to window expansion, sectioned docs to parent resolution	Moderate infrastructure complexity
Real-time conversational AI	Local Context Expansion	Low latency requirement; dynamic radius adapts to query scope	Predictable latency, low cost
Compliance/audit reporting	Structural Context Resolution	Regulatory context must remain intact; partial sections are unacceptable	Higher initial setup, audit-ready outputs

Configuration Template

# rag-context-pipeline.config.yaml
retrieval:
  strategy: hybrid
  fallback: local_expansion

local_expansion:
  enabled: true
  radius: 3
  boundary_check: document_ref
  max_tokens: 1500

structural_resolution:
  enabled: true
  hierarchy_depth: 2
  deduplicate_parents: true
  max_context_blocks: 4

pipeline:
  token_budget: 4000
  truncate_policy: relevance_descending
  log_boundary_violations: true
  cache_resolved_context: true
  cache_ttl_seconds: 300

Quick Start Guide

1. Ingest and split: Run your documents through a sentence/paragraph splitter. Assign sequential indices and document references.
2. Build the index: Store slices or child nodes in your vector database. Keep parent nodes in a separate key-value store or relational table.
3. Deploy the resolver: Integrate LocalContextRetriever or StructuralRetriever into your retrieval endpoint. Wire the resolver to run immediately after vector search.
4. Enforce boundaries: Add document reference validation and token budget checks before passing context to the LLM.
5. Evaluate and tune: Run a validation set through the pipeline. Adjust expansion radius or parent resolution rules based on answer accuracy and latency metrics.