[Self-Hosting] Phase 4: Implement Queryable API in Gradient

[graydeon]

Summary

Implement the queryable API in Gradient. This is the key enabler for agentic workflows.

Background

With a working type checker (Phase 3), we can now provide structured, programmatic access to compiler internals. This moves the queryable API from Rust to Gradient.

Current State

Rust has working query API (codebase/compiler/src/query.rs - 5,400 lines). We need equivalent in Gradient.

Target State

NEW FILE: compiler/query.gr (~2,000 lines)

Provides:

• Session type for holding compiled state
• session_from_source() - compile from string
• session_check() - get errors
• session_symbols() - get all symbols
• session_type_at() - type at position
• session_rename() - safe refactoring
• session_effects() - effect analysis
• session_documentation() - doc extraction
• session_call_graph() - call relationships

Implementation Requirements

Types

type Session:
    source: String
    tokens: TokenList
    ast: AstModule
    typed_module: TypedModule
    type_cache: TypeCache
    symbol_table: SymbolTable

Core Functions

1. session_from_source(source: String) -> Session

   • Run full pipeline: lex → parse → check
   • Store all intermediate results
   • Return session handle

2. session_check(sess: Session) -> CheckResult

   • Return all diagnostics
   • Structured errors (not text)
   • Include positions, severity, phase

3. session_symbols(sess: Session) -> SymbolList

   • Return all top-level symbols
   • Name, kind, type, effects, location

4. session_type_at(sess: Session, line: Int, col: Int) -> TypeAtResult

   • Get type of expression at position
   • Used for hover information

5. session_rename(sess: Session, old: String, new: String) -> RenameResult

   • Find all references
   • Verify new name is valid
   • Return all changes needed

6. session_effects(sess: Session) -> EffectSummary

   • Return effect analysis for all functions
   • Purity tracking

JSON Output

All results must be JSON-serializable for tooling:

fn check_result_to_json(result: CheckResult) -> String
fn symbol_list_to_json(symbols: SymbolList) -> String

Acceptance Criteria

• All query methods implemented
• JSON serialization for all results
• Performance: <50ms per query
• Same functionality as Rust query API
• Type-checks successfully
• Comprehensive tests

Why This Matters

This enables agents to develop Gradient in Gradient:

• Agents can query the compiler programmatically
• Structured data instead of text parsing
• Real-time feedback (<50ms)
• Safe, automated refactoring

Part Of

• Epic: Full Self-Hosting with Rust Kernel
• Phase: 4 of 7
• Blocks: Phase 5 (LSP in Gradient)

Effort

~5 days, ~1,500 lines of Gradient

Dependencies

• Phase 3 complete (Type Checker)

[graydeon]

Phase 4 (Query API) is complete. The query.gr module is fully implemented with all required functionality including Session API, symbol queries, hover information, and completion items. All tests pass. Closing this tracking issue.