Design dynamic XMD evaluation in md eval fences

[taras]

Story

As an Executable.md author, I want an XMD fragment to remain visibly documented as a Markdown code block while allowing xmd to evaluate it, so a document can show the exact workflow source that it executes.

The canonical surface under consideration is:

```md eval
<File path="release.txt">Release {props.version}</File>
```

An ordinary Markdown viewer displays the fenced source. Executable.md evaluates the XMD and replaces the fence with its rendered result.

This design also raises the more powerful possibility that a value containing XMD becomes executable source:

```md eval
{generatedXmd}
```

Dynamic XMD evaluation is an explicit data-to-code boundary. It is distinct from #416: <Call> composes statically authored document targets, while md eval may admit and execute source produced at runtime.

Status

This is a future design issue, not an implementation-ready story. Do not implement md eval until the open product and architecture decisions below are resolved and recorded in the architecture and executable MDX specification.

<Call> does not depend on this feature. Markdown workflow tests can initially invoke authored targets through <Call> without dynamic evaluation.

Settled direction

• The first fence token is md, so ordinary Markdown renderers recognize and highlight the content.
• The eval modifier is the explicit signal that the fenced Markdown is executable rather than passive.
• A successful block inserts its evaluated output at the fence position.
• md eval and <Call> are separate features with separate trust models.
• XMD headings produced inside the fence are runtime output and never become statically addressable document targets.
• Nested durable effects retain their ordinary descriptions, results and replay behavior rather than being hidden behind one opaque rendered result.
• In a durable workflow, generated executable source cannot run before the complete admitted source passes the existing journal security boundary and the applicable generated-XMD admission policy.
• The exact admitted source must be retained for replay, history and deliberate training ingestion. Replay evaluates that retained source rather than invoking the producer again.

Open product decisions

Source model and interpolation

Decide which forms the language supports:

1. A statically authored XMD fragment whose expressions resolve using ordinary XMD semantics.
2. An expression whose resulting string is scanned as executable XMD.
3. A mixed template in which interpolated values can introduce XMD structure.

The third form needs an explicit escaping and value-insertion model. A value intended as file content or prose must not accidentally become executable merely because it contains <Component /> syntax.

The design must state when source interpolation occurs, what values are accepted, and which bytes constitute the source retained in history.

Authority and admission

Decide what components dynamically produced source may invoke:

• the full authority available to the authored surrounding document;
• the constrained generated-XMD evaluator already required by workflow architecture; or
• a separately declared capability set.

The answer may differ between xmd run, which uses the caller's selected environment, and xmd workflow, whose Agent and generated-XMD authority is deliberately constrained. Any difference must be an explicit provider capability rather than runtime detection in shared code.

An authored document must not be able to accidentally turn read-only Agent output into unrestricted workflow authority.

Durable source publication

Define the journal protocol that establishes executable source before nested effects begin:

• whether every md eval block retains a source event or only a dynamically produced block does;
• how the filtered source publication is ordered before the fragment's first nested effect;
• what happens when source filtering or admission is rejected;
• whether source capture is a durable operation, another retained protocol record, or part of a more general generated-XMD construct; and
• how fail-stop durability behavior applies between source publication and nested expansion.

The protocol must leave no state in which effects ran from source that replay, history inspection or training ingestion cannot recover.

Bindings and results

Decide:

• whether the fragment sees durable bindings, live bindings, or an explicit input object;
• whether dynamically evaluated XMD can export bindings to later content;
• whether it is a transparent lexical expansion or creates an invocation/lifetime boundary;
• how rendered output and partial output are represented; and
• how failures propagate through surrounding error middleware.

No live binding may enter retained executable source or the journal accidentally.

Modifier composition

Define which existing code-fence modifiers are meaningful around md eval, including silent and timeout. JavaScript-eval-specific behavior such as persist and ephemeral must either receive coherent XMD semantics or fail validation rather than being silently ignored.

Identity and diagnostics

Define:

• the structural frame beneath which dynamically scanned elements expand;
• stable nested expansion identity across replay;
• source positions for diagnostics originating in evaluated source;
• how retained generated source is named in errors and history; and
• active recursion and resource-lifetime behavior.

Required design evidence

Before this issue becomes implementation-ready, the design should include executable examples covering:

• a static visible XMD fence;
• a binding that supplies executable XMD;
• dynamic prose or file content containing component-like text that must remain data;
• a generated fragment containing multiple durable effects;
• rejection before the first effect;
• interruption after source retention and before or between nested effects;
• replay without invoking the source producer;
• journal security-filter rejection;
• generated-XMD admission rejection;
• surrounding error handling and partial output; and
• Deno, Node, Bun and compiled-host provider boundaries.

Out of scope

• Implementing <Call> or hierarchical targets;
• making runtime-generated headings discoverable through xmd targets;
• starting a separate workflow run for an evaluated fragment;
• loading mutable Workspace files as trusted authored definitions; and
• defining a Markdown workflow testing harness.

Related work

• Compose authored document targets with <Call> #416 composes statically authored targets through <Call> and deliberately excludes dynamic XMD.
• Run document sections as hierarchical workflow targets #412 defines hierarchical document targets and static target discovery.
• Implement retained Workflow Workspace restoration #218 owns retained workflow, generated-XMD, journal security and Workspace architecture.