phase-memory/docs/api-compatibility.md

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.