🔧 Operator

Compatibility Commitment

3 min readOperator-facingPer ADR-013

What this commits to

Per ADR-013. This document is the written commitment about what stigmem will not break, scaled to project resources and the v0.9.0a1 reset posture. Reviewed at every major release; tightening or loosening goes through an ADR amendment.

Stability tiers

Tier

Promise

What it means

Stable

no wire-format breaks within v1.x

Spec section normative. In production. Eval-covered. No wire-format breaking changes within the v1.x line after v1.0.0 ships.

Beta

minor breaks possible

Spec normative; feature-flagged or in early adopters. Minor breaking changes possible before next major release.

Experimental

no commitment

Implementation behind a flag, in experimental/<feature>/. Spec section may be draft. Breaking changes expected.

Deprecated

marked for removal

Still operational; replacement available. See removal-distance commitment below.

Per-tier commitments

Stable features

Wire format: no breaking changes within the v1.x line after v1.0.0 ships. Public Python API: removing or renaming a public symbol requires a deprecation in v1.x followed by removal no earlier than v2.0.0. Default behavior: changes require a deprecation cycle.

Beta features

Subject to breaking changes in the next minor release with a CHANGELOG entry per change. Pin to specific versions; do not rely on a beta feature's wire format being stable across minor releases.

Experimental features

Subject to breaking changes in any release without notice. Use behind feature flags is at-your-own-risk. Per ADR-008 reintroduction gates, an experimental feature graduates to stable only after passing all five gates.

Deprecated features

A feature deprecated in vX.Y is supported through all subsequent vX.* releases. Removal may not happen earlier than vX+1.0. Operators have at least one major version of notice to migrate. The deprecated feature's page carries removed_in: and replacement: frontmatter.

Wire-format pinning via Stigmem-Version header

Per ADR-012: clients lock to a declared protocol version via the Stigmem-Version request header. Server honors the pin; future server versions stay backward-compatible to declared protocol versions for at least one major version after a deprecation lands.

POST /v1/facts HTTP/1.1
Stigmem-Version: 0.9.0a1
Authorization: Bearer <api_key>
Content-Type: application/json

{ ... }

The pinning header is documented in Spec-15-Fact-Semantics (Wire Format). Server implementation is future hardened-core work.

Beta opt-in via Stigmem-Beta header

Experimental wire-level features require an opt-in header per call:

POST /v1/facts HTTP/1.1
Stigmem-Version: 0.9.0a1
Stigmem-Beta: instruction-typed-facts
Authorization: Bearer <api_key>
Content-Type: application/json

{ ... }

Lists of supported beta names live at /v1/.well-known/stigmem in a betas field. Beta names retire when the underlying feature graduates per ADR-008 — calls referring to a retired beta name receive 410 Gone with a deprecation header pointing at the now-stable feature.

What this commitment does NOT cover

Implementation internals

Internal Python module structure, algorithm choices, performance characteristics — not subject to the wire-format or public-API commitments above.

Operational defaults

Default rate-limit values, cache TTLs, log retention windows — operators should pin via configuration, not rely on defaults remaining constant.

Pre-1.0 builds

Alpha and any future pre-stable builds have NO stability guarantee per ADR-001. Pin to specific versions; auto-upgrade is not safe.

Deferred features

experimental/<feature>/ — subject to breaking changes in any release without notice until the feature graduates per ADR-008.

Cross-references

ADR-001VersioningPhases and stability commitments.ADR-013Deprecation policyLifecycle and required artifacts.ReferenceExperimental featuresCurrent deferred-feature index.