The Deterministic Intelligence Substrate for AI Coding Assistants

The software industry has entered the era of autonomous pair-programming. However, modern frontier models (Claude 3.7 Sonnet, GPT-4o, Gemini 2.0 Flash) face fundamental physical limits when dropped into enterprise repositories. PolyTuring was engineered to bridge the chasm between raw LLM reasoning and real-world software architecture.

The Context Window Crisis & The Myth of Raw Grep

When autonomous coding agents are equipped only with primitive filesystem tools (cat, grep, find), three catastrophic failure modes inevitably emerge:

The PolyTuring Triad

To transform stochastic coding assistants into deterministic software engineers, PolyTuring provides three foundational pillars:

Built Antigravity-First — Architected for the Entire Ecosystem

Omni-Graph is a zero-telemetry, multi-container semantic graph engine that models software repositories as rich Abstract Syntax Tree (AST) graphs augmented with dense 384-dimensional vector embeddings. It solves code navigation, blast-radius analysis, and agent context starvation entirely on local hardware.

4-Tier Container Architecture

Omni-Graph runs on an isolated Docker network (omni-net) coordinating four decoupled microservices:

flowchart TB
    subgraph UI["Tier 4: WebGL Visualizer (:3000)"]
        Cosmo["Cosmograph 3D Force Graph"]
        Analytics["Dual-Source Agent Analytics"]
    end

    subgraph Rust["Tier 3: Rust Axum Orchestrator (:8080)"]
        Parser["Tree-Sitter Polyglot Parser"]
        Condenser["Context Condenser (≤ 1500 Tokens)"]
        RagEngine["GraphRagEngine (Hybrid Synthesizer)"]
        Watcher["Notify Background Watcher Daemon"]
    end

    subgraph DB["Tier 1: SurrealDB v2 (:8000)"]
        NodeTbl["node (SCHEMAFULL, HNSW 384-dim)"]
        EdgeTbl["linked_to (TYPE RELATION, idx_edge_*)"]
        GalaxyTbl["galaxy (Pre-Computed LPA Clusters)"]
    end

    subgraph TEI["Tier 2: HuggingFace TEI (:8081)"]
        Model["BAAI/bge-small-en-v1.5 (ARM64 SIMD)"]
    end

    UI --> Rust
    Rust --> DB
    Rust --> TEI
                

Live Interface · 3D Galaxy Subsystems Studio

− 100% + ⟲ Theater

Figure 1.2: 3D Force-Directed Galaxy Subsystems — Macro Topology & LPA Community Clusters

Live Interface · Agent Analytics & LSP Telemetry

− 100% + ⟲ Theater

Figure 1.3: Real-Time Agent Analytics — AST Call Efficiency, Context Window Preservation (90.7%), & Multi-Language LSP Telemetry

Galaxy Subsystems & Louvain / Leiden Modularity Clustering

Software codebases are not flat hierarchies of directories. In reality, modern applications are scale-free, directed multi-graphs of functions, types, interfaces, and traits linked by call invocations, type references, and implementations. When an autonomous coding agent attempts to modify a codebase without architectural clustering, it suffers from context blindness: it cannot distinguish tightly-coupled internal modules from loose external boundaries.

Omni-Graph solves this by partitioning the entire AST graph into self-contained, cohesive architectural clusters called Galaxy Subsystems using a dual-phase Louvain and Leiden community detection engine.

Robert C. Martin Coupling Metrics & Dynamic Blast Radius Contracts

Once Galaxy Subsystems are clustered, Omni-Graph analyzes cross-boundary dependency vectors using Robert C. Martin's package metric formulations. This allows agents to quantify risk before writing a single line of refactored code:

Ephemeral Branch Fabric (EBF) & Git Worktrees

Coding agents frequently branch or create Git worktrees to isolate experimental code and execute parallel strategies. Traditional code indexing tools either re-index the entire multi-gigabyte repository from scratch or fail completely. Omni-Graph solves this with the Ephemeral Branch Fabric (EBF):

flowchart TB
    Trunk["Trunk Workspace (Parent)
e.g. ecommerce-platform"]

    subgraph GitWorktrees["Git Worktree Directory (.git/worktrees/*)"]
        WT1[".git/worktrees/feat-stripe-v2"]
        WT2[".git/worktrees/refactor-auth-jwt"]
        WT3[".git/worktrees/hotfix-cart-lock"]
        WT4[".git/worktrees/exp-graphql-mesh"]
    end

    subgraph EBFEngine["Omni-Graph EBF Core (Rust Axum Engine)"]
        Peeker["O(1) Worktree Peeker
Resolves gitdir and lineage"]
        Cascade["Top-Down Auto-Cascade
Asynchronous Background Ingestion"]
        LPAInherit["Seed-Preserving LPA
Inherits parent community IDs"]
        WatcherPool["Notify Watcher Pool
Multi-Path Concurrent Daemon"]
    end

    subgraph Storage["SurrealDB v2 Isolation"]
        DB_Trunk["workspace: ecommerce-platform"]
        DB_WT1["workspace: feat-stripe-v2"]
        DB_WT2["workspace: refactor-auth-jwt"]
        DB_WT3["workspace: hotfix-cart-lock"]
        DB_WT4["workspace: exp-graphql-mesh"]
    end

    Trunk --> Peeker
    Peeker --> GitWorktrees
    GitWorktrees --> Cascade
    Cascade --> LPAInherit
    Cascade --> WatcherPool
    LPAInherit --> Storage
    WatcherPool -.->|Live Invalidation| Storage
                

Polyglot AST Grammar & Struct Field Extraction

Omni-Graph utilizes Tree-Sitter grammars compiled natively in Rust. Unlike shallow regex matchers, Omni-Graph models true language semantics across four enterprise languages:

• Rust: Functions, methods in impl blocks (with DECLARES edges from structs), struct declarations with child field_declaration nodes (with CONTAINS and REFERENCES edges), enum_item, trait_item, macro_definition, and macro_invocation.
• Go: Package declarations, function declarations, method declarations with pointer receiver binding, type_spec structs with member field_declaration nodes, and discrete import_spec symbols.
• TypeScript / JavaScript: Lexical arrow functions, classes, interface_declaration with child property_signature nodes, type aliases, and multi-symbol named imports (import { A, B }).
• Python: Synchronous and async coroutine definitions, class definitions with multi-inheritance tracking, call sites, and multi-symbol imports (from m import A, B).

Two-Tier Context Condenser & Graph-RAG Token Budget Math

A common failure mode in code assistants is context starvation: a retrieval tool dumps 8,000 tokens of raw source code, blowing past agent context windows and truncating essential architectural call graphs. Omni-Graph enforces a mathematical token budget guarantee:

SurrealDB Relational Indexing & Zero-Blackout Re-indexing

SurrealDB v2 handles both relational graph traversals and HNSW vector searches. In Round 4, four dedicated relational indexes were added to linked_to:

-- Sub-millisecond graph edge traversals & caller lookups
DEFINE INDEX idx_edge_workspace ON TABLE linked_to FIELDS workspace;
DEFINE INDEX idx_edge_in        ON TABLE linked_to FIELDS in;
DEFINE INDEX idx_edge_out       ON TABLE linked_to FIELDS out;
DEFINE INDEX idx_edge_out_ws    ON TABLE linked_to FIELDS workspace, out;
DEFINE INDEX idx_edge_in_ws     ON TABLE linked_to FIELDS workspace, in;

During live file modifications, the live watcher daemon performs an atomic zero-blackout swap: the HuggingFace TEI vector embedding is computed prior to pruning previous AST nodes. This eliminates the 404 deletion gap from ~250ms down to $\approx 1$ms.

Test and simulate Omni-Graph's mathematical token budget. Tweak the sliders to see how two-tier symbol truncation and edge reservation guarantee compliance with the < 1,500 token SLA.

Select any Omni-Graph REST endpoint to generate ready-to-run curl commands formatted for terminal or agent tool invocations.

curl -s -X POST http://localhost:8080/api/query \
  -H "Content-Type: application/json" \
  -d '{"prompt": "How does token budgeting work?", "workspace": "PolyTuring"}'

Session Explorer is a single-binary conversation intelligence browser and real-time observability cockpit for agent transcripts across Antigravity CLI, Antigravity IDE, and extensible runtime providers. It parses raw JSONL logs on local disk, extracts tool parameters, indexes user prompts, and serves an embedded liquid-glass web interface with zero runtime dependencies.

Go + Bun Standalone Binary Architecture

Built for zero runtime friction, Session Explorer embeds its entire web application, Highlight.js syntax engine, KaTeX mathematical typesetter, client-side Mermaid compiler, and Swagger UI directly inside the compiled Go binary using //go:embed:

flowchart LR
    CLI["~/.gemini/antigravity-cli/brain/ (CLI)"] --> Scanner["Go Concurrent Scanner (Worker Pool + Delta Cache)"]
    IDE["~/.gemini/antigravity-ide/brain/ (IDE)"] --> Scanner
    Scanner --> MemIndex["In-Memory Index & Search Engine"]
    MemIndex --> Api["Go HTTP REST API & SSE Live Tail (/tail)"]
    Assets["Bun Web Frontend (Liquid Glass UI)"] --> Embed["go:embed Static Assets"]
    Embed --> Binary["Standalone 'session-explorer' Binary (0 Deps)"]
    Binary --> Browser["Local Browser (:9876)"]
    Api -.->|SSE Stream| Browser
                

Live Interface · Session Explorer Cockpit

− 100% + ⟲ Theater

Figure 2.2: Session Explorer Cockpit — Multi-Runtime Workspace Discovery, Date Clustering & Live Filter HUD

Live Interface · 1-Click Dialogue Mode

− 100% + ⟲ Theater

Figure 2.3: Session Trail in Dialogue Mode — High-Signal Reading, Markdown Tables & Inline KaTeX Rendering

Live Interface · Native File & Artifact Viewer

− 100% + ⟲ Theater

Figure 2.4: Native In-Browser File Viewer — Syntax Highlighting, Synchronized Gutter, Anchored Highlights & Pinned Find Widget

Agent Work-in-Progress (WIP) Recovery & Disambiguation

Autonomous coding companions occasionally suffer from context window resets, token ceiling truncations, IDE crashes, or system reboots. Without telemetry, an assistant entering a codebase has no recollection of recent file modifications, pending tasks, or error blockers.

Session Explorer introduces the Agent WIP Recovery System (/most-recent-wip and make session-wip). It extracts recent user prompts, modified files, executed commands, and error logs directly from local JSONL transcripts.

flowchart TD
    Trigger["Coding Assistant Runs /most-recent-wip (or wip.sh)"] --> QueryAPI["Query Session Explorer Engine (GET /api/wip)"]
    QueryAPI --> ScanIndex["Scan Brain Transcripts & Correlate Workspace"]
    ScanIndex --> Decision{"Multiple Active Sessions Found?"}
    Decision -- "Yes (>1 Candidates)" --> HaltAgent["🛑 MANDATORY AGENT HALT: Present Candidates & Ask User"]
    Decision -- "No (1 Match or Forced)" --> LoadDigest["🚀 Auto-Resume: Extract Recent Prompts, Diffed Files & Commands"]
    HaltAgent --> UserPicks["User Selects Target Session UUID"]
    UserPicks --> LoadDigest
    LoadDigest --> ContinueWork["Assistant Resumes Task Seamlessly Without Context Loss"]
                

Liquid Glass UI, 22px Gutter Invariant & Persistent In-Page Find

Reviewing source code touched by coding assistants inside traditional tools often suffers from jarring layout shifts, duplicate scrollbars, and line-number drift. Session Explorer enforces three critical frontend engineering invariants:

Embedded OpenAPI 3.0 & Swagger UI

Session Explorer embeds an interactive, 100% offline OpenAPI 3.0 specification and Swagger-compatible documentation explorer directly inside the compiled binary:

CLI Commands & Quickstart

# Launch Session Explorer (auto-opens browser at http://localhost:9876)
make session-explorer

# Launch interactive OpenAPI/Swagger Documentation in browser
open http://localhost:9876/docs

# Recover Agent WIP status for current repository
make session-wip

# Force selection of newest session
make session-wip LATEST=1

# Install session-wip skill into local workspace or global system
make setup-session-wip TARGET=workspace
make setup-session-wip TARGET=global

# Headless mode (no auto-opening browser)
cd tools/session-explorer && make run-headless

# Run unit tests and automated mock dataset demo
make test-tool T=session-explorer
make demo-tool T=session-explorer

While PolyTuring was engineered natively and verified first against Google Antigravity, its architectural nervous system is deliberately decoupled from any single proprietary AI ecosystem. Through clean protocol boundaries (REST, SSE, and the Model Context Protocol), PolyTuring serves as a universal intelligence substrate across the leading AI coding companions.

Extensibility Roadmap: Multi-Assistant Phasing

Universal MCP Extensibility Blueprint

The diagram below illustrates how PolyTuring's Model Context Protocol (MCP) server bridges any AI coding assistant into the deterministic local substrate:

flowchart TB
    subgraph Assistants["Supported Coding Assistants"]
        AG["Google Antigravity
(Native CLI / IDE / Brain)"]
        CC["Claude Code
(Anthropic CLI)"]
        GH["GitHub Copilot
(VS Code / IntelliJ)"]
        CR["Cursor
(IDE / Composer)"]
    end

    subgraph AdapterLayer["PolyTuring Universal Adapter Layer"]
        Hooks["Native Hooks
hook_pre_tool.sh"]
        MCPServer["PolyTuring MCP Server
(JSON-RPC over stdio / HTTP)"]
        LSPBridge["LSP Proxy Sidecar
(Diagnostics & Hover)"]
    end

    subgraph CoreEngines["PolyTuring Deterministic Engines"]
        OG["Omni-Graph Core (:8080)
AST Knowledge & Galaxies"]
        SE["Session Explorer (:9876)
Trajectory Intelligence & WIP"]
        DB["SurrealDB v2 Graph Store"]
    end

    AG --> Hooks
    CC --> MCPServer
    CR --> MCPServer
    GH --> LSPBridge

    Hooks --> OG
    Hooks --> SE
    MCPServer --> OG
    MCPServer --> SE
    LSPBridge --> OG
    OG <--> DB
                

Autonomous development requires extreme discipline. Without formal contracts and automated verification gates, agent-generated code rapidly decays into technical debt. PolyTuring enforces a constitutional engineering framework across every tool in the monorepo:

Spec-Driven Development (SDD) & SDLC Constitution

In traditional codebases, autonomous coding agents rapidly diverge from human architectural intent because documentation and code live in disconnected universes. In vadde/PolyTuring, every single line of production code is governed by Spec-Driven Development (SDD):

The Agentic Defense Shield & Reconnaissance Gates

Large Language Models possess context windows, but context windows are finite and vulnerable to noise contamination. Blindly reading a 3,000-line source file wastes tokens and destroys reasoning capabilities. The monorepo enforces the 3-Tier Omniverse Reconnaissance Ladder:

graph TD
    User["Agent Trigger / PreInvocation Hook"] --> ReconCheck{"Recon Marker Present? /tmp/omni_recon"}
    ReconCheck -- No --> GateEnforce["150-Line Source Gate ACTIVE"]
    GateEnforce --> Tier1["Tier 1: Global Graph-RAG (make query Q=...)"]
    Tier1 --> Tier2["Tier 2: Galaxy Cluster Boundaries (make galaxies)"]
    Tier2 --> Tier3["Tier 3: AST Call Graph Condenser (make condense SYM=...)"]
    Tier3 --> TouchMarker["Touch Recon Marker"]
    TouchMarker --> GatePass["150-Line Gate UNLOCKED for Precision Reads"]
    ReconCheck -- Yes --> GatePass
                

Continuous Integration Matrix

The repository enforces continuous integration across all supported languages (Rust, Go, TypeScript, Python, Shell) using matrix workflows:

The Documentation Synchronization Gate

Under Rule 06 (06-documentation.md), no tool may transition to review or released if documentation has drifted from the active implementation: