CURD API Contract (v0.7.1)

This document defines response and error guarantees exposed by curd JSON-RPC and tool handlers.

Envelope

All responses are JSON-RPC objects with:

• jsonrpc: "2.0"
• id: request id (for requests with id)
• api_version: "0.7.1"
• config_hash: SHA-256 of the active policy (provided upon connection verification)

Success shape

Success responses contain either:

• result: <object|array|primitive>

Tool-call responses (tools/call) include:

• result.content[] with text payloads

Built-in operational methods include:

• benchmark for in-process timing (search|read|graph|lsp)
• debug_backends for runtime backend availability introspection
• debug_session_start|send|recv|stop for iterative debugger/repl workflows

Graph endpoints:

• graph supports view=edges|tree
• graph responses include nodes[] metadata (id, name, kind, file, start_line, end_line)

Profile endpoints:

• profile supports compare_command when format=folded to return frame-level deltas
• sampling capabilities are surfaced in sampling.capabilities

Error shape

Error responses contain:

• error.code (integer)
• error.message (string)
• error.details (nullable; optional structured metadata)

If details is not explicitly set by a handler, CLI normalization sets it to null.

Diagnostics schema (LSP)

Diagnostic entries returned by LSP endpoints use normalized fields:

• message
• severity (error|warning|info)
• code (string/null)
• source (syntax|semantic)
• tool (e.g. tree-sitter, rustc, pyright)
• line, column, end_line, end_column

Backward compatibility policy

• New fields may be added.
• Existing required fields listed above are stable within a minor series.
• Breaking schema changes should bump api_version.