---
id: KONT-WP-0009
type: workplan
title: "Service API And Agent-Safe Operation"
domain: markitect
repo: kontextual-engine
status: todo
owner: codex
topic_slug: markitect
planning_priority: high
planning_order: 9
created: "2026-05-05"
updated: "2026-05-05"
state_hub_workstream_id: "6e672b1a-2e57-489e-8516-cb75611d4354"
---

# KONT-WP-0009: Service API And Agent-Safe Operation

## Purpose

Expose the engine through versioned service APIs and explicit agent-safe
operations. This workplan turns the programmatic contracts into a headless
service surface for assets, metadata, relationships, ingestion, retrieval,
transformations, workflows, permissions, audit, context packages, and bounded
agent actions.

## Requirement Coverage

Primary: FR-160 to FR-169 and FR-180 to FR-188.

Supporting: FR-060 to FR-066, FR-080 to FR-085, FR-100 to FR-106,
FR-120 to FR-126, FR-200 to FR-202, FR-240 to FR-245.

## Architecture Constraint

Implement the service API as an adapter over application services, following
`docs/architecture-blueprint.md`. HTTP routes must not own domain behavior.
Agent operations must use the bounded operation catalog, policy checks, audit
events, dry-run behavior, and review gates described in the blueprint.

## markitect-tool Boundary Remark

Service and agent APIs may expose engine operations that internally use
Markitect for markdown-backed context packages, selectors, validation, and
deterministic markdown operations. They must not expose the `mkt` CLI as the
engine control plane or let agents bypass engine policy, audit, lifecycle, and
review gates through Markitect APIs.

## S9.1 - Implement versioned FastAPI service skeleton and health contracts

```task
id: KONT-WP-0009-T001
status: todo
priority: high
state_hub_task_id: "bdb2380e-4ea1-4b8c-a6c9-fc8da2122813"
```

Add the first optional FastAPI service layer while keeping core behavior in
programmatic contracts.

Acceptance:

- Service startup, health, readiness, version, and OpenAPI output are tested.
- Service code wraps core contracts rather than becoming the architecture.
- API versioning policy is documented for MVP.

## S9.2 - Expose asset metadata relationship audit and policy APIs

```task
id: KONT-WP-0009-T002
status: todo
priority: high
state_hub_task_id: "a37e5ba3-e128-4100-b22c-c85cca3f8db3"
```

Expose service APIs for asset lifecycle, metadata, classifications,
relationships, policies, permissions, lifecycle state, and audit events.

Acceptance:

- Core asset operations are available without a CLI or UI.
- Permission and policy checks run before protected operations.
- Audit history can be queried by authorized callers.

## S9.3 - Expose ingestion retrieval transformation and workflow APIs

```task
id: KONT-WP-0009-T003
status: todo
priority: high
state_hub_task_id: "7271b26d-0dbb-4eca-9140-a7729ad296e4"
```

Expose APIs for ingestion jobs, query/retrieval, transformations, derived
artifacts, workflow templates, workflow runs, and job recovery actions.

Acceptance:

- Jobs return IDs, state, outputs, failures, retry options, and correlation
  IDs.
- Retrieval results are permission-aware and source-grounded.
- Transformations and workflows expose lineage and audit references.

## S9.4 - Implement actor context delegation and authorization middleware

```task
id: KONT-WP-0009-T004
status: todo
priority: high
state_hub_task_id: "7becdec7-ddbb-497f-b762-77043e16046e"
```

Implement request-level actor context for human users, applications,
automation, service accounts, delegated users, and AI agents.

Acceptance:

- Every material service operation has actor context.
- Delegation and agent identity are represented explicitly.
- Authorization failures do not leak protected content in errors or result
  shapes.

## S9.5 - Implement bounded agent operation catalog

```task
id: KONT-WP-0009-T005
status: todo
priority: high
state_hub_task_id: "fc9e1def-229c-4224-8fd3-6fd4f9785c27"
```

Define and expose explicit agent operations for inspect, search, retrieve,
assemble context, enrich metadata, classify, transform, invoke workflow, submit
review, and report result.

Acceptance:

- Agents can only act through documented operations.
- Each operation declares inputs, outputs, permission requirements, audit
  behavior, and failure modes.
- Agent operations are auditable separately from human and deterministic
  automation actions.

## S9.6 - Implement context package API with policy constraints

```task
id: KONT-WP-0009-T006
status: todo
priority: medium
state_hub_task_id: "9ff1d345-d0a1-46eb-ae9a-f6beba2fa5e9"
```

Provide bounded context packages containing selected assets, snippets,
metadata, relationships, provenance, task instructions, and policy constraints.

Acceptance:

- Context packages do not require unrestricted repository access.
- Package contents are source-grounded and permission filtered.
- External memory references remain opaque and respect
  `docs/phase-memory-boundary.md`.
- Markdown-backed packages can interoperate with Markitect context-package
  payloads while remaining wrapped in engine permission and audit contracts.

## S9.7 - Implement dry-run review-gate and contract-test coverage

```task
id: KONT-WP-0009-T007
status: todo
priority: medium
state_hub_task_id: "bbbdec75-d3c0-4367-b073-ef9c5dffa2b7"
```

Add dry-run and review-gate behavior for destructive, sensitive, externally
published, or high-impact service and agent operations.

Acceptance:

- Risky actions can be denied, dry-run, or routed to review.
- Contract tests cover API errors, authorization failures, review-required
  responses, and partial failures.
- OpenAPI output remains stable for implemented endpoints.

## Definition Of Done

- The service API exposes the MVP operation surface without requiring UI.
- Agent-safe operations are explicit, bounded, permissioned, auditable, and
  reviewable.
- API routes remain adapters over the core contracts described in
  `docs/architecture-blueprint.md`.
- `python3 -m pytest` passes.