# Render Export Adapter Contract

Markitect owns the contract layer for optional render/export adapters. It does
not run real renderers in core, install renderer dependencies, store durable
artifacts, or publish outputs.

This is the output-side sibling of the read-only source adapter contract:

```text
source adapters: source formats -> normalized Markdown
render adapters: Markdown/context -> renderer source or artifact metadata
```

`markitect-filter` remains read-side only. Concrete Quarkdown execution belongs
in `markitect-quarkdown`.

## Contract Version

- `markitect.render.export.v1`

The optional package entry point group is:

```text
markitect_tool.render_export_adapters
```

## Descriptor Shape

Render/export adapters declare:

| Field | Meaning |
| --- | --- |
| `id` | Stable adapter id, for example `render.fake` or `render.quarkdown`. |
| `version` | Adapter contract implementation version. |
| `operations` | Supported operations: `inspect-profile`, `export-source`, `render-artifact`. |
| `input_contracts` | Accepted inputs, such as Markdown or function evaluation results. |
| `output_profiles` | Supported profiles: `plain`, `docs`, `slides`, `paged`, `static-site`, `pdf`. |
| `artifact_media_types` | Artifact media types the adapter may emit. |
| `safety` | Declared filesystem, process, network, native dependency, and side-effect behavior. |

The built-in `render.fake` adapter is deterministic and never invokes external
processes. It exists to test the contract and examples.

## Request And Result

`RenderExportRequest` contains Markdown source, operation, profile, source
identity, options, and local policy flags.

`RenderExportResult` contains:

- adapter identity
- operation and profile
- exported renderer source where applicable
- artifact metadata
- diagnostics
- source-to-render provenance
- metadata such as whether an external renderer was invoked

`RenderExportRequest` may also carry a passive render reference manifest. That
manifest is defined in `docs/render-reference-asset-manifest.md` and lets core
Markitect pass unit identities, cross-reference intent, TOC planning, source
maps, and asset descriptors to a renderer without assigning final numbering or
copying assets.

Artifacts are descriptors, not durable storage records. Real renderer packages
may write files, but core Markitect only models the result.

## Capability Gates

Adapters declare local safety flags:

- `filesystem_read`
- `filesystem_write`
- `external_process`
- `network`
- `native_renderer_dependency`
- `assisted_generation`
- `publication_side_effect`

`render_capability_diagnostics` maps those flags to denied-operation
diagnostics when a request policy blocks them. This is a contract boundary, not
a durable authorization service.

## Quarkdown Handoff

`MQD-WP-0001` should implement a concrete `render.quarkdown` adapter in
`markitect-quarkdown` against this contract. That adapter should own Quarkdown
CLI invocation, Java/Node/Puppeteer assumptions, Quarkdown permissions, output
directory conventions, artifact validation, and upstream compatibility
monitoring.

`markitect-tool` keeps only the render/export schema, descriptor registry,
fake renderer, diagnostics, provenance, and tests.