# Operational Readiness Recipe

Updated: 2026-05-18

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.

## 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)
```

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.

## 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 a pack before wiring it into the runtime:

```python
from phase_memory import fake_external_adapter_pack, validate_adapter_pack_manifest

diagnostics = validate_adapter_pack_manifest(fake_external_adapter_pack())
assert 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.
- Adapter conformance helpers in `phase_memory.service`.
- External adapter pack manifests and validation helpers.

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