generated from coulomb/repo-seed
Implement live-shaped readiness workplan
This commit is contained in:
46
docs/api-compatibility.md
Normal file
46
docs/api-compatibility.md
Normal file
@@ -0,0 +1,46 @@
|
||||
# API Compatibility
|
||||
|
||||
Updated: 2026-05-19
|
||||
|
||||
`phase-memory` now treats its embedding surface as a compatibility contract for
|
||||
local integrations.
|
||||
|
||||
## Stable Surface
|
||||
|
||||
The public surface is:
|
||||
|
||||
- exports listed in `phase_memory.__all__`;
|
||||
- `PhaseMemoryRuntime` JSON-serializable runtime envelopes;
|
||||
- `LocalServiceRunner.handle(operation, payload)`;
|
||||
- every operation declared by `service_contracts()["operations"]`;
|
||||
- `ServiceBinding` and `service_binding_from_config` as optional
|
||||
framework-neutral binding helpers;
|
||||
- `RuntimeConfig`, `resolve_runtime_adapters`, and `runtime_from_config`;
|
||||
- adapter pack manifests and `validate_adapter_pack_manifest`;
|
||||
- evaluation threshold reports from `evaluation_threshold_report`.
|
||||
|
||||
The snapshot in `tests/fixtures/public-api-snapshot.json` intentionally fails
|
||||
when exports or service operations change. Update the snapshot only when the
|
||||
change is deliberate and documented.
|
||||
|
||||
## Adding Operations
|
||||
|
||||
When adding a service operation:
|
||||
|
||||
1. Add the operation to `SERVICE_OPERATIONS`.
|
||||
2. Add a `LocalServiceRunner` dispatch path.
|
||||
3. Add binding and runner tests that exercise the operation without starting a
|
||||
network listener.
|
||||
4. Update the API snapshot.
|
||||
5. Note the change in docs or release notes.
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
Breaking changes should include:
|
||||
|
||||
- a migration note in this document or release notes;
|
||||
- a compatibility test update explaining the intentional break;
|
||||
- StateHub workplan evidence for why the break is needed.
|
||||
|
||||
Avoid changing runtime envelope keys, service operation names, adapter manifest
|
||||
schema fields, or fixture schema names without a migration path.
|
||||
@@ -1,6 +1,6 @@
|
||||
# Phase Memory Maturity Scorecard
|
||||
|
||||
Updated: 2026-05-18
|
||||
Updated: 2026-05-19
|
||||
|
||||
## Purpose
|
||||
|
||||
@@ -26,51 +26,51 @@ to 5.
|
||||
|
||||
## Current Score
|
||||
|
||||
Overall maturity: **4.0 / 5**
|
||||
Overall maturity: **4.2 / 5**
|
||||
|
||||
Two sub-scores make the result easier to reason about:
|
||||
|
||||
- Local integration maturity: **4.3 / 5**
|
||||
- Operational maturity: **3.5 / 5**
|
||||
- Local integration maturity: **4.5 / 5**
|
||||
- Operational maturity: **3.8 / 5**
|
||||
|
||||
The repo is strong as a deterministic local library and service-boundary core.
|
||||
It is not yet production-operational because the external adapters are fakes,
|
||||
service bindings are framework-neutral shapes rather than deployable endpoints,
|
||||
and migration behavior is diagnostic rather than an operator-applied migration
|
||||
system.
|
||||
It is not yet production-operational because adapter coverage is still
|
||||
live-shaped rather than credentialed live integration, and service bindings are
|
||||
framework-neutral embedding surfaces rather than a deployed service.
|
||||
|
||||
## Dimension Scorecard
|
||||
|
||||
| Dimension | Score | Target | Evidence | Needed Next |
|
||||
| --- | ---: | ---: | --- | --- |
|
||||
| Intent and boundaries | 4.4 | 5.0 | `INTENT.md`, `SCOPE.md`, `README.md`, architecture docs, adjacent-repo boundary docs | Keep docs current as live adapters and service bindings clarify real ownership. |
|
||||
| Package and API foundation | 4.3 | 4.5 | Python package, public exports, runtime facade, CLI, service runner export, service config, dependency-light tests | Add public export compatibility checks and release notes discipline. |
|
||||
| Package and API foundation | 4.5 | 4.8 | Python package, public exports, runtime facade, CLI, service runner export, service config, dependency-light tests, public API snapshot | Add release notes discipline and compatibility migration examples. |
|
||||
| Markitect profile contract ingress | 3.7 | 4.5 | Profile loading, diagnostics, runtime envelopes, profile-derived config, local alias normalization | Add richer compatibility fixtures and schema drift diagnostics. |
|
||||
| Graph and event ingress | 3.9 | 4.5 | Graph loading, endpoint diagnostics, event model, JSONL log, export, repair checks, corrupt-record diagnostics, fake graph/event adapters | Add broader malformed/large graph fixtures and operator repair utilities. |
|
||||
| Graph and event ingress | 4.0 | 4.5 | Graph loading, endpoint diagnostics, event model, JSONL log, export, repair checks, corrupt-record diagnostics, fake and live-shaped graph/event adapters | Add broader malformed/large graph fixtures and operator repair utilities. |
|
||||
| Phase domain model | 3.5 | 4.5 | Phases, lifecycle states, actions, paths, retention rules, profile-derived transition rules | Add migration semantics for profile/rule changes over durable stores. |
|
||||
| Profile execution planning | 4.2 | 4.5 | Adapter plan, capabilities, policy gates, fallback behavior, config-driven local/external resolution, adapter pack manifests | Add compatibility gates for live adapter packs. |
|
||||
| Lifecycle planning and apply | 4.0 | 4.5 | Dry-run lifecycle plans, profile rules, review-gated local apply, service `lifecycle.apply`, apply audit queries | Add operator migration semantics and richer apply rollback/repair drills. |
|
||||
| Profile execution planning | 4.3 | 4.5 | Adapter plan, capabilities, policy gates, fallback behavior, config-driven local/external resolution, adapter pack manifests, live-shaped compatibility gates | Add compatibility gates for credentialed live adapter packs. |
|
||||
| Lifecycle planning and apply | 4.1 | 4.5 | Dry-run lifecycle plans, profile rules, review-gated local apply, service `lifecycle.apply`, apply audit/export queries | Add richer apply rollback and repair drills. |
|
||||
| Activation planning | 4.0 | 4.8 | Budgeted activation, selections, package request, graph neighborhoods, paths, ranking, metrics, multi-scenario evaluation fixtures | Wire semantic-index-assisted retrieval into runtime planning. |
|
||||
| Local persistence | 3.7 | 4.5 | File-backed graph store, JSONL event log, audit sink, atomic JSON writes, metadata migration diagnostics, export, repair diagnostics | Add executable migrations, compaction/retention utilities, and stronger corruption recovery. |
|
||||
| Policy, review, and audit | 3.9 | 5.0 | Operation points, review records, audit schema, queryable audit sinks, denials, redaction, fake external policy/audit adapters | Add live policy adapter boundary and enforceable audit retention policy. |
|
||||
| Observability and operations | 3.6 | 4.8 | Health report, config diagnostics, adapter status, fake telemetry audit sink, operational recipe | Add metrics/event export and deployable health/readiness binding. |
|
||||
| Markitect interop | 3.7 | 4.5 | Local validation, package request/response envelopes, fake compiler | Add optional live Markitect compiler adapter and contract compatibility suite. |
|
||||
| Kontextual/Infospace interop | 3.3 | 4.5 | Delegation envelope, fake runtime registry, activation quality report fixture, adapter compatibility manifests | Add live/fake delegation scenarios and broader Infospace restart reports. |
|
||||
| Testing and evaluation | 4.1 | 4.5 | 70 deterministic tests over runtime, CLI, adapters, policy, activation, lifecycle, service, fakes, and evaluation scenarios | Add larger regression corpus and threshold trend reports. |
|
||||
| Service readiness | 4.2 | 4.8 | Service contracts, full local runner parity, health, config, adapter conformance, fake pack | Add optional framework binding and deployable readiness endpoints. |
|
||||
| Developer experience | 4.1 | 4.5 | README, package map, CLI examples, persistence/policy/interop/service/lifecycle/fake-pack docs, operational recipe | Add troubleshooting matrix and embedded-service examples. |
|
||||
| Local persistence | 4.0 | 4.5 | File-backed graph store, JSONL event log, audit sink, atomic JSON writes, executable metadata migrations, migration audit, export, repair diagnostics | Add compaction/retention utilities and stronger corruption recovery. |
|
||||
| Policy, review, and audit | 4.2 | 5.0 | Operation points, review records, audit schema, queryable/exportable audit sinks, retention plans, denials, redaction, fake/live-shaped policy/audit adapters | Add live policy adapter boundary and enforceable audit retention pruning. |
|
||||
| Observability and operations | 4.0 | 4.8 | Health report, readiness report, config diagnostics, adapter status, service binding, fake/live-shaped telemetry audit sinks, operational recipe | Add metrics/event export to external telemetry and deployable service packaging. |
|
||||
| Markitect interop | 4.0 | 4.5 | Local validation, package request/response envelopes, fake and live-shaped compiler fixtures | Add optional credentialed Markitect compiler adapter and schema drift suite. |
|
||||
| Kontextual/Infospace interop | 3.7 | 4.5 | Delegation envelope, fake and live-shaped runtime registry, activation quality report fixture, adapter compatibility manifests | Add credentialed Kontextual adapter drill and broader Infospace restart reports. |
|
||||
| Testing and evaluation | 4.3 | 4.7 | Deterministic tests over runtime, CLI, adapters, policy, activation, lifecycle, service, fakes, live-shaped packs, API snapshots, and evaluation threshold reports | Add larger regression corpus and threshold trend reports. |
|
||||
| Service readiness | 4.5 | 4.8 | Service contracts, full local runner parity, framework-neutral service binding, WSGI adapter, health/readiness, config, adapter conformance | Add deployable packaging and operator readiness runbooks. |
|
||||
| Developer experience | 4.3 | 4.7 | README, package map, CLI examples, persistence/policy/interop/service/lifecycle/fake-pack docs, operational recipe, API compatibility docs | Add troubleshooting matrix and release note templates. |
|
||||
|
||||
## Assessment
|
||||
|
||||
The project has crossed the local integration-readiness threshold. The runtime
|
||||
envelopes, policy/review model, profile-derived configuration, lifecycle rules,
|
||||
local persistence diagnostics, queryable audit path, fake external pack
|
||||
manifests, and conformance helpers form a solid integration boundary.
|
||||
local persistence migrations, queryable/exportable audit path, fake and
|
||||
live-shaped external pack manifests, service binding, API snapshots, and
|
||||
conformance helpers form a solid integration boundary.
|
||||
|
||||
The biggest optimization opportunity is now the next operational layer:
|
||||
turning diagnostic-only durability into operator actions, adding optional
|
||||
deployable service bindings, and testing live or live-shaped adapters behind
|
||||
the same conformance suite as the fake pack.
|
||||
moving from live-shaped local fixtures to credentialed live adapter drills,
|
||||
packaging the service binding for deployment, and growing evaluation thresholds
|
||||
into trend reports.
|
||||
|
||||
## Completed Refinement Workplan
|
||||
|
||||
@@ -86,19 +86,31 @@ the same conformance suite as the fake pack.
|
||||
- adapter pack manifests and explicit missing-capability diagnostics;
|
||||
- an operational end-to-end recipe.
|
||||
|
||||
`PMEM-WP-0012` moved the score from 4.0 to 4.2 by adding:
|
||||
|
||||
- framework-neutral `ServiceBinding` and WSGI adapter tests without starting a
|
||||
listener;
|
||||
- executable local-store migration planning/apply behavior with audit traces;
|
||||
- live-shaped Markitect/Kontextual/telemetry adapter fixtures behind the same
|
||||
manifest and conformance contract;
|
||||
- audit retention plans and export batches;
|
||||
- evaluation threshold reports over the scenario corpus;
|
||||
- public API and service operation compatibility snapshots.
|
||||
|
||||
## Recommended Next Refinement
|
||||
|
||||
Create and execute `PMEM-WP-0012`: live-adapter and service-binding readiness.
|
||||
Create and execute `PMEM-WP-0013`: credentialed adapter drills and deployment
|
||||
packaging.
|
||||
|
||||
Highest-value tasks:
|
||||
|
||||
- Add an optional framework binding around `LocalServiceRunner` with health and
|
||||
readiness endpoints.
|
||||
- Add executable local-store migrations, not only diagnostics.
|
||||
- Add live-shaped Markitect/Kontextual adapter fixtures behind the manifest and
|
||||
conformance suite.
|
||||
- Add audit retention enforcement and telemetry export drills.
|
||||
- Grow the evaluation corpus into threshold reports that can catch regressions.
|
||||
- Add optional credentialed Markitect/Kontextual adapter smoke drills that are
|
||||
skipped unless credentials are present.
|
||||
- Package the service binding as a deployable local service with operator
|
||||
readiness checks.
|
||||
- Add audit retention pruning and telemetry export enforcement.
|
||||
- Grow evaluation reporting into historical threshold trends.
|
||||
- Add release note and migration-note templates for compatibility changes.
|
||||
|
||||
## Score Movement Gates
|
||||
|
||||
@@ -111,10 +123,10 @@ Achieved overall score **4.0** when:
|
||||
|
||||
Move overall score to **4.3+** when:
|
||||
|
||||
- Live optional Markitect or Kontextual adapter can be used behind the same
|
||||
conformance suite as the fake pack.
|
||||
- Operational docs include a deployable service binding or a clear embedding
|
||||
recipe.
|
||||
- Credentialed optional Markitect or Kontextual adapter smoke drills run behind
|
||||
the same conformance suite as the fake/live-shaped packs.
|
||||
- Operational docs include deployable service packaging and an operator
|
||||
readiness runbook.
|
||||
|
||||
Move overall score to **4.7+** only when:
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Operational Readiness Recipe
|
||||
|
||||
Updated: 2026-05-18
|
||||
Updated: 2026-05-19
|
||||
|
||||
This recipe exercises the local operational surface without requiring live
|
||||
Markitect, Kontextual, or telemetry services. It is the expected smoke path for
|
||||
@@ -60,6 +60,30 @@ Expected checks:
|
||||
audit sink retention mode.
|
||||
- `health["ok"]` is true.
|
||||
|
||||
## Service Binding Drill
|
||||
|
||||
`ServiceBinding` wraps `LocalServiceRunner` in an HTTP-shaped API without
|
||||
starting a listener:
|
||||
|
||||
```python
|
||||
from phase_memory import ServiceBinding
|
||||
|
||||
binding = ServiceBinding(runner)
|
||||
|
||||
health_response = binding.route("GET", "/health")
|
||||
ready_response = binding.route("GET", "/ready")
|
||||
contracts_response = binding.route("GET", "/contracts")
|
||||
package_response = binding.route(
|
||||
"POST",
|
||||
"/operations/package.compile",
|
||||
{"selection": activation["data"]["activation_plan"]["selection"]},
|
||||
)
|
||||
```
|
||||
|
||||
The WSGI adapter returned by `binding.as_wsgi_app()` is also callable in tests
|
||||
without opening a socket. Use this for deployment wrappers so the core service
|
||||
operation contract stays framework-neutral.
|
||||
|
||||
## Review-Gated Apply
|
||||
|
||||
Lifecycle actions that require review are denied until an approval marker or
|
||||
@@ -90,6 +114,12 @@ from phase_memory import RuntimeConfig, LocalServiceRunner
|
||||
config = RuntimeConfig.from_profile(profile, local_store_path=".phase-memory-local")
|
||||
runner = LocalServiceRunner(config=config)
|
||||
repair = runner.runtime.repair_diagnostics(source_ref=config.local_store_path)
|
||||
migration_plan = runner.runtime.plan_store_migration(source_ref=config.local_store_path)
|
||||
migration_apply = runner.runtime.apply_store_migration(
|
||||
migration_plan["data"]["migration_plan"],
|
||||
actor="operator",
|
||||
source_ref=config.local_store_path,
|
||||
)
|
||||
```
|
||||
|
||||
Repair diagnostics distinguish:
|
||||
@@ -100,6 +130,22 @@ Repair diagnostics distinguish:
|
||||
- `missing_edge_source` / `missing_edge_target` for graph reference damage.
|
||||
- `orphaned_path_event` when paths reference absent event-log records.
|
||||
|
||||
Migration apply is audited as `store.migration.apply` and updates metadata
|
||||
atomically when changes are needed.
|
||||
|
||||
## Audit Export And Retention Drill
|
||||
|
||||
Runtime audit behavior is inspectable beyond point queries:
|
||||
|
||||
```python
|
||||
export = runner.runtime.export_audit_events({"operation": "package.compile"})
|
||||
retention = runner.runtime.audit_retention_plan(retention_days=30)
|
||||
```
|
||||
|
||||
The export batch includes matching audit events and sink retention metadata.
|
||||
The retention plan identifies eligible operation ids but does not prune records;
|
||||
retention apply is a follow-on operational task.
|
||||
|
||||
## Adapter Pack Compatibility
|
||||
|
||||
Fake and future live adapter packs should publish a manifest with:
|
||||
@@ -108,13 +154,16 @@ Fake and future live adapter packs should publish a manifest with:
|
||||
- ownership boundaries for every adapter;
|
||||
- required conformance helpers.
|
||||
|
||||
Validate a pack before wiring it into the runtime:
|
||||
Validate fake or live-shaped packs before wiring them into the runtime:
|
||||
|
||||
```python
|
||||
from phase_memory import fake_external_adapter_pack, validate_adapter_pack_manifest
|
||||
from phase_memory import fake_external_adapter_pack, live_shaped_adapter_pack, validate_adapter_pack_manifest
|
||||
|
||||
diagnostics = validate_adapter_pack_manifest(fake_external_adapter_pack())
|
||||
assert diagnostics == ()
|
||||
|
||||
live_diagnostics = validate_adapter_pack_manifest(live_shaped_adapter_pack())
|
||||
assert live_diagnostics == ()
|
||||
```
|
||||
|
||||
Missing capabilities are reported as `missing_adapter_capability` diagnostics
|
||||
@@ -129,8 +178,12 @@ The stable embedding surface is:
|
||||
`service_contracts()["operations"]`.
|
||||
- `RuntimeConfig` and `resolve_runtime_adapters` for local/external adapter
|
||||
resolution.
|
||||
- `ServiceBinding` and `service_binding_from_config` for optional service
|
||||
wrappers.
|
||||
- Adapter conformance helpers in `phase_memory.service`.
|
||||
- External adapter pack manifests and validation helpers.
|
||||
- Public export and service operation snapshots in
|
||||
`tests/fixtures/public-api-snapshot.json`.
|
||||
|
||||
New public operations should be added to the service contract first, then to
|
||||
the local runner, runtime tests, and docs in the same change.
|
||||
|
||||
Reference in New Issue
Block a user