integrations/haskell/notes/001-garnet.md

# Garnet findings

Date: 2026-03-24
Path inspected: `./tmp/garnet`

## Plain-English summary

`./tmp/garnet` is a small experiment for calling Rust from Haskell.

The flow is:

1. Define Rust functions and data types.
2. Export them as a C ABI.
3. Generate a C header with `cbindgen`.
4. Generate Haskell-side low-level bindings with `hs-bindgen`.
5. Add hand-written Haskell wrappers on top.
6. Run a demo executable to show the setup works.

This looks like a prototype or reference repo, not a finished product.

## What it is

This is a mixed Haskell/Rust FFI demo.

It contains:

- a Cabal package named `garnet`
- a Rust static library in `./tmp/garnet/rust`
- Haskell modules for raw bindings and higher-level wrappers
- a small executable that exercises the API
- a shell build script
- a Nix flake for the development environment

## What it is trying to prove

The repo appears to be testing whether this toolchain is practical:

Rust -> `cbindgen` -> C header -> `hs-bindgen` -> Haskell wrappers

It also tests whether the approach can handle more than trivial examples, including:

- C strings
- plain structs
- enums
- simple arithmetic
- recursive tree-shaped data

## Key files

- `./tmp/garnet/rust/lib.rs`
  - Rust definitions for exported FFI functions and example types
- `./tmp/garnet/rust/build.rs`
  - generates `garnet_rs.h` and patches it for compatibility with `hs-bindgen`
- `./tmp/garnet/lib/GarnetRs/Raw.hs`
  - drives low-level binding generation from the generated header
- `./tmp/garnet/lib/GarnetRs/Wrapped.hs`
  - adds Haskell-friendly wrapper types and conversion code
- `./tmp/garnet/exe/Main.hs`
  - demo executable using the wrapper API
- `./tmp/garnet/build`
  - custom build script for Rust + Cabal coordination

## Easy reading of the design

### Rust side

The Rust library exports a handful of example FFI functions:

- `hello`
- `hello_struct`
- `hello_shape`
- `add`
- `sum_tree`

These are not a product API. They are examples chosen to stress different interop cases.

### Haskell side

The Haskell code is split into two layers:

- `GarnetRs.Raw`
  - low-level generated bindings
- `GarnetRs.Wrapped`
  - nicer Haskell-facing types and functions

This separation is a good design choice. It keeps generated code concerns away from the public API.

## Critical assessment

This repo is technically promising, but clearly unfinished.

What looks good:

- It demonstrates the full end-to-end workflow.
- It goes beyond the easiest possible FFI examples.
- It keeps raw and wrapped APIs separate.
- It includes a dev shell, which improves reproducibility.

What looks weak:

- The build flow is manual and somewhat brittle.
- The project depends on pinned git sources and alpha-stage tooling.
- The Rust build script contains a workaround for upstream tooling issues.
- The Haskell wrapper layer still requires manual boilerplate.
- There is no obvious sign of tests, CI, or a stability story.

## Pros of the approach

- **Clear architecture**: raw bindings and ergonomic wrappers are separated well.
- **Good exploration value**: useful for learning the actual friction points in Rust/Haskell interop.
- **Covers realistic cases**: includes enums and recursive data, not just simple integers.
- **Small and understandable**: the repo is compact enough to inspect quickly.
- **Useful as a reference**: someone exploring `hs-bindgen` could learn from it.

## Cons of the approach

- **Custom build glue**: the shell script and symlink step suggest the toolchain is not yet smooth.
- **Dependency fragility**: pinned git dependencies increase maintenance burden.
- **Tooling immaturity**: the repo already needs local workarounds for upstream issues.
- **Manual wrapper overhead**: generated bindings do not remove the need for hand-written API cleanup.
- **Potential safety complexity**: FFI, pointer conversions, and `unsafe` code are easy to get wrong.
- **Weak production story**: this setup does not yet look ready for long-term team use.

## Status of the work

My assessment of current status:

- **Stage**: proof of concept / exploration
- **Scope**: enough code exists to show the full path works
- **Maturity**: decent as an experiment, weak as a reusable foundation
- **Stability**: uncertain because of upstream pins and workarounds
- **Readiness**: not production-ready

In simple terms: this looks like “we got it working” rather than “we finished the system.”

## Likely next problems if this grows

If someone tried to turn this into a serious integration layer, the next hard problems would likely be:

- making the build process less custom
- reducing wrapper boilerplate
- keeping generated headers and bindings in sync
- handling more complex Rust types safely
- upgrading upstream tooling without breakage
- adding tests that catch FFI regressions early

## Bottom line

`./tmp/garnet` is a useful and interesting interop prototype.

It succeeds as a demonstration that Rust -> C header -> Haskell bindings -> Haskell wrapper can work. But it also shows the current cost of that path: manual build glue, unstable dependencies, wrapper code, and reliance on tool-specific workarounds.

Overall: good experiment, useful reference, not mature infrastructure yet.