generated from coulomb/repo-seed
94 lines
3.2 KiB
Markdown
94 lines
3.2 KiB
Markdown
# 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.
|