generated from coulomb/repo-seed
137 lines
4.3 KiB
Markdown
137 lines
4.3 KiB
Markdown
# 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.
|