coulomb/phase-memory
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Implement credentialed drill packaging workplan

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-19 01:27:59 +02:00
parent 022cd8d37e
commit 6e0372d21a
23 changed files with 924 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
docs/api-compatibility.md
View File

@@ -23,6 +23,11 @@ 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.
The snapshot also points to `docs/release-note-template.md`. When a public API
snapshot changes, fill in that template or a release note derived from it so
operators can see changed exports, changed service operations, migration needs,
and required action.
## Adding Operations
When adding a service operation:

71
docs/maturity-scorecard.md
View File

@@ -26,24 +26,24 @@ to 5.
## Current Score
Overall maturity: **4.2 / 5**
Overall maturity: **4.3 / 5**
Two sub-scores make the result easier to reason about:
- Local integration maturity: **4.5 / 5**
- Operational maturity: **3.8 / 5**
- Local integration maturity: **4.6 / 5**
- Operational maturity: **4.0 / 5**
The repo is strong as a deterministic local library and service-boundary core.
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.
credential-gated rather than continuously exercised against live services, and
service packaging is stdlib/local rather than deployed to a managed environment.
## 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.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. |
| Package and API foundation | 4.6 | 4.8 | Python package, public exports, runtime facade, CLI, service runner export, service config, dependency-light tests, public API snapshot, release-note template | Add compatibility migration examples from a real release. |
| 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 | 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. |
@@ -51,26 +51,26 @@ framework-neutral embedding surfaces rather than a deployed service.
| 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 | 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. |
| Policy, review, and audit | 4.4 | 5.0 | Operation points, review records, audit schema, queryable/exportable audit sinks, retention plans and apply, denials, redaction, fake/live-shaped policy/audit adapters | Add live policy adapter boundary and credentialed telemetry pruning drill. |
| Observability and operations | 4.3 | 4.8 | Health report, readiness report, config diagnostics, adapter status, service binding, stdlib service entrypoint, operator runbook, fake/live-shaped telemetry audit sinks | Add metrics/event export to external telemetry and managed deployment packaging. |
| Markitect interop | 4.1 | 4.5 | Local validation, package request/response envelopes, fake/live-shaped compiler fixtures, credential-gated drill contract | Add credentialed Markitect compiler execution and schema drift suite. |
| Kontextual/Infospace interop | 3.9 | 4.5 | Delegation envelope, fake/live-shaped runtime registry, credential-gated drill contract, activation quality report fixture, adapter compatibility manifests | Add credentialed Kontextual execution and broader Infospace restart reports. |
| Testing and evaluation | 4.5 | 4.7 | Deterministic tests over runtime, CLI, adapters, policy, activation, lifecycle, service, fakes, live-shaped packs, credential skip gates, API snapshots, evaluation threshold and trend reports | Add larger regression corpus and persisted trend history. |
| Service readiness | 4.6 | 4.8 | Service contracts, full local runner parity, framework-neutral service binding, WSGI adapter, stdlib service entrypoint, health/readiness, config, adapter conformance | Add managed deployment packaging. |
| Developer experience | 4.5 | 4.7 | README, package map, CLI examples, persistence/policy/interop/service/lifecycle/fake-pack docs, operational recipe, operator runbook, API compatibility docs, release-note template | Add troubleshooting matrix from real operator feedback. |
## Assessment
The project has crossed the local integration-readiness threshold. The runtime
envelopes, policy/review model, profile-derived configuration, lifecycle rules,
local persistence migrations, queryable/exportable audit path, fake and
live-shaped external pack manifests, service binding, API snapshots, and
local persistence migrations, queryable/exportable/prunable audit path, fake
and live-shaped external pack manifests, credential-gated drills, service
binding and stdlib entrypoint, API snapshots, release discipline, and
conformance helpers form a solid integration boundary.
The biggest optimization opportunity is now the next operational layer:
moving from live-shaped local fixtures to credentialed live adapter drills,
packaging the service binding for deployment, and growing evaluation thresholds
into trend reports.
running the credential-gated drills against real services, adding managed
deployment packaging, and growing evaluation trends into a historical corpus.
## Completed Refinement Workplan
@@ -97,20 +97,30 @@ into trend reports.
- evaluation threshold reports over the scenario corpus;
- public API and service operation compatibility snapshots.
`PMEM-WP-0013` moved the score from 4.2 to 4.3 by adding:
- credential-gated adapter drill helpers and skipped smoke tests that list
required environment variables;
- stdlib `phase-memory-service` packaging with check mode and WSGI dispatch;
- operator readiness runbook for service startup, migrations, audit retention,
credentialed drills, and rollback;
- audit retention apply behavior with audit trace coverage;
- evaluation trend artifacts with threshold and regression deltas;
- release-note template gating for public API snapshot changes.
## Recommended Next Refinement
Create and execute `PMEM-WP-0013`: credentialed adapter drills and deployment
packaging.
Create and execute `PMEM-WP-0014`: live credential execution and managed
deployment hardening.
Highest-value tasks:
- 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.
- Run the credential-gated drills against real Markitect/Kontextual endpoints
in an operator environment.
- Add managed deployment packaging and readiness probes.
- Persist evaluation trend reports across runs.
- Add credentialed telemetry export and retention pruning drills.
- Expand troubleshooting from actual operator feedback.
## Score Movement Gates
@@ -121,10 +131,11 @@ Achieved overall score **4.0** when:
- Local persistence has migration diagnostics.
- Evaluation fixtures cover at least three profile/graph families.
Move overall score to **4.3+** when:
Achieved overall score **4.3+** when:
- Credentialed optional Markitect or Kontextual adapter smoke drills run behind
the same conformance suite as the fake/live-shaped packs.
- Credentialed optional Markitect or Kontextual adapter smoke drills are
available behind the same conformance suite as the fake/live-shaped packs and
skip cleanly without credentials.
- Operational docs include deployable service packaging and an operator
readiness runbook.

18
docs/operational-readiness.md
View File

@@ -84,6 +84,16 @@ 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.
For the stdlib deployable entrypoint, use:
```bash
phase-memory-service --check --store .phase-memory-local
phase-memory-service --host 127.0.0.1 --port 8080 --store .phase-memory-local
```
See `docs/operator-readiness-runbook.md` for operator checks and rollback
guidance.
## Review-Gated Apply
Lifecycle actions that require review are denied until an approval marker or
@@ -143,8 +153,12 @@ 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.
The retention plan identifies eligible operation ids. Retention apply prunes
eligible records and records `audit.retention.apply` after pruning:
```python
retention_apply = runner.runtime.apply_audit_retention(retention["plan"])
```
## Adapter Pack Compatibility

141
docs/operator-readiness-runbook.md Normal file
View File

@@ -0,0 +1,141 @@
# Operator Readiness Runbook
Updated: 2026-05-19
This runbook covers the operational path for `phase-memory` without requiring
credentials in the default test suite.
## Modes
| Mode | Purpose | Credentials | Network |
| --- | --- | --- | --- |
| Local fixture | Default deterministic runtime and tests. | No | No |
| Live-shaped | Adapter manifests and behavior that model live services locally. | No | No |
| Credentialed live drill | Operator-provided smoke drill for real endpoints. | Yes, via env only | Optional |
Credentialed drills require:
- `PHASE_MEMORY_MARKITECT_URL`
- `PHASE_MEMORY_MARKITECT_TOKEN`
- `PHASE_MEMORY_KONTEXTUAL_URL`
- `PHASE_MEMORY_KONTEXTUAL_TOKEN`
Do not store those values in Git, workplans, progress logs, or release notes.
## Service Startup
The deployable stdlib entrypoint is `phase-memory-service`.
Readiness check without listening:
```bash
phase-memory-service --check --store .phase-memory-local
```
Start the stdlib WSGI service:
```bash
phase-memory-service --host 127.0.0.1 --port 8080 --store .phase-memory-local
```
Routes:
- `GET /health`
- `GET /ready`
- `GET /contracts`
- `POST /operations/{operation}`
- `POST /operations` with `{"operation": "...", "payload": {...}}`
## Readiness Checks
Before accepting traffic:
1. Run `phase-memory-service --check`.
2. Verify `/ready` reports `ok: true`.
3. Verify `unsupported_operations` is empty.
4. Verify adapter diagnostics have no `error` severity.
5. Verify the public API snapshot test passes after any operation/export change.
## Migration Apply
Plan and apply local-store metadata migrations through the runtime:
```python
from phase_memory import RuntimeConfig, runtime_from_config
config = RuntimeConfig(local_store_path=".phase-memory-local")
runtime = runtime_from_config(config)
plan = runtime.plan_store_migration(source_ref=config.local_store_path)
result = runtime.apply_store_migration(
plan["data"]["migration_plan"],
actor="operator",
source_ref=config.local_store_path,
)
```
Expected:
- no `error` diagnostics in the plan;
- `result["valid"] is True`;
- metadata is updated atomically;
- `audit.query` can find the `store.migration.apply` event.
Rollback:
- stop the service;
- restore the previous local store directory from backup;
- rerun `phase-memory-service --check`;
- rerun `runtime.repair_diagnostics()`.
## Audit Export And Retention
Plan retention:
```python
plan = runtime.audit_retention_plan(retention_days=30)
```
Apply retention:
```python
result = runtime.apply_audit_retention(plan["plan"])
```
Expected:
- eligible operation ids are pruned;
- `audit.retention.apply` is recorded after pruning;
- no retention apply happens when the sink reports unsupported behavior.
Export a trace batch:
```python
export = runtime.export_audit_events({"operation": "package.compile"})
```
Use export batches for operator review, not as a credential or secret store.
## Credentialed Drill
Run the credentialed smoke test only from an operator environment:
```bash
PHASE_MEMORY_MARKITECT_URL=... \
PHASE_MEMORY_MARKITECT_TOKEN=... \
PHASE_MEMORY_KONTEXTUAL_URL=... \
PHASE_MEMORY_KONTEXTUAL_TOKEN=... \
python3 -m pytest tests/test_credentialed_drills.py
```
The report redacts tokens and uses a credential fingerprint rather than
persisting secrets.
## Compatibility Release Discipline
When public exports or service operations change:
1. Update `tests/fixtures/public-api-snapshot.json`.
2. Fill in `docs/release-note-template.md`.
3. Call out changed exports, changed service operations, migration needs, and
operator action.
4. Link the workplan or decision that authorized the change.

41
docs/release-note-template.md Normal file
View File

@@ -0,0 +1,41 @@
# Release Note Template
## Summary
Briefly describe the release and the workplan or decision that authorized it.
## Changed Exports
- Added:
- Changed:
- Removed:
Reference the updated `tests/fixtures/public-api-snapshot.json` entry when the
public export list changes.
## Changed Service Operations
- Added:
- Changed:
- Removed:
Reference `service_contracts()["operations"]` and explain compatibility impact.
## Migration Needs
- Local store migrations:
- Runtime envelope migrations:
- Adapter manifest migrations:
Include whether migration apply is automatic, operator-triggered, or not
required.
## Operator Action
- Required environment variables:
- Service packaging changes:
- Readiness checks:
- Rollback note:
No credentials, tokens, or live endpoints should be included in the release
note.