💥 feat(core): return schema-validated values from components and roots

[taras]

Why

Components produce rendered Markdown, and as captures that text as a string.
Agent workflows need validated values for control flow — a verdict, a list of
findings, a question — and the only way to get one was to render text and
re-parse it. Root documents had the same gap: execute() completed with
rendered text, so a document that computed a structured result had nowhere to
put it.

Closes #176.

What changes

Before:

• A component returned its rendering. <Review as="review" /> bound a string.
• DocumentExecution completed with Result<string>; xmd run printed
  rendered Markdown.

After:

• A returns declaration switches a component into value mode: it renders
  nothing, must be invoked with as, and binds the JSON value its single
  direct top-level <Return value={…} /> produces, validated at the component
  boundary. Components without returns are unchanged.
• A root uses the same modes minus as. A value root completes with its
  validated JSON; xmd run writes only that JSON to stdout.
• inspectDocument() reports returns (the effective schema) and returnMode
  without executing the document.

---
returns:
  passed: { type: boolean }
  summary: { type: string }
---

```js eval
const verdict = { passed: true, summary: "no findings" };
```

<Return value={verdict} />

<Review as="review" />

<Show when={review.passed}>Review passed: {review.summary}</Show>

How it works

frontmatter/export `returns` → definition.returns → structural preflight →
body runs as documentation, <Return> evaluated in place → JSON boundary +
schema → bound under `as` in the caller's env (or the root's completion value)

parseReturnsDeclaration is the single declaration parser — object-only, full
schema vs object-return shorthand, draft-07 dialect check — used by Markdown
frontmatter and by export const returns. Every shorthand property is
required; optional properties need the full schema form.

validateBodyStructure replaces validateOutputPlacement at both call sites.
It runs against the body's own source, before <Content /> substitution, and
aggregates every violation into one diagnostic.

expandValueBody runs the complete body: everything except the
definition-owned <Return> is documentation under fail-fast, its rendering
discarded. It returns the validated value rather than binding it, so
expandComponent binds into the caller's environment after the component's
scope unwinds — the value never enters the component's own env.

validateReturnValue passes the produced value through parseJson before Ajv,
so non-JSON is rejected and defaults fill a clone rather than the producer's
object.

Review guide

Start with: packages/core/tests/component-returns.test.ts

Then review:

1. specs/executable-mdx-spec.md §6.10, §5.4, §8.1, §9.6 — the contract
2. packages/core/src/frontmatter.ts + validate.ts — declaration parsing and
   the JSON/schema boundary
3. packages/core/src/expand.ts — preflight, <Return> reservation,
   expandValueBody, the binding boundary
4. packages/core/src/execute.ts — value roots, the internal { output, value }
   result, and DocumentExecution
5. packages/cli/src/cli.ts — stdout/stderr separation

Look carefully at:

• Value-root failure is total: structural, schema, value, body, and
  post-<Return> failures all complete Err (packages/cli/tests/value-root.test.ts).
• Replay still delivers output: executeDocument sends the journaled body text
  through DocumentOutput before closing, because callback consumers never see
  the close value.

What must stay true

• definition.returns === undefined is text mode — absence is never
  normalized, so an explicit returns: { type: string } is still value mode.
  Checked by "treats an explicit string schema as value mode".
• Structure fails before body effects — enforced by the preflight in
  expandComponent/documentWorkflow and checked by the "structure, before
  body effects" tests, which assert no exec ran.
• Props and returns never share a compiled validator — separate WeakMap
  caches, checked by "keeps props and return contracts independent for the same
  schema object".
• A value never reaches stdout as text, and rendered text never passes for a
  result — checked by Tier VR.

How to verify it

• Tier RV (packages/core/tests/component-returns.test.ts) proves value kinds,
  declaration forms, the JSON boundary, structure, execution order, function
  components, composition, value roots, and replay; it fails if a value is
  bound before validation or if a structural failure lets the body run.
• Tier VR (packages/cli/tests/value-root.test.ts) proves the CLI channel
  contract end to end and fails if body text or a diagnostic reaches stdout.
• smoke-test/Guide/ReturnValues.md runs under xmd test in CI, and the new
  CI step asserts xmd run smoke-test/value-root.md prints exactly the JSON the
  guide documents.

All seven checks pass locally: deno task lint, check, test, check:jsr,
pnpm exec tsc --project tsconfig.node.json --noEmit, pnpm test:node,
bun run test:bun.

Scope

Included

• returns for Markdown and function components, <Return>, value roots, the
  xmd run JSON result contract, DocumentInfo.returns / returnMode, spec
  and author documentation.

Intentionally unchanged

• <Output> behavior for text components and text roots.
• xmd test output: its report stays on stdout in both modes.
• Persistence: returning a value does not choose where it is stored.

New abstractions

• ReturnsSchema names the declared return schema, distinct from PropsSchema,
  whose root must be an object.
• ReturnSchemaError / ReturnValidationError exist so a return failure is not
  reported as a props failure; they share an internal SchemaValidationError
  base that the segment conversion reads, and the base is not exported.
• packages/core/tests/helpers.ts holds asText for suites that assert on
  rendered text now that collect() returns Json.

Risks and limitations

• 💥 DocumentExecution completes with Result<Json> and collect() returns
  Json. A text root still completes with its rendered Markdown, so the runtime
  value is unchanged; call sites that need a string narrow it.
• A text function component returning a non-string is now an error rather than
  flowing into a text segment unchecked.

Scope confirmation

• Every changed file supports the purpose described above.
• Unrelated cleanup and formatting changes are excluded.
• Generated or mechanical changes are clearly identified.
• The description matches the final diff and test results.

[github-actions]

PR #200: 💥 feat(core): return schema-validated values from components and roots

49 files, +2906 / -851

Scope

🔴 PR has 3757 lines changed. Split into focused PRs.

🟡 3757 lines changed. PRs under 400 receive more thorough review.

🟡 49 files changed. Are all changes related?

🟡 PR mixes config and source changes.

🟡 New abstraction files: packages/core/tests/helpers.ts. Verify 3+ consumers.

🟡 package.json changed without dependency justification.

Structural

✅ No structural bloat detected.

Slop

✅ Slop indicators look low.

Static Analysis

✅ Oxlint found no issues.

Correctness

No extraneous code patterns detected.