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	Document Function Value Contracts	markitect	done	markitect-tool	markitect	complete	130	MKTT-WP-0010 MKTT-WP-0011 MKTT-WP-0012	MKTT-WP-0013 MKTT-WP-0020 MKTT-WP-0021 MKTF-WP-0003 MQD-WP-0001	2026-05-04	2026-05-15	a38f676a-0d0b-493c-9792-2e34480c3681

MKTT-WP-0015: Document Function Value Contracts

Purpose

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 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.

Split Decision - 2026-05-15

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.

The split is now:

• 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.

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.

Boundary

markitect-tool owns:

• 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

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

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

Define a small DocumentValue model for function results:

• string, number, boolean, and none
• Markdown content
• lists and dictionaries
• records and tables
• references and content units
• diagnostics-friendly unknown or dynamic values

The model should serialize cleanly and stay independent of renderer-specific objects.

Output: value dataclasses or schema objects, serialization helpers, tests, and documentation.

P15.2 - Add deterministic value mapping

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

Define how each DocumentValue maps to:

• inline Markdown
• block Markdown
• JSON/YAML API output
• diagnostic fallback text for unknown or dynamic values

Mapping must be deterministic, inspectable, and safe to use from mkt function render.

Output: mapper API, compatibility tests for existing function outputs, and diagnostics examples.

P15.3 - Validate function descriptor output contracts

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

Extend DocumentFunctionDescriptor output metadata so functions can declare their result type using the new value vocabulary.

Validation should catch:

• 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: descriptor updates, evaluator checks, diagnostics, and tests.

P15.4 - Pin syntax extension boundaries

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

Document which syntax improvements are still acceptable without replacing the current conservative parser:

• clearer escaping rules
• fenced block-body argument refinements
• line/span reporting improvements
• cycle and depth limits for current pipeline evaluation

Explicitly defer:

• 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

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

Update document-function docs, examples, and extension descriptor metadata to show typed outputs without advertising render/export behavior as core function execution.

Output: docs, examples, extension catalog assertions, and generated API/CLI reference updates if the public surface changes.

Exit Criteria

• 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.