Add FreeBSD as a CI target (compilation + base Capsicum support)

[paul-hammant]

Summary

Add FreeBSD to Aether's CI matrix to ensure code compiles and runs on FreeBSD, with foundational support for Capsicum capability-based sandboxing.

Background

Aether already builds on FreeBSD:

• Runtime uses kqueue I/O poller (implemented for macOS/FreeBSD)
• Source has `#ifdef FreeBSD` conditionals
• Mostly POSIX-compatible code
• Gap: No CI testing, so breakage could hide

Capsicum is FreeBSD's mature capability-based sandboxing framework (similar to Aether's language-level model but OS-enforced). Adding FreeBSD CI + Capsicum bindings would position Aether as the only language with both language-level AND OS-level sandboxing capabilities.

Work Items

Phase 1: FreeBSD CI + Base Capsicum (MVP, ~3-4 days)

• Add FreeBSD CI job (~2-4 hours)

  • Use Cirrus CI (native FreeBSD VMs, free for open source)
  • Alternative: GitHub Actions + freebsd/action community runner
  • Run make ci (same as Linux/macOS matrix)
  • Verify compiler, ae check, stdlib, unit tests, integration tests pass

• Create std.capsicum module (~1-2 days)

  • New: std/capsicum/module.ae with Aether bindings
  • New: std/capsicum/aether_capsicum.c with C wrappers
  • Bindings: capsicum_available(), capsicum_enter(), capsicum_limit_rights(), capsicum_pdwait4()
  • Allow manual Capsicum usage from Aether code
  • Document with example: enter capability mode, restrict fd rights

• Build system support (~1 day)

  • Detect FreeBSD: #ifdef __FreeBSD__
  • Optional flag: -DAETHER_HAS_CAPSICUM
  • Link libcasper if available: pkg-config --libs libcasper
  • Update Makefile to compile std.capsicum conditionally

• Documentation (~1 day)

  • Add FreeBSD section to docs/contributing-bsd.md (or new file)
  • Example: calling std.capsicum from Aether code
  • Explain what Capsicum does + how it complements Aether's sandbox
  • Note limitation: requires FreeBSD kernel (not available in Linux containers)

Phase 2: Transparent Runtime Integration (optional, future)

• Modify runtime/scheduler/actor_pool.c to automatically use Capsicum
• Map permission contexts to fd capabilities + rights
• Spawn sandboxed actors in capability mode on FreeBSD
• Audit logging for capability grants/denials

Phase 3: Ecosystem Integration (optional, future)

• Casper daemon support (DNS, getpwd, etc. delegation)
• Jail integration for process isolation
• RCTL resource limits (CPU, memory, fds)

Success Criteria

Phase 1 completion:

• ✓ FreeBSD is in CI matrix (prevents regressions)
• ✓ All existing tests pass on FreeBSD
• ✓ Users can call std.capsicum.capsicum_enter() and capsicum_limit_rights()
• ✓ Documentation explains the feature + limitations
• ✓ Aether story extends to: "Works on Linux, macOS, Windows, and FreeBSD"

Effort Estimate

Task	Time	Notes
FreeBSD CI setup	2-4 hours	Cirrus CI is straightforward
std.capsicum module	1-2 days	Mostly wrappers around cap_*(2) syscalls
Build system	1 day	Similar to AETHER_HAS_OPENSSL pattern
Documentation	1 day	Examples + limitations
Total (MVP)	3-4 days	Can be done in a sprint

Technical Notes

• CI choice: Cirrus CI recommended (native FreeBSD VMs, free for open source, real Capsicum support)
  • Alternative: GitHub Actions + freebsd/action (Linux emulation, no Capsicum)
• Capsicum limitation on Linux containers: FreeBSD OCI images run FreeBSD userspace on Linux kernel; Capsicum syscalls won't work (requires FreeBSD kernel). This is OK for MVP—Phase 1 focuses on compilation & manual bindings.
• Kernel requirement: Capsicum requires FreeBSD 10.0+; can check at runtime with capsicum_available()

Related Issues

• #396 Stack protection & FORTIFY_SOURCE hardening
• #397 Multi-compiler CI targets (gcc, clang, RISCV64)
• Aether vs. BSD Capsicum comparison doc — design rationale

References

• Capsicum research paper
• FreeBSD Capsicum man pages
• Cirrus CI (free for open source)