🧹 DecayZero

Autonomous AI-Driven Software Portfolio Telemetry, AST Analysis, and Automated Deprecation System

---

📖 The Layman's Breakdown

1. Problem Statement

In large software organizations, hundreds of microservices, features, and API endpoints are built every year. Over time, many of these features stop being used.

When usage drops, engineering leaders face a difficult dilemma:

• Is the feature truly useless (Bloat)? If so, it is wasting expensive cloud servers, slowing down test pipelines, and creating security vulnerabilities.
• Or is the feature actually valuable, but users simply don't know it exists or struggle to find it (Discovery Friction / Ignorance)?

Until now, answering this required months of tedious manual cross-referencing between codebase repositories, APM logs (Datadog), analytics dashboards (PostHog), and engineering teams. As a result, companies keep paying thousands of dollars for zombie code out of fear of breaking something.

---

2. The Solution

DecayZero is an autonomous AI janitor for enterprise software.

It continuously monitors your codebases and live production traffic to solve that exact dilemma:

1. When it finds Discovery Friction (Ignorance): It detects that users are performing tedious manual workarounds for something a feature already solves. It automatically drafts and sends in-app and Slack enablement nudges so users discover the tool.
2. When it finds Zero-Substance Utility (Bloat): It confirms that nobody is calling the code, no other service imports it, and no gateway routes reach it. It then autonomously creates a safe, test-verified GitHub Pull Request to cleanly remove the dead code and save cloud costs.

---

3. How It Works (Step-by-Step)

  ┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
  │ 1. Scan Codebase│ ────> │ 2. Query APM    │ ────> │ 3. Calculate    │
  │    (AST Parser) │       │    (PostHog/DD) │       │    Net Utility  │
  └─────────────────┘       └─────────────────┘       └────────┬────────┘
                                                               │
                                                               v
  ┌─────────────────────────────────────────────────────────────────────┐
  │                    4. Classify into 4 Quadrants                     │
  └───────┬─────────────────┬─────────────────┬─────────────────┬───────┘
          │                 │                 │                 │
          v                 v                 v                 v
   [ Q1: Core Value ] [ Q2: Ignorance ]  [ Q3: True Bloat ]  [ Q4: Whitelist ]
    Active Monitoring   Slack Nudge CTA   Two-Phase Prune PR  SLA/Tax Exemption

1. Static AST Call-Graph Scan: Uses tree-sitter to parse TypeScript, Python, and Rust source code, mapping every function and counting incoming references.
2. Runtime Gateway & APM Telemetry: Queries Datadog and PostHog via the Model Context Protocol (MCP) to check real traffic over a 60-day rolling window.
3. Net Utility Scoring: Computes a balance between the value a feature provides and the cost (server compute, maintenance complexity) required to keep it alive.
4. Two-Phase Tombstoning (HTTP 410 Gone): When deprecating code, DecayZero first injects a 14-day observation shim. If unexpected traffic ever hits it, the system automatically rolls back and alerts the team before physical deletion.

---

🏛️ System Architecture

graph TB
    subgraph Frontend["Frontend Cockpit (/apps/cockpit)"]
        UI["Next.js 16 Cyber Cockpit"]
        Matrix["4-Quadrant HITL Triage Matrix"]
        MCPHub["MCP Management Hub"]
        Policies["Policy & SLA Whitelist Editor"]
        TelemetryView["Telemetry Visualizer"]
    end

    subgraph Backend["Janitor Daemon (/apps/janitor-daemon)"]
        AxumAPI["Axum REST Engine (:8088)"]
        AST["Tree-sitter AST Multi-Language Parser"]
        Evaluator["Net Utility & 4-Quadrant Classifier"]
        GitSand["Sandboxed Git PR Generator & Tiered CI Gate"]
        MCPClient["MCP Protocol Runner"]
    end

    subgraph Storage["Embedded Storage"]
        DB[("SQLite LibSQL Store (data/decayzero.db)")]
    end

    subgraph External["External Ecosystem via MCP"]
        PH["PostHog Analytics MCP"]
        DD["Datadog APM / OTel MCP"]
        Slack["Slack Bot MCP"]
        GH["GitHub Octocrab MCP"]
    end

    UI --> AxumAPI
    AxumAPI --> DB
    AxumAPI --> AST
    AxumAPI --> Evaluator
    AxumAPI --> GitSand
    AxumAPI --> MCPClient
    MCPClient --> PH
    MCPClient --> DD
    MCPClient --> Slack
    MCPClient --> GH

Loading

---

📐 Mathematical Formulation

The Net Utility Formula

$$\text{Net_Utility} = \frac{\text{Task_Completion_Rate} \times \text{Estimated_Time_Saved_Hrs}}{\text{Inference_COGS} + \text{Entropy_Score} + \text{Verification_Tax}}$$

Variable	Description
$\text{Task_Completion_Rate}$	Percentage ($0.0 - 1.0$) of sessions that successfully complete the user workflow.
$\text{Estimated_Time_Saved_Hrs}$	Hours saved by using the automation over manual alternatives.
$\text{Inference_COGS}$	Direct compute, GPU/LLM token, or infrastructure cost in USD.
$\text{Entropy_Score}$	Codebase complexity, cyclomatic depth, and AST maintenance weight.
$\text{Verification_Tax}$	Ongoing automated test runtime and CI/CD validation latency.

---

⚡ Quick Start Guide

Prerequisites

• Rust (v1.80+)
• Node.js (v18+ or v20+)
• Git

1. Clone the Repository

git clone https://github.com/TamTunnel/Decayzero.git
cd Decayzero

2. Start the Backend Janitor Daemon (Rust)

# Compiles and launches Axum REST API on http://127.0.0.1:8088
cargo run --manifest-path apps/janitor-daemon/Cargo.toml

3. Start the Governance Cockpit (Next.js)

# In a new terminal tab:
npm --prefix apps/cockpit run dev

Open http://localhost:3000 in your browser to access the Cockpit.

---

⚙️ Environment Variables

All variables include built-in fallback defaults. You can override them by creating a .env file in the root directory:

Variable	Default Value	Description
PORT / DECAYZERO_PORT	8088	Port for the Rust Axum REST API server.
HOST / DECAYZERO_HOST	0.0.0.0	Network host interface to bind.
DECAYZERO_DB_PATH	./data/decayzero.db	Path to the SQLite LibSQL database.
TARGET_REPO_ROOT	./demo-repo	Target repository root for AST scanning.
NEXT_PUBLIC_API_URL	http://127.0.0.1:8088	Backend REST URL for Cockpit frontend.
RUST_LOG	info	Tracing logger verbosity (debug, info, warn).
POSTHOG_API_KEY	(Mock / Demo Key)	PostHog MCP API authentication key.
DATADOG_API_KEY	(Mock / Demo Key)	Datadog APM / OTel MCP application key.
SLACK_WEBHOOK_URL	(Mock Webhook)	Incoming webhook for Slack enablement nudges.
GITHUB_TOKEN	(Mock Token)	GitHub Personal Access Token for PR generation.

---

🛡️ Enterprise Guardrails Implemented

1. Dynamic Routing Guard: An endpoint is never marked as Bloat unless static AST call counts and runtime API gateway trace logs both confirm zero invocations over the evaluation window.
2. Ingress Boundary Check: If an endpoint is exposed as a public/internal gateway route, DecayZero relies primarily on distributed trace headers rather than local AST call counts.
3. Database Schema Lock-in: Strict read-only boundary on database models (models/, schema/, migrations/). Automated PRs only prune route handlers and controllers.
4. Two-Phase Tombstone (HTTP 410 Gone): Dead endpoints are replaced with an explicit 410 Gone alert shim for 14 days before physical code deletion.
5. Tiered CI/CD Verification in Sandbox: Every deprecation PR runs Tier 1 static syntax checks and Tier 2 targeted unit tests before opening a GitHub pull request.

---

❓ Frequently Asked Questions (FAQ)

1. Will DecayZero accidentally delete code that runs once a year (e.g. annual tax reports)?

No. You can define SLA Whitelist regex and glob patterns (e.g., cron/annual-tax-close/*) in the Policy Editor. Whitelisted routes are classified in Quadrant IV and protected from automated pruning.

2. How does Two-Phase Tombstoning prevent production outages?

Instead of immediately deleting code, Phase 1 injects an HTTP 410 Gone shim with structured logging for a 14-day observation window. If an unexpected downstream service calls it, DecayZero automatically cancels the deprecation, reverts the feature to Active, and alerts engineering via Slack.

3. What programming languages does DecayZero support for AST parsing?

DecayZero currently supports TypeScript/JavaScript, Python, and Rust using native Tree-sitter parsers. Support for Go, Java, and Ruby is on the roadmap.

4. Does DecayZero require an internet connection?

No. The core AST engine, SQLite store, and Net Utility evaluator run entirely offline and on-premises. Telemetry connectors can communicate with internal private APM instances.

---

🤝 Contributing

We welcome contributions from the community!

How to Contribute

1. Fork the Repository: Click the Fork button at the top right of the page.
2. Create a Feature Branch:

   git checkout -b feature/amazing-feature

3. Run Validation Tests:

   cargo test --manifest-path apps/janitor-daemon/Cargo.toml
   npm --prefix apps/cockpit run build

4. Commit Your Changes:

   git commit -m "feat(ast): add Go tree-sitter language parser"

5. Push to the Branch:

   git push origin feature/amazing-feature

6. Open a Pull Request: Submit a PR against the main branch with a clear description of your changes.

---

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

Maintained by @TamTunnel