Stability and compatibility
Know exactly what stays compatible across the 1.x line—and what is provisional or internal.
Stability levels
A public import is not automatically stable. The public API inventory in the repository defines three levels, and only the surfaces it lists as stable carry the 1.x compatibility promise.
| Level | Meaning |
|---|---|
| Stable | Changes follow semantic versioning; backward-incompatible changes wait for a major release. |
| Provisional | Publicly usable and documented, but feedback may still require a breaking change before promotion. |
| Internal | No compatibility promise; importing it couples you to implementation details. |
The stable 1.x surface
| Surface | Stable contract |
|---|---|
| Domain and application | Public models and services exported by lumis_sdk.domain and lumis_sdk.application. |
| Ports | Protocols exported by lumis_sdk.ports; new optional methods require a new protocol or a major release. |
| Configuration and documents | lumis.dev/v1 Project, rule, DiagnosisReport, PluginManifest, Playbook, and RecoveryPolicy envelopes with their checked schemas. |
| Plugin discovery | Static manifest semantics, the entry-point group, compatibility intervals, support statuses, and default-deny authority checks. |
| Memory port | Asynchronous MemoryStore behavior and the reusable contract suite—not database tables or SQL. |
| CLI | Command names, exit-code classes, and documented JSON output of rules validate, rules test, plugins list, and plugins doctor. |
| Testkit | Documented fixtures and contract assertions exported by lumis_sdk.testkit. |
Additive optional fields may appear in a minor release; required fields, field meaning, enum removal, and default behavior do not change incompatibly within 1.x.
Provisional and internal
- Future executor and verifier protocols are intentionally absent and require an accepted RFC.
- ActionProposal is a stable Python model, but its standalone schema remains provisional as a cross-language wire format.
- Concrete adapters are reference implementations—documented constructor behavior is supported; private helpers and storage layout are internal.
- Replay metric breadth, lexical ranking weights, and benchmark numbers are provisional; truth semantics and score-component visibility are stable.
- Anything starting with an underscore, storage layouts, SQL statements, and repository automation are internal.