Add provider-neutral Elicit through the core Context API

[taras]

Motivation

Executable Markdown workflows need a provider-neutral way to pause for
structured human input. The document should describe what it is asking and the
valid response shape without choosing whether the interaction occurs in a web
form, terminal UI, Effection Inspector, automated test, or another host.

<Elicit> is a core contextual capability. It does not select an interaction
mode. The current CLI configuration uses the WebForm provider tracked in #195.

Implementation coordination

<Elicit> is an ordinary core TypeScript function component registered as a non-reserved default through #202's registration surface. Core resolves and validates props, owns as, creates the invocation boundary, and applies the validated return binding. The component receives no raw ComponentElement, expression map, binding environment, or as value and is not implemented through Component.expand.

Implementation depends on:

1. Register function components and migrate legacy component handlers #202 PR 1 for scope-local registration and ordinary function-component resolution; and
2. Add a bundled local WebForm component for schema-backed user input #195's reviewed live-form provider operation/adapter contract for the CLI's initial provider.

It does not wait for #202's Agent, Testing, assertion, or TestAgent migrations, and it does not depend on WebForm's browser-CI, website, or publication cleanup once the provider contract is available.

The component compiles the response schema before calling content(). It then presents the rendered request through the contextual Elicitation provider and returns the provider result through a declared broad JSON return schema. No schema, content, provider, or transport behavior is implemented a second time in an expansion handler.

Authoring contract

<Elicit schema={responseSchema} as="response">
  Review the implementation plan and provide your decision.
</Elicit>

• <Elicit> and the Elicitation Context API live in @executablemd/core.
• schema and as are required.
• schema accepts captured JSON text or an already structured draft-07 JSON
  Schema value.
• Invocation content expands through content() into the request message presented by the configured provider.
• A valid structured response binds directly to as.
• The component emits nothing into the surrounding document.
• The component exposes no mode, provider, WebForm, or RJSF-specific props.
• Authors that intentionally require a browser form or RJSF uiSchema can use
  the public <WebForm> component from Add a bundled local WebForm component for schema-backed user input #195 directly.

Elicitation Context API

The contextual provider receives only the rendered request and compiled
response schema:

interface ElicitationRequest {
  message: string;
  schema: JsonSchema;
}

It returns an unknown structured value through an Effection operation.

Core owns:

• schema parsing and compilation;
• final response validation;
• capture and source diagnostics;
• durable response recording and replay; and
• interruption through the surrounding Effection scope.

The provider owns only its live interaction and transport lifecycle. It does
not receive as, workflow run IDs, journal details, or component execution
identities.

The schema compiles before invocation content expands or the provider is contacted. An
invalid schema therefore produces no invocation-content effects and cannot open an
interaction.

When no provider is installed, <Elicit> fails immediately with a clear
no elicitation provider configured diagnostic.

Provider configuration

Provider selection happens only through the Context API.

• The normal CLI composes the WebForm implementation from Add a bundled local WebForm component for schema-backed user input #195 as its current
  provider.
• Applications embedding core explicitly install an elicitation provider.
• Automated tests install scripted middleware through the same API.
• Future terminal and Effection Inspector integrations replace the provider
  without changing executable Markdown.

Core has no dependency on React, RJSF, HTTP serving, browser launching, terminal
UI, or Inspector packages.

Response and lifecycle behavior

• Core validates every provider result against the compiled schema before it
  binds or journals the value.
• A schema-invalid provider result fails once with normalized validation
  diagnostics. Core does not silently invoke the provider again.
• Interactive correction belongs inside a provider such as WebForm. Workflow
  retry belongs in visible bounded Markdown control flow.
• Provider failures propagate with <Elicit> source context.
• Halting the execution halts the provider operation and its owned resources.
• <Elicit> has no protocol-defined approve, decline, cancel, or other
  outcomes. The schema defines every response option available to the user.
• Cancellation of execution remains an Effection lifecycle event unless the
  document explicitly models cancellation as schema data.

Durability

Only the final validated response is journaled.

On replay, core restores the response and binding without expanding the request
content or invoking the configured provider. Provider choice and transport
details do not affect a completed replay.

Testing

Add a colocated Elicit.test.md document. It uses an eval block to apply
scripted Elicitation Context middleware within each <Test> scope, invokes
<Elicit> normally, and asserts the captured response.

Core exposes a test helper for constructing the scripted middleware. The eval
block supplies an ordered response queue rather than reimplementing a provider.
The helper:

• consumes one response per live elicitation;
• fails when an elicitation has no scripted response;
• fails at test teardown when scripted responses remain unused; and
• is removed automatically with the enclosing test scope.

No testing-only prop or special Markdown component is added. This eval use is
an explicitly approved exception for installing Context API middleware.

The Markdown tests cover:

• schemas supplied as captured JSON and structured values;
• invocation content becoming the provider request;
• structured capture with no surrounding output;
• multiple elicitations consuming scripted responses in order;
• missing scripted responses; and
• unused scripted responses.

Add lower-level automated tests for:

• required props and capture name;
• malformed and invalid draft-07 schemas;
• schema compilation before invocation-content expansion;
• no provider being configured;
• the provider receiving only the rendered message and compiled schema;
• provider results being validated again by core;
• normalized diagnostics for invalid provider results;
• invocation-content and provider failures propagating with source context;
• interruption halting an active provider;
• contextual provider override and restoration;
• durable response recording;
• full replay without invocation-content expansion or provider invocation; and
• parity across Deno, Node, and Bun.

Documentation

• Specify the component props, schema forms, output, validation, and lifecycle
  behavior in the core component reference.
• Document the Elicitation Context API and show how hosts install providers.
• Add a website example using <Elicit> for a human review decision.
• Explain why provider selection is contextual rather than an author-facing
  mode.
• Link the current WebForm provider in Add a bundled local WebForm component for schema-backed user input #195 while keeping browser-specific
  details out of the core contract.

Acceptance criteria

• <Elicit> expresses a provider-neutral, schema-constrained request.
• The provider is selected exclusively through the Context API.
• Core validates both the schema and the provider response.
• Invalid schemas cause no invocation-content or provider effects.
• Missing providers and invalid responses produce actionable diagnostics.
• Response options come only from the document's schema.
• Interruption remains a lifecycle event.
• Replay restores the response without repeating invocation-content or provider work.
• Markdown tests configure scripted responses through eval-installed
  middleware with exact queue consumption.
• Specification and website documentation ship in the same PR.

Not included

• A mode prop or provider selection in Markdown.
• RJSF uiSchema or other provider-specific presentation options.
• Built-in approve, decline, or cancel actions.
• Hidden retry or response repair.
• The WebForm implementation and bundled assets tracked in Add a bundled local WebForm component for schema-backed user input #195.
• Terminal UI and Effection Inspector providers.

[taras]

Sequencing update: both dependencies are satisfied — scope-local registration merged in #242 and the reviewed provider operation merged in #252 (liveForm(input) with the prepareForm/runPreparedForm split in packages/web/src/live-form.ts). This issue is next for implementation after #259.

One addition since this contract was written: #260 (xmd prompt) is a second consumer of the Elicitation Context API — the CLI will invoke the contextual provider directly for its approval step, outside any document execution. No contract change: the provider still receives only { message, schema }. But keep the provider-invocation path host-callable rather than private to the <Elicit> component internals, so a host with an installed provider can elicit without executing a document.

[taras]

Owner rulings on two implementation questions

1. The rendered message participates in the durable fingerprint. <Elicit>'s durable identity is the compiled schema plus the rendered request message, matching <WebForm>'s merged fingerprint (schema + UI schema + sanitized content). Preflight — schema compilation, invocation-content expansion, normalization — runs on every execution, replay included; what replay never repeats is provider and interaction work. A message-only edit therefore re-asks: replaying a recorded answer against a question that changed is exactly the failure a human-decision component must not have.

This amends two sentences in the issue body:

• "full replay without invocation-content expansion or provider invocation" → "full replay without provider invocation or interaction work"
• Acceptance criterion "Replay restores the response without repeating invocation-content or provider work" → "Replay restores the response without repeating provider or interaction work; preflight and invocation-content projection run as on any execution."

The ephemeral-environment consequence (replay re-runs projection, which can fail where the environment is gone) is accepted and stays in #218's deferred territory, as it already does for <WebForm>.

2. The __proto__-name and external-$ref refusals hoist into core. Core's Elicit schema compilation refuses both, with positioned diagnostics, under every provider — so a schema's validity never depends on which provider is installed, and scripted-middleware tests agree with the real CLI. Rationale: a __proto__ property name is a core binding-safety hazard (the validated response binds into the evaluation environment, and obj[key] = v rewrites the prototype on Node/Bun), and external $ref is unsupported platform-wide until #192. The WebForm adapter keeps its own checks as defense-in-depth for direct liveForm/<WebForm> use; via <Elicit> they become unreachable.

Refactor approved: parseDeclaration gains a leading label parameter so its diagnostics name the invoking component, mirroring compileParseSchema(componentName, …).

[taras]

Slicing ruling on the __proto__ finding: the implementor verified core's own parser has the assignment hazard the earlier ruling cited — packages/core/src/json.ts assigns result[key] = … where packages/web/src/json.ts uses defineProperty, and measured the divergence (Deno keeps the key; Node/Bun drop it and rewrite the prototype). Since JSON.parse creates __proto__ as an own property, a provider answering a bare {"type": "object"} schema reaches it directly once exists — the schema-name refusal cannot close it.

Land the fix as its own PR ahead of the chain (PR 0), not folded into PR 1:

• The defect is pre-existing in core and independent of Elicit; the fix must not be hostage to PR 1's review cycle, and every current parser caller benefits immediately.
• The chain's contract then rests on a merged invariant rather than a sibling commit.
• Contract for the fix: uniform cross-runtime semantics equal to Deno's current behavior — the key is kept as an own data property and the prototype is never rewritten — via defineProperty, mirroring packages/web. The cross-runtime test asserts both columns of the measured table come out "kept / not rewritten" under Deno, Node, and Bun, and fails with the fix reverted.

Deferring it past the chain was never on the table, correctly.

[taras]

Ruling update, ratified during PR #264 review: refuse-on-mismatch is the shipped semantics. The durable protocol's ReplayOutcome offers replay-or-error today (re-execution is named as future work), so a resumed document whose recorded answer does not match the current question fails with StaleInputError naming the cause and the remedy. The safety property the fingerprint ruling protects — never bind a recorded answer to a different question — holds. Live re-execution on mismatch lands with #218 when the protocol grows that outcome.

PR 2 scope addition: <WebForm>'s recorded fingerprint is currently decorative — no guard compares it, so a resumed form binds its recorded answer even when the question changed. PR 2, which already touches packages/web, adds the same replay guard to WebForm's journal path with a mismatch test.