# Analysis Readiness Follow-Up Findings

Date: 2026-03-28

## Purpose

Track the follow-up findings discovered during the important-repo analysis audit.

This document focuses on three structural gaps that still block efficient and reliable cross-module analysis, even if deployment/config repositories are added into the KB later.

The items are recorded in the requested order:

1. Drift/freshness mechanism and reverse indexes
2. Source-of-truth and confidence status
3. Unified entity model and naming mapping

Actual implementation should still follow the dependency order:

1. drift/freshness and reverse indexes
2. source-of-truth and confidence status
3. unified entity model and naming mapping

## Context

Related documents:

- `construction/important-repos-analysis-audit.md`
- `construction/important-repos-analysis-audit-report.md`

Current high-level conclusion:

- runtime-side scan is already useful in some repositories
- deployment/config source evidence exists in local repos
- cross-module analysis is still not analysis-ready because KB joins are fragile, expensive, and hard to verify

## 3. Drift/Freshness Mechanism and Reverse Indexes

### Current Symptoms

- KB outputs do not consistently record which source commit they came from.
- There is no stable freshness signal for deciding whether a KB conclusion is still trustworthy.
- Cross-module analysis is mostly forward-oriented:
  - runtime service -> dependency
- Reverse lookup is still weak:
  - config key -> consumers
  - cluster -> deployed services
  - namespace -> workloads
  - external resource -> affected modules

### Why This Matters

Without freshness metadata, an answer may look precise while actually being based on stale data.

Without reverse indexes, impact analysis remains expensive. This blocks questions like:

- which services consume this config object
- which repos are affected by this cluster change
- which modules depend on this external endpoint

### Minimum Viable Implementation

Every tracked KB artifact should carry:

- `source_repo`
- `source_commit`
- `scanned_at`
- `freshness_status`

Suggested `freshness_status` values:

- `fresh`
- `stale`
- `unknown`
- `blocked`

Minimal freshness rules:

- `fresh`: KB `source_commit` matches current source baseline
- `stale`: source repo moved forward and relevant directories changed
- `unknown`: source repo or commit is unavailable
- `blocked`: scan/update failed or schema cannot be applied

Reverse indexes should be stored as dedicated lookup artifacts, not mixed into raw scan files.

Recommended first indexes:

- `by-service`
- `by-config-group`
- `by-configmap`
- `by-cluster`
- `by-namespace`
- `by-external-resource`

Each reverse-index record should contain at least:

- `entity_type`
- `entity_id`
- `producers`
- `consumers`
- `evidence`
- `last_verified_at`

### Tracking Checklist

- [ ] Define common freshness fields for all KB artifacts
- [ ] Add freshness status to existing runtime scan outputs
- [ ] Define stale-detection rules by repo type
- [ ] Create first reverse-index schema
- [ ] Generate first reverse indexes for `oneconfig`, `app-delivery`, and `tidb-management-service`
- [ ] Validate one impact-analysis workflow using only reverse indexes

### Exit Condition

This item is complete only when a user can ask one reverse-impact question and the KB can answer it without opening raw source trees.

## 2. Source-of-Truth and Confidence Status

### Current Symptoms

- The KB does not consistently declare which repo is authoritative for which truth domain.
- Some facts are derived from runtime code, some from config repos, some from deployment manifests, but the authority boundary is implicit.
- When different repos encode overlapping values, there is no tracked conflict status.
- Confidence is mostly implicit in narrative judgment rather than structured metadata.

### Why This Matters

Cross-module analysis is not only about finding data. It is about knowing which evidence should dominate when multiple sources differ.

Without explicit source-of-truth metadata, the KB can easily produce:

- correct facts with weak justification
- conflicting conclusions with no conflict marker
- answers that are difficult to review or trust

### Minimum Viable Implementation

Track source-of-truth by truth domain, not by repo only.

Examples of truth domains:

- runtime method dependency
- runtime default config
- runtime delivered config
- service rollout target
- platform topology
- environment mapping

Each tracked conclusion should include:

- `truth_domain`
- `authoritative_source`
- `supporting_sources`
- `confidence`
- `conflict_status`

Suggested `confidence` values:

- `high`
- `medium`
- `low`

Suggested `conflict_status` values:

- `none`
- `suspected`
- `confirmed`

Minimal confidence rules:

- `high`: direct tracked evidence from the authoritative source, no conflict
- `medium`: strong evidence exists but cross-repo join still needs some inference
- `low`: evidence depends mainly on naming similarity, comments, or manual interpretation

### Tracking Checklist

- [ ] Define initial truth-domain taxonomy
- [ ] Define common source-of-truth fields
- [ ] Create authoritative-source table for important repo domains
- [ ] Mark confidence on existing important-repo conclusions
- [ ] Add conflict markers for overlapping config/deployment/runtime facts
- [ ] Review one real conflict example end to end

### Exit Condition

This item is complete only when a KB answer can state:

- what truth domain it belongs to
- which source is authoritative
- what the confidence is
- whether any conflict exists

## 1. Unified Entity Model and Naming Mapping

### Current Symptoms

- The same logical object can appear under different names in different repos.
- Runtime binaries, runtime services, deployment units, namespaces, config groups, and external resources do not yet share canonical IDs.
- Many joins currently depend on string similarity or human interpretation.

Examples:

- runtime binary name
- Argo application name
- deployment directory name
- namespace-local service name
- proto service name
- config group or configmap name

### Why This Matters

If entity identity is unstable, every cross-repo join remains brittle.

Even after deployment/config outputs enter the KB, analysis will still degrade if the system cannot reliably say:

- these two names refer to the same thing
- this deployment unit runs that runtime service
- this config group configures that service set

### Minimum Viable Implementation

Start with a small core entity set:

- `repo`
- `binary`
- `runtime_service`
- `deployment_unit`
- `config_group`
- `cluster`
- `namespace`
- `external_resource`

Each entity should have a stable canonical ID.

Example shapes:

- `repo:tidbcloud/tidb-management-service`
- `binary:tidbcloud/tidb-management-service:dedicated-global-service/cmd/dedicated-global-service`
- `runtime_service:tidb-management-service/dedicated-global-service`
- `deployment_unit:app-delivery/dedicated-global-service`
- `config_group:oneconfig/eventbus`
- `cluster:dev-base-us-west-2`
- `namespace:dev-base-us-west-2/tidb-management-service`
- `external_resource:kubernetes:///config-center.devops:8080`

Add alias and relationship mapping as a dedicated layer.

Minimum relationship types:

- `same_as`
- `deployed_as`
- `runs_in`
- `configured_by`
- `depends_on`

### Tracking Checklist

- [ ] Define core entity types
- [ ] Define canonical ID format for each type
- [ ] Create alias mapping schema
- [ ] Create relationship mapping schema
- [ ] Build sample mappings across `tidb-management-service`, `app-delivery`, and `oneconfig`
- [ ] Validate one end-to-end join using canonical IDs only

### Exit Condition

This item is complete only when at least one full cross-repo analysis path can be resolved through canonical IDs and explicit relationship mappings rather than string guessing.

## Recommended Execution Order

Even though the findings are recorded as `3 -> 2 -> 1`, implementation should follow this order:

1. Drift/freshness mechanism and reverse indexes
2. Source-of-truth and confidence status
3. Unified entity model and naming mapping

Reason:

- freshness decides whether evidence is safe to trust
- source-of-truth decides how to resolve overlapping evidence
- entity model then gives the joins a stable identity layer

## Immediate Next Actions

Recommended first concrete slice:

1. Define common metadata fields for freshness and confidence
2. Apply them to:
   - `tidb-management-service`
   - `oneconfig`
   - `app-delivery`
3. Build one reverse index:
   - `by-service`
4. Build one canonical mapping set:
   - runtime service <-> deployment unit <-> config group

## Status

Current status of all three items: `not started`