generated from coulomb/repo-seed
Complete memory graph and document value workplans
This commit is contained in:
@@ -1,222 +1,221 @@
|
||||
---
|
||||
id: MKTT-WP-0015
|
||||
type: workplan
|
||||
title: "Render And Document Function Extensions"
|
||||
title: "Document Function Value Contracts"
|
||||
domain: markitect
|
||||
status: todo
|
||||
status: done
|
||||
owner: markitect-tool
|
||||
topic_slug: markitect
|
||||
planning_priority: P2
|
||||
planning_priority: complete
|
||||
planning_order: 130
|
||||
depends_on_workplans:
|
||||
- MKTT-WP-0010
|
||||
- MKTT-WP-0011
|
||||
- MKTT-WP-0012
|
||||
related_workplans:
|
||||
- MKTT-WP-0007
|
||||
- MKTT-WP-0008
|
||||
- MKTT-WP-0009
|
||||
- MKTT-WP-0013
|
||||
- KONT-WP-0017
|
||||
- IB-WP-0017
|
||||
- MKTT-WP-0020
|
||||
- MKTT-WP-0021
|
||||
- MKTF-WP-0003
|
||||
- MQD-WP-0001
|
||||
created: "2026-05-04"
|
||||
updated: "2026-05-04"
|
||||
updated: "2026-05-15"
|
||||
state_hub_workstream_id: "a38f676a-0d0b-493c-9792-2e34480c3681"
|
||||
---
|
||||
|
||||
# MKTT-WP-0015: Render And Document Function Extensions
|
||||
# MKTT-WP-0015: Document Function Value Contracts
|
||||
|
||||
## Purpose
|
||||
|
||||
Capture the natural follow-on work from the Quarkdown comparison and the first
|
||||
Markitect document-function layer.
|
||||
Split the original render-and-function extension plan into a small,
|
||||
Markitect-native core slice: typed document-function values and deterministic
|
||||
value mapping.
|
||||
|
||||
The current function layer is intentionally small: deterministic functions,
|
||||
Markdown-native explicit syntax, local context variables, diagnostics,
|
||||
provenance, and capability metadata. This workplan should extend that model
|
||||
only when the need is concrete, keeping the core framework clean and avoiding a
|
||||
second workflow engine.
|
||||
The current document-function layer is intentionally small: deterministic
|
||||
functions, Markdown-native explicit syntax, local context variables,
|
||||
diagnostics, provenance, and capability metadata. This workplan should make
|
||||
function outputs more explicit without turning Markitect into a publishing
|
||||
language, renderer, or second workflow engine.
|
||||
|
||||
## Background
|
||||
## Split Decision - 2026-05-15
|
||||
|
||||
Quarkdown shows the value of a document language where functions are not just
|
||||
macros. They can return typed values, Markdown content, layout structures,
|
||||
tables, dictionaries, booleans, and renderable nodes. Its compiler expands
|
||||
function-call nodes, maps output values back to renderable nodes, and then
|
||||
continues through traversal, rendering, and post-rendering stages.
|
||||
The previous `MKTT-WP-0015` scope bundled typed values, syntax extensions,
|
||||
document-local reusable functions, render/export adapters, render-aware
|
||||
references/assets, and permission sandboxing. That was architecturally too
|
||||
large for one workplan.
|
||||
|
||||
Markitect should not become a Quarkdown clone. The better fit is:
|
||||
The split is now:
|
||||
|
||||
- keep Markitect as the contract, reference, processor, workflow, cache,
|
||||
provenance, and policy framework
|
||||
- make document functions an authoring surface over those primitives
|
||||
- add render/export behavior as optional extensions
|
||||
- use Quarkdown as an optional external publishing target where that is useful
|
||||
- `MKTT-WP-0015`: typed document-function value contracts in `markitect-tool`.
|
||||
- `MKTT-WP-0020`: render/export adapter contracts in `markitect-tool`.
|
||||
- `MKTT-WP-0021`: render reference and asset manifest contracts in
|
||||
`markitect-tool`.
|
||||
- `MQD-WP-0001`: concrete Quarkdown render adapter work in
|
||||
`markitect-quarkdown`.
|
||||
- `MKTF-WP-0003`: read-side source attachment and asset metadata compatibility
|
||||
in `markitect-filter`.
|
||||
|
||||
## Decision
|
||||
`markitect-filter` remains a source normalization repository. It should not own
|
||||
write/export adapters or renderer execution. Concrete Quarkdown invocation
|
||||
belongs in `markitect-quarkdown`; durable render jobs, publication state, and
|
||||
artifact storage belong outside `markitect-tool`.
|
||||
|
||||
Defer this work until after the current original successor work is stable,
|
||||
unless a concrete document publishing, render provenance, or function-language
|
||||
use case becomes urgent.
|
||||
## Boundary
|
||||
|
||||
When picked up, treat this as an extension workplan. It may evolve framework
|
||||
interfaces, but should not make Quarkdown, flex-auth, network access, live LLM
|
||||
calls, filesystem writes, or external processes required for deterministic
|
||||
Markitect parsing and function validation.
|
||||
`markitect-tool` owns:
|
||||
|
||||
Boundary clarification: `markitect-tool` owns typed value contracts,
|
||||
Markdown-compatible function syntax, render/export adapter interfaces,
|
||||
provenance envelopes, diagnostics, and deterministic fake renderers. It does
|
||||
not own durable rendered artifact storage, publication workflows, enterprise
|
||||
authorization, real renderer operations, or concrete application reports. Those
|
||||
belong in `kontextual-engine`, optional renderer packages, or
|
||||
`infospace-bench` application workflows.
|
||||
- typed document value contracts
|
||||
- value-to-Markdown and value-to-JSON mapping
|
||||
- function descriptor output validation
|
||||
- deterministic diagnostics and provenance for value coercion
|
||||
- compatibility notes for future syntax extensions
|
||||
|
||||
## P15.1 - Typed document values and value mapping
|
||||
`markitect-tool` does not own in this workplan:
|
||||
|
||||
- nested function expression parsing
|
||||
- document-local reusable functions
|
||||
- render/export adapter execution
|
||||
- Quarkdown invocation
|
||||
- filesystem-writing render jobs
|
||||
- publication lifecycle or durable artifact storage
|
||||
- concrete source-format filtering
|
||||
|
||||
## Implementation Summary - 2026-05-15
|
||||
|
||||
Implemented the narrowed value-contract slice:
|
||||
|
||||
- `DocumentValue` and `DOCUMENT_VALUE_KINDS`.
|
||||
- Deterministic coercion and Markdown/JSON mapping helpers:
|
||||
`coerce_document_value`, `format_document_value`, and
|
||||
`document_value_to_json`.
|
||||
- `DocumentFunctionRun.value` while preserving the legacy raw `output` field.
|
||||
- Descriptor `output_type` validation for string, markdown, dynamic, table,
|
||||
record, reference, content unit, and related value kinds.
|
||||
- Diagnostics for output type mismatches and reference/content-unit values that
|
||||
lack provenance.
|
||||
- Conservative pipeline depth limit without adding nested function syntax.
|
||||
- Docs, examples, API exports, extension descriptor metadata, and tests.
|
||||
|
||||
Render/export contracts remain in `MKTT-WP-0020`; render references and asset
|
||||
manifests remain in `MKTT-WP-0021`; concrete Quarkdown execution remains in
|
||||
`MQD-WP-0001`; read-side source attachment metadata remains in `MKTF-WP-0003`.
|
||||
|
||||
## P15.1 - Define typed document values
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0015-T001
|
||||
status: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "995945c5-6cec-435c-8943-b8da0a9ff89d"
|
||||
```
|
||||
|
||||
Define a typed value model for document functions:
|
||||
Define a small `DocumentValue` model for function results:
|
||||
|
||||
- string, number, boolean, none
|
||||
- string, number, boolean, and none
|
||||
- Markdown content
|
||||
- list and dictionary values
|
||||
- lists and dictionaries
|
||||
- records and tables
|
||||
- references and content units
|
||||
- tables and records
|
||||
- diagnostics-friendly unknown or dynamic values
|
||||
|
||||
Define how each value maps back to Markdown or structured output. Keep the
|
||||
mapper deterministic and inspectable.
|
||||
The model should serialize cleanly and stay independent of renderer-specific
|
||||
objects.
|
||||
|
||||
Output: value model, mapper API, tests, and documentation.
|
||||
Output: value dataclasses or schema objects, serialization helpers, tests, and
|
||||
documentation.
|
||||
|
||||
## P15.2 - Richer function syntax without losing Markdown compatibility
|
||||
## P15.2 - Add deterministic value mapping
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0015-T002
|
||||
status: todo
|
||||
priority: medium
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "bfce1388-e123-4e91-a5ab-ba67d21c22b8"
|
||||
```
|
||||
|
||||
Evaluate syntax extensions that improve author ergonomics without turning
|
||||
Markitect into a full compiler language:
|
||||
Define how each `DocumentValue` maps to:
|
||||
|
||||
- multiline argument continuation
|
||||
- nested function expressions
|
||||
- clearer escaping rules
|
||||
- block-body argument refinements
|
||||
- source spans beyond line numbers
|
||||
- cycle and depth limits for nested calls
|
||||
- inline Markdown
|
||||
- block Markdown
|
||||
- JSON/YAML API output
|
||||
- diagnostic fallback text for unknown or dynamic values
|
||||
|
||||
Output: syntax compatibility note, parser tests, and diagnostics examples.
|
||||
Mapping must be deterministic, inspectable, and safe to use from
|
||||
`mkt function render`.
|
||||
|
||||
## P15.3 - Document-local reusable functions
|
||||
Output: mapper API, compatibility tests for existing function outputs, and
|
||||
diagnostics examples.
|
||||
|
||||
## P15.3 - Validate function descriptor output contracts
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0015-T003
|
||||
status: todo
|
||||
priority: medium
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "a8a8f017-3622-47f1-814e-0c71bd49a42f"
|
||||
```
|
||||
|
||||
Explore document-local reusable functions as a constrained, contract-aware
|
||||
extension:
|
||||
Extend `DocumentFunctionDescriptor` output metadata so functions can declare
|
||||
their result type using the new value vocabulary.
|
||||
|
||||
- named reusable snippets
|
||||
- parameter lists and default values
|
||||
- body arguments
|
||||
- provenance for expansions
|
||||
- validation against allowed function namespaces
|
||||
Validation should catch:
|
||||
|
||||
Avoid general-purpose Turing-complete scripting in core. If assisted or
|
||||
external behavior is needed, route it through workflow steps and explicit
|
||||
capability gates.
|
||||
- declared output type mismatches
|
||||
- values that cannot be mapped to Markdown in the requested context
|
||||
- unstable or dynamic values in deterministic contexts
|
||||
- missing provenance for reference/content-unit values
|
||||
|
||||
Output: design proposal and one deterministic prototype if justified.
|
||||
Output: descriptor updates, evaluator checks, diagnostics, and tests.
|
||||
|
||||
## P15.4 - Quarkdown and render/export adapters
|
||||
## P15.4 - Pin syntax extension boundaries
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0015-T004
|
||||
status: todo
|
||||
priority: high
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "69e550a0-188b-4bc4-9658-47219b090904"
|
||||
```
|
||||
|
||||
Design optional render/export adapter contracts:
|
||||
Document which syntax improvements are still acceptable without replacing the
|
||||
current conservative parser:
|
||||
|
||||
- emit Quarkdown source from Markitect references, processors, templates, and
|
||||
function calls
|
||||
- support output profiles such as plain, docs, slides, paged, and static site
|
||||
- invoke external renderers only through declared capabilities and fake
|
||||
deterministic test adapters in this repo
|
||||
- keep direct code reuse license-safe
|
||||
- track source to rendered-artifact provenance
|
||||
- clearer escaping rules
|
||||
- fenced block-body argument refinements
|
||||
- line/span reporting improvements
|
||||
- cycle and depth limits for current pipeline evaluation
|
||||
|
||||
Output: adapter interface, Quarkdown export sketch, local policy model, and
|
||||
tests with deterministic fake renderers. Durable render jobs, stored artifacts,
|
||||
publication state, and application-specific reports are out of scope here.
|
||||
Explicitly defer:
|
||||
|
||||
## P15.5 - Render-aware references, numbering, and assets
|
||||
- nested function expressions
|
||||
- document-local function definitions
|
||||
- conditionals, loops, lambdas, or Turing-complete scripting
|
||||
- Quarkdown syntax compatibility as a core parser requirement
|
||||
|
||||
Output: syntax compatibility note and parser diagnostics tests for the retained
|
||||
scope.
|
||||
|
||||
## P15.5 - Update examples and extension descriptor metadata
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0015-T005
|
||||
status: todo
|
||||
priority: high
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "53eb9f94-830b-4fdf-bb47-3f549048c82a"
|
||||
```
|
||||
|
||||
Extend the reference model for rendered documents:
|
||||
Update document-function docs, examples, and extension descriptor metadata to
|
||||
show typed outputs without advertising render/export behavior as core function
|
||||
execution.
|
||||
|
||||
- figures, tables, equations, code blocks, and custom numbered units
|
||||
- generated table of contents and cross-reference links
|
||||
- static asset manifests
|
||||
- media checksums and copy policies
|
||||
- root output asset references
|
||||
|
||||
Output: reference/asset manifest model and docs with examples.
|
||||
|
||||
## P15.6 - Permission sandbox for non-core functions
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0015-T006
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "9ef2c516-2cd0-40ba-b270-abefbfd8fc40"
|
||||
```
|
||||
|
||||
Add explicit local permission gates for functions that need:
|
||||
|
||||
- filesystem reads or writes
|
||||
- network access
|
||||
- external processes
|
||||
- native content inclusion
|
||||
- assisted generation
|
||||
- render/export side effects
|
||||
|
||||
Use Markitect-local policy contracts first. flex-auth, OpenFGA, OPA, Cedar,
|
||||
Keycloak, Entra, or similar systems may be optional adapters, but must not be
|
||||
required for deterministic function parsing, validation, and rendering of pure
|
||||
functions.
|
||||
|
||||
Output: permission vocabulary, denied-operation diagnostics, and policy tests.
|
||||
This is a syntax-layer capability contract, not a durable authorization service
|
||||
or audit system.
|
||||
Output: docs, examples, extension catalog assertions, and generated API/CLI
|
||||
reference updates if the public surface changes.
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
- Core deterministic document functions remain simple and dependency-light.
|
||||
- Richer functions are optional extensions with declared capabilities.
|
||||
- Render/export adapters can be tested without live external services.
|
||||
- Quarkdown interoperability is conceptually supported without direct code
|
||||
dependency.
|
||||
- Typed values, render provenance, references, and assets have clear contracts.
|
||||
- The extension does not duplicate the dataflow workflow engine.
|
||||
- Durable render operations, publication lifecycle, and enterprise policy
|
||||
enforcement remain outside `markitect-tool`.
|
||||
- Core deterministic document functions remain dependency-light.
|
||||
- Function outputs use explicit typed value contracts.
|
||||
- Existing Markdown rendering behavior remains compatible.
|
||||
- Renderer-specific objects and Quarkdown invocation are outside this
|
||||
workplan.
|
||||
- Richer syntax and reusable local functions are deferred until a concrete use
|
||||
case justifies a parser/evaluator redesign.
|
||||
|
||||
@@ -3,7 +3,7 @@ id: MKTT-WP-0016
|
||||
type: workplan
|
||||
title: "Memory Graph Profile Contract And Context Package Compiler"
|
||||
domain: markitect
|
||||
status: active
|
||||
status: done
|
||||
owner: markitect-tool
|
||||
topic_slug: markitect
|
||||
planning_priority: P2
|
||||
@@ -119,9 +119,16 @@ mkt memory graph pack <selection-file>
|
||||
```
|
||||
|
||||
Examples and documentation now live in `docs/memory-graph-contract.md` and
|
||||
`examples/memory/*graph*.yaml`. The remaining refinement is fixture breadth:
|
||||
add invalid fixtures and richer conversation/knowledge examples before closing
|
||||
the workplan fully.
|
||||
`examples/memory/`. The fixture catalog now covers reasoning decision graphs,
|
||||
conversation paths, knowledge neighborhoods, mixed profiles, invalid graph and
|
||||
profile examples, and non-executing runtime adapter handoff descriptors.
|
||||
|
||||
## Closure Update - 2026-05-15
|
||||
|
||||
This workplan is complete. The final pass added deterministic conversation and
|
||||
knowledge fixtures, invalid validation fixtures, a runtime adapter boundary
|
||||
catalog, extension descriptor coverage, and tests that compile the valid graph
|
||||
selections into `ContextPackage` objects.
|
||||
|
||||
## Out Of Scope
|
||||
|
||||
@@ -216,7 +223,7 @@ retention, compaction, latency, or policy decisions.
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0016-T004
|
||||
status: in_progress
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "afcd7ce9-e657-4779-b3b2-0ae3f8e2d66e"
|
||||
```
|
||||
@@ -286,7 +293,7 @@ Output: CLI commands, docs, and tests.
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0016-T007
|
||||
status: in_progress
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "ff78d449-0738-4f1b-a018-2efed3d8e878"
|
||||
```
|
||||
|
||||
174
workplans/MKTT-WP-0020-render-export-adapter-contract.md
Normal file
174
workplans/MKTT-WP-0020-render-export-adapter-contract.md
Normal file
@@ -0,0 +1,174 @@
|
||||
---
|
||||
id: MKTT-WP-0020
|
||||
type: workplan
|
||||
title: "Render Export Adapter Contract"
|
||||
domain: markitect
|
||||
status: todo
|
||||
owner: markitect-tool
|
||||
topic_slug: markitect
|
||||
planning_priority: P2
|
||||
planning_order: 150
|
||||
depends_on_workplans:
|
||||
- MKTT-WP-0013
|
||||
- MKTT-WP-0015
|
||||
related_workplans:
|
||||
- MKTT-WP-0018
|
||||
- MKTT-WP-0021
|
||||
- MQD-WP-0001
|
||||
created: "2026-05-15"
|
||||
updated: "2026-05-15"
|
||||
state_hub_workstream_id: "19d1a377-848a-4156-b712-7b9febd836a6"
|
||||
---
|
||||
|
||||
# MKTT-WP-0020: Render Export Adapter Contract
|
||||
|
||||
## Purpose
|
||||
|
||||
Define the `markitect-tool` contract for optional render/export adapters
|
||||
without implementing real renderer operations in the core toolkit.
|
||||
|
||||
This is the output-side sibling of the source adapter contract. Source
|
||||
adapters normalize input formats into canonical Markdown; render/export
|
||||
adapters transform Markitect-compatible Markdown into rendered artifacts or
|
||||
renderer-specific sources. The two directions must stay separate now that
|
||||
`markitect-filter` owns concrete source normalization.
|
||||
|
||||
## Boundary
|
||||
|
||||
`markitect-tool` owns:
|
||||
|
||||
- render/export request and result envelopes
|
||||
- adapter descriptors and extension catalog metadata
|
||||
- declared output profiles such as plain, docs, slides, paged, static site,
|
||||
and PDF
|
||||
- deterministic fake renderers for tests
|
||||
- diagnostics, provenance, source maps, and capability declarations
|
||||
|
||||
`markitect-tool` does not own:
|
||||
|
||||
- Quarkdown CLI invocation
|
||||
- Pandoc, browser, PDF, or static-site generator execution
|
||||
- filesystem-writing publication jobs beyond test fixtures
|
||||
- durable artifact storage
|
||||
- renderer-specific dependency installation
|
||||
- concrete application reports
|
||||
|
||||
Concrete Quarkdown integration belongs in `markitect-quarkdown`.
|
||||
|
||||
## P20.1 - Define render adapter descriptors
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0020-T001
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "5b52b196-a7f5-4e4f-abc6-972febdc2638"
|
||||
```
|
||||
|
||||
Define a `RenderExportAdapterDescriptor` shape that mirrors the source adapter
|
||||
descriptor style while remaining output-oriented.
|
||||
|
||||
Descriptor fields should include:
|
||||
|
||||
- stable adapter id
|
||||
- version and human-readable name
|
||||
- operations such as `export-source`, `render-artifact`, and `inspect-profile`
|
||||
- supported input contracts
|
||||
- output profiles and artifact media types
|
||||
- option schema
|
||||
- optional dependencies
|
||||
- safety and capability metadata
|
||||
- docs/examples links
|
||||
|
||||
Output: descriptor dataclass or schema, extension descriptor mapping, and
|
||||
registry tests.
|
||||
|
||||
## P20.2 - Define render request and result envelopes
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0020-T002
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "3d43b168-7e55-4885-ae17-fcea262f2641"
|
||||
```
|
||||
|
||||
Define service-free request/result types:
|
||||
|
||||
- `RenderExportRequest`
|
||||
- `RenderExportResult`
|
||||
- `RenderArtifact`
|
||||
- `RenderDiagnostic`
|
||||
- `RenderProvenance`
|
||||
|
||||
Results should describe artifacts and source maps without requiring durable
|
||||
artifact storage.
|
||||
|
||||
Output: serializable models, round-trip tests, and docs.
|
||||
|
||||
## P20.3 - Add deterministic fake renderer fixtures
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0020-T003
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "45748ad7-131c-4b75-9720-6958fde93208"
|
||||
```
|
||||
|
||||
Add an in-tree fake renderer that proves the contract without invoking
|
||||
Quarkdown or any external process.
|
||||
|
||||
The fake renderer should support:
|
||||
|
||||
- profile inspection
|
||||
- source export into deterministic text
|
||||
- artifact metadata emission
|
||||
- source-to-render provenance
|
||||
- denied-operation diagnostics for disabled capabilities
|
||||
|
||||
Output: fake adapter, tests, and examples.
|
||||
|
||||
## P20.4 - Define capability and policy gates
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0020-T004
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "50aa8f00-eeba-495d-9d45-089f855fc3bd"
|
||||
```
|
||||
|
||||
Pin a local capability vocabulary for render/export adapters:
|
||||
|
||||
- filesystem read
|
||||
- filesystem write
|
||||
- external process
|
||||
- network
|
||||
- native renderer dependency
|
||||
- assisted generation
|
||||
- publication side effect
|
||||
|
||||
This is a syntax-layer contract and local denial model, not a durable
|
||||
authorization service.
|
||||
|
||||
Output: capability constants, blocked-operation diagnostics, and tests.
|
||||
|
||||
## P20.5 - Document Quarkdown handoff
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0020-T005
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "173a75d0-d82c-4dcb-9ced-eb73e9438db2"
|
||||
```
|
||||
|
||||
Document how `markitect-quarkdown` should implement a concrete Quarkdown
|
||||
adapter against this contract.
|
||||
|
||||
Output: handoff note linking `MQD-WP-0001`, example descriptor metadata, and
|
||||
no direct Quarkdown dependency in `markitect-tool`.
|
||||
|
||||
## Exit Criteria
|
||||
|
||||
- Render/export adapters are discoverable through the extension framework.
|
||||
- Contract tests pass with a fake deterministic renderer.
|
||||
- Core Markitect remains usable without renderer dependencies.
|
||||
- `markitect-filter` remains read-side only.
|
||||
- Quarkdown interop is supported by contract, not by core dependency.
|
||||
147
workplans/MKTT-WP-0021-render-reference-asset-manifest.md
Normal file
147
workplans/MKTT-WP-0021-render-reference-asset-manifest.md
Normal file
@@ -0,0 +1,147 @@
|
||||
---
|
||||
id: MKTT-WP-0021
|
||||
type: workplan
|
||||
title: "Render Reference And Asset Manifest Contract"
|
||||
domain: markitect
|
||||
status: todo
|
||||
owner: markitect-tool
|
||||
topic_slug: markitect
|
||||
planning_priority: P2
|
||||
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.
|
||||
|
||||
## P21.1 - Define render unit references
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0021-T001
|
||||
status: todo
|
||||
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: todo
|
||||
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: todo
|
||||
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: todo
|
||||
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: todo
|
||||
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.
|
||||
Reference in New Issue
Block a user