feat(stats): opt-out entity-link aggregation via include_entity_links param

[chrislatimer]

Summary

Under multi-tenant workloads where one bank holds many memories with many distinct entities per memory, the entity-link aggregation in get_bank_stats (a join + group on unit_entities ⨝ memory_units) dominates the response time of GET /v1/default/banks/{bank_id}/stats. The aggregation is an approximation (per-entity count capped at 10) feeding a single dashboard slice, but it's the only piece of the stats endpoint that scales with the cross-product of memories × entities rather than just memories.

Add an optional include_entity_links query parameter (default true, preserving existing behavior) so callers that don't surface the per-entity slice can skip the aggregation entirely. When false, the entity key in link_counts is omitted — matching the existing "no entity edges yet" rendering — so downstream readers that already tolerate a missing key see no behavior change.

This is purely additive: no existing endpoint contract, response field, default, or behavior changes. Existing callers (including the OSS control plane, the CLI's bank stats renderer, and all generated SDK consumers that don't pass the new param) see identical responses.

Changes

Engine

• MemoryEngineInterface.get_bank_stats and the concrete MemoryEngine impl now accept include_entity_links: bool = True. The flag is threaded through to _compute_bank_stats, which gates the entity-link CTE on it.
• BankStatsCache extended to accept a key_suffix so semantically distinct variants of the same (schema, bank_id) get separate cache slots. invalidate clears every variant for a bank by matching the (schema, bank_id) prefix — writers don't have to know which suffixes the read path is using.
• get_bank_stats passes (include_entity_links,) as the suffix, so a True-variant cache hit can never be served to a False caller and vice versa.

HTTP

• GET /v1/default/banks/{bank_id}/stats accepts ?include_entity_links=false. Default is true. The route description is expanded so clients see the option in the docs.

Generated artifacts

• hindsight-docs/static/openapi.json regenerated. Diff is strictly additive: new optional query param + expanded route description. Response schema unchanged.
• skills/hindsight-docs/references/openapi.json regenerated to match (the generate-docs-skill.sh pre-commit hook syncs the two).
• Client SDK regeneration (./scripts/generate-clients.sh) not included — the script invokes cargo build for the Rust client which isn't available in this dev environment. Maintainer should run it before merge so Python / TypeScript / Go / Rust clients all pick up the new optional query param.

Test plan

Unit tests (tests/test_bank_stats_cache.py) — added, all 17 passing locally

• test_key_suffix_separates_cache_slots — True and False variants produce distinct cache entries; cross-variant reads never run the other loader.
• test_default_key_suffix_is_distinct_slot — the empty default suffix is its own slot, does not collide with (True,).
• test_invalidate_clears_all_variants_for_bank — a single invalidate call wipes both variants so a post-write read reloads regardless of which variant the client asks for next.
• test_invalidate_keeps_other_banks — invalidation is scoped; never bleeds across banks.
• test_concurrent_misses_coalesce_per_variant — two concurrent True callers share one load; a concurrent False caller runs independently.

Integration tests (tests/test_bank_stats.py) — added, require a running Postgres + LLM

• test_bank_stats_default_includes_entity_link_count — default path computes the entity-link slice and returns a well-shaped response.
• test_bank_stats_include_entity_links_false_skips_entity_aggregation — query param threads through to _compute_bank_stats with include_entity_links=False; response omits the entity key; every other field still present.
• test_bank_stats_caches_true_and_false_separately — at the HTTP layer, True and False variants each cache once and are served independently on repeat calls; payloads agree on every field except the optional entity slot.
• test_bank_stats_invalidate_clears_both_variants — a retain that invalidates the cache forces both variants to reload from fresh SQL.

Local results

• Cache unit tests: 17/17 passing
• ruff check: clean on changed files
• ty check: clean on changed files
• OpenAPI regen: strictly additive
• Pre-commit hooks (lint + docs-skill regen): passing
• Integration tests: need a running pg0 + LLM environment to exercise; reviewer should run cd hindsight-api-slim && uv run pytest tests/test_bank_stats.py -v
• SDK regeneration: needs cargo available; reviewer should run ./scripts/generate-clients.sh