# Root Call Graph Task

Date: 2026-03-30

## Goal

Build a capability similar to "gc trace object from root".

Given a first backend entrypoint API as the root, return the transitive call graph triggered by that root.

Required graph semantics:

- node = `service + api/method name`
- directed edge = `caller -> callee`
- edges represent concrete call relationships
- graph should preserve known call conditions when available
- graph should distinguish service-to-service edges from infrastructure leaves when useful

Example root from the discussion:

- `tidb-mgmt-portal.ListClusters`

Expected conceptual result:

- start from the first backend entrypoint
- traverse downstream calls
- return the complete call graph reachable from that root

## Important Scope Clarification

The current KB is **not sufficient** to guarantee a fully complete end-to-end runtime call graph for every possible root.

However, the KB is already sufficient to support a **v0 implementation** if the root is constrained to:

- a method that belongs to an already deep-scanned primary-service binary

That means:

- `tidb-mgmt-service.ClusterService.ListClusters` is a viable v0 root
- `tidb-mgmt-portal.ListClusters` is **not** a fully supported v0 root yet

Reason:

- `tidb-mgmt-portal` is currently not deep-scanned into method-level `interfaces` and `service-mapping`

## What The User Actually Wants

The underlying user need is:

1. choose one API entrypoint as a root
2. follow the call chain downstream
3. produce a graph where each node is `service + api`
4. return the graph as a query result, not as prose analysis

This should behave like a reusable capability, not a one-off manual investigation.

## Current KB State

### 1. Strongest Existing Input: `tidb-management-service`

`tidb-management-service` is the best current foundation for this task.

It has already been deep-scanned across 6 primary-service binaries and 603 methods.

Evidence:

- `knowledge/repos/tidb-management-service/deep-scan-state.json`
- `expected_binaries` and `scanned_binaries` are complete
- `statistics.total_methods = 603`

Relevant lines:

- `knowledge/repos/tidb-management-service/deep-scan-state.json:7`
- `knowledge/repos/tidb-management-service/deep-scan-state.json:53`

### 2. Method-Level Interface Inventory Exists

For already scanned binaries, the KB has method-level interface definitions.

Example:

- `tidb-mgmt-service.ClusterService.ListClusters`

Evidence:

- `knowledge/repos/tidb-management-service/interfaces/tidb-mgmt-service-cmd-tidb-mgmt-service.json:37`

This shows:

- service name = `ClusterService`
- method name = `ListClusters`

### 3. Method-Level Dependency Mapping Exists

For already scanned binaries, the KB also has method-level dependency entries.

Example:

- `ClusterService.CreateServerlessCluster` already records downstream service calls

Evidence:

- `knowledge/repos/tidb-management-service/service-mapping/tidb-mgmt-service-cmd-tidb-mgmt-service.json:18`

That entry already records:

- downstream service name
- `target_interface`
- `target_repo`
- `operation_type`
- `conditions`
- human-readable operation details

This is already enough to construct a service-method dependency graph for some roots.

### 4. Some Methods Still Have Empty Downstream Edges

Not every method currently has non-empty service edges.

Examples:

- `tidb-mgmt-service.ClusterService.ListClusters`
- `dedicated-global-service.ClusterService.ListClusters`
- `nextgen-global-service.ClusterService.ListClusters`

Evidence:

- `knowledge/repos/tidb-management-service/service-mapping/tidb-mgmt-service-cmd-tidb-mgmt-service.json:6`
- `knowledge/repos/tidb-management-service/service-mapping/dedicated-global-service-cmd-dedicated-global-service.json:451`
- `knowledge/repos/tidb-management-service/service-mapping/nextgen-global-service-cmd-nextgen-global-service.json:681`

Implication:

- interface coverage is high
- dependency edge completeness is still uneven
- "no downstream edge recorded" does **not** always mean "no downstream call exists"

### 5. `tidb-mgmt-portal` Is Not Yet In Scope

This is the most important blocker for the user's example root.

Current state:

- `tidb-mgmt-portal` exists in repo metadata
- but it is treated as an `admin_cli` binary
- and it was explicitly skipped in the deep-scan task

Evidence:

- `knowledge/repos/tidb-management-service/meta.json:131`
- `construction/deep-scan-all-repos.md:56`

Implication:

- the KB currently does not provide method-level interface inventory for portal handlers
- the KB currently does not provide portal -> first-backend-service call edges
- therefore `tidb-mgmt-portal.ListClusters` cannot yet be used as a reliable root for a complete call graph

## What The Current KB Is Sufficient For

The KB is sufficient for:

1. selecting a root from already scanned primary-service methods
2. building a transitive graph across recorded method-level service calls
3. including infrastructure leaves such as MySQL, CRD, HTTP endpoint, or other recorded dependency types when present
4. annotating each edge with conditions and evidence
5. marking graph completeness as partial where the KB has gaps

In other words, the KB supports a **best-effort transitive dependency graph from a scanned backend root**.

## What The Current KB Is Not Sufficient For

The KB is not yet sufficient for:

1. using `tidb-mgmt-portal` as a first-class root
2. claiming full runtime completeness for all service paths
3. reconstructing local in-process function call graphs inside a service method
4. covering asynchronous side effects exhaustively
5. guaranteeing that empty `services: []` means "terminal node"

This limitation is consistent with the existing query guide.

Evidence:

- `knowledge/deployment/deployment-artifact-query-guide.md`

That guide already states the current artifact set does **not** fully answer:

- complete runtime call graphs for every service and bundle

## Recommended Deliverable Strategy

Do not aim for the full ideal feature first.

Split execution into two phases.

### Phase 1: Ship A V0 That Is Honest About Coverage

Input:

- root must be an already scanned method
- format recommendation:
  - `repo/binary/service.method`
  - example:
    - `tidb-management-service/tidb-mgmt-service/ClusterService.ListClusters`

Output:

- directed graph
- node format:
  - `service`
  - `method`
  - optional `repo`
  - optional `binary`
- edge format:
  - `from`
  - `to`
  - `edge_type`
  - `condition`
  - `target_repo`
  - `evidence_file`
  - `evidence_method_key`
  - `confidence`
- optional infrastructure leaf nodes:
  - MySQL table operation
  - HTTP endpoint
  - external service

Behavior:

- traverse only graph edges that are explicitly present in `service-mapping`
- if a callee is present in KB and has its own method-level dependency entry, continue traversal
- if a method exists but has no outgoing recorded edges, stop there and mark coverage as `unknown_or_terminal`

### Phase 2: Expand Root Coverage

After v0 works, expand to:

1. deep-scan `tidb-mgmt-portal`
2. deep-scan other BFF / portal / gateway layers
3. add explicit coverage metadata to each scanned method:
   - `edge_coverage`
   - `scan_confidence`
   - `may_have_unresolved_internal_calls`

Only after that should the system advertise support for roots like:

- `tidb-mgmt-portal.ListClusters`

## Suggested Data Model

Use a dedicated query artifact or generator output instead of only answering from raw per-repo files.

Recommended graph node schema:

```json
{
  "node_id": "node:tidb-mgmt-service:ClusterService.ListClusters",
  "repo": "tidbcloud/tidb-management-service",
  "binary": "tidb-mgmt-service",
  "service": "ClusterService",
  "method": "ListClusters",
  "kind": "service_method"
}
```

Recommended edge schema:

```json
{
  "edge_id": "edge:tidb-mgmt-service:ClusterService.CreateServerlessCluster->serverless-global-service:ServerlessService.Create",
  "from_node": "node:tidb-mgmt-service:ClusterService.CreateServerlessCluster",
  "to_node": "node:serverless-global-service:ServerlessService.Create",
  "edge_type": "grpc_unary",
  "conditions": ["Always"],
  "target_repo": "tidbcloud/tidb-management-service",
  "evidence_file": "knowledge/repos/tidb-management-service/service-mapping/tidb-mgmt-service-cmd-tidb-mgmt-service.json",
  "evidence_method_key": "ClusterService.CreateServerlessCluster",
  "confidence": "recorded"
}
```

Recommended query result envelope:

```json
{
  "root": "tidb-management-service/tidb-mgmt-service/ClusterService.ListClusters",
  "support_level": "v0",
  "completeness": "partial",
  "nodes": [],
  "edges": [],
  "warnings": []
}
```

## Suggested Execution Plan For The Next Session

### Step 1: Build A Global Method Index

Aggregate from:

- `knowledge/repos/*/interfaces/*.json`
- `knowledge/repos/*/service-mapping/*.json`
- `knowledge/repos/*/deep-scan-state.json`

Build:

- method identity index
- root parser
- service-method node registry

### Step 2: Build A Traversal Engine

Traversal rule:

- start from root method key
- read outgoing `services[]`
- map each `target_interface` to a known node when possible
- recurse until no known outgoing edges remain

Need explicit handling for:

- target interface matches by exact `service.method`
- target interface matches by HTTP signature
- target interface points outside currently scanned KB

### Step 3: Add Coverage Warnings

Warnings should include at least:

- root not scanned
- root belongs to skipped binary
- callee service exists but no deep-scan artifact exists
- method exists but has no recorded downstream edges
- edge target cannot be resolved to a known node

### Step 4: Test With Known Roots

Recommended first test roots:

1. `tidb-management-service/tidb-mgmt-service/ClusterService.CreateServerlessCluster`
   Reason:
   - already has recorded downstream service calls
   - should produce a non-trivial graph

2. `tidb-management-service/tidb-mgmt-service/ClusterService.ListClusters`
   Reason:
   - should demonstrate a partial graph with infrastructure leaves only

3. `tidb-management-service/dedicated-global-service/ClusterService.ListClusters`
   Reason:
   - should demonstrate a method that exists but currently has empty outgoing edges

4. `tidb-management-service/tidb-mgmt-portal/ListClusters`
   Reason:
   - should fail with an explicit "root not supported yet" message

## Acceptance Criteria For A Good V0

The next session should consider the task successful if it can provide:

1. a documented root format
2. a traversal implementation over current KB data
3. a machine-readable graph result
4. explicit completeness / support-level metadata
5. explicit warnings when coverage is partial
6. at least one successful non-trivial traced example
7. one clear unsupported example using `tidb-mgmt-portal`

## Non-Goals For V0

The next session should **not** attempt to solve all of these immediately:

- exact in-process function call graph inside a service
- dynamic dispatch reconstruction
- async worker and eventbus completeness
- full UI/portal/BFF coverage
- cross-language code tracing outside scanned artifacts

## Most Important Implementation Principle

Do not silently turn KB incompleteness into false certainty.

The feature should prefer:

- "partial graph with warnings"

over:

- "complete-looking graph with unstated gaps"

That is the key constraint if this capability is to be trustworthy.