generated from coulomb/repo-seed
185 lines
4.6 KiB
Markdown
185 lines
4.6 KiB
Markdown
---
|
|
id: PMEM-WP-0005
|
|
type: workplan
|
|
title: "Markitect Package Bridge And Contract Interop"
|
|
domain: markitect
|
|
repo: phase-memory
|
|
status: proposed
|
|
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.
|
|
|
|
## T01 - Define compiler bridge envelopes
|
|
|
|
```task
|
|
id: PMEM-WP-0005-T01
|
|
status: todo
|
|
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: todo
|
|
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: todo
|
|
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: todo
|
|
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: todo
|
|
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: todo
|
|
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.
|