El módulo de cognición estructural de la codebase de AI-LAB (runtime/codebase/) proporciona comprensión determinista y grounded de la estructura del código fuente del propio runtime. Responde tres preguntas operacionales:

1. ¿Cómo es la codebase estructuralmente? — inventario de módulos, grafo de dependencias, topología de dominios
2. ¿Qué se rompe si cambio X? — blast radius analysis mediante recorrido BFS
3. ¿Quién es dueño de qué? — ownership mapping desde rutas de módulos a dominios operacionales

Si accedes a la UI de GitNexus desde un PC remoto y ves “Waiting for server to start”, revisa:

• docs/codebase/gitnexus-local-access.md

runtime/codebase/
├── __init__.py              # Public API exports
├── contracts.py             # Dataclasses, OWNERSHIP_DOMAINS, constants
└── gitnexus_memory.py       # AST scanner, graph builder, risk engine

flowchart TD
  SRC["runtime/*.py"] --> IDX["npx gitnexus analyze<br/>(index-only)"]
  IDX --> GRAPH["Structural graph<br/>(nodes / edges / clusters / flows)"]
  GRAPH --> SIG["Signals<br/>(hotspots, coupling, blast radius, drift)"]
  SIG --> INC["Incident intelligence<br/>(enrichment)"]
  SIG --> GOV["Governance / Validation<br/>(risk gates)"]
  SIG --> REP["Reporting<br/>(operator summary)"]

  NOTE[".gitnexusignore<br/>(governance)"] -.-> IDX
  STATE["runtime/state/*"] -. "excluded" .-> IDX

AI-LAB mantiene tres capas de verdad independientes:

Cada llamada a codebase memory produce un determinant_signature — un hash SHA-256 de la lista de módulos, la lista de edges y el inventario de riesgos. Misma codebase → misma firma. Esto permite:

• Análisis de blast radius reproducible
• Detección de cambios mediante comparación de firmas
• Invariantes de validación que verifican el determinismo

Una caché basada en TTL (por defecto 30 segundos) evita re-escaneos en cada petición. El estado de la caché se expone via get_codebase_cache_state().

_parse_imports() lee cada archivo .py, parsea su AST y extrae todas las sentencias import y from ... import:

for node in ast.walk(tree):
    if isinstance(node, ast.Import):
        for alias in node.names:
            targets.append(alias.name)
    elif isinstance(node, ast.ImportFrom):
        if node.module:
            targets.append(node.module)

Los edges se filtran para incluir solo imports runtime.* entre módulos trackeados.

Cada ruta de módulo se asigna a un dominio operacional via OWNERSHIP_DOMAINS:

El blast radius se calcula mediante recorrido BFS a través de los reverse dependency edges:

for each module:
    impacted = {module}
    queue = [module]
    while queue:
        current = queue.pop(0)
        for dependent, deps in dep_map.items():
            if current in deps and dependent not in visited:
                visited.add(dependent)
                impacted.add(dependent)
                queue.append(dependent)

Clasificación de severidad:

Se identifican tres tipos de riesgo automáticamente:

El módulo importa 5+ otros módulos. Indica que el módulo tiene dependencias externas de amplio alcance.

El módulo es importado por 5+ otros módulos. Indica que el módulo es un hub — los cambios aquí se propagan ampliamente.

Un cambio en el módulo impacta 6+ otros módulos mediante cadenas de dependencias transitivas.

Se detecta cuando el módulo authority es importado por 3+ dominios distintos — indicando concentración de dependencia operacional.

La fórmula del score:

base = 100
base -= high_risks * 5      (max -50)
base -= medium_risks * 2     (max -30)
base -= edge_density penalty (max -15 if density > 5.0)
score = max(10, min(100, base))

Niveles:

Todos los endpoints bajo GET /runtime/codebase/* devuelven JSON con determinant_signature.

GET /runtime/codebase/summary
Response: { contract_version, summary, score, freshness, gitnexus_stats, determinant_signature }

GET /runtime/codebase/modules
Response: { contract_version, modules: [{ path, module_name, domain, file_count }], ... }

GET /runtime/codebase/dependencies
Response: { contract_version, edges: [{ source, target, edge_type }], modules, ... }

GET /runtime/codebase/blast-radius?module_path=gateway
Response: { results: [{ module_path, affected_domains, total_impacted, severity }], ... }

GET /runtime/codebase/ownership
Response: { domains: [{ domain, paths, file_count }], ... }

GET /runtime/codebase/topology
Response: { modules_total, domains_total, edges_total, hotspots, domain_dependency_matrix }

GET /runtime/codebase/risks
Response: { risks: [{ risk_type, domain, severity, description }], score, ... }

GET /runtime/codebase/score
Response: { score: { structural_health_score, level, modules_total, ... } }

Seis counters de Prometheus trackean la codebase memory:

El registry de governance incluye codebase_memory_health como dominio monitorizado. Un structural health score < 50 dispara un flag de degradación en governance.

Cuatro invariantes aseguran la integridad de la codebase memory:

detect_codebase_incidents() se dispara cuando:

• Structural health score < 50 (high/critical)
• High-risk count > 3 (high)
• Wide blast radius detectado (medium)

Los reportes de incidentes se enriquecen con ownership de codebase y hotspots.

compress_codebase_signals() en cognitive_compression.py expone:

• Structural health score y nivel
• High risk count
• Módulos hotspot
• Wide blast radius entries

build_codebase_memory_summary() en reporting_engine.py expone:

• structural_health_score
• modules_total, edges_total
• high_risks, medium_risks
• hotspots, domain_dependencies
• freshness

Ver:

• Safe Refactor Workflow
• Blast Radius Review
• Dependency Risk Analysis
• Runtime-Codebase Correlation
• Incident-to-Module Analysis