generated from coulomb/repo-seed
Complete memory graph and document value workplans
This commit is contained in:
@@ -1,222 +1,221 @@
|
||||
---
|
||||
id: MKTT-WP-0015
|
||||
type: workplan
|
||||
title: "Render And Document Function Extensions"
|
||||
title: "Document Function Value Contracts"
|
||||
domain: markitect
|
||||
status: todo
|
||||
status: done
|
||||
owner: markitect-tool
|
||||
topic_slug: markitect
|
||||
planning_priority: P2
|
||||
planning_priority: complete
|
||||
planning_order: 130
|
||||
depends_on_workplans:
|
||||
- MKTT-WP-0010
|
||||
- MKTT-WP-0011
|
||||
- MKTT-WP-0012
|
||||
related_workplans:
|
||||
- MKTT-WP-0007
|
||||
- MKTT-WP-0008
|
||||
- MKTT-WP-0009
|
||||
- MKTT-WP-0013
|
||||
- KONT-WP-0017
|
||||
- IB-WP-0017
|
||||
- MKTT-WP-0020
|
||||
- MKTT-WP-0021
|
||||
- MKTF-WP-0003
|
||||
- MQD-WP-0001
|
||||
created: "2026-05-04"
|
||||
updated: "2026-05-04"
|
||||
updated: "2026-05-15"
|
||||
state_hub_workstream_id: "a38f676a-0d0b-493c-9792-2e34480c3681"
|
||||
---
|
||||
|
||||
# MKTT-WP-0015: Render And Document Function Extensions
|
||||
# MKTT-WP-0015: Document Function Value Contracts
|
||||
|
||||
## Purpose
|
||||
|
||||
Capture the natural follow-on work from the Quarkdown comparison and the first
|
||||
Markitect document-function layer.
|
||||
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 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.
|
||||
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.
|
||||
|
||||
## Background
|
||||
## Split Decision - 2026-05-15
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
Markitect should not become a Quarkdown clone. The better fit is:
|
||||
The split is now:
|
||||
|
||||
- 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
|
||||
- `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`.
|
||||
|
||||
## Decision
|
||||
`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`.
|
||||
|
||||
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.
|
||||
## Boundary
|
||||
|
||||
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.
|
||||
`markitect-tool` owns:
|
||||
|
||||
Boundary clarification: `markitect-tool` owns typed value contracts,
|
||||
Markdown-compatible function syntax, render/export adapter interfaces,
|
||||
provenance envelopes, diagnostics, and deterministic fake renderers. It does
|
||||
not own durable rendered artifact storage, publication workflows, enterprise
|
||||
authorization, real renderer operations, or concrete application reports. Those
|
||||
belong in `kontextual-engine`, optional renderer packages, or
|
||||
`infospace-bench` application workflows.
|
||||
- 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
|
||||
|
||||
## P15.1 - Typed document values and value mapping
|
||||
`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: todo
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "995945c5-6cec-435c-8943-b8da0a9ff89d"
|
||||
```
|
||||
|
||||
Define a typed value model for document functions:
|
||||
Define a small `DocumentValue` model for function results:
|
||||
|
||||
- string, number, boolean, none
|
||||
- string, number, boolean, and none
|
||||
- Markdown content
|
||||
- list and dictionary values
|
||||
- lists and dictionaries
|
||||
- records and tables
|
||||
- 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.
|
||||
The model should serialize cleanly and stay independent of renderer-specific
|
||||
objects.
|
||||
|
||||
Output: value model, mapper API, tests, and documentation.
|
||||
Output: value dataclasses or schema objects, serialization helpers, tests, and
|
||||
documentation.
|
||||
|
||||
## P15.2 - Richer function syntax without losing Markdown compatibility
|
||||
## P15.2 - Add deterministic value mapping
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0015-T002
|
||||
status: todo
|
||||
priority: medium
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "bfce1388-e123-4e91-a5ab-ba67d21c22b8"
|
||||
```
|
||||
|
||||
Evaluate syntax extensions that improve author ergonomics without turning
|
||||
Markitect into a full compiler language:
|
||||
Define how each `DocumentValue` maps to:
|
||||
|
||||
- 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
|
||||
- inline Markdown
|
||||
- block Markdown
|
||||
- JSON/YAML API output
|
||||
- diagnostic fallback text for unknown or dynamic values
|
||||
|
||||
Output: syntax compatibility note, parser tests, and diagnostics examples.
|
||||
Mapping must be deterministic, inspectable, and safe to use from
|
||||
`mkt function render`.
|
||||
|
||||
## P15.3 - Document-local reusable functions
|
||||
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: todo
|
||||
priority: medium
|
||||
status: done
|
||||
priority: high
|
||||
state_hub_task_id: "a8a8f017-3622-47f1-814e-0c71bd49a42f"
|
||||
```
|
||||
|
||||
Explore document-local reusable functions as a constrained, contract-aware
|
||||
extension:
|
||||
Extend `DocumentFunctionDescriptor` output metadata so functions can declare
|
||||
their result type using the new value vocabulary.
|
||||
|
||||
- named reusable snippets
|
||||
- parameter lists and default values
|
||||
- body arguments
|
||||
- provenance for expansions
|
||||
- validation against allowed function namespaces
|
||||
Validation should catch:
|
||||
|
||||
Avoid general-purpose Turing-complete scripting in core. If assisted or
|
||||
external behavior is needed, route it through workflow steps and explicit
|
||||
capability gates.
|
||||
- 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: design proposal and one deterministic prototype if justified.
|
||||
Output: descriptor updates, evaluator checks, diagnostics, and tests.
|
||||
|
||||
## P15.4 - Quarkdown and render/export adapters
|
||||
## P15.4 - Pin syntax extension boundaries
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0015-T004
|
||||
status: todo
|
||||
priority: high
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "69e550a0-188b-4bc4-9658-47219b090904"
|
||||
```
|
||||
|
||||
Design optional render/export adapter contracts:
|
||||
Document which syntax improvements are still acceptable without replacing the
|
||||
current conservative parser:
|
||||
|
||||
- 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 and fake
|
||||
deterministic test adapters in this repo
|
||||
- keep direct code reuse license-safe
|
||||
- track source to rendered-artifact provenance
|
||||
- clearer escaping rules
|
||||
- fenced block-body argument refinements
|
||||
- line/span reporting improvements
|
||||
- cycle and depth limits for current pipeline evaluation
|
||||
|
||||
Output: adapter interface, Quarkdown export sketch, local policy model, and
|
||||
tests with deterministic fake renderers. Durable render jobs, stored artifacts,
|
||||
publication state, and application-specific reports are out of scope here.
|
||||
Explicitly defer:
|
||||
|
||||
## P15.5 - Render-aware references, numbering, and assets
|
||||
- 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: todo
|
||||
priority: high
|
||||
status: done
|
||||
priority: medium
|
||||
state_hub_task_id: "53eb9f94-830b-4fdf-bb47-3f549048c82a"
|
||||
```
|
||||
|
||||
Extend the reference model for rendered documents:
|
||||
Update document-function docs, examples, and extension descriptor metadata to
|
||||
show typed outputs without advertising render/export behavior as core function
|
||||
execution.
|
||||
|
||||
- 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
|
||||
|
||||
```task
|
||||
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.
|
||||
This is a syntax-layer capability contract, not a durable authorization service
|
||||
or audit system.
|
||||
Output: docs, examples, extension catalog assertions, and generated API/CLI
|
||||
reference updates if the public surface changes.
|
||||
|
||||
## 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.
|
||||
- Durable render operations, publication lifecycle, and enterprise policy
|
||||
enforcement remain outside `markitect-tool`.
|
||||
- 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.
|
||||
|
||||
Reference in New Issue
Block a user