Compatibility and Versioning

Compatibility in Ophiolite should be judged by public surfaces, not only by internal package versions.

What to watch

• Python SDK behavior
• CLI commands and payloads
• operator-package contracts
• compatibility rules for external packages
• .tbflow workflow scripts
• compiled WorkflowRecipe JSON
• workflow bundles and evidence
• Workbench diagnostics bundles

Current stance

Most public surfaces are still in Preview. Expect change, but expect it to happen around explicit platform nouns instead of random wrapper drift.

Compatibility classes

Ophiolite uses these compatibility classes for the commercial MVP:

Class	Meaning
Stable-by-direction	Intended public contract. Still preview, but changes need migration notes.
Preview-compatible	Expected to keep working within the current preview lane unless a limitation says otherwise.
Evidence-readable	Expected to remain inspectable for provenance, but not necessarily rerunnable or reusable.
Internal	No compatibility promise.

Surface policy

Surface	Current class	Policy
ophiolite-sdk package/import name	Stable-by-direction	Keep package and import names stable. Document public API breaks.
ophiolite CLI public commands	Stable-by-direction	Keep documented commands and support fields stable where practical.
ophiolite doctor support fields	Stable-by-direction	Preserve category, code, status, message, and details semantics.
.tbflow scripts	Preview-compatible	Require compiler/version evidence and migration notes for breaking syntax or semantic changes.
WorkflowRecipe JSON	Preview-compatible	Treat as canonical compiled/runtime format. Use schema/version fields for compatibility checks.
Workflow bundles	Evidence-readable	Keep old bundles inspectable when practical. Rerun/replay compatibility is a narrower promise.
Operator ids and family ids	Stable-by-direction once documented	Avoid renames. Use aliases or migration notes when practical.
Workbench diagnostics bundles	Preview-compatible	Support bundle contents may grow, but named files such as app.json, environment.json, runtime.json, commercial-state.json, and session-events.json should remain readable.

Release notes rule

Release notes should identify breaking changes by public surface:

• SDK API
• CLI command or JSON payload
• .tbflow syntax or semantics
• compiled recipe schema
• bundle/evidence layout
• operator id or family id
• diagnostics bundle shape

Workbench diagnostics compatibility is checked by a headless exporter test plus the release zip smoke validator.

Internal crate refactors do not need migration notes unless they change one of those public surfaces.

The architecture decision is tracked in ADR-0040.