coulomb/phase-memory
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Implement local runtime persistence and policy gates

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-18 18:21:27 +02:00
parent 7f9913c45a
commit 8089a7c8fa
23 changed files with 2263 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

95
workplans/PMEM-MATURITY-SCORECARD.md
View File

@@ -44,31 +44,94 @@ not what adjacent repositories may already provide.
## Current Baseline - 2026-05-18
Overall maturity: **2.0 / 5**
Overall maturity: **3.1 / 5**
The repo has crossed from intent-only into a working deterministic library
foundation. It is not yet a usable local runtime because there is no facade,
CLI, file-backed persistence, review-gated apply path, package compiler bridge,
or service contract.
foundation, a usable local runtime facade, a CLI, a file-backed local
workspace, and first-slice policy/review/audit gates. It is not yet an
interop-complete runtime because richer Markitect package bridge, activation
quality, and service contracts remain ahead.
| Dimension | Current | Target | Evidence | Needed Next |
| --- | ---: | ---: | --- | --- |
| Intent and boundaries | 4.0 | 5.0 | `INTENT.md`, `SCOPE.md`, `README.md`, architecture doc, PMEM-WP-0001 closure | Keep boundaries current as runtime behavior expands. |
| Package foundation | 2.5 | 4.0 | Python package, exports, dependency-light tests | Add runtime facade, stable public envelopes, CLI. |
| Profile contract ingress | 2.0 | 4.0 | Markitect-compatible profile loading and diagnostics | Add validation adapter boundary and compatibility fixture catalog. |
| Graph/event contract ingress | 2.0 | 4.0 | Graph loading, edge endpoint diagnostics, event model | Add richer event path modeling and import/export repair diagnostics. |
| Phase domain model | 2.5 | 4.0 | Phases, memory kinds, lifecycle states, actions | Add transition rules, approved apply behavior, path-aware state updates. |
| Profile execution planning | 2.5 | 4.0 | Adapter plan, capabilities, policy gates, fallback behavior | Add runtime orchestration, JSON snapshots, CLI outputs. |
| Lifecycle planning | 2.0 | 4.0 | Transition, retention, refresh, compaction dry-run plans | Add profile-driven rule evaluation and review-gated apply. |
| Activation planning | 2.0 | 5.0 | Budgeted selection and Markitect-compatible selection output | Add graph neighborhoods, event paths, ranking, metadata preservation, metrics. |
| Local persistence | 1.0 | 4.0 | In-memory adapters only | Add versioned file-backed graph store and JSONL event log. |
| Policy and audit | 1.5 | 5.0 | Policy/audit ports, allow-all gateway, recording sink, review flags | Add enforcement points, review records, redaction, audit schema. |
| Observability and diagnostics | 1.5 | 4.0 | Planner diagnostics and observability event names | Add audit/health envelopes and adapter status diagnostics. |
| Package foundation | 3.0 | 4.0 | Python package, exports, runtime facade, CLI entrypoint, dependency-light tests | Add local persistence and richer adapter configuration. |
| Profile contract ingress | 2.5 | 4.0 | Markitect-compatible profile loading, diagnostics, runtime envelopes | Add validation adapter boundary and compatibility fixture catalog. |
| Graph/event contract ingress | 3.0 | 4.0 | Graph loading, edge endpoint diagnostics, event model, JSONL event log, export, repair diagnostics | Add richer policy-aware import/export checks. |
| Phase domain model | 3.0 | 4.0 | Phases, memory kinds, lifecycle states, actions, explicit path records | Add transition rule profiles and review records. |
| Profile execution planning | 3.0 | 4.0 | Adapter plan, capabilities, policy gates, fallback behavior, CLI output, snapshot fixture | Add profile-driven runtime configuration and compatibility validation. |
| Lifecycle planning | 3.0 | 4.0 | Transition, retention, refresh, compaction dry-run plans, review-gated local apply | Add profile-driven rule evaluation and full review records. |
| Activation planning | 2.5 | 5.0 | Budgeted selection, Markitect-compatible selection output, package request envelope, CLI output | Add graph neighborhoods, event paths, ranking, metadata preservation, metrics. |
| Local persistence | 3.0 | 4.0 | Versioned local workspace, file-backed graph store, JSONL event log, JSONL audit sink | Add migration/repair utilities and stronger durability semantics. |
| Policy and audit | 3.2 | 5.0 | Operation points, policy gateway checks, audit schema, review records, redaction, activation denials | Add external policy adapters and richer audit retention behavior. |
| Observability and diagnostics | 2.5 | 4.0 | Planner diagnostics, runtime diagnostics, event log corruption checks, repair diagnostics, policy denial diagnostics | Add health envelopes and adapter status diagnostics. |
| Markitect interop | 1.5 | 4.0 | Compatible schema constants and selection handoff | Add package bridge envelopes, optional validation/compiler adapters. |
| Kontextual/Infospace interop | 1.0 | 4.0 | Boundaries documented and small derived fixtures | Add delegation envelope design and evaluation fixture reports. |
| Testing and evaluation | 2.0 | 4.0 | 13 deterministic tests over core planners/adapters | Add CLI snapshots, file-store round trips, policy denial, activation metrics. |
| Testing and evaluation | 3.2 | 4.0 | 36 deterministic tests over planners, adapters, runtime envelopes, CLI, snapshots, file-store round trips, apply denial, review records, audit schema, and policy redaction | Add activation metrics. |
| Service readiness | 0.5 | 4.0 | Runtime ports exist | Add service contracts, config, health checks, adapter conformance tests. |
| Developer experience | 2.0 | 4.0 | README quick start and package map | Add CLI guide, local persistence guide, examples, troubleshooting. |
| Developer experience | 3.3 | 4.0 | README quick start, package map, runtime facade docs, CLI examples, local persistence guide | Add troubleshooting and richer examples. |
## Progress Update - PMEM-WP-0002
Closed on 2026-05-18:
- Added `PhaseMemoryRuntime` as the local application facade.
- Added JSON runtime envelopes with policy decisions, audit receipts,
diagnostics, dry-run flags, operation ids, and source references.
- Added `phase-memory` console script metadata and CLI commands for profile
planning, graph lifecycle planning, and graph activation planning.
- Added snapshot fixtures for profile-plan and activation-plan envelope shapes.
- Updated local usage and architecture docs.
Remaining maturity blockers:
- File-backed persistence and event path runtime.
- Review-gated apply behavior.
- Policy enforcement and redaction beyond the allow-all local adapter.
- Stronger Markitect compiler/validation bridge.
- Activation quality evaluation.
- Service contracts and external adapter conformance.
## Progress Update - PMEM-WP-0003
Closed on 2026-05-18:
- Added a versioned local file-backed workspace layout.
- Added deterministic file-backed profile, node, edge, and path storage.
- Added append-only JSONL event and audit adapters.
- Added graph export, event replay, and repair diagnostics.
- Added explicit conversational path records and path-event helpers.
- Added review-gated lifecycle apply behavior for local stores.
- Added store import/export/repair CLI coverage and local persistence docs.
Remaining maturity blockers:
- Policy operation vocabulary and review records.
- Activation-time policy checks and redaction.
- Stable audit event schema.
- Markitect compiler/validation bridge.
- Activation quality metrics.
- Service readiness and external adapter conformance.
## Progress Update - PMEM-WP-0004
Closed on 2026-05-18:
- Added canonical memory operation policy points.
- Added review records and deterministic review ids.
- Added stable audit event schema `phase_memory.audit.event.v1`.
- Added review-record enforcement for lifecycle apply.
- Added activation policy checks for labels, denied labels, trust zones,
secrets, reauthorization, and freshness.
- Added deterministic redaction records and diagnostics for denied activation
items.
- Added policy/audit documentation.
Remaining maturity blockers:
- Optional Markitect validation and package compiler bridge.
- Activation ranking and evaluation metrics.
- Service contracts, health diagnostics, and external adapter conformance.
## Score Movement Rules

62
workplans/PMEM-WP-0002-local-runtime-facade-and-cli.md
View File

@@ -4,7 +4,7 @@ type: workplan
title: "Local Runtime Facade And CLI"
domain: markitect
repo: phase-memory
status: proposed
status: finished
owner: phase-memory
topic_slug: local-runtime
planning_priority: P1
@@ -50,11 +50,34 @@ together and there is no command-line path for inspecting plans.
- Do not start a long-lived HTTP service in this workplan.
- Do not add live LLM, vector, or graph database dependencies.
## Implementation Update - 2026-05-18
The local runtime and CLI slice is complete.
Implemented outputs:
- `src/phase_memory/runtime.py` defines `PhaseMemoryRuntime` with stable
runtime envelopes for profile import, graph import, profile planning,
lifecycle planning, activation planning, and package compilation handoff.
- `src/phase_memory/cli.py` adds dependency-light `argparse` commands for
profile planning, graph lifecycle planning, and graph activation planning.
- `pyproject.toml` exposes the installed console script as `phase-memory`.
- Runtime and CLI tests cover JSON envelopes, dry-run lifecycle actions,
package requests, summary output, and console-script metadata.
- Snapshot fixtures pin the public profile-plan and activation-plan envelope
shape without freezing internal dataclass details.
- `README.md` and `docs/architecture.md` document local usage, the facade
boundary, dry-run guarantees, and adjacent-repo expectations.
Validation:
- `python3 -m pytest` -> 23 passed.
## T01 - Add a local runtime facade
```task
id: PMEM-WP-0002-T01
status: todo
status: done
priority: high
state_hub_task_id: "456557a9-3ac3-483b-bbdd-5591224894b9"
```
@@ -78,7 +101,7 @@ usable, but gives integrations one obvious local entrypoint.
```task
id: PMEM-WP-0002-T02
status: todo
status: done
priority: high
state_hub_task_id: "b04054cb-d743-4fcd-9b37-2685d1f9c00d"
```
@@ -100,7 +123,7 @@ ids, dry-run flags, and source contract references.
```task
id: PMEM-WP-0002-T03
status: todo
status: done
priority: high
state_hub_task_id: "8463924e-a6ce-43f1-b7fc-544a2aa7fd5f"
```
@@ -120,7 +143,7 @@ Output: CLI command, tests around success and diagnostics, and README usage.
```task
id: PMEM-WP-0002-T04
status: todo
status: done
priority: high
state_hub_task_id: "ab818835-5ef3-4a43-adf2-444ab712ead9"
```
@@ -142,7 +165,7 @@ refresh, and compaction proposals.
```task
id: PMEM-WP-0002-T05
status: todo
status: done
priority: medium
state_hub_task_id: "9c8e8511-f00a-4685-91b5-a52c93d8461d"
```
@@ -161,7 +184,7 @@ Output: activation command, deterministic output tests, and README usage.
```task
id: PMEM-WP-0002-T06
status: todo
status: done
priority: medium
state_hub_task_id: "a005aa31-053e-4b51-b3ea-3bebf24ac833"
```
@@ -176,7 +199,7 @@ Output: stable examples for downstream repos and future compatibility checks.
```task
id: PMEM-WP-0002-T07
status: todo
status: done
priority: medium
state_hub_task_id: "f6c6c6b2-141a-44da-a3d5-dbef95559049"
```
@@ -200,3 +223,26 @@ five minutes.
the CLI against existing fixtures.
- Runtime outputs are deterministic and JSON-serializable.
- No default path mutates durable memory stores.
## Closure Review - 2026-05-18
**Outcome:** All tasks completed.
### Completed
- PMEM-WP-0002-T01 - Add a local runtime facade
- PMEM-WP-0002-T02 - Define runtime input and output envelopes
- PMEM-WP-0002-T03 - Implement profile planning CLI
- PMEM-WP-0002-T04 - Implement graph lifecycle CLI
- PMEM-WP-0002-T05 - Implement activation CLI
- PMEM-WP-0002-T06 - Add snapshot tests for CLI and runtime envelopes
- PMEM-WP-0002-T07 - Update documentation for local usage
### Cancelled
None.
### Carried Forward
Local persistence, review-gated apply behavior, richer policy enforcement, and
external adapter readiness remain in PMEM-WP-0003 through PMEM-WP-0007.

64
workplans/PMEM-WP-0003-file-backed-stores-and-event-path-runtime.md
View File

@@ -4,7 +4,7 @@ type: workplan
title: "File-Backed Stores And Event Path Runtime"
domain: markitect
repo: phase-memory
status: proposed
status: finished
owner: phase-memory
topic_slug: local-persistence
planning_priority: P1
@@ -42,11 +42,36 @@ first-class runtime objects.
- 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: todo
status: done
priority: high
state_hub_task_id: "37d082c7-c019-4ecd-8655-94f8f27807ff"
```
@@ -70,7 +95,7 @@ Output: documented storage layout, schema version fields, and fixture examples.
```task
id: PMEM-WP-0003-T02
status: todo
status: done
priority: high
state_hub_task_id: "c417f7ec-0423-4723-91c3-3b4681e30ec3"
```
@@ -90,7 +115,7 @@ Output: adapter implementation and tests for round-trip behavior.
```task
id: PMEM-WP-0003-T03
status: todo
status: done
priority: high
state_hub_task_id: "1d3b3ffb-fc9b-401f-a77f-cfad4a4f6b72"
```
@@ -109,7 +134,7 @@ Output: event log adapter and tests for append, list, replay, and diagnostics.
```task
id: PMEM-WP-0003-T04
status: todo
status: done
priority: high
state_hub_task_id: "43d5863c-f2db-441e-8f3e-7e1843b6bc33"
```
@@ -131,7 +156,7 @@ abandon flows without requiring transcript storage.
```task
id: PMEM-WP-0003-T05
status: todo
status: done
priority: medium
state_hub_task_id: "e9079c0c-5834-47b2-b1dc-1d97604c96f8"
```
@@ -147,7 +172,7 @@ unapproved durable actions are denied.
```task
id: PMEM-WP-0003-T06
status: todo
status: done
priority: medium
state_hub_task_id: "a0597e3e-2f2d-4abf-8fc2-37c914e0ce34"
```
@@ -166,7 +191,7 @@ Output: CLI/runtime helpers and tests for useful diagnostics.
```task
id: PMEM-WP-0003-T07
status: todo
status: done
priority: medium
state_hub_task_id: "60b3bce7-3e73-427b-95d7-d68283503a3c"
```
@@ -186,3 +211,26 @@ Output: local persistence guide and README pointers.
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.

66
workplans/PMEM-WP-0004-policy-audit-and-review-gates.md
View File

@@ -4,7 +4,7 @@ type: workplan
title: "Policy, Audit, And Review Gates"
domain: markitect
repo: phase-memory
status: proposed
status: finished
owner: phase-memory
topic_slug: policy-audit
planning_priority: P1
@@ -52,11 +52,38 @@ activations, writes, compactions, and phase transitions.
- Do not make `flex-auth` a hard dependency.
- Do not store or expose secrets in test fixtures.
## Implementation Update - 2026-05-18
The policy, audit, and review-gate slice is complete.
Implemented outputs:
- `phase_memory.policy` defines canonical memory operation points, audit event
schema helpers, review-record helpers, activation policy checks, and
deterministic redaction.
- `ReviewRecord` and `ReviewDecision` model structured local approvals and
rejections for review-gated lifecycle actions.
- Runtime audit events now use `phase_memory.audit.event.v1` and carry policy
decisions, source references, dry-run flags, actor labels, and subjects.
- `apply_lifecycle_actions` rejects review-required actions unless the caller
provides a matching approved review record or explicit local approval marker.
- Activation planning can evaluate required labels, denied labels, trust zones,
secret denial, reauthorization, and freshness policy context before package
selection.
- Policy-denied activation nodes are omitted and returned as redacted denial
records with diagnostics.
- `docs/policy-audit.md` documents operation points, review records,
activation policy, audit envelopes, and ownership boundaries.
Validation:
- `python3 -m pytest` -> 36 passed.
## T01 - Define memory operation policy points
```task
id: PMEM-WP-0004-T01
status: todo
status: done
priority: high
state_hub_task_id: "1231b7bf-b23c-498d-a9d6-a6ee307aa3d4"
```
@@ -82,7 +109,7 @@ the right boundary.
```task
id: PMEM-WP-0004-T02
status: todo
status: done
priority: high
state_hub_task_id: "b989d43c-eb25-4663-afd1-a54673ad565a"
```
@@ -107,7 +134,7 @@ Output: review record model and approval checks in the runtime facade.
```task
id: PMEM-WP-0004-T03
status: todo
status: done
priority: high
state_hub_task_id: "6b677c18-7135-4d54-9e46-5116645d2ebe"
```
@@ -122,7 +149,7 @@ and deletion requests cannot be applied silently.
```task
id: PMEM-WP-0004-T04
status: todo
status: done
priority: high
state_hub_task_id: "6f07087b-e6e2-469a-9bce-71bfd21cb633"
```
@@ -143,7 +170,7 @@ for policy-denied records.
```task
id: PMEM-WP-0004-T05
status: todo
status: done
priority: medium
state_hub_task_id: "bb6461a8-9181-4b88-a152-334668b22208"
```
@@ -169,7 +196,7 @@ apply operations.
```task
id: PMEM-WP-0004-T06
status: todo
status: done
priority: medium
state_hub_task_id: "dcdec3af-d20f-43ba-b12e-6febc4347d38"
```
@@ -183,7 +210,7 @@ Output: redaction utility, denied activation examples, and regression tests.
```task
id: PMEM-WP-0004-T07
status: todo
status: done
priority: medium
state_hub_task_id: "c4e0bdff-5047-4fe5-ab86-e422d4b1a17e"
```
@@ -202,3 +229,26 @@ review-required operations.
- Review-required actions fail closed without an explicit review record.
- The policy layer remains adapter-based and does not become an identity
platform.
## Closure Review - 2026-05-18
**Outcome:** All tasks completed.
### Completed
- PMEM-WP-0004-T01 - Define memory operation policy points
- PMEM-WP-0004-T02 - Add review authorization records
- PMEM-WP-0004-T03 - Enforce durable write gates
- PMEM-WP-0004-T04 - Add activation policy checks
- PMEM-WP-0004-T05 - Add audit event schema
- PMEM-WP-0004-T06 - Add redaction and denial diagnostics
- PMEM-WP-0004-T07 - Document policy and audit guarantees
### Cancelled
None.
### Carried Forward
Optional Markitect validation and context-package compiler bridge behavior
remain in PMEM-WP-0005.