generated from coulomb/repo-seed
233 lines
6.2 KiB
Markdown
233 lines
6.2 KiB
Markdown
---
|
|
id: PMEM-WP-0005
|
|
type: workplan
|
|
title: "Markitect Package Bridge And Contract Interop"
|
|
domain: markitect
|
|
repo: phase-memory
|
|
status: finished
|
|
owner: phase-memory
|
|
topic_slug: markitect-interop
|
|
planning_priority: P1
|
|
planning_order: 50
|
|
related_workplans:
|
|
- PMEM-WP-0002
|
|
- PMEM-WP-0004
|
|
created: "2026-05-18"
|
|
updated: "2026-05-18"
|
|
state_hub_workstream_id: "be683a3e-49d1-4e35-a227-c43233cc652e"
|
|
---
|
|
|
|
# PMEM-WP-0005: Markitect Package Bridge And Contract Interop
|
|
|
|
## Goal
|
|
|
|
Make the boundary with `markitect-tool` operational while preserving clean
|
|
ownership.
|
|
|
|
`phase-memory` should consume Markitect-compatible profiles, graphs, events,
|
|
and selections; plan memory operations; and hand activation selections to a
|
|
Markitect-owned context-package compiler. It should not fork Markitect syntax
|
|
or quietly depend on Markitect internals.
|
|
|
|
## Current Evidence
|
|
|
|
The repository currently has:
|
|
|
|
- constants for Markitect memory profile, graph, and selection schema versions
|
|
- profile and graph ingress helpers
|
|
- a selection output from activation planning
|
|
- a `ContextPackageCompiler` protocol
|
|
- a noop compiler adapter for tests
|
|
|
|
The missing work is a real bridge contract, compatibility fixtures, validation
|
|
delegation, and stable package request/response envelopes.
|
|
|
|
## Non-Goals
|
|
|
|
- Do not reimplement Markitect schema validation.
|
|
- Do not own context package internals.
|
|
- 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: done
|
|
priority: high
|
|
state_hub_task_id: "e51c4804-4938-443b-b02f-afa7bac0b846"
|
|
```
|
|
|
|
Define the request and response shape for context package compilation:
|
|
|
|
- selection id
|
|
- graph id
|
|
- profile id
|
|
- selected nodes
|
|
- selected events
|
|
- budget metadata
|
|
- policy metadata
|
|
- provenance metadata
|
|
- compiler diagnostics
|
|
- package reference
|
|
|
|
Output: typed helpers and JSON fixtures for package requests and responses.
|
|
|
|
## T02 - Add Markitect validation adapter boundary
|
|
|
|
```task
|
|
id: PMEM-WP-0005-T02
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "5a1a8777-b971-4f1b-bf65-bd71918eabf6"
|
|
```
|
|
|
|
Add an adapter boundary that can delegate validation to Markitect when
|
|
available, while still accepting already-valid dictionaries in dependency-light
|
|
mode.
|
|
|
|
Output: protocol, noop/local validation adapter, optional Markitect-backed
|
|
adapter design, and tests around fallback behavior.
|
|
|
|
## T03 - Preserve provenance and source spans through activation
|
|
|
|
```task
|
|
id: PMEM-WP-0005-T03
|
|
status: done
|
|
priority: high
|
|
state_hub_task_id: "012210c6-fc05-467e-9d36-7358c0e11abd"
|
|
```
|
|
|
|
Ensure activation selections carry enough information for Markitect to compile
|
|
inspectable packages:
|
|
|
|
- source spans
|
|
- provenance
|
|
- confidence
|
|
- freshness
|
|
- namespace
|
|
- policy labels
|
|
- reason selected
|
|
|
|
Output: expanded selection metadata and tests proving metadata survives ingress
|
|
to package request.
|
|
|
|
## T04 - Add interop fixture catalog
|
|
|
|
```task
|
|
id: PMEM-WP-0005-T04
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "90ebf80e-1f7e-422c-879c-f4270f1e232e"
|
|
```
|
|
|
|
Create a fixture catalog that mirrors the Markitect contract shapes this repo
|
|
expects, including:
|
|
|
|
- valid profile
|
|
- invalid profile
|
|
- valid graph
|
|
- invalid graph
|
|
- activation selection
|
|
- package request
|
|
- package response
|
|
|
|
Output: fixtures and docs that downstream repos can use as compatibility
|
|
examples.
|
|
|
|
## T05 - Add contract compatibility tests
|
|
|
|
```task
|
|
id: PMEM-WP-0005-T05
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "95b07795-6d8c-4473-a98a-5e48a3e6cca9"
|
|
```
|
|
|
|
Add tests that prove phase-memory can:
|
|
|
|
- accept Markitect profile and graph fixtures
|
|
- report diagnostics without claiming schema ownership
|
|
- emit Markitect-compatible selections
|
|
- build package requests through the compiler port
|
|
- consume package responses without understanding internals
|
|
|
|
Output: compatibility test suite.
|
|
|
|
## T06 - Document the Markitect boundary
|
|
|
|
```task
|
|
id: PMEM-WP-0005-T06
|
|
status: done
|
|
priority: medium
|
|
state_hub_task_id: "21e4ffb5-e8dc-4b32-9008-97fb6ffb3726"
|
|
```
|
|
|
|
Update architecture docs with a concrete boundary contract:
|
|
|
|
- what Markitect owns
|
|
- what phase-memory owns
|
|
- which data moves across the boundary
|
|
- which diagnostics stay local
|
|
- how optional Markitect integration is configured
|
|
|
|
Output: interop architecture note.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- `python3 -m pytest` passes.
|
|
- Activation package bridge envelopes are stable and documented.
|
|
- The default test suite does not require Markitect to be installed.
|
|
- Optional Markitect validation or compilation can be added without changing
|
|
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.
|