generated from coulomb/repo-seed
249 lines
6.7 KiB
Markdown
249 lines
6.7 KiB
Markdown
---
|
|
id: PMEM-WP-0007
|
|
type: workplan
|
|
title: "Service Readiness And External Adapters"
|
|
domain: markitect
|
|
repo: phase-memory
|
|
status: finished
|
|
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.
|
|
|
|
## Implementation Update - 2026-05-18
|
|
|
|
The service-readiness and external-adapter slice is complete.
|
|
|
|
Implemented outputs:
|
|
|
|
- `phase_memory.service` defines service contract catalog, runtime config,
|
|
health reports, local service runner, adapter conformance helpers, and
|
|
Kontextual delegation envelopes.
|
|
- Service contracts cover profile planning, graph import, lifecycle planning,
|
|
lifecycle apply, activation planning, package compile handoff, audit query,
|
|
and health check.
|
|
- `RuntimeConfig` models local store path, adapter registry, policy mode,
|
|
audit sink mode, package compiler mode, semantic index mode, dry-run default,
|
|
and trust-zone labels.
|
|
- Health reports expose adapter availability, config diagnostics, stale memory
|
|
counts, pending review counts, and store counts.
|
|
- Adapter conformance helpers cover graph stores, event logs, context package
|
|
compilers, semantic indexes, policy gateways, audit sinks, and runtime
|
|
registries.
|
|
- `kontextual_delegation_envelope` documents the JSON boundary that avoids
|
|
circular imports while preserving ownership between phase-memory and
|
|
`kontextual-engine`.
|
|
- `docs/service-readiness.md` documents contracts, config, health,
|
|
conformance, delegation, and deployment modes.
|
|
|
|
Validation:
|
|
|
|
- `python3 -m pytest` -> 51 passed.
|
|
|
|
## T01 - Define runtime service API contracts
|
|
|
|
```task
|
|
id: PMEM-WP-0007-T01
|
|
status: done
|
|
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: done
|
|
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: done
|
|
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: done
|
|
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: done
|
|
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: done
|
|
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: done
|
|
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.
|
|
|
|
## Closure Review - 2026-05-18
|
|
|
|
**Outcome:** All tasks completed.
|
|
|
|
### Completed
|
|
|
|
- PMEM-WP-0007-T01 - Define runtime service API contracts
|
|
- PMEM-WP-0007-T02 - Add adapter conformance tests
|
|
- PMEM-WP-0007-T03 - Add Kontextual delegation adapter design
|
|
- PMEM-WP-0007-T04 - Add optional service runner
|
|
- PMEM-WP-0007-T05 - Add runtime configuration model
|
|
- PMEM-WP-0007-T06 - Add observability and health diagnostics
|
|
- PMEM-WP-0007-T07 - Document deployment modes
|
|
|
|
### Cancelled
|
|
|
|
None.
|
|
|
|
### Carried Forward
|
|
|
|
Future work should focus on live external adapters, broader evaluation corpora,
|
|
and optional framework-specific service bindings.
|