Add IR-to-Brainfuck extension generator example

[flyingrobots]

Linked Issue

Closes #740

Branch / Issue-Title Check

• Exception: this branch uses the isolated-worktree agent/ir-to-brainfuck-example name so the example cannot pick up either pre-existing contaminated Wesley index. The subject still maps one-to-one to feat(examples): add IR-to-Brainfuck extension generator #740.

Summary

• Ship a runnable external-generator example that lowers GraphQL into canonical Wesley IR, compiles an IR-derived message into Brainfuck, executes it, and verifies exact provenance.

Why

• The public extension-generation contract had comprehensive fixtures but no memorable executable example of a consumer using only public APIs.
• A Cargo example target is a useful boundary witness because Cargo compiles it as a separate crate. Keeping the schema built in makes playback hermetic and deterministic.
• Brainfuck is intentionally ridiculous, small enough to implement without dependencies, and exact enough to expose any input or output drift.
• This does not add a plugin loader or a Wesley CLI command; those remain explicit non-goals.

Changes

• Add crates/wesley-core/examples/ir_to_brainfuck.rs with a deterministic compiler and bounded wrapping-u8 interpreter.
• Bind the owner declaration, example source, generator component, canonical generation input, and emitted program into the existing provenance contract.
• Test deterministic replay, semantic-input sensitivity, tamper rejection, and malformed/input-bearing program rejection.
• Document normal playback and --source mode beside the extension-generation reference.
• Make cargo xtask test and preflight exercise the example test target.
• Record the example in the unreleased changelog.

Method Evidence

• Design doc linked or not required. feat(examples): add IR-to-Brainfuck extension generator #740 records the hill, invariants, non-goals, and witness plan; feat(extensions): publish canonical semantic-generation input and provenance contract #728 owns the underlying contract design.
• Tests or validation evidence included below.
• Playback/witness included below.
• Retro or closeout evidence included here: the separate Cargo target proved sufficient; no loader, CLI surface, target authority, or ambient I/O was needed.

Tracker Hygiene

• Linked issue had work-in-progress while active.
• Linked issue lane/status/legend labels are current.
• Follow-up work is captured as GitHub Issues, not hidden in chat or local-only backlog files. No follow-up was discovered in this slice.

Playback

Input schema:

type Query {
  ponder(question: String!): Thought!
}

type Thought {
  answer: String!
  confidence: Int!
}

cargo run --quiet -p wesley-core --example ir_to_brainfuck:

IR -> Brainfuck -> stdout
WESLEY LOWERED 2 TYPES AND 1 ROOT OPERATION. THE IR WAS BEAUTIFUL. THEN WE COMPILED IT TO BRAINFUCK. WHAT HAPPENED NEXT WAS NOT. OPERATIONS=QUERY.PONDER. SHAPE=sha256:4c9e4656fddb80f5bbebc39c4654b1ba73b91c820cd7f72ca0a048b8fd853c1b
brainfuck instructions: 17088
generation input: sha256:f9c2e9bac55593faea792bf49c3349a1fe243e3a583fe4dd13cacefba5019293
emitted program: sha256:5a895685bbf8fe174cbdf148b853fd615432fc0f795a9bb82d9bb216e6cbcfe9
provenance manifest: sha256:a9948224ef5b4013d2e0b45aa99d667e868b870ec7eafc2867c5a416ec7f622b
review authoritative: false
verified materials: 1 source / 1 output

Source-only playback emitted 17,088 bytes containing only Brainfuck instructions.

Risk

• Low runtime risk: this is an example target, not a library or CLI behavior change.
• Preflight now runs seven additional example tests, adding a small amount of test time in exchange for preventing the shipped witness from drifting.
• The interpreter rejects input instructions, malformed brackets, pointer underflow, and executions above a fixed step limit.

Backout

• Revert the merge commit. That removes the example, docs/changelog entry, and the extra example-test invocation together; no migration or generated artifact cleanup is required.

Testing

• cargo test -p wesley-core --example ir_to_brainfuck — 7 passed.
• pnpm run preflight — passed in full after final test-runner wiring.
• Push hook repeated Rust product preflight — formatting, clippy with warnings denied, docs/link/truth guards, workspace tests, example tests, doc tests, and CLI help all passed.
• cargo run --quiet -p wesley-core --example ir_to_brainfuck — playback above.
• cargo run --quiet -p wesley-core --example ir_to_brainfuck -- --source — 17,088 valid Brainfuck instruction bytes.
• Legacy package preflight not applicable: no packages/, JavaScript, or legacy tooling changed.

EvidenceMap / SourceMap (if applicable)

• Not applicable; the example lowers GraphQL SDL directly and does not map SQL or consume .wesley-cache/bundle.json.

Screenshots / Logs (optional)

• Text playback is included above; no visual surface changed.

Merge Strategy

• Merge commit only; no rebase.
• Delete branch after merge.

Checklist

• One-topic PR with tight diff
• Rust-native preflight passes (cargo xtask preflight)
• Legacy package preflight passes when relevant (not applicable)
• No widened permissions/secrets in workflows
• Docs updated if behavior changed

Summary by CodeRabbit

• New Features

  • Added a runnable example that lowers a fixed schema to canonical IR, deterministically compiles it to Brainfuck, executes it, and verifies generation provenance.
  • Added a --source mode to print only the generated Brainfuck program.

• Documentation

  • Expanded the “Runnable Example: IR To Brainfuck” reference with exact cargo run commands and an end-to-end verification flow.

• Tests

  • Updated preflight/workspace test runs to additionally include the wesley-core --example ir_to_brainfuck example tests, with stricter governance/documentation checks to prevent drift.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 691afc68-65fd-43cc-8b3b-81317667eb2a

📥 Commits

Reviewing files that changed from the base of the PR and between 79fa881 and 3837cbe.

📒 Files selected for processing (8)

• crates/wesley-core/examples/ir_to_brainfuck.rs
• docs/ARCHITECTURE.md
• docs/END_TO_END.md
• docs/TECHNICAL_TEARDOWN.md
• docs/governance/RELEASE_POLICY.md
• docs/topics/validation.md
• test/release-governance.bats
• xtask/src/main.rs

🚧 Files skipped from review as they are similar to previous changes (2)

• xtask/src/main.rs
• crates/wesley-core/examples/ir_to_brainfuck.rs

---

📝 Walkthrough

Walkthrough

Adds a standalone wesley-core example that lowers GraphQL Shape IR into deterministic Brainfuck, executes and verifies the result, tests provenance and interpreter behavior, documents usage, and includes the example in xtask test and preflight flows.

Changes

IR-to-Brainfuck example

Layer / File(s)	Summary
Generation and provenance pipeline crates/wesley-core/examples/ir_to_brainfuck.rs	Lowers a fixed schema, derives a deterministic IR message, compiles it to Brainfuck, packages provenance artifacts, and supports source-only output.
Brainfuck execution and validation crates/wesley-core/examples/ir_to_brainfuck.rs	Adds bounded wrapping-u8 execution, bracket validation, structured errors, provenance checks, replay and semantic-change tests, tamper rejection, and CLI argument coverage.
Test-runner integration xtask/src/main.rs	Runs the Brainfuck example test alongside workspace tests for xtask test and preflight, and updates the command help text.
Documentation and governance coverage docs/reference/extension-generation.md, docs/ARCHITECTURE.md, docs/END_TO_END.md, docs/governance/RELEASE_POLICY.md, docs/topics/validation.md, docs/TECHNICAL_TEARDOWN.md, CHANGELOG.md, test/release-governance.bats	Documents the example, its verification commands, and its inclusion in release and governance checks.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant ir_to_brainfuck
  participant wesley_core
  participant BrainfuckInterpreter
  User->>ir_to_brainfuck: run Cargo example
  ir_to_brainfuck->>wesley_core: lower schema and create provenance artifacts
  wesley_core-->>ir_to_brainfuck: return canonical input and generated source
  ir_to_brainfuck->>wesley_core: verify provenance
  ir_to_brainfuck->>BrainfuckInterpreter: execute generated Brainfuck
  BrainfuckInterpreter-->>ir_to_brainfuck: return decoded message
  ir_to_brainfuck-->>User: print playback and verification diagnostics

Loading

Possibly related PRs

• flyingrobots/wesley#731: Introduced the extension-generation provenance contracts exercised by this example.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the main change: adding an IR-to-Brainfuck example.
Description check	✅ Passed	The description follows the template and includes the required sections, testing, evidence, and rollout details.
Linked Issues check	✅ Passed	The PR implements #740's standalone example, deterministic playback, provenance checks, source-only mode, docs, and test wiring.
Out of Scope Changes check	✅ Passed	Changes stay focused on the example, docs, tests, and changelog; the small doc reflow is incidental.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/ir-to-brainfuck-example

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

🔍 The Case of Pull Request #741

Schema Sets

• ecommerce
• reference

Schema Set ecommerce

Plain-English Readout

• Holmes (evidence investigation): The Holmes report is unavailable because the workflow finished without a readable holmes-report.json artifact.
• Watson (independent verification): The Watson report is unavailable because the workflow finished without a readable watson-report.json artifact.
• Moriarty (trend forecast): The Moriarty forecast is unavailable because the workflow finished without a readable moriarty-report.json artifact.

Suggested next actions

1. Regenerate the HOLMES artifacts and make sure holmes-report.json is uploaded before trusting this PR summary.
2. Regenerate the WATSON artifacts and make sure watson-report.json is uploaded before trusting this PR summary.
3. Regenerate the MORIARTY artifacts and make sure moriarty-report.json is uploaded before trusting this PR summary.

🕵️ SHA-lock HOLMES full report for ecommerce (click to expand)

Report unavailable for holmes: readable holmes-report.md artifact not found.

🩺 Dr. WATSON full report for ecommerce (click to expand)

Report unavailable for watson: readable watson-report.md artifact not found.

🔮 Professor MORIARTY full report for ecommerce (click to expand)

Report unavailable for moriarty: readable moriarty-report.md artifact not found.

---

Schema Set reference

Plain-English Readout

• Holmes (evidence investigation): The Holmes report is unavailable because the workflow finished without a readable holmes-report.json artifact.
• Watson (independent verification): The Watson report is unavailable because the workflow finished without a readable watson-report.json artifact.
• Moriarty (trend forecast): The Moriarty forecast is unavailable because the workflow finished without a readable moriarty-report.json artifact.

Suggested next actions

1. Regenerate the HOLMES artifacts and make sure holmes-report.json is uploaded before trusting this PR summary.
2. Regenerate the WATSON artifacts and make sure watson-report.json is uploaded before trusting this PR summary.
3. Regenerate the MORIARTY artifacts and make sure moriarty-report.json is uploaded before trusting this PR summary.

🕵️ SHA-lock HOLMES full report for reference (click to expand)

Report unavailable for holmes: readable holmes-report.md artifact not found.

🩺 Dr. WATSON full report for reference (click to expand)

Report unavailable for watson: readable watson-report.md artifact not found.

🔮 Professor MORIARTY full report for reference (click to expand)

Report unavailable for moriarty: readable moriarty-report.md artifact not found.

---

📚 Glossary (what the Holmes terms mean)

• HOLMES: Wesley’s main evidence investigation. It decides whether the cited proof is strong enough to justify shipping this commit.
• WATSON: An independent verification pass. It checks Holmes’s citations and score math instead of trusting them blindly.
• MORIARTY: A readiness forecast over time. It is advisory trend analysis, not the release gate itself.
• Schema coverage score (SCS): How much of the schema has direct supporting evidence across generated artifacts and cited proof.
• Test confidence index (TCI): How much test evidence exists for constraints, policies, relationships, and operations.
• Migration risk index (MRI): How risky the schema change is to roll out. Lower is better.
• Evidence trust: Whether the report is backed by exact citations, whole-file citations, or coarse references. Weak trust means the claim may be directionally right but not specific enough to trust blindly.
• Citation quality: A count of exact line-span citations versus whole-file or coarse references.
• ELEMENTARY: Ready to ship based on the current evidence.
• REQUIRES INVESTIGATION: More work or review is needed before shipping.
• YOU SHALL NOT PASS: Do not ship this change in its current state.

---

Machine-readable reports are grouped by schema set in workflow artifacts.

---

Filed at 221B Repository Street

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/wesley-core/examples/ir_to_brainfuck.rs`:
- Around line 233-276: Update execute_brainfuck to validate and reject any b','
input instruction before entering the execution loop, rather than only erroring
when the instruction is reached. Preserve the existing InputUnsupported error
and offset reporting, and ensure skipped input instructions such as [,] are
rejected consistently.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 63cc7064-bd57-4c04-be33-23f0888360d6

📥 Commits

Reviewing files that changed from the base of the PR and between 4891a63 and ae674fa.

📒 Files selected for processing (4)

• CHANGELOG.md
• crates/wesley-core/examples/ir_to_brainfuck.rs
• docs/reference/extension-generation.md
• xtask/src/main.rs

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ae674fa43d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[flyingrobots]

Code Lawyer self-audit findings

ID	Severity	File	Finding	Planned correction
S1	P3	crates/wesley-core/examples/ir_to_brainfuck.rs	The source-byte test calls write_brainfuck_source directly, so changing the real --source branch back to println! would reintroduce the exact newline defect while all four tests remain green.	Route output through an injectable writer, exercise the actual source-mode dispatch, and pin the emitted bytes/digest.
S2	P4	crates/wesley-core/examples/ir_to_brainfuck.rs	The claimed pointer-underflow and execution-step defenses have no regression coverage.	Add deterministic underflow and small-limit loop tests.
S3	P4	docs/reference/extension-generation.md	The page says the example executes Brainfuck, then literally says it does not add target execution or Brainfuck semantics; the intended example-only ownership boundary is implicit.	State explicitly that those semantics stay inside the separate example crate and are not Wesley library/CLI capabilities.

@codex — second opinion requested on these self-audit findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6cde56d42f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[flyingrobots]

Code Lawyer Activity Summary

#	Source	Severity	File	Commit	Outcome
1	PR	P2	crates/wesley-core/examples/ir_to_brainfuck.rs	6cde56d4	Verified exact source bytes against the provenance digest; resolved stale GraphQL thread.
2	Self	P3	crates/wesley-core/examples/ir_to_brainfuck.rs	378686f0	Exercised real writer-backed --source dispatch and pinned SHA-256; the prior newline mutant fails deterministically.
3	Self	P4	crates/wesley-core/examples/ir_to_brainfuck.rs	69ff1580	Added deterministic pointer-underflow and small step-limit regressions; both controlled mutants fail.
4	Self	P4	docs/reference/extension-generation.md	79fa8817	Clarified that compiler/interpreter semantics remain owned by the separate example crate.

Verification

• cargo test -p wesley-core --example ir_to_brainfuck: 6 passed
• cargo xtask docs-check: passed
• pnpm run preflight: passed in full
• pre-push Rust product preflight: passed in full
• --source stdout: 17,088 bytes, SHA-256 5a895685bbf8fe174cbdf148b853fd615432fc0f795a9bb82d9bb216e6cbcfe9, identical to the provenance-reported emitted-program digest
• Worktree: clean after normal push to agent/ir-to-brainfuck-example

[flyingrobots]

Code Lawyer supplemental self-audit finding

ID	Severity	File	Finding	Planned correction
S4	P4	crates/wesley-core/examples/ir_to_brainfuck.rs	env::args() panics before usage validation when Unix argv contains non-UTF-8 bytes. The runnable example must reject malformed arguments through its existing InvalidInput path instead of aborting.	Parse OsString arguments and add a Unix non-UTF-8 regression.

@codex — second opinion requested on this supplemental finding.

[flyingrobots]

Code Lawyer Activity Summary — Final

This supersedes the earlier four-item summary.

#	Source	Severity	Surface	Commit	Outcome
1	PR	P2	crates/wesley-core/examples/ir_to_brainfuck.rs	6cde56d4	Verified exact source bytes against the provenance digest; resolved stale GraphQL thread.
2	PR + Self	P3	crates/wesley-core/examples/ir_to_brainfuck.rs	378686f0	Exercised real writer-backed --source dispatch and pinned SHA-256; resolved the duplicate Codex thread.
3	Self	P4	crates/wesley-core/examples/ir_to_brainfuck.rs	69ff1580	Added deterministic pointer-underflow and small step-limit regressions.
4	Self	P4	docs/reference/extension-generation.md	79fa8817	Clarified that compiler/interpreter semantics remain owned by the separate example crate.
5	Self	P4	crates/wesley-core/examples/ir_to_brainfuck.rs	305b4fca	Replaced UTF-8-only argv parsing with OsString; invalid Unix bytes now return the usage error instead of panicking.
6	Self	P3	Issue #740 metadata	—	OPEN: requires human selection of exactly one scheduling-state label and the intended goalpost milestone.

Final local verification

• cargo test -p wesley-core --example ir_to_brainfuck: 7 passed
• cargo xtask docs-check: passed
• pnpm run preflight: passed in full after the final commit
• pre-push Rust product preflight: passed in full after the final commit
• --source stdout: 17,088 bytes, SHA-256 5a895685bbf8fe174cbdf148b853fd615432fc0f795a9bb82d9bb216e6cbcfe9, identical to the provenance-reported emitted-program digest
• Worktree: clean after normal push to agent/ir-to-brainfuck-example
• Current-head CI and CodeRabbit: green
• Review threads: 0 unresolved
• Merge gate: locked on roadmap metadata and 0/2 required approvals

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 79fa881793

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[flyingrobots]

Code Lawyer governance finding

ID	Severity	Surface	Finding	Required disposition
S5	P3	Issue #740 / PR tracker-hygiene assertion	Open implementation issue #740 has zero scheduling-state labels: neither one triage:* label nor one vX.Y.Z label. It also has no Goalpost: ... milestone. This violates docs/METHOD.md and docs/topics/contributing/triage.md, and makes the checked PR statement that lane/status metadata is current false.	A roadmap owner must assign exactly one scheduling-state label and the intended goalpost milestone. Parent #728 does not supply an objective choice, so the auditor will not guess.

@codex — second opinion requested on this governance finding.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 305b4fcaaa

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Assign #740 scheduling and goalpost metadata

While implementation issue #740 remains open, it has neither a triage:* nor a vX.Y.Z scheduling-state label and has no Goalpost: ... milestone. This violates the slice and label invariants in docs/METHOD.md:42,69-70 and docs/topics/contributing/triage.md:43-53, and makes the PR's checked tracker-hygiene assertion inaccurate; a roadmap owner should select exactly one scheduling label and the intended goalpost rather than inferring them from parent #728.

Useful? React with 👍 / 👎.

[flyingrobots]

Code Lawyer supplemental self-audit finding

ID	Severity	Surface	Finding	Planned correction
S6	P4	xtask/src/main.rs; docs/ARCHITECTURE.md; docs/END_TO_END.md; docs/TECHNICAL_TEARDOWN.md; docs/topics/validation.md	cargo xtask test and preflight now execute the Brainfuck example test after cargo test --workspace, but the CLI help and current preflight maps still enumerate only workspace tests. The same topology drift identified in RELEASE_POLICY.md therefore exists across the documented operator and architecture surfaces.	Update every current exact preflight enumeration and add a deterministic regression that pins the ordered release-policy sequence.

@codex — second opinion requested on this supplemental finding.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 305b4fcaaa

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[flyingrobots]

Code Lawyer Activity Summary — Review Rerun

#	Source	Severity	Surface	Commit	Outcome
1	PR	P3	crates/wesley-core/examples/ir_to_brainfuck.rs argv path	305b4fca	Verified the Unix invalid-byte regression in isolation; the process returns InvalidInput without panic; GraphQL thread resolved.
2	PR + Self S6	P3 / P4	strict-preflight policy, architecture maps, operator docs, CLI help	3837cbe7	Added a RED governance regression, documented the explicit example-test step everywhere current, passed GREEN verification, and resolved the policy thread and its late duplicate.
3	PR	P3	PR Playback / Risk / Testing evidence	—	Refreshed the manifest digest to sha256:a9948224ef5b4013d2e0b45aa99d667e868b870ec7eafc2867c5a416ec7f622b, corrected both test counts to seven, reproduced exact playback equality, and resolved the thread.
4	PR + Self S5	P3	Issue #740 scheduling metadata	—	OPEN: zero triage:* or vX.Y.Z labels and no Goalpost: ... milestone. Available evidence selects neither value, so roadmap-owner input remains required.

Verification

• Focused RED: strict-preflight documentation regression failed before correction.
• Focused GREEN: regression passed after correction.
• Release-governance Bats: 24/24 passed.
• cargo test -p xtask: 46/46 passed.
• cargo xtask docs-check: passed.
• pnpm run preflight: passed in full.
• Pre-push Rust product preflight and repository Bats smoke suite: passed in full.
• Branch: clean, pushed, and synchronized at 3837cbe7.
• Review threads: one intentionally unresolved governance thread remains.
• Current-head CI and CodeRabbit: 20/20 checks passed; CodeRabbit completed without cooldown.
• Reviews: 0 approvals, 0 changes requested.