kontextual-engine/docs/markitect-tool-reuse-boundary.md

# markitect-tool Reuse Boundary

Date: 2026-05-05

## Purpose

This note records what `kontextual-engine` should reuse from
`markitect-tool` instead of reimplementing. `markitect-tool` is the syntax
layer; `kontextual-engine` is the system/runtime layer.

## Dependency Contract

`kontextual-engine` should integrate `markitect-tool` through documented public
Python APIs and adapter modules. The preferred import surface is the
top-level `markitect_tool` package or documented subpackages such as
`markitect_tool.query`, `markitect_tool.ops`, `markitect_tool.memory`,
`markitect_tool.policy`, and `markitect_tool.backend`.

The engine must treat returned Markitect objects as adapter payloads. Domain
state should persist serializable envelopes, source references, digests,
lineage, policy decisions, and audit events rather than storing Markitect
runtime objects as canonical engine entities.

Markdown proxy documents are a supported adapter pattern. The engine may create
or store Markdown representations that proxy non-Markdown assets so Markitect
selectors, contracts, document schemas, functions, and workflows can operate on
them. Those proxies are representations of governed assets, not replacements
for engine-owned asset identity, metadata, lifecycle, policy, lineage, or audit
state.

Required integration behavior is captured in
`docs/markitect-tool-integration-usecases.md` and exercised by
`tests/test_markitect_tool_contract.py`. These tests are allowed to skip when
the optional `markitect-tool` dependency is not installed, but they become
stability checks for the boundary when the `markdown` extra is installed.

## Reuse As Adapter Dependencies

| Need in kontextual-engine | markitect-tool owner | Reuse posture |
| --- | --- | --- |
| Markdown parsing and structured document snapshots | `markitect_tool.core.parser`, `markitect_tool.core.document`, `markitect_tool.backend.engine.DocumentSnapshot` | Call through a markdown ingestion adapter. Persist normalized artifacts here, but do not parse markdown here. |
| Document-level selectors and extraction | `markitect_tool.query`, `docs/query-extraction.md` | Use for markdown source extraction and context package creation. Engine query should operate over persisted artifacts and relationships. |
| Deterministic transforms, composition, and includes | `markitect_tool.ops.engine`, `docs/transform-compose-include.md` | Treat as external operations invoked by workflows. Store operation provenance and derived artifacts in the engine. |
| Contract checks, runtime context, forms, and assessments | `markitect_tool.contract.*`, `markitect_tool.runtime.*`, `docs/runtime-context-forms-assessments.md` | Use as validation/assessment step adapters. Engine owns run state and audit trail. |
| Markdown document schema validation | `markitect_tool.schema.*` | Use for Markdown document/proxy validation. Engine-owned asset metadata validation stays in the registry layer. |
| Backend manifests, local snapshots, FTS, and query adapters | `markitect_tool.backend.*`, `docs/backend-fabric.md` | Reuse snapshot identity and local index concepts. Engine storage remains separate and cross-format. |
| Agent working memory context packages | `markitect_tool.memory.engine`, `docs/agent-working-memory.md` | Reuse as a portable context-package format for markdown-backed context. Engine should provide durable context registries across formats. |
| Workflow definition syntax and markdown-centered step kinds | `markitect_tool.workflow.*`, `docs/workflow-definition-standard.md` | Reuse where workflows consume markdown inputs. Engine workflows should generalize to artifact collections, external tools, and service operations. |
| Document functions, templates, and generation hooks | `markitect_tool.document_function`, `markitect_tool.generation` | Invoke as syntax-layer processors. Keep provider calls behind `llm-connect`. |
| Local label policy and policy adapter protocols | `markitect_tool.policy.*` | Reuse for markdown source/package filtering. Engine should expose policy-aware operations at artifact/service level. |

## Adapter Ownership Rules

- Markdown ingestion adapters may call `parse_markdown`, `parse_markdown_file`,
  `query_document`, `extract_document`, `validate_document`,
  `validate_markdown_file`, and `snapshot_identity_for_file`.
- Markdown transformation adapters may call `transform_markdown`,
  `compose_files`, `resolve_includes`, Markitect contract checks, document
  functions, templates, and workflow helpers.
- Agent/context adapters may call Markitect context-package and local policy
  APIs for markdown-backed context packages.
- Engine domain code must not import Markitect APIs directly.
- Service APIs must not expose the `mkt` CLI as the engine control surface.
- Cross-format query, policy, audit, workflow run, versioning, and export
  contracts remain engine-owned even when Markitect produced the markdown
  payload.

## Do Not Reimplement Here

- Markdown ASTs, section trees, frontmatter parsing, explode/implode, document
  transforms, includes, contract files, and selector syntax.
- Local markdown FTS/index refresh internals unless a durable engine backend
  explicitly wraps them.
- CLI-first command behavior from `mkt`.
- Provider-specific LLM adapters or prompt adapter internals.

## Engine-Owned Responsibilities

`kontextual-engine` should own the durable runtime concepts that sit above
`markitect-tool`:

- Artifact and collection identity across formats.
- Persistent artifact metadata, content digests, lineage, and lifecycle state.
- Relationship graphs between artifacts and collections.
- Workflow runs, step state, input/output bundles, errors, and provenance.
- Cross-artifact dependency graph, recomputation, and impact debt.
- Agent-operable context continuity and service/programmatic APIs.
- Adapter registry that can call `markitect-tool`, `llm-connect`, and storage
  backends without embedding their internals.