feat(examples): add IR-to-Brainfuck extension generator

[flyingrobots]

Requested classification

Suggested scheduling state: active follow-up to #728
Suggested legend: TRANSMUTE
Suggested work type: enabler

Work type

enabler

Sponsor actor

A Wesley adopter evaluating whether the extension-generation contract is concrete enough to use from a real external generator.

Sponsored perspectives

• Sponsored Human: A contributor who needs one memorable, executable example instead of assembling the contract from API documentation.
• Sponsored Agent: An implementation or review agent that needs a deterministic fixture with exact input, output, and provenance evidence.

Hill

A contributor can run one Cargo example that lowers GraphQL into canonical Wesley facts, deterministically emits Brainfuck from those facts, executes the Brainfuck playback, and verifies exact source, generator, and output provenance.

Playback

Run:

cargo run -p wesley-core --example ir_to_brainfuck

The example prints the decoded Brainfuck message, input and provenance digests, verification counts, and the structurally false review-authority bit. A source-only mode emits the complete Brainfuck program.

Problem

Issue #728 and PR #731 shipped a public external-generation contract and checked JSON fixtures, but the repository does not ship a standalone example target showing how an external generator actually consumes canonical IR, owns an output format, emits bytes, and asks Wesley to verify them end to end.

Proposed change

Add a Cargo example target compiled as a separate crate against only public wesley-core APIs. It will:

• lower a small built-in GraphQL schema into Shape IR and root operations;
• derive a deterministic, amusing IR summary;
• compile that summary into a valid single-cell Brainfuck program;
• execute the generated program for human-visible playback;
• bind the generator component, owner declaration, canonical input, and Brainfuck output into provenance;
• verify every exact source and output byte;
• offer a source-only mode for piping the generated Brainfuck elsewhere.

Document the example beside the extension-generation reference and record it in the changelog.

Invariants to preserve

• Wesley remains domain-neutral and does not interpret target semantics.
• The example consumes only public wesley-core APIs as an external Cargo example crate.
• No filesystem discovery, registry lookup, plugin loading, network access, or target execution is added to the contract.
• Generation and playback are deterministic for identical input.
• Review output remains structurally non-authoritative.
• Exact source, generator, and emitted-program bytes remain digest-backed.

Non-goals

• No dynamic plugin loader.
• No new Wesley CLI command.
• No general-purpose Brainfuck optimizer or production runtime.
• No revival of retired JavaScript generator infrastructure.
• No claim that successful playback proves target-runtime semantic authority.

Acceptance / tests

• The example compiles as a Cargo example using only public wesley-core APIs.
• Identical canonical input produces byte-identical Brainfuck.
• Executing the generated Brainfuck reproduces the expected IR-derived message.
• Changing semantic input changes the generation input and emitted output.
• Provenance verification recomputes the generator, owner declaration, and Brainfuck output.
• Tampered output is rejected by the existing structured digest error.
• The review projection remains non-authoritative.
• Focused example tests and full pnpm run preflight pass.
• Reference documentation and changelog describe the example and its boundary.

Witness plan

Tests

Run the example test target, the focused extension-generation integration test, and full pnpm run preflight.

Playback

Capture the example's decoded message, deterministic digests, verification counts, and source-only mode.

Docs

Update docs/reference/extension-generation.md and CHANGELOG.md.

Retro / closeout

Record the exact commands and results in the implementation PR. Issue-only triage is sufficient because this is an example of the already-designed #728 contract rather than a new architecture.

Method artifacts

• Design: Issue-only triage is sufficient; the architecture and boundaries were established in feat(extensions): publish canonical semantic-generation input and provenance contract #728.
• Witness: To be linked from the implementation PR.
• Retro: To be recorded in the PR closeout.
• PR: Pending.

[coderabbitai]

🔗 Related PRs

#499 - test(stack): add Stack Witness 0001 fixture artifact shape [merged]
#521 - Add Rust IR performance baseline [merged]
#618 - feat: LE binary Rust codec emitter (le-binary-rust) + output-object codecs [merged]
#686 - docs: add plain Wesley onboarding path [merged]
#731 - Publish extension generation provenance contract [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!