feat: cluster embeddings and POST /v1/query/similar (#20)

[leo-aa88]

Closes #20

G11 remainder: persist cluster template vectors, ANN indexes, and cross-incident similar search with fingerprint fallback.

What landed

• cluster_embeddings table keyed by (scope, fingerprint) (migration 0009_cluster_embeddings) with upsert after clustering when the embeddings provider is available (fail-open).
• ANN indexes on log_embeddings.embedding and cluster_embeddings.embedding — HNSW first, IVFFlat lists=1 if HNSW is unavailable.
• POST /v1/query/similar plus deprecated /query/similar, G7 schema_version 1.0 + llm provenance (rules-only), G8 bind_request_scope.
• Graceful degradation: provider down / no vectors → fingerprint-equality matching; DB/embed errors return empty matches, never 500.

Cross-scope policy

• admin: cross-scope by default
• pinned query keys: same-scope only
• query + allow_scope_override: cross-scope when cross_scope=true
• AUTH_ENABLED=false: cross-scope allowed

Tests

Unit suite passed locally (724). Semantic vs fingerprint fallback, permission isolation, G7 fields, upsert helpers.

  

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[cursor]

Review — PR #48 (G11 /similar)

Unit tests (724) and ruff on the touched files both passed. The G11 remainder matches the acceptance bar.

Must-fix

(None)

Should-fix

(None)

Nice-to-have

1. src/core/clustering/clusterer.py:194 — _maybe_persist_cluster_embeddings runs even when save_to_db=False, so /query/clusters, /query/timeline, /query/compare, and /query/similar become writers. A short-window clusters call can overwrite (scope, fingerprint) vectors plus first_seen/count from a fuller explain run. Prefer persisting only when save_to_db=True, or LEAST(first_seen) / GREATEST(last_seen, count) on conflict.
2. src/api/routes/similar.py:137 — the route except Exception swallows every failure after scope/window validation (including a future HTTPException). Fail-open is correct for G11; re-raise HTTPException / ScopeResolutionError so 4xx stays 4xx.

Verdict

Ready to merge (0 must-fix, 0 should-fix)

Acceptance is met: cluster_embeddings unique on (scope, fingerprint) (0009, new migration only), HNSW with IVFFlat lists=1 fallback on both vector columns, POST /v1/query/similar plus deprecated /query/similar, G7 schema_version 1.0 + rules-only llm, G8 bind_request_scope. Pinned query keys ignore cross_scope=true and SQL pins scope = visible_scope. Embeddings/DB failures return empty fingerprint results, not 500s. Vectors and fingerprints are bound parameters. /v1/query/similar is covered by existing /query* rate limits. Unit tests mock the DB. No secrets.