--- id: KONT-WP-0008 type: workplan title: "Traceable Transformations And Workflow Jobs" domain: markitect repo: kontextual-engine status: active owner: codex topic_slug: markitect planning_priority: high planning_order: 8 created: "2026-05-05" updated: "2026-05-06" state_hub_workstream_id: "1b7a6b04-7879-4862-bb3e-817f7f20fc59" --- # KONT-WP-0008: Traceable Transformations And Workflow Jobs ## Purpose Implement the operations layer that turns knowledge assets into traceable outputs: transformation operations, derived artifacts, workflow templates, workflow runs, job execution state, retries, cancellation, review gates, exception queues, and operation audit. ## Requirement Coverage Primary: FR-080 to FR-090 and FR-100 to FR-110. Supporting: FR-083 to FR-085, FR-106, FR-144 to FR-145, FR-165, FR-200 to FR-202. ## Architecture Constraint Implement transformations and workflows through operation registries, workflow services, repository ports, event ports, policy checks, and audit events described in `docs/architecture-blueprint.md`. Execution may start embedded, but contracts must allow later queue or workflow-engine adapters. ## markitect-tool Boundary Remark Markdown-specific transformations should delegate to Markitect operations, contracts, runtime checks, templates, document functions, processors, and workflow helpers. The engine owns the operation registry, run state, actors, policy checks, derived artifact identity, lineage, retries, review gates, and audit events. ## Implementation Status The first foundation slice is implemented for transformation operations, transformation run persistence, and derived artifact lineage. See `docs/transformation-implementation.md`. Workflow templates, job runner orchestration, review gates, exception queues, and richer workflow audit reconstruction remain open in this workplan. ## O8.1 - Implement transformation operation registry ```task id: KONT-WP-0008-T001 status: done priority: high state_hub_task_id: "ee2471b1-fab3-48f5-8b2d-d8f624abfc35" ``` Create a registry for transformation operations such as summarize, extract, classify, compose, validate, generate report, and produce structured view. Acceptance: - Operations declare inputs, outputs, parameters, required permissions, and supported asset types. - Provider-specific LLM behavior remains behind adapters. - Unsupported operations return structured capability errors. - Markdown compose, include, transform, and validate operations are registered as adapter-backed operations rather than reimplemented. Implemented: - `TransformationOperationRegistry` and default operation descriptors are in `src/kontextual_engine/services/transformation_service.py`. - `structured_view` is executable inside the engine as a generic derived structured representation. - Markdown operations are registered with `adapter_ref="markitect-tool"` and no local handler, preserving the boundary against reimplementing Markitect. ## O8.2 - Implement transformation runs with parameters actors and policy context ```task id: KONT-WP-0008-T002 status: done priority: high state_hub_task_id: "1eac7b47-8cff-4736-9f7d-599123218bad" ``` Represent each transformation as a run with source assets, source versions, operation type, parameters, actor, policy context, timestamps, and status. Acceptance: - Transformations can be queued, run, completed, failed, retried, or canceled. - Transformation permissions are checked before reading sources or writing outputs. - Parameters needed to interpret or reproduce the run are preserved. Implemented: - `TransformationRun` records include operation, source assets, source versions, parameters, actor, correlation ID, policy context, diagnostics, timestamps, status, retry metadata, and output asset IDs. - Source-read and run-execution policy decisions are captured before handler execution. - Run state is persisted in memory and SQLite repositories. ## O8.3 - Persist derived artifacts and source lineage ```task id: KONT-WP-0008-T003 status: done priority: high state_hub_task_id: "837ad793-2e9a-41f0-bce6-0a75815b5c15" ``` Persist summaries, extracts, reports, structured representations, generated artifacts, and composed outputs as governed derived artifacts. Acceptance: - Derived artifacts have stable identity and lineage to source assets. - Lineage includes transformation run, source versions, actor, parameters, policy context, and output representation. - Re-runs create new traceable records rather than silently overwriting outputs. Implemented: - Executed transformations can persist governed derived assets through `AssetRegistryService`. - `DerivedArtifactLineage` records are saved and queryable by output asset, source asset, or transformation run. - Derived asset versions use `VersionChangeType.DERIVED_OUTPUT` and point back to the transformation run and source parent version. ## O8.4 - Implement workflow templates steps dependencies and preconditions ```task id: KONT-WP-0008-T004 status: todo priority: high state_hub_task_id: "2c55c5dd-f07b-466b-85a5-f229e41fd124" ``` Define reusable workflow templates containing steps, dependencies, inputs, outputs, preconditions, policy checks, and failure behavior. Acceptance: - Templates can be created and invoked programmatically. - Step dependencies prevent unsafe or premature execution. - Workflow inputs can be assets, collections, queries, source events, or submitted payloads. ## O8.5 - Implement job runner status retry resume and cancel behavior ```task id: KONT-WP-0008-T005 status: todo priority: high state_hub_task_id: "5f4d6c88-904d-4369-90d5-eaa4d27e3010" ``` Implement a simple MVP job runner for workflows and transformations. Acceptance: - Runs expose queued, running, waiting, completed, failed, retried, canceled, and partially completed states. - Safe retry, resume, and cancellation behavior is defined per operation. - Recovery actions do not require direct storage edits. ## O8.6 - Implement review gates human tasks and exception queues ```task id: KONT-WP-0008-T006 status: todo priority: medium state_hub_task_id: "5fae9005-4d64-4fca-8c51-a19405512377" ``` Add workflow primitives for review, approval, correction, rejection, low-confidence handling, policy conflicts, and blocked exceptions. Acceptance: - Sensitive or high-impact outputs can pause for human review. - Exception queues expose failed, blocked, low-confidence, policy-conflicted, or review-required items. - Review decisions continue, reject, correct, retry, or escalate runs. ## O8.7 - Audit workflow and transformation operations ```task id: KONT-WP-0008-T007 status: todo priority: medium state_hub_task_id: "9e06aa46-3988-4389-99ec-0a934c68af1b" ``` Audit template changes, run starts, step executions, retries, cancellations, approvals, failures, outputs, and derived artifact changes. Acceptance: - A workflow run can be reconstructed from run records and audit events. - Audit records include actor, operation, target, outcome, correlation ID, and policy context. - Derived artifact audit events connect to source lineage. ## Definition Of Done - Transformations and workflows produce inspectable run records and audit events. - Derived artifacts are persistent, governed, and lineage-linked. - Transformation and workflow run models follow `docs/architecture-blueprint.md`. - `python3 -m pytest` passes.