Add render export adapter contract

docs/api-reference.md

@@ -13,6 +13,9 @@ Generated from `markitect_tool.__all__`.
 - `LOCAL_INDEX_SCHEMA_VERSION` - object. str(object='') -> str
 - `MAX_FUNCTION_PIPELINE_DEPTH` - object. int([x]) -> integer
 - `NORMALIZED_SOURCE_SCHEMA_VERSION` - object. str(object='') -> str
+- `RENDER_EXPORT_ADAPTER_ENTRY_POINT_GROUP` - object. str(object='') -> str
+- `RENDER_EXPORT_ADAPTER_KIND` - object. str(object='') -> str
+- `RENDER_EXPORT_SCHEMA_VERSION` - object. str(object='') -> str
 - `SOURCE_ADAPTER_ENTRY_POINT_GROUP` - object. str(object='') -> str
 
 ## `markitect_tool.backend.engine`
@@ -310,6 +313,23 @@ Generated from `markitect_tool.__all__`.
 - `parse_reference(reference: 'str') -> 'ReferenceAddress'` - function. Parse a compact Markitect content reference.
 - `resolve_reference(reference: 'str | ReferenceAddress', *, context: 'ReferenceContext') -> 'ReferenceResolution'` - function. Resolve a content reference to one or more content units.
 
+## `markitect_tool.render.engine`
+
+- `FakeRenderExportAdapter() -> 'None'` - class. Deterministic no-op renderer used for contract tests.
+- `RenderArtifact(artifact_id: 'str', role: 'str', media_type: 'str', content: 'str | None' = None, path: 'str | None' = None, uri: 'str | None' = None, digest: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Metadata for a rendered or exported artifact.
+- `RenderExportAdapter(*args, **kwargs)` - class. Render/export adapter protocol.
+- `RenderExportAdapterDescriptor(id: 'str', version: 'str', name: 'str', operations: 'list[str]', input_contracts: 'list[str]', output_profiles: 'list[str]', artifact_media_types: 'list[str]', factory: 'RenderExportAdapterFactory', summary: 'str | None' = None, option_schema: 'dict[str, Any]' = <factory>, optional_dependencies: 'list[OptionalDependency]' = <factory>, safety: 'dict[str, Any]' = <factory>, quality_profile: 'dict[str, Any]' = <factory>, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Inspectable descriptor for one render/export adapter.
+- `RenderExportAdapterError` - class. Raised when render/export adapter contracts are invalid.
+- `RenderExportAdapterRegistry(descriptors: 'Iterable[RenderExportAdapterDescriptor] | None' = None) -> 'None'` - class. Registry of render/export adapter descriptors.
+- `RenderExportRequest(source: 'str', operation: 'str' = 'render-artifact', profile: 'str' = 'plain', source_path: 'str | None' = None, options: 'dict[str, Any]' = <factory>, policy: 'dict[str, Any]' = <factory>, schema_version: 'str' = 'markitect.render.export.v1', metadata: 'dict[str, Any]' = <factory>) -> None` - class. Service-free render/export request.
+- `RenderExportResult(adapter: 'dict[str, Any]', operation: 'str', profile: 'str', artifacts: 'list[RenderArtifact]' = <factory>, exported_source: 'str | None' = None, diagnostics: 'list[Diagnostic]' = <factory>, provenance: 'list[RenderProvenance]' = <factory>, schema_version: 'str' = 'markitect.render.export.v1', metadata: 'dict[str, Any]' = <factory>) -> None` - class. Result of a render/export adapter operation.
+- `RenderProvenance(operation: 'str', adapter_id: 'str', profile: 'str', source_path: 'str | None' = None, source_digest: 'str | None' = None, artifact_id: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Source-to-render provenance envelope.
+- `default_render_export_adapter_registry() -> 'RenderExportAdapterRegistry'` - function. Return the built-in render/export adapter registry.
+- `discover_render_export_adapters() -> 'list[RenderExportAdapterDescriptor]'` - function. Discover package-provided render/export adapter descriptors.
+- `render_capability_diagnostics(descriptor: 'RenderExportAdapterDescriptor', request: 'RenderExportRequest') -> 'list[Diagnostic]'` - function. Return diagnostics for capabilities blocked by request policy.
+- `render_export_registry_descriptor() -> 'ExtensionDescriptor'` - function. Descriptor for the render/export adapter registry itself.
+- `render_with_adapter(request: 'RenderExportRequest', *, registry: 'RenderExportAdapterRegistry | None' = None, adapter_id: 'str' = 'render.fake') -> 'RenderExportResult'` - function. Render/export through a registered adapter.
+
 ## `markitect_tool.runtime.assessment`
 
 - `AssessmentRequest(contract_id: 'str | None', rule_id: 'str', scope: 'str', text: 'str', criteria: 'Any', context: 'dict[str, Any]' = <factory>, structured_inputs: 'dict[str, Any]' = <factory>, severity: 'str' = 'error', threshold: 'float | None' = None, provider: 'str | None' = None, model: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. A provider-neutral request for rubric assessment.

docs/examples-index.md

@@ -37,6 +37,12 @@ This index maps example files to practical usecases and useful commands.
 | `examples/source-adapters/*.json`, `examples/source-adapters/normalized-output.md` | Expected envelopes for the v1 source adapter contract | Use as fixtures for `mkt source` commands after `MKTT-WP-0018` implementation |
 | `examples/source-adapters/fake-adapter-pyproject.toml` | External adapter entry point shape | Use as the fake package discovery fixture for source adapter contract tests |
 
+## Render Export Contract Fixtures
+
+| Files | Usecase | Try |
+| --- | --- | --- |
+| `examples/render/fake-render-request.yaml` | Deterministic render/export contract fixture | Use with the `render.fake` API adapter; no external renderer required |
+
 ## Cache, Backend, Policy, And Context
 
 | Files | Usecase | Try |

docs/internal-extension-framework.md

@@ -41,7 +41,7 @@ framework organizes how Markitect itself exposes and composes capabilities.
 | `generation-adapter` | provider-neutral assisted generation | request in, generated candidate out |
 | `source-adapter` | EPUB3/PDF/DOCX adapters in external packages | source asset in, normalized Markdown out |
 | `cli-group` | cache, backend, ref, class | command descriptors or registration hook |
-| `render-export` | future Quarkdown/export adapters | Markdown source in, rendered/exported artifact out |
+| `render-export` | Quarkdown/export adapters | Markdown source in, rendered/exported artifact descriptor out |
 | `document-function` | future function layer | function call in, typed document value out |
 
 ## Canonical Lifecycle

docs/render-export-adapters.md

@@ -0,0 +1,87 @@
+# 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
+
+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.

docs/workplan-planning-map.md

@@ -44,8 +44,10 @@ and descriptions mirror the operational view.
 | `MKTT-WP-0017` | complete | done | `MKTT-WP-0003`, `MKTT-WP-0013` | CLI/API polish and practical adoption track is complete: shell completion, extension discovery, generated CLI/API docs, usecase relevance matrix, E2E fixture matrix, large-corpus smoke coverage, first-use docs, examples index, and command cheat sheet. |
 | `MKTT-WP-0019` | complete | done | `MKTT-WP-0013`, `MKTT-WP-0017` | Source adapter contract refinement is complete: v1 read-only scope, normalized model fields, package entry point discovery, CLI/API envelopes, fake adapter fixtures, and `markitect-filter` EPUB3 handoff are pinned in `docs/source-adapter-contract.md`. |
 | `MKTT-WP-0018` | complete | done | `MKTT-WP-0013`, `MKTT-WP-0017`, `MKTT-WP-0019` | Source adapter framework implementation is complete: read-only models, protocol, registry, entry point discovery, extension descriptors, CLI/API, fake adapter fixtures, migration notes, and tests are in place. |
-| `MKTT-WP-0015` | P2 | todo | `MKTT-WP-0010`, `MKTT-WP-0011`, `MKTT-WP-0012` | Future render and document-function extensions: typed values, richer syntax, document-local reusable functions, Quarkdown/export adapters, render-aware references, assets, and permission sandboxing. Defer unless publishing/export pressure becomes current. |
-| `MKTT-WP-0016` | P2 | todo | `MKTT-WP-0008`, `MKTT-WP-0007`, `MKTT-WP-0009`, `MKTT-WP-0013` | Follow-on agentic memory architecture: reasoning decision graphs, conversational paths, long-term knowledge graphs, memory service blueprints/profiles, graph-to-context-package compilation, and adapter boundaries. |
+| `MKTT-WP-0015` | complete | done | `MKTT-WP-0010`, `MKTT-WP-0011`, `MKTT-WP-0012` | Document function value contracts are complete: typed values, deterministic Markdown/JSON mapping, descriptor output validation, API exports, docs, examples, and tests. |
+| `MKTT-WP-0016` | complete | done | `MKTT-WP-0008`, `MKTT-WP-0007`, `MKTT-WP-0009`, `MKTT-WP-0013` | Memory graph profile contracts are complete: graph/profile/event models, validation, context-package compilation, CLI, fixture breadth, invalid fixtures, and runtime adapter handoff descriptors. |
+| `MKTT-WP-0020` | complete | done | `MKTT-WP-0013`, `MKTT-WP-0015` | Render/export adapter contract is complete: descriptors, registry/discovery, request/result/artifact/provenance envelopes, fake deterministic renderer, capability diagnostics, extension descriptors, docs, examples, and tests. |
+| `MKTT-WP-0021` | P2 | todo | `MKTT-WP-0010`, `MKTT-WP-0015`, `MKTT-WP-0020` | Render reference and asset manifest contract remains open: passive references, numbered unit metadata, static asset manifests, and source-to-render provenance maps. |
 
 ## Dependency Notes