phase-memory/docs/operational-readiness.md

# Operational Readiness Recipe

Updated: 2026-05-19

This recipe exercises the local operational surface without requiring live
Markitect, Kontextual, or telemetry services. It is the expected smoke path for
embedding `phase-memory` in another local agent runtime.

## Local End-To-End Flow

```python
import json
from pathlib import Path

from phase_memory import LocalServiceRunner

fixtures = Path("tests/fixtures")
profile = json.loads((fixtures / "memory-profile.json").read_text(encoding="utf-8"))
graph = json.loads((fixtures / "memory-graph.json").read_text(encoding="utf-8"))

runner = LocalServiceRunner()

profile_plan = runner.handle("profile.plan", {"profile": profile, "source_ref": "recipe:profile"})
graph_import = runner.handle("graph.import", {"graph": graph, "source_ref": "recipe:graph"})
lifecycle = runner.handle(
    "graph.lifecycle.plan",
    {
        "profile": profile,
        "graph": graph,
        "parameters": {"refresh_digests": {"event.restart": "new-digest"}},
        "source_ref": "recipe:lifecycle",
    },
)
activation = runner.handle(
    "graph.activation.plan",
    {
        "graph": graph,
        "budget": {"max_items": 3, "max_tokens": 60},
        "profile_id": profile["id"],
        "source_ref": "recipe:activation",
    },
)
package = runner.handle(
    "package.compile",
    {
        "selection": activation["data"]["activation_plan"]["selection"],
        "source_ref": "recipe:package",
    },
)
audit = runner.handle("audit.query", {"filters": {"operation": "package.compile"}})
health = runner.handle("health.check")
```

Expected checks:

- `profile_plan["valid"]`, `graph_import["valid"]`, `activation["valid"]`, and
  `package["valid"]` are true.
- `lifecycle["data"]["dry_run_actions"]` contains the planned refresh action.
- `audit["count"]` is at least 1 and `audit["retention"]` declares the active
  audit sink retention mode.
- `health["ok"]` is true.

## Service Binding Drill

`ServiceBinding` wraps `LocalServiceRunner` in an HTTP-shaped API without
starting a listener:

```python
from phase_memory import ServiceBinding

binding = ServiceBinding(runner)

health_response = binding.route("GET", "/health")
ready_response = binding.route("GET", "/ready")
contracts_response = binding.route("GET", "/contracts")
package_response = binding.route(
    "POST",
    "/operations/package.compile",
    {"selection": activation["data"]["activation_plan"]["selection"]},
)
```

The WSGI adapter returned by `binding.as_wsgi_app()` is also callable in tests
without opening a socket. Use this for deployment wrappers so the core service
operation contract stays framework-neutral.

For the stdlib deployable entrypoint, use:

```bash
phase-memory-service --check --store .phase-memory-local
phase-memory-service --host 127.0.0.1 --port 8080 --store .phase-memory-local
```

See `docs/operator-readiness-runbook.md` for operator checks and rollback
guidance.

## Review-Gated Apply

Lifecycle actions that require review are denied until an approval marker or
matching review record is supplied:

```python
denied = runner.handle("lifecycle.apply", {"actions": lifecycle["data"]["dry_run_actions"]})
approved = runner.handle(
    "lifecycle.apply",
    {
        "actions": lifecycle["data"]["dry_run_actions"],
        "approval_marker": "review:operator-approved",
    },
)
```

Use `audit.query` with `{"operation": "lifecycle.apply", "dry_run": False}` to
trace denied and approved apply attempts.

## Persistence Repair Drill

File-backed operation is configured through a profile or explicit
`RuntimeConfig`:

```python
from phase_memory import RuntimeConfig, LocalServiceRunner

config = RuntimeConfig.from_profile(profile, local_store_path=".phase-memory-local")
runner = LocalServiceRunner(config=config)
repair = runner.runtime.repair_diagnostics(source_ref=config.local_store_path)
migration_plan = runner.runtime.plan_store_migration(source_ref=config.local_store_path)
migration_apply = runner.runtime.apply_store_migration(
    migration_plan["data"]["migration_plan"],
    actor="operator",
    source_ref=config.local_store_path,
)
```

Repair diagnostics distinguish:

- `store_migration_required` for old or missing local-store schema metadata.
- `planned_store_migrations` when metadata declares pending migrations.
- `corrupt_store_record` for unreadable node, edge, or path JSON.
- `missing_edge_source` / `missing_edge_target` for graph reference damage.
- `orphaned_path_event` when paths reference absent event-log records.

Migration apply is audited as `store.migration.apply` and updates metadata
atomically when changes are needed.

## Audit Export And Retention Drill

Runtime audit behavior is inspectable beyond point queries:

```python
export = runner.runtime.export_audit_events({"operation": "package.compile"})
retention = runner.runtime.audit_retention_plan(retention_days=30)
```

The export batch includes matching audit events and sink retention metadata.
The retention plan identifies eligible operation ids. Retention apply prunes
eligible records and records `audit.retention.apply` after pruning:

```python
retention_apply = runner.runtime.apply_audit_retention(retention["plan"])
```

## Adapter Pack Compatibility

Fake and future live adapter packs should publish a manifest with:

- declared capabilities;
- ownership boundaries for every adapter;
- required conformance helpers.

Validate fake or live-shaped packs before wiring them into the runtime:

```python
from phase_memory import fake_external_adapter_pack, live_shaped_adapter_pack, validate_adapter_pack_manifest

diagnostics = validate_adapter_pack_manifest(fake_external_adapter_pack())
assert diagnostics == ()

live_diagnostics = validate_adapter_pack_manifest(live_shaped_adapter_pack())
assert live_diagnostics == ()
```

Missing capabilities are reported as `missing_adapter_capability` diagnostics
with the adapter and capability names attached.

## API Compatibility Expectations

The stable embedding surface is:

- `PhaseMemoryRuntime` methods and JSON-serializable envelopes.
- `LocalServiceRunner.handle(operation, payload)` for every operation in
  `service_contracts()["operations"]`.
- `RuntimeConfig` and `resolve_runtime_adapters` for local/external adapter
  resolution.
- `ServiceBinding` and `service_binding_from_config` for optional service
  wrappers.
- Adapter conformance helpers in `phase_memory.service`.
- External adapter pack manifests and validation helpers.
- Public export and service operation snapshots in
  `tests/fixtures/public-api-snapshot.json`.

New public operations should be added to the service contract first, then to
the local runner, runtime tests, and docs in the same change.