0029: The 1.0 API freeze¶
Status: accepted (M4 exit criterion "API frozen"). Accepted by the owner as drafted, 15 November 2026.
Problem¶
After 1.0, people will build on OunceMCP and expect upgrades not to break them. That needs three things: a clear line between public and internal names, promises about what may change and how, and a mechanical check that catches accidental changes. The check exists (tests/test_api_surface.py, added in M4). This proposal draws the line and states the promises.
What is public¶
tests/api_snapshot.json records 114 names in 8 modules, with every public signature.
Stable at 1.0¶
Semantic versioning applies to these: no breaking change before 2.0.
| Module | Names |
|---|---|
ouncemcp |
OunceServer (constructor, tool, job, resource, prompt, run, http_app, list_tools, call_tool, cost_report, discovery, measure_recall, budget_overrides, wrap, from_config, check_ready, add_trace_sink, catalog, tools), ToolContext (all public members), Effect, Budget, BudgetOverride, BudgetOverrideWarning, Detail, Paginated, Cursor, CursorSigner, Limits, RetryPolicy, Idempotency, JobResult, stores (OunceStore, MemoryStore, KeyValueStore, RedisStore), errors (OunceError and its subclasses), tokenizers (TokenCounter, TiktokenCounter, CallableCounter, get_counter), cost reports (measure_tool, measure_tools, ServerCost, ToolCost), DiscoveryDecision, RecallCase, RecallReport |
ouncemcp.security |
Identity (Identity, current_identity, identity_from_token, ANONYMOUS_IDENTITY), policies (Policy, PolicyRequest, allow_all, authenticated, require_scopes, require_tenant, writes_require, all_of, any_of, audience_matches), state (StateSigner, InvalidState), caches (PartitionedCache, CacheView), outbound safety (check_url, checked_addresses, safe_client, PinnedTransport, URLNotAllowed, guarded_client, passthrough_guard, check_outbound, TokenPassthrough), UnsafeInputRequest |
ouncemcp.client |
Broker, BrokerResult, BrokerTool, BrokerError, CrossServerCall, META_DEFINITIONS, OunceOAuth, registration_method |
ouncemcp.trace |
CallTrace, Tracer, TraceSink, MemorySink, JsonlSink, LoggingSink, CallbackSink, redact_text, redact_value |
ouncemcp.testing |
as_caller, make_token |
ouncemcp.eval |
the security suite: run_security_suite, SecurityReport and the probes |
Provisional at 1.0¶
These are public and documented, but may change in a minor release, with the change named in the changelog. They depend on fast-moving parts: model APIs, benchmark methods and report formats.
ouncemcp.eval.agent: task suites, models and reports.ouncemcp.eval.bench.ouncemcp.ui.ouncemcp.AnthropicCounter(added after the draft): it follows a provider's token-counting API.
Made internal at 1.0¶
These are plumbing that is public only by accident. Each keeps working for one release with a DeprecationWarning.
ouncemcp.security.resolve_http_options: used byOunceServer.run; nobody needs to call it.ouncemcp.security.partition_key: used byPartitionedCacheonly.ouncemcp.shape_result,ouncemcp.PageWindow,ouncemcp.WriteAttempt,ouncemcp.WriteResolver: kept public but documented as advanced. The proposal is to keep them stable, becausewrite_resolver=and custom shaping are real extension points.
What else is part of the contract¶
These are visible to users and agents outside Python, so they get the same promise as the stable API.
- Wire contract:
- the error categories and codes;
- the
_meta["ouncemcp"]keys on results; _meta["ouncemcp/parallelSafe"]on tools;- the
handles.readandjobs.gettools and their inputs.
- Command line: command names, flags and exit codes of
ouncemcp check,context,audit,eval,benchandtrace. - Report files: JSON reports carry
report_version. A change that removes or renames a field bumps it, and readers of older versions keep working for one minor release. - Lint rule names, since CI configurations refer to them.
The rules after 1.0¶
- Semantic versioning.
- Patch releases fix bugs.
- Minor releases add names and options; provisional names may change here.
- Only a major release removes or changes stable names.
- Deprecation before removal. A stable name is deprecated (warning, changelog, docs) in a minor release and removed no earlier than the next major.
- Snapshot updates in the PR. Every change to the public API updates
tests/api_snapshot.jsonin the same PR. The PR says whether the change is an addition, a provisional change or a deprecation. - Defaults are API. Changing a default (budgets,
output_schemas, discovery thresholds,stdio_policy) counts as a breaking change unless it only makes results smaller or safer, and it needs a proposal. - Supported versions.
- Python: 3.11 and later, following CPython's end-of-life dates.
- FastMCP: a tested range within one FastMCP major,
>=4.1.6,<5, with CI testing the lowest and highest versions in that range.
Before declaring the freeze¶
- Snapshot test of every public name and signature, stable on Python 3.11 to 3.13.
- API reference generated from the code.
- Missing exports added:
JobResult,BudgetOverride,BudgetOverrideWarning;ouncemcp.traceandouncemcp.evaltracked. - Owner review of the stable and provisional lists above.
- Deprecate the two internal security helpers: they warn and will be removed in 1.1.
- Change the FastMCP pin to a tested range:
>=4.1.6,<5. The CI matrix tests 4.1.6 from the lockfile, and thefastmcp-latestjob tests the newest release (4.2.0 today). - Add a CHANGELOG with the 1.0 entry, and mark the stable modules in the API reference.
Alternatives considered¶
- Freezing everything exported today. That would lock in plumbing such as
resolve_http_optionsand the fast-moving eval APIs. - No provisional tier. Then the evaluation tools could not keep up with model APIs without a major release.
Impact on tokens and task success¶
None.