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

id, type, title, domain, status, owner, topic_slug, planning_priority, planning_order, depends_on_workplans, related_workplans, created, updated, state_hub_workstream_id

id	type	title	domain	status	owner	topic_slug	planning_priority	planning_order	depends_on_workplans	related_workplans	created	updated	state_hub_workstream_id
MKTT-WP-0020	workplan	Render Export Adapter Contract	markitect	done	markitect-tool	markitect	complete	150	MKTT-WP-0013 MKTT-WP-0015	MKTT-WP-0018 MKTT-WP-0021 MQD-WP-0001	2026-05-15	2026-05-15	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

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

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

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

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

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.