perf: optimize everyday query hot paths

[ferueda]

Summary

• make entry inventory select limit + 1 compact coordinates through an explicit indexed source → tracking → canonical → entry traversal, then hydrate only the page
• add compatible v2 numeric keyset anchors for entry pagination while continuing to accept v1 offset cursors
• batch selected search content, linked-context discovery/body hydration, and retained session summaries with strict identity and corruption checks
• lazily load command handlers so version/help and provider-free reads do less startup work
• add generated entry, search, planner-statistics, and compiled-startup measures; document the resulting work shapes and decisions

Why

A real 4,544-session / 3.57-million-entry library exposed a broad 50-entry query taking roughly 4.5–6 seconds warm. SQLite entered through sessions_entries, scanned broadly, and built a temporary ordering B-tree before applying the page limit. Search hydration also repeated selected-content, context, and summary reads per hit, while CLI startup eagerly loaded handlers that version/help did not need.

Performance evidence

Entries

The shipped statement now enters through source/tracking/canonical rows, uses existing indexes, avoids the entry-first full scan and full temporary sort, and stops at limit + 1. On the generated skew corpus (2,001 sessions, 212,000 entries):

Profile	Coordinate selection	Full page
broad early page	0.132 ms	3.378 ms
broad deep v2 page	0.193 ms	4.116 ms

The deep plan uses keyset continuation and contains no OFFSET or temporary ordering sort. The original 4.5–6 second number came from the larger live library, so it is root-cause evidence rather than a same-corpus percentage claim; the repeatable generated measure is the regression baseline going forward.

Search

Before, selected content, context, and summary hydration grew through repeated point reads. After, selected content and linked discovery are page-wide, summaries are batched, and distinct context bodies hydrate in fixed 200-coordinate chunks. In the maximum-page generated profiles, selected-content work remained one statement and SELECT authorization counts stayed constant at 28 for all / 31 for any without context; the measured context profile added four authorizations. Wall time remained roughly 15–31 ms depending on page size, term mode, and context.

A one-pass MATERIALIZED search prototype preserved semantics and reduced the qualifying FTS scan to one, but was about 15% slower over broad profiles rather than meeting the 20% improvement gate. It was removed from runtime code.

CLI startup

Compiled warm medians, before → after:

Command	Before	After	Change
--version	94.933 ms	67.583 ms	~29% faster
top-level help	94.410 ms	67.237 ms	~29% faster
command help	94.291 ms	67.843 ms	~28% faster
provider-free list	97.400 ms	77.458 ms	~20% faster

Planner statistics were also tested on byte-identical clones. Entry plans did not improve and several list/search profiles regressed, so no runtime ANALYZE or PRAGMA optimize policy was added.

Compatibility and correctness

• public query schemas and structured output remain unchanged; only the opaque entry cursor encoding advances to v2
• existing v1 entry cursors remain accepted and transition to v2 after one continuation
• ranking, support, roots, capture scope, filters, first/last, corruption failures, stale/mismatched cursor behavior, and snapshot semantics remain exact
• provider histories remain read-only; there is no schema migration, telemetry, or network dependency
• high-fan-out linked discovery is capped at 41 candidates per primary, with the public 20-entry linked-context cap and truncation signal preserved
• context corruption in a later hydration chunk fails the complete search rather than returning partial evidence

Verification

• pnpm check
  • formatting, lint, dependency boundaries, and typecheck passed
  • 1,299 tests across 124 files passed
  • build, distribution smoke, and package smoke passed
• focused pagination contracts compare complete page-size-one traversal—including full entry payloads and every capture scope—with canonical one-page results across every filter and selection mode
• generated measures require repeated semantic equality and inspect production SQL/work shape; timing alone is never the correctness gate
• final harness review 20260723-185502-c6e50f: implementation pass, code quality pass, zero findings