markitect-tool/workplans/MKTT-WP-0012-document-function-layer.md

---
id: MKTT-WP-0012
type: workplan
title: "Document Function Layer"
domain: markitect
status: todo
owner: markitect-tool
topic_slug: markitect
planning_priority: P3
planning_order: 85
depends_on_workplans:
  - MKTT-WP-0004
  - MKTT-WP-0010
  - MKTT-WP-0011
related_workplans:
  - MKTT-WP-0005
  - MKTT-WP-0006
  - MKTT-WP-0007
  - MKTT-WP-0009
created: "2026-05-04"
updated: "2026-05-04"
state_hub_workstream_id: "f82e74c4-d349-4e9e-80cd-10c0c6d9545d"
---

# MKTT-WP-0012: Document Function Layer

## Purpose

Design and implement an optional document function layer inspired by
Quarkdown's rich function language, while keeping Markitect markdown-native,
contract-aware, provenance-rich, and extension-oriented.

This layer should let authors and agents express reusable document operations
as named functions over Markdown content, structured data, references,
processors, contracts, workflows, and eventually assisted generation.

## Background

Quarkdown demonstrates that document authoring can benefit from a compact
function language with:

- dot-style function calls
- positional and named arguments
- block-body arguments that remain readable in Markdown
- nested and chained calls
- variables and scoped bindings
- conditionals, loops, lambdas, and table/data operations
- rendering-aware helpers for layout, numbering, references, and document setup

For Markitect, the useful idea is not to clone Quarkdown syntax or compiler
behavior. The useful idea is a disciplined function abstraction:

```text
document function = named operation + declared inputs + Markdown-friendly body
                    + output type + capability/policy metadata
                    + provenance + diagnostics
```

The layer should sit above existing primitives rather than replace them:
contracts define expectations, references identify content, processors perform
deterministic transformations, workflows orchestrate dataflow, backend fabric
tracks identity/provenance, and access policy gates risky operations.

## Decision

Do not implement this until the deterministic workflow layer has enough shape
to show real author pressure. Treat it as a future extension track that can
unify processor ergonomics, workflow steps, contract-aware generation, and
render/export adapters.

Recommended sequencing:

1. Finish or substantially shape `MKTT-WP-0011`.
2. Use practical workflow examples to identify recurring author-facing step
   patterns.
3. Define the function model as a thin authoring surface over those primitives.
4. Add assisted and unsafe functions only after capability/policy metadata is
   enforced.

## P12.1 - Define function model and vocabulary

```task
id: MKTT-WP-0012-T001
status: todo
priority: high
state_hub_task_id: "13ddfdbb-8fc1-4570-915d-038d40d489e1"
```

Define a document function descriptor with:

- stable function id and namespace
- summary and documentation fields
- positional and named parameters
- optional/default parameter behavior
- block-body parameter semantics
- accepted input types and output type
- deterministic/assisted/external execution kind
- capability requirements
- provenance and diagnostic contract

Output: design note, schema, and small examples.

## P12.2 - Design Markdown-native call syntax

```task
id: MKTT-WP-0012-T002
status: todo
priority: high
state_hub_task_id: "58166792-457a-4844-96a7-27baf50c1d7e"
```

Evaluate a conservative syntax that stays close to Markdown and does not break
CommonMark documents accidentally.

The design should consider:

- inline calls
- block calls with indented body content
- named arguments
- multiline arguments
- escaping/literal behavior
- fenced-block alternatives
- namespace-qualified function names
- diagnostics for ambiguous parses

Output: syntax proposal with accepted/rejected examples and parser impact.

## P12.3 - Add function registry and adapter boundary

```task
id: MKTT-WP-0012-T003
status: todo
priority: high
state_hub_task_id: "06196bde-cc10-464e-9d1a-6b8acc616c06"
```

Create a registry that can expose existing Markitect capabilities as functions
without moving their core implementation:

- reference resolution
- selectors and extraction
- deterministic processors
- template rendering
- contract validation
- workflow steps
- render/export adapters

Output: registry API, adapter protocol, and tests with fake functions.

## P12.4 - Implement pure deterministic function execution

```task
id: MKTT-WP-0012-T004
status: todo
priority: high
state_hub_task_id: "986121f0-f824-46eb-af59-65ebf2389f34"
```

Implement an evaluator for pure deterministic functions only.

It should produce:

- expanded Markdown or structured values
- source spans and provenance envelopes
- typed diagnostics
- cycle/depth limits
- stable execution traces for caching and test fixtures

Output: minimal evaluator and CLI/library tests.

## P12.5 - Add chaining and data binding semantics

```task
id: MKTT-WP-0012-T005
status: todo
priority: medium
state_hub_task_id: "94bb131c-cb4e-4391-8453-bb9de4f3834c"
```

Explore pipeline-style chaining where the previous result becomes the first
argument of the next function, plus explicit bindings to workflow data products.

This should integrate with `MKTT-WP-0011` expressions rather than create a
second unrelated expression system.

Output: chaining rules, data binding rules, and diagnostic examples.

## P12.6 - Add contract-aware function validation

```task
id: MKTT-WP-0012-T006
status: todo
priority: medium
state_hub_task_id: "899d361f-8eaa-4098-97d9-0fd33afc3304"
```

Allow contracts to declare which functions are permitted, expected, deprecated,
or forbidden in a document or workflow.

Validation should cover:

- unknown functions
- wrong arity or argument names
- wrong input/output type
- unsafe capability use
- missing required provenance
- unstable assisted functions in deterministic contexts

Output: contract integration and actionable diagnostics.

## P12.7 - Define capability and policy gates

```task
id: MKTT-WP-0012-T007
status: todo
priority: medium
state_hub_task_id: "2a51b42c-b46b-42cd-ba33-ab504100e653"
```

Integrate with the access-control and backend capability vocabulary before any
function can read files, access network resources, invoke external processes, or
call assisted-generation adapters.

Output: permission model, blocked-operation diagnostics, and policy examples.

## P12.8 - Add author-facing examples

```task
id: MKTT-WP-0012-T008
status: todo
priority: medium
state_hub_task_id: "30358902-5564-48a2-b1e3-e400bfbe7d1a"
```

Create examples that show practical value:

- reusable document components
- contract-aware report sections
- Markdown table filtering/summarization
- reference-driven transclusion
- processor pipelines expressed as function chains
- Quarkdown export preparation without taking a dependency on Quarkdown

Output: examples and comparison notes against Quarkdown-inspired patterns.

## Exit Criteria

- The function layer is optional and does not disturb existing Markdown parsing
  or deterministic processors.
- Functions are discoverable, typed enough for diagnostics, and namespace-aware.
- Pure deterministic functions can be executed and tested without external
  dependencies.
- Function calls preserve source provenance and can be explained.
- Risky capabilities are declared before execution and can be blocked.
- The model composes naturally with workflows, contracts, references,
  processors, cache backends, and future assisted steps.