---
id: KONT-WP-0003
type: workplan
title: "Headless Knowledge Engine Implementation"
domain: markitect
repo: kontextual-engine
status: done
owner: codex
topic_slug: markitect
created: "2026-05-03"
updated: "2026-05-05"
state_hub_workstream_id: "0fd08391-e8c9-4f1b-ace4-06439f958e88"
---

# KONT-WP-0003: Headless Knowledge Engine Implementation

## Purpose

Build the first usable `kontextual-engine` runtime around the PRD/FRS contract:
persistent knowledge artifacts, collections, relationships, ingestion,
retrieval, workflows, and agent-operable context.

## I3.1 - Scaffold package and test harness

```task
id: KONT-WP-0003-T001
status: done
priority: high
state_hub_task_id: "3d3400a5-63ee-4c64-8bfb-fd3caa1ce787"
```

Create the initial Python package, dependency metadata, test harness, and CI
commands after the stack decision in `KONT-WP-0001`.

Output: `pyproject.toml`, `src/kontextual_engine/`, and `tests/`.

## I3.2 - Implement artifact and collection model

```task
id: KONT-WP-0003-T002
status: done
priority: high
state_hub_task_id: "638ce4d0-b96b-4d8f-8bd9-4c77acad0a59"
```

Implement core models for artifacts, metadata, collections, domains, and
relationships. Cover FR-001 through FR-011 with focused unit tests.

Output: `src/kontextual_engine/artifacts.py`,
`src/kontextual_engine/relationships.py`, and `tests/test_artifacts.py`.

## I3.3 - Implement storage abstraction

```task
id: KONT-WP-0003-T003
status: done
priority: high
state_hub_task_id: "41c84f25-96b0-40eb-b2b4-834938cf9bb9"
```

Define repository interfaces and the first backend. Start with the simplest
backend that can support deterministic tests, then document the path to SQLite
or service-backed persistence.

Output: `src/kontextual_engine/storage.py` and
`tests/test_storage_query.py`.

## I3.4 - Implement ingestion and normalization interfaces

```task
id: KONT-WP-0003-T004
status: done
priority: high
state_hub_task_id: "0be5fff9-f4a2-4aee-86b9-b84feef477f7"
```

Define format-agnostic ingestion contracts. Add a markdown adapter boundary
that can later call `markitect-tool`, without embedding markdown primitives in
this repo.

Output: `src/kontextual_engine/ingestion.py`.

## I3.5 - Implement query and retrieval API

```task
id: KONT-WP-0003-T005
status: done
priority: high
state_hub_task_id: "c8841fab-6dd1-47e1-a794-798bef1663e7"
```

Provide programmatic query over identifiers, metadata, content references, and
relationships. Cover FR-030 and FR-031 with tests.

Output: `src/kontextual_engine/query.py`.

## I3.6 - Implement workflow run model

```task
id: KONT-WP-0003-T006
status: done
priority: high
state_hub_task_id: "0d62f47c-339a-4d86-9ab0-737bd4ab553c"
```

Represent workflow runs, steps, dependencies, inputs, outputs, structured
errors, and derived artifacts. Cover FR-040 through FR-052.

Output: `src/kontextual_engine/workflows.py`.

## I3.7 - Implement agent context surface

```task
id: KONT-WP-0003-T007
status: done
priority: medium
state_hub_task_id: "96689817-e8e9-42e4-9af3-f03021e3ae4e"
```

Provide a provider-neutral context assembly API so agents can inspect
knowledge state, trigger operations, and receive traceable results.

Output: `src/kontextual_engine/context.py`.

## I3.8 - Define service API boundary

```task
id: KONT-WP-0003-T008
status: done
priority: medium
state_hub_task_id: "0f4748f9-934a-438c-ac2d-e9796ad98818"
```

Decide and document the first HTTP/RPC service boundary after the programmatic
API is stable enough to avoid framework-driven architecture.

Output: `docs/service-api-boundary.md`.