feat(api.management): knowledge graph and data source resources

[jsell-rh]

Summary

• Adds KnowledgeGraph resource
• Adds Management context plumbing for Data Sources
• Supports ingestion to, and query from, multiple KnowledgeGraphs

Summary by CodeRabbit

• New Features

  • Management UI/API: create/update/list knowledge graphs and data sources with optional ontology, embedded latest sync run, sync-run logs, and scheduler-triggered syncs.
  • Tenant-scoped graphs and provisioning; per-entity authorization/redaction for read endpoints (Secure Enclave).
  • Ingestion→Extraction job-package pipeline; MCP resource to list accessible knowledge graphs; health endpoints; Mutations Console UX improvements (JSONL editor, large-file mode, live preview, deep-links).

• Bug Fixes

  • Stricter CORS defaults (no wildcard with credentials); group-name trimming/validation; user-provisioning conflict mapped to 409.

• Refactors

  • Expanded sync lifecycle states and clearer mutation/query error semantics; outbox worker graceful shutdown; DB migrations and schema additions.

[coderabbitai]

Actionable comments posted: 9

Note

Due to the large number of review comments, Critical severity comments were prioritized as inline comments.

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)

src/api/graph/infrastructure/age_client.py (1)

128-138: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Return the checked-out connection when connect() fails.

_current_connection is borrowed from the pool before _ensure_graph_exists() / age.setUpAge(). If either raises, the except path never returns it, so repeated bad graph selections can exhaust the pool.

Suggested fix

         try:
             self._current_connection = self._connection_factory.get_connection()
             if self._auto_create:
                 self._ensure_graph_exists()
             # Register AGType parser for automatic conversion of Vertex, Edge, Path objects
             age.setUpAge(self._current_connection, self._graph_name)
             self._connected = True
             self._probe.connected_to_graph(self._graph_name)
         except Exception as e:
             self._connected = False
+            if (
+                self._current_connection is not None
+                and self._connection_factory is not None
+            ):
+                self._connection_factory.return_connection(self._current_connection)
+                self._current_connection = None
             raise DatabaseConnectionError(f"Failed to connect: {e}") from e

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/api/graph/infrastructure/age_client.py` around lines 128 - 138, When
connect() borrows self._current_connection via
self._connection_factory.get_connection() but an exception occurs in
_ensure_graph_exists() or age.setUpAge(), the checked-out connection is never
returned to the pool; update connect() so that on any failure it releases the
borrowed connection before raising DatabaseConnectionError. Concretely, in the
connect() method's except (or a finally) block, if self._current_connection is
not None call the appropriate release method (e.g.,
self._current_connection.close() or
self._connection_factory.release_connection(self._current_connection) /
return_connection) then set self._current_connection = None and self._connected
= False before re-raising the DatabaseConnectionError so the pool is not
exhausted.

src/api/graph/dependencies.py (1)

79-128: ⚠️ Potential issue | 🔴 Critical

Tenant routing mismatch: graph_id not scoped to tenant graph.

get_age_graph_client() correctly scopes the connection to the tenant's graph via get_tenant_graph_name(current_user), but get_graph_query_service() defaults graph_id to the global settings.graph_name.

The repository uses graph_id to filter all Cypher queries (e.g., WHERE m.graph_id = '{self._graph_id}'), so passing the global graph name instead of the tenant-scoped name defeats the isolation. The client connects to the right graph, but query filtering uses the wrong scope, creating a cross-tenant exposure.

Set graph_id to the same tenant-derived value as the client's graph name:

graph_id: str = get_tenant_graph_name(current_user)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/api/graph/dependencies.py` around lines 79 - 128, The graph_id default in
get_graph_query_service is using global settings.graph_name, causing query
filtering to miss the tenant-scoped graph; change graph_id to derive the tenant
graph name from the same current_user used by get_age_graph_client (use
get_tenant_graph_name(current_user)) or compute graph_id inside
get_graph_query_service using the injected client/current_user so the
GraphExtractionReadOnlyRepository and AgeGraphClient use the same tenant graph
(refer to get_tenant_graph_name, get_age_graph_client, get_graph_query_service,
AgeGraphClient, GraphExtractionReadOnlyRepository).

♻️ Duplicate comments (1)

.hyperloop/checks/check-idempotency-tests.sh (1)

113-124: ⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Fix the grep -E alternation syntax in the re-execution patterns.

These patterns still use \|, but Line 130 searches them with grep -E. That prevents valid re-execution tests from matching and causes false “missing test” failures.

Quick verification:

#!/usr/bin/env bash
set -euo pipefail

printf '%s\n' 'handler second invocation' | grep -Eq 'second.*invocation\|invocation.*second' \
  && echo 'escaped_pipe: matched' || echo 'escaped_pipe: no match'

printf '%s\n' 'handler second invocation' | grep -Eq 'second.*invocation|invocation.*second' \
  && echo 'bare_pipe: matched' || echo 'bare_pipe: no match'

Suggested fix

 REEXECUTION_TEST_PATTERNS=(
-  "call.*twice\|twice.*call"
-  "second.*invocation\|invocation.*second"
-  "duplicate.*invoc\|invoc.*duplicate"
-  "retry.*same.*entry\|same.*entry.*retry"
-  "idempoten.*handler\|handler.*idempoten"
-  "second_call\|call_count.*2\|called_twice"
-  "already.*written.*spicedb\|spicedb.*already"
-  "no.*duplicate.*relationship\|relationship.*no.*duplicate"
-  "partial.*failure.*retry\|retry.*partial.*failure"
-  "simulate.*partial\|partial.*fail"
+  "call.*twice|twice.*call"
+  "second.*invocation|invocation.*second"
+  "duplicate.*invoc|invoc.*duplicate"
+  "retry.*same.*entry|same.*entry.*retry"
+  "idempoten.*handler|handler.*idempoten"
+  "second_call|call_count.*2|called_twice"
+  "already.*written.*spicedb|spicedb.*already"
+  "no.*duplicate.*relationship|relationship.*no.*duplicate"
+  "partial.*failure.*retry|retry.*partial.*failure"
+  "simulate.*partial|partial.*fail"
 )

Also applies to: 129-130

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.hyperloop/checks/check-idempotency-tests.sh around lines 113 - 124, The
REEXECUTION_TEST_PATTERNS array contains escaped alternation tokens `\|` which
do not work with grep -E; update each pattern in REEXECUTION_TEST_PATTERNS to
use the POSIX extended alternation `|` (remove the backslashes) so they match
when passed to grep -E, and ensure the code that evaluates these patterns (the
grep -E invocation that iterates over REEXECUTION_TEST_PATTERNS) uses the
corrected strings.

🟡 Minor comments (1)

.hyperloop/checks/check-empty-test-stubs.sh-111-126 (1)

111-126: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fail fast when the target test directory does not exist

If test_dir is wrong/missing, os.walk yields nothing and the script reports PASS, silently disabling this guard. Add an existence check right after Line 111 and exit non-zero on missing directory.

Suggested fix

 test_dir = sys.argv[1]
+if not os.path.isdir(test_dir):
+    print(f"FAIL: test directory not found: {test_dir}", file=sys.stderr)
+    sys.exit(1)
+
 all_stubs: list[tuple[str, int, str]] = []

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.hyperloop/checks/check-empty-test-stubs.sh around lines 111 - 126, After
assigning test_dir, add a directory-existence check (using os.path.isdir or
os.path.exists) and fail fast with a non-zero exit if the directory is missing:
detect if test_dir does not exist, print an explanatory error to stderr (or use
processLogger equivalent), and call sys.exit(1) before calling os.walk; this
ensures the later os.walk loop and check_file(path) calls are not silently
skipped when the target test directory is wrong or missing.

🧹 Nitpick comments (3)

.hyperloop/checks/check-no-coming-soon-stubs.sh (1)

31-69: ⚡ Quick win

Count matching lines, not just “patterns with hits”.

found increments by 1 per pattern that matches at least once (line 57). If you find 200 hits for one pattern, the failure message will still say FAIL: 1 stub pattern(s) found..., which makes CI output less actionable.

If the intent is to fail with the number of matching occurrences, increment by the number of hit lines instead (and update the message accordingly).

🛠️ Proposed fix

-  if [[ -n "$hits" ]]; then
+  if [[ -n "$hits" ]]; then
     echo ""
     echo "--- Stub marker detected (pattern: '$pattern') ---"
     echo "$hits"
-    found=$((found + 1))
+    match_count=$(printf '%s\n' "$hits" | wc -l | tr -d ' ')
+    found=$((found + match_count))
   fi
 done

 echo ""
 if [[ $found -gt 0 ]]; then
-  echo "FAIL: $found stub pattern(s) found in source files."
+  echo "FAIL: $found stub marker hit(s) found in source files."
   echo "Stubs and 'Coming Soon' placeholders are NOT acceptable implementations."
   echo "Either implement the scenario fully or raise a scope blocker before submitting."
   exit 1

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.hyperloop/checks/check-no-coming-soon-stubs.sh around lines 31 - 69, The
script currently increments found by 1 per matching pattern; change it to add
the actual number of matching lines so failures report total occurrences. Inside
the for-loop where you compute hits (variable hits), count matches with
something like count=$(echo "$hits" | sed '/^$/d' | wc -l) or wc -l after
filtering empty lines, then do found=$((found + count)) instead of
found=$((found + 1)); update the final failure message that references found to
reflect "stub marker(s) found" (variables: STUB_PATTERNS, hits, count, found,
SOURCE_DIR).

.hyperloop/checks/check-unused-fixtures.sh (1)

92-151: Verification found no uses of usefixtures in the repository.

The verification script discovered zero instances of @pytest.mark.usefixtures(...) decorators or pytestmark assignments across the codebase, which invalidates the "false negatives" concern from this review. The current scanner's narrower parameter-based detection is sufficient for this codebase's patterns.

The secondary concern about false positives—where arbitrary helper function parameters could match fixture names and make fixtures appear used—remains theoretical without concrete examples in the actual code. If you discover this pattern causing issues in practice, consider refactoring get_all_consumer_param_names() to filter only test and fixture functions rather than all functions.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.hyperloop/checks/check-unused-fixtures.sh around lines 92 - 151, The
scanner currently treats parameters from every function as potential fixture
consumers which can produce false positives; update
get_all_consumer_param_names(tree) to only collect parameters from functions
that are actual tests (name startswith "test_") or from fixture functions (use
get_fixture_names(tree) to identify fixture function names, and include nodes
whose name is in that set), then iterate ast.walk but skip other functions so
only test_ and fixture functions contribute to consumer_params; keep references
to get_all_consumer_param_names, get_fixture_names, and file_has_tests to locate
the relevant logic.

src/api/graph/ports/protocols.py (1)

126-141: 🏗️ Heavy lift

This makes the shared graph port AGE-specific.

GraphQueryExecutorProtocol is documented as a generic graph abstraction, but graph_exists() now bakes in AGE catalog and naming semantics. That forces any non-AGE implementation to emulate an AGE concept or carry dead API surface. Prefer an AGE-specific extension protocol or a backend-neutral capability contract here.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/api/graph/ports/protocols.py` around lines 126 - 141, The
GraphQueryExecutorProtocol.graph_exists method currently embeds AGE-specific
semantics (references to ag_catalog.ag_graph and AGE naming) making the protocol
non-generic; instead, either remove AGE-specific text and make graph_exists a
backend-neutral capability (documenting only that it checks existence of a graph
by name) or move this API into an AGE-specific extension interface (e.g., create
AgeGraphQueryExecutorProtocol that subclasses GraphQueryExecutorProtocol and
owns graph_exists with AGE docs and behavior), update implementations to
implement the new AGE-specific protocol, and ensure callers that need AGE-only
behavior depend on the AGE-specific protocol rather than
GraphQueryExecutorProtocol.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Enterprise

Run ID: 9350e0f4-2d7f-4487-8b4a-8f181cb2262a

📥 Commits

Reviewing files that changed from the base of the PR and between cb4ded8 and 7770840.

📒 Files selected for processing (300)

• .agent-memory/spec-alignment-reviewer.md
• .gitignore
• .hyperloop.yaml
• .hyperloop/agents/kustomization.yaml
• .hyperloop/agents/pm-overlay.yaml
• .hyperloop/agents/process.yaml
• .hyperloop/agents/process/implementer-overlay.yaml
• .hyperloop/agents/process/kustomization.yaml
• .hyperloop/agents/process/process-improvement-overlay.yaml
• .hyperloop/agents/process/verifier-overlay.yaml
• .hyperloop/agents/spec-reviewer.yaml
• .hyperloop/checks/check-all-commits-have-task-ref.sh
• .hyperloop/checks/check-alpha-local-vs-remote.sh
• .hyperloop/checks/check-branch-has-commits.sh
• .hyperloop/checks/check-branch-rebased-on-alpha.sh
• .hyperloop/checks/check-branch-rebases-cleanly.sh
• .hyperloop/checks/check-cascade-delete-cleanup.sh
• .hyperloop/checks/check-cascade-delete-empty-collection-mocks.sh
• .hyperloop/checks/check-cascade-delete-rollback-test.sh
• .hyperloop/checks/check-cited-tests-exist.sh
• .hyperloop/checks/check-di-wiring-updated.sh
• .hyperloop/checks/check-domain-aggregate-mocks.sh
• .hyperloop/checks/check-domain-events-have-consumers.sh
• .hyperloop/checks/check-domain-exception-http-mapping.sh
• .hyperloop/checks/check-empty-test-stubs.sh
• .hyperloop/checks/check-event-handlers-registered.sh
• .hyperloop/checks/check-failure-path-tests.sh
• .hyperloop/checks/check-frontend-deps-resolve.sh
• .hyperloop/checks/check-frontend-lockfile-frozen.sh
• .hyperloop/checks/check-frontend-scenario-labels.sh
• .hyperloop/checks/check-frontend-test-infrastructure.sh
• .hyperloop/checks/check-frontend-tests-exist.sh
• .hyperloop/checks/check-frontend-tests-pass.sh
• .hyperloop/checks/check-frontend-type-check.sh
• .hyperloop/checks/check-idempotency-tests.sh
• .hyperloop/checks/check-implementation-commits-exist.sh
• .hyperloop/checks/check-last-commit-removes-trailers.sh
• .hyperloop/checks/check-new-checks-pass-on-head.sh
• .hyperloop/checks/check-no-api-simulation.sh
• .hyperloop/checks/check-no-check-script-deletions.sh
• .hyperloop/checks/check-no-check-script-modifications.sh
• .hyperloop/checks/check-no-coming-soon-stubs.sh
• .hyperloop/checks/check-no-dead-ports.sh
• .hyperloop/checks/check-no-direct-logger-usage.sh
• .hyperloop/checks/check-no-domain-exception-deletions.sh
• .hyperloop/checks/check-no-duplicate-vue-imports.sh
• .hyperloop/checks/check-no-foreign-task-commits.sh
• .hyperloop/checks/check-no-future-placeholder-comments.sh
• .hyperloop/checks/check-no-multiple-alembic-heads.sh
• .hyperloop/checks/check-no-mypy-violations.sh
• .hyperloop/checks/check-no-repo-port-mocks.sh
• .hyperloop/checks/check-no-route-handler-removals.sh
• .hyperloop/checks/check-no-ruff-violations.sh
• .hyperloop/checks/check-no-source-regressions.sh
• .hyperloop/checks/check-no-state-file-commits.sh
• .hyperloop/checks/check-no-test-regressions.sh
• .hyperloop/checks/check-no-worker-result-staged.sh
• .hyperloop/checks/check-pages-have-tests.sh
• .hyperloop/checks/check-partial-error-assertions.sh
• .hyperloop/checks/check-process-agent-not-on-task-branch.sh
• .hyperloop/checks/check-process-improvement-commit-is-clean.sh
• .hyperloop/checks/check-process-overlay-content-intact.sh
• .hyperloop/checks/check-process-overlays-intact.sh
• .hyperloop/checks/check-property-merge-semantics.sh
• .hyperloop/checks/check-pytest-env-skip-if-set.sh
• .hyperloop/checks/check-route-handler-mock-coverage.sh
• .hyperloop/checks/check-run-backend-suite.sh
• .hyperloop/checks/check-scenario-test-body-alignment.sh
• .hyperloop/checks/check-selector-forwarding.sh
• .hyperloop/checks/check-task-branch-exists.sh
• .hyperloop/checks/check-task-owns-branch-commits.sh
• .hyperloop/checks/check-tautological-frontend-tests.sh
• .hyperloop/checks/check-unused-fixtures.sh
• .hyperloop/checks/check-watch-handler-reload-tests.sh
• .hyperloop/checks/check-weak-test-assertions.sh
• .hyperloop/checks/check-worker-result-not-committed.sh
• .hyperloop/checks/install-git-commit-msg-hook.sh
• .hyperloop/checks/install-git-pre-commit-hook.sh
• .hyperloop/checks/install-process-agent-pre-commit-hook.sh
• .hyperloop/intake/2026-04-26-nfr-index-intake.md
• .hyperloop/intake/2026-04-26-run2-nfr-index-intake.md
• .hyperloop/intake/2026-04-26-run22-nfr-index-final.md
• .hyperloop/intake/2026-04-26-run29-nfr-index-intake.md
• .hyperloop/intake/2026-04-26-run4-nfr-index-intake.md
• .hyperloop/intake/2026-04-26-run5-nfr-index-intake.md
• .hyperloop/intake/2026-04-26-run6-nfr-index-intake.md
• .hyperloop/intake/2026-04-27-nfr-index-intake.md
• .hyperloop/intake/2026-04-27-run40-nfr-index-intake.md
• .hyperloop/intake/2026-04-27-run41-nfr-index-intake.md
• .hyperloop/intake/2026-04-27-run42-nfr-index-intake.md
• .hyperloop/intake/2026-04-27-run49-nfr-index-intake.md
• .hyperloop/intake/2026-04-27-run54-nfr-index-intake.md
• .hyperloop/intake/2026-04-27-run59-nfr-index-intake.md
• .hyperloop/intake/2026-04-27-run60-nfr-index-intake.md
• .hyperloop/intake/2026-04-27-run67-nfr-index-intake.md
• .hyperloop/intake/2026-04-27-run68-nfr-index-intake.md
• .hyperloop/intake/2026-04-27-run72-nfr-index-intake.md
• .hyperloop/intake/2026-04-27-run76-nfr-index-intake.md
• .hyperloop/intake/2026-05-03-query-ui-specs-verification-pass2.md
• .hyperloop/intake/2026-05-03-query-ui-specs-verification-pass3.md
• .hyperloop/intake/2026-05-03-query-ui-specs-verification-pass4.md
• .hyperloop/intake/nfr-and-index-intake.md
• .pre-commit-config.yaml
• env/api.env
• specs/iam/tenants.spec.md
• specs/query/mcp-server.spec.md
• specs/query/query-execution.spec.md
• specs/ui/experience.spec.md
• src/api/extraction/__init__.py
• src/api/extraction/domain/__init__.py
• src/api/extraction/domain/events/__init__.py
• src/api/extraction/domain/events/extraction.py
• src/api/extraction/infrastructure/__init__.py
• src/api/extraction/infrastructure/event_handler.py
• src/api/extraction/ports/__init__.py
• src/api/extraction/ports/services.py
• src/api/graph/application/observability/default_graph_service_probe.py
• src/api/graph/application/observability/graph_service_probe.py
• src/api/graph/application/services/__init__.py
• src/api/graph/application/services/graph_mutation_service.py
• src/api/graph/application/services/graph_query_service.py
• src/api/graph/application/services/graph_secure_enclave.py
• src/api/graph/dependencies.py
• src/api/graph/domain/events/__init__.py
• src/api/graph/domain/events/graph.py
• src/api/graph/domain/value_objects.py
• src/api/graph/infrastructure/age_bulk_loading/queries.py
• src/api/graph/infrastructure/age_bulk_loading/strategy.py
• src/api/graph/infrastructure/age_client.py
• src/api/graph/infrastructure/event_handler.py
• src/api/graph/infrastructure/graph_repository.py
• src/api/graph/infrastructure/tenant_graph_handler.py
• src/api/graph/ports/mutation_log.py
• src/api/graph/ports/protocols.py
• src/api/graph/ports/repositories.py
• src/api/graph/presentation/routes.py
• src/api/health_routes.py
• src/api/iam/dependencies/user.py
• src/api/iam/domain/aggregates/group.py
• src/api/iam/infrastructure/user_repository.py
• src/api/iam/ports/exceptions.py
• src/api/iam/presentation/groups/models.py
• src/api/iam/presentation/tenants/routes.py
• src/api/iam/presentation/workspaces/routes.py
• src/api/infrastructure/mcp_dependencies.py
• src/api/infrastructure/migrations/versions/a2b3c4d5e6f7_add_logs_column_to_sync_runs.py
• src/api/infrastructure/migrations/versions/b3c4d5e6f7a8_add_ontology_json_to_data_sources.py
• src/api/infrastructure/migrations/versions/c0d1e2f3a4b5_add_ontology_jsonb_to_knowledge_graphs.py
• src/api/infrastructure/migrations/versions/d0e1f2a3b4c5_merge_all_heads.py
• src/api/infrastructure/migrations/versions/e1f2a3b4c5d6_expand_sync_run_lifecycle_statuses.py
• src/api/infrastructure/migrations/versions/f183acf6d089_merge_migration_branches.py
• src/api/infrastructure/outbox/models.py
• src/api/infrastructure/outbox/worker.py
• src/api/infrastructure/settings.py
• src/api/ingestion/__init__.py
• src/api/ingestion/application/__init__.py
• src/api/ingestion/application/services/__init__.py
• src/api/ingestion/application/services/ingestion_service.py
• src/api/ingestion/domain/__init__.py
• src/api/ingestion/domain/events/__init__.py
• src/api/ingestion/domain/events/sync.py
• src/api/ingestion/infrastructure/__init__.py
• src/api/ingestion/infrastructure/adapters/__init__.py
• src/api/ingestion/infrastructure/adapters/github.py
• src/api/ingestion/infrastructure/dlt_runner.py
• src/api/ingestion/infrastructure/event_handler.py
• src/api/ingestion/infrastructure/outbox/__init__.py
• src/api/ingestion/infrastructure/outbox/serializer.py
• src/api/ingestion/ports/__init__.py
• src/api/ingestion/ports/adapters.py
• src/api/ingestion/ports/services.py
• src/api/main.py
• src/api/management/application/services/data_source_service.py
• src/api/management/application/services/knowledge_graph_service.py
• src/api/management/application/services/sync_scheduler.py
• src/api/management/dependencies/data_source.py
• src/api/management/dependencies/knowledge_graph.py
• src/api/management/domain/aggregates/data_source.py
• src/api/management/domain/aggregates/knowledge_graph.py
• src/api/management/domain/entities/data_source_sync_run.py
• src/api/management/domain/events/__init__.py
• src/api/management/domain/events/data_source.py
• src/api/management/domain/value_objects.py
• src/api/management/infrastructure/models/data_source.py
• src/api/management/infrastructure/models/data_source_sync_run.py
• src/api/management/infrastructure/models/knowledge_graph.py
• src/api/management/infrastructure/outbox/translator.py
• src/api/management/infrastructure/repositories/data_source_repository.py
• src/api/management/infrastructure/repositories/data_source_sync_run_repository.py
• src/api/management/infrastructure/repositories/knowledge_graph_repository.py
• src/api/management/infrastructure/sync_lifecycle_handler.py
• src/api/management/ports/exceptions.py
• src/api/management/ports/repositories.py
• src/api/management/presentation/__init__.py
• src/api/management/presentation/data_sources/__init__.py
• src/api/management/presentation/data_sources/models.py
• src/api/management/presentation/data_sources/routes.py
• src/api/management/presentation/knowledge_graphs/__init__.py
• src/api/management/presentation/knowledge_graphs/models.py
• src/api/management/presentation/knowledge_graphs/routes.py
• src/api/pyproject.toml
• src/api/query/application/kg_service.py
• src/api/query/application/mcp_secure_enclave.py
• src/api/query/application/observability.py
• src/api/query/application/services.py
• src/api/query/dependencies.py
• src/api/query/domain/value_objects.py
• src/api/query/infrastructure/git_repository.py
• src/api/query/infrastructure/query_repository.py
• src/api/query/infrastructure/tenant_routing.py
• src/api/query/ports/knowledge_graphs.py
• src/api/query/ports/repositories.py
• src/api/query/presentation/mcp.py
• src/api/shared_kernel/graph_primitives/entity_id_generator.py
• src/api/shared_kernel/job_package/__init__.py
• src/api/shared_kernel/job_package/builder.py
• src/api/shared_kernel/job_package/checksum.py
• src/api/shared_kernel/job_package/path_safety.py
• src/api/shared_kernel/job_package/reader.py
• src/api/shared_kernel/job_package/value_objects.py
• src/api/tests/fakes/authorization.py
• src/api/tests/fakes/management.py
• src/api/tests/integration/iam/test_group_service.py
• src/api/tests/integration/iam/test_group_workspace_inheritance.py
• src/api/tests/integration/iam/test_tenant_service.py
• src/api/tests/integration/iam/test_user_repository.py
• src/api/tests/integration/iam/test_workspace_authorization.py
• src/api/tests/integration/iam/test_workspace_rollback.py
• src/api/tests/integration/management/test_data_source_authorization.py
• src/api/tests/integration/management/test_data_source_repository.py
• src/api/tests/integration/management/test_data_source_service.py
• src/api/tests/integration/management/test_data_source_sync_run_repository.py
• src/api/tests/integration/management/test_knowledge_graph_authorization.py
• src/api/tests/integration/management/test_knowledge_graph_repository.py
• src/api/tests/integration/query/__init__.py
• src/api/tests/integration/query/test_kg_resource.py
• src/api/tests/integration/query/test_mcp_auth_http.py
• src/api/tests/integration/test_api_key_auth.py
• src/api/tests/integration/test_auth_enforcement.py
• src/api/tests/integration/test_bulk_loading.py
• src/api/tests/integration/test_query_mcp.py
• src/api/tests/integration/test_query_mcp_http.py
• src/api/tests/integration/test_query_readonly.py
• src/api/tests/integration/test_secure_enclave_mcp.py
• src/api/tests/unit/extraction/__init__.py
• src/api/tests/unit/extraction/infrastructure/__init__.py
• src/api/tests/unit/extraction/infrastructure/test_extraction_event_handler.py
• src/api/tests/unit/graph/application/test_create_define_same_batch_validation.py
• src/api/tests/unit/graph/application/test_graph_secure_enclave.py
• src/api/tests/unit/graph/application/test_knowledge_graph_id_stamping.py
• src/api/tests/unit/graph/application/test_mutation_service.py
• src/api/tests/unit/graph/application/test_schema_learning.py
• src/api/tests/unit/graph/application/test_schema_service.py
• src/api/tests/unit/graph/infrastructure/test_age_bulk_loading_strategy_partitioning.py
• src/api/tests/unit/graph/infrastructure/test_age_query_builder_update_merge.py
• src/api/tests/unit/graph/infrastructure/test_graph_mutation_event_handler.py
• src/api/tests/unit/graph/infrastructure/test_mutation_applier_sort.py
• src/api/tests/unit/graph/infrastructure/test_staging_table_manager.py
• src/api/tests/unit/graph/infrastructure/test_tenant_graph_handler.py
• src/api/tests/unit/graph/presentation/test_routes.py
• src/api/tests/unit/graph/test_application_observability.py
• src/api/tests/unit/graph/test_application_services.py
• src/api/tests/unit/graph/test_domain_value_objects.py
• src/api/tests/unit/graph/test_graph_repository.py
• src/api/tests/unit/graph/test_mutation_tenant_routing.py
• src/api/tests/unit/graph/test_staleness_detection.py
• src/api/tests/unit/graph/test_system_properties.py
• src/api/tests/unit/iam/application/test_api_key_service.py
• src/api/tests/unit/iam/application/test_tenant_service.py
• src/api/tests/unit/iam/domain/test_exceptions.py
• src/api/tests/unit/iam/domain/test_group_aggregate.py
• src/api/tests/unit/iam/domain/test_user_aggregate.py
• src/api/tests/unit/iam/infrastructure/test_user_repository.py
• src/api/tests/unit/iam/presentation/test_api_key_routes.py
• src/api/tests/unit/iam/presentation/test_group_routes.py
• src/api/tests/unit/iam/presentation/test_tenant_bootstrap_routes.py
• src/api/tests/unit/iam/presentation/test_tenant_member_routes.py
• src/api/tests/unit/iam/presentation/test_workspaces_routes.py
• src/api/tests/unit/iam/test_authenticate_dependency.py
• src/api/tests/unit/iam/test_authenticated_user_dependency.py
• src/api/tests/unit/iam/test_tenant_context_dependency.py
• src/api/tests/unit/infrastructure/outbox/test_worker.py
• src/api/tests/unit/infrastructure/test_cors_settings.py
• src/api/tests/unit/infrastructure/test_settings.py
• src/api/tests/unit/ingestion/__init__.py
• src/api/tests/unit/ingestion/application/__init__.py
• src/api/tests/unit/ingestion/application/test_ingestion_service.py
• src/api/tests/unit/ingestion/domain/__init__.py
• src/api/tests/unit/ingestion/domain/test_sync_events.py
• src/api/tests/unit/ingestion/infrastructure/__init__.py
• src/api/tests/unit/ingestion/infrastructure/adapters/__init__.py
• src/api/tests/unit/ingestion/infrastructure/adapters/test_github_adapter.py
• src/api/tests/unit/ingestion/infrastructure/test_dlt_runner.py
• src/api/tests/unit/ingestion/infrastructure/test_ingestion_event_handler.py
• src/api/tests/unit/ingestion/ports/__init__.py
• src/api/tests/unit/ingestion/ports/test_adapter_port.py
• src/api/tests/unit/ingestion/test_architecture.py
• src/api/tests/unit/management/application/test_data_source_service.py
• src/api/tests/unit/management/application/test_knowledge_graph_service.py
• src/api/tests/unit/management/application/test_sync_scheduler.py

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

tmp="$(mktemp -d)"
trap 'rm -rf "$tmp"' EXIT

git init -q "$tmp/src"
cd "$tmp/src"
git config user.email test@example.com
git config user.name test
echo x > f
git add f
git commit -q -m init
git branch -M main

cd "$tmp"
git clone --bare src origin.git >/dev/null 2>&1
git clone -q origin.git work
cd work

printf 'short ref: '
git merge-base HEAD main >/dev/null 2>&1 && echo PASS || echo FAIL

printf 'remote ref: '
git merge-base HEAD origin/main >/dev/null 2>&1 && echo PASS || echo FAIL

Repository: openshift-hyperfleet/kartograph

Length of output: 250

---

🏁 Script executed:

cat -n .hyperloop/checks/check-implementation-commits-exist.sh | head -80

Repository: openshift-hyperfleet/kartograph

Length of output: 3543

---

🏁 Script executed:

rg "feat\(tasks\)" .hyperloop/ --context 3

Repository: openshift-hyperfleet/kartograph

Length of output: 888

---

🏁 Script executed:

rg "feat\|fix\|test" .hyperloop/checks/check-implementation-commits-exist.sh -A 2 -B 2

Repository: openshift-hyperfleet/kartograph

Length of output: 298

---

🏁 Script executed:

rg "feat\(tasks" . --type sh --context 5

Repository: openshift-hyperfleet/kartograph

Length of output: 57

---

🏁 Script executed:

python3 << 'EOF'
import re

# The regex from the script
pattern = r'^[0-9a-f]+ (feat|fix|test)(\([^)]+\))?:'

test_cases = [
    "abc1234 feat: implement thing",
    "abc1234 feat(scope): implement thing",
    "abc1234 feat(tasks): add task",
    "abc1234 fix: fix bug",
    "abc1234 fix(api): fix bug",
    "abc1234 test: add test",
    "abc1234 chore: cleanup",
    "abc1234 chore(intake): intake work",
]

for case in test_cases:
    match = re.match(pattern, case)
    print(f"{'MATCH' if match else 'NO    '}: {case}")
EOF

Repository: openshift-hyperfleet/kartograph

Length of output: 358

---

Fix short ref resolution AND exclude feat(tasks): from implementation detection.

Two issues need fixing:

1. Short ref in remote-only scenarios: Lines 34–36 store only the short branch name even when refs/remotes/origin/<name> exists. In edge cases (shallow clones, specific git configs), git merge-base HEAD main can fail silently, causing the script to exit 0 and skip the check.

2. Regex incorrectly matches feat(tasks):: The regex on line 68 ((feat|fix|test)(\([^)]+\))?:) matches feat(tasks): because [^)]+ includes "tasks". However, the file comments explicitly classify feat(tasks): as a process commit, not implementation work. This causes the script to incorrectly return PASS when only process commits exist.

Suggested fix

-BASE_BRANCH="${1:-}"
+BASE_REF="${1:-}"
 
-if [[ -z "$BASE_BRANCH" ]]; then
+if [[ -z "$BASE_REF" ]]; then
   for candidate in alpha main master; do
-    if git show-ref --verify --quiet "refs/heads/$candidate" 2>/dev/null || \
-       git show-ref --verify --quiet "refs/remotes/origin/$candidate" 2>/dev/null; then
-      BASE_BRANCH="$candidate"
+    if git show-ref --verify --quiet "refs/heads/$candidate" 2>/dev/null; then
+      BASE_REF="$candidate"
+      break
+    elif git show-ref --verify --quiet "refs/remotes/origin/$candidate" 2>/dev/null; then
+      BASE_REF="origin/$candidate"
       break
     fi
   done
 fi
 
-if [[ -z "$BASE_BRANCH" ]]; then
+if [[ -z "$BASE_REF" ]]; then
   echo "WARNING: Could not detect base branch — skipping implementation-commit check."
   exit 0
 fi
 
-MERGE_BASE=$(git merge-base HEAD "$BASE_BRANCH" 2>/dev/null || true)
+MERGE_BASE=$(git merge-base HEAD "$BASE_REF" 2>/dev/null || true)
 if [[ -z "$MERGE_BASE" ]]; then
-  echo "WARNING: Could not compute merge-base with $BASE_BRANCH — skipping check."
+  echo "WARNING: Could not compute merge-base with $BASE_REF — skipping check."
   exit 0
 fi
 
@@ -65,7 +65,7 @@ fi
 # Implementation commit = subject starts with feat:, fix:, or test:
 # (covers both bare and scoped forms: feat(scope):, fix(scope):, test(scope):)
 IMPL_COMMITS=$(git log --oneline "$MERGE_BASE..HEAD" 2>/dev/null \
-  | grep -E '^[0-9a-f]+ (feat|fix|test)(\([^)]+\))?:' || true)
+  | grep -E '^[0-9a-f]+ (feat|fix|test)(\([^)]*\))?:' | grep -v 'feat(tasks):' || true)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.hyperloop/checks/check-implementation-commits-exist.sh around lines 32 -
50, When resolving BASE_BRANCH, don't store only the short name: when the
candidate exists as a local ref use "refs/heads/<candidate>" and when it exists
only on origin use "refs/remotes/origin/<candidate>" so MERGE_BASE uses the full
ref (update the logic that currently sets BASE_BRANCH in the git show-ref checks
to assign the appropriate full ref instead of just "$candidate"); and update the
implementation-commit regex to exclude the process scope "tasks" by using a PCRE
negative lookahead such as '(feat|fix|test)(\((?!tasks\))[^\)]+\))?:' (and
ensure the grep/egrep invocation uses PCRE, e.g. grep -P or adjust code to use
perl-compatible matching) so "feat(tasks):" is not treated as an implementation
commit.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

Use commit-history detection, not net diff, for policy enforcement

git diff --name-only "$MERGE_BASE" HEAD -- "$TARGET_FILE" checks only net tree state. If the file is added and later deleted in the branch, this returns empty and the script incorrectly passes, despite violating the “must never appear in any commit” rule.

Proposed fix

-# Check all diff-filter variants: Added, Copied, Deleted, Modified, Renamed
-touches=$(git diff --name-only "$MERGE_BASE" HEAD -- "$TARGET_FILE" 2>/dev/null || true)
-
-if [[ -z "$touches" ]]; then
+# Detect any commit in range that touches the target file (add/modify/delete/rename).
+offending_commits=$(git log --oneline "$MERGE_BASE"..HEAD -- "$TARGET_FILE" 2>/dev/null || true)
+
+if [[ -z "$offending_commits" ]]; then
   echo "PASS: $TARGET_FILE does not appear in any commit on this branch."
   exit 0
 fi
-
-# Find the specific commits that touch the file for diagnostic output
-offending_commits=$(git log --oneline "$MERGE_BASE"..HEAD -- "$TARGET_FILE" 2>/dev/null || true)

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	# Check all diff-filter variants: Added, Copied, Deleted, Modified, Renamed
	touches=$(git diff --name-only "$MERGE_BASE" HEAD -- "$TARGET_FILE" 2>/dev/null || true)
	if [[ -z "$touches" ]]; then
	echo "PASS: $TARGET_FILE does not appear in any commit on this branch."
	exit 0
	fi
	# Detect any commit in range that touches the target file (add/modify/delete/rename).
	offending_commits=$(git log --oneline "$MERGE_BASE"..HEAD -- "$TARGET_FILE" 2>/dev/null || true)
	if [[ -z "$offending_commits" ]]; then
	echo "PASS: $TARGET_FILE does not appear in any commit on this branch."
	exit 0
	fi

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.hyperloop/checks/check-worker-result-not-committed.sh around lines 85 - 91,
The current check uses git diff --name-only which only reflects net tree changes
and misses files added then deleted; replace that with a commit-history lookup
using git log (e.g. git log --format= --name-only "$MERGE_BASE..HEAD" --
"$TARGET_FILE" 2>/dev/null) or git rev-list -- "$TARGET_FILE" to detect any
commit in the branch that touched TARGET_FILE; update the variable touches to
capture that command's output, keep the same empty-check logic, and preserve
MERGE_BASE and TARGET_FILE variables so the script fails when the file appears
in any commit (even if later removed).

[coderabbitai]

⚠️ Potential issue | 🔴 Critical | 🏗️ Heavy lift

Harden find_nodes_by_slug against Cypher injection.

Line 120 and Line 125 interpolate knowledge_graph_id/slug directly into the Cypher string. This is an injection vector and can bypass intended scoping if crafted input reaches this method.

Suggested hardening (validate dynamic label + escape literals)

+import re
@@
 class GraphExtractionReadOnlyRepository(IGraphReadOnlyRepository):
+    _CYPHER_LABEL_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+    `@staticmethod`
+    def _escape_cypher_literal(value: str) -> str:
+        return value.replace("\\", "\\\\").replace("'", "\\'")
@@
     def find_nodes_by_slug(
         self,
         slug: str,
         node_type: str | None = None,
         knowledge_graph_id: str | None = None,
     ) -> list[NodeRecord]:
@@
-        type_filter = f":{node_type}" if node_type else ""
+        if node_type and not self._CYPHER_LABEL_RE.fullmatch(node_type):
+            raise GraphQueryError(f"Invalid node_type label: {node_type}")
+
+        type_filter = f":{node_type}" if node_type else ""
+        safe_slug = self._escape_cypher_literal(slug)
+        safe_graph_id = self._escape_cypher_literal(self._graph_id)
         kg_filter = (
-            f", knowledge_graph_id: '{knowledge_graph_id}'"
+            f", knowledge_graph_id: '{self._escape_cypher_literal(knowledge_graph_id)}'"
             if knowledge_graph_id
             else ""
         )
         query = f"""
-            MATCH (n{type_filter} {{slug: '{slug}', graph_id: '{self._graph_id}'{kg_filter}}})
+            MATCH (n{type_filter} {{slug: '{safe_slug}', graph_id: '{safe_graph_id}'{kg_filter}}})
             RETURN {{node: n}}
         """

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/api/graph/infrastructure/graph_repository.py` around lines 119 - 126, The
current find_nodes_by_slug builds kg_filter/type_filter and interpolates slug
and knowledge_graph_id directly into the Cypher string (via kg_filter,
type_filter, slug, knowledge_graph_id and self._graph_id), which is an injection
risk; change this to use Cypher query parameters for all user-controlled values
(slug, knowledge_graph_id, self._graph_id) and pass a params dict to the query
execution, and instead of interpolating type_filter as raw text
validate/whitelist the dynamic label value used for type_filter (or map safe
label names) before including it in the query so only known labels are inserted;
ensure the final query uses parameter placeholders and the execution call
supplies the params.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical | 🏗️ Heavy lift

Startup wiring makes ingestion fail for every sync.

IngestionService is constructed with an empty adapter_registry, so any real adapter_type immediately raises and emits IngestionFailed. In the current app wiring, manual and scheduled syncs cannot progress past the first stage.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/api/main.py` around lines 146 - 149, IngestionService is being
initialized with an empty adapter_registry (IngestionService(...
adapter_registry={}, ...)), which causes every ingestion to fail; replace the
empty dict with the actual adapter registry used by the app (or construct and
pass the registry of available adapters) so IngestionService receives real
adapter implementations—locate where adapters are registered (e.g., an existing
adapter_registry, build_adapter_registry(), or AdapterRegistry class) and pass
that variable instead of {} when constructing IngestionService (keep
_JOB_PACKAGE_WORK_DIR as-is).

[coderabbitai]

⚠️ Potential issue | 🔴 Critical | 🏗️ Heavy lift

Extraction is registered in a permanently failing state.

This wrapper always injects _StubExtractionService, so every JobPackageProduced becomes ExtractionFailed. If the real extraction pipeline is not ready yet, this handler should be feature-gated rather than enabled as a guaranteed failure path.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/api/main.py` around lines 188 - 205, The constructor currently hardcodes
_extraction_service = _StubExtractionService(), causing all JobPackageProduced
events to be marked ExtractionFailed; change the initialization in __init__ to
accept the real extraction service via dependency injection (or a factory)
and/or gate registration with a feature flag so the stub is only used in tests:
update __init__ to accept an optional extraction_service parameter (or check a
config flag) and set self._extraction_service accordingly, and ensure handle()
continues to pass that service into ExtractionEventHandler instead of the stub
so the real pipeline is used only when ready.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical | 🏗️ Heavy lift

Graph mutation handling is also hardwired to fail.

This wrapper always injects _StubMutationLogApplier, so any MutationLogProduced will be converted into MutationApplicationFailed. Registering the stage before a real applier exists leaves the back half of the sync pipeline non-functional.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/api/main.py` around lines 234 - 252, The constructor currently hardwires
_mutation_log_applier to _StubMutationLogApplier which causes
MutationLogProduced events to be turned into MutationApplicationFailed; change
__init__ to accept an optional mutation_log_applier parameter (or provide a
setter) and set self._mutation_log_applier = provided_applier or
_StubMutationLogApplier(); keep handle untouched other than using
self._mutation_log_applier when constructing GraphMutationEventHandler so a real
applier can be injected later instead of always using the stub.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical | 🏗️ Heavy lift

Secret-store writes and deletes can escape the DB transaction.

Create/update call secret_store.store() before commit(), while delete calls secret_store.delete() before commit(). A later DB failure leaves you with orphaned secrets, partially applied credential rotations, or rows that still exist but no longer have credentials.

Also applies to: 384-394, 499-507

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/api/management/application/services/data_source_service.py` around lines
178 - 188, The secret-store write/delete happen before committing the DB
transaction (see raw_credentials, cred_path, self._secret_store.store,
self._ds_repo.save, self._session.commit), which can leave orphaned secrets if
the DB commit later fails; fix by deferring secret-store operations until after
a successful DB commit: commit the DB change first, then call
self._secret_store.store(...) (or delete) and then persist the resulting
credentials_path to the datasource row with a subsequent save+commit (or if you
prefer, record pending secret ops and execute them in a follow-up step only
after commit); apply the same change to the other places that call
self._secret_store.store/delete.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical | 🏗️ Heavy lift

Don’t delete secrets inside the DB savepoint.

self._secret_store.delete() is irreversible, but the surrounding transaction can still roll back later. That can leave restored data-source rows pointing at credentials that were already deleted.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/api/management/application/services/knowledge_graph_service.py` around
lines 475 - 492, The code currently calls self._secret_store.delete() inside the
database nested transaction (inside async with self._session.begin_nested()),
which is irreversible and may be executed even if the DB transaction later rolls
back; instead, collect the credentials_path values (via ds.credentials_path) for
data-sources found by self._ds_repo.find_by_knowledge_graph(kg_id) while still
inside the transaction, perform ds.mark_for_deletion(...) and await
self._ds_repo.delete(ds) and kg.mark_for_deletion(...) / await
self._kg_repo.delete(kg) as before, commit the DB work with await
self._session.commit(), and only after a successful commit iterate the collected
credential paths and call self._secret_store.delete(path=...,
tenant_id=self._scope_to_tenant) (or skip if self._secret_store is None),
handling/ logging any secret-store errors separately so DB state and secret
deletions remain consistent.

[coderabbitai]

⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

Redaction misses entities returned inside lists.

_process_value() only descends into dicts. Queries like RETURN collect(n) or nested arrays of node/edge dicts bypass authorization entirely and can leak unauthorized payloads.

Suggested fix

     async def _process_value(self, value: Any) -> Any:
         """Recursively process a single value.
@@
-        if isinstance(value, dict):
+        if isinstance(value, list):
+            return [await self._process_value(item) for item in value]
+        if isinstance(value, tuple):
+            return tuple([await self._process_value(item) for item in value])
+        if isinstance(value, dict):
             if _is_edge_dict(value):
                 return await self._authorize_edge(value)
             if _is_node_dict(value):
                 return await self._authorize_node(value)
             # Plain dict (map result or nested structure) — recurse
             return {k: await self._process_value(v) for k, v in value.items()}

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	async def _process_value(self, value: Any) -> Any:
	"""Recursively process a single value.
	Dispatch table:
	- EdgeDict → ``_authorize_edge``
	- NodeDict → ``_authorize_node``
	- dict → recurse into values (map result)
	- other → pass through (scalar)
	EdgeDict is checked BEFORE NodeDict because EdgeDict is a strict
	superset of NodeDict's fields.
	"""
	if isinstance(value, dict):
	if _is_edge_dict(value):
	return await self._authorize_edge(value)
	if _is_node_dict(value):
	return await self._authorize_node(value)
	# Plain dict (map result or nested structure) — recurse
	return {k: await self._process_value(v) for k, v in value.items()}
	# Scalar (int, str, float, bool, None, list, …) — no entity to check
	return value
	async def _process_value(self, value: Any) -> Any:
	"""Recursively process a single value.
	Dispatch table:
	- EdgeDict → ``_authorize_edge``
	- NodeDict → ``_authorize_node``
	- dict → recurse into values (map result)
	- list/tuple → recurse into items
	- other → pass through (scalar)
	EdgeDict is checked BEFORE NodeDict because EdgeDict is a strict
	superset of NodeDict's fields.
	"""
	if isinstance(value, list):
	return [await self._process_value(item) for item in value]
	if isinstance(value, tuple):
	return tuple([await self._process_value(item) for item in value])
	if isinstance(value, dict):
	if _is_edge_dict(value):
	return await self._authorize_edge(value)
	if _is_node_dict(value):
	return await self._authorize_node(value)
	# Plain dict (map result or nested structure) — recurse
	return {k: await self._process_value(v) for k, v in value.items()}
	# Scalar (int, str, float, bool, None) — no entity to check
	return value

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/api/query/application/mcp_secure_enclave.py` around lines 120 - 141,
_process_value currently only recurses into dicts so node/edge dicts inside
lists/tuples are skipped; update _process_value to also detect sequence types
(at least list and tuple) and recursively call self._process_value on each
element, returning the same sequence type (e.g., list or tuple) so results from
queries like RETURN collect(n) or nested arrays are authorized; keep existing
branch logic that calls _authorize_edge and _authorize_node for dicts and reuse
those helpers when processing list/tuple elements to ensure nested entity dicts
are handled.

[coderabbitai]

Actionable comments posted: 5

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.hyperloop/agents/process/implementer-overlay.yaml:
- Around line 68-70: Update the overlay rule that forbids committed changes
under `.hyperloop/checks/` to add an explicit exception when the task's spec
itself includes changes to `.hyperloop/checks/`; specifically modify the policy
text around the existing prohibition lines (the two bullets referencing
`.hyperloop/checks/` and "spec-scoped edits") so it allows commits to
`.hyperloop/checks/` only when the Task-Ref/spec explicitly lists those files,
and ensure the check script `check-no-check-script-modifications.sh` and any
gating logic consult the task spec before treating such modifications as a hard
block; keep the strict local-fix guidance for other cases and document the
exception in the overlay.

In @.hyperloop/checks/check-commit-msg-hook-has-guard.sh:
- Around line 36-41: The script assumes the commit hook lives at
"$GIT_DIR/hooks/commit-msg" which breaks for linked worktrees and custom hooks
paths; instead resolve the hooks directory via Git and use that path when
setting HOOK_FILE. Replace usages of GIT_DIR/hooks with a resolved HOOK_DIR from
git rev-parse --git-path hooks (e.g., HOOK_DIR="$(git rev-parse --git-path hooks
2>/dev/null)") and set HOOK_FILE="$HOOK_DIR/commit-msg", handling errors if git
rev-parse fails; update the GIT_DIR and HOOK_FILE variables accordingly in the
script.

In @.hyperloop/checks/check-run-backend-suite.sh:
- Around line 59-97: The CHECKS array in the check-run-backend-suite.sh file is
missing two mandatory scripts (check-service-route-coverage.sh and
check-no-domain-exception-deletions.sh), allowing the suite to report ALL PASS
while required checks remain unenforced; update the CHECKS array to include
these two script names (add check-service-route-coverage.sh and
check-no-domain-exception-deletions.sh) in a logical place among related checks
(e.g., near other route/domain checks) so the suite runs them as part of the
authoritative submit gate.
- Around line 45-52: The script normalizes to the repo root with cd "$REPO_ROOT"
but doesn't fail if that cd fails; ensure the suite stops on failure by making
the cd operation fail-fast. Replace the bare cd "$REPO_ROOT" with a
fail-on-error pattern (e.g., make the script exit if cd fails or enable errexit)
so the check using PWD/REPO_ROOT cannot continue when cd "$REPO_ROOT" does not
succeed.

In `@src/api/main.py`:
- Around line 288-290: Replace the silent except block that currently reads
"except Exception: pass" with proper logging: locate the "except Exception:" in
src/api/main.py (the scheduler/error-handling block) and call the module's
logger (e.g., logger.exception(...) or process_logger.error(...) with exception
info) so the exception and stack trace are recorded while still allowing the
scheduler loop to continue; ensure you include a clear contextual message like
"Scheduler loop error" and preserve the non-crashing behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Enterprise

Run ID: 4ca7ffd7-f565-486b-9ee2-02e49ee97731

📥 Commits

Reviewing files that changed from the base of the PR and between 7770840 and 87cca3d.

📒 Files selected for processing (10)

• .hyperloop/agents/process/implementer-overlay.yaml
• .hyperloop/checks/check-commit-msg-hook-has-guard.sh
• .hyperloop/checks/check-run-backend-suite.sh
• .hyperloop/intake/2026-05-04-query-ui-specs-intake.md
• .hyperloop/intake/2026-05-04-query-ui-specs-pass3.md
• src/api/main.py
• src/api/shared_kernel/job_package/checksum.py
• src/api/tests/integration/iam/test_tenant_api.py
• src/api/tests/integration/test_query_mcp.py
• src/api/tests/integration/test_query_mcp_http.py

✅ Files skipped from review due to trivial changes (1)

• .hyperloop/intake/2026-05-04-query-ui-specs-intake.md

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Add an exception for tasks whose spec explicitly changes .hyperloop/checks/.

Line 68 allows spec-scoped edits, but Line 69 then bans committed changes under .hyperloop/checks/ outright. That makes legitimate process/CI tasks impossible to complete under this overlay.

Possible fix

-  - Never commit modifications to files in `.hyperloop/checks/` on a task branch: check-script edits are process-improvement work regardless of which Task-Ref the commit carries; if a check script produces a false positive that blocks the backend suite, apply the fix locally WITHOUT committing it (so the suite passes for this run), then document the issue for the orchestrator — check-no-check-script-modifications.sh detects any modified pre-existing scripts and is a hard suite block.
+  - Never commit modifications to files in `.hyperloop/checks/` on a task branch unless the task spec explicitly requires a process/check change. For ordinary feature work, treat check-script edits as out of scope; if a pre-existing check produces a false positive, apply the fix locally WITHOUT committing it and escalate it separately. When the spec does require process/check work, that change is in scope and must be validated like any other deliverable.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.hyperloop/agents/process/implementer-overlay.yaml around lines 68 - 70,
Update the overlay rule that forbids committed changes under
`.hyperloop/checks/` to add an explicit exception when the task's spec itself
includes changes to `.hyperloop/checks/`; specifically modify the policy text
around the existing prohibition lines (the two bullets referencing
`.hyperloop/checks/` and "spec-scoped edits") so it allows commits to
`.hyperloop/checks/` only when the Task-Ref/spec explicitly lists those files,
and ensure the check script `check-no-check-script-modifications.sh` and any
gating logic consult the task spec before treating such modifications as a hard
block; keep the strict local-fix guidance for other cases and document the
exception in the overlay.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/usr/bin/env bash
set -euo pipefail

echo "git-dir:        $(git rev-parse --git-dir)"
echo "git-common-dir: $(git rev-parse --git-common-dir)"
echo "core.hooksPath: $(git config --path core.hooksPath 2>/dev/null || echo '<unset>')"
echo

for path in \
  "$(git rev-parse --git-dir)/hooks/commit-msg" \
  "$(git rev-parse --git-common-dir)/hooks/commit-msg"
do
  if [[ -f "$path" ]]; then
    echo "present  $path"
  else
    echo "missing  $path"
  fi
done

hooks_path="$(git config --path core.hooksPath 2>/dev/null || true)"
if [[ -n "$hooks_path" ]]; then
  if [[ -f "$hooks_path/commit-msg" ]]; then
    echo "present  $hooks_path/commit-msg"
  else
    echo "missing  $hooks_path/commit-msg"
  fi
fi

Repository: openshift-hyperfleet/kartograph

Length of output: 238

---

🏁 Script executed:

cat -n .hyperloop/checks/check-commit-msg-hook-has-guard.sh

Repository: openshift-hyperfleet/kartograph

Length of output: 3984

---

🏁 Script executed:

# Check git command availability and documentation for git-common-dir and core.hooksPath
git rev-parse --help | grep -A 2 "git-common-dir" || echo "git-common-dir not found in help"
git config --help | grep -A 2 "core.hooksPath" || echo "core.hooksPath not found in help"

Repository: openshift-hyperfleet/kartograph

Length of output: 355

---

🏁 Script executed:

# Test the git commands used in the proposed fix
cd .git 2>/dev/null && cd .. || true

echo "Testing git rev-parse --git-common-dir:"
git rev-parse --git-common-dir 2>&1

echo ""
echo "Testing git config --path core.hooksPath:"
git config --path core.hooksPath 2>&1 || true

echo ""
echo "Testing git rev-parse --git-dir:"
git rev-parse --git-dir 2>&1

Repository: openshift-hyperfleet/kartograph

Length of output: 213

---

🏁 Script executed:

# Check if there are other instances of hook path hard-coding
rg "hooks/commit-msg|GIT_DIR.*hooks" --type sh

Repository: openshift-hyperfleet/kartograph

Length of output: 57

---

🏁 Script executed:

# Check the install script to see if it also has path resolution issues
cat -n .hyperloop/checks/install-git-commit-msg-hook.sh 2>/dev/null | head -50

Repository: openshift-hyperfleet/kartograph

Length of output: 2318

---

Resolve the hook path through Git, not $GIT_DIR/hooks.

commit-msg is not guaranteed to live under $GIT_DIR/hooks: linked worktrees use the common Git dir, and core.hooksPath can relocate hooks entirely. In those setups this check hard-fails even when the hook is installed and active.

Possible fix

 GIT_DIR="$(git rev-parse --git-dir 2>/dev/null)" || {
   echo "WARNING: Not inside a git repository — skipping commit-msg hook check."
   exit 0
 }
 
-HOOK_FILE="$GIT_DIR/hooks/commit-msg"
+HOOKS_DIR="$(git config --path core.hooksPath 2>/dev/null || true)"
+if [[ -z "$HOOKS_DIR" ]]; then
+  HOOKS_DIR="$(git rev-parse --git-common-dir 2>/dev/null)/hooks"
+fi
+
+HOOK_FILE="$HOOKS_DIR/commit-msg"

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	GIT_DIR="$(git rev-parse --git-dir 2>/dev/null)" || {
	echo "WARNING: Not inside a git repository — skipping commit-msg hook check."
	exit 0
	}
	HOOK_FILE="$GIT_DIR/hooks/commit-msg"
	GIT_DIR="$(git rev-parse --git-dir 2>/dev/null)" || {
	echo "WARNING: Not inside a git repository — skipping commit-msg hook check."
	exit 0
	}
	HOOKS_DIR="$(git config --path core.hooksPath 2>/dev/null || true)"
	if [[ -z "$HOOKS_DIR" ]]; then
	HOOKS_DIR="$(git rev-parse --git-common-dir 2>/dev/null)/hooks"
	fi
	HOOK_FILE="$HOOKS_DIR/commit-msg"

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.hyperloop/checks/check-commit-msg-hook-has-guard.sh around lines 36 - 41,
The script assumes the commit hook lives at "$GIT_DIR/hooks/commit-msg" which
breaks for linked worktrees and custom hooks paths; instead resolve the hooks
directory via Git and use that path when setting HOOK_FILE. Replace usages of
GIT_DIR/hooks with a resolved HOOK_DIR from git rev-parse --git-path hooks
(e.g., HOOK_DIR="$(git rev-parse --git-path hooks 2>/dev/null)") and set
HOOK_FILE="$HOOK_DIR/commit-msg", handling errors if git rev-parse fails; update
the GIT_DIR and HOOK_FILE variables accordingly in the script.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Fail fast if changing to the repo root does not succeed.

Without set -e, a failed cd "$REPO_ROOT" leaves the suite running from the wrong directory, which brings back the false-PASS pathspec problem this script is trying to eliminate.

Possible fix

 if [[ "$PWD" != "$REPO_ROOT" ]]; then
   echo "⚠  NOTICE: Suite invoked from $PWD"
   echo "   Normalizing CWD to repo root: $REPO_ROOT"
   echo "   (Running from a subdirectory causes git pathspecs to silently"
   echo "    match nothing — all content checks would produce false PASSes.)"
   echo ""
 
-  cd "$REPO_ROOT"
+  cd "$REPO_ROOT" || {
+    echo "ERROR: Failed to change directory to repo root: $REPO_ROOT"
+    exit 1
+  }
 fi

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	if [[ "$PWD" != "$REPO_ROOT" ]]; then
	echo "⚠ NOTICE: Suite invoked from $PWD"
	echo " Normalizing CWD to repo root: $REPO_ROOT"
	echo " (Running from a subdirectory causes git pathspecs to silently"
	echo " match nothing — all content checks would produce false PASSes.)"
	echo ""
	cd "$REPO_ROOT"
	fi
	if [[ "$PWD" != "$REPO_ROOT" ]]; then
	echo "⚠ NOTICE: Suite invoked from $PWD"
	echo " Normalizing CWD to repo root: $REPO_ROOT"
	echo " (Running from a subdirectory causes git pathspecs to silently"
	echo " match nothing — all content checks would produce false PASSes.)"
	echo ""
	cd "$REPO_ROOT" || {
	echo "ERROR: Failed to change directory to repo root: $REPO_ROOT"
	exit 1
	}
	fi

🧰 Tools

🪛 Shellcheck (0.11.0)

[warning] 51-51: Use 'cd ... || exit' or 'cd ... || return' in case cd fails.

(SC2164)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.hyperloop/checks/check-run-backend-suite.sh around lines 45 - 52, The
script normalizes to the repo root with cd "$REPO_ROOT" but doesn't fail if that
cd fails; ensure the suite stops on failure by making the cd operation
fail-fast. Replace the bare cd "$REPO_ROOT" with a fail-on-error pattern (e.g.,
make the script exit if cd fails or enable errexit) so the check using
PWD/REPO_ROOT cannot continue when cd "$REPO_ROOT" does not succeed.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

The “definitive PASS gate” still skips some mandatory checks.

The new overlay says this suite is the authoritative submit gate, but the list here does not run check-service-route-coverage.sh or check-no-domain-exception-deletions.sh. A branch can therefore print RESULT: ALL PASS while missing checks the process file still marks as required.

Possible fix

   check-no-ruff-violations.sh
   check-no-mypy-violations.sh
+  check-no-domain-exception-deletions.sh
   check-no-source-regressions.sh
+  check-service-route-coverage.sh
   check-no-route-handler-removals.sh
   check-no-test-regressions.sh

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.hyperloop/checks/check-run-backend-suite.sh around lines 59 - 97, The
CHECKS array in the check-run-backend-suite.sh file is missing two mandatory
scripts (check-service-route-coverage.sh and
check-no-domain-exception-deletions.sh), allowing the suite to report ALL PASS
while required checks remain unenforced; update the CHECKS array to include
these two script names (add check-service-route-coverage.sh and
check-no-domain-exception-deletions.sh) in a logical place among related checks
(e.g., near other route/domain checks) so the suite runs them as part of the
authoritative submit gate.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Exception silently swallowed despite comment claiming to log.

The comment says "Log but don't crash" but no logging is performed. Silent exception swallowing hides scheduler failures, database connectivity issues, and other critical problems. Add actual logging so operational visibility into scheduler health is maintained.

🔧 Proposed fix

+import logging
+
+logger = logging.getLogger(__name__)
+
 async def _run_scheduler_loop(session_factory: Any, poll_interval: int) -> None:
     ...
         except asyncio.CancelledError:
             break
         except Exception:
-            # Log but don't crash — scheduler must remain resilient
-            pass
+            # Log but don't crash — scheduler must remain resilient
+            logger.exception("Scheduler loop iteration failed")

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	except Exception:
	# Log but don't crash — scheduler must remain resilient
	pass
	except Exception:
	# Log but don't crash — scheduler must remain resilient
	logger.exception("Scheduler loop iteration failed")

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/api/main.py` around lines 288 - 290, Replace the silent except block that
currently reads "except Exception: pass" with proper logging: locate the "except
Exception:" in src/api/main.py (the scheduler/error-handling block) and call the
module's logger (e.g., logger.exception(...) or process_logger.error(...) with
exception info) so the exception and stack trace are recorded while still
allowing the scheduler loop to continue; ensure you include a clear contextual
message like "Scheduler loop error" and preserve the non-crashing behavior.

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.hyperloop/agents/process/implementer-overlay.yaml:
- Line 27: Two remediation entries conflict: one mandates using "git rebase -i
$(git merge-base HEAD alpha)" for excising committed protocol artifact files,
while another permits "git reset --soft HEAD~1" for HEAD-only violations; make
them mutually exclusive by updating the YAML text to state that "git reset
--soft HEAD~1" is allowed only when the offending artifact commit exists solely
at HEAD and has not been pushed or merged, and require the interactive rebase
"git rebase -i $(git merge-base HEAD alpha)" for any case where the artifact
appears earlier in branch history or has been pushed/merged; explicitly cite
both commands ("git reset --soft HEAD~1" and "git rebase -i $(git merge-base
HEAD alpha)") in the remediation section so readers know which to use based on
whether the violation is HEAD-only versus present in branch history.
- Line 35: The rule banning cherry-picks ("Never cherry-pick commits from alpha,
process-improvement branches, or any other branch...") is too broad and
conflicts with the permitted recovery step that requires cherry-picking delivery
commits onto a clean branch when foreign commits added files; update the ban to
add an explicit exception allowing cherry-picking delivery commits onto a clean
branch solely as part of the recovery/cleanup workflow (keep reference to the
existing check-no-foreign-task-commits.sh and the recovery step that mentions
cherry-picking delivery commits) so the cleanup path remains legal while
preserving the original intent to forbid arbitrary cherry-picks.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Enterprise

Run ID: 7b75517e-cae3-4d69-be70-30c101b061e0

📥 Commits

Reviewing files that changed from the base of the PR and between 87cca3d and a9306f8.

📒 Files selected for processing (1)

• .hyperloop/agents/process/implementer-overlay.yaml

[coderabbitai]

🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Resolve the conflicting history-fix instructions.

Line 27 says interactive rebase is the only valid remediation, but Line 37 allows git reset --soft HEAD~1 for the same class of violation when it is confined to HEAD. Those rules are mutually exclusive as written.

Suggested wording

-  - When any protocol artifact file (.hyperloop/worker-result.yaml, .hyperloop/state/**) is accidentally committed, the ONLY correct fix is `git rebase -i $(git merge-base HEAD alpha)` to excise the commit from history; adding a deletion commit does NOT fix the violation because check-worker-result-not-committed.sh flags deletions in branch history as well as additions.
+  - When any protocol artifact file (.hyperloop/worker-result.yaml, .hyperloop/state/**) is accidentally committed, the fix MUST excise the offending commit from history; use `git rebase -i $(git merge-base HEAD alpha)` by default. If `.hyperloop/worker-result.yaml` appears only in `HEAD`, `git reset --soft HEAD~1` followed by unstaging the file and recommitting is also acceptable. Adding a deletion commit does NOT fix the violation because check-worker-result-not-committed.sh flags deletions in branch history as well as additions.

Also applies to: 37-37

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.hyperloop/agents/process/implementer-overlay.yaml at line 27, Two
remediation entries conflict: one mandates using "git rebase -i $(git merge-base
HEAD alpha)" for excising committed protocol artifact files, while another
permits "git reset --soft HEAD~1" for HEAD-only violations; make them mutually
exclusive by updating the YAML text to state that "git reset --soft HEAD~1" is
allowed only when the offending artifact commit exists solely at HEAD and has
not been pushed or merged, and require the interactive rebase "git rebase -i
$(git merge-base HEAD alpha)" for any case where the artifact appears earlier in
branch history or has been pushed/merged; explicitly cite both commands ("git
reset --soft HEAD~1" and "git rebase -i $(git merge-base HEAD alpha)") in the
remediation section so readers know which to use based on whether the violation
is HEAD-only versus present in branch history.

[coderabbitai]

🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick win

Narrow the cherry-pick ban so the cleanup path stays legal.

Line 35 forbids cherry-picking from “any other branch”, but Line 50 later requires cherry-picking delivery commits onto a clean branch when foreign commits added files. Without an explicit exception, the recovery path reads as prohibited by the earlier rule.

Suggested wording

-  - Never cherry-pick commits from alpha, process-improvement branches, or any other branch onto your task branch: The only valid way to incorporate new upstream commits is `git fetch origin && git branch -f alpha origin/alpha && git rebase alpha`; cherry-picking creates duplicate commits with different hashes that (a) carry a foreign Task-Ref and immediately fail check-no-foreign-task-commits.sh, and (b) produce rebase conflicts when alpha later absorbs the same changes.
+  - Never cherry-pick upstream commits from alpha or process-improvement branches onto your task branch: The only valid way to incorporate new upstream commits is `git fetch origin && git branch -f alpha origin/alpha && git rebase alpha`; cherry-picking upstream commits creates duplicate hashes, foreign Task-Refs, and later rebase conflicts. The only exception is the clean-branch rescue flow below, which cherry-picks this task's own delivery commits onto a fresh branch.

Also applies to: 50-50

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.hyperloop/agents/process/implementer-overlay.yaml at line 35, The rule
banning cherry-picks ("Never cherry-pick commits from alpha, process-improvement
branches, or any other branch...") is too broad and conflicts with the permitted
recovery step that requires cherry-picking delivery commits onto a clean branch
when foreign commits added files; update the ban to add an explicit exception
allowing cherry-picking delivery commits onto a clean branch solely as part of
the recovery/cleanup workflow (keep reference to the existing
check-no-foreign-task-commits.sh and the recovery step that mentions
cherry-picking delivery commits) so the cleanup path remains legal while
preserving the original intent to forbid arbitrary cherry-picks.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/api/main.py (1)

484-485: 💤 Low value

Consider exposing lifespan context through the proxy's public interface.

Accessing mcp_http_app_proxy._app directly couples this code to the proxy's internal structure. If the proxy already has a public refresh() method, it should also provide a public way to enter the lifespan context (e.g., a lifespan_context() method or making the proxy itself a context manager).

♻️ Suggested pattern

-    mcp_http_app_proxy.refresh()
-    async with mcp_http_app_proxy._app.lifespan(app):
+    mcp_http_app_proxy.refresh()
+    async with mcp_http_app_proxy.lifespan_context(app):
         yield

This would require adding a lifespan_context method to the proxy class.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/api/main.py` around lines 484 - 485, The code currently accesses
mcp_http_app_proxy._app.lifespan(app) directly which couples to internals; add a
public lifespan context to the proxy (e.g., a lifespan_context(self, app) method
or implement __enter__/__exit__ / __aenter__/__aexit__ so the proxy is a context
manager) that returns/delegates to self._app.lifespan(app), then replace the
direct use of mcp_http_app_proxy._app.lifespan(app) with
mcp_http_app_proxy.lifespan_context(app) (or use "async with
mcp_http_app_proxy:" if you make it a context manager) and keep calling
mcp_http_app_proxy.refresh() as before.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.hyperloop/intake/2026-05-04-query-ui-specs-pass4.md:
- Line 44: The blockquote line ">  AND when unscoped, queries span all knowledge
graphs the user can access in the tenant" has two spaces after the ">" causing
markdownlint MD027; edit that blockquote (the line starting with ">  AND when
unscoped...") to use a single space after ">" ("> AND when unscoped, queries
span all knowledge graphs the user can access in the tenant").

---

Nitpick comments:
In `@src/api/main.py`:
- Around line 484-485: The code currently accesses
mcp_http_app_proxy._app.lifespan(app) directly which couples to internals; add a
public lifespan context to the proxy (e.g., a lifespan_context(self, app) method
or implement __enter__/__exit__ / __aenter__/__aexit__ so the proxy is a context
manager) that returns/delegates to self._app.lifespan(app), then replace the
direct use of mcp_http_app_proxy._app.lifespan(app) with
mcp_http_app_proxy.lifespan_context(app) (or use "async with
mcp_http_app_proxy:" if you make it a context manager) and keep calling
mcp_http_app_proxy.refresh() as before.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Enterprise

Run ID: e392b852-a23f-41d0-a1ca-57a5f814eac1

📥 Commits

Reviewing files that changed from the base of the PR and between a9306f8 and eb9108b.

📒 Files selected for processing (3)

• .hyperloop/intake/2026-05-04-query-ui-specs-pass4.md
• src/api/main.py
• src/api/query/presentation/mcp.py

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Fix markdownlint MD027 in blockquote spacing (Line 44).

There are two spaces after > in the blockquote, which triggers MD027. Use a single space.

Suggested patch

->  AND when unscoped, queries span all knowledge graphs the user can access in the tenant"
+> AND when unscoped, queries span all knowledge graphs the user can access in the tenant"

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	> AND when unscoped, queries span all knowledge graphs the user can access in the tenant"
	> AND when unscoped, queries span all knowledge graphs the user can access in the tenant"

🧰 Tools

🪛 markdownlint-cli2 (0.22.1)

[warning] 44-44: Multiple spaces after blockquote symbol

(MD027, no-multiple-space-blockquote)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @.hyperloop/intake/2026-05-04-query-ui-specs-pass4.md at line 44, The
blockquote line ">  AND when unscoped, queries span all knowledge graphs the
user can access in the tenant" has two spaces after the ">" causing markdownlint
MD027; edit that blockquote (the line starting with ">  AND when unscoped...")
to use a single space after ">" ("> AND when unscoped, queries span all
knowledge graphs the user can access in the tenant").