generated from coulomb/repo-seed
Operator metrics, job inspection, and event views, Recovery, Governance reports, Extension catalog and semantic extension events
This commit is contained in:
35
docs/mvp-compliance-report.md
Normal file
35
docs/mvp-compliance-report.md
Normal file
@@ -0,0 +1,35 @@
|
||||
# MVP Compliance Report
|
||||
|
||||
Date: 2026-05-06
|
||||
|
||||
Status: MVP compliance snapshot for `KONT-WP-0010`.
|
||||
|
||||
## Implemented MVP Coverage
|
||||
|
||||
| Area | Status | Evidence |
|
||||
| --- | --- | --- |
|
||||
| Asset registry and governance | implemented | Asset lifecycle, metadata, relationships, versions, audit, and policy checks. |
|
||||
| Multi-format ingestion | implemented | Ingestion jobs, local file/directory connectors, built-in extractors, Markitect markdown adapter boundary, quarantine and partial failures. |
|
||||
| Governed retrieval | implemented | Permission-aware asset, context entity, and relationship retrieval with snippets, feedback, and quality metrics. |
|
||||
| Transformations | implemented | Operation registry, durable runs, output assets, lineage, audit, retry and cancel. |
|
||||
| Workflow jobs | implemented | Templates, invocations, retries, cancel, review tasks, exceptions, and reconstruction. |
|
||||
| Service API and agent-safe operation | implemented | Versioned FastAPI adapter, actor/delegation context, bounded agent operation catalog, context packages, review and dry-run gates. |
|
||||
| Observability and recovery | implemented | Metrics, job inspection, operational events, recovery action catalog and audited recovery dispatch. |
|
||||
| Export and portability | implemented | Governed export packages with manifests, hashes, policy context, audit references, and validation. |
|
||||
| Enterprise readiness hooks | implemented | Governance reports, extension catalog/events, quality/cost signals, and smoke/compliance reports. |
|
||||
|
||||
## Explicitly Deferred
|
||||
|
||||
- External webhook delivery adapters beyond audited semantic event emission.
|
||||
- Provider-backed AI execution and cost capture beyond adapter-supplied usage
|
||||
metadata.
|
||||
- Deployed API request latency middleware; current runtime reports an empty API
|
||||
latency observation set.
|
||||
- Enterprise IAM/PDP adapters, object stores, queues, semantic search, and
|
||||
external model backends.
|
||||
|
||||
## Verification
|
||||
|
||||
The MVP compliance report is exposed at `GET /api/v1/compliance/mvp`, and the
|
||||
performance smoke summary is exposed at `GET /api/v1/performance/smoke`.
|
||||
Regression coverage lives in `tests/test_service_api.py`.
|
||||
57
docs/observability-export-enterprise-readiness.md
Normal file
57
docs/observability-export-enterprise-readiness.md
Normal file
@@ -0,0 +1,57 @@
|
||||
# Observability Export And Enterprise Readiness
|
||||
|
||||
Date: 2026-05-06
|
||||
|
||||
Status: implemented MVP note for `KONT-WP-0010`.
|
||||
|
||||
## Purpose
|
||||
|
||||
This note records the operator-facing surfaces that make the engine
|
||||
inspectable, recoverable, exportable, and measurable without direct storage
|
||||
access. The implementation is intentionally an adapter layer over existing
|
||||
runtime services, repository contracts, policy decisions, and audit events.
|
||||
|
||||
## Implemented Surfaces
|
||||
|
||||
- `GET /api/v1/operations/metrics`
|
||||
- `GET /api/v1/operations/jobs`
|
||||
- `GET /api/v1/operations/events`
|
||||
- `GET /api/v1/operations/recovery/actions`
|
||||
- `POST /api/v1/operations/recovery/{action}`
|
||||
- `POST /api/v1/exports`
|
||||
- `POST /api/v1/exports/validate`
|
||||
- `POST /api/v1/governance/report`
|
||||
- `GET /api/v1/extensions/catalog`
|
||||
- `POST /api/v1/extensions/events`
|
||||
- `POST /api/v1/quality/signals`
|
||||
- `GET /api/v1/quality/cost`
|
||||
- `GET /api/v1/performance/smoke`
|
||||
- `GET /api/v1/compliance/mvp`
|
||||
|
||||
## Boundary Decisions
|
||||
|
||||
Operational metrics are computed from durable repository state and audit
|
||||
events. API request latency is reported as an empty observation set until the
|
||||
deployed FastAPI service adds middleware timing.
|
||||
|
||||
Recovery actions are explicit and policy checked. They dispatch through the
|
||||
same runtime methods as normal service use: ingestion retry, transformation
|
||||
retry/cancel, workflow retry/cancel, retrieval index refresh, and failure
|
||||
inspection.
|
||||
|
||||
Export packages are governed envelopes, not raw database dumps. They include
|
||||
assets, metadata, representations, relationships, versions, derived lineage,
|
||||
audit references, adapter sections, manifest counts, a content hash, actor, and
|
||||
policy context.
|
||||
|
||||
Governance reports avoid embedding source content. Findings identify missing
|
||||
ownership, metadata, source references, audit gaps, and sensitive assets without
|
||||
review or retention metadata.
|
||||
|
||||
Extension readiness is expressed through semantic event types, connector and
|
||||
extractor capabilities, transformation operation metadata, backend abstraction
|
||||
names, and explicit Markitect adapter boundaries.
|
||||
|
||||
Quality and cost signals are audit-backed observations. Retrieval quality uses
|
||||
existing retrieval feedback metrics; AI cost and usage depend on adapters
|
||||
providing token, provider, error, and estimated-cost fields.
|
||||
@@ -113,6 +113,24 @@ Implemented in `KONT-WP-0009-T007`:
|
||||
`dry_run` audit outcomes.
|
||||
- Partial-failure job envelopes are covered by contract tests.
|
||||
|
||||
Implemented in `KONT-WP-0010`:
|
||||
|
||||
- `GET /api/v1/operations/metrics`
|
||||
- `GET /api/v1/operations/jobs`
|
||||
- `GET /api/v1/operations/events`
|
||||
- `GET /api/v1/operations/recovery/actions`
|
||||
- `POST /api/v1/operations/recovery/{action}`
|
||||
- `POST /api/v1/exports`
|
||||
- `POST /api/v1/exports/validate`
|
||||
- `POST /api/v1/governance/report`
|
||||
- `GET /api/v1/extensions/catalog`
|
||||
- `POST /api/v1/extensions/events`
|
||||
- `POST /api/v1/quality/signals`
|
||||
- `GET /api/v1/quality/cost`
|
||||
- `GET /api/v1/performance/smoke`
|
||||
- `GET /api/v1/compliance/mvp`
|
||||
- Operator/readiness endpoints remain policy checked and audit backed.
|
||||
|
||||
The unversioned health/readiness/version endpoints are operational probes. The
|
||||
versioned `/api/v1/*` endpoints establish the MVP API namespace. Future
|
||||
domain-resource endpoints should live under `/api/v1`.
|
||||
|
||||
@@ -78,6 +78,20 @@ src/kontextual_engine/
|
||||
- `POST /api/v1/agents/operations/{operation_id}`
|
||||
- `GET /api/v1/context-packages/schema`
|
||||
- `POST /api/v1/context-packages`
|
||||
- `GET /api/v1/operations/metrics`
|
||||
- `GET /api/v1/operations/jobs`
|
||||
- `GET /api/v1/operations/events`
|
||||
- `GET /api/v1/operations/recovery/actions`
|
||||
- `POST /api/v1/operations/recovery/{action}`
|
||||
- `POST /api/v1/exports`
|
||||
- `POST /api/v1/exports/validate`
|
||||
- `POST /api/v1/governance/report`
|
||||
- `GET /api/v1/extensions/catalog`
|
||||
- `POST /api/v1/extensions/events`
|
||||
- `POST /api/v1/quality/signals`
|
||||
- `GET /api/v1/quality/cost`
|
||||
- `GET /api/v1/performance/smoke`
|
||||
- `GET /api/v1/compliance/mvp`
|
||||
- `GET /openapi.json`
|
||||
|
||||
Unversioned endpoints are operational probes. Versioned endpoints establish
|
||||
@@ -106,6 +120,8 @@ the `/api/v1` namespace for future domain resources.
|
||||
- workflow template/run/review/exception/reconstruction translation,
|
||||
- bounded agent operation catalog and dispatch translation,
|
||||
- governed context-package assembly translation.
|
||||
- observability, recovery, export, governance, extension, quality/cost, smoke,
|
||||
and compliance report translation.
|
||||
|
||||
Readiness currently checks that the configured asset registry repository can
|
||||
list assets. It does not mutate state.
|
||||
@@ -154,6 +170,13 @@ outcomes. `dry_run_only` decisions return `dry_run_required` envelopes unless
|
||||
the request is already a dry run. Partial-failure contracts are covered through
|
||||
directory ingestion with mixed supported and unsupported inputs.
|
||||
|
||||
`KONT-WP-0010` added the MVP operator/readiness surface. Metrics, jobs, events,
|
||||
recovery actions, export packages, governance reports, extension events,
|
||||
quality/cost signals, performance smoke summaries, and compliance reports are
|
||||
available through versioned service endpoints. See
|
||||
`docs/observability-export-enterprise-readiness.md` and
|
||||
`docs/mvp-compliance-report.md`.
|
||||
|
||||
## Dependency Boundary
|
||||
|
||||
The `service` extra now includes FastAPI, Uvicorn, and HTTPX for test-client
|
||||
@@ -190,6 +213,8 @@ missing-dependency behavior are tested without FastAPI.
|
||||
references, and Markitect-compatible payload shape,
|
||||
- runtime review-required and dry-run-only agent operation envelopes,
|
||||
- runtime partial-failure ingestion job envelopes,
|
||||
- runtime operator metrics, recovery, export, governance, extension events,
|
||||
quality/cost signals, smoke reports, and MVP compliance reports,
|
||||
- `create_app()` missing-dependency behavior when the optional extra is absent,
|
||||
- health/readiness/version/OpenAPI endpoint contracts when FastAPI and HTTPX
|
||||
are installed,
|
||||
|
||||
Reference in New Issue
Block a user