markitect-tool/workplans/MKTT-WP-0021-render-reference-asset-manifest.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-0021	workplan	Render Reference And Asset Manifest Contract	markitect	done	markitect-tool	markitect	complete	155	MKTT-WP-0010 MKTT-WP-0015 MKTT-WP-0020	MKTT-WP-0018 MKTF-WP-0003 MQD-WP-0001	2026-05-15	2026-05-15	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

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

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

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

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

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.