optional FastAPI service skeleton

docs/service-api-boundary.md

@@ -1,6 +1,6 @@
 # Service API Boundary
 
-Date: 2026-05-05
+Date: 2026-05-06
 
 ## Decision
 
@@ -10,11 +10,34 @@ define separate business behavior; it should expose the same artifact,
 collection, relationship, ingestion, query, workflow, and context operations as
 HTTP resources.
 
-## First Resource Shape
+## Implemented MVP Resource Shape
+
+Implemented in `KONT-WP-0009-T001`:
+
+- `GET /health`
+- `GET /ready`
+- `GET /version`
+- `GET /api/v1/health`
+- `GET /api/v1/ready`
+- `GET /api/v1/version`
+- `GET /openapi.json`
+
+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`.
+
+The service dependency is optional. Importing `kontextual_engine` and
+`kontextual_engine.api` does not require FastAPI; calling `create_app()` does.
+Install the `service` extra to run the HTTP adapter:
+
+```bash
+python3 -m pip install -e '.[service]'
+```
+
+## Planned Resource Shape
 
 Planned endpoint groups:
 
-- `GET /health`
 - `POST /collections`, `GET /collections`, `GET /collections/{id}`
 - `POST /artifacts`, `GET /artifacts/{id}`, `GET /artifacts`
 - `POST /relationships`, `GET /relationships`
@@ -23,6 +46,21 @@ Planned endpoint groups:
 - `POST /runs`, `GET /runs/{id}`, `GET /runs/{id}/manifest`
 - `POST /context/artifact/{id}`
 
+For the governed asset registry architecture, these planned groups should be
+translated to assets, metadata, relationships, ingestion jobs, retrieval,
+transformations, workflow templates/runs, review queues, and reconstruction
+resources.
+
+## MVP API Versioning Policy
+
+- `/api/v1` is the first stable namespace for implemented service resources.
+- Backward-incompatible changes require a new namespace such as `/api/v2`.
+- Additive response fields are allowed inside a version.
+- Structured diagnostics and error codes are part of the contract and should
+  remain stable inside a version.
+- Unversioned operational probes may remain as aliases for the active API
+  generation, but domain-resource endpoints must be versioned.
+
 ## Rules
 
 - The Python API is canonical until contracts stabilize.
@@ -34,9 +72,11 @@ Planned endpoint groups:
 
 ## Deferred
 
-- Authentication and authorization.
-- Durable database backend.
-- OpenAPI model polishing.
+- Asset, metadata, relationship, audit, and policy endpoints.
+- Ingestion, retrieval, transformation, and workflow endpoints.
+- Actor context, delegation, and authorization middleware.
+- Agent-safe operation catalog.
+- Context package API.
+- Dry-run and review-gate response envelopes for high-impact operations.
 - Streaming run execution.
 - Provider-backed assisted steps.
-

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.