markitect-quarkdown/workplans/MQD-WP-0001-quarkdown-render-adapter-boundary.md

---
id: MQD-WP-0001
type: workplan
title: "Quarkdown Render Adapter Boundary"
domain: markitect
status: done
owner: markitect-quarkdown
topic_slug: markitect
planning_priority: complete
planning_order: 10
related_workplans:
  - MKTT-WP-0020
  - MKTT-WP-0021
  - MKTT-WP-0015
  - MKTF-WP-0003
created: "2026-05-15"
updated: "2026-05-15"
state_hub_workstream_id: "fb4ebcf9-21ba-455d-8982-63908663c130"
---

# MQD-WP-0001: Quarkdown Render Adapter Boundary

## Purpose

Implement the concrete Quarkdown render integration in the native
`markitect-quarkdown` repo, using the render/export adapter contract defined by
`markitect-tool` rather than embedding Quarkdown execution in core Markitect.

This repository is the right home for Quarkdown-specific runtime assumptions,
permission handling, CLI invocation, artifact validation, and open-reuse
integration maintenance.

## Boundary

`markitect-quarkdown` owns:

- Quarkdown CLI/distribution integration
- runtime dependency assumptions such as Java, Node.js, npm, and Puppeteer
- Quarkdown permission model mapping
- output directory and artifact validation rules
- PDF/HTML/profile-specific behavior
- upstream Quarkdown compatibility monitoring
- open-reuse Integration Definition metadata

`markitect-quarkdown` does not own:

- core Markitect document-function parsing
- source-format read adapters
- durable artifact storage or publication lifecycle
- enterprise authorization services
- a long-lived divergent Quarkdown fork

## Implementation Summary

Completed as the initial native Quarkdown render adapter boundary:

- Added a Python package with a `render.quarkdown` descriptor registered under
  `markitect_tool.render_export_adapters`.
- Implemented `MarkitectQuarkdownAdapter` for `inspect-profile`,
  `export-source`, and controlled `render-artifact` execution.
- Added Markitect profile to Quarkdown document/output mapping, option schema,
  permission mapping, default output conventions, dry-run plan artifacts, and
  structured runtime/execution/artifact diagnostics.
- Added artifact validation with extension, non-empty, digest, media type, and
  source-to-artifact provenance.
- Added docs, an example render request, open-reuse integration metadata, and
  tests that use fake execution plus a real-runtime skip hook.

## P1.1 - Map Markitect render contract to Quarkdown invocation

```task
id: MQD-WP-0001-T001
status: done
priority: high
state_hub_task_id: "cb8014d5-9384-4736-8be4-a1f336a416c8"
```

Map the future `MKTT-WP-0020` render/export request and result envelopes onto a
`MarkitectQuarkdownAdapter` boundary.

The mapping should define:

- accepted Markitect-compatible source inputs
- Quarkdown source export expectations
- output profiles and artifact media types
- structured failure results
- provenance and source map fields returned to Markitect

Output: adapter boundary note and compatibility tests with contract fixtures.

## P1.2 - Define Quarkdown profile and option mapping

```task
id: MQD-WP-0001-T002
status: done
priority: high
state_hub_task_id: "57a11359-4888-48e9-978b-bf30ba86c961"
```

Define how Markitect render profiles map to Quarkdown document and output
modes:

- plain
- docs
- slides
- paged
- static site or HTML
- PDF

Output: profile matrix, option schema, and examples.

## P1.3 - Implement controlled CLI execution boundary

```task
id: MQD-WP-0001-T003
status: done
priority: high
state_hub_task_id: "e0aa1eb2-39e2-40c6-bd03-c44910303ce9"
```

Implement Quarkdown invocation through a controlled adapter boundary with
explicit capability metadata for filesystem writes, external process execution,
and optional network/runtime dependencies.

Output: adapter implementation, structured diagnostics, and tests that can skip
cleanly when Quarkdown runtime dependencies are unavailable.

## P1.4 - Handle Quarkdown permissions and output conventions

```task
id: MQD-WP-0001-T004
status: done
priority: high
state_hub_task_id: "c0d73105-ae4f-407e-9137-fe4216abd9c8"
```

Pin Quarkdown 2.x permission model behavior, default output directories,
artifact naming, and PDF export assumptions.

Output: permission mapping docs, output convention tests, and compatibility
notes.

## P1.5 - Validate generated artifacts and provenance

```task
id: MQD-WP-0001-T005
status: done
priority: medium
state_hub_task_id: "4719b31f-eec9-4e1b-a2e5-82a261ed8139"
```

Validate generated artifacts without making `markitect-tool` responsible for
renderer behavior.

Validation should cover:

- expected artifact existence
- media type and file extension
- digest/checksum
- source-to-artifact provenance
- error interpretation for failed renders

Output: artifact validation helpers, fixtures, and tests.

## P1.6 - Maintain open-reuse integration metadata

```task
id: MQD-WP-0001-T006
status: done
priority: medium
state_hub_task_id: "f8c2c874-8fee-45b3-86fd-2fe7fc563ee8"
```

Represent the Quarkdown integration as an open-reuse Integration Definition so
upstream change, dependency, license, and security risks can be monitored.

Output: integration definition, upstream version policy, risk profile, and
maintenance checklist.

## Exit Criteria

- Quarkdown render behavior lives in `markitect-quarkdown`, not
  `markitect-tool` or `markitect-filter`.
- The adapter can satisfy the `MKTT-WP-0020` render/export contract once that
  contract exists.
- Runtime dependencies are optional, declared, and test-skippable.
- Generated artifacts have structured diagnostics, checksums, and provenance.
- Upstream Quarkdown compatibility is tracked as an open-reuse integration.