Cougr Compatibility Promises

Purpose

This document defines the compatibility story Cougr is prepared to defend at 1.0.

It turns the maturity model into explicit expectations for adopters, contributors, and maintainers.

1.0 Baseline

Cougr 1.0.0 freezes a scoped stable surface inside a broader public crate.

That means:

  • compatibility promises are scoped by maturity, not by visibility alone
  • stable, beta, and experimental namespaces can coexist in the same crate
  • the stable guarantee is the documented contract, not every public symbol

Stable Surfaces

The following surfaces are treated as Cougr's strongest 1.0 compatibility commitments:

  • root ECS onboarding and runtime entrypoints documented in API_CONTRACT.md
  • prelude
  • runtime
  • ops
  • standards
  • privacy::stable
  • zk::stable
  • the contracts documented in PRIVACY_MODEL.md for commit-reveal, hidden-state codecs, and Merkle verification

For these surfaces, maintainers should preserve:

  • type and function intent unless there is a documented breaking reason
  • documented failure behavior
  • documented malformed-input behavior where applicable
  • byte-level or proof-shape contracts already written in the privacy model

Beta Surfaces

The following surfaces are supported but intentionally not frozen:

  • higher-level ECS helpers outside the frozen root/runtime contract
  • auth
  • accounts
  • proof-submission orchestration that depends on experimental verification flows

For Beta surfaces, maintainers commit to:

  • keep the product direction coherent
  • document meaningful semantic changes
  • avoid gratuitous churn
  • preserve the curated onboarding path where practical

For Beta surfaces, maintainers do not yet promise:

  • SemVer-stable signatures
  • unchanged storage layouts for every helper
  • unchanged auth or orchestration semantics across all releases

Experimental Surfaces

The following surfaces are explicitly outside compatibility guarantees:

  • privacy::experimental
  • zk::experimental
  • hazmat cryptographic helpers
  • advanced proof-verification helpers and descriptors
  • any public support surface documented as test-only or transition-only

These may:

  • change shape
  • move namespace
  • be removed
  • gain stronger validation that changes edge-case behavior

Non-Contract Support Surfaces

Support-only surfaces such as MockAccount are not part of the default product contract.

They exist for tests and explicit utility consumers, not as long-term framework guarantees.

Change Management Rules

When changing a Stable or Beta public surface, update at minimum:

1.0 Freeze Decisions

The 1.0 release gate decisions are:

  • ECS onboarding and runtime surfaces are in the stable contract
  • ops is the stable domain alias for standards
  • standards is in the stable contract
  • auth is a Beta domain alias and is not part of the stable guarantee
  • accounts remains Beta and is not part of the stable guarantee
  • privacy::stable maps to the frozen privacy contract
  • zk::stable is the frozen privacy contract
  • privacy::experimental remains outside compatibility guarantees
  • zk::experimental remains outside compatibility guarantees