phase-memory/docs/operational-readiness.md

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

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:

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:

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:

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.