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.