docs(chapel): PIC-from-source rebuild ADR + Justfile recipe (#150)

## Summary

Wave-2 follow-on to PR #146. The metalayer is currently linked
`--library --static` because the apt-distributed Chapel runtime ships
only the `lib_pic-none` variant. This PR ships:

- **ADR** at \`docs/decisions/2026-05-30-chapel-pic-rebuild.md\` —
  documents the constraint, the source-rebuild procedure, tradeoffs
  vs the current static form, and why the CI flip is deferred to a
  future registry-pushed container.
- **\`just chapel-pic-from-source\`** — runnable recipe that downloads
  chapel-2.8.0, sets \`CHPL_LIB_PIC=pic\`, builds, and verifies the
  \`lib_pic-pic/\` runtime variant landed. Cache via
  \`ECHIDNA_CHAPEL_PIC_CACHE\`; version via \`CHPL_VERSION\`. **Not**
  invoked from CI.
- Cross-link from the rehabilitation ADR's Wave-2 plan into this ADR.

## Why no CI flip

The PIC runtime is required for \`--library --dynamic\` and the L2.5
multi-locale Chapel work, but **not** required for the current Rust
link path (which uses \`libechidna_chapel.a\`). The ~30 min wall +
~5 GB disk cost of the source rebuild would dominate the chapel-ci
budget for negligible gain until L2.5 starts — see the
\"Tradeoffs\" table in the ADR.

A registry-pushed Containerfile is the right amortisation, gated on
L1 Cap'n Proto.

## Test plan

- [x] \`just --list\` shows the new recipe
- [x] Justfile parses (shebang-style recipe, same form as
\`init\`/\`doctor\`/\`heal\`)
- [ ] Recipe end-to-end execution (deliberately local-only; takes ~30
min)
- [ ] CI: chapel-build + chapel-smoke remain green (unchanged from
current main)

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

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

Author: hyperpolymath

Justfile

@@ -534,6 +534,43 @@ bench-chapel-mrr:
     cd src/chapel && chpl -o bench_mrr bench_mrr.chpl && \
       ./bench_mrr --verbose=false --timeout=10
 
+# Rebuild Chapel 2.8.0 from source with CHPL_LIB_PIC=pic so that
+# `chpl --library --dynamic` can produce a shared-library form of the
+# metalayer. The apt deb ships only the `lib_pic-none` runtime
+# variant. ~25-35 min wall on a 4-core x86_64. ~5 GB disk under
+# ~/.cache/echidna/chapel-pic. Procedure + tradeoffs:
+# docs/decisions/2026-05-30-chapel-pic-rebuild.md. NOT a CI step.
+chapel-pic-from-source:
+    #!/usr/bin/env bash
+    set -euo pipefail
+    CACHE_DIR="${ECHIDNA_CHAPEL_PIC_CACHE:-$HOME/.cache/echidna/chapel-pic}"
+    CHPL_VERSION="${CHPL_VERSION:-2.8.0}"
+    mkdir -p "$CACHE_DIR"
+    cd "$CACHE_DIR"
+    if [ ! -f "chapel-${CHPL_VERSION}.tar.gz" ]; then
+      echo "Downloading chapel ${CHPL_VERSION}..."
+      curl -fL "https://github.com/chapel-lang/chapel/releases/download/${CHPL_VERSION}/chapel-${CHPL_VERSION}.tar.gz" \
+        -o "chapel-${CHPL_VERSION}.tar.gz"
+    fi
+    if [ ! -d "chapel-${CHPL_VERSION}" ]; then
+      tar xf "chapel-${CHPL_VERSION}.tar.gz"
+    fi
+    cd "chapel-${CHPL_VERSION}"
+    export CHPL_LIB_PIC=pic
+    export CHPL_LLVM=bundled
+    export CHPL_HOME="$PWD"
+    source util/setchplenv.bash
+    echo "Building chapel runtime with CHPL_LIB_PIC=pic (~30 min)..."
+    make -j"$(nproc)"
+    echo "Verifying lib_pic-pic variant landed..."
+    if find lib -name 'lib_pic-pic' -type d | head -1 | grep -q .; then
+      echo "OK: PIC runtime built at $CHPL_HOME"
+      echo "Use:  PATH=$CHPL_HOME/bin/linux64-x86_64:\$PATH chpl --library --dynamic ..."
+    else
+      echo "ERROR: lib_pic-pic variant not found after build" >&2
+      exit 1
+    fi
+
 # Build Zig FFI bridge for Chapel (prerequisite for --features chapel)
 build-chapel-ffi:
     @echo "Building Zig FFI bridge..."

docs/decisions/2026-05-30-chapel-pic-rebuild.md

@@ -0,0 +1,148 @@
+<!-- SPDX-License-Identifier: MPL-2.0 -->
+
+# 2026-05-30 — Chapel PIC rebuild from source for `--library --dynamic`
+
+ADR-style addendum to [2026-05-30-chapel-rehabilitation.md][rehab].
+Documents the procedure and constraints for replacing the apt-shipped
+Chapel runtime with a position-independent variant so the metalayer can
+be linked as a shared library instead of a static archive.
+
+[rehab]: ./2026-05-30-chapel-rehabilitation.md
+
+## Status
+
+Documented. Procedure is `just chapel-pic-from-source`; **not** invoked
+from any CI workflow because the build is ~30 min wall and ~5 GB disk,
+which would dominate the Chapel CI budget for negligible runtime gain
+until L2.5 multi-locale work needs the shared-library form.
+
+## Context
+
+The rehabilitation PR (#146) chose `--library --static` for
+`chapel-build` because the apt-distributed Chapel deb only ships one
+runtime variant — `lib_pic-none`:
+
+```
+/usr/lib/chapel/2.8/runtime/lib/linux64/gnu/x86_64/loc-flat/
+  comm-none/tasks-qthreads/launch-smp/tmr-generic/unwind-system/
+  mem-jemalloc/atomics-cstdlib/lib_pic-none/san-none/libchpllaunch.a
+```
+
+`chpl --library --dynamic` requires a `lib_pic-pic/` variant in the
+same path tree; without it, the link of `libchpl.a` into a `.so` fails
+with:
+
+```
+relocation R_X86_64_TPOFF32 against symbol `chpl_task_root_uniqueId'
+can not be used when making a shared object; recompile with -fPIC
+```
+
+The same constraint applies to the conda-forge `chapel` package, which
+also ships only the non-PIC runtime variant as of 2.8.0.
+
+The only way to obtain a PIC runtime is to build Chapel from the
+release source with `CHPL_LIB_PIC=pic` set at `make` time. The variant
+ends up at the parallel `lib_pic-pic/` path and is auto-discovered by
+`chpl --library --dynamic` at link time.
+
+## Decision
+
+Ship a documented, reproducible Justfile recipe that performs the
+source rebuild on demand, but do **not** invoke it from CI and do **not**
+change the canonical `chapel-build` recipe. Local developers and the
+eventual L2.5 multi-locale workflow can opt in via `just chapel-pic-from-source`.
+
+Rationale:
+
+- The PIC rebuild is a one-shot ~30 min operation per CI runner, which
+  cannot be amortised across PRs without a registry-pushed container
+  image — see follow-up below.
+- The static-library form (`--library --static`) is correct for the
+  current Rust-link path; Rust binaries already embed the Chapel
+  runtime by linking against `libechidna_chapel.a`. Switching to
+  `.so` linkage gains separability of the Chapel runtime but adds
+  packaging complexity (now two artifacts to ship and version).
+- The PIC form is only **required** for L2.5 (multi-locale Chapel
+  dispatch under PGAS), where the runtime needs to be loadable from
+  multiple Chapel-distinct executables. That work is gated on L1
+  Cap'n Proto, so the PIC runtime is a precondition we can satisfy
+  asynchronously when L2.5 starts.
+
+## Procedure
+
+```bash
+just chapel-pic-from-source
+```
+
+Equivalent to:
+
+```bash
+mkdir -p ~/.cache/echidna/chapel-pic && cd ~/.cache/echidna/chapel-pic
+
+# Source — 2.8.0 matches the local development install. Adjust if
+# CI moves to a newer point release.
+curl -fL https://github.com/chapel-lang/chapel/releases/download/2.8.0/chapel-2.8.0.tar.gz \
+    -o chapel-2.8.0.tar.gz
+tar xf chapel-2.8.0.tar.gz
+cd chapel-2.8.0
+
+# PIC runtime variant — the single env var that drives the additional
+# `lib_pic-pic/` subtree under `runtime/lib/.../`. LLVM is the default
+# back end on 2.8+; the apt deb also uses LLVM, so we match.
+export CHPL_LIB_PIC=pic
+export CHPL_LLVM=bundled        # match apt deb
+export CHPL_HOME=$PWD
+source util/setchplenv.bash
+
+# Build. This step is ~25-35 min wall on a 4-core x86_64 box.
+make -j$(nproc)
+
+# Verify the PIC variant landed.
+find lib -name 'lib_pic-pic' -type d | head -1
+```
+
+After this completes, `chpl` from `$CHPL_HOME/bin/linux64-x86_64/chpl`
+can produce shared-library output:
+
+```bash
+$CHPL_HOME/bin/linux64-x86_64/chpl \
+    --library --dynamic -I ../zig_ffi \
+    -o libechidna_chapel parallel_proof_search.chpl chapel_ffi_exports.chpl
+```
+
+## Tradeoffs
+
+| Aspect | `--library --static` (current default) | `--library --dynamic` (PIC rebuild) |
+|---|---|---|
+| Build time, cold | ~10 s | ~30 min (one-time) + ~10 s |
+| Build time, warm | ~10 s | ~10 s |
+| Disk footprint | runtime in libchpl.a (~30 MB) | runtime in libchpl.so (~30 MB) + source tree (~5 GB) |
+| Rust link | static archive into executable | dynamic load at runtime |
+| Multi-process sharing | each process embeds runtime | runtime shared across processes |
+| L2.5 multi-locale | does not support | required |
+
+## Follow-up
+
+A registry-pushed Containerfile that pre-builds the PIC runtime would
+amortise the 30 min cost across CI runs, but requires:
+
+- A `Containerfile.chapel-pic` under `.containerization/`.
+- A registry destination (ghcr.io/hyperpolymath/echidna-chapel-pic:2.8.0).
+- A CI job to build + push on chapel version bumps.
+
+Tracked as a Wave-3 follow-up issue; the current PR does **not** add
+the container path because it would duplicate the in-flight L1 Cap'n
+Proto schema work and risk image-tag drift if Chapel point-releases
+between now and L2.5 starting.
+
+## Verification
+
+The recipe is not executed in CI for the reasons above. Local
+verification (one-time, by anyone who wants `--dynamic` linkage) is:
+
+```bash
+just chapel-pic-from-source
+# Confirm:
+find ~/.cache/echidna/chapel-pic/chapel-2.8.0/lib -name 'lib_pic-pic' -type d
+# Expected output: at least one path containing `lib_pic-pic/`.
+```

docs/decisions/2026-05-30-chapel-rehabilitation.md

@@ -106,9 +106,12 @@ Wave 1 (this PR, echidna only):
 - `Justfile` recipes: `chapel-build`, `chapel-smoke`, `chapel-test`.
 
 Wave 2 (separate PR, after Wave 1 green-on-main for ≥7 days):
-- Rebuild Chapel CI image with `CHPL_LIB_PIC=pic` runtime; revert
+- Rebuild Chapel from source with `CHPL_LIB_PIC=pic` runtime; revert
   the metalayer build to `--dynamic`; flip `rust-chapel-real` to
-  strict.
+  strict. Recipe + tradeoffs:
+  [2026-05-30-chapel-pic-rebuild.md](./2026-05-30-chapel-pic-rebuild.md).
+  CI flip deferred — the ~30 min source build dominates the chapel-ci
+  budget; a registry-pushed container image is the L2.5 prerequisite.
 - Add the cancel-token thread through `tryProver` and switch the
   Chapel-side default to the speculative search.
 - Wire the `proven` and `docudactyl` parallel-dispatch tracks