optional FastAPI service skeleton

docs/service-api-implementation.md

@@ -0,0 +1,86 @@
+# Service API Implementation Note
+
+Date: 2026-05-06
+
+Status: active implementation note for `KONT-WP-0009`.
+
+## Purpose
+
+This note records the first optional FastAPI service adapter. The service layer
+is intentionally thin: it exposes operational probes and API version metadata
+while leaving domain behavior in the application services.
+
+## Implemented Package Shape
+
+```text
+src/kontextual_engine/
+  api/
+    __init__.py
+    app.py
+```
+
+`kontextual_engine.api.create_app()` builds the FastAPI app when the optional
+`service` extra is installed. Importing the package does not require FastAPI.
+
+## Implemented Endpoints
+
+- `GET /health`
+- `GET /ready`
+- `GET /version`
+- `GET /api/v1/health`
+- `GET /api/v1/ready`
+- `GET /api/v1/version`
+- `GET /openapi.json`
+
+Unversioned endpoints are operational probes. Versioned endpoints establish
+the `/api/v1` namespace for future domain resources.
+
+## Runtime Contract
+
+`ServiceRuntime` owns the adapter runtime state:
+
+- repository reference,
+- API version,
+- service name,
+- startup timestamp,
+- package version discovery,
+- health payload,
+- readiness checks,
+- version payload.
+
+Readiness currently checks that the configured asset registry repository can
+list assets. It does not mutate state.
+
+## Dependency Boundary
+
+The `service` extra now includes FastAPI, Uvicorn, and HTTPX for test-client
+execution:
+
+```text
+kontextual-engine[service]
+```
+
+The current workspace does not have FastAPI installed, so HTTP adapter tests
+are skipped locally until the extra is installed. The pure runtime contract and
+missing-dependency behavior are tested without FastAPI.
+
+## Test Coverage
+
+`tests/test_service_api.py` covers:
+
+- service runtime health/readiness/version without FastAPI installed,
+- `create_app()` missing-dependency behavior when the optional extra is absent,
+- health/readiness/version/OpenAPI endpoint contracts when FastAPI and HTTPX
+  are installed,
+- runtime attachment to FastAPI application state when the service extra is
+  installed.
+
+## Not Yet Implemented
+
+- Asset, metadata, relationship, audit, and policy endpoints.
+- Ingestion, retrieval, transformation, workflow, review, and reconstruction
+  endpoints.
+- Request actor context and delegation middleware.
+- Bounded agent operation catalog.
+- Context package API.
+- Dry-run and review-gate response envelopes.