fix(abi): make the probe-handle lifecycle real and correct the Idris wrappers

The proven-ABI story was connected to nothing: gossamer_gsa_probe returned
a bare result code (never a handle), gossamer_gsa_close_handle was a no-op
(_ = handle;), and every Foreign.idr wrapper assumed negative error codes
the Zig side never emits. So the Idris linear-type guarantees
(AlreadyConsumed/DoubleFree) had no runtime counterpart.

Zig side (main.zig, probe.zig, abi_serde.zig):
- GsaHandle now issues monotonic handle ids (>= FIRST_HANDLE_ID = 1000,
  disjoint from the 0-17 result-code space so a success value can never be
  read as an error code).
- gossamer_gsa_probe returns the handle id; gossamer_gsa_close_handle
  validates it, frees the binding, and reports double_free on a repeat
  close and not_found for a stray id, via a bounded tombstone ring.
- gossamer_gsa_apply_config validates the handle (already_consumed if the
  handle was closed) instead of ignoring it.
- Two new tests cover open/use/close/double-close/unknown and the bounded
  tombstone ring.

Idris side (Foreign.idr):
- New resultOf/parseResultCode drop the bogus negation: a code of 0 is Ok,
  1-17 is that GsaResult (Zig never negates — grep-verified).
- probe classifies its return by magnitude (>= firstHandleId = handle).
- prim__serverAction and prim__getLogs retyped from Int to String to match
  the real C signatures (both return char*, not codes/arrays); wrappers
  updated (serverAction returns the JSON string, getLogs splits lines).
- fingerprint now consumes the handle it produces (no leak); storeOctad,
  addProfile, applyConfig, checkHealth reworked to honest behaviour with
  scope notes where an Idris-side struct emitter is the documented follow-up.

Ephapax (Bridge.eph): probe success checks widened to >= 1000; code-returning
FFI checks tightened to != 0 to match the positive-code convention.

CI: new abi-contract.yml regenerates both expected tables and fails on drift,
runs the comptime cross-check via zig build, and type-checks the Idris2
package (was never compiled in CI — the reason this drift shipped).
cross-platform.yml now also runs the smoke and property suites.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TaWWedv6VQqeZaPvc94keN

Author: claude

.claude/CLAUDE.md

@@ -42,7 +42,7 @@ panic-attack assail .
 Gossamer GUI (Ephapax .eph)        -- src/core/, src/gui/panels/
     |  IPC (gossamer:// protocol)
 Zig FFI (libgsa.so + gsa CLI)     -- src/interface/ffi/src/ (11 modules)
-    |  C ABI (13 result codes)
+    |  C ABI (18 result codes)
 Idris2 ABI (Types/Foreign/Layout)  -- src/interface/abi/
     |  REST (port 8090)
 VeriSimDB (8-modality octads)      -- container/verisimdb/

.github/workflows/abi-contract.yml

@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: MPL-2.0
+# ABI contract gate — keeps the Zig FFI and the Idris2 model in lockstep.
+#
+# Two things drift silently if unchecked (and did: result codes 5-12 once
+# encoded different concepts on each side):
+#   1. The generated expected-tables (result codes, struct layout) must match
+#      what the generators produce from Types.idr / Layout.idr right now.
+#   2. The Idris2 model itself must type-check.
+# The Zig comptime cross-checks (abi_layout.zig, the GsaResult block in
+# main.zig) turn any table drift into a compile error, so `zig build` is the
+# enforcement; this workflow regenerates first so a stale committed table
+# fails loudly instead of masking a change.
+
+name: ABI Contract
+
+on:
+  push:
+    branches: [main, 'claude/**']
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  zig-contract:
+    name: Zig ↔ Idris tables in sync
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Install Zig 0.15.2
+        uses: mlugg/setup-zig@d1434d08867e3ee9daa34448df10607b98908d29 # v2.2.1
+        with:
+          version: 0.15.2
+
+      - name: Regenerate expected tables from the Idris2 model
+        run: |
+          zig run scripts/gen_abi_expected.zig
+          zig run scripts/gen_result_codes.zig
+
+      - name: Fail on drift (committed tables must match the model)
+        run: |
+          git diff --exit-code \
+            src/interface/ffi/src/abi_layout_expected.zig \
+            src/interface/ffi/src/result_codes_expected.zig \
+          || { echo "::error::Generated ABI tables are stale. Run: zig run scripts/gen_abi_expected.zig && zig run scripts/gen_result_codes.zig"; exit 1; }
+
+      - name: Build (runs the comptime GsaResult ↔ Types.idr cross-check)
+        working-directory: src/interface/ffi
+        run: zig build
+
+  idris-typecheck:
+    name: Idris2 model type-checks
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+
+      - name: Install Idris2
+        run: sudo apt-get update && sudo apt-get install -y idris2
+
+      - name: Type-check the ABI package
+        working-directory: src/interface/abi
+        run: idris2 --typecheck gsa-abi.ipkg

.github/workflows/cross-platform.yml

@@ -60,3 +60,11 @@ jobs:
         if: matrix.run-integration
         working-directory: src/interface/ffi
         run: zig build test-integration
+
+      - name: Smoke Tests
+        working-directory: src/interface/ffi
+        run: zig build test-smoke
+
+      - name: Property Tests
+        working-directory: src/interface/ffi
+        run: zig build test-property

docs/INDEX.adoc

@@ -37,7 +37,7 @@ _You build GSA, extend it, or contribute code across the Gossamer GUI → Zig FF
 | `docs/developer/ABI-FFI-README.adoc` | live | Idris2 ABI + Zig FFI standard; C/Idris2/Rust/Julia examples (strong)
 | `TOPOLOGY.md` | live | System architecture + data flow
 | `docs/decisions/` | live | Architecture decision records (RSR adoption)
-| FFI module reference | *planned* | Per-module docs for the 11 FFI modules (signatures, the 13 result codes, examples)
+| FFI module reference | *planned* | Per-module docs for the 11 FFI modules (signatures, the 18 result codes, examples)
 | Panel extension guide | *planned* | The PanLL clade system; registering a new panel; inheriting base clades
 | Game-profile authoring | *thin* | Expand the README snippet: field types, validation, port/protocol, debugging
 | Config-format guide | *planned* | How to add a parser to the 8-format `config_extract`

src/core/Bridge.eph

@@ -52,7 +52,7 @@ fn handleProbeServer(payload: String, caps: &GsaCapSet) -> String =
     jsonError("Missing 'host' in probe request")
   else {
     let result = __ffi("gossamer_gsa_probe", host, port) in
-    if result < 0 then
+    if result < 1000 then
       jsonError("Probe failed: " ++ __ffi("gossamer_gsa_last_error"))
     else {
       -- Fingerprint succeeded, extract config
@@ -85,7 +85,7 @@ fn handleAddServer(payload: String, caps: &GsaCapSet) -> String =
 fn handleRemoveServer(payload: String, caps: &GsaCapSet) -> String =
   let server_id = jsonField(payload, "server_id") in
   let result = __ffi("gossamer_gsa_verisimdb_delete", server_id) in
-  if result < 0 then
+  if result != 0 then
     jsonError("Failed to remove: " ++ __ffi("gossamer_gsa_last_error"))
   else
     jsonOk("{\"server_id\":\"" ++ server_id ++ "\",\"removed\":true}")
@@ -138,7 +138,7 @@ fn handleSetConfig(payload: String, caps: &GsaCapSet) -> String =
   else {
     -- Apply changes via FFI (writes to server, updates VeriSimDB)
     let result = __ffi("gossamer_gsa_apply_config", server_id, changes) in
-    if result < 0 then
+    if result != 0 then
       jsonError("Config apply failed: " ++ __ffi("gossamer_gsa_last_error"))
     else {
       -- Record provenance
@@ -158,7 +158,7 @@ fn handleRevertConfig(payload: String, caps: &GsaCapSet) -> String =
     jsonError("No stored config for: " ++ server_id)
   else {
     let result = __ffi("gossamer_gsa_apply_stored_config", server_id, stored) in
-    if result < 0 then
+    if result != 0 then
       jsonError("Revert failed: " ++ __ffi("gossamer_gsa_last_error"))
     else {
       let prov = "{\"event_type\":\"config_revert\",\"actor\":\"gsa-gui\",\"description\":\"Config reverted to stored version\"}" in
@@ -220,7 +220,7 @@ fn handleGetLogs(payload: String, caps: &GsaCapSet) -> String =
 -- Get overall health status of all managed servers.
 fn handleGetHealth(payload: String, caps: &GsaCapSet) -> String =
   let result = __ffi("gossamer_gsa_verisimdb_health") in
-  if result < 0 then
+  if result != 0 then
     jsonError("VeriSimDB health check failed")
   else {
     let drift_status = __ffi("gossamer_gsa_verisimdb_drift_all") in
@@ -279,7 +279,7 @@ fn handleRollbackConfig(payload: String, caps: &GsaCapSet) -> String =
     else {
       -- Apply historical config
       let result = __ffi("gossamer_gsa_apply_stored_config", server_id, historical) in
-      if result < 0 then
+      if result != 0 then
         jsonError("Rollback failed: " ++ __ffi("gossamer_gsa_last_error"))
       else {
         let prov = "{\"event_type\":\"config_rollback\",\"actor\":\"gsa-gui\",\"description\":\"Rolled back to version " ++ version ++ "\"}" in
@@ -506,7 +506,7 @@ fn handleAddProfile(payload: String) -> String =
     jsonError("Missing 'a2ml' profile definition")
   else {
     let result = __ffi("gossamer_gsa_add_profile", a2ml) in
-    if result < 0 then
+    if result != 0 then
       jsonError("Profile registration failed: " ++ __ffi("gossamer_gsa_last_error"))
     else
       jsonOk("{\"registered\":true}")
@@ -574,7 +574,7 @@ fn handleNexusStageFiles(payload: String, caps: &GsaCapSet) -> String =
     let env_json = "{\"STEAM_USER\":\"" ++ steam_user ++
                    "\",\"PROVISION_TARGET_HOST\":\"" ++ target_host ++ "\"}" in
     let result = __ffi("gossamer_gsa_run_script", "scripts/steam-stage.sh", profile_id, env_json, steam_pass) in
-    if result < 0 then
+    if result != 0 then
       jsonError("Staging failed: " ++ __ffi("gossamer_gsa_last_error"))
     else {
       let prov = "{\"event_type\":\"nexus_stage\",\"actor\":\"gsa-gui\",\"description\":\"SteamCMD stage for " ++ profile_id ++ " on " ++ target_host ++ "\"}" in
@@ -605,7 +605,7 @@ fn handleNexusProvision(payload: String, caps: &GsaCapSet) -> String =
       let env_json = "{\"PROVISION_TARGET_HOST\":\"" ++ target_host ++
                      "\",\"PROVISION_SSH_USER\":\"" ++ ssh_user ++ "\"}" in
       let result = __ffi("gossamer_gsa_run_script", "scripts/provision-server.sh", profile_id, env_json, "") in
-      if result < 0 then
+      if result != 0 then
         jsonError("Provisioner failed: " ++ __ffi("gossamer_gsa_last_error"))
       else {
         -- Register in VeriSimDB
@@ -637,7 +637,7 @@ fn handleNexusVerify(payload: String, caps: &GsaCapSet) -> String =
     let vdb_check = __ffi("gossamer_gsa_verisimdb_query",
       "SELECT id FROM octads WHERE id = '" ++ server_id ++ "'") in
     let registered = if vdb_check != "" then "true" else "false" in
-    if probe < 0 then
+    if probe < 1000 then
       -- Not yet reachable — partial ok (provisioned but not responding yet)
       jsonOk("{\"ok\":false,\"verisimdb_registered\":" ++ registered ++
              ",\"error\":\"Server not yet responding on UDP " ++ game_port ++ "\"}")