[hmziqagent]

What this adds

Four research waves (October–November 2026) comparing llm-proxy against the
LLM-gateway market, ending in an evidence-backed, crate-mapped compensation
backlog. Waves 1–2 surveyed 27 products/themes plus 10 doc sweeps and 10
capability frontiers; wave 3 hunted 14 ecosystem niches on GitHub (121 unique
repository finds, 23 researched in full); wave 4 shallow-cloned those 23,
harvested the issues and PRs of 120 repositories, and mined them for what
those projects themselves lack.

Reports in this PR

All referenced from the updated index, docs/research/README.md:

Document	What it is
docs/research/README.md	Research index (updated with all new entries)
docs/research/competitive-gap-analysis.md	Waves 1–2: sourced gap analysis — 57 research tasks, 10 deep dives, 20 ranked gaps; llm-proxy-side claims verified against the code, corrections dated 2026-10-28
docs/research/competitive-landscape-compendium.md	The consolidated master document — market map (~41 products), 15 capability sections, the 18-gap register, 10 implementation blueprints, build-order candidates, coverage appendix; passed four independent audit passes
docs/research/niche-repos.md	Wave 3: modular per-repo survey of 23 niche gateways + capability index + appendix of all 121 finds
docs/research/repos-registry.json	Machine-readable registry of all 72 researched products across the waves (name, category, language, status, capabilities with source URLs)
docs/research/repo-intelligence.md	Wave 4: per-repo intelligence from the 23 clones and the issue/PR harvests — capabilities, pain points, directions, recurring unmet needs across 3+ repos
docs/research/compensation-backlog.json	38 evidence-backed candidate features to implement, each mapped to the workspace crate where it lands (12 high / 19 medium / 7 low, 162 evidence entries)
docs/research/harvest-manifest.json	Record of the GitHub harvest: 120 repositories with issue/PR counts

Pre-existing notes referenced by the same index (unchanged here):
core-protocol.md, providers.md, endpoints.md, and the vendored
reference pins under ref/ (ref/REFS).

Headline findings

• Top of the gap register: request-path retries/fallback/cooldowns;
  per-key spend budgets with enforcement; TPM and concurrency limits
  (per-key RPM already exists); cloud-native upstream auth (AWS SigV4/STS,
  Azure Entra refresh, GCP ADC/workload identity); upstream credential
  pools with rotation and cooldowns; client-facing /v1/responses.
• Added by the niche wave: LLM-phase-shaped timeout hierarchy,
  request-payload cost transforms (context compaction) with a shadow-eval
  guard, OAuth credential lifecycle incl. consumer subscription upstreams,
  client-disconnect upstream cancellation, engine-state-aware routing,
  admission queueing, caller OIDC/RBAC, community price catalogs, hedged
  request races.
• Harvest-backed compensation candidates (each citing the issue/PR that
  proves the pain): OpenAI-dialect cached-token accounting
  (prompt_tokens_details), first-frame SSE failover, context-overflow
  preflight with the existing token counter, disconnect usage settlement,
  usage_estimated fallback when upstreams omit usage, egress header
  hygiene and redirect re-validation, Host/Origin (DNS-rebinding)
  validation in mode=none.

Verification

• Every capability claim carries evidence: a live source URL, a ref/
  clone path, or a harvested issue/PR URL.
• The compendium went through four independent audit passes; two claims
  that contradicted shipped code (BYOK passthrough, per-key rate limiting)
  were corrected in place with dated markers.
• Both JSON deliverables validate with python3 -m json.tool.

Deliberately not in the repo

research-repos/ (23 shallow clones, ~658 MB) and research-issues/
(harvested tracker JSON, ~182 MB) stay git-ignored locally as the evidence
base; harvest-manifest.json records their scope.