ADR-017: v2.0.0 Public-API Stability & Deprecation Policy

Date: 2026-06-21 Status: Accepted Decision-makers: FCC core maintainers Consulted: Ecosystem consumers (PAOM/AOME/RC/CONSTEL) that import or pull FCC surfaces Informed: All fcc-integration downstream pins; constellation/vertical consumers

Context and Problem Statement

v2.0.0 is the first SemVer major since the v1.0.0 capability freeze. FCC is now imported and pulled by multiple sister projects (PAOM ingests personas; AOME/CONSTEL/RC consume the catalog; the constellation plugins import the core), yet FCC has never declared which parts of src/fcc/ are a stable public API versus internal implementation. Without that line, every internal refactor risks a silent downstream break, and SemVer can't mean anything.

Decision

Declare a stable public API surface for v2.0.0, governed by SemVer, plus a deprecation policy. The full surface lives in docs/developer/public-api.md; the principles:

Stable (public — breaking changes require a major bump): - fcc.__version__ - fcc.personas — PersonaRegistry, PersonaSpec, RISCEARSpec, archetypes (taxonomy resolver) and their to_dict/from_dict. - fcc.messaging.events (Event, EventType) + fcc.messaging.lanes (LaneRouter). - fcc.governance.constitution_registry (PersonaConstitution). - fcc.contributions (build_dossier, federation_summary). - fcc.protocols.portal / fcc.protocols.journey / fcc.protocols.ux_gateway (the served HTTP contracts — agent-card, MCP info, portal-component-v1, contribution-dossier-v1, /embed, journey emission). - fcc.observability (tracing, spans, collector). - The fcc CLI command surface (fcc.scaffold.cli) — command names, options, and output contracts. - The packaged data contracts: data/schemas/*.schema.json, data/exchange_contracts/*, the catalog export shape, and the partner-probe-guide surfaces.

Internal (may change in any release, no deprecation owed): - Any module or symbol prefixed _ (e.g. fcc._resources) — importable but internal-stable; we avoid gratuitous breaks but make no SemVer promise. - Implementation internals of demos, dashboard, scaffold (beyond the CLI), simulation, rag, search, knowledge builders, and test/dev tooling.

Deprecation policy: - A public symbol slated for removal emits a DeprecationWarning for at least one minor release before removal, and removal happens only in a major bump. (Precedent: the v1.5.1 role_collaborators nested-shape shim.) - The deprecation names the replacement and the target removal version.

Consequences

• Downstream fcc-integration pins gain a real stability contract: import the public surface freely; treat internal modules as subject to change.
• FCC retains freedom to refactor internals without a major bump.
• A lightweight importability guard test (tests/test_public_api.py) asserts the declared public modules import — catching accidental public-surface breakage.
• Future public-surface additions are minor bumps; removals/renames are majors.