Service-API completion: ingestion, retrieval, transformations, workflows, actor/delegation context, bounded agent operations, context packages, and dry-run/review-gate contracts

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

@@ -4,7 +4,7 @@ type: workplan
 title: "Service API And Agent-Safe Operation"
 domain: markitect
 repo: kontextual-engine
-status: active
+status: completed
 owner: codex
 topic_slug: markitect
 planning_priority: high
@@ -48,14 +48,13 @@ review gates through Markitect APIs.
 
 ## Implementation Status
 
-The first optional FastAPI service skeleton is implemented for health,
-readiness, version, OpenAPI contracts, and the initial asset/metadata/
-relationship/audit/policy resource surface. See
+The optional FastAPI service skeleton is implemented for health, readiness,
+version, OpenAPI contracts, asset/metadata/relationship/audit/policy resources,
+ingestion jobs, governed retrieval, transformations, and workflow resources.
+See
 `docs/service-api-implementation.md`.
 
-Ingestion, retrieval, transformation, workflow, actor context, agent
-operations, context packages, and dry-run/review-gate response contracts remain
-open in this workplan.
+All MVP tasks in this workplan are implemented.
 
 ## S9.1 - Implement versioned FastAPI service skeleton and health contracts
 
@@ -116,7 +115,7 @@ Implemented:
 
 ```task
 id: KONT-WP-0009-T003
-status: todo
+status: done
 priority: high
 state_hub_task_id: "7271b26d-0dbb-4eca-9140-a7729ad296e4"
 ```
@@ -131,11 +130,25 @@ Acceptance:
 - Retrieval results are permission-aware and source-grounded.
 - Transformations and workflows expose lineage and audit references.
 
+Implemented:
+
+- `ServiceRuntime` exposes ingestion capabilities and ingestion job start/list/get
+  over `AssetIngestionService`.
+- Governed retrieval endpoints wrap `AssetRetrievalService` for asset, context
+  entity, relationship, feedback, index refresh, and quality metric contracts.
+- Transformation operations and runs are exposed with retry/cancel hints,
+  lineage, output assets, audit references, and policy decisions.
+- Workflow templates, queued/invoked runs, run recovery, review decisions,
+  review queues, exception queues, and reconstruction are exposed over
+  `WorkflowService`.
+- Runtime tests cover completed and failed ingestion jobs, source-grounded
+  retrieval, transformation lineage/audit, and workflow reconstruction.
+
 ## S9.4 - Implement actor context delegation and authorization middleware
 
 ```task
 id: KONT-WP-0009-T004
-status: todo
+status: done
 priority: high
 state_hub_task_id: "7becdec7-ddbb-497f-b762-77043e16046e"
 ```
@@ -150,11 +163,23 @@ Acceptance:
 - Authorization failures do not leak protected content in errors or result
   shapes.
 
+Implemented:
+
+- `ServiceRuntime.operation_context()` now supports actor external refs,
+  groups, delegated actors, request scope, policy scope, and AI-agent metadata.
+- FastAPI request context parsing accepts actor, delegated actor, agent, group,
+  request-scope, and policy-scope headers.
+- `GET /api/v1/context` exposes the resolved operation context for integration
+  checks and client diagnostics.
+- FastAPI exception handlers preserve structured errors from dependencies.
+- HTTP authorization error payloads redact protected resource metadata from
+  policy-decision context.
+
 ## S9.5 - Implement bounded agent operation catalog
 
 ```task
 id: KONT-WP-0009-T005
-status: todo
+status: done
 priority: high
 state_hub_task_id: "fc9e1def-229c-4224-8fd3-6fd4f9785c27"
 ```
@@ -171,11 +196,24 @@ Acceptance:
 - Agent operations are auditable separately from human and deterministic
   automation actions.
 
+Implemented:
+
+- Added a bounded agent operation catalog for inspect, retrieve, search,
+  assemble-context preview, metadata enrichment, classification request,
+  transformation, workflow invocation, review submission, and result reporting.
+- Added `GET /api/v1/agents/operations`, `GET /api/v1/agents/operations/{id}`,
+  and `POST /api/v1/agents/operations/{id}`.
+- Agent operation execution authorizes `agent.operation.*`, emits separate
+  agent-operation audit events, supports generic dry-run envelopes, and
+  dispatches through existing runtime methods.
+- Unsupported operation IDs fail with structured validation errors rather than
+  opening arbitrary command or internal-service access.
+
 ## S9.6 - Implement context package API with policy constraints
 
 ```task
 id: KONT-WP-0009-T006
-status: todo
+status: done
 priority: medium
 state_hub_task_id: "9ff1d345-d0a1-46eb-ae9a-f6beba2fa5e9"
 ```
@@ -192,11 +230,24 @@ Acceptance:
 - Markdown-backed packages can interoperate with Markitect context-package
   payloads while remaining wrapped in engine permission and audit contracts.
 
+Implemented:
+
+- Added `GET /api/v1/context-packages/schema` and
+  `POST /api/v1/context-packages`.
+- Context packages are assembled from permission-filtered retrieval results and
+  include source refs, snippets, metadata, relationships, representation
+  provenance, policy constraints, audit references, and policy decisions.
+- External memory refs are represented as opaque pointers and do not embed
+  memory graph content.
+- The `markitect` format emits a Markitect-compatible envelope while keeping
+  markdown rendering, selector semantics, and validation delegated to
+  `markitect-tool`.
+
 ## S9.7 - Implement dry-run review-gate and contract-test coverage
 
 ```task
 id: KONT-WP-0009-T007
-status: todo
+status: done
 priority: medium
 state_hub_task_id: "bbbdec75-d3c0-4367-b073-ef9c5dffa2b7"
 ```
@@ -211,6 +262,18 @@ Acceptance:
   responses, and partial failures.
 - OpenAPI output remains stable for implemented endpoints.
 
+Implemented:
+
+- Agent operation policy decisions with `require_review` now return structured
+  `review_required` envelopes and audit `review_required` outcomes.
+- Agent operation policy decisions with `dry_run_only` now return
+  `dry_run_required` envelopes unless the request is already a dry run.
+- Generic agent dry-run requests audit with `dry_run` outcomes and avoid domain
+  mutation.
+- Contract tests cover redacted authorization failures, review-required
+  responses, dry-run-required responses, partial ingestion failures, and OpenAPI
+  stability for implemented endpoint groups.
+
 ## Definition Of Done
 
 - The service API exposes the MVP operation surface without requiring UI.