# Service API Boundary

Date: 2026-05-06

## Decision

The first service boundary will be an optional FastAPI layer over the
programmatic contracts implemented in `kontextual_engine`. The service must not
define separate business behavior; it should expose the same artifact,
collection, relationship, ingestion, query, workflow, and context operations as
HTTP resources.

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

- `POST /collections`, `GET /collections`, `GET /collections/{id}`
- `POST /artifacts`, `GET /artifacts/{id}`, `GET /artifacts`
- `POST /relationships`, `GET /relationships`
- `POST /ingest`
- `POST /query/artifacts`, `POST /query/relationships`
- `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.
- HTTP handlers must translate request/response envelopes only.
- Markdown parsing, document transforms, selectors, contracts, and local
  indexes must remain adapter calls to `markitect-tool`.
- Provider calls must remain adapter calls to `llm-connect`.
- Structured diagnostics and errors must be preserved in responses.

## Deferred

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