Implement live-shaped readiness workplan

docs/api-compatibility.md

@@ -0,0 +1,46 @@
+# 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.