kontextual-engine/docs/markitect-tool-integration-usecases.md

markitect-tool Integration Use Cases

Date: 2026-05-05

Status: contract examples for the kontextual-engine to markitect-tool adapter boundary.

Purpose

kontextual-engine should use markitect-tool for Markdown-native syntax, selection, deterministic operations, snapshot identity, and portable markdown-backed context packages. The engine should not rebuild those features. Instead, it should wrap them as adapters and persist engine-owned assets, lineage, policy decisions, audit events, and service contracts around them.

The executable companion for this document is tests/test_markitect_tool_contract.py. The reusable fixture corpus lives in examples/markitect-tool-contract/. Opt-in bottleneck sentinels are described in docs/markitect-tool-capacity-risks.md and implemented in tests/test_markitect_tool_capacity.py.

Expected Dependency Shape

• Optional dependency: kontextual-engine[markdown].
• Import preference: public exports from markitect_tool or documented subpackages.
• Failure mode: when unavailable, engine adapters raise structured adapter errors and non-Markdown functionality continues.
• Persistence posture: store serializable Markitect results and provenance as adapter metadata, not as canonical domain objects.

Run the examples against the sibling source checkout during integration development with:

PYTHONPATH=/home/worsch/kontextual-engine/src:/home/worsch/markitect-tool/src \
  python3 -m pytest tests/test_markitect_tool_contract.py -q

Run the larger capacity sentinels with:

KONTEXTUAL_RUN_CAPACITY=1 \
PYTHONPATH=/home/worsch/kontextual-engine/src:/home/worsch/markitect-tool/src \
  python3 -m pytest tests/test_markitect_tool_capacity.py -q

Use Case 1: Markdown Normalization

Intent: convert Markdown source content into structured frontmatter, headings, sections, blocks, and source-aware metadata.

Expected Markitect APIs:

• parse_markdown(markdown, source_path=...)
• parse_markdown_file(path)
• Document.to_dict()

Example:

from markitect_tool import parse_markdown

document = parse_markdown(markdown, source_path="decision.md")
frontmatter = document.frontmatter
headings = [heading.to_dict() for heading in document.headings]

Engine expectation:

• Ingestion stores the original source representation separately from the normalized representation.
• Frontmatter and headings can become engine metadata.
• The parser object model remains Markitect-owned.

Use Case 2: Selector-Based Markdown Extraction

Intent: extract stable Markdown units such as a section, heading set, frontmatter path, or block without inventing a second selector language.

Expected Markitect APIs:

• query_document(document, "sections[heading=Decision]")
• extract_document(document, "frontmatter.status")
• optional JSONPath support through Markitect when the dependency is present.

Example:

from markitect_tool import parse_markdown, query_document, extract_document

document = parse_markdown(markdown)
matches = query_document(document, "sections[heading=Decision]")
text = extract_document(document, "sections[heading=Decision]")[0]

Engine expectation:

• Engine retrieval contracts can reference source-grounded snippets derived from Markitect matches.
• Cross-format retrieval remains engine-owned and cannot be reduced to Markitect selectors.

Use Case 3: Deterministic Markdown Operations

Intent: compose, include, or transform Markdown while preserving Markitect operation provenance.

Expected Markitect APIs:

• transform_markdown(...)
• compose_files(...)
• resolve_includes(...)
• OperationProvenance.to_dict()

Example:

from markitect_tool import resolve_includes, transform_markdown

included = resolve_includes(markdown, base_dir=root)
transformed = transform_markdown(
    included.markdown,
    set_frontmatter={"status": "draft"},
    heading_delta=1,
)

Engine expectation:

• The transformation run, actor, policy context, source versions, and derived artifact identity are engine-owned.
• Markitect provenance is stored as adapter provenance inside the engine run.

Use Case 4: Snapshot Identity For Markdown Sources

Intent: reuse Markitect content-addressed snapshot identity for Markdown-backed normalized representations and dependency tracking.

Expected Markitect APIs:

• snapshot_identity_for_file(path, parse_options=..., contract_hash=...)
• SnapshotIdentity.snapshot_id
• SnapshotIdentity.to_dict()

Example:

from markitect_tool import snapshot_identity_for_file

identity = snapshot_identity_for_file("decision.md")
snapshot_id = identity.snapshot_id

Engine expectation:

• The engine can persist Markitect snapshot IDs as adapter metadata.
• Engine asset identity remains independent of Markitect snapshot identity.

Use Case 5: Markdown-Backed Agent Context Packages

Intent: build portable context packages from Markdown sources while applying local label policy where available.

Expected Markitect APIs:

• create_context_package_from_sources(...)
• activate_context_package(...)
• MemoryNamespace
• ContextBudget
• LocalLabelPolicyGateway

Example:

from markitect_tool import (
    ContextBudget,
    LocalLabelPolicyGateway,
    MemoryNamespace,
    activate_context_package,
    create_context_package_from_sources,
)

package = create_context_package_from_sources(
    "sections[heading=Decision]",
    [source_path],
    root=root,
    namespace=MemoryNamespace(project="kontextual-engine"),
    budget=ContextBudget(max_items=3),
)
activation = activate_context_package(package, policy_gateway=gateway)

Engine expectation:

• Markitect context packages are portable markdown-backed payloads.
• Engine context packages must remain permission-aware, source-grounded, auditable, and usable across non-Markdown assets.

Use Case 6: Contracts Runtime And Markdown Workflows

Intent: reuse Markitect contract checks, runtime context, templates, document functions, and markdown-centered workflow helpers where Markdown documents are the subject.

Expected Markitect APIs:

• check_document_contract(...)
• load_contract_file(...)
• evaluate_form_state(...)
• WorkflowRunner, load_workflow_file(...)
• document function, template, generation, and processor public APIs.

Engine expectation:

• Markitect checks can become workflow steps or validation adapters.
• The engine owns workflow templates, run state, retries, review gates, exceptions, audit, and derived artifacts.

Use Case 7: Markdown Proxy Schema Validation

Intent: validate Markdown source or proxy documents through Markitect document schemas instead of adding a second Markdown schema validator to the engine.

Expected Markitect APIs:

• load_schema_file(...)
• validate_schema(...)
• validate_document(...)
• validate_markdown_file(...)

Example:

from markitect_tool import validate_markdown_file

result = validate_markdown_file("asset-proxy.md", "asset-proxy.schema.md")

Engine expectation:

• Markdown proxy documents are adapter representations of governed assets.
• Markitect owns Markdown document schema validation for those proxies.
• Engine metadata schema validation remains registry-owned because it governs asset metadata records, confirmation state, policy assignment, write rejection, and audit behavior.

Integration Test Matrix

Test area	Boundary protected
Parser and document shape	Markdown structure comes from Markitect.
Selector query and extraction	Engine does not invent duplicate selector behavior.
Transform and include provenance	Markdown ops retain Markitect provenance.
Snapshot identity	Engine stores Markitect snapshot metadata without owning the algorithm.
Context package policy filtering	Agent context can reuse Markitect packages and local label policy.
Document contracts	Markdown validation can call Markitect contracts without moving contract semantics into the engine.
Markdown document schemas	Markdown source/proxy validation uses Markitect schema APIs instead of duplicating them.
Capacity sentinels	Larger generated examples expose likely parser, selector, include, context-package, and snapshot bottlenecks.

These tests are intentionally small but example-backed. They are not a replacement for markitect-tool's own test suite; they assert only the behaviors this engine depends on and provide concrete data for diagnosing interface drift.