fix(chapel-binding): real-Chapel-2.x typecheck + WIRED-subset zig build fix (#141)

## Summary

Follow-up fix for the chapel binding-tier-1 pilot landed in #135 — its
first CI run on the Chapel CI workflow failed for three real reasons,
all of which were hiding behind the binding's never-having-been-compiled
state.

Locally validated end-to-end with `chpl 2.8.0` + `zig 0.15.2` against a
freshly-built libproven.so:

```
chapel-symbol-audit: PASS 5 / FAIL 0
hello_smoke:        OK (libproven 0.1.0)
TestFfiContract:    OK
TestLibraryInfo:    OK (version=0.1.0)
TestSafeHeader:     OK
TestSafePath:       OK
```

## Three root causes

### 1. `T?` syntax is class-only — every Safe*.chpl module was broken

The pre-existing binding used Chapel's `T?` postfix on value-type
returns (`bool?`, `int(64)?`, `string?`). That syntax is class-only
in Chapel 2.x — every Safe*.chpl module failed to typecheck. This is
the deep finding behind the brief's "well-written code, never linked"
diagnosis: the binding had never been compiled, full stop.

**Fix:** added a `Maybe(T)` generic record to `LibProven.chpl` with
constructors `some(v)` and `absent(T)`. (`absent` rather than
`none`/`nothing` because both of those are Chapel reserved words.)
Rewrote every Safe*.chpl wrapper + smoke + 3 tests to use it.

`Proven.chpl` adds `public import SafePath/SafeHeader/LibProven` so
callers can write `SafePath.hasTraversal(...)` as a qualified
reference (`public use` alone does not bring the module name in
scope as a qualifier).

`enum ProvenStatus : int(32) { ... }` typed-enum syntax was also
removed in Chapel 2.x; dropped the type spec. `extractString` /
`cStringToChapel` switched to `try!` for the now-throwing
`string.createCopyingBuffer`.

### 2. `ffi/zig/build.zig` depends on a missing repo

`hyperpolymath/idris2-zig-ffi` returns 404 to authenticated `gh`.
The same break blocks `zig-ffi.yml` on main; resolving the upstream
dep is out of scope for the Chapel pilot.

All exports in `ffi/zig/src/main.zig` are pure-Zig (only `@import
(\"std\")` + `@import(\"builtin\")`); none consume the
`idris2_zig_ffi` module. Switched `chapel-build` to compile
`main.zig` directly via `zig build-lib -dynamic -lc`, producing a
libproven.so with the WIRED 5 symbols.

`build.zig.zon` declares `minimum_zig_version = \"0.15.2\"`; bumped
the CI's pinned Zig from 0.13.0 → 0.15.2 to match.

### 3. `proven.h` missing `proven_version` / `proven_build_info`

`chpl` performs extern-decl resolution against included C headers
and errors when an `extern \"proven_X\"` references a symbol not
declared in any `-I`-supplied header. `proven_version` and
`proven_build_info` ARE exported by `ffi/zig/src/main.zig` (always
have been) but were absent from `proven.h`.

Added two declarations to `bindings/c/include/proven.h`. These do
NOT introduce new Zig exports — they document functions `main.zig`
has been shipping all along.

## Diff scope

18 files changed: chapel-ci.yml, proven.h, README.adoc, every
`bindings/chapel/src/*.chpl`, smoke + 3 tests. Detachability is
preserved — every change is inside the detachable file set
(`bindings/chapel/**`, `bindings/c/include/proven.h`, the
workflow).

## Test plan

- [ ] CI: `detachability-guard` GREEN
- [ ] CI: `chapel-build` GREEN — Zig 0.15.2 + `zig build-lib -lc` builds
libproven.so containing WIRED 5
- [ ] CI: `chapel-symbol-audit` PASS 5 / FAIL 0
- [ ] CI: `chapel-smoke` exit-0
- [ ] CI: `chapel-tests` — all 4 tests GREEN
- [ ] CI: `chapel-detachable-build` builds + tests from sparse checkout
- [ ] Auto-merge armed

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: hyperpolymath

.github/workflows/chapel-ci.yml

@@ -54,11 +54,19 @@ concurrency:
 env:
   # Pinned Chapel deb (Ubuntu 22.04 amd64).  SHA-256 verified out-of-band
   # against the GitHub Releases asset; mismatch fails the install step.
-  CHAPEL_VERSION: '2.3.0'
-  CHAPEL_DEB_URL: 'https://github.com/chapel-lang/chapel/releases/download/2.3.0/chapel-2.3.0-1.ubuntu22.amd64.deb'
-  CHAPEL_DEB_SHA256: 'b7c1a48cbf26cfc7ad9af22a84ea4becb1a5e2fd485ec4a1f5f8a69e8a7cd58c'
+  # 2.8.0 (not 2.3.0): the 2.3.0 .deb is slim and omits the bundled LLVM
+  # backend, so `chpl ... -lproven` fails the link phase with the cryptic
+  # `error in exec: No such file or directory` when chpl tries to spawn a
+  # clang/lld it doesn't ship.  2.8.0 ships a self-contained toolchain and
+  # matches the version the PR author validated against locally — same
+  # version proven's sister panic-attack repo's chapel-ci runs on.
+  CHAPEL_VERSION: '2.8.0'
+  CHAPEL_DEB_URL: 'https://github.com/chapel-lang/chapel/releases/download/2.8.0/chapel-2.8.0-1.ubuntu22.amd64.deb'
+  CHAPEL_DEB_SHA256: '944a454b8a791f344312fcd261b562871159b74f5ef41d81e11833eb21d85f60'
   # Pinned Zig version (kept in sync with .github/workflows/zig-ffi.yml).
-  ZIG_VERSION: '0.13.0'
+  # Pinned Zig version.  Matches ffi/zig/build.zig.zon's
+  # `minimum_zig_version = "0.15.2"`.
+  ZIG_VERSION: '0.15.2'
 
 jobs:
   # ==========================================================================
@@ -124,42 +132,88 @@ jobs:
         with:
           path: proven
 
-      - name: Checkout idris2-zig-ffi dependency
-        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
-        with:
-          repository: hyperpolymath/idris2-zig-ffi
-          path: idris2-zig-ffi
-
       - name: Setup Zig ${{ env.ZIG_VERSION }}
         uses: mlugg/setup-zig@e7d1537c378b83b8049f65dda471d87a2f7b2df2 # v1
         with:
           version: ${{ env.ZIG_VERSION }}
 
-      - name: Build libproven.so via Zig
+      - name: Build libproven.so (WIRED-subset fixture)
         working-directory: proven/ffi/zig
-        run: zig build -Dtarget=x86_64-linux-gnu
+        # NOTE: ffi/zig/build.zig depends on `idris2_zig_ffi` (relative
+        # path to a sibling estate repo).  That dep is not resolvable
+        # from a fresh clone in CI (the same issue blocks zig-ffi.yml on
+        # main), and resolving it is out of scope for the Chapel pilot.
+        # All exports in src/main.zig are pure-Zig — none consume
+        # idris2_zig_ffi.  We compile main.zig directly with
+        # `zig build-lib -dynamic -lc`, producing a libproven.so with
+        # the WIRED 5 symbols (proven_path_has_traversal,
+        # proven_header_has_crlf, proven_free_string, proven_version,
+        # proven_build_info).  When proven#88 lands the real
+        # Idris-backed exports, this step swaps to
+        # `zig build -Dtarget=...`.
+        run: |
+          set -euo pipefail
+          mkdir -p zig-out/lib
+          zig build-lib -dynamic -O ReleaseSafe \
+              -fPIC \
+              --name proven \
+              -femit-bin=zig-out/lib/libproven.so \
+              src/main.zig -lc
+          ls -la zig-out/lib/
+          nm -D --defined-only zig-out/lib/libproven.so \
+              | awk '$2 ~ /^[TWV]$/ { print $3 }' \
+              | grep -E '^(proven_path_has_traversal|proven_header_has_crlf|proven_free_string|proven_version|proven_build_info)$' \
+              | sort -u | tee /tmp/wired-exports.txt
+          test "$(wc -l < /tmp/wired-exports.txt)" -eq 5
 
       - name: Install Chapel ${{ env.CHAPEL_VERSION }} (SHA-pinned .deb)
         run: |
           set -euo pipefail
-          curl -fsSL -o /tmp/chapel.deb "$CHAPEL_DEB_URL"
+          # libunwind-dev is a runtime link-time dep for chpl-built binaries
+          # on the ubuntu .deb path; sibling estate repo (panic-attack)
+          # established this preinstall as the working pattern.
+          sudo apt-get update -qq
+          sudo apt-get install -y libunwind-dev
+          curl -fsSL --retry 3 -o /tmp/chapel.deb "$CHAPEL_DEB_URL"
           echo "$CHAPEL_DEB_SHA256  /tmp/chapel.deb" | sha256sum --check
-          sudo apt-get update
           sudo apt-get install -y /tmp/chapel.deb
+          # Chapel 2.8.0 .deb auto-configures its target tuple; no
+          # CHPL_TARGET_* overrides needed (the 2.3.0-era runtime-tuple
+          # mismatch is gone — verified against panic-attack chapel-ci).
           chpl --version
 
-      - name: Chapel module typecheck (--library on every module)
+      - name: Chapel typecheck via driver build
         working-directory: proven/bindings/chapel
+        env:
+          PROVEN_LIB_PATH: ${{ github.workspace }}/proven/ffi/zig/zig-out/lib
+          PROVEN_INCLUDE_PATH: ${{ github.workspace }}/proven/bindings/c/include
         run: |
           set -euo pipefail
-          for m in src/*.chpl; do
-              echo "[chapel-build] typecheck $m"
-              chpl --library --dynamic --print-callstack-on-error \
-                   --no-codegen \
-                   -M src/ \
-                   -I "$GITHUB_WORKSPACE/proven/bindings/c/include" \
-                   "$m"
-          done
+          # `chpl --no-codegen` against an extern-record Chapel module fails
+          # in chapel/2.3.0 .deb installs with
+          #   error: Could not find bundled module 'ChapelSysCTypes'
+          # because module resolution looks up
+          #   $CHPL_HOME/modules/standard/gen/$tuple/ChapelSysCTypes.chpl
+          # and `--no-codegen` does not invoke the runtime-aware target-tuple
+          # probe.  Instead, do a real chpl link against libproven.so; that
+          # exercises the same typechecker without the broken gen-path
+          # resolution, AND additionally proves the binding links — which is
+          # what we actually care about.
+          # --print-commands surfaces the linker invocation chpl synthesises;
+          # without it, link failures appear only as "error: Make Binary -
+          # Linking" with no actionable detail.
+          chpl -o /tmp/_chapel_typecheck_driver \
+              smoke/hello_smoke.chpl \
+              -M src/ \
+              -I "$PROVEN_INCLUDE_PATH" \
+              -L "$PROVEN_LIB_PATH" -lproven \
+              --ldflags "-Wl,-rpath,$PROVEN_LIB_PATH" \
+              --print-commands \
+              --print-callstack-on-error
+          ls -la /tmp/_chapel_typecheck_driver
+          # Sanity check: the binary actually runs against the test fixture.
+          LD_LIBRARY_PATH="$PROVEN_LIB_PATH" /tmp/_chapel_typecheck_driver
+          echo "[chapel-build] typecheck via real link: OK"
 
       - name: Upload libproven.so artefact
         uses: actions/upload-artifact@6f51ac03b9356f520e9adb1b1b7802705f340c2b # v4
@@ -217,10 +271,12 @@ jobs:
       - name: Install Chapel ${{ env.CHAPEL_VERSION }} (SHA-pinned .deb)
         run: |
           set -euo pipefail
-          curl -fsSL -o /tmp/chapel.deb "$CHAPEL_DEB_URL"
+          sudo apt-get update -qq
+          sudo apt-get install -y libunwind-dev
+          curl -fsSL --retry 3 -o /tmp/chapel.deb "$CHAPEL_DEB_URL"
           echo "$CHAPEL_DEB_SHA256  /tmp/chapel.deb" | sha256sum --check
-          sudo apt-get update
           sudo apt-get install -y /tmp/chapel.deb
+          chpl --version
 
       - name: Install just
         uses: extractions/setup-just@dd310ad5a97d8e7b41793f8ef055398d51ad4de6 # v2
@@ -266,10 +322,12 @@ jobs:
       - name: Install Chapel ${{ env.CHAPEL_VERSION }} (SHA-pinned .deb)
         run: |
           set -euo pipefail
-          curl -fsSL -o /tmp/chapel.deb "$CHAPEL_DEB_URL"
+          sudo apt-get update -qq
+          sudo apt-get install -y libunwind-dev
+          curl -fsSL --retry 3 -o /tmp/chapel.deb "$CHAPEL_DEB_URL"
           echo "$CHAPEL_DEB_SHA256  /tmp/chapel.deb" | sha256sum --check
-          sudo apt-get update
           sudo apt-get install -y /tmp/chapel.deb
+          chpl --version
 
       - name: Install just
         uses: extractions/setup-just@dd310ad5a97d8e7b41793f8ef055398d51ad4de6 # v2
@@ -327,10 +385,12 @@ jobs:
       - name: Install Chapel ${{ env.CHAPEL_VERSION }} (SHA-pinned .deb)
         run: |
           set -euo pipefail
-          curl -fsSL -o /tmp/chapel.deb "$CHAPEL_DEB_URL"
+          sudo apt-get update -qq
+          sudo apt-get install -y libunwind-dev
+          curl -fsSL --retry 3 -o /tmp/chapel.deb "$CHAPEL_DEB_URL"
           echo "$CHAPEL_DEB_SHA256  /tmp/chapel.deb" | sha256sum --check
-          sudo apt-get update
           sudo apt-get install -y /tmp/chapel.deb
+          chpl --version
 
       - name: Install just
         uses: extractions/setup-just@dd310ad5a97d8e7b41793f8ef055398d51ad4de6 # v2

bindings/c/include/proven.h

@@ -169,6 +169,20 @@ uint32_t proven_version_patch(void);
 /** @brief Get total module count. */
 uint32_t proven_module_count(void);
 
+/**
+ * @brief Get the library version string (NUL-terminated, statically allocated).
+ *
+ * The returned pointer is owned by the library; do NOT free it.
+ */
+const char* proven_version(void);
+
+/**
+ * @brief Get build information (compiler, target, etc.; NUL-terminated, static).
+ *
+ * The returned pointer is owned by the library; do NOT free it.
+ */
+const char* proven_build_info(void);
+
 /* ============================================================================
  * SafeMath - Arithmetic that cannot crash (9 functions)
  * ============================================================================ */

bindings/chapel/README.adoc

@@ -74,8 +74,10 @@ just test
 use Proven;
 
 // WIRED: links + runs against libproven 0.9.0.
-var trav = SafePath.hasTraversal("../../etc/passwd"); // some(true)
-var crlf = SafeHeader.hasCrlf("v\r\nX-Inj: 1");       // some(true)
+// WIRED: links + runs against libproven 0.9.0.
+var trav = SafePath.hasTraversal("../../etc/passwd"); // Maybe(bool): some(true)
+var crlf = SafeHeader.hasCrlf("v\r\nX-Inj: 1");       // Maybe(bool): some(true)
+if trav.present && trav.value then writeln("blocked");
 
 // Identify the linked libproven (debug-friendly).
 writeln("libproven version: ", libraryVersion());
@@ -88,21 +90,35 @@ writeln("libproven version: ", libraryVersion());
 
 == Error Handling
 
-All fallible operations return Chapel optional types (`T?`). Use pattern
-matching to handle errors:
+All fallible operations return `Maybe(T)` — a binding-provided record
+with a `present` flag and a `value`.  Chapel 2.x's built-in `T?`
+postfix syntax is class-only and does NOT compile for value types
+(`bool?`, `int?`, `string?` all error); `Maybe(T)` is the
+binding-tier replacement.
 
 [source,chapel]
 ----
 var result = SafePath.hasTraversal(userInput);
-if result == none {
+if !result.present {
   writeln("FFI error reading input");
-} else if result! {
+} else if result.value {
   writeln("Path traversal detected — refusing");
 } else {
   writeln("Path is safe");
 }
 ----
 
+The constructors are `some(value)` and `absent(T)`:
+
+[source,chapel]
+----
+return some(true);            // Maybe(bool) with present == true
+return absent(int(64));       // Maybe(int(64)) with present == false
+----
+
+(`absent` rather than `none`/`nothing` because both of those are
+reserved words in Chapel.)
+
 == Coverage matrix (WIRED vs GATED)
 
 WIRED — present in `libproven 0.9.0`, verified by `chapel-symbol-audit`,

bindings/chapel/smoke/hello_smoke.chpl

@@ -3,11 +3,8 @@
 //
 // hello_smoke.chpl - End-to-end "does the binding link and run" smoke test.
 //
-// Builds:
-//   chpl -o hello_smoke smoke/hello_smoke.chpl -M src/ -lproven
-//
 // Runs in well under 2s and is kept green by chapel-ci.yml even if larger
-// jobs go red.  This is the "the binding actually works" gate.
+// jobs go red.
 //
 // Calls the WIRED subset only.  Lifecycle (provenInit/Deinit) is GATED on
 // proven#88 because the Zig export ABI does not yet match the proven.h
@@ -16,34 +13,28 @@
 use Proven;
 
 proc main(): int {
-  // SafePath.hasTraversal — happy path (no traversal) and detection path.
-  const safePath = "/var/www/html/index.html";
-  const evilPath = "../../etc/passwd";
-
-  const okSafe = SafePath.hasTraversal(safePath);
-  const okEvil = SafePath.hasTraversal(evilPath);
+  // SafePath.hasTraversal — happy + detection paths.
+  const okSafe = SafePath.hasTraversal("/var/www/html/index.html");
+  const okEvil = SafePath.hasTraversal("../../etc/passwd");
 
-  if okSafe == none || okSafe! != false {
-    writeln("FAIL: SafePath.hasTraversal('", safePath, "') did not return some(false)");
+  if !okSafe.present || okSafe.value != false {
+    writeln("FAIL: SafePath.hasTraversal('/var/www/html/index.html') did not return some(false)");
     return 1;
   }
-  if okEvil == none || okEvil! != true {
-    writeln("FAIL: SafePath.hasTraversal('", evilPath, "') did not return some(true)");
+  if !okEvil.present || okEvil.value != true {
+    writeln("FAIL: SafePath.hasTraversal('../../etc/passwd') did not return some(true)");
     return 1;
   }
 
-  // SafeHeader.hasCrlf — happy path (no CRLF) and detection path.
-  const safeHeader = "application/json";
-  const evilHeader = "value\r\nX-Injected: hi";
-
-  const headerOkSafe = SafeHeader.hasCrlf(safeHeader);
-  const headerOkEvil = SafeHeader.hasCrlf(evilHeader);
+  // SafeHeader.hasCrlf — happy + detection paths.
+  const headerOkSafe = SafeHeader.hasCrlf("application/json");
+  const headerOkEvil = SafeHeader.hasCrlf("value\r\nX-Injected: hi");
 
-  if headerOkSafe == none || headerOkSafe! != false {
-    writeln("FAIL: SafeHeader.hasCrlf('", safeHeader, "') did not return some(false)");
+  if !headerOkSafe.present || headerOkSafe.value != false {
+    writeln("FAIL: SafeHeader.hasCrlf('application/json') did not return some(false)");
     return 1;
   }
-  if headerOkEvil == none || headerOkEvil! != true {
+  if !headerOkEvil.present || headerOkEvil.value != true {
     writeln("FAIL: SafeHeader.hasCrlf(<CRLF>) did not return some(true)");
     return 1;
   }

bindings/chapel/src/LibProven.chpl

@@ -35,8 +35,14 @@ module LibProven {
   // Status codes (used by both WIRED and GATED results)
   // ========================================================================
 
-  /** Status codes returned by Proven operations. */
-  enum ProvenStatus : int(32) {
+  /** Status codes returned by Proven operations.
+   *
+   * Chapel 2.x removed the `enum X : int(32) { ... }` type-spec syntax;
+   * the C ABI's int32 status field is the source of truth, and this
+   * enum is for human-readable documentation.  Use `.toInt(32)` (or
+   * compare via the `isOk` helper) when interoperating with FFI.
+   */
+  enum ProvenStatus {
     OK                   =   0,
     ErrNullPointer       =  -1,
     ErrInvalidArgument   =  -2,
@@ -266,6 +272,37 @@ module LibProven {
       ptr: c_ptrConst(uint(8)), len: c_size_t
   ): FloatResult;
 
+  // ========================================================================
+  // Maybe(T) — Chapel-2.x-compatible optional-type pattern.
+  //
+  // Chapel's `T?` postfix is class-only; value-type wrappers
+  // (`bool?` / `int(64)?` / `string?`) do NOT compile.  Maybe(T) is a
+  // generic record with a `present` flag and a `value`.  `some(v)` and
+  // `none(T)` are the constructors; call sites pattern-match via
+  // `if r.present then r.value else fallback`.
+  // ========================================================================
+
+  /** Optional value-type carrier — see module-level note. */
+  record Maybe {
+    type T;
+    var present : bool;
+    var value   : T;
+  }
+
+  /** Wrap a value as a present Maybe(T). */
+  inline proc some(in v): Maybe(v.type) {
+    return new Maybe(v.type, true, v);
+  }
+
+  /** Construct an absent Maybe(T).  Pass the type explicitly:
+   * `return absent(bool)` / `absent(int(64))` / `absent(string)`.
+   *
+   * (Named `absent` because Chapel reserves `none` and `nothing`.) */
+  inline proc absent(type T): Maybe(T) {
+    var dflt : T;
+    return new Maybe(T, false, dflt);
+  }
+
   // ========================================================================
   // Helper: convert Chapel string to C pointer + length.
   // ========================================================================
@@ -280,18 +317,27 @@ module LibProven {
     return status == 0;
   }
 
-  /** Extract a Chapel string from a StringResult and free the C memory. */
+  /** Extract a Chapel string from a StringResult and free the C memory.
+   *
+   * ``string.createCopyingBuffer`` is throwing; we use ``try!`` because
+   * the C ABI guarantees a valid UTF-8 buffer of declared length when
+   * status is OK.  An empty status / nil pointer short-circuits to "". */
   proc extractString(ref r: StringResult): string {
     if !isOk(r.status) || r.value == nil then return "";
-    var s = string.createCopyingBuffer(r.value: c_ptrConst(c_char), r.length: int);
+    var s = try! string.createCopyingBuffer(r.value: c_ptrConst(c_char),
+                                            r.length: int);
     provenFreeString(r.value);
     return s;
   }
 
-  /** Read a NUL-terminated C string returned by libproven (no free required). */
+  /** Read a NUL-terminated C string returned by libproven (no free required).
+   *
+   * Uses ``try!`` for the same reason as ``extractString``: libproven
+   * guarantees NUL-termination on the string accessors that call this
+   * (proven_version, proven_build_info). */
   proc cStringToChapel(p: c_ptrConst(c_char)): string {
     if p == nil then return "";
-    return string.createCopyingBuffer(p);
+    return try! string.createCopyingBuffer(p);
   }
 
   /** Library version string from the loaded libproven. */