markitect-tool/workplans/MKTT-WP-0015-render-and-document-function-extensions.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-0015	workplan	Render And Document Function Extensions	markitect	todo	markitect-tool	markitect	P2	130	MKTT-WP-0010 MKTT-WP-0011 MKTT-WP-0012	MKTT-WP-0007 MKTT-WP-0008 MKTT-WP-0009 MKTT-WP-0013	2026-05-04	2026-05-04	a38f676a-0d0b-493c-9792-2e34480c3681

MKTT-WP-0015: Render And Document Function Extensions

Purpose

Capture the natural follow-on work from the Quarkdown comparison and the first Markitect document-function layer.

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.

Background

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.

Markitect should not become a Quarkdown clone. The better fit is:

• 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

Decision

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.

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.

P15.1 - Typed document values and value mapping

id: MKTT-WP-0015-T001
status: todo
priority: high
state_hub_task_id: "995945c5-6cec-435c-8943-b8da0a9ff89d"

Define a typed value model for document functions:

• string, number, boolean, none
• Markdown content
• list and dictionary values
• 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.

Output: value model, mapper API, tests, and documentation.

P15.2 - Richer function syntax without losing Markdown compatibility

id: MKTT-WP-0015-T002
status: todo
priority: medium
state_hub_task_id: "bfce1388-e123-4e91-a5ab-ba67d21c22b8"

Evaluate syntax extensions that improve author ergonomics without turning Markitect into a full compiler language:

• 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

Output: syntax compatibility note, parser tests, and diagnostics examples.

P15.3 - Document-local reusable functions

id: MKTT-WP-0015-T003
status: todo
priority: medium
state_hub_task_id: "a8a8f017-3622-47f1-814e-0c71bd49a42f"

Explore document-local reusable functions as a constrained, contract-aware extension:

• named reusable snippets
• parameter lists and default values
• body arguments
• provenance for expansions
• validation against allowed function namespaces

Avoid general-purpose Turing-complete scripting in core. If assisted or external behavior is needed, route it through workflow steps and explicit capability gates.

Output: design proposal and one deterministic prototype if justified.

P15.4 - Quarkdown and render/export adapters

id: MKTT-WP-0015-T004
status: todo
priority: high
state_hub_task_id: "69e550a0-188b-4bc4-9658-47219b090904"

Design optional render/export adapters:

• 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
• keep direct code reuse license-safe
• track source to rendered-artifact provenance

Output: adapter interface, Quarkdown export sketch, policy model, and tests with deterministic fake renderers.

P15.5 - Render-aware references, numbering, and assets

id: MKTT-WP-0015-T005
status: todo
priority: high
state_hub_task_id: "53eb9f94-830b-4fdf-bb47-3f549048c82a"

Extend the reference model for rendered documents:

• 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

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.

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.