generated from coulomb/repo-seed
237 lines
6.5 KiB
Markdown
237 lines
6.5 KiB
Markdown
---
|
|
id: PMEM-WP-0003
|
|
type: workplan
|
|
title: "File-Backed Stores And Event Path Runtime"
|
|
domain: markitect
|
|
repo: phase-memory
|
|
status: finished
|
|
owner: phase-memory
|
|
topic_slug: local-persistence
|
|
planning_priority: P1
|
|
planning_order: 30
|
|
related_workplans:
|
|
- PMEM-WP-0002
|
|
created: "2026-05-18"
|
|
updated: "2026-05-18"
|
|
state_hub_workstream_id: "c15d2f61-449b-48fa-9e4d-ea22a9b419b2"
|
|
---
|
|
|
|
# PMEM-WP-0003: File-Backed Stores And Event Path Runtime
|
|
|
|
## Goal
|
|
|
|
Add a local-first durable adapter layer that can persist profiles, graph
|
|
records, and append-only memory events without requiring external
|
|
infrastructure.
|
|
|
|
This should move the project from deterministic in-memory tests to a useful
|
|
developer runtime while preserving the INTENT.md principle that durable writes
|
|
are explicit, inspectable, and policy-aware.
|
|
|
|
## Current Evidence
|
|
|
|
The repository has port protocols and in-memory adapters, but no file-backed
|
|
store, event replay, export, import, or durable local graph snapshot format.
|
|
The memory event model also exists, but conversational paths are not yet
|
|
first-class runtime objects.
|
|
|
|
## Non-Goals
|
|
|
|
- Do not choose a production graph database.
|
|
- Do not implement a generic vector database.
|
|
- Do not add hidden background compaction or deletion.
|
|
- Do not make file-backed storage the only adapter option.
|
|
|
|
## Implementation Update - 2026-05-18
|
|
|
|
The local persistence and event-path runtime slice is complete.
|
|
|
|
Implemented outputs:
|
|
|
|
- `FileBackedMemoryGraphStore` stores profiles, nodes, edges, and path records
|
|
as deterministic JSON under a versioned local workspace layout.
|
|
- `JsonlMemoryEventLog` provides append-only event logging, duplicate event id
|
|
detection, kind filtering, graph replay, and corruption/schema diagnostics.
|
|
- `JsonlAuditSink` records local runtime audit events into `audit.jsonl`.
|
|
- `MemoryPath` and `phase_memory.paths` model branch, merge, abandon, compact,
|
|
and structured path-event behavior without transcript storage.
|
|
- `PhaseMemoryRuntime` can export local graph state, report repair diagnostics,
|
|
and apply lifecycle actions only when review-required actions include an
|
|
explicit approval marker.
|
|
- CLI store commands can import fixtures, export local graph envelopes, and
|
|
report repair diagnostics.
|
|
- `docs/local-persistence.md` documents the storage layout, CLI flow, path
|
|
model, and review-gated apply rule.
|
|
|
|
Validation:
|
|
|
|
- `python3 -m pytest` -> 31 passed.
|
|
|
|
## T01 - Define local storage layout
|
|
|
|
```task
|
|
id: PMEM-WP-0003-T01
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "37d082c7-c019-4ecd-8655-94f8f27807ff"
|
|
```
|
|
|
|
Define a simple versioned local storage layout for:
|
|
|
|
- profiles
|
|
- nodes
|
|
- edges
|
|
- events
|
|
- activation plans
|
|
- audit records
|
|
- runtime metadata
|
|
|
|
Prefer JSON and JSONL formats for this slice unless a concrete requirement
|
|
forces SQLite.
|
|
|
|
Output: documented storage layout, schema version fields, and fixture examples.
|
|
|
|
## T02 - Implement a file-backed graph store
|
|
|
|
```task
|
|
id: PMEM-WP-0003-T02
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "c417f7ec-0423-4723-91c3-3b4681e30ec3"
|
|
```
|
|
|
|
Implement a deterministic adapter for the `MemoryGraphStore` protocol that can:
|
|
|
|
- save and load profiles
|
|
- save and load nodes
|
|
- save and load edges
|
|
- list nodes by kind
|
|
- list edges by source or target
|
|
- export a Markitect-compatible graph envelope
|
|
|
|
Output: adapter implementation and tests for round-trip behavior.
|
|
|
|
## T03 - Implement a JSONL event log
|
|
|
|
```task
|
|
id: PMEM-WP-0003-T03
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "1d3b3ffb-fc9b-401f-a77f-cfad4a4f6b72"
|
|
```
|
|
|
|
Implement an append-only `MemoryEventLog` adapter with:
|
|
|
|
- duplicate event id detection
|
|
- deterministic ordering
|
|
- kind filtering
|
|
- replay into graph snapshots where possible
|
|
- corruption diagnostics for malformed lines
|
|
|
|
Output: event log adapter and tests for append, list, replay, and diagnostics.
|
|
|
|
## T04 - Model conversational paths explicitly
|
|
|
|
```task
|
|
id: PMEM-WP-0003-T04
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "43d5863c-f2db-441e-8f3e-7e1843b6bc33"
|
|
```
|
|
|
|
Add first-slice path records for fluid memory:
|
|
|
|
- path id
|
|
- parent path id
|
|
- event ids
|
|
- active branch marker
|
|
- merge marker
|
|
- abandoned branch reason
|
|
- compaction status
|
|
|
|
Output: path model, path event helpers, and tests that show branch, merge, and
|
|
abandon flows without requiring transcript storage.
|
|
|
|
## T05 - Add safe apply behavior behind review gates
|
|
|
|
```task
|
|
id: PMEM-WP-0003-T05
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "e9079c0c-5834-47b2-b1dc-1d97604c96f8"
|
|
```
|
|
|
|
Add an optional runtime operation that applies approved lifecycle actions to a
|
|
file-backed store. The operation must reject actions that require review unless
|
|
the caller provides an explicit approval marker.
|
|
|
|
Output: apply operation, approval checks, audit records, and tests that prove
|
|
unapproved durable actions are denied.
|
|
|
|
## T06 - Add import, export, and repair diagnostics
|
|
|
|
```task
|
|
id: PMEM-WP-0003-T06
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "a0597e3e-2f2d-4abf-8fc2-37c914e0ce34"
|
|
```
|
|
|
|
Add local tooling to:
|
|
|
|
- import Markitect-compatible graph and profile fixtures
|
|
- export local state to a graph envelope
|
|
- report missing edge endpoints
|
|
- report orphaned events
|
|
- report unknown schema versions
|
|
|
|
Output: CLI/runtime helpers and tests for useful diagnostics.
|
|
|
|
## T07 - Update docs with local persistence examples
|
|
|
|
```task
|
|
id: PMEM-WP-0003-T07
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "60b3bce7-3e73-427b-95d7-d68283503a3c"
|
|
```
|
|
|
|
Document how to create a local memory workspace, import a profile and graph,
|
|
append events, inspect paths, and export a graph.
|
|
|
|
Output: local persistence guide and README pointers.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- `python3 -m pytest` passes.
|
|
- File-backed adapters satisfy the same public protocols as in-memory adapters.
|
|
- A local workspace can be created, inspected, exported, and replayed
|
|
deterministically.
|
|
- Review-required actions cannot be applied without an explicit approval
|
|
marker.
|
|
- Conversational path branches and merges are represented as structured memory
|
|
events, not only as transcript text.
|
|
|
|
## Closure Review - 2026-05-18
|
|
|
|
**Outcome:** All tasks completed.
|
|
|
|
### Completed
|
|
|
|
- PMEM-WP-0003-T01 - Define local storage layout
|
|
- PMEM-WP-0003-T02 - Implement a file-backed graph store
|
|
- PMEM-WP-0003-T03 - Implement a JSONL event log
|
|
- PMEM-WP-0003-T04 - Model conversational paths explicitly
|
|
- PMEM-WP-0003-T05 - Add safe apply behavior behind review gates
|
|
- PMEM-WP-0003-T06 - Add import, export, and repair diagnostics
|
|
- PMEM-WP-0003-T07 - Update docs with local persistence examples
|
|
|
|
### Cancelled
|
|
|
|
None.
|
|
|
|
### Carried Forward
|
|
|
|
Policy enforcement, review record modeling, activation redaction, and richer
|
|
audit schema remain in PMEM-WP-0004.
|