generated from coulomb/repo-seed
222 lines
6.8 KiB
Markdown
222 lines
6.8 KiB
Markdown
---
|
|
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.
|