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

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