Files

tegwick 850979ccf1 Complete adapter conformance coverage

2026-05-18 20:38:00 +02:00

6.7 KiB

Raw 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-0007

workplan

Service Readiness And External Adapters

markitect

phase-memory

finished

phase-memory

service-readiness

PMEM-WP-0003

PMEM-WP-0004

PMEM-WP-0005

PMEM-WP-0006

2026-05-18

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

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

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

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

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

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

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

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.

6.7 KiB Raw Blame History