perf(graphrag): bound relation authorization hot paths

[kl3inIT]

Summary

• constrain relation contribution and visible-weight authorization to requested relation candidates before endpoint checks
• execute both hot reads inside the existing transaction-local PostgreSQL statement budget
• emit bounded, payload-free per-operation timings correlated to the outer retrieval operation

Incident evidence

• authenticated production pre-fix turn completed HTTP 200/SSE finish in 26.574s
• PostgreSQL sampling measured loadRelationContributions at ~8.10s and loadVisibleRelationWeights at ~8.32s
• protected generation-27 old/new SQL benchmark used the same 40 candidate relations and 27 authorized assets, returned the same 43 rows, and measured 26.093ms old vs 7.666ms new

Security and semantics

• preserves organization, published batch, authorized-asset and independent source/target endpoint visibility checks
• no prompt, answer, evidence, actor, relation/entity ID or credential telemetry
• bounded stage enum; per-invocation observer preserves concurrent snapshot correlation
• independent review found no blocking security or authorization regression

Verification

• relevant PostgreSQL, core, testkit and graph observability suites: PASS (35 tasks executed)
• CI-equivalent Java backend build: PASS (115 tasks)
• evaluation tests: 86 passed
• Ruff: PASS
• Gitleaks: 761 commits scanned, no leaks
• git diff --check: PASS

Production acceptance

After merge and immutable-image deployment, rerun authenticated P001 and the complete official P001-P050 evaluation. Verify retrieval/TTFT/total separately, exact permission/citation gates, zero long-running/orphan PostgreSQL backends, and DB CPU recovery before declaring fixed.

Summary by CodeRabbit

• New Features

  • Added detailed query-operation monitoring, including search, expansion, ranking, and loading stages.
  • Exposed operation outcomes, durations, and input/output counts through an observation callback.
  • Added correlation and authorization-scope details to query telemetry.

• Bug Fixes

  • Improved relation retrieval to enforce query timeouts and visibility checks consistently.
  • Restricted relation contribution results to authorized candidate relations.

[coderabbitai]

📝 Walkthrough

Walkthrough

The change adds per-operation query telemetry across the graph-RAG query engine and retrieval service. It also adds query stages and tests, and updates PostgreSQL relation reads with timeouts and authorized candidate filtering.

Changes

Query operation observability

Layer / File(s)	Summary
Engine operation measurements components/graph-rag-core/src/main/java/com/orgmemory/graphrag/observability/GraphRagEventSink.java, components/graph-rag-core/src/main/java/com/orgmemory/graphrag/query/LightRagQueryEngine.java, components/graph-rag-testkit/src/test/java/com/orgmemory/graphrag/testkit/LightRagQueryRuntimeConformanceTests.java	The query engine adds observer-aware execution, operation and outcome types, measurements, and timing wrappers. Retrieval, expansion, contribution loading, ranking, and chunk operations report input and output counts. Conformance tests validate bounded measurements.
Retrieval service telemetry core/src/main/java/com/orgmemory/core/knowledge/retrieval/DefaultGraphRagKnowledgeRetrievalService.java, core/src/test/java/com/orgmemory/core/knowledge/retrieval/GraphRagKnowledgeRetrievalServiceTests.java	The retrieval service passes operation IDs, converts query measurements into graph-RAG events, and validates stage, duration, counts, scope fingerprint, and correlation data.
Authorized PostgreSQL relation reads integrations/graph-rag-postgres/src/main/java/com/orgmemory/graphrag/postgres/PostgresGraphStore.java, integrations/graph-rag-postgres/src/test/java/com/orgmemory/graphrag/postgres/PostgresGraphStoreOptionsTests.java	Relation contribution and visible-weight queries apply graph query timeouts and materialized candidate-relation filtering based on authorized endpoint entities. Source inspection tests verify both query properties.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant DefaultGraphRagKnowledgeRetrievalService
  participant LightRagQueryEngine
  participant PostgresGraphStore
  participant GraphRagEventSink
  DefaultGraphRagKnowledgeRetrievalService->>LightRagQueryEngine: executePrepared with operation observer
  LightRagQueryEngine->>PostgresGraphStore: load graph and chunk data
  PostgresGraphStore-->>LightRagQueryEngine: return authorized query data
  LightRagQueryEngine-->>DefaultGraphRagKnowledgeRetrievalService: emit operation measurement
  DefaultGraphRagKnowledgeRetrievalService->>GraphRagEventSink: emit staged query telemetry

Loading

Possibly related PRs

• kl3inIT/OrgMemory#20: Introduced query-engine stages and retrieval operations instrumented by this change.
• kl3inIT/OrgMemory#22: Introduced PostgreSQL retrieval methods updated with authorized candidate filtering.
• kl3inIT/OrgMemory#292: Modified the same retrieval service with related admission-control and telemetry changes.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly describes the primary change: bounding relation authorization hot paths.
Description check	✅ Passed	The description covers the summary, evidence, security semantics, verification, and production acceptance; only the documentation impact section is omitted.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/graphrag-relation-hotpaths

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Tegami

This repository uses Tegami to manage releases. When your changes affect published packages, add a changelog file under .tegami/ before merging.

Create a changelog → · Changelog format

Release preview

Package	Bump	Version
orgmemory	minor	0.2.0 → 0.3.0

This PR does not add changelog files. Pending changelogs from other branches are included in the preview above.

Run pnpm run tegami locally to create a changelog interactively.

_{Managed by Tegami.}