Public Surface Stability Contract

Fgentic mints public surfaces beyond its code: extension URIs partners pin, event namespaces clients parse, schemas operators write. Anyone building on the platform needs to know which of these are contracts and which are experiments. This registry is the single source of truth; adding or changing a public surface requires a PR touching this file. The A2A conformance currency note binds the protocol claim and SDK pin and requires every A2A revision evaluation to revisit the extension entries below. Operators apply these tiers through the Day-2 Operations Handbook upgrade procedure.

Tiers

1. Stable — versioned; breaking changes require a new major version of the surface, a deprecation entry here, and an upgrade note in the release contract (#188). The old version keeps working for at least one minor release.
2. Beta — may change between releases; every change ships a migration note. Safe to build on with pinning.
3. Experimental — may change or disappear without notice; namespaces are reserved here so they never collide, but nothing else is promised.

Registry

The v1.0.0 decision column is binding input to the v1.0.0 release gate. A Promote to Stable at v1.0.0 row changes tier only in the release PR that ships the guarantee; until then its current tier remains authoritative.

Surface	Current tier	v1.0.0 decision	Defined in	Rationale / guarantee
Delegation audit schema fgentic.delegation.v1	Stable	Retain Stable	docs/audit.md	Content-free by design; schema stability is an explicit deliverable of #37.
A2A extension URI …/a2a/extensions/token-budget/v1	Stable	Retain Stable	docs/bridge.md §6	Partner-enforced request contract already pinned by remote configurations.
A2A extension URI for per-skill quotes	Experimental	Remain Experimental	docs/federation.md §8.3, #142	Shipped and signed, but credit units are bilateral and no external adopter has accepted this contract.
A2A extension URI for signed usage receipts	Experimental	Remain Experimental	docs/federation.md §8.3, #141	The v1 receipt is seller-signed only and cannot attest actual client consumption or a counterparty acknowledgment.
A2A extension URI for mandate profiles	Experimental	Remain Experimental	#144	The AP2-shaped authorization chain is vision-scoped and not implemented; the namespace remains reserved only.
agents.yaml schema v1	Stable	Retain Stable	agents.schema.json, docs/bridge.md	Explicit schemaVersion: 1; omitted v1 is deprecated and unknown majors fail closed.
Matrix profile fields under ai.fgentic.*	Experimental	Remain Experimental	#120	The advisory, unsigned discovery fields are vision-scoped and not implemented.
Matrix task state event ai.fgentic.task	Experimental	Remain Experimental	#121	The publisher and its consumer compatibility contract are vision-scoped and not implemented.
Matrix structured result metadata ai.fgentic.a2a	Experimental	Remain Experimental	docs/federation.md §8.6.3, #167	The content-free schema is new; its cross-organization runtime acceptance and an external consumer remain outstanding.
Prometheus metric names fgentic_*	Beta	Promote to Stable at v1.0.0	docs/observability.md	Adopter dashboards and alerts pin these names; after 1.0, replacements require migration notes and deprecation.
mise task vocabulary (demo:up, fed:up, fed:up:constrained, fed:status, fed:stop, fed:down, …)	Beta	Promote to Stable at v1.0.0	mise.toml, README	These commands are the operator and acceptance interface; replacements overlap for at least one minor release.
Bridge Helm chart values	Beta	Remain Beta	apps/matrix-a2a-bridge/chart/, #190	Standalone install and compatibility acceptance are deferred to v1.1; every values change still needs a migration note.
Federation lab acceptance interface (fed:up proofs, constrained mode, lifecycle, resource trace)	Beta	Promote to Stable at v1.0.0	docs/federation.md §8.5, ADR 0013	The v1 federation claim depends on this proof contract; constrained mode may not weaken the proof set.

Support and tested upgrade paths

This section states the support reality plainly; do not infer stronger guarantees than are written here.

1. Single maintainer. Fgentic is maintained by one person. There is no support SLA, no security-response SLA beyond the SECURITY.md private-reporting process, and no commitment to backport fixes to older releases. Best-effort, community-oriented support only.
2. The release unit is a tag. A supported deployment pins a release tag and its BOM, not main. See the Adopter Release & Upgrade Contract. Tracking main is unsupported: it carries untested pin-sets and CD digest-pin commits.
3. Tested upgrade paths: currently none end-to-end. At this stage the release contract's offline core is in place (the BOM, its fail-closed verify gate, and the upgrade-notes convention), but no live tag-to-tag upgrade drill has been run. Do not assume any upgrade is validated until an upgrade note documents it. The intended steady-state guarantee is N-1 → N only: each release is expected to be upgradeable from the immediately preceding release by following its upgrade note, and skipping releases is not tested. Multi-version jumps mean applying each intermediate note in order, at your own risk.
4. Surface guarantees are separate from upgrade support. The tiers below govern how individual public surfaces change; they do not by themselves promise that a full-platform upgrade between two tags has been exercised.

Policy

1. New public surfaces start Experimental with a reserved namespace and an owning issue; promotion to Beta/Stable happens in the PR that ships the guarantee.
2. A breaking change to a Stable surface is a design change: it needs the deprecation entry here, the release-contract upgrade note (#188), and — where it touches a settled decision — an ADR.
3. The Stable agents.yaml schema uses major versions in schemaVersion: additive fields evolve within the current minor release, while removals or incompatible meaning changes require a new major plus an upgrade note. The bridge never guesses how to read an unknown major.
4. The v1.0.0 release PR applies every promotion decision above and leaves every retained Beta or Experimental rationale intact. A changed decision must be recorded on #471 before the release tag.
5. Internal interfaces (Go packages, unexported config, cluster-internal Services) are deliberately absent: absence from this table means no contract.