Backwards Compatibility Policy
What we promise not to break, how far in advance we announce changes, and which parts of the stack you should treat as alpha.
Stable
semver-protectedThese packages follow strict Semantic Versioning. Breaking changes require a major version bump and at minimum 6 months advance notice via a deprecation cycle.
| Package | Stable since |
|---|---|
| @aroha-sdk/core | v1.0.0 |
| @aroha-sdk/credentials | v1.0.0 |
| @aroha-sdk/run | v1.0.0 |
| @aroha-sdk/registry | v1.0.0 |
| @aroha-sdk/micro | v1.0.0 |
| @aroha-sdk/cli | v1.0.0 |
| @aroha-sdk/mcp-bridge | v1.0.0 |
| @aroha-sdk/a2a-bridge | v1.0.0 |
| @aroha-sdk/langchain-bridge | v1.0.0 |
| @aroha-sdk/hermes-bridge | v1.0.0 |
| @aroha-sdk/composio-bridge | v1.0.0 |
| @aroha-sdk/openclaw-bridge | v1.0.0 |
| create-aroha-agent | v1.0.0 |
Public TypeScript APIs
Exported interfaces and function signatures won't change within a major version
did:aroha: DID format
Existing DIDs resolve indefinitely — the format is permanently stable
Mandate token format
Tokens issued by any SDK ≥ 1.0.0 verify correctly with future 1.x releases
Protocol version 1.0
arohaProtocolVersion: "1.0" accepted by all future 1.x servers
Alpha
may change without noticeThese packages carry @alpha in their documentation. API shape, semantics, or existence may change in any minor version. Not recommended for production financial flows.
@aroha-sdk/settlement
Settlement hooks called by SagaEngine, but spending limits are NOT enforced at transport layer. Use NullSettlement in production.
@aroha-sdk/commerce
B2B/B2C interaction patterns — may consolidate with core
@aroha-sdk/escrow
On-chain escrow client — ArohaEscrow.sol not yet deployed on any public network
@aroha-sdk/postgres
Postgres settlement backend — database schema may change
@aroha-sdk/stripe
Stripe settlement backend — awaiting production validation
Experimental
no guaranteesThese packages exist for exploration and may be removed in any release.
@aroha-sdk/reputation
Reputation recording hooks — API not finalized
@aroha-sdk/chaos
Fault injection for testing — development-only
@aroha-sdk/cache
Registry caching layer — may merge into registry
@aroha-sdk/preferences
Agent preference store — API evolving
@aroha-sdk/trusted-mesh
Mesh trust policy engine — early prototype
@aroha-sdk/audit
Audit log adapters — schema not finalized
Breaking Change Process
For stable packages, breaking changes follow this process:
1
Deprecation release
The old API is marked @deprecated with a JSDoc comment pointing to the replacement. A minor-version release ships with both old and new APIs.
2
6-month notice period
At least 6 months between the deprecation release and the breaking major-version release.
3
Migration guide
A MIGRATION.md is published alongside the major-version release with a step-by-step upgrade path.
4
Changelog
Every breaking change is listed in CHANGELOG.md under a ### Breaking heading.
What is NOT guaranteed (even in stable packages)
- —Private class members (anything not in exported TypeScript interfaces)
- —Internal error message strings — check err.code or err instanceof X, not err.message
- —The shape of dist/ build artifacts beyond the declared exports map
- —Test utilities in */src/__tests__/ directories