generated from coulomb/repo-seed
Improvements and perspective from architecture review
This commit is contained in:
@@ -0,0 +1,206 @@
|
||||
---
|
||||
id: MKTT-WP-0015
|
||||
type: workplan
|
||||
title: "Render And Document Function Extensions"
|
||||
domain: markitect
|
||||
status: todo
|
||||
owner: markitect-tool
|
||||
topic_slug: markitect
|
||||
planning_priority: P2
|
||||
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
|
||||
created: "2026-05-04"
|
||||
updated: "2026-05-04"
|
||||
state_hub_workstream_id: "a38f676a-0d0b-493c-9792-2e34480c3681"
|
||||
---
|
||||
|
||||
# MKTT-WP-0015: Render And Document Function Extensions
|
||||
|
||||
## Purpose
|
||||
|
||||
Capture the natural follow-on work from the Quarkdown comparison and the first
|
||||
Markitect document-function layer.
|
||||
|
||||
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.
|
||||
|
||||
## Background
|
||||
|
||||
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.
|
||||
|
||||
Markitect should not become a Quarkdown clone. The better fit is:
|
||||
|
||||
- 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
|
||||
|
||||
## Decision
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
## P15.1 - Typed document values and value mapping
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0015-T001
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "995945c5-6cec-435c-8943-b8da0a9ff89d"
|
||||
```
|
||||
|
||||
Define a typed value model for document functions:
|
||||
|
||||
- string, number, boolean, none
|
||||
- Markdown content
|
||||
- list and dictionary values
|
||||
- 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.
|
||||
|
||||
Output: value model, mapper API, tests, and documentation.
|
||||
|
||||
## P15.2 - Richer function syntax without losing Markdown compatibility
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0015-T002
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "bfce1388-e123-4e91-a5ab-ba67d21c22b8"
|
||||
```
|
||||
|
||||
Evaluate syntax extensions that improve author ergonomics without turning
|
||||
Markitect into a full compiler language:
|
||||
|
||||
- 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
|
||||
|
||||
Output: syntax compatibility note, parser tests, and diagnostics examples.
|
||||
|
||||
## P15.3 - Document-local reusable functions
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0015-T003
|
||||
status: todo
|
||||
priority: medium
|
||||
state_hub_task_id: "a8a8f017-3622-47f1-814e-0c71bd49a42f"
|
||||
```
|
||||
|
||||
Explore document-local reusable functions as a constrained, contract-aware
|
||||
extension:
|
||||
|
||||
- named reusable snippets
|
||||
- parameter lists and default values
|
||||
- body arguments
|
||||
- provenance for expansions
|
||||
- validation against allowed function namespaces
|
||||
|
||||
Avoid general-purpose Turing-complete scripting in core. If assisted or
|
||||
external behavior is needed, route it through workflow steps and explicit
|
||||
capability gates.
|
||||
|
||||
Output: design proposal and one deterministic prototype if justified.
|
||||
|
||||
## P15.4 - Quarkdown and render/export adapters
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0015-T004
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "69e550a0-188b-4bc4-9658-47219b090904"
|
||||
```
|
||||
|
||||
Design optional render/export adapters:
|
||||
|
||||
- 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
|
||||
- keep direct code reuse license-safe
|
||||
- track source to rendered-artifact provenance
|
||||
|
||||
Output: adapter interface, Quarkdown export sketch, policy model, and tests
|
||||
with deterministic fake renderers.
|
||||
|
||||
## P15.5 - Render-aware references, numbering, and assets
|
||||
|
||||
```task
|
||||
id: MKTT-WP-0015-T005
|
||||
status: todo
|
||||
priority: high
|
||||
state_hub_task_id: "53eb9f94-830b-4fdf-bb47-3f549048c82a"
|
||||
```
|
||||
|
||||
Extend the reference model for rendered documents:
|
||||
|
||||
- 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.
|
||||
|
||||
## 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.
|
||||
Reference in New Issue
Block a user