Add Markitect bridge and activation quality

docs/activation-quality.md

@@ -0,0 +1,52 @@
+# Activation Quality
+
+`phase-memory` activation can now be planned from deterministic graph
+neighborhoods and event paths without requiring embeddings, vector stores, or
+LLM ranking.
+
+## Graph Neighborhood Retrieval
+
+`retrieve_graph_neighborhood` expands from seed nodes across graph edges.
+
+Supported controls:
+
+- maximum hops
+- edge kind filters
+- `in`, `out`, or `both` direction
+- phase filters
+- memory kind filters
+
+Candidates receive deterministic scores based on explicit priority, graph
+distance, phase, lifecycle state, confidence, source-backed status, freshness,
+and policy allowance.
+
+## Event Path Activation
+
+`select_event_path` activates ordered event ids from a structured
+`MemoryPath`. Active paths are selected by default. Abandoned, merged, or
+compacted paths can be included explicitly when a caller wants to inspect
+inactive branches.
+
+## Token Estimation
+
+`TokenEstimator` is a protocol. The default implementation is
+`WordCountTokenEstimator`, which keeps tests deterministic and dependency-free.
+Provider-specific tokenizers can be supplied later without changing retrieval
+contracts.
+
+## Quality Report
+
+`activation_quality_report` emits local metrics suitable for later export to
+evaluation systems:
+
+- selected expected nodes
+- omitted required nodes
+- policy-denied required nodes
+- token budget utilization
+- stale item activation count
+- provenance coverage
+- source span coverage
+- explanation coverage
+
+The fixture `tests/fixtures/activation-quality-report.json` pins a small
+expected report for regression tests.

docs/markitect-interop.md

@@ -0,0 +1,93 @@
+# Markitect Interop
+
+`phase-memory` consumes and emits Markitect-compatible memory contracts while
+keeping ownership boundaries explicit.
+
+## Ownership
+
+Markitect owns:
+
+- markdown-facing memory profile syntax
+- memory graph contract vocabulary
+- memory selection validation
+- context-package internals
+- package compilation semantics
+
+`phase-memory` owns:
+
+- phase-aware runtime planning
+- lifecycle planning
+- activation planning
+- policy/audit/review checks around memory runtime behavior
+- adapter orchestration
+- package compile request handoff
+
+## Contract Inputs
+
+The dependency-light boundary accepts already-valid dictionaries for:
+
+- `markitect.memory.profile.v1`
+- `markitect.memory.graph.v1`
+- `markitect.memory.selection.v1`
+
+`LocalMarkitectValidator` uses local ingress diagnostics only. It checks
+schema ids, required ids, known first-slice memory kinds, and graph edge
+integrity. It does not claim to be the Markitect schema owner.
+
+`OptionalMarkitectValidator` can wrap a Markitect-owned validator object with
+methods such as `validate_memory_profile`, `validate_memory_graph`, and
+`validate_memory_selection`. If no delegate is configured, it falls back to the
+local boundary.
+
+## Package Request
+
+Activation planning emits a Markitect-compatible selection and a package
+request envelope:
+
+```text
+phase_memory.markitect.package_request.v1
+```
+
+The request includes:
+
+- selection id
+- graph id
+- profile id
+- selected node ids
+- selected event ids
+- budget metadata
+- policy metadata
+- selected item provenance metadata
+- compiler name
+- compiler diagnostics
+- original selection
+
+Selected item metadata preserves source spans, provenance, confidence,
+freshness, namespace, policy labels, and reason selected. This gives Markitect
+enough input to build inspectable packages without requiring phase-memory to
+understand package internals.
+
+## Package Response
+
+Package compiler responses are wrapped in:
+
+```text
+phase_memory.markitect.package_response.v1
+```
+
+The wrapper keeps the Markitect response opaque and extracts only a
+`package_ref` when present.
+
+## Fixture Catalog
+
+Compatibility fixtures live under `tests/fixtures/`:
+
+- `memory-profile.json` - valid Markitect-compatible profile
+- `memory-graph.json` - valid Markitect-compatible graph
+- `markitect-invalid-profile.json` - invalid profile diagnostics
+- `markitect-invalid-graph.json` - invalid graph diagnostics
+- `runtime-activation-plan-snapshot.json` - activation/package request shape
+- `markitect-package-response.json` - opaque package response fixture
+
+These fixtures are small and deterministic so adjacent repositories can reuse
+them as examples without installing Markitect.