generated from coulomb/repo-seed
82 lines
1.9 KiB
Markdown
82 lines
1.9 KiB
Markdown
# Fenced-Block Processors
|
|
|
|
Date: 2026-05-04
|
|
|
|
## Purpose
|
|
|
|
The processor registry is the deterministic execution boundary for WP-0010.
|
|
It lets Markdown fenced blocks opt into named processors while keeping
|
|
execution explicit, inspectable, and non-magical.
|
|
|
|
Processors receive:
|
|
|
|
- the fenced content unit
|
|
- resolver-capable context
|
|
- variables and policy maps
|
|
|
|
Processors return:
|
|
|
|
- generated content
|
|
- optional generated files
|
|
- diagnostics
|
|
- dependencies
|
|
- operation provenance
|
|
|
|
No built-in processor runs arbitrary code.
|
|
|
|
## Syntax
|
|
|
|
A fenced block opts into processing by using an `mkt-<processor>` language:
|
|
|
|
````markdown
|
|
```mkt-uppercase {#shout}
|
|
hello
|
|
```
|
|
````
|
|
|
|
The processor can also be named with attributes:
|
|
|
|
````markdown
|
|
```markdown {#example processor="identity"}
|
|
Rendered as-is by the identity processor.
|
|
```
|
|
````
|
|
|
|
## Built-In Processors
|
|
|
|
Initial deterministic processors:
|
|
|
|
- `identity`: returns the fenced block content unchanged.
|
|
- `uppercase`: returns uppercased content; mainly a registry smoke-test.
|
|
- `include`: resolves a `ref` attribute through the content reference resolver.
|
|
|
|
Reference-backed include:
|
|
|
|
````markdown
|
|
```mkt-include {#payment ref="std:clauses.md#payment-terms"}
|
|
```
|
|
````
|
|
|
|
The include processor returns the resolved content, records the target file as
|
|
a dependency, and emits operation provenance.
|
|
|
|
## CLI
|
|
|
|
Run processors in a document:
|
|
|
|
```bash
|
|
mkt process examples/references/context.md --format json
|
|
```
|
|
|
|
Text output reports processor validity, block IDs, and the first generated
|
|
content line. JSON/YAML output includes diagnostics, dependencies, and
|
|
provenance.
|
|
|
|
## Extension Boundary
|
|
|
|
The registry is deliberately small. It does not render a final document yet and
|
|
does not execute shell, Python, SQL, or LLM calls. Those can become opt-in
|
|
processors later, but they should use the same result envelope so diagnostics,
|
|
dependencies, provenance, cache invalidation, and access-control hooks stay
|
|
consistent.
|