---
id: MKTT-WP-0015
type: workplan
title: "Document Function Value Contracts"
domain: markitect
status: done
owner: markitect-tool
topic_slug: markitect
planning_priority: complete
planning_order: 130
depends_on_workplans:
  - MKTT-WP-0010
  - MKTT-WP-0011
  - MKTT-WP-0012
related_workplans:
  - MKTT-WP-0013
  - MKTT-WP-0020
  - MKTT-WP-0021
  - MKTF-WP-0003
  - MQD-WP-0001
created: "2026-05-04"
updated: "2026-05-15"
state_hub_workstream_id: "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

```task
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

```task
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

```task
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

```task
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

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