Files

tegwick 1efb7d4c13 Add Markitect bridge and activation quality

2026-05-18 20:04:40 +02:00

6.2 KiB

Raw Permalink Blame History

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, related_workplans, created, updated, state_hub_workstream_id

type

title

domain

repo

status

owner

topic_slug

planning_priority

planning_order

related_workplans

created

updated

state_hub_workstream_id

PMEM-WP-0005

workplan

Markitect Package Bridge And Contract Interop

markitect

phase-memory

finished

phase-memory

markitect-interop

PMEM-WP-0002

PMEM-WP-0004

2026-05-18

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

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

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

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

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

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

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.

6.2 KiB Raw Permalink Blame History