kontextual-engine/workplans/KONT-WP-0004-knowledge-operations-architecture.md

---
id: KONT-WP-0004
type: workplan
title: "Knowledge Operations Architecture Rebase"
domain: markitect
repo: kontextual-engine
status: completed
owner: codex
topic_slug: markitect
planning_priority: high
planning_order: 4
created: "2026-05-05"
updated: "2026-05-06"
state_hub_workstream_id: "e177f2dc-a2a0-41a4-b5cd-82e8f9f12f34"
---

# KONT-WP-0004: Knowledge Operations Architecture Rebase

## Purpose

Rebase the implementation roadmap around the V0.2 product vision:
`kontextual-engine` as a headless knowledge operations engine for making
heterogeneous information assets persistent, contextual, governed, retrievable,
transformable, and agent-operable.

This workplan supersedes the earlier persistence-only interpretation of
`KONT-WP-0004`. Durable persistence remains required, but it must be designed
with asset identity, provenance, permissions, audit, transformation lineage,
workflow state, exportability, and agent-safe operation from the start.

## Outputs

- Updated scope and roadmap documentation.
- `docs/architecture-blueprint.md` as the architecture baseline for the V0.2
  implementation sequence.
- `docs/markitect-tool-reuse-boundary.md` and
  `docs/markitect-tool-integration-usecases.md` as the explicit boundary
  between markdown syntax tooling and the engine runtime.
- `docs/architecture-core-implementation.md` as the first code-backed domain
  core implementation note.
- Architecture decision notes for the P0 capability baseline.
- Traceability from PRD/FRS V0.2 requirements to implementation workplans.
- Revised implementation sequence for `KONT-WP-0005` through `KONT-WP-0010`.

## markitect-tool Boundary Remark

The architecture work must treat `markitect-tool` as the Markdown-native syntax
and operations dependency, not as a subsystem to copy into this repo.
Architecture decisions should require adapter-only imports, public Markitect
APIs, and integration contract tests for parser, selector, operation,
snapshot, and context-package behavior.

## A4.1 - Reconcile implementation baseline with V0.2 vision

```task
id: KONT-WP-0004-T001
status: done
priority: high
state_hub_task_id: "6b665ab1-cc8e-473b-824a-d953b598bb72"
```

Review the current Python package against the V0.2 PRD/FRS and identify which
existing contracts can remain, which must be renamed or expanded, and which are
now out of date.

Acceptance:

- Current modules are mapped to V0.2 capability areas.
- In-memory artifacts, collections, relationships, query, workflows, and
  context packages are classified as reusable, replace, or defer.
- The old persistence-only roadmap is explicitly superseded.

## A4.2 - Define canonical asset identity and representation model

```task
id: KONT-WP-0004-T002
status: done
priority: high
state_hub_task_id: "eed4f0b5-9080-4c76-9ae6-841459edbab6"
```

Define stable knowledge asset identity, source references, source
representations, normalized representations, derived artifacts, aliases,
supersession, lifecycle state, and duplicate/re-ingestion semantics.

Acceptance:

- FR-001 through FR-010 have an implementation model.
- Source, normalized, and derived forms are distinct.
- Identity is independent of path, filename, backend, and representation.

## A4.3 - Define actor permission policy and audit baseline

```task
id: KONT-WP-0004-T003
status: done
priority: high
state_hub_task_id: "7f34e36f-4e9b-40ab-bbe9-afaee4553a9f"
```

Define the minimum actor, authorization context, policy check, sensitivity,
lifecycle, review, fail-closed, and audit event model needed for P0.

Acceptance:

- Human, application, automation, service, and AI-agent actors are modeled.
- Permission-aware retrieval and transformation rules are specified.
- Audit records include actor, operation, target, outcome, correlation ID, and
  policy context where available.

## A4.4 - Define provenance lineage versioning and derived artifact model

```task
id: KONT-WP-0004-T004
status: done
priority: high
state_hub_task_id: "6d20a457-7246-4380-943f-c6d726506356"
```

Specify how source provenance, versions, content changes, metadata changes,
relationship changes, transformation runs, and derived artifacts are linked.

Acceptance:

- FR-080 through FR-090 and FR-140 through FR-146 are mapped to data contracts.
- Derived artifacts can explain their source assets, parameters, actor, policy,
  run, and output identity.
- Restore, supersession, and re-run behavior is defined at contract level.

## A4.5 - Define retrieval architecture and quality KPIs

```task
id: KONT-WP-0004-T005
status: done
priority: high
state_hub_task_id: "e4e6f188-9ac3-4daf-9633-f11d812e50fa"
```

Define the first retrieval architecture: lexical search, filters, relationship
retrieval, stable pagination, snippets, citations/source-grounding, permission
checks, feedback, and KPIs.

Acceptance:

- FR-060 through FR-071 have an implementation path.
- MVP retrieval does not depend on vector search.
- Precision, zero-result rate, p95 latency, citation precision, and permission
  fidelity are named as measurable targets.

## A4.6 - Define workflow job and operation execution architecture

```task
id: KONT-WP-0004-T006
status: done
priority: high
state_hub_task_id: "d0a9e9d4-12eb-406b-b32c-5b45f931f18c"
```

Define job and workflow execution boundaries for ingestion, enrichment,
validation, transformation, review, publication, archival, synchronization,
export, retries, cancellation, and exception handling.

Acceptance:

- FR-020 through FR-030 and FR-100 through FR-110 have job-state semantics.
- Workflow templates, runs, steps, dependencies, retries, failures, and outputs
  are explicitly modeled.
- Embedded execution vs adapter-backed orchestration is decided for MVP.

## A4.7 - Define agent-safe operation catalog and review gates

```task
id: KONT-WP-0004-T007
status: done
priority: high
state_hub_task_id: "965738a5-9538-45f6-98bb-7987aba62904"
```

Define explicit agent operations for inspection, retrieval, metadata
enrichment, classification, transformation, workflow invocation, review
submission, dry runs, and bounded context packages.

Acceptance:

- FR-160 through FR-169 have API-level operation contracts.
- Agent operations cannot bypass permission, lifecycle, export, or review
  policy.
- Destructive or sensitive actions can be denied, dry-run, or routed to review.

## A4.8 - Publish roadmap traceability and update scope docs

```task
id: KONT-WP-0004-T008
status: done
priority: medium
state_hub_task_id: "ea7313ce-fb1f-49b1-b5da-66a036893a04"
```

Update repo-local docs so humans and agents can understand the new product
shape and implementation sequence.

Acceptance:

- `SCOPE.md` reflects the V0.2 knowledge operations vision.
- `docs/knowledge-operations-roadmap.md` maps PRD/FRS areas to workplans.
- `docs/architecture-blueprint.md` defines the implementation shape and review
  checklist.
- Markitect dependency boundaries and use cases are linked from roadmap and
  scope materials where they affect implementation sequencing.
- `README.md` points to the new research and roadmap materials.

## Definition Of Done

- Architecture docs clearly distinguish engine, application, connector,
  provider, and domain-package responsibilities.
- Architecture docs define domain core, application service, port, adapter,
  persistence, retrieval, workflow, policy, audit, service API, export, and
  agent-safe operation boundaries.
- Workplans `KONT-WP-0005` through `KONT-WP-0010` exist and are linked to State
  Hub.
- `python3 -m pytest` passes.
- State Hub consistency passes without using the push-capable fixer.