Implement local runtime persistence and policy gates

docs/local-persistence.md

@@ -0,0 +1,91 @@
+# Local Persistence
+
+`phase-memory` can run against a versioned local file workspace. This is a
+developer and integration adapter, not a production graph database.
+
+## Layout
+
+```text
+memory-store/
+  phase-memory.json
+  profiles/
+    <profile-id>.json
+  nodes/
+    <node-id>.json
+  edges/
+    <edge-id>.json
+  paths/
+    <path-id>.json
+  activations/
+  events.jsonl
+  audit.jsonl
+```
+
+The root `phase-memory.json` declares:
+
+```json
+{
+  "schema_version": "phase_memory.local_store.v1"
+}
+```
+
+Profiles, nodes, edges, and paths are stored as deterministic JSON files.
+Events and audit records are append-only JSONL files. The current local runtime
+does not compact, delete, or rewrite append-only logs.
+
+## CLI
+
+Import local fixtures:
+
+```bash
+PYTHONPATH=src python3 -m phase_memory.cli store import \
+  --store .phase-memory-local \
+  --profile tests/fixtures/memory-profile.json \
+  --graph tests/fixtures/memory-graph.json
+```
+
+Export a Markitect-compatible graph envelope:
+
+```bash
+PYTHONPATH=src python3 -m phase_memory.cli store export \
+  --store .phase-memory-local \
+  --graph-id local-dev
+```
+
+Inspect repair diagnostics:
+
+```bash
+PYTHONPATH=src python3 -m phase_memory.cli store repair \
+  --store .phase-memory-local
+```
+
+Repair diagnostics report malformed JSONL event lines, unknown event schema
+versions, missing edge endpoints, and path records that reference events not
+present in the event log.
+
+## Paths
+
+Conversational paths are structured records, not transcript blobs. A path can
+record:
+
+- `path_id`
+- `parent_path_id`
+- ordered `event_ids`
+- active, merged, abandoned, or compacted state
+- merge target
+- abandoned reason
+- compacted summary id
+
+Helper functions in `phase_memory.paths` create, branch, merge, abandon, and
+compact paths while also producing structured path events for the fluid memory
+event log.
+
+## Review-Gated Apply
+
+Lifecycle planning remains dry-run by default. The runtime exposes an optional
+`apply_lifecycle_actions` operation for local stores. Actions marked
+`requires_review` are denied unless the caller provides an explicit
+`approval_marker`.
+
+This keeps the local adapter useful for development while preserving the
+project rule that durable memory changes must be inspectable and deliberate.