pure-borrow: Instructions file for Claude Code

AGENTS.md

This file is the source of truth for coding-agent guidance in this repository. Keep agent-agnostic project instructions here, and keep tool-specific files as thin adapters. CLAUDE.md is intentionally a symlink to this file so Claude Code and Codex read the same repository policy.

Overview

pure-borrow realizes Rust-style borrowing in Linear Haskell, purely — compile-time ownership and memory safety with no runtime overhead, plus safe deterministic parallelism. It is the artifact of the paper Pure Borrow: Linear Haskell Meets Rust-Style Borrowing (Y. Matsushita & H. Ishii, PLDI 2026; arXiv:2604.15290). The package is already released on Hackage (latest release 0.1.0.0); current work is incremental improvement (notably performance) of a published, paper-backed library — so preserve the public API and the soundness invariants unless a change is deliberate.

Control.Monad.Borrow.Pure is the umbrella module and carries the full Haddock tutorial; read it before designing changes to the core.

Language & toolchain

• GHC 9.10.2+ required (Linear Types); 9.12.4+ recommended — pinned locally to ghc-9.12.4 via cabal.project.local. tested-with: 9.10.3 || 9.12.4 || 9.14.1.
• default-language: GHC2021, with LinearTypes enabled by default everywhere.
• Interpreter caveat: GHC < 9.12.3 segfaults evaluating some linear programs in GHCi / the HLS eval plugin (a compiler bug). Compiled code is fine on 9.10.2+. Use 9.12.3+ if you need the REPL. The pure-borrow-doctests suite is disabled for GHC < 9.12.3.
• Cabal nix-style builds only; cabal.project (+ cabal.project.local) is the source of truth. Do not use stack or invoke ghc directly. cabal-install ≥ 3.14.2 recommended.

Build / test / bench / run

cabal.project sets the +examples flag and cabal.project.local enables tests+benchmarks, so locally every component below is buildable.

cabal build all                       # build the library + all enabled components
cabal build pure-borrow               # just the library

cabal test                            # run all test suites
cabal test pure-borrow-test           # main tasty suite only
cabal test pure-borrow-doctests       # doctests (needs GHC >= 9.12.3)

cabal bench qsort-bench               # parallel quicksort benchmark (tasty-bench)
cabal bench fft-bench                 # parallel FFT benchmark (tasty-bench)
cabal bench pure-borrow-bench         # all single-threaded micro-benchmarks (needs -j1)

cabal run qsort -- --help             # quicksort demo executable (needs +examples)
cabal run fft   -- --help             # FFT demo executable (needs +examples)