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

Add Markitect bridge and activation quality

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-18 20:04:40 +02:00
parent 8089a7c8fa
commit 1efb7d4c13
19 changed files with 871 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -44,30 +44,30 @@ not what adjacent repositories may already provide.
## Current Baseline - 2026-05-18
Overall maturity: **3.1 / 5**
Overall maturity: **3.7 / 5**
The repo has crossed from intent-only into a working deterministic library
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.
workspace, first-slice policy/review/audit gates, and a concrete Markitect
package bridge, and deterministic activation quality helpers. It is not yet
service-ready.
| 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 | 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. |
| Package foundation | 3.0 | 4.0 | Python package, exports, runtime facade, CLI entrypoint, dependency-light tests | Add runtime configuration, service contracts, and adapter conformance. |
| Profile contract ingress | 2.5 | 4.0 | Markitect-compatible profile loading, diagnostics, runtime envelopes | Add profile-driven runtime configuration and richer compatibility coverage. |
| Graph/event contract ingress | 3.0 | 4.0 | Graph loading, edge endpoint diagnostics, event model, JSONL event log, export, repair diagnostics | Add service-level import/export contracts and adapter conformance. |
| Phase domain model | 3.0 | 4.0 | Phases, memory kinds, lifecycle states, actions, explicit path records | Add profile-driven transition rule evaluation and migration semantics. |
| Profile execution planning | 3.0 | 4.0 | Adapter plan, capabilities, policy gates, fallback behavior, CLI output, snapshot fixture | Add runtime configuration model and service-readiness diagnostics. |
| Lifecycle planning | 3.0 | 4.0 | Transition, retention, refresh, compaction dry-run plans, review-gated local apply | Add profile-driven rule evaluation and service apply contracts. |
| Activation planning | 3.8 | 5.0 | Budgeted selection, Markitect-compatible selection output, package request envelope, graph neighborhoods, event paths, ranking, metadata preservation, metrics | Add semantic-index adapters and broader evaluation corpora. |
| 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 | 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. |
| Markitect interop | 3.5 | 4.0 | Compatible contract ingress, optional validation boundary, enriched selection metadata, package request/response envelopes | Add live optional Markitect compiler adapter when available. |
| Kontextual/Infospace interop | 1.5 | 4.0 | Boundaries documented, small derived fixtures, activation quality report fixture | Add Kontextual delegation envelopes and broader Infospace evaluation fixture reports. |
| Testing and evaluation | 3.7 | 4.0 | 46 deterministic tests over planners, adapters, runtime envelopes, CLI, snapshots, file-store round trips, apply denial, review records, audit schema, policy redaction, Markitect bridge fixtures, retrieval, and activation metrics | Add broader evaluation corpora. |
| Service readiness | 0.5 | 4.0 | Runtime ports exist | Add service contracts, config, health checks, adapter conformance tests. |
| Developer experience | 3.3 | 4.0 | README quick start, package map, runtime facade docs, CLI examples, local persistence guide | Add troubleshooting and richer examples. |
@@ -113,6 +113,26 @@ Remaining maturity blockers:
- Activation quality metrics.
- Service readiness and external adapter conformance.
## Progress Update - PMEM-WP-0006
Closed on 2026-05-18:
- Added deterministic graph-neighborhood retrieval.
- Added event-path selection from structured memory paths.
- Added candidate scoring and explanation reasons.
- Added pluggable token estimator protocol with deterministic word-count
default.
- Added activation quality report metrics and fixture.
- Documented retrieval and evaluation behavior.
Remaining maturity blockers:
- Service API contracts.
- Runtime configuration model.
- Health diagnostics.
- External adapter conformance tests.
- Kontextual delegation adapter design.
## Progress Update - PMEM-WP-0004
Closed on 2026-05-18:
@@ -133,6 +153,25 @@ Remaining maturity blockers:
- Activation ranking and evaluation metrics.
- Service contracts, health diagnostics, and external adapter conformance.
## Progress Update - PMEM-WP-0005
Closed on 2026-05-18:
- Added Markitect package request and response envelopes.
- Added local and optional Markitect validation adapter boundary.
- Preserved selected item source spans, provenance, confidence, freshness,
namespace, policy metadata, and selection reasons through activation.
- Added compatibility fixtures and tests for invalid contracts, activation
package requests, and opaque package responses.
- Documented the Markitect boundary.
Remaining maturity blockers:
- Graph-neighborhood retrieval and event-path activation.
- Ranking signals and token accounting.
- Activation quality metrics and evaluation fixtures.
- Service readiness and external adapter conformance.
## Score Movement Rules
A dimension should move up only when executable behavior and tests exist.

62
workplans/PMEM-WP-0005-markitect-package-bridge-and-contract-interop.md
View File

@@ -4,7 +4,7 @@ type: workplan
title: "Markitect Package Bridge And Contract Interop"
domain: markitect
repo: phase-memory
status: proposed
status: finished
owner: phase-memory
topic_slug: markitect-interop
planning_priority: P1
@@ -49,11 +49,37 @@ delegation, and stable package request/response envelopes.
- Do not require Markitect installation for the default test suite.
- Do not turn Markitect into a hidden import dependency.
## Implementation Update - 2026-05-18
The Markitect bridge and contract interop slice is complete.
Implemented outputs:
- `phase_memory.bridge` defines package request and response envelopes,
dependency-light local validation, and an optional Markitect validator
adapter shell.
- Activation selections now preserve selected-item source spans, provenance,
confidence, freshness, namespace, policy metadata, and reason selected.
- Runtime package requests use
`phase_memory.markitect.package_request.v1` and keep selected node/event,
budget, policy, provenance, compiler, and selection data explicit.
- Package compiler responses are wrapped as
`phase_memory.markitect.package_response.v1` while keeping Markitect internals
opaque.
- Interop fixtures cover valid profiles/graphs, invalid profiles/graphs,
activation package request snapshots, and opaque package responses.
- `docs/markitect-interop.md` documents ownership, validation boundaries,
package request/response contracts, and fixture catalog.
Validation:
- `python3 -m pytest` -> 41 passed.
## T01 - Define compiler bridge envelopes
```task
id: PMEM-WP-0005-T01
status: todo
status: done
priority: high
state_hub_task_id: "e51c4804-4938-443b-b02f-afa7bac0b846"
```
@@ -77,7 +103,7 @@ Output: typed helpers and JSON fixtures for package requests and responses.
```task
id: PMEM-WP-0005-T02
status: todo
status: done
priority: high
state_hub_task_id: "5a1a8777-b971-4f1b-bf65-bd71918eabf6"
```
@@ -93,7 +119,7 @@ adapter design, and tests around fallback behavior.
```task
id: PMEM-WP-0005-T03
status: todo
status: done
priority: high
state_hub_task_id: "012210c6-fc05-467e-9d36-7358c0e11abd"
```
@@ -116,7 +142,7 @@ to package request.
```task
id: PMEM-WP-0005-T04
status: todo
status: done
priority: medium
state_hub_task_id: "90ebf80e-1f7e-422c-879c-f4270f1e232e"
```
@@ -139,7 +165,7 @@ examples.
```task
id: PMEM-WP-0005-T05
status: todo
status: done
priority: medium
state_hub_task_id: "95b07795-6d8c-4473-a98a-5e48a3e6cca9"
```
@@ -158,7 +184,7 @@ Output: compatibility test suite.
```task
id: PMEM-WP-0005-T06
status: todo
status: done
priority: medium
state_hub_task_id: "21e4ffb5-e8dc-4b32-9008-97fb6ffb3726"
```
@@ -182,3 +208,25 @@ Output: interop architecture note.
the core planner APIs.
- Source spans, provenance, freshness, confidence, and policy metadata survive
from graph ingress to package request.
## Closure Review - 2026-05-18
**Outcome:** All tasks completed.
### Completed
- PMEM-WP-0005-T01 - Define compiler bridge envelopes
- PMEM-WP-0005-T02 - Add Markitect validation adapter boundary
- PMEM-WP-0005-T03 - Preserve provenance and source spans through activation
- PMEM-WP-0005-T04 - Add interop fixture catalog
- PMEM-WP-0005-T05 - Add contract compatibility tests
- PMEM-WP-0005-T06 - Document the Markitect boundary
### Cancelled
None.
### Carried Forward
Graph-neighborhood retrieval, event-path activation, ranking, and activation
quality metrics remain in PMEM-WP-0006.

65
workplans/PMEM-WP-0006-retrieval-activation-quality-and-evaluation.md
View File

@@ -4,7 +4,7 @@ type: workplan
title: "Retrieval, Activation Quality, And Evaluation"
domain: markitect
repo: phase-memory
status: proposed
status: finished
owner: phase-memory
topic_slug: activation-quality
planning_priority: P2
@@ -51,11 +51,37 @@ activation-memory intent.
- Do not own benchmark dashboards that belong in `infospace-bench`.
- Do not optimize for a single application domain.
## Implementation Update - 2026-05-18
The retrieval, activation quality, and evaluation slice is complete.
Implemented outputs:
- `phase_memory.retrieval` adds deterministic graph-neighborhood retrieval,
candidate scoring, event-path selection, pluggable token estimator protocol,
neighborhood activation planning, and activation quality reports.
- Retrieval supports max hops, edge-kind filters, direction filters, phase
filters, and memory kind filters.
- Event-path activation selects bounded event windows from structured
`MemoryPath` records and treats inactive paths as opt-in.
- Ranking signals include explicit priority, graph distance, phase, lifecycle
state, confidence, source-backed status, freshness, and policy allowance.
- `WordCountTokenEstimator` provides deterministic local budget accounting.
- `activation_quality_report` emits selected expected nodes, omitted required
nodes, policy-denied required nodes, token budget utilization, stale item
count, provenance coverage, source span coverage, and explanation coverage.
- `docs/activation-quality.md` documents retrieval, event paths, scoring,
estimator boundaries, and evaluation metrics.
Validation:
- `python3 -m pytest` -> 46 passed.
## T01 - Add deterministic graph-neighborhood retrieval
```task
id: PMEM-WP-0006-T01
status: todo
status: done
priority: high
state_hub_task_id: "8ed0909f-9e8e-4d49-9312-dca267df29f5"
```
@@ -75,7 +101,7 @@ Output: retrieval planner and tests for stable graph-neighborhood selection.
```task
id: PMEM-WP-0006-T02
status: todo
status: done
priority: high
state_hub_task_id: "5d48ba91-fef0-4d4f-a560-836abed1c527"
```
@@ -90,7 +116,7 @@ active, abandoned, and merged paths.
```task
id: PMEM-WP-0006-T03
status: todo
status: done
priority: high
state_hub_task_id: "0f6340ef-f7bd-408b-b98e-6d90188c5969"
```
@@ -113,7 +139,7 @@ Output: scoring model, per-item selection reason, and omitted-item reason.
```task
id: PMEM-WP-0006-T04
status: todo
status: done
priority: medium
state_hub_task_id: "12d83382-a767-45a8-b7cc-8c3f6f3f4c37"
```
@@ -128,7 +154,7 @@ package budget pressure.
```task
id: PMEM-WP-0006-T05
status: todo
status: done
priority: medium
state_hub_task_id: "509e9417-3aa7-4899-aed5-20749372fe00"
```
@@ -148,7 +174,7 @@ Output: fixture set and expected activation plans.
```task
id: PMEM-WP-0006-T06
status: todo
status: done
priority: medium
state_hub_task_id: "477a896a-8013-42a5-b965-b1ccd2577fec"
```
@@ -170,7 +196,7 @@ Output: metrics helper and JSON report fixture.
```task
id: PMEM-WP-0006-T07
status: todo
status: done
priority: medium
state_hub_task_id: "551432e4-2551-49fa-b17b-f762853a6a50"
```
@@ -187,3 +213,26 @@ Output: activation planning guide and scorecard update.
- Every selected and omitted item has a machine-readable reason.
- Evaluation fixtures produce deterministic activation quality reports.
- Optional semantic indexes remain behind the `SemanticIndex` port.
## Closure Review - 2026-05-18
**Outcome:** All tasks completed.
### Completed
- PMEM-WP-0006-T01 - Add deterministic graph-neighborhood retrieval
- PMEM-WP-0006-T02 - Add event-path activation
- PMEM-WP-0006-T03 - Add ranking signals and explanations
- PMEM-WP-0006-T04 - Improve token and budget accounting
- PMEM-WP-0006-T05 - Add evaluation fixture scenarios
- PMEM-WP-0006-T06 - Add maturity metrics for activation quality
- PMEM-WP-0006-T07 - Document retrieval and evaluation behavior
### Cancelled
None.
### Carried Forward
Service contracts, runtime configuration, health diagnostics, and external
adapter conformance remain in PMEM-WP-0007.