From 0d1ad21a9f23e6c4bce3a2ef1897f9fedce081ec Mon Sep 17 00:00:00 2001 From: tegwick Date: Mon, 4 May 2026 04:11:31 +0200 Subject: [PATCH] Quarkdown review and document function extension workplan generation --- docs/workplan-planning-map.md | 10 + .../MKTT-WP-0012-document-function-layer.md | 256 ++++++++++++++++++ 2 files changed, 266 insertions(+) create mode 100644 workplans/MKTT-WP-0012-document-function-layer.md diff --git a/docs/workplan-planning-map.md b/docs/workplan-planning-map.md index ef13358..758b628 100644 --- a/docs/workplan-planning-map.md +++ b/docs/workplan-planning-map.md @@ -37,6 +37,7 @@ and descriptions mirror the operational view. | `MKTT-WP-0005` | P2 | todo | `MKTT-WP-0003`, `MKTT-WP-0004` | Pick up when generation/form/context or semantic assessment pressure appears. | | `MKTT-WP-0011` | P2 | todo | `MKTT-WP-0003`; task-level triggers: `MKTT-WP-0010-T001`, `MKTT-WP-0010-T005` | Declarative Markdown dataflow workflows: source extraction, deterministic/assisted processing, and multi-output generation. | | `MKTT-WP-0009` | P2 | todo | `MKTT-WP-0006` | Establish access-control gateway before security-sensitive cache/context use. | +| `MKTT-WP-0012` | P3 | todo | `MKTT-WP-0004`, `MKTT-WP-0010`, `MKTT-WP-0011` | Future Quarkdown-inspired document function layer: reusable Markdown-native function calls over processors, references, contracts, workflows, and later assisted steps. | | `MKTT-WP-0008` | P3 | todo | `MKTT-WP-0006`, `MKTT-WP-0007`, `MKTT-WP-0009` | Agent working-memory cache after backend and policy floor are available. | ## Dependency Notes @@ -60,6 +61,12 @@ optional assisted generation hooks, and multiple Markdown outputs. It should not block P3.7, but it should follow the first reference model and processor registry decisions in `MKTT-WP-0010`. +`MKTT-WP-0012` captures the Quarkdown-inspired document function layer. It +should follow `MKTT-WP-0011` because the workflow layer will reveal which +operations deserve author-facing function syntax. It should remain optional and +capability-gated, especially before assisted, external, file, or network +functions are allowed. + ## State Hub Mirror Native State Hub dependency edges should mirror the whole-workstream @@ -78,6 +85,9 @@ dependencies: - `MKTT-WP-0005 -> MKTT-WP-0004` - `MKTT-WP-0011 -> MKTT-WP-0003` - `MKTT-WP-0009 -> MKTT-WP-0006` +- `MKTT-WP-0012 -> MKTT-WP-0004` +- `MKTT-WP-0012 -> MKTT-WP-0010` +- `MKTT-WP-0012 -> MKTT-WP-0011` - `MKTT-WP-0008 -> MKTT-WP-0006` - `MKTT-WP-0008 -> MKTT-WP-0007` - `MKTT-WP-0008 -> MKTT-WP-0009` diff --git a/workplans/MKTT-WP-0012-document-function-layer.md b/workplans/MKTT-WP-0012-document-function-layer.md new file mode 100644 index 0000000..018e8c4 --- /dev/null +++ b/workplans/MKTT-WP-0012-document-function-layer.md @@ -0,0 +1,256 @@ +--- +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.