fix: add SAFETY comments to all unsafe pointer casts in FFI modules

Documents 62 unsafe pointer operations (@ptrCast, @aligncast, @constcast)
with // SAFETY: comments explaining why each cast is safe, per panic-attack
security audit findings (13 High severity).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: hyperpolymath

ffi/zig/src/cache.zig

@@ -111,12 +111,14 @@ export fn ddac_cache_init(
         .allocator = allocator,
     };
 
+    // SAFETY: state was just allocated by c_allocator.create(CacheState), which returns a well-aligned *CacheState
     return @ptrCast(state);
 }
 
 /// Free the LMDB cache. Safe to call with null.
 export fn ddac_cache_free(handle: ?*anyopaque) void {
     const ptr = handle orelse return;
+    // SAFETY: ptr originates from ddac_cache_init() which stores a *CacheState via @ptrCast; alignment is guaranteed by c_allocator
     const state: *CacheState = @ptrCast(@alignCast(ptr));
 
     lmdb.mdb_env_close(state.env);
@@ -139,6 +141,7 @@ export fn ddac_cache_lookup(
     result_size: usize,
 ) c_int {
     const ptr = handle orelse return 0;
+    // SAFETY: ptr originates from ddac_cache_init() which stores a *CacheState via @ptrCast; alignment is guaranteed by c_allocator
     const state: *CacheState = @ptrCast(@alignCast(ptr));
     const path = doc_path orelse return 0;
     const out = result_out orelse return 0;
@@ -150,6 +153,8 @@ export fn ddac_cache_lookup(
 
     // Look up by path
     const path_slice = std.mem.span(path);
+    // SAFETY: @constCast is required by LMDB's C API which takes void* for keys; the data is only read, never written by mdb_get
+    // SAFETY: @ptrCast converts [*]const u8 to *anyopaque as required by MDB_val.mv_data field
     var key = lmdb.MDB_val{ .mv_size = path_slice.len, .mv_data = @constCast(@ptrCast(path_slice.ptr)) };
     var data: lmdb.MDB_val = undefined;
 
@@ -160,6 +165,7 @@ export fn ddac_cache_lookup(
     if (data.mv_size < expected_size) return 0;
 
     // Check mtime and file_size
+    // SAFETY: LMDB mdb_get returns mv_data pointing into the memory-mapped database; valid for the transaction lifetime
     const value_bytes: [*]const u8 = @ptrCast(data.mv_data);
     const cached_mtime = std.mem.readInt(i64, value_bytes[0..8], .little);
     const cached_size = std.mem.readInt(i64, value_bytes[8..16], .little);
@@ -187,6 +193,7 @@ export fn ddac_cache_store(
     result_size: usize,
 ) void {
     const ptr = handle orelse return;
+    // SAFETY: ptr originates from ddac_cache_init() which stores a *CacheState via @ptrCast; alignment is guaranteed by c_allocator
     const state: *CacheState = @ptrCast(@alignCast(ptr));
     const path = doc_path orelse return;
     const result_bytes = result orelse return;
@@ -205,7 +212,10 @@ export fn ddac_cache_store(
     if (lmdb.mdb_txn_begin(state.env, null, 0, &txn) != 0) return;
 
     const path_slice = std.mem.span(path);
+    // SAFETY: @constCast is required by LMDB's C API which takes void* for keys; the data is only read, never written by mdb_put for keys
+    // SAFETY: @ptrCast converts [*]const u8 to *anyopaque as required by MDB_val.mv_data field
     var key = lmdb.MDB_val{ .mv_size = path_slice.len, .mv_data = @constCast(@ptrCast(path_slice.ptr)) };
+    // SAFETY: value_buf is a stack-allocated array; @ptrCast converts *[N]u8 to *anyopaque for MDB_val.mv_data; valid for the transaction scope
     var data = lmdb.MDB_val{ .mv_size = value_size, .mv_data = @ptrCast(&value_buf) };
 
     if (lmdb.mdb_put(txn, state.dbi, &key, &data, 0) != 0) {
@@ -219,6 +229,7 @@ export fn ddac_cache_store(
 /// Return the number of entries in the cache.
 export fn ddac_cache_count(handle: ?*anyopaque) u64 {
     const ptr = handle orelse return 0;
+    // SAFETY: ptr originates from ddac_cache_init() which stores a *CacheState via @ptrCast; alignment is guaranteed by c_allocator
     const state: *CacheState = @ptrCast(@alignCast(ptr));
 
     var txn: ?*lmdb.MDB_txn = null;
@@ -235,6 +246,7 @@ export fn ddac_cache_count(handle: ?*anyopaque) u64 {
 /// Call this periodically for durability or before graceful shutdown.
 export fn ddac_cache_sync(handle: ?*anyopaque) void {
     const ptr = handle orelse return;
+    // SAFETY: ptr originates from ddac_cache_init() which stores a *CacheState via @ptrCast; alignment is guaranteed by c_allocator
     const state: *CacheState = @ptrCast(@alignCast(ptr));
     _ = lmdb.mdb_env_sync(state.env, 1);
 }

ffi/zig/src/capnp.zig

@@ -312,11 +312,13 @@ pub const Builder = struct {
 
     fn wr64(self: *Builder, off: usize, val: u64) void {
         if (off + 8 > self.cap) return;
+        // SAFETY: bounds check on line above ensures off + 8 <= cap; buf is caller-provided aligned buffer; align(1) permits unaligned write
         @as(*align(1) u64, @ptrCast(self.buf + off)).* = std.mem.nativeToLittle(u64, val);
     }
 
     fn wr32(self: *Builder, off: usize, val: u32) void {
         if (off + 4 > self.cap) return;
+        // SAFETY: bounds check on line above ensures off + 4 <= cap; buf is caller-provided aligned buffer; align(1) permits unaligned write
         @as(*align(1) u32, @ptrCast(self.buf + off)).* = std.mem.nativeToLittle(u32, val);
     }
 

ffi/zig/src/docudactyl_ffi.zig

@@ -396,6 +396,7 @@ fn parseImage(input_path: [*:0]const u8, output_path: [*:0]const u8, state: *Han
         result.status = 2;
         return;
     }
+    // SAFETY: @constCast required because pixDestroy takes *?*PIX (mutable pointer) but only reads then nullifies; pix will not be used after this
     defer c.pixDestroy(@constCast(&pix));
 
     // Check minimum dimensions — tiny images (icons, spacers) produce
@@ -809,12 +810,14 @@ export fn ddac_init() ?*anyopaque {
         state.vips_initialised = true;
     }
 
+    // SAFETY: state was just allocated by c_allocator.create(HandleState), which returns a well-aligned *HandleState
     return @ptrCast(state);
 }
 
 /// Free all library contexts. Safe to call with null.
 export fn ddac_free(handle: ?*anyopaque) void {
     const ptr = handle orelse return;
+    // SAFETY: ptr originates from ddac_init() which stores a *HandleState via @ptrCast; alignment is guaranteed by c_allocator
     const state: *HandleState = @ptrCast(@alignCast(ptr));
 
     if (state.tess_api) |tess| {
@@ -853,6 +856,7 @@ export fn ddac_parse(
         copyToFixed(256, &result.error_msg, "Null handle");
         return result;
     };
+    // SAFETY: ptr originates from ddac_init() which stores a *HandleState via @ptrCast; alignment is guaranteed by c_allocator
     const state: *HandleState = @ptrCast(@alignCast(ptr));
 
     const in_path = input_path orelse {
@@ -874,6 +878,7 @@ export fn ddac_parse(
         result.status = 2; // FileNotFound
         copyToFixed(256, &result.error_msg, "File not found: ");
         // Append as much of the path as fits
+        // SAFETY: error_msg is a [256]u8 array that was null-terminated by copyToFixed; casting to [*:0]const u8 is valid for std.mem.len
         const prefix_len = std.mem.len(@as([*:0]const u8, @ptrCast(&result.error_msg)));
         const remaining = 255 - prefix_len;
         const path_len = @min(in_slice.len, remaining);
@@ -921,6 +926,7 @@ export fn ddac_parse(
             .char_count = result.char_count,
             .duration_sec = result.duration_sec,
             .ocr_confidence = captured.ocr_confidence,
+            // SAFETY: TessBaseAPI* from Tesseract C API is cast to *anyopaque for the generic StageContext; the stages module casts it back
             .tess_api = if (state.tess_api) |t| @ptrCast(t) else null,
             .ml_handle = state.ml_handle,
         };
@@ -935,6 +941,7 @@ export fn ddac_parse(
 /// (Chapel) — it will NOT be freed by ddac_free().
 export fn ddac_set_ml_handle(handle: ?*anyopaque, ml_handle: ?*anyopaque) void {
     const ptr = handle orelse return;
+    // SAFETY: ptr originates from ddac_init() which stores a *HandleState via @ptrCast; alignment is guaranteed by c_allocator
     const state: *HandleState = @ptrCast(@alignCast(ptr));
     state.ml_handle = ml_handle;
 }
@@ -944,6 +951,7 @@ export fn ddac_set_ml_handle(handle: ?*anyopaque, ml_handle: ?*anyopaque) void {
 /// caller (Chapel) — it will NOT be freed by ddac_free().
 export fn ddac_set_gpu_ocr_handle(handle: ?*anyopaque, ocr_handle: ?*anyopaque) void {
     const ptr = handle orelse return;
+    // SAFETY: ptr originates from ddac_init() which stores a *HandleState via @ptrCast; alignment is guaranteed by c_allocator
     const state: *HandleState = @ptrCast(@alignCast(ptr));
     state.gpu_ocr_handle = ocr_handle;
 }

ffi/zig/src/dragonfly.zig

@@ -209,12 +209,14 @@ export fn ddac_dragonfly_connect(host_port: [*:0]const u8) ?*anyopaque {
         return null;
     }
 
+    // SAFETY: handle was just allocated by c_allocator.create(DfHandle), which returns a well-aligned *DfHandle
     return @ptrCast(handle);
 }
 
 /// Close and free the Dragonfly connection.
 export fn ddac_dragonfly_close(handle: ?*anyopaque) void {
     if (handle) |h| {
+        // SAFETY: h originates from ddac_dragonfly_connect() which stores a *DfHandle via @ptrCast; alignment is guaranteed by c_allocator
         const df: *DfHandle = @ptrCast(@alignCast(h));
         df.client.close();
         std.heap.c_allocator.destroy(df);
@@ -231,6 +233,7 @@ export fn ddac_dragonfly_lookup(
     result_out: [*]u8,
     result_size: usize,
 ) c_int {
+    // SAFETY: handle originates from ddac_dragonfly_connect() which stores a *DfHandle via @ptrCast; alignment is guaranteed by c_allocator
     const df: *DfHandle = @ptrCast(@alignCast(handle));
     const sha = std.mem.span(sha256);
 
@@ -260,6 +263,7 @@ export fn ddac_dragonfly_store(
     result_size: usize,
     ttl_secs: u32,
 ) void {
+    // SAFETY: handle originates from ddac_dragonfly_connect() which stores a *DfHandle via @ptrCast; alignment is guaranteed by c_allocator
     const df: *DfHandle = @ptrCast(@alignCast(handle));
     const sha = std.mem.span(sha256);
 
@@ -276,6 +280,7 @@ export fn ddac_dragonfly_store(
 /// Get the number of ddac keys in the cache (approximate).
 /// Uses DBSIZE command.
 export fn ddac_dragonfly_count(handle: *anyopaque) u64 {
+    // SAFETY: handle originates from ddac_dragonfly_connect() which stores a *DfHandle via @ptrCast; alignment is guaranteed by c_allocator
     const df: *DfHandle = @ptrCast(@alignCast(handle));
     df.client.sendCommand(&[_][]const u8{"DBSIZE"}) catch return 0;
     const n = df.client.readIntegerReply() catch return 0;

ffi/zig/src/gpu_ocr.zig

@@ -329,12 +329,14 @@ fn processBatchGpu(state: *GpuOcrState) void {
 export fn ddac_gpu_ocr_init() ?*anyopaque {
     const allocator = std.heap.c_allocator;
     const state = GpuOcrState.init(allocator) catch return null;
+    // SAFETY: state was just allocated by c_allocator.create(GpuOcrState), which returns a well-aligned *GpuOcrState
     return @ptrCast(state);
 }
 
 /// Free the GPU OCR coprocessor.
 export fn ddac_gpu_ocr_free(handle: ?*anyopaque) void {
     const ptr = handle orelse return;
+    // SAFETY: ptr originates from ddac_gpu_ocr_init() which stores a *GpuOcrState via @ptrCast; alignment is guaranteed by c_allocator
     const state: *GpuOcrState = @ptrCast(@alignCast(ptr));
     state.deinit();
 }
@@ -343,6 +345,7 @@ export fn ddac_gpu_ocr_free(handle: ?*anyopaque) void {
 /// Returns: 0=paddle_gpu, 1=tesseract_cuda, 2=cpu_only
 export fn ddac_gpu_ocr_backend(handle: ?*anyopaque) u8 {
     const ptr = handle orelse return 2;
+    // SAFETY: ptr originates from ddac_gpu_ocr_init() which stores a *GpuOcrState via @ptrCast; alignment is guaranteed by c_allocator
     const state: *GpuOcrState = @ptrCast(@alignCast(ptr));
     return @intFromEnum(state.backend);
 }
@@ -356,6 +359,7 @@ export fn ddac_gpu_ocr_submit(
     output_path: [*:0]const u8,
 ) c_int {
     const ptr = handle orelse return -1;
+    // SAFETY: ptr originates from ddac_gpu_ocr_init() which stores a *GpuOcrState via @ptrCast; alignment is guaranteed by c_allocator
     const state: *GpuOcrState = @ptrCast(@alignCast(ptr));
 
     if (state.queue_len >= MAX_BATCH_SIZE) return -1;
@@ -381,6 +385,7 @@ export fn ddac_gpu_ocr_submit(
 /// Call this before collecting results if the queue isn't full.
 export fn ddac_gpu_ocr_flush(handle: ?*anyopaque) void {
     const ptr = handle orelse return;
+    // SAFETY: ptr originates from ddac_gpu_ocr_init() which stores a *GpuOcrState via @ptrCast; alignment is guaranteed by c_allocator
     const state: *GpuOcrState = @ptrCast(@alignCast(ptr));
 
     if (state.queue_len > 0) {
@@ -391,6 +396,7 @@ export fn ddac_gpu_ocr_flush(handle: ?*anyopaque) void {
 /// Get the number of results ready to collect after flush.
 export fn ddac_gpu_ocr_results_ready(handle: ?*anyopaque) u32 {
     const ptr = handle orelse return 0;
+    // SAFETY: ptr originates from ddac_gpu_ocr_init() which stores a *GpuOcrState via @ptrCast; alignment is guaranteed by c_allocator
     const state: *GpuOcrState = @ptrCast(@alignCast(ptr));
     return state.results_ready;
 }
@@ -404,6 +410,7 @@ export fn ddac_gpu_ocr_collect(
     result_out: *OcrResult,
 ) c_int {
     const ptr = handle orelse return -1;
+    // SAFETY: ptr originates from ddac_gpu_ocr_init() which stores a *GpuOcrState via @ptrCast; alignment is guaranteed by c_allocator
     const state: *GpuOcrState = @ptrCast(@alignCast(ptr));
 
     if (slot_id >= state.results_ready) return -1;
@@ -427,6 +434,7 @@ export fn ddac_gpu_ocr_stats(
         gpu_time_us.* = 0;
         return;
     };
+    // SAFETY: ptr originates from ddac_gpu_ocr_init() which stores a *GpuOcrState via @ptrCast; alignment is guaranteed by c_allocator
     const state: *GpuOcrState = @ptrCast(@alignCast(ptr));
     submitted.* = state.total_submitted;
     completed.* = state.total_completed;

ffi/zig/src/lith_adapter.zig

@@ -68,12 +68,14 @@ pub const Reader = struct {
     pub fn readU64(self: Reader, off: usize) u64 {
         const abs = self.data_start + off;
         if (abs + 8 > self.seg_len) return 0;
+        // SAFETY: bounds check on line above ensures abs + 8 <= seg_len; seg is a valid segment pointer from Reader.init
         return std.mem.readInt(u64, @as(*const [8]u8, @ptrCast(self.seg + abs)), .little);
     }
 
     pub fn readU32(self: Reader, off: usize) u32 {
         const abs = self.data_start + off;
         if (abs + 4 > self.seg_len) return 0;
+        // SAFETY: bounds check on line above ensures abs + 4 <= seg_len; seg is a valid segment pointer from Reader.init
         return std.mem.readInt(u32, @as(*const [4]u8, @ptrCast(self.seg + abs)), .little);
     }
 
@@ -93,6 +95,7 @@ pub const Reader = struct {
         const ptr_off = self.ptr_start + ptr_idx * 8;
         if (ptr_off + 8 > self.seg_len) return &.{};
 
+        // SAFETY: bounds check on line 94 ensures ptr_off + 8 <= seg_len; seg is a valid Cap'n Proto segment pointer
         const raw = std.mem.readInt(u64, @as(*const [8]u8, @ptrCast(self.seg + ptr_off)), .little);
 
         // Null pointer check.
@@ -127,6 +130,7 @@ pub const Reader = struct {
         const ptr_off = self.ptr_start + ptr_idx * 8;
         if (ptr_off + 8 > self.seg_len) return .{ .base = 0, .count = 0 };
 
+        // SAFETY: bounds check on line 128 ensures ptr_off + 8 <= seg_len; seg is a valid Cap'n Proto segment pointer
         const raw = std.mem.readInt(u64, @as(*const [8]u8, @ptrCast(self.seg + ptr_off)), .little);
         if (raw == 0) return .{ .base = 0, .count = 0 };
         if (raw & 3 != 1) return .{ .base = 0, .count = 0 };
@@ -151,6 +155,7 @@ pub const Reader = struct {
         const elem_ptr_off = list_base + elem_idx * 8;
         if (elem_ptr_off + 8 > self.seg_len) return &.{};
 
+        // SAFETY: bounds check on line 152 ensures elem_ptr_off + 8 <= seg_len; seg is a valid Cap'n Proto segment pointer
         const raw = std.mem.readInt(u64, @as(*const [8]u8, @ptrCast(self.seg + elem_ptr_off)), .little);
         if (raw == 0) return &.{};
         if (raw & 3 != 1) return &.{};

ffi/zig/src/ml_inference.zig

@@ -296,12 +296,14 @@ const MlEngine = struct {
 export fn ddac_ml_init() ?*anyopaque {
     const allocator = std.heap.c_allocator;
     const engine = MlEngine.init(allocator) catch return null;
+    // SAFETY: engine was just allocated by c_allocator.create(MlEngine), which returns a well-aligned *MlEngine
     return @ptrCast(engine);
 }
 
 /// Free the ML inference engine.
 export fn ddac_ml_free(handle: ?*anyopaque) void {
     const ptr = handle orelse return;
+    // SAFETY: ptr originates from ddac_ml_init() which stores a *MlEngine via @ptrCast; alignment is guaranteed by c_allocator
     const engine: *MlEngine = @ptrCast(@alignCast(ptr));
     engine.deinit();
 }
@@ -310,6 +312,7 @@ export fn ddac_ml_free(handle: ?*anyopaque) void {
 /// Returns 1 if available, 0 if not.
 export fn ddac_ml_available(handle: ?*anyopaque) u8 {
     const ptr = handle orelse return 0;
+    // SAFETY: ptr originates from ddac_ml_init() which stores a *MlEngine via @ptrCast; alignment is guaranteed by c_allocator
     const engine: *MlEngine = @ptrCast(@alignCast(ptr));
     return if (engine.ort.available) 1 else 0;
 }
@@ -318,13 +321,15 @@ export fn ddac_ml_available(handle: ?*anyopaque) u8 {
 /// Returns: 0=TensorRT, 1=CUDA, 2=OpenVINO, 3=CPU
 export fn ddac_ml_provider(handle: ?*anyopaque) u8 {
     const ptr = handle orelse return 3;
+    // SAFETY: ptr originates from ddac_ml_init() which stores a *MlEngine via @ptrCast; alignment is guaranteed by c_allocator
     const engine: *MlEngine = @ptrCast(@alignCast(ptr));
     return @intFromEnum(engine.ort.provider);
 }
 
 /// Get human-readable name for the execution provider.
 export fn ddac_ml_provider_name(handle: ?*anyopaque) [*:0]const u8 {
     const ptr = handle orelse return "unavailable";
+    // SAFETY: ptr originates from ddac_ml_init() which stores a *MlEngine via @ptrCast; alignment is guaranteed by c_allocator
     const engine: *MlEngine = @ptrCast(@alignCast(ptr));
     return switch (engine.ort.provider) {
         .tensorrt => "TensorRT (NVIDIA INT8/FP16)",
@@ -339,6 +344,7 @@ export fn ddac_ml_provider_name(handle: ?*anyopaque) [*:0]const u8 {
 ///                  layout_analysis.onnx, handwriting_ocr.onnx
 export fn ddac_ml_set_model_dir(handle: ?*anyopaque, dir: [*:0]const u8) void {
     const ptr = handle orelse return;
+    // SAFETY: ptr originates from ddac_ml_init() which stores a *MlEngine via @ptrCast; alignment is guaranteed by c_allocator
     const engine: *MlEngine = @ptrCast(@alignCast(ptr));
     engine.setModelDir(std.mem.span(dir));
 }
@@ -359,6 +365,7 @@ export fn ddac_ml_run_stage(
         result_out.status = 4; // onnx_not_available
         return -1;
     };
+    // SAFETY: ptr originates from ddac_ml_init() which stores a *MlEngine via @ptrCast; alignment is guaranteed by c_allocator
     const engine: *MlEngine = @ptrCast(@alignCast(ptr));
 
     if (stage >= ML_STAGE_COUNT) {
@@ -384,6 +391,7 @@ export fn ddac_ml_stats(
         total_inference_us.* = 0;
         return;
     };
+    // SAFETY: ptr originates from ddac_ml_init() which stores a *MlEngine via @ptrCast; alignment is guaranteed by c_allocator
     const engine: *MlEngine = @ptrCast(@alignCast(ptr));
     total_inferences.* = engine.total_inferences;
     total_inference_us.* = engine.total_inference_us;
@@ -402,5 +410,6 @@ export fn ddac_ml_stage_count() u8 {
 /// Get the model filename for a stage.
 export fn ddac_ml_model_name(stage: u8) [*:0]const u8 {
     if (stage >= ML_STAGE_COUNT) return "unknown";
+    // SAFETY: MODEL_NAMES[stage] is a comptime string literal; .ptr is a valid [*]const u8 that is null-terminated by Zig's string literal guarantee
     return @ptrCast(MlEngine.MODEL_NAMES[stage].ptr);
 }