markitect-quarkdown/docs/adapter-boundary.md

Markitect Quarkdown Adapter Boundary

markitect-quarkdown provides the concrete render.quarkdown adapter for the Markitect render/export contract. Core markitect-tool owns the passive request/result/artifact/provenance contracts; this repository owns Quarkdown runtime behavior.

Adapter Contract

The adapter supports:

• inspect-profile
• export-source
• render-artifact

inspect-profile and export-source do not invoke Quarkdown. render-artifact requires a Quarkdown CLI plus runtime dependencies.

The adapter descriptor declares filesystem writes, external process execution, native renderer dependency, and permission-controlled network behavior. Callers can block render execution through Markitect request policy:

RenderExportRequest(
    source="# Demo",
    operation="render-artifact",
    profile="pdf",
    policy={"external_process": False},
)

Execution Plan

build_quarkdown_execution_plan produces an inspectable command plan with:

• Quarkdown command path
• source file path
• output directory
• expected artifact path
• Markitect profile
• Quarkdown document type
• output format
• permission flags
• runtime dependency notes

The default output directory is quarkdown-output. The default permission allow-list is project-read, and network access is denied by default.

Structured Failure

The adapter returns RenderExportResult diagnostics instead of raising for expected render failures:

• render.quarkdown.runtime_missing
• render.quarkdown.execution_failed
• render.quarkdown.artifact_missing
• render.quarkdown.artifact_extension
• render.quarkdown.artifact_empty
• render.quarkdown.capability_blocked

Artifact Validation

validate_quarkdown_artifact validates that the expected artifact exists, has the expected extension, is non-empty, and receives a sha256 digest. The result is a Markitect RenderArtifact with source-to-artifact provenance generated by the adapter.