Index Handbook

bijux-canon-index owns vector execution, provenance-aware retrieval, and replayable index behavior. It turns prepared ingest output into retrieval surfaces that downstream packages can inspect and reuse without guessing how search happened.

The main failure this handbook prevents is smearing retrieval concerns across ingest, reasoning, and runtime. If vector execution and replay behavior are not owned explicitly here, every later layer starts making hidden assumptions about how evidence was found.

What The Reader Should See First

Index is the retrieval accountability layer. It accepts prepared material, executes search through declared vector and query contracts, and hands forward results that carry enough provenance for another package to explain why a piece of evidence was returned.

flowchart LR
    prepared["prepared ingest output"]
    plan["execution plan"]
    backend["vector backend"]
    result["retrieval result"]
    replay["replay record"]
    reason["reasoning package"]

    prepared --> plan --> backend --> result --> reason
    plan --> replay
    backend --> replay
    result --> replay

Index earns trust by making retrieval inspectable after the fact. The point is not just to return matches. The point is to make it obvious which prepared inputs, query choices, and backend behavior produced those matches so later reasoning does not have to guess how evidence was found.

What This Package Owns

• embedding and vector-store execution tied to prepared ingest output
• retrieval behavior that stays provenance-aware and replayable under review
• index-facing contracts and artifacts that downstream packages rely on during search

What This Package Does Not Own

• source preparation and chunk shaping before indexing begins
• claim interpretation, reasoning policy, or reviewer-facing verification semantics
• top-level runtime authority above retrieval execution and trace collection

Boundary Test

If the disputed behavior decides what gets embedded, stored, retrieved, compared, or replayed during search, it belongs here. If it decides what a claim means or whether a run is acceptable to keep, it does not.

First Proof Check

• packages/bijux-canon-index/src/bijux_canon_index for the owned retrieval implementation boundary
• apis/bijux-canon-index/v1/schema.yaml for the tracked caller-facing schema
• packages/bijux-canon-index/src/bijux_canon_index/domain/provenance for audit, replay, and lineage behavior
• packages/bijux-canon-index/tests for replay, provenance, and retrieval correctness evidence

Start Here

• open Foundation when the question is why this package exists or where its ownership stops
• open Architecture when you need module boundaries, dependency flow, or execution shape
• open Interfaces when the question is about commands, APIs, schemas, imports, or artifacts that callers may treat as stable
• open Operations when you need local workflow, diagnostics, release, or recovery guidance
• open Quality when the question is whether the package has proved its promises strongly enough

Pages In This Package

• Foundation
• Architecture
• Interfaces
• Operations
• Quality

Leave This Handbook When

• the question is now about what evidence means rather than how it was found
• the next step is a concrete interface, workflow, benchmark, or replay test
• the concern belongs to ingest preparation below or runtime authority above