Roundhouse Docs
Working on Roundhouse View Markdown

docs/ — map

The user guide is guide/ — install, and one door each for analyzing, transpiling and compiling a Rails app. Everything below is for people working on roundhouse itself.

Use the current code and executed checks for current behavior; RELEASES.md records dated release snapshots. Architecture references explain design, while working plans are point-in-time proposals.

Working on Roundhouse

Compiler inputs — data/

  • ruby-and-erb.md — Ruby + template ingest: Prism, the ERB/HAML compile-to-Ruby seam, surface preservation, strict vs survey mode.
  • schema-routes-seeds.md — the declarative inputs: schema (and migration fallback), routes, seeds, fixtures, importmap, RBS sidecars.
  • catalog.md — the method catalog: one IDL-shaped table for the Active Record surface, plus the gem catalog.
  • adapter.md — the DatabaseAdapter trait: effect classification and async coloring per database backend.

Pipeline internals — pipeline/

  • analyze.md — type + effect inference.
  • lower.md — target-neutral lowerings and the post-analyze pass pipeline.
  • specialization.md — every target as a specializer of Rails: the shared decision procedure, and the residue policies (forbidden, runs on Rails, handed to a person) that tell the strict targets, futamura and roda apart; and futamura's whole-route replacement, which serves the routes the analysis clears from the lowered app in a Ruby::Box inside Rails.
  • fractal.md — fractal emit compiles the files named with --file and writes only changed files. fractal apply overwrites those files in the base app. Rails runs the result with unchanged line numbers. The build checks each rewrite's assumptions.
  • emit.md — per-target emitters and the shared emit machinery.
  • runtime.md — the two-layer runtime (per-target primitives + transpiled framework Ruby), including the semantic-divergence ledger.
  • verification.md — how we know the output is correct: evidence layers and their limits, not CI job topology.
  • bytecode.md — experimental bytecode target; parked, test-only.

Reference

  • writebook.md — pinned external-corpus inventory and its limits.
  • ractor-ledger.md — what stops campfire's CRuby emit from serving on worker Ractors, by owner (dated snapshot).

Working plans

Point-in-time design documents; each records its own status at the top. When one completes, it moves to archive/.

archive/

Completed or superseded plans, kept as historical design records (browser demo, the rust/kotlin/swift/csharp emitter migrations, the jbuilder lowerer, maintainability refactor phase 1, and the rust-migration spike crates). Accurate about the decisions they made; not maintained against the current tree.