---
id: MKTT-WP-0021
type: workplan
title: "Render Reference And Asset Manifest Contract"
domain: markitect
status: done
owner: markitect-tool
topic_slug: markitect
planning_priority: complete
planning_order: 155
depends_on_workplans:
  - MKTT-WP-0010
  - MKTT-WP-0015
  - MKTT-WP-0020
related_workplans:
  - MKTT-WP-0018
  - MKTF-WP-0003
  - MQD-WP-0001
created: "2026-05-15"
updated: "2026-05-15"
state_hub_workstream_id: "c567c1a8-3029-4f9c-9587-e85fede64599"
---

# MKTT-WP-0021: Render Reference And Asset Manifest Contract

## Purpose

Define passive contracts for render-aware references, numbered units, and
static asset manifests.

This workplan should make rendered document structure inspectable before and
after an optional renderer runs. It should not implement renderer layout,
final numbering, asset copying, or publication lifecycle.

## Boundary

`markitect-tool` owns:

- stable render unit identities
- references to figures, tables, equations, code blocks, and custom numbered
  units
- table-of-contents and cross-reference planning metadata
- static asset manifest fields
- media checksums and copy-policy declarations
- source-to-render provenance envelopes

Renderer packages own:

- final numbering and layout
- link rewriting
- asset copying
- output directory conventions
- artifact validation

`markitect-filter` owns only read-side source asset and attachment metadata
needed by normalized Markdown inputs.

## Implementation Summary

Completed in `markitect-tool` as a passive render reference and asset manifest
contract:

- `RenderUnitReference`, `RenderCrossReference`, and `RenderTocEntry` model
  renderable units, requested cross-references, and TOC planning without final
  numbering.
- `RenderAsset`, `RenderAssetManifest`, and `RenderAssetProvenance` model
  static assets, copy-policy declarations, output placeholders, and source
  adapter attachment provenance without asset copying.
- `RenderSourceMap` and `RenderReferenceManifest` tie Markitect source spans,
  generated function outputs, render units, assets, and artifact references
  together under `markitect.render.reference.v1`.
- `RenderExportRequest` can carry a passive render manifest; `render.fake`
  echoes manifest and asset counts into result/artifact metadata without
  invoking a renderer.
- Docs, examples, extension catalog metadata, generated API reference, and
  tests were added.

## P21.1 - Define render unit references

```task
id: MKTT-WP-0021-T001
status: done
priority: high
state_hub_task_id: "3d33d387-633e-4ffb-962e-1a5061d3db01"
```

Define stable identities for renderable units:

- figures
- tables
- equations
- code blocks
- sections
- custom numbered units

Output: render reference model, serialization tests, and examples.

## P21.2 - Define cross-reference and TOC planning metadata

```task
id: MKTT-WP-0021-T002
status: done
priority: medium
state_hub_task_id: "4a96e27b-9165-450c-899c-f7af484d9438"
```

Represent requested cross-reference links and table-of-contents entries before
renderer-specific numbering is known.

Output: manifest model and tests that keep final numbering outside core.

## P21.3 - Define static asset manifests

```task
id: MKTT-WP-0021-T003
status: done
priority: high
state_hub_task_id: "ba917e45-1912-4bdb-bf3f-5946c20957b2"
```

Define an asset manifest with:

- source URI/path
- media type and extension
- digest/checksum
- logical role
- copy policy declaration
- renderer output reference placeholder
- provenance back to source spans or source adapter attachments

Output: model, examples, and compatibility note for `MKTF-WP-0003`.

## P21.4 - Define source-to-render provenance maps

```task
id: MKTT-WP-0021-T004
status: done
priority: high
state_hub_task_id: "dd9f1128-af1e-44a8-961b-3aba6104ec9a"
```

Define a provenance envelope that maps Markitect source spans and generated
function outputs to renderer-source units and artifact references.

Output: source map model, fake-renderer fixture integration, and tests.

## P21.5 - Add docs and examples

```task
id: MKTT-WP-0021-T005
status: done
priority: medium
state_hub_task_id: "1d472c44-d970-4403-9f0b-18e6192da737"
```

Add examples showing render references and asset manifests without requiring a
real renderer.

Output: docs, examples, and extension catalog metadata if needed.

## Exit Criteria

- Render-aware references can be represented before renderer execution.
- Asset manifests are deterministic and provenance-preserving.
- Core Markitect does not perform asset copying or final layout numbering.
- `markitect-filter` attachment metadata can feed the manifest without making
  `markitect-filter` a renderer.