generated from coulomb/repo-seed
266 lines
8.3 KiB
Markdown
266 lines
8.3 KiB
Markdown
# 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.
|