Machine-Facing API Boundary

April 14, 2026 ยท View on GitHub

This document defines the supported external integration boundary for soldr.

Decision Summary

Current repo policy is:

  • soldr is a binary-first product
  • the supported external surface is the soldr executable, not the internal Rust workspace crates
  • there is no supported public Rust crate API, C ABI, or FFI surface
  • there is no supported long-running daemon or local service protocol today
  • the first supported machine-facing API is explicit CLI commands with structured JSON output on selected commands

What Is Supported Today

Supported use today means invoking the soldr binary as a subprocess through documented commands and flags such as:

  • soldr cargo ...
  • soldr <tool>[@version] ...
  • soldr status
  • soldr status --json
  • soldr cache
  • soldr cache --json
  • soldr clean
  • soldr version
  • soldr version --json

The current CLI reference lives in API.md.

What Is Not A Supported Public API

The following are implementation details and may change without a semver promise to automation consumers:

  • the internal Rust crates in crates/
  • direct use of soldr-core, soldr-fetch, soldr-cache, or soldr-cli as library dependencies
  • undocumented environment variables or wrapper-mode conventions
  • the exact on-disk cache/session layout beyond what is explicitly documented for users
  • human-oriented stdout/stderr wording unless a command is explicitly documented as structured and stable
  • commands that do not explicitly document --json as a supported protocol surface

Future Direction

The intended progression is:

  1. Keep soldr binary-first.
  2. Expand explicit JSON output only for selected commands that need automation support.
  3. Version that structured output as an external protocol.
  4. Only consider a daemon or other long-running local protocol if a real use case appears that the CLI cannot serve cleanly.

If a daemon or other protocol is ever added, it should be documented and versioned as a separate external interface. It should not expose the internal Rust crate graph and call that the supported API.

Non-Goals

This repo is not currently pursuing:

  • a stable public Rust library API
  • a stable embeddable C ABI
  • undocumented machine parsing of human help/status text
  • a background service that third parties are expected to integrate with by default