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

docs/service-api-implementation.md

@@ -8,8 +8,8 @@ Status: active implementation note for `KONT-WP-0009`.
 
 This note records the first optional FastAPI service adapter. The service layer
 is intentionally thin: it exposes operational probes, API version metadata, and
-the first governed asset-resource surface while leaving domain behavior in the
-application services.
+the governed asset-resource, job, retrieval, transformation, and workflow
+surface while leaving domain behavior in the application services.
 
 ## Implemented Package Shape
 
@@ -31,6 +31,7 @@ src/kontextual_engine/
 - `GET /api/v1/health`
 - `GET /api/v1/ready`
 - `GET /api/v1/version`
+- `GET /api/v1/context`
 - `POST /api/v1/assets`
 - `GET /api/v1/assets`
 - `GET /api/v1/assets/{asset_id}`
@@ -41,6 +42,42 @@ src/kontextual_engine/
 - `GET /api/v1/relationships`
 - `GET /api/v1/audit/events`
 - `POST /api/v1/policy/evaluate`
+- `GET /api/v1/ingestion/capabilities`
+- `POST /api/v1/ingestion/jobs`
+- `GET /api/v1/ingestion/jobs`
+- `GET /api/v1/ingestion/jobs/{job_id}`
+- `POST /api/v1/retrieval/index/refresh`
+- `POST /api/v1/retrieval/assets`
+- `POST /api/v1/retrieval/context-entities`
+- `POST /api/v1/retrieval/relationships`
+- `POST /api/v1/retrieval/feedback`
+- `GET /api/v1/retrieval/feedback`
+- `GET /api/v1/retrieval/quality`
+- `GET /api/v1/transformations/operations`
+- `POST /api/v1/transformations/runs`
+- `GET /api/v1/transformations/runs`
+- `GET /api/v1/transformations/runs/{run_id}`
+- `POST /api/v1/transformations/runs/{run_id}/retry`
+- `POST /api/v1/transformations/runs/{run_id}/cancel`
+- `POST /api/v1/workflows/templates`
+- `GET /api/v1/workflows/templates`
+- `GET /api/v1/workflows/templates/{template_id}`
+- `POST /api/v1/workflows/runs`
+- `POST /api/v1/workflows/runs/queue`
+- `GET /api/v1/workflows/runs`
+- `GET /api/v1/workflows/runs/{run_id}`
+- `POST /api/v1/workflows/runs/{run_id}/resume`
+- `POST /api/v1/workflows/runs/{run_id}/retry`
+- `POST /api/v1/workflows/runs/{run_id}/cancel`
+- `GET /api/v1/workflows/runs/{run_id}/reconstruction`
+- `GET /api/v1/workflows/reviews`
+- `GET /api/v1/workflows/exceptions`
+- `POST /api/v1/workflows/runs/{run_id}/reviews/{review_id}/decision`
+- `GET /api/v1/agents/operations`
+- `GET /api/v1/agents/operations/{operation_id}`
+- `POST /api/v1/agents/operations/{operation_id}`
+- `GET /api/v1/context-packages/schema`
+- `POST /api/v1/context-packages`
 - `GET /openapi.json`
 
 Unversioned endpoints are operational probes. Versioned endpoints establish
@@ -59,18 +96,63 @@ the `/api/v1` namespace for future domain resources.
 - readiness checks,
 - version payload,
 - asset service construction,
-- basic actor/correlation context construction,
+- actor/correlation/delegation context construction,
 - asset, metadata, lifecycle, relationship, audit, and policy operation
-  translation.
+  translation,
+- ingestion job start/list/get translation,
+- governed retrieval query translation for assets, context entities, and
+  relationships,
+- transformation operation/run/retry/cancel translation,
+- workflow template/run/review/exception/reconstruction translation,
+- bounded agent operation catalog and dispatch translation,
+- governed context-package assembly translation.
 
 Readiness currently checks that the configured asset registry repository can
 list assets. It does not mutate state.
 
-Asset, metadata, relationship, lifecycle, audit, and policy operations delegate
-to `AssetRegistryService`, the configured repository, and the configured
-`PolicyGateway`. Protected mutations therefore keep the existing policy and
-audit semantics. The current header-to-actor translation is deliberately simple
-and will be expanded in `KONT-WP-0009-T004`.
+Asset, metadata, relationship, lifecycle, audit, policy, ingestion, retrieval,
+transformation, and workflow operations delegate to existing application
+services, the configured repository, and the configured `PolicyGateway`.
+Protected mutations and retrieval operations therefore keep the existing policy
+and audit semantics.
+
+`KONT-WP-0009-T004` expanded request context parsing. The FastAPI adapter now
+accepts explicit actor, delegated actor, group, agent, request-scope, and
+policy-scope headers, and exposes the resulting operation context at
+`GET /api/v1/context`. Authorization errors are redacted at the HTTP boundary
+so denied responses keep action, resource, correlation, and public policy
+decision fields while omitting protected resource metadata from policy context.
+
+Job and run responses include correlation IDs, state, output references,
+failures or diagnostics, and compact retry/cancel hints where the runtime can
+derive them. Retrieval responses remain permission-filtered and source-grounded
+through source references, representations, snippets, relationships, and
+retrieval audit events. Transformation and workflow responses expose lineage,
+audit events, run reconstruction, review tasks, and exception queues from the
+underlying core services.
+
+`KONT-WP-0009-T005` added a bounded agent operation catalog. Agents can list
+documented operations and execute only those operation IDs. Each catalog entry
+declares required permissions, input/output shape notes, audit operation,
+failure modes, and dry-run support. Execution first authorizes and audits
+`agent.operation.*`, then dispatches through existing runtime operations such
+as retrieval, metadata enrichment, transformation, workflow invocation, review
+submission, or result reporting.
+
+`KONT-WP-0009-T006` added a governed context-package assembly API. Packages are
+assembled from permission-filtered retrieval results rather than unrestricted
+repository reads. The payload carries selected assets, snippets, metadata,
+relationships, representations, source references, policy constraints, opaque
+external memory refs, and an audit event. The `markitect` format adds a
+Markitect-compatible payload envelope while keeping markdown rendering,
+selector semantics, and contract checks delegated to `markitect-tool`.
+
+`KONT-WP-0009-T007` added explicit review/dry-run response envelopes for agent
+operation policy decisions. `require_review` decisions now return
+`review_required` envelopes with review obligations and `review_required` audit
+outcomes. `dry_run_only` decisions return `dry_run_required` envelopes unless
+the request is already a dry run. Partial-failure contracts are covered through
+directory ingestion with mixed supported and unsupported inputs.
 
 ## Dependency Boundary
 
@@ -96,6 +178,18 @@ missing-dependency behavior are tested without FastAPI.
 - runtime relationship create/list operations,
 - runtime audit query and policy evaluation,
 - runtime policy denial blocking a protected operation,
+- runtime actor context with delegated actors and AI-agent identity,
+- redacted API authorization error payloads,
+- runtime ingestion jobs with completed and failed job envelopes,
+- runtime source-grounded retrieval with snippets,
+- runtime transformation runs with lineage and audit references,
+- runtime workflow template/run/reconstruction contracts,
+- runtime bounded agent operation catalog, dry-run behavior, dispatch, and
+  separate agent audit events,
+- runtime context-package assembly with source-grounded results, opaque memory
+  references, and Markitect-compatible payload shape,
+- runtime review-required and dry-run-only agent operation envelopes,
+- runtime partial-failure ingestion job envelopes,
 - `create_app()` missing-dependency behavior when the optional extra is absent,
 - health/readiness/version/OpenAPI endpoint contracts when FastAPI and HTTPX
   are installed,
@@ -104,9 +198,4 @@ missing-dependency behavior are tested without FastAPI.
 
 ## Not Yet Implemented
 
-- Ingestion, retrieval, transformation, workflow, review, and reconstruction
-  endpoints.
-- Request actor context and delegation middleware.
-- Bounded agent operation catalog.
-- Context package API.
-- Dry-run and review-gate response envelopes.
+No MVP service API tasks remain open in `KONT-WP-0009`.