contextweaver: Instructions file for GitHub Copilot

Routing Engine — Agent Instructions

Path-scoped guidance for src/contextweaver/routing/. Read before modifying any file here.

ChoiceGraph validation invariants (graph.py)

ChoiceGraph._validate() enforces four rules — all must hold at all times:

1. Root exists — root_id must be present in _nodes.
2. Children resolve — every edge destination must exist in _nodes | _items.
3. No cycles — topological_order() must succeed (raises GraphBuildError if not).
4. All items reachable — every item in _items must be reachable from root_id.

Cycle detection is eager: add_edge() calls _creates_cycle() immediately and raises GraphBuildError before the edge is persisted. Do not bypass this check.

Serialisation via from_dict() rebuilds children / child_types from _edges to guarantee consistency — never rely on serialised node metadata for child lists.

TreeBuilder grouping strategies (tree.py)

TreeBuilder.build() tries three strategies in priority order:

1. Namespace grouping — group by first dot-segment of item.namespace; requires ≥ 50 % of items to have a namespace and ≥ 2 groups.
2. Jaccard clustering — farthest-first seeding over tokenize(_text_repr(item)); falls back if clustering yields < 2 groups.
3. Alphabetical fallback — sort by item.name.lower(), split into even chunks.

The builder is deterministic: it sorts items by item.id before processing. Do not introduce randomness or non-deterministic ordering inside _build_subtree.

Every node has at most max_children children (default 20). Oversized groups are coalesced via _coalesce_groups() or re-split before adding edges.

Router beam-search constraints (router.py)

• Deterministic tie-breaking: children are sorted (-score, id) — descending score, alphabetical ID for ties. Never change this sort key.
• confidence_gap (default 0.15) widens the beam by 1 when rank-1 and rank-2 scores differ by less than the gap. Must stay in [0.0, 1.0].
• Results are ranked (-score, item_id) — same determinism guarantee end-to-end.
• The TF-IDF index is lazily built on first route() call via _ensure_index(). Items are indexed by sorted item_id before non-item (navigation) nodes; do not change order.
• Fallback scoring (nodes not in TF-IDF index) uses jaccard() from contextweaver._utils — never duplicate this logic here.