Compatibility and Versioning

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

What to watch

• Python automation 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_automation package/import name | Stable-by-direction | Keep the thin automation import stable. Document public command 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.