Added deterministic function layer

docs/document-functions.md

@@ -0,0 +1,137 @@
+# Document Function Layer
+
+Date: 2026-05-04
+
+## Purpose
+
+Document functions are a Markdown-native authoring surface over existing
+Markitect primitives. They let a document author write small deterministic
+operations inline or in fenced blocks while preserving diagnostics,
+provenance, trace events, capability metadata, and extension descriptors.
+
+The first implementation is intentionally conservative:
+
+- deterministic functions only
+- no network access
+- no filesystem access
+- no external processes
+- no provider or assisted-generation calls
+- no live flex-auth or external authorization service required
+
+Riskier functions can be added later as optional adapters once capability and
+policy gates are explicit.
+
+## Syntax
+
+Inline calls use:
+
+```markdown
+{{mkt:text.upper "draft"}}
+```
+
+Fenced block calls use:
+
+````markdown
+```mkt-function md.codeblock lang=python
+print("hello")
+```
+````
+
+Names are namespace-qualified. Arguments may be positional or named:
+
+```markdown
+{{mkt:md.heading text="Decision" level=2}}
+```
+
+Pipeline calls pass the previous result as the first argument of the next
+function:
+
+```markdown
+{{mkt:text.upper "draft" | text.replace DRAFT Final}}
+```
+
+Values of the form `${name}` are resolved from `ProcessingContext.variables`.
+This keeps data binding aligned with workflow expression conventions without
+creating a second workflow engine.
+
+## Built-In Functions
+
+Initial deterministic functions:
+
+| Function | Purpose |
+| --- | --- |
+| `text.upper` | Uppercase text. |
+| `text.lower` | Lowercase text. |
+| `text.title` | Title-case text. |
+| `text.trim` | Trim surrounding whitespace. |
+| `text.replace` | Replace text. |
+| `text.join` | Join values with an optional separator. |
+| `md.heading` | Create a Markdown heading. |
+| `md.bold` | Create bold Markdown text. |
+| `md.link` | Create a Markdown link. |
+| `md.codeblock` | Create a fenced code block. |
+| `data.get` | Read a value from processing context variables. |
+
+## CLI
+
+List functions:
+
+```text
+mkt function list
+```
+
+Validate calls without rendering:
+
+```text
+mkt function check examples/functions/basic-functions.md
+```
+
+Render deterministic calls:
+
+```text
+mkt function render examples/functions/basic-functions.md
+```
+
+JSON and YAML outputs include calls, diagnostics, provenance, and trace data.
+
+## Registry And Extension Fit
+
+The function layer has its own `DocumentFunctionRegistry`. Functions are
+described by `DocumentFunctionDescriptor`:
+
+- stable id and namespace
+- parameters
+- output type
+- execution kind
+- capability declarations
+- safety metadata
+- examples
+
+The built-in extension catalog exposes this layer as `document.function` with
+kind `document-function`. This keeps it discoverable without replacing
+processors, workflows, references, contracts, templates, or query engines.
+
+## Policy And Capability Gates
+
+The first evaluator blocks non-deterministic functions and supports local
+capability blocking through `ProcessingContext.policy`, for example:
+
+```python
+ProcessingContext(policy={"blocked_capabilities": ["document_function"]})
+```
+
+Future functions that read files, access network resources, invoke external
+processes, render exports, or call assisted generation must declare those
+capabilities before execution. External policy services may provide decisions
+through adapters later, but deterministic function execution has no external
+service dependency.
+
+## Design Rules
+
+- Stay close to Markdown and preserve CommonMark documents unless function
+  syntax is explicit.
+- Keep deterministic execution useful without backends or providers.
+- Surface diagnostics instead of silently deleting failed calls.
+- Preserve source line information where available.
+- Treat functions as an authoring surface over existing capabilities, not as a
+  second workflow engine.

docs/workplan-planning-map.md

@@ -39,7 +39,7 @@ and descriptions mirror the operational view.
 | `MKTT-WP-0011` | complete | done | `MKTT-WP-0003`; task-level triggers: `MKTT-WP-0010-T001`, `MKTT-WP-0010-T005` | Markdown dataflow workflow layer is complete: workflow standard, source collectors, binding model, deterministic steps, assisted boundary, safe outputs, CLI, docs, and examples. |
 | `MKTT-WP-0009` | complete | done | `MKTT-WP-0006` | Access-controlled knowledge gateway is complete: local labels, trust zones, path rules, policy-aware cache query/search, decisions, diagnostics, and external adapter boundaries. |
 | `MKTT-WP-0014` | complete | done | `MKTT-WP-0009` | Markitect-side enterprise IAM access-control integration is complete: NetKingdom/key-cape-compatible identity claims, flex-auth resource/policy contract, directory group resolution fixtures, decision-log sink, workflow declarations, CLI commands, and external PDP request examples. |
-| `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-0012` | complete | done | `MKTT-WP-0004`, `MKTT-WP-0010`, `MKTT-WP-0011` | Document function layer is complete: deterministic Markdown-native function descriptors, registry, inline/fenced syntax, pipelines, context bindings, CLI, docs, examples, diagnostics, provenance, and extension descriptor. |
 | `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
@@ -69,11 +69,10 @@ runtime/workflow expansion because it reduces central wiring and gives future
 features a canonical processing context/result/diagnostic/provenance model. It
 is not a business dataflow layer; that remains `MKTT-WP-0011`.
 
-`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.
+`MKTT-WP-0012` completed the Quarkdown-inspired document function layer as a
+deterministic authoring surface over existing Markitect capabilities. Assisted,
+external, file, network, render/export, and provider-backed functions remain
+future optional extensions behind local capability and policy gates.
 
 `MKTT-WP-0014` completed Markitect-side enterprise IAM integration for the
 access-control gateway. Central authorization administration remains optional