feat(codegen): rewrite Chapel/Zig/header generators with real distribution logic

Phase 1 of chapeliser implementation — the codegen now produces:

- Chapel: compilable .chpl with real coforall distribution, 5 partition
  strategies (per-item, chunk, adaptive/DynamicIters, spatial/BlockDist,
  keyed), 5 gather strategies (merge, reduce, tree-reduce, stream, first),
  buffer-based cross-locale data transfer, retry logic, checkpoint support
- Zig FFI: buffer-based C-ABI bridge (not pointer-based), delegates to
  user's workload-specific functions, 12 Chapel-facing exports
- C header: full FFI contract with lifecycle (init/shutdown), data I/O
  (load_item/store_result), processing, reduction, match, key hash,
  and checkpoint functions
- Build script: environment variable overrides, Chapel config passthrough

Split codegen/mod.rs into 4 submodules (chapel.rs, zig.rs, header.rs,
build_script.rs). Tests expanded from 6 to 9 — all passing.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

src/codegen/build_script.rs

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+//
+// Build script generator for Chapeliser.
+//
+// Generates a bash script that compiles all generated artifacts:
+//   1. Zig FFI bridge → .o object file
+//   2. User's application → .o or .a (user-specific, documented in comments)
+//   3. Chapel wrapper + FFI object + user code → distributed binary
+//
+// The build script also supports environment variable overrides for
+// cross-compilation and cluster-specific Chapel configurations.
+
+use anyhow::{Context, Result};
+use std::fmt::Write as FmtWrite;
+use std::fs;
+use std::path::Path;
+
+use crate::manifest::Manifest;
+
+/// Generate the build script from a manifest.
+/// Writes to `output_dir/build.sh` (executable).
+pub fn generate(manifest: &Manifest, output_dir: &Path) -> Result<()> {
+    let name = &manifest.workload.name;
+    let safe_name = name.replace('-', "_");
+
+    let mut src = String::with_capacity(2048);
+
+    writeln!(src, "#!/usr/bin/env bash")?;
+    writeln!(src, "# SPDX-License-Identifier: PMPL-1.0-or-later")?;
+    writeln!(src, "# Auto-generated by Chapeliser — build script for workload: {name}")?;
+    writeln!(src, "# Regenerate with: chapeliser generate")?;
+    writeln!(src)?;
+    writeln!(src, "set -euo pipefail")?;
+    writeln!(src)?;
+
+    // Environment variable overrides
+    writeln!(src, "# Override these environment variables for your setup:")?;
+    writeln!(src, "#   ZIG        — path to zig compiler (default: zig)")?;
+    writeln!(src, "#   CHPL       — path to Chapel compiler (default: chpl)")?;
+    writeln!(src, "#   USER_LIB   — path to user's compiled library (.a or .o)")?;
+    writeln!(src, "#   CHPL_FLAGS — extra Chapel compiler flags")?;
+    writeln!(src, "ZIG=${{ZIG:-zig}}")?;
+    writeln!(src, "CHPL=${{CHPL:-chpl}}")?;
+    writeln!(src, "USER_LIB=${{USER_LIB:-}}")?;
+    writeln!(src, "CHPL_FLAGS=${{CHPL_FLAGS:-}}")?;
+    writeln!(src)?;
+
+    writeln!(src, "echo \"=== Chapeliser Build: {name} ===\"")?;
+    writeln!(src)?;
+
+    // Step 1: Compile Zig FFI bridge
+    writeln!(src, "# Step 1: Compile the Zig FFI bridge to a C-ABI object file")?;
+    writeln!(src, "echo \"[1/3] Compiling Zig FFI bridge...\"")?;
+    writeln!(
+        src,
+        "$ZIG build-obj -O ReleaseFast zig/{safe_name}_ffi.zig -femit-bin={safe_name}_ffi.o"
+    )?;
+    writeln!(src)?;
+
+    // Step 2: User code
+    writeln!(src, "# Step 2: Link user's application code")?;
+    writeln!(src, "echo \"[2/3] Checking user code...\"")?;
+    writeln!(src, "if [ -z \"$USER_LIB\" ]; then")?;
+    writeln!(src, "  echo \"  WARNING: USER_LIB not set. You must provide your compiled application.\"")?;
+    writeln!(src, "  echo \"  For Rust: cargo build --release && export USER_LIB=target/release/lib{safe_name}.a\"")?;
+    writeln!(src, "  echo \"  For C:    gcc -c -O2 your_code.c -o user_code.o && export USER_LIB=user_code.o\"")?;
+    writeln!(src, "  echo \"  For Zig:  zig build-obj -O ReleaseFast your_code.zig && export USER_LIB=your_code.o\"")?;
+    writeln!(src, "  exit 1")?;
+    writeln!(src, "fi")?;
+    writeln!(src)?;
+    writeln!(src, "if [ ! -f \"$USER_LIB\" ]; then")?;
+    writeln!(src, "  echo \"  ERROR: USER_LIB=$USER_LIB not found\"")?;
+    writeln!(src, "  exit 1")?;
+    writeln!(src, "fi")?;
+    writeln!(src, "echo \"  Using: $USER_LIB\"")?;
+    writeln!(src)?;
+
+    // Step 3: Chapel compilation
+    writeln!(src, "# Step 3: Compile the Chapel distributed wrapper")?;
+    writeln!(src, "echo \"[3/3] Compiling Chapel wrapper...\"")?;
+
+    // Build Chapel compile command with appropriate flags
+    if manifest.resilience.checkpoint {
+        writeln!(src, "# Checkpointing enabled — Chapel needs IO support")?;
+    }
+
+    let mut chpl_cmd = format!(
+        "$CHPL --fast -I include/ chapel/{safe_name}_distributed.chpl {safe_name}_ffi.o \"$USER_LIB\""
+    );
+
+    // Add Chapel config from manifest
+    if let Some(ref comm) = manifest.chapel.comm_layer {
+        writeln!(src, "export CHPL_COMM={comm}")?;
+    }
+
+    for flag in &manifest.chapel.compiler_flags {
+        chpl_cmd.push(' ');
+        chpl_cmd.push_str(flag);
+    }
+
+    if manifest.chapel.gpu_enabled {
+        chpl_cmd.push_str(" --set gpuEnabled=true");
+    }
+
+    chpl_cmd.push_str(" $CHPL_FLAGS");
+    chpl_cmd.push_str(&format!(" -o {safe_name}_distributed"));
+
+    writeln!(src, "{chpl_cmd}")?;
+    writeln!(src)?;
+
+    // Success message
+    writeln!(src, "echo \"=== Build complete: ./{safe_name}_distributed ===\"")?;
+    writeln!(src, "echo \"Run with: ./{safe_name}_distributed -nl <num_locales>\"")?;
+    writeln!(src, "echo \"  --totalItems=N       override item count\"")?;
+    writeln!(src, "echo \"  --maxItemBytes=N     override max buffer size\"")?;
+    writeln!(src, "echo \"  --grainSize=N        override chunk grain size\"")?;
+    writeln!(src, "echo \"  --maxRetries=N       override retry limit\"")?;
+    writeln!(src, "echo \"  --enableCheckpoint   enable checkpointing\"")?;
+
+    let out_path = output_dir.join("build.sh");
+    fs::write(&out_path, &src)
+        .with_context(|| format!("Failed to write build script: {}", out_path.display()))?;
+
+    // Make executable
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        let mut perms = fs::metadata(&out_path)?.permissions();
+        perms.set_mode(0o755);
+        fs::set_permissions(&out_path, perms)?;
+    }
+
+    println!("  Build script:   {}", out_path.display());
+    Ok(())
+}

src/codegen/header.rs

@@ -0,0 +1,148 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
+//
+// C header generator for Chapeliser.
+//
+// Generates the C header that declares all functions the user must implement.
+// This is the contract between the user's application code and the Chapeliser
+// runtime (Chapel wrapper + Zig FFI bridge).
+
+use anyhow::{Context, Result};
+use std::fmt::Write as FmtWrite;
+use std::fs;
+use std::path::Path;
+
+use crate::manifest::Manifest;
+
+/// Generate the C header from a manifest.
+/// Writes to `output_dir/include/<name>_chapeliser.h`.
+pub fn generate(manifest: &Manifest, output_dir: &Path) -> Result<()> {
+    let name = &manifest.workload.name;
+    let safe_name = name.replace('-', "_");
+    let upper = safe_name.to_uppercase();
+
+    let mut src = String::with_capacity(4096);
+
+    writeln!(src, "/* SPDX-License-Identifier: PMPL-1.0-or-later */")?;
+    writeln!(src, "/* Auto-generated by Chapeliser — do not edit manually. */")?;
+    writeln!(src, "/* C header for workload: {name} */")?;
+    writeln!(src, "/* Regenerate with: chapeliser generate */")?;
+    writeln!(src)?;
+    writeln!(src, "#ifndef CHAPELISER_{upper}_H")?;
+    writeln!(src, "#define CHAPELISER_{upper}_H")?;
+    writeln!(src)?;
+    writeln!(src, "#include <stddef.h>")?;
+    writeln!(src, "#include <stdint.h>")?;
+    writeln!(src)?;
+    writeln!(src, "#ifdef __cplusplus")?;
+    writeln!(src, "extern \"C\" {{")?;
+    writeln!(src, "#endif")?;
+    writeln!(src)?;
+
+    // Documentation block
+    writeln!(src, "/*")?;
+    writeln!(src, " * Chapeliser FFI contract for workload: {name}")?;
+    writeln!(src, " *")?;
+    writeln!(src, " * Implement these functions with C linkage in your application.")?;
+    writeln!(src, " * Chapeliser's generated Chapel + Zig code calls them at runtime.")?;
+    writeln!(src, " *")?;
+    writeln!(src, " * Return values: 0 = success, non-zero = error code.")?;
+    writeln!(src, " *")?;
+    writeln!(src, " * For Rust:  #[no_mangle] pub extern \"C\" fn {safe_name}_init() -> i32 {{ ... }}")?;
+    writeln!(src, " * For Zig:   export fn {safe_name}_init() callconv(.C) c_int {{ ... }}")?;
+    writeln!(src, " * For C:     int {safe_name}_init(void) {{ ... }}")?;
+    writeln!(src, " */")?;
+    writeln!(src)?;
+
+    // --- Lifecycle ---
+    writeln!(src, "/* ---- Lifecycle ---- */")?;
+    writeln!(src)?;
+    writeln!(src, "/* Initialise the workload. Called once on locale 0 before processing. */")?;
+    writeln!(src, "int {safe_name}_init(void);")?;
+    writeln!(src)?;
+    writeln!(src, "/* Shut down the workload. Called once on locale 0 after all results stored. */")?;
+    writeln!(src, "int {safe_name}_shutdown(void);")?;
+    writeln!(src)?;
+
+    // --- Data I/O ---
+    writeln!(src, "/* ---- Data I/O ---- */")?;
+    writeln!(src)?;
+    writeln!(src, "/* Return the total number of input items. Called on locale 0. */")?;
+    writeln!(src, "int {safe_name}_get_total_items(void);")?;
+    writeln!(src)?;
+    writeln!(src, "/* Serialise input item `idx` into `buf`. Set `*len` to bytes written. */")?;
+    writeln!(src, "/* `buf` has capacity {max_bytes} bytes (from manifest max-item-bytes). */",
+        max_bytes = manifest.data.max_item_bytes.unwrap_or(1_048_576))?;
+    writeln!(src, "int {safe_name}_load_item(int idx, uint8_t* buf, size_t* len);")?;
+    writeln!(src)?;
+    writeln!(src, "/* Receive a processed result. `buf` contains `len` serialised bytes. */")?;
+    writeln!(src, "int {safe_name}_store_result(int idx, const uint8_t* buf, size_t len);")?;
+    writeln!(src)?;
+
+    // --- Processing ---
+    writeln!(src, "/* ---- Processing ---- */")?;
+    writeln!(src)?;
+    writeln!(src, "/* Process a single serialised item. Read from in_buf/in_len, */")?;
+    writeln!(src, "/* write result to out_buf, set *out_len. Called on any locale. */")?;
+    writeln!(src, "int {safe_name}_process_item(")?;
+    writeln!(src, "    const uint8_t* in_buf, size_t in_len,")?;
+    writeln!(src, "    uint8_t* out_buf, size_t* out_len")?;
+    writeln!(src, ");")?;
+    writeln!(src)?;
+    writeln!(src, "/* Process a chunk of items (for chunk partition strategy). */")?;
+    writeln!(src, "int {safe_name}_process_chunk(")?;
+    writeln!(src, "    const uint8_t* items_buf, int item_count,")?;
+    writeln!(src, "    const int* item_offsets, const int* item_sizes,")?;
+    writeln!(src, "    uint8_t* out_buf, size_t* out_len")?;
+    writeln!(src, ");")?;
+    writeln!(src)?;
+
+    // --- Reduction ---
+    writeln!(src, "/* ---- Reduction (for reduce/tree-reduce gather) ---- */")?;
+    writeln!(src)?;
+    writeln!(src, "/* Combine two results into one. */")?;
+    writeln!(src, "int {safe_name}_reduce(")?;
+    writeln!(src, "    const uint8_t* a_buf, size_t a_len,")?;
+    writeln!(src, "    const uint8_t* b_buf, size_t b_len,")?;
+    writeln!(src, "    uint8_t* out_buf, size_t* out_len")?;
+    writeln!(src, ");")?;
+    writeln!(src)?;
+
+    // --- Match predicate ---
+    writeln!(src, "/* ---- Match predicate (for 'first' gather) ---- */")?;
+    writeln!(src)?;
+    writeln!(src, "/* Return 1 if result satisfies the search criterion, 0 otherwise. */")?;
+    writeln!(src, "int {safe_name}_is_match(const uint8_t* buf, size_t len);")?;
+    writeln!(src)?;
+
+    // --- Key hash ---
+    writeln!(src, "/* ---- Key hash (for keyed partition) ---- */")?;
+    writeln!(src)?;
+    writeln!(src, "/* Return a hash of the item's key for distribution routing. */")?;
+    writeln!(src, "unsigned int {safe_name}_key_hash(const uint8_t* buf, size_t len);")?;
+    writeln!(src)?;
+
+    // --- Checkpoint ---
+    writeln!(src, "/* ---- Checkpoint (optional) ---- */")?;
+    writeln!(src)?;
+    writeln!(src, "/* Save checkpoint data. Return -1 if not implemented. */")?;
+    writeln!(src, "int {safe_name}_checkpoint_save(const uint8_t* buf, size_t len, const char* tag);")?;
+    writeln!(src)?;
+    writeln!(src, "/* Load checkpoint data. Return -1 if not implemented. */")?;
+    writeln!(src, "int {safe_name}_checkpoint_load(uint8_t* buf, size_t* len, const char* tag);")?;
+    writeln!(src)?;
+
+    // Close
+    writeln!(src, "#ifdef __cplusplus")?;
+    writeln!(src, "}}")?;
+    writeln!(src, "#endif")?;
+    writeln!(src)?;
+    writeln!(src, "#endif /* CHAPELISER_{upper}_H */")?;
+
+    let out_path = output_dir.join(format!("{}_chapeliser.h", safe_name));
+    fs::write(&out_path, &src)
+        .with_context(|| format!("Failed to write C header: {}", out_path.display()))?;
+    println!("  C header:       {}", out_path.display());
+
+    Ok(())
+}