---
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.