Files

tegwick 8089a7c8fa Implement local runtime persistence and policy gates

2026-05-18 18:21:27 +02:00

6.5 KiB

Raw Blame History

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, related_workplans, created, updated, state_hub_workstream_id

type

title

domain

repo

status

owner

topic_slug

planning_priority

planning_order

related_workplans

created

updated

state_hub_workstream_id

PMEM-WP-0003

workplan

File-Backed Stores And Event Path Runtime

markitect

phase-memory

finished

phase-memory

local-persistence

PMEM-WP-0002

2026-05-18

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

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

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

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

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

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

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

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.

6.5 KiB Raw Blame History