kontextual-engine/workplans/KONT-WP-0009-service-api-agent-safe-operation.md

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	planning_priority	planning_order	created	updated	state_hub_workstream_id
KONT-WP-0009	workplan	Service API And Agent-Safe Operation	markitect	kontextual-engine	todo	codex	markitect	high	9	2026-05-05	2026-05-05	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.

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

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

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

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

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

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

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.

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

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.