generated from coulomb/repo-seed
Markitect boundary and reuse tests
This commit is contained in:
@@ -201,8 +201,11 @@ Required MVP ports:
|
||||
|
||||
Adapter rules:
|
||||
|
||||
- `markitect-tool` is an adapter for markdown syntax and context-package
|
||||
interoperability.
|
||||
- `markitect-tool` is an adapter for markdown syntax, selector extraction,
|
||||
deterministic markdown operations, snapshot identity, contracts/runtime
|
||||
checks, and context-package interoperability. Engine domain code must not
|
||||
import it directly; adapter code should persist serializable Markitect
|
||||
outputs as adapter provenance or representation metadata.
|
||||
- `llm-connect` or equivalent is an adapter for LLM providers.
|
||||
- `phase-memory` is an adjacent memory runtime; this engine may exchange opaque
|
||||
memory references or context packages but should not implement memory phases.
|
||||
|
||||
@@ -55,6 +55,11 @@ The strongest implementation wedge is:
|
||||
review-gated where needed.
|
||||
- Use adapters for markdown tooling, document extraction, AI providers, search,
|
||||
workflow engines, external policy systems, and storage backends.
|
||||
- Treat `markitect-tool` as the Markdown-native adapter dependency described in
|
||||
`docs/markitect-tool-reuse-boundary.md` and
|
||||
`docs/markitect-tool-integration-usecases.md`, with contract tests guarding
|
||||
the expected parser, selector, operations, snapshot, and context-package
|
||||
behavior.
|
||||
|
||||
## Workplan Set
|
||||
|
||||
|
||||
213
docs/markitect-tool-integration-usecases.md
Normal file
213
docs/markitect-tool-integration-usecases.md
Normal file
@@ -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.
|
||||
@@ -8,6 +8,25 @@ 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 |
|
||||
@@ -22,6 +41,21 @@ layer; `kontextual-engine` is the system/runtime layer.
|
||||
| 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
|
||||
@@ -44,4 +78,3 @@ layer; `kontextual-engine` is the system/runtime layer.
|
||||
- Agent-operable context continuity and service/programmatic APIs.
|
||||
- Adapter registry that can call `markitect-tool`, `llm-connect`, and storage
|
||||
backends without embedding their internals.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user