Markitect boundary and reuse tests

docs/markitect-tool-integration-usecases.md

@@ -0,0 +1,213 @@
+# 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`.
+
+## 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.
+
+## 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.
+
+## 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. |
+
+These tests are intentionally small. They are not a replacement for
+`markitect-tool`'s own test suite; they assert only the behaviors this engine
+depends on.