feat(sdk): indexed reads, workspace memory, and cursor contracts

Merged
UN
3mo ago
+3336-739

What changed

  • add a rebuildable, cursor-bound SQLite metadata query index with atomic publication, transactional mutation maintenance, corruption/staleness fallback, and an SDK-owned query surface
  • use the index for safe bounded list reads while preserving authoritative scan behavior for hooks, rich projections, custom schemas, and unsupported filters
  • add deterministic epoch, quarter, and nearest-epic workspace-memory rollups that keep large closed histories available to context/search within bounded token budgets
  • replace list/context/search cursor deny-lists with contract-declared presentation semantics and a shared SDK selector
  • make standard pm get child context compact through counts, status summaries, and continuations while retaining explicit/full child samples
  • extract typed search contracts, document all new SDK/runtime behavior, and refresh the package-owned changelog with pm-changelog 2026.7.23
  • replace the CodeQL-alerted trailing-separator regex with a linear scan plus a 100,000-separator regression test

Why

The CLI and SDK need reusable project-management primitives that treat project management as bounded, precise context management. This change makes large workspaces cheaper to query, preserves source files as the sole authority, gives package authors public customization surfaces, and removes presentation-only cursor invalidation drift.

Tracked work

The completed workspace-memory, cursor-contract, and security items are closed. The broader 1M-index and rolling SDK-reference items were returned to open with their remaining acceptance recorded; no work item remains in progress.

Verification

  • release gates: build, typecheck, docs/links, strict static quality, SDK boundary, token budgets, version sync, secrets, packed-package smoke, and 88-command dogfood passed
  • exact coverage: 6,120 tests; 100% statements (41,544/41,544), branches (29,316/29,316), functions (8,438/8,438), and lines (40,383/40,383)
  • pnpm benchmark:scale:check: CLI and SDK 10k budgets passed
  • isolated packed consumer: npm audit reported zero vulnerabilities; strict erasable TypeScript SDK imports passed; installed pm init/create/list/context/search passed
  • changelog: latest pm-changelog 2026.7.23 installed; generation and check are reproducible

The local Greptile gate reached the external service but returned free_reviews_limit_reached; hosted checks and available reviewer feedback will be handled on this PR.

Summary by cubic

Delivers a rebuildable SQLite metadata query index for fast, bounded list reads and adds deterministic workspace‑memory rollups that keep large histories searchable. Unifies cursor identities via flag contracts, compacts single‑item child projections by default, and fixes a CodeQL‑flagged ReDoS in path trimming.

  • New Features

    • SQLite metadata query index with atomic rebuilds, transactional updates, and scan fallback; default‑order light list pages serve windowed rows and counts from the index; SDK exposes queryItemMetadataIndex (pm-801d, pm-px153l).
    • Workspace‑memory rollups (epoch, quarter, nearest‑epic) for compact historical context/search on large workspaces; context auto‑attaches; SDK surfaces read/select/search APIs (pm-5qmm).
    • Cursor fingerprints driven by flag contracts; shared selector ignores presentation‑only flags so list/context/search cursors stay stable; typed search contracts extracted (pm-fgih).
    • pm get children are compact by default (counts, status summary, continuation); deep/full retains bounded samples.

  • Bug Fixes

    • Replaced trailing‑separator regex with a linear scan to remove polynomial ReDoS; added a 100k‑separator regression test (pm-v3zd3o).