# 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.

## 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.