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.

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.
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, 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.