generated from coulomb/repo-seed
192 lines
5.9 KiB
Markdown
192 lines
5.9 KiB
Markdown
---
|
|
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.
|