Implement refinement hardening workplan

2026-05-18 23:56:41 +02:00
parent 836acf7e01
commit 0eea94d05e
17 changed files with 1164 additions and 68 deletions
--- a/docs/operational-readiness.md
+++ b/docs/operational-readiness.md
@@ -0,0 +1,136 @@
+# 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.