kontextual-engine/docs/observability-export-enterprise-readiness.md

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.