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