IPC Protocol

This document defines the client-daemon protocol for Kanbus just-in-time indexing. It is the shared contract that both Python and Rust implementations must enforce.

Transport

• JSON over a local IPC socket
• UTF-8 encoded
• One JSON object per line (newline-delimited)

Versioning

Protocol versions are MAJOR.MINOR (for example, 1.0).

Compatibility rules:

• If the major version differs, the daemon must reject the request.
• If the major version matches and the client minor version is less than or equal to the daemon minor version, the request is accepted.
• If the major version matches and the client minor version is greater than the daemon minor version, the daemon must reject the request.

Request Envelope

{
  "protocol_version": "1.0",
  "request_id": "req-01",
  "action": "index.build",
  "payload": {
    "project_root": "/path/to/repo",
    "force_rebuild": false
  }
}

Fields:

• protocol_version (string, required): Client protocol version.
• request_id (string, required): Client-generated identifier for correlation.
• action (string, required): Operation identifier (for example, index.build).
• payload (object, required): Action-specific input.

Response Envelope

{
  "protocol_version": "1.0",
  "request_id": "req-01",
  "status": "ok",
  "result": {
    "index_version": "2026-02-11T00:00:00Z"
  }
}

Fields:

• protocol_version (string, required): Daemon protocol version.
• request_id (string, required): Echo of the request ID.
• status (string, required): ok or error.
• result (object, required on success): Action-specific output.
• error (object, required on error): Error description.

Error Contract

{
  "protocol_version": "1.0",
  "request_id": "req-01",
  "status": "error",
  "error": {
    "code": "protocol_version_mismatch",
    "message": "Client version 2.0 is not supported by daemon 1.0",
    "details": {
      "client_version": "2.0",
      "daemon_version": "1.0"
    }
  }
}

Required error fields:

• code (string): Machine-readable error code.
• message (string): Human-readable error summary.
• details (object): Structured context for debugging.

Standard error codes:

• protocol_version_mismatch
• protocol_version_unsupported
• invalid_request
• unknown_action
• internal_error

Validation Rules

Both implementations must:

• Reject requests missing required fields.
• Enforce version compatibility rules.
• Echo request_id in all responses.
• Return a structured error response for all failures.