generated from coulomb/repo-seed
52 lines
1.8 KiB
Markdown
52 lines
1.8 KiB
Markdown
# API Compatibility
|
|
|
|
Updated: 2026-05-19
|
|
|
|
`phase-memory` now treats its embedding surface as a compatibility contract for
|
|
local integrations.
|
|
|
|
## Stable Surface
|
|
|
|
The public surface is:
|
|
|
|
- exports listed in `phase_memory.__all__`;
|
|
- `PhaseMemoryRuntime` JSON-serializable runtime envelopes;
|
|
- `LocalServiceRunner.handle(operation, payload)`;
|
|
- every operation declared by `service_contracts()["operations"]`;
|
|
- `ServiceBinding` and `service_binding_from_config` as optional
|
|
framework-neutral binding helpers;
|
|
- `RuntimeConfig`, `resolve_runtime_adapters`, and `runtime_from_config`;
|
|
- adapter pack manifests and `validate_adapter_pack_manifest`;
|
|
- evaluation threshold reports from `evaluation_threshold_report`.
|
|
|
|
The snapshot in `tests/fixtures/public-api-snapshot.json` intentionally fails
|
|
when exports or service operations change. Update the snapshot only when the
|
|
change is deliberate and documented.
|
|
|
|
The snapshot also points to `docs/release-note-template.md`. When a public API
|
|
snapshot changes, fill in that template or a release note derived from it so
|
|
operators can see changed exports, changed service operations, migration needs,
|
|
and required action.
|
|
|
|
## Adding Operations
|
|
|
|
When adding a service operation:
|
|
|
|
1. Add the operation to `SERVICE_OPERATIONS`.
|
|
2. Add a `LocalServiceRunner` dispatch path.
|
|
3. Add binding and runner tests that exercise the operation without starting a
|
|
network listener.
|
|
4. Update the API snapshot.
|
|
5. Note the change in docs or release notes.
|
|
|
|
## Breaking Changes
|
|
|
|
Breaking changes should include:
|
|
|
|
- a migration note in this document or release notes;
|
|
- a compatibility test update explaining the intentional break;
|
|
- StateHub workplan evidence for why the break is needed.
|
|
|
|
Avoid changing runtime envelope keys, service operation names, adapter manifest
|
|
schema fields, or fixture schema names without a migration path.
|