Skip to content

PROTOCOL.md

Latest commit

 

History

History
383 lines (306 loc) · 7.07 KB

PROTOCOL.md

File metadata and controls

383 lines (306 loc) · 7.07 KB
Raw

Arbor Protocol Specification

Version: 1.0.0

Overview

The Arbor Protocol is a JSON-RPC 2.0 interface over WebSocket that allows AI agents and IDE integrations to query the code graph for architectural context.

Connection

Default endpoint: ws://localhost:7433

The server supports multiple concurrent connections. Each connection maintains its own query state but shares the underlying graph.

Message Format

All messages follow JSON-RPC 2.0:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "methodName",
  "params": { ... }
}

Responses:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { ... }
}

Methods

graph.info

Returns metadata about the indexed graph.

Request:

{
  "method": "graph.info",
  "params": {}
}

Response:

{
  "result": {
    "nodeCount": 1542,
    "edgeCount": 4820,
    "languages": ["typescript", "rust", "python"],
    "lastIndexed": "2024-01-15T10:30:00Z",
    "version": "0.1.0"
  }
}

discover

Finds the architectural root for a semantic query. Unlike simple text search, this traces the call graph to find the primary service or component.

Request:

{
  "method": "discover",
  "params": {
    "query": "user authentication",
    "limit": 5
  }
}

Response:

{
  "result": {
    "nodes": [
      {
        "id": "auth_controller_validate",
        "name": "AuthController.validate",
        "kind": "function",
        "file": "src/controllers/auth.ts",
        "line": 45,
        "score": 0.95,
        "reason": "Entry point for authentication flow, called by 12 routes"
      }
    ],
    "queryTime": 8
  }
}

impact

Analyzes the blast radius of a code change. Returns all nodes that depend on the specified target.

Request:

{
  "method": "impact",
  "params": {
    "node": "UserService.validateToken",
    "depth": 3
  }
}

Response:

{
  "result": {
    "target": {
      "id": "user_service_validate_token",
      "name": "UserService.validateToken",
      "kind": "function",
      "file": "src/services/user.ts",
      "line": 127
    },
    "dependents": [
      {
        "id": "auth_middleware_check",
        "name": "authMiddleware.check",
        "kind": "function",
        "file": "src/middleware/auth.ts",
        "line": 23,
        "relationship": "calls",
        "depth": 1
      }
    ],
    "totalAffected": 47,
    "queryTime": 15
  }
}

context

Retrieves ranked context for a task. Nodes are ordered by architectural significance, optimized for AI context windows.

Request:

{
  "method": "context",
  "params": {
    "task": "refactor the payment processing flow",
    "maxTokens": 8000,
    "includeSource": true
  }
}

Response:

{
  "result": {
    "nodes": [
      {
        "id": "payment_service",
        "name": "PaymentService",
        "kind": "class",
        "file": "src/services/payment.ts",
        "lineStart": 15,
        "lineEnd": 245,
        "centrality": 0.87,
        "source": "export class PaymentService { ... }",
        "tokenCount": 1250
      }
    ],
    "totalTokens": 7840,
    "queryTime": 22
  }
}

node.get

Retrieves detailed information about a specific node.

Request:

{
  "method": "node.get",
  "params": {
    "id": "payment_service_process"
  }
}

Response:

{
  "result": {
    "id": "payment_service_process",
    "name": "PaymentService.process",
    "kind": "function",
    "file": "src/services/payment.ts",
    "lineStart": 67,
    "lineEnd": 125,
    "signature": "async process(order: Order): Promise<PaymentResult>",
    "edges": {
      "calledBy": ["checkout_controller_submit"],
      "calls": ["stripe_client_charge", "order_service_update"],
      "imports": ["stripe", "order_types"]
    }
  }
}

search

Simple text search across node names and signatures.

Request:

{
  "method": "search",
  "params": {
    "query": "validate",
    "kind": "function",
    "limit": 20
  }
}

Response:

{
  "result": {
    "nodes": [
      {
        "id": "user_service_validate",
        "name": "UserService.validate",
        "kind": "function",
        "file": "src/services/user.ts",
        "line": 45
      }
    ],
    "total": 127,
    "queryTime": 3
  }
}

Node Kinds

Kind Description
function Standalone function or method
class Class definition
interface Type interface or protocol
variable Module-level variable or constant
import Import statement
export Export declaration
module File/module boundary

Edge Types

Type Description
calls Function A calls function B
calledBy Inverse of calls
imports Module A imports from module B
implements Class implements interface
extends Class extends another class
references General reference to a symbol

Error Codes

Code Message Description
-32700 Parse error Invalid JSON
-32600 Invalid request Missing required fields
-32601 Method not found Unknown method name
-32602 Invalid params Missing or invalid parameters
-32000 Graph not ready Index not yet complete
-32001 Node not found Requested node doesn't exist

Subscriptions

The protocol supports subscriptions for real-time updates:

graph.subscribe

Subscribe to graph changes.

Request:

{
  "method": "graph.subscribe",
  "params": {
    "events": ["nodeAdded", "nodeRemoved", "edgeAdded"]
  }
}

Notification:

{
  "method": "graph.event",
  "params": {
    "type": "nodeAdded",
    "node": { ... }
  }
}

Spotlight Protocol

The Spotlight Protocol enables real-time synchronization between AI agents, the Arbor Visualizer, and local development environments.

Transport

Property Value
Endpoint ws://127.0.0.1:8081 (SyncServer)
Latency Target <50ms for UI triggers
Highlight System Golden Highlight (#FFD700)

Message: FocusNode

Broadcasts when an AI tool focuses on a specific node.

Payload:

{
  "type": "FocusNode",
  "payload": {
    "node_id": "auth_controller_validate",
    "file": "src/controllers/auth.rs",
    "line": 45
  }
}

Arbor Visualizer (Flutter)

Component Specification
AnimationController 600ms duration
Easing easeOutCubic
Haptics Medium impact on arrival
State spotlightNodeId in GraphState

VS Code Extension

Feature Behavior
Spotlight Sync Highlights line when AI focuses
Keyboard Shortcut Ctrl+Shift+A (Toggle Visualizer)
Context Menu "Show in Arbor Visualizer"
Status Bar Connection indicator

Centrality Metric (Impact Level)

Uses PageRank algorithm to determine symbol importance.

Range Classification
> 0.8 High Impact (heavily imported/referenced)
0.3-0.8 Medium Impact
< 0.3 Low Impact (leaf nodes)