Operator metrics, job inspection, and event views, Recovery, Governance reports, Extension catalog and semantic extension events

docs/observability-export-enterprise-readiness.md

@@ -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.