# 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:

```bash
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:

```bash
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:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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:

```python
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.