markitect-tool/workplans/MKTT-WP-0020-render-export-adapter-contract.md

---
id: MKTT-WP-0020
type: workplan
title: "Render Export Adapter Contract"
domain: markitect
status: done
owner: markitect-tool
topic_slug: markitect
planning_priority: complete
planning_order: 150
depends_on_workplans:
  - MKTT-WP-0013
  - MKTT-WP-0015
related_workplans:
  - MKTT-WP-0018
  - MKTT-WP-0021
  - MQD-WP-0001
created: "2026-05-15"
updated: "2026-05-15"
state_hub_workstream_id: "19d1a377-848a-4156-b712-7b9febd836a6"
---

# MKTT-WP-0020: Render Export Adapter Contract

## Purpose

Define the `markitect-tool` contract for optional render/export adapters
without implementing real renderer operations in the core toolkit.

This is the output-side sibling of the source adapter contract. Source
adapters normalize input formats into canonical Markdown; render/export
adapters transform Markitect-compatible Markdown into rendered artifacts or
renderer-specific sources. The two directions must stay separate now that
`markitect-filter` owns concrete source normalization.

## Boundary

`markitect-tool` owns:

- render/export request and result envelopes
- adapter descriptors and extension catalog metadata
- declared output profiles such as plain, docs, slides, paged, static site,
  and PDF
- deterministic fake renderers for tests
- diagnostics, provenance, source maps, and capability declarations

`markitect-tool` does not own:

- Quarkdown CLI invocation
- Pandoc, browser, PDF, or static-site generator execution
- filesystem-writing publication jobs beyond test fixtures
- durable artifact storage
- renderer-specific dependency installation
- concrete application reports

Concrete Quarkdown integration belongs in `markitect-quarkdown`.

## Implementation Summary - 2026-05-15

Implemented the contract-only render/export adapter layer:

- `RenderExportAdapterDescriptor`, `RenderExportAdapterRegistry`, and optional
  package discovery through `markitect_tool.render_export_adapters`.
- `RenderExportRequest`, `RenderExportResult`, `RenderArtifact`, and
  `RenderProvenance` envelopes.
- Built-in deterministic `render.fake` adapter for contract tests.
- Capability and safety diagnostics for filesystem, network, external process,
  native renderer dependency, assisted generation, and publication side-effect
  boundaries.
- Extension catalog descriptors for `render.export-registry` and `render.fake`.
- Docs, fixture, public API exports, generated API reference, and tests.

No real renderer, Quarkdown invocation, external process, or filesystem-writing
publication behavior was added to `markitect-tool`.

## P20.1 - Define render adapter descriptors

```task
id: MKTT-WP-0020-T001
status: done
priority: high
state_hub_task_id: "5b52b196-a7f5-4e4f-abc6-972febdc2638"
```

Define a `RenderExportAdapterDescriptor` shape that mirrors the source adapter
descriptor style while remaining output-oriented.

Descriptor fields should include:

- stable adapter id
- version and human-readable name
- operations such as `export-source`, `render-artifact`, and `inspect-profile`
- supported input contracts
- output profiles and artifact media types
- option schema
- optional dependencies
- safety and capability metadata
- docs/examples links

Output: descriptor dataclass or schema, extension descriptor mapping, and
registry tests.

## P20.2 - Define render request and result envelopes

```task
id: MKTT-WP-0020-T002
status: done
priority: high
state_hub_task_id: "3d43b168-7e55-4885-ae17-fcea262f2641"
```

Define service-free request/result types:

- `RenderExportRequest`
- `RenderExportResult`
- `RenderArtifact`
- `RenderDiagnostic`
- `RenderProvenance`

Results should describe artifacts and source maps without requiring durable
artifact storage.

Output: serializable models, round-trip tests, and docs.

## P20.3 - Add deterministic fake renderer fixtures

```task
id: MKTT-WP-0020-T003
status: done
priority: high
state_hub_task_id: "45748ad7-131c-4b75-9720-6958fde93208"
```

Add an in-tree fake renderer that proves the contract without invoking
Quarkdown or any external process.

The fake renderer should support:

- profile inspection
- source export into deterministic text
- artifact metadata emission
- source-to-render provenance
- denied-operation diagnostics for disabled capabilities

Output: fake adapter, tests, and examples.

## P20.4 - Define capability and policy gates

```task
id: MKTT-WP-0020-T004
status: done
priority: medium
state_hub_task_id: "50aa8f00-eeba-495d-9d45-089f855fc3bd"
```

Pin a local capability vocabulary for render/export adapters:

- filesystem read
- filesystem write
- external process
- network
- native renderer dependency
- assisted generation
- publication side effect

This is a syntax-layer contract and local denial model, not a durable
authorization service.

Output: capability constants, blocked-operation diagnostics, and tests.

## P20.5 - Document Quarkdown handoff

```task
id: MKTT-WP-0020-T005
status: done
priority: medium
state_hub_task_id: "173a75d0-d82c-4dcb-9ced-eb73e9438db2"
```

Document how `markitect-quarkdown` should implement a concrete Quarkdown
adapter against this contract.

Output: handoff note linking `MQD-WP-0001`, example descriptor metadata, and
no direct Quarkdown dependency in `markitect-tool`.

## Exit Criteria

- Render/export adapters are discoverable through the extension framework.
- Contract tests pass with a fake deterministic renderer.
- Core Markitect remains usable without renderer dependencies.
- `markitect-filter` remains read-side only.
- Quarkdown interop is supported by contract, not by core dependency.