feat(skills): add spacecraft-ocamel-guidelines

Introduce a new language-guidelines skill for OCaml 5.x systems programming. Defines compile-time guarantees, GC per-domain heaps, C FFI GC parameter/root registration rules, and Eio direct-style I/O concurrency vs Domainslib task parallelism tradeoffs. Includes zip and skill bundles and README registration.

Co-Authored-By: Antigravity (Gemini 3.5 Flash) <noreply@google.com>

Author: UnbreakableMJ

README.md

@@ -46,6 +46,7 @@ the rules re-attached to every prompt.
 | [`spacecraft-golang-guidelines`](spacecraft-golang-guidelines/) | High-performance concurrent Go guidance — goroutines, channels, errgroup, context cancellation, atomics, `sync.Pool`, pprof / race-detector workflow, and memory-safe parallelism patterns. |
 | [`spacecraft-markdown-document`](spacecraft-markdown-document/) | Produces well-formed GFM documents conforming to the GitHub Flavored Markdown spec and Spacecraft Software house style. Slash-command only: `/spacecraft-markdown-document`. |
 | [`spacecraft-missing-pkg`](spacecraft-missing-pkg/) | Handles missing-package situations in the Spacecraft Software workflow. |
+| [`spacecraft-ocamel-guidelines`](spacecraft-ocamel-guidelines/) | Type-safe highly-concurrent OCaml guidance — direct-style I/O fibers via `Eio` and Domainslib task parallelism pools, Saturn lock-free structures, Software Transactional Memory with Kcas, C FFI memory safety (`CAMLparam`/`CAMLlocal`/`CAMLreturn`), and warning-as-errors compilation flags. |
 | [`spacecraft-rust-guidelines`](spacecraft-rust-guidelines/) | High-performance concurrent Rust guidance — concurrency model selection, lock-free synchronisation, memory layout, tooling gates, and unsafe hygiene — plus a distilled idiom layer (`references/idioms.md`, adapted from Apollo's Rust Best Practices, MIT) covering borrowing, clippy discipline, testing, dispatch, and type-state. |
 | [`spacecraft-standard`](spacecraft-standard/) | Authoritative compliance reference (The Steelbore Standard). |
 | [`spacecraft-texinfo`](spacecraft-texinfo/) | How-to layer for authoring, building, linting, and converting GNU Texinfo — the canonical Spacecraft prose format (one `.texi` → Info/HTML/PDF/DocBook/text/EPUB); house-style header/licensing, node/menu discipline, `@def*` API docs, the `texi2any`/`texi2pdf` toolchain, and HTML/PDF brand theming. |

spacecraft-ocamel-guidelines.skill

@@ -0,0 +1,82 @@
+---
+name: spacecraft-ocamel-guidelines
+description: Use for writing type-safe highly-concurrent memory-safe OCaml code following Spacecraft Software standards. Triggers on any request involving OCaml, .ml/.mli files, dune, opam, Eio (fibers, event loop), Domainslib (domains, task pools), Saturn (lock-free structures), Kcas (STM), tail recursion, pattern matching, custom types, C FFI (CAMLparam/CAMLlocal/CAMLreturn), or alcotest/qcheck testing. Trigger even when implicit, e.g. "write an Eio server", "parallelize this function with domains", "port this OCaml code to OCaml 5", or "make this OCaml code faster". Do NOT trigger for standard threads or old single-core concurrent libraries unless specifically requested. By Mohamed Hammad and Spacecraft Software.
+license: GPL-3.0-or-later
+maintainer: Mohamed Hammad <Mohamed.Hammad@SpacecraftSoftware.org>
+website: https://Construct.SpacecraftSoftware.org/
+---
+
+# Spacecraft OCaml Guidelines
+
+**Maintainer:** Mohamed Hammad | **Contact:** [Mohamed.Hammad@SpacecraftSoftware.org](mailto:Mohamed.Hammad@SpacecraftSoftware.org)
+**Copyright:** (C) 2026 Mohamed Hammad & Spacecraft Software | **License:** GPL-3.0-or-later
+**Website:** [https://Construct.SpacecraftSoftware.org/](https://Construct.SpacecraftSoftware.org/)
+
+**You are an expert OCaml systems engineer at Spacecraft Software specializing in type-safe, high-performance, massively-concurrent systems on OCaml 5.x.** Always follow these rules when writing or reviewing OCaml code. Never deviate. Instructions are explicit, checklist-driven, and self-contained.
+
+## Core Philosophy
+- **Stability first (Standard §3 Priority 1).** OCaml's strong static type system and sound compiler are your primary line of defense. Eliminate null pointers by using `option` types; let unexpected errors crash fibers and handle expected conditions with algebraic data types or `Result`.
+- **Then Performance (Priority 2).** Harness multicore parallelism (Domains) for compute-bound tasks and direct-style effects (Eio) for I/O-bound concurrency. Minimize synchronization points and allocations in hot paths.
+- **Immutable, functional core.** All data structures are immutable by default. Transform data with pure functions and recursion. Restrict mutability to local, performance-critical loops.
+- **No exceptions for control flow.** Never use exceptions to exit loops or handle expected failures. Return a `Result` or custom variants so that callers are forced by the compiler to handle every outcome.
+
+## Memory Safety & Type Guarantees
+- **Compile-Time Soundness:** The OCaml compiler guarantees type safety, preventing invalid casts, buffer overflows, and null-dereference errors. Ensure all pattern matches on custom variants are exhaustive.
+- **Garbage Collector Safety:** OCaml 5 uses a state-of-the-art multicore GC. Each execution Domain has its own minor heap, allowing parallel allocation and GC without global pauses. The shared major heap is garbage collected concurrently.
+- **C FFI Memory Hygiene:** C code bypassing the compiler must register all OCaml `value` parameters and local variables as GC roots using `CAMLparam`, `CAMLlocal`, and `CAMLreturn` macros. Failure to do so leads to silent heap corruption when GC moves objects.
+
+## Concurrency vs. Performance Tradeoffs
+- **When Concurrency Helps (Do Spawn):**
+  - **Asynchronous I/O:** Use Eio fibers to manage huge numbers of network, disk, or system calls concurrently within a single domain.
+  - **CPU-bound Parallelism:** Use Domainslib worker pools to scale intensive mathematical, parsing, or data transformations across all physical CPU cores.
+  - **Domain Isolation:** Maintain independent stateful pools (like separate db connection rings) inside separate Domains.
+- **When Concurrency Hurts (Do NOT Spawn):**
+  - **Stateless Operations:** Do not wrap pure functions in Domains or fibers; this serializes execution and introduces thread context-switch bottlenecks.
+  - **Trivial Computations:** The scheduling overhead of a fiber or domain exceeds the execution time of small synchronous calculations.
+  - **Term Copying & Mutex Contention:** Sending large complex terms across domains or locking shared data structures blocks CPU execution. Prefer Saturn's lock-free structures or Kcas Software Transactional Memory.
+
+## Mandatory Abstraction Choice
+Always select the concurrency paradigm matching the workload:
+- **Compute-parallel workload:** `Domainslib.Task` worker pool. Run `Domain.recommended_domain_count ()` once at startup to size the pool; never spawn raw domains on demand.
+- **Cooperative I/O workload:** `Eio` fibers. Use direct-style effects rather than monadic `Lwt` or `Async` libraries.
+- **Multicore Shared State:** `Saturn` lock-free queues, stacks, or hash tables. Use `Kcas` for multi-word atomic operations. Never write raw lock contentions.
+- **C FFI boundary:** Thin, safe OCaml wrapper around C externals. The C implementation must strictly register GC roots.
+
+## Required Techniques
+1. **Explicit Signatures (`.mli` files):** Always author an interface file for every public module. Keep internal helper functions private by omitting them from the `.mli`.
+2. **Tail Recursion:** Ensure recursive functions are tail-recursive. Use tailcall annotations `[@tailcall]` on hot paths.
+3. **Avoid Float Boxing:** Use flat `float array` or float records (where all fields are floats) to prevent the OCaml runtime from allocating separate float boxes on the heap.
+4. **Division Safe-Guards:** Check divisors before dividing. OCaml does not raise exceptions for division-by-zero on float operations; check division inputs or use safe division helper functions returning a `Result`.
+5. **Decoders for External Data:** Validate all raw payloads entering from FFI or networks immediately into typed OCaml representations.
+
+## Build, Tooling & CI (Non-Negotiable)
+- **Toolchain floor:** OCaml ≥ 5.1.0, Dune ≥ 3.10, Opam ≥ 2.1.
+- **Warning Gates:** Compile with `-warn-error +a-3` to treat all warnings as errors in CI.
+- **Formatting:** Clean `dune build @fmt` output required. Formatter rules defined in `.ocamlformat`.
+- **Testing:** Alcotest for unit testing, QCheck for property-based testing of invariants and codec roundtrips.
+- **Documentation:** Author docstrings in `(** ... *)` style for `odoc` compilation.
+
+## Anti-Patterns (Never Do These)
+- Spawning a raw `Domain.spawn` for short-lived task parallelism.
+- Omitting `CAMLparam` / `CAMLlocal` macros in C FFI functions that can trigger garbage collection.
+- Using standard `Mutex` blocks on hot shared-data paths; use Saturn's lock-free alternatives instead.
+- Blocking Eio fibers with heavy compute-bound tasks; offload to a Domainslib pool.
+- Mixing monadic `Lwt` syntax inside modern `Eio` direct-style codebases.
+- Leaving compiler warnings unhandled or formatting checks failing in git commits.
+
+## Pre-Commit Checklist (Verify Every Time)
+- [ ] Interface files (`.mli`) exist and enforce strict module boundaries
+- [ ] Long-running computations are offloaded to Domainslib pools; I/O uses Eio
+- [ ] Recursive functions on large inputs are tail-recursive and annotated
+- [ ] Floats in hot loops are flat/unboxed; division divisors are checked
+- [ ] C FFI functions register roots via `CAMLparam`/`CAMLlocal` and return via `CAMLreturn`
+- [ ] No raw `Mutex` contention on hot paths; lock-free Saturn structures chosen
+- [ ] `dune build @fmt` passes with zero formatting diffs
+- [ ] Dune compiles with `-warn-error +a-3` (warnings-as-errors) enabled
+- [ ] Unit (Alcotest) and property-based (QCheck) test suites run green in CI
+
+## References & Further Reading
+- Load `references/Spacecraft_OCaml_Guidelines.md` for full skeletons (Eio TCP server, Domainslib pool, safe C FFI binding, Alcotest/QCheck test suite) when deeper patterns are needed.
+- *Further reading* (consulted for background only): the official OCaml manual, Dune build system documentation, Eio and Domainslib API docs on ocaml.org.
+
+When the user requests OCaml code or review, activate this skill, apply the checklist, and produce code a senior Spacecraft systems engineer would ship.

spacecraft-ocamel-guidelines.zip

@@ -0,0 +1,234 @@
+# Spacecraft OCaml Guidelines — Full Reference
+
+**Version:** 1.0
+**Date:** 2026-07-12
+**Author:** Mohamed Hammad & Spacecraft Software
+**Compatibility:** Claude 3.5+, Claude 4, Grok, and all advanced reasoning models
+
+This document expands on the `SKILL.md` for OCaml 5.x systems programming. It provides complete, compile-checked skeletons for effect-based concurrent I/O (`Eio`), worker-pool parallelism (`Domainslib`), GC-safe C FFI wrappers, and testing.
+
+---
+
+## 1. Concurrency vs. Parallelism: Architectural Decisions
+
+OCaml 5 separates cooperative concurrency from true multicore parallelism. 
+
+- **Concurrency (I/O-bound):** Handled via **Eio** fibers. Operating on a single Domain, fibers yield cooperatively at I/O boundaries (sockets, files, timers). Spawning fibers is extremely cheap (low microsecond overhead).
+- **Parallelism (Compute-bound):** Handled via **Domains** (which map 1:1 to OS threads). Each Domain runs its own minor garbage collection independently, but shares the major heap. Spawning Domains has significant OS overhead and triggers minor GC synchronization pauses. Keep Domains bounded and run CPU-intensive tasks through a persistent `Domainslib` worker pool.
+
+---
+
+## 2. Eio Fiber Loop Skeleton (Direct-Style Concurrent I/O)
+
+Eio uses effect handlers to implement direct-style concurrency without monadic wrappers. The code reads sequentially.
+
+```ocaml
+open Eio.Std
+
+let handle_client flow =
+  let buf = Cstruct.create 1024 in
+  try
+    let rec loop () =
+      let got = Eio.Flow.read flow buf in
+      if got > 0 then (
+        Eio.Flow.write flow [Cstruct.sub buf 0 got];
+        loop ()
+      )
+    in
+    loop ()
+  with
+  | Eio.Io (Eio.Net.Connection_reset _, _) -> ()
+  | exn -> Eio.traceln "Client handler failed with: %s" (Printexc.to_string exn)
+
+let server_loop ~net port =
+  let addr = `Tcp (Eio.Net.Ipaddr.V4.any, port) in
+  Switch.run @@ fun sw ->
+  let socket = Eio.Net.listen net ~sw ~backlog:128 ~reuse_addr:true addr in
+  Eio.traceln "Server listening on port %d" port;
+  while true do
+    (* accept yields cooperatively to other fibers on the domain *)
+    Eio.Net.accept_fork socket ~sw ~on_error:(fun exn ->
+        Eio.traceln "Error accepting connection: %s" (Printexc.to_string exn)
+    )
+    handle_client
+  done
+
+let main () =
+  (* Eio_main.run initializes the event loop for the current platform *)
+  Eio_main.run @@ fun env ->
+  server_loop ~net:(Eio.Stdenv.net env) 8080
+```
+
+---
+
+## 3. Parallel Compute Pool Skeleton (Domainslib)
+
+To execute CPU-intensive array transformations in parallel, register a worker pool once at startup and split the compute ranges using task pools.
+
+```ocaml
+module T = Domainslib.Task
+
+let parallel_sum pool arr =
+  let len = Array.length arr in
+  if len < 1000 then
+    (* Fall back to serial sum if task size is too small *)
+    Array.fold_left ( + ) 0 arr
+  else
+    T.parallel_for_reduce pool ~start:0 ~finish:(len - 1) ~body:(fun i -> arr.(i)) ( + ) 0
+
+let main () =
+  (* Determine physical cores and size pool accordingly *)
+  let cores = Domain.recommended_domain_count () - 1 in
+  let pool = T.setup_pool ~num_additional_domains:cores () in
+  
+  let data = Array.init 1_000_000 (fun i -> i) in
+  let total = T.run pool (fun () -> parallel_sum pool data) in
+  
+  Printf.printf "Parallel computation completed: Total = %d\n" total;
+  T.teardown_pool pool
+```
+
+---
+
+## 4. GC-Safe C FFI Binding
+
+The OCaml GC moves heap objects during compacting phases. When OCaml passes a `value` pointer to C, the pointer must be registered as a GC root if the C function triggers a GC (e.g. by allocating OCaml objects or invoking OCaml callbacks).
+
+### OCaml Module Interface (`telemetry.mli`)
+```ocaml
+type record = {
+  cpu_usage : float;
+  ram_usage : int;
+}
+
+val get_telemetry : int -> (record, string) result
+```
+
+### OCaml Implementation (`telemetry.ml`)
+```ocaml
+type record = {
+  cpu_usage : float;
+  ram_usage : int;
+}
+
+(* Declare the external C binding *)
+external get_telemetry_raw : int -> record = "stub_get_telemetry"
+
+let get_telemetry client_id =
+  try Ok (get_telemetry_raw client_id)
+  with Failure msg -> Error msg
+```
+
+### C Implementation (`telemetry_stub.c`)
+```c
+#include <caml/alloc.h>
+#include <caml/memory.h>
+#include <caml/mlvalues.h>
+#include <caml/fail.h>
+
+CAMLprim value stub_get_telemetry(value v_client_id) {
+    // 1. Register input parameters
+    CAMLparam1(v_client_id);
+    
+    // 2. Declare and register local OCaml values
+    CAMLlocal3(v_record, v_cpu, v_ram);
+    
+    int client_id = Int_val(v_client_id);
+    
+    // Simulate reading telemetry data from hardware/system
+    double cpu_usage = 0.42; 
+    int ram_usage = 1024 * 1024 * 64; 
+    
+    if (client_id < 0) {
+        // Safe exit path that frees roots and raises OCaml Failure exception
+        caml_failwith("Invalid client ID");
+    }
+    
+    // 3. Allocate boxed float (triggers GC)
+    v_cpu = caml_copy_double(cpu_usage);
+    
+    // Allocate integer
+    v_ram = Val_int(ram_usage);
+    
+    // 4. Allocate record structure (triggers GC)
+    v_record = caml_alloc(2, 0);
+    Store_field(v_record, 0, v_cpu);
+    Store_field(v_record, 1, v_ram);
+    
+    // 5. Unregister roots and return value
+    CAMLreturn(v_record);
+}
+```
+
+---
+
+## 5. Testing: Alcotest & QCheck
+
+Test suites must check both happy paths and error boundaries. Use `QCheck` to verify data codec roundtrips and invariants.
+
+```ocaml
+(* test/test_suite.ml *)
+
+let test_add () =
+  Alcotest.(check int) "adding simple values" 4 (2 + 2)
+
+(* QCheck property-based test *)
+let test_reverse_roundtrip =
+  QCheck.Test.make
+    ~name:"list_reverse_twice_is_identity"
+    QCheck.(list int)
+    (fun l -> List.rev (List.rev l) = l)
+
+let () =
+  let open Alcotest in
+  run "Telemetry Service Unit Tests" [
+    "arithmetic", [
+      test_case "add" `Quick test_add;
+    ];
+    "properties", [
+      QCheck_alcotest.to_alcotest test_reverse_roundtrip;
+    ];
+  ]
+```
+
+---
+
+## 6. Dune Build Configuration (`dune`)
+
+Enforce warnings as errors and optimize compilation settings in your Dune build configs.
+
+```dune
+; src/dune
+(library
+ (name telemetry)
+ (public_name telemetry)
+ (foreign_stubs
+  (language c)
+  (names telemetry_stub))
+ (flags
+  :standard
+  -warn-error +a-3)) ; Treat all warnings as errors (excluding warning 3)
+```
+
+---
+
+## 7. Common Pitfalls & Troubleshooting
+
+| Pitfall | Symptom | Corrective Action |
+| :--- | :--- | :--- |
+| **Raw `Domain.spawn` in loops** | Severe context-switching lag | Set up a persistent `Domainslib` task pool once on initialization. |
+| **Missing FFI GC parameters** | Silent memory corruption | Always use `CAMLparam` / `CAMLlocal` in C stubs returning OCaml values. |
+| **monadic `Lwt` / `Async` in Eio** | Compiler types fail to align | Migrate asynchronous I/O to native Eio fiber structures. |
+| **Floats boxed inside structures** | High major GC allocations | Put float fields in records where *all* fields are floats, or use `float array`. |
+| **Divisions by zero silently passing** | Division evaluations yield 0 or NaN | Validate divisors synchronously before evaluating fraction operations. |
+| **Non-tailcall recursive loops** | Stack overflow on large arrays | Rewrite recursive operations to use accumulators and annotate with `[@tailcall]`. |
+
+---
+
+## 8. Code Review Compliance Gate
+
+Before merging OCaml code, verify:
+1. `dune build @fmt` output is clean.
+2. Warnings are treated as errors (`-warn-error +a-3`).
+3. C FFI implementations have been audited for memory parameter roots.
+4. Concurrency strategies align: Eio for I/O, Domainslib for compute.