Add render reference asset manifest contract

docs/api-reference.md

@@ -13,9 +13,13 @@ 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_ASSET_COPY_POLICIES` - object. set() -> new empty set object
 - `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
+- `RENDER_REFERENCE_MANIFEST_KIND` - object. str(object='') -> str
+- `RENDER_REFERENCE_SCHEMA_VERSION` - object. str(object='') -> str
+- `RENDER_UNIT_KINDS` - object. set() -> new empty set object
 - `SOURCE_ADAPTER_ENTRY_POINT_GROUP` - object. str(object='') -> str
 
 ## `markitect_tool.backend.engine`
@@ -317,17 +321,31 @@ Generated from `markitect_tool.__all__`.
 
 - `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.
+- `RenderAsset(asset_id: 'str' = '', source_uri: 'str | None' = None, source_path: 'str | None' = None, name: 'str | None' = None, media_type: 'str | None' = None, extension: 'str | None' = None, digest: 'str | None' = None, role: 'str' = 'asset', copy_policy: 'str' = 'copy', output_reference: 'str | None' = None, provenance: 'list[RenderAssetProvenance]' = <factory>, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Static asset descriptor with declared renderer copy behavior.
+- `RenderAssetManifest(manifest_id: 'str' = '', assets: 'list[RenderAsset]' = <factory>, source_path: 'str | None' = None, source_digest: 'str | None' = None, schema_version: 'str' = 'markitect.render.reference.v1', metadata: 'dict[str, Any]' = <factory>) -> None` - class. Deterministic list of static assets requested by renderer source.
+- `RenderAssetProvenance(source_uri: 'str | None' = None, source_path: 'str | None' = None, source_href: 'str | None' = None, package_path: 'str | None' = None, attachment_id: 'str | None' = None, source_adapter_id: 'str | None' = None, source_span: 'RenderSourceSpan | None' = None, digest: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Provenance for an asset manifest entry.
+- `RenderCrossReference(target_unit_id: 'str', reference_id: 'str' = '', source_unit_id: 'str | None' = None, source_span: 'RenderSourceSpan | None' = None, label: 'str | None' = None, requested_style: 'str' = 'numbered', fallback_text: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Requested cross-reference link before renderer-specific numbering exists.
 - `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.
+- `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>, render_manifest: 'RenderReferenceManifest | dict[str, Any] | None' = None, 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.
+- `RenderReferenceError` - class. Raised when render reference or asset manifest contracts are invalid.
+- `RenderReferenceManifest(manifest_id: 'str' = '', units: 'list[RenderUnitReference]' = <factory>, cross_references: 'list[RenderCrossReference]' = <factory>, toc: 'list[RenderTocEntry]' = <factory>, asset_manifest: 'RenderAssetManifest' = <factory>, source_maps: 'list[RenderSourceMap]' = <factory>, source_path: 'str | None' = None, source_digest: 'str | None' = None, schema_version: 'str' = 'markitect.render.reference.v1', metadata: 'dict[str, Any]' = <factory>) -> None` - class. Passive render structure, cross-reference, asset, and provenance manifest.
+- `RenderSourceMap(map_id: 'str' = '', source: 'RenderSourceSpan | None' = None, source_unit_id: 'str | None' = None, generated_by: 'str | None' = None, function_run_id: 'str | None' = None, render_unit_id: 'str | None' = None, artifact_id: 'str | None' = None, artifact_ref: 'str | None' = None, role: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Trace from Markitect source/generated output to renderer units or artifacts.
+- `RenderSourceSpan(source_path: 'str | None' = None, line_start: 'int | None' = None, line_end: 'int | None' = None, selector: 'str | None' = None, source_unit_id: 'str | None' = None, content_hash: 'str | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Source location for a render unit, asset, or source-map edge.
+- `RenderTocEntry(unit_id: 'str', title: 'str', level: 'int', entry_id: 'str' = '', parent_id: 'str | None' = None, order: 'int | None' = None, source_span: 'RenderSourceSpan | None' = None, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Table-of-contents planning entry before final renderer links exist.
+- `RenderUnitReference(unit_id: 'str' = '', kind: 'str' = 'custom', label: 'str | None' = None, title: 'str | None' = None, caption: 'str | None' = None, source_path: 'str | None' = None, anchor: 'str | None' = None, source_span: 'RenderSourceSpan | None' = None, content_hash: 'str | None' = None, ordinal_hint: 'int | None' = None, numbering: 'dict[str, Any]' = <factory>, metadata: 'dict[str, Any]' = <factory>) -> None` - class. Stable identity for one renderable unit before final renderer numbering.
 - `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_asset_id(source: 'str', *, digest: 'str | None' = None, role: 'str | None' = None, output_reference: 'str | None' = None) -> 'str'` - function. Return a deterministic asset id without copying or reading the asset.
 - `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_manifest_id(manifest: 'RenderReferenceManifest | dict[str, Any]') -> 'str'` - function. Return the deterministic id for a render reference manifest-like object.
+- `render_reference_manifest_descriptor() -> 'ExtensionDescriptor'` - function. Descriptor for passive render reference and asset manifest contracts.
+- `render_unit_id(kind: 'str', *, source_path: 'str | None' = None, anchor: 'str | None' = None, content_hash: 'str | None' = None, ordinal_hint: 'int | None' = None, title: 'str | None' = None) -> 'str'` - function. Return a deterministic render unit id for passive reference manifests.
 - `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`

docs/examples-index.md

@@ -42,6 +42,7 @@ This index maps example files to practical usecases and useful commands.
 | 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 |
+| `examples/render/render-reference-manifest.yaml` | Render unit, cross-reference, TOC, asset, and source-map manifest fixture | Load with `RenderReferenceManifest.from_dict`; no renderer or asset copying required |
 
 ## Cache, Backend, Policy, And Context
 

docs/internal-extension-framework.md

@@ -42,6 +42,7 @@ framework organizes how Markitect itself exposes and composes capabilities.
 | `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` | Quarkdown/export adapters | Markdown source in, rendered/exported artifact descriptor out |
+| `render-reference-contract` | render units, cross-references, TOC, asset manifests | passive manifest in, renderer-planning metadata out |
 | `document-function` | future function layer | function call in, typed document value out |
 
 ## Canonical Lifecycle
@@ -172,8 +173,10 @@ Each module exposes one or more descriptors plus a registration function. The
 root registry can be assembled explicitly at import time or by a small internal
 discovery list. Source adapters are the first external package-discovery slice
 and use the `markitect_tool.source_adapters` entry point group defined in
-`docs/source-adapter-contract.md`; other extension kinds can adopt package
-entry points later if they become a real requirement.
+`docs/source-adapter-contract.md`. Render/export adapters use
+`markitect_tool.render_export_adapters` and keep concrete renderer execution in
+external packages. Render reference and asset manifests remain built-in passive
+contracts; they do not need adapter discovery.
 
 See `docs/extension-authoring.md` for the extension authoring checklist and
 descriptor template.

docs/render-export-adapters.md

@@ -56,6 +56,12 @@ identity, options, and local policy flags.
 - 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.
 

docs/render-reference-asset-manifest.md

@@ -0,0 +1,96 @@
+# Render Reference And Asset Manifest Contract
+
+Markitect models render-aware structure before an optional renderer runs. The
+contract is passive: it records units, requested references, static assets, and
+source maps, but it does not assign final numbering, rewrite links, copy
+assets, or validate renderer output directories.
+
+## Contract Version
+
+- `markitect.render.reference.v1`
+
+The manifest kind is:
+
+```text
+render-reference-manifest
+```
+
+## Render Units
+
+`RenderUnitReference` gives a stable identity to renderable content:
+
+| Unit kind | Typical use |
+| --- | --- |
+| `section` | Headings and TOC entries. |
+| `figure` | Images, charts, diagrams, and captions. |
+| `table` | Markdown or generated tables. |
+| `equation` | Math blocks or equation-like units. |
+| `code-block` | Numbered or referenced code listings. |
+| `custom` | Project-defined numbered units. |
+
+The unit model may carry labels, captions, anchors, source spans, content
+hashes, and numbering intent such as scope or sequence. It intentionally does
+not carry final numbers.
+
+## Cross-References And TOC Planning
+
+`RenderCrossReference` represents a requested link from one source location to
+a target render unit. It records the target unit and requested style, while the
+renderer decides final label text, numbering, and URL rewriting.
+
+`RenderTocEntry` records planned table-of-contents entries by unit id, title,
+level, parent id, and order. The renderer owns final page numbers and links.
+
+## Static Assets
+
+`RenderAssetManifest` is a deterministic list of static assets referenced by
+renderer source. Each `RenderAsset` records:
+
+- source URI or source path
+- name, media type, and extension
+- digest when available
+- logical role
+- copy policy declaration
+- renderer output reference placeholder
+- provenance back to source spans or source adapter attachments
+
+Supported copy policies are `copy`, `embed`, `link`, `preserve`, and `skip`.
+They are declarations for downstream renderers. Core Markitect never copies the
+asset.
+
+`markitect-filter` may provide read-side attachment metadata, such as source
+URI, path, media type, extension, digest, and attachment provenance. Markitect
+can transform that metadata into a render asset entry without making
+`markitect-filter` responsible for rendering.
+
+## Source Maps
+
+`RenderSourceMap` connects Markitect source spans or generated function outputs
+to renderer units and artifact references. This is the bridge from deterministic
+Markdown processing to renderer-owned artifacts:
+
+```text
+source span / function output -> render unit -> renderer source or artifact
+```
+
+The map can reference a Markitect source unit, a document function run, a
+render unit id, an artifact id, or a renderer-owned artifact reference.
+
+## Fake Renderer Integration
+
+`RenderExportRequest` accepts an optional `render_manifest`. The built-in
+`render.fake` adapter echoes the manifest id, asset manifest id, unit counts,
+cross-reference count, TOC count, source-map count, and asset count into result
+and artifact metadata. It still performs no external rendering and has no
+filesystem or network side effects.
+
+See `examples/render/render-reference-manifest.yaml` for a complete manifest
+fixture.
+
+## Repository Boundary
+
+- `markitect-tool` owns these passive contracts and fake-renderer metadata
+  integration.
+- `markitect-filter` owns read-side source asset and attachment metadata.
+- `markitect-quarkdown` owns concrete Quarkdown execution, final numbering,
+  output paths, link rewriting, asset copying, and artifact validation.

docs/workplan-planning-map.md

@@ -47,7 +47,7 @@ and descriptions mirror the operational view.
 | `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. |
+| `MKTT-WP-0021` | complete | done | `MKTT-WP-0010`, `MKTT-WP-0015`, `MKTT-WP-0020` | Render reference and asset manifest contract is complete: passive render unit identities, cross-reference/TOC planning, deterministic asset manifests, source maps, fake-renderer metadata integration, docs, examples, and tests. |
 
 ## Dependency Notes