generated from coulomb/repo-seed
168 lines
4.5 KiB
Markdown
168 lines
4.5 KiB
Markdown
---
|
|
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.
|