Add phase-memory roadmap workplans

workplans/PMEM-WP-0007-service-readiness-and-external-adapters.md

@@ -0,0 +1,195 @@
+---
+id: PMEM-WP-0007
+type: workplan
+title: "Service Readiness And External Adapters"
+domain: markitect
+repo: phase-memory
+status: proposed
+owner: phase-memory
+topic_slug: service-readiness
+planning_priority: P2
+planning_order: 70
+related_workplans:
+  - PMEM-WP-0003
+  - PMEM-WP-0004
+  - PMEM-WP-0005
+  - PMEM-WP-0006
+created: "2026-05-18"
+updated: "2026-05-18"
+state_hub_workstream_id: "35512fad-8a37-406d-9074-6b6891a5a83a"
+---
+
+# PMEM-WP-0007: Service Readiness And External Adapters
+
+## Goal
+
+Prepare phase-memory to run as an embedded runtime or service-backed adapter
+layer once the local runtime, persistence, policy, package bridge, and
+activation quality slices are stable.
+
+INTENT.md says the project should run standalone, embedded behind a local
+agent toolchain, as a service with durable stores, and as an adapter layer over
+existing systems. This workplan is the transition from local library to
+integration-ready runtime.
+
+## Current Evidence
+
+The repository currently defines ports for graph stores, event logs, context
+package compilers, semantic indexes, policy gateways, audit sinks, and runtime
+registries. It does not yet define service API contracts, adapter conformance
+tests, runtime configuration, health checks, or deployment guidance.
+
+## Non-Goals
+
+- Do not make the service path mandatory for local use.
+- Do not choose one production graph, vector, policy, or audit provider as the
+  only supported backend.
+- Do not move durable knowledge ownership out of `kontextual-engine`.
+- Do not add operational complexity before PMEM-WP-0002 through PMEM-WP-0006
+  stabilize.
+
+## T01 - Define runtime service API contracts
+
+```task
+id: PMEM-WP-0007-T01
+status: todo
+priority: high
+state_hub_task_id: "48dc8e83-ff0f-4c25-b1c9-d94c3a2ac0eb"
+```
+
+Define service-level request and response contracts for:
+
+- profile plan
+- graph import
+- lifecycle plan
+- lifecycle apply
+- activation plan
+- package compile handoff
+- audit query
+- health check
+
+Output: API contract docs and fixture request/response envelopes.
+
+## T02 - Add adapter conformance tests
+
+```task
+id: PMEM-WP-0007-T02
+status: todo
+priority: high
+state_hub_task_id: "da22d548-3123-46fc-acac-8bbcf8b54fb7"
+```
+
+Create conformance tests for all public adapter protocols:
+
+- graph store
+- event log
+- context package compiler
+- semantic index
+- policy gateway
+- audit sink
+- runtime registry
+
+Output: reusable test helpers that any external adapter must pass.
+
+## T03 - Add Kontextual delegation adapter design
+
+```task
+id: PMEM-WP-0007-T03
+status: todo
+priority: high
+state_hub_task_id: "2a0fc3d0-3dda-4c58-95de-3f70cf097ff1"
+```
+
+Define the first external delegation boundary for `kontextual-engine`:
+
+- what phase-memory asks Kontextual to persist or retrieve
+- what Kontextual delegates back to phase-memory for phase policy
+- how audit and policy decisions are exchanged
+- how circular imports are avoided
+
+Output: adapter design note, envelope fixtures, and local fake adapter tests.
+
+## T04 - Add optional service runner
+
+```task
+id: PMEM-WP-0007-T04
+status: todo
+priority: medium
+state_hub_task_id: "10934c46-db81-4a68-be4f-2ce95408d279"
+```
+
+Add an optional service runner only after the local runtime API is stable.
+Keep dependencies optional and the default test suite dependency-light.
+
+Output: minimal service module, health endpoint, deterministic tests, and
+clear installation extras if a framework is used.
+
+## T05 - Add runtime configuration model
+
+```task
+id: PMEM-WP-0007-T05
+status: todo
+priority: medium
+state_hub_task_id: "a7129077-b736-4d69-94ab-d6921cd8ed15"
+```
+
+Define configuration for:
+
+- local store path
+- adapter registry
+- policy mode
+- audit sink mode
+- package compiler mode
+- semantic index mode
+- dry-run default
+- trust-zone labels
+
+Output: config model, default local config, and validation diagnostics.
+
+## T06 - Add observability and health diagnostics
+
+```task
+id: PMEM-WP-0007-T06
+status: todo
+priority: medium
+state_hub_task_id: "24ef8feb-90f8-454d-8c8f-7b3468454f57"
+```
+
+Expose runtime diagnostics for:
+
+- adapter availability
+- store schema version
+- pending review actions
+- stale memory counts
+- activation budget pressure
+- audit sink status
+- package compiler status
+
+Output: health report helpers and tests.
+
+## T07 - Document deployment modes
+
+```task
+id: PMEM-WP-0007-T07
+status: todo
+priority: medium
+state_hub_task_id: "89c8802c-f536-441b-a514-8d3e56b3c6e5"
+```
+
+Document the supported deployment modes:
+
+- pure library
+- CLI over local files
+- embedded runtime
+- optional service
+- adapter layer over external stores
+
+Output: service-readiness guide and scorecard update.
+
+## Acceptance Criteria
+
+- `python3 -m pytest` passes.
+- Service contracts are documented before service implementation expands.
+- External adapters can be validated with reusable conformance tests.
+- Local library and CLI use remain first-class.
+- The Kontextual delegation boundary is explicit and avoids ownership drift.