topological-visibility 1.0.0

Deterministic architectural auditing for large codebases. Discover and validate your system's structure.

Topological Visibility System

4D Architecture Discovery & Audit Tool

Discover and audit the hidden structure of your codebase across 5 registers: Code, Governance, Data, Knowledge, and Deployment.

What It Does

The Topological Visibility System automatically maps your architecture across:

1. Code Register — All Python source files, imports, exports, dependencies
2. Governance Register — Project structure, shops/teams, manifests, policies
3. Data Register — Databases, schemas, cardinality, storage footprint
4. Knowledge Register — Documentation, structure, cross-references
5. Deployment Register — Services, artifacts, deployment status

Then it audits for:

• Orphans — Code without governance, data without owners
• Dependencies — Import cycles, gravity wells, critical paths
• Coherence — Cross-register alignment, consistency
• Decay — Trends, drift, breach forecasting
• Impact — Blast radius analysis for changes

Quick Start

1. Initialize Your Project

python -m src.product.cli init --name "MyProject"

This creates topological.yaml with sensible defaults.

2. Run a Full Report

python -m src.product.cli report --config topological.yaml

This produces:

• data/MyProject_register.json — Full unified register
• data/audit_report.json — Comprehensive audit findings

3. Check Health

python -m src.product.cli health --config topological.yaml

Quick status: HEALTHY or list of issues.

Commands

topological init

Create a default topological.yaml configuration.

python -m src.product.cli init --name "MyProject" --output topological.yaml

topological scan

Run all discoverers (extract metadata from 5 registers).

python -m src.product.cli scan --config topological.yaml --output data/register.json

Outputs: JSON with all souls, shops, databases, documents, artifacts.

topological audit

Run all auditors (analyze the register).

python -m src.product.cli audit --config topological.yaml --register data/register.json

Outputs: JSON with all audit findings (errors, warnings, info).

topological health

Quick health check (scan + audit, brief output).

python -m src.product.cli health --config topological.yaml

Returns exit code 0 (healthy) or 1 (issues found).

topological report

Full scan + audit + report.

python -m src.product.cli report --config topological.yaml --output-dir data/

Outputs both register and audit report.

Configuration

Edit topological.yaml to customize:

project_name: MyProject
root_path: .
description: Topology configuration for MyProject

code_register:
  enabled: true
  root_path: src
  include_patterns:
    - "*.py"
  exclude_patterns:
    - "__pycache__/*"
    - "*.pyc"

governance_register:
  enabled: true
  root_path: shops
  include_patterns:
    - "*.yaml"
    - "*.yml"

data_register:
  enabled: true
  root_path: data
  include_patterns:
    - "*.db"
    - "*.sqlite3"

knowledge_register:
  enabled: true
  root_path: docs
  include_patterns:
    - "*.md"

deployment_register:
  enabled: true
  root_path: ""

auditors:
  enabled: true
  strict_mode: false
  phi_floor: 0.618
  checks:
    unmapped_souls: true
    cycles: true
    orphans: true
    coherence: true
    manifest: true
    decay: true
    impact: true

output_dir: data
output_format: json
verbose: false

Output Formats

Register (JSON)

Structure:

{
  "metadata": {
    "project_name": "MyProject",
    "root_path": "/path/to/project",
    "scan_timestamp": "2026-05-27T14:02:00",
    "schema_version": "1.0"
  },
  "code_register": {
    "souls": {
      "soul_name": {
        "path": "src/soul_name.py",
        "imports": ["dependency1", "dependency2"],
        "exports": ["function1", "class1"],
        "has_pulse": true,
        "commit_frequency": 0.5,
        "last_update_days_ago": 5
      }
    }
  },
  "governance_register": {
    "shops": {
      "shop_name": {
        "path": "shops/shop_name",
        "souls": ["soul1", "soul2"],
        "phi_score": 0.9,
        "semantic_drift": 0.1
      }
    }
  },
  "data_register": {
    "databases": {
      "data/db.db": {
        "tables": [
          {
            "name": "users",
            "columns": ["id", "name"],
            "row_count": 1000
          }
        ],
        "size_mb": 5.2
      }
    }
  },
  "knowledge_register": {
    "documents": {
      "docs/README.md": {
        "size_bytes": 2500,
        "headings": ["Installation", "Usage"],
        "cross_references": ["src/soul.py", "docs/guide.md"]
      }
    }
  },
  "deployment_register": {
    "artifacts": {
      "service1": {
        "path": "worker/service1",
        "artifact_type": "worker"
      }
    }
  }
}

Audit Report (JSON)

Structure:

{
  "timestamp": "2026-05-27T14:02:00",
  "total_audits": 7,
  "total_findings": 12,
  "errors": 0,
  "warnings": 12,
  "info": 5,
  "is_healthy": true,
  "health_status": "HEALTHY",
  "audit_reports": [
    {
      "name": "Soul Registry (#1)",
      "errors": 0,
      "warnings": 1,
      "info": 0,
      "errors_detail": [],
      "warnings_detail": [
        {
          "code": "SOULS_UNMAPPED",
          "message": "177 souls exist in code but not listed in any SHOP.yaml",
          "affected_items": ["soul1", "soul2"],
          "metadata": {"count": 177}
        }
      ]
    }
  ]
}

Auditors (7 Critical Audits)

#1: Soul Registry

Creates canonical index of all code-level entities (souls).

Detects:

• Unmapped souls (code without governance)
• Missing souls (referenced but don't exist)

#2: Dependency Auditor

Builds import graph and analyzes dependencies.

Detects:

• Cycles (broken architecture)
• Gravity wells (critical dependencies, SPOFs)
• Isolated souls

#3: Orphan Auditor

Checks for misalignment between code and data.

Detects:

• Orphaned data/ directories (no corresponding soul)
• Stateless souls (no corresponding data)

#4: Coherence Auditor

Cross-register validation.

Detects:

• Souls not in governance
• Souls with no data directories
• Shops referencing missing souls
• Docs with broken references

#5: Manifest Validator

Validates governance manifests (SHOP.yaml, LEDGER.md, STATE.md).

Detects:

• Invalid phi scores
• Invalid semantic drift
• Empty LEDGERs

#6: Decay Forecaster

Analyzes φ-score trends and predicts breach dates.

Detects:

• Phi breaches (< 0.618 floor)
• Declining phi scores
• High semantic drift

#7: Impact Analyzer

Analyzes blast radius for code/governance changes.

Detects:

• Critical souls (3+ dependents)
• Large shops (10+ souls)
• Infrastructure change risks

Use Cases

1. Architecture Visibility

topological report --config topological.yaml

Understand your full architecture: what modules exist, who imports what, what data they own.

2. Governance Auditing

topological health --config topological.yaml

Quick health check: are all code modules listed in governance? Are LEDGERs current?

3. Impact Analysis (before refactoring)

topological audit --config topological.yaml
# Check "Impact Analyzer" section for blast radius

Know which souls are critical before changing them.

4. Decay Forecasting

topological audit --config topological.yaml
# Check "Decay Forecaster" section for breach dates

When will your governance φ-scores breach the floor? Plan maintenance.

5. Orphan Cleanup

topological audit --config topological.yaml
# Check "Orphan Auditor" for stale data dirs

Which data directories have no corresponding code?

Example Projects

See examples/ for configs for:

• Python packages
• Monorepos
• Django projects
• Flask services
• Custom architectures

Installation

# As part of matrix-cr-studio
cd matrix-cr-studio
python -m src.product.cli --help

# Or standalone (future)
pip install topological
topological --help

Output

Results are JSON (ready for downstream tools, dashboards, APIs):

• *_register.json — Unified architecture model
• audit_report.json — Audit findings and metrics

Philosophy

Determinism over guessing. The tool doesn't use ML classifiers or heuristics. It scans actual code, actual configuration, actual databases. Findings are facts, not probabilistic.

Geometry over sequential. Instead of reading files line-by-line, you get a unified 5D model (code × governance × data × knowledge × deployment). See the shape of your system.

Actionable over alarming. Findings are specific (affected items listed) and auditable (metadata included). No generic warnings.

---

Built by Matrix CR Studio
4D Architecture for High-Stakes Claims