cimpl 0.4.0

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [0.4.0]
_14 September 2026_

Syncs cimpl with the pointer-registry rewrite done for the embedded copy in
c2pa-rs, replacing simple pointer validation with borrow-checked handle
tracking.

### Added

- Handle-based pointer tracking: tracked pointers are now opaque, scrambled
  ids (not real addresses), so a stale handle can never alias a different
  object that later reuses the same address
- Reader/writer borrow tracking per handle via `checkout_shared()` /
  `checkout_exclusive()`, returning RAII guards (`SharedCheckout`,
  `ExclusiveCheckout`, `TypedShared<T>`, `TypedExclusive<T>`) instead of bare
  references, so concurrent misuse of a handle is rejected instead of racing.
  `deref_or_return!` / `deref_mut_or_return!` now check out a guarded borrow
  under the hood rather than dereferencing directly
- `deref_mut_option!`, `deref_mut_option_or_return!`,
  `deref_mut_option_or_return_int!` macros for parameters where NULL is a
  legitimate "not provided" rather than an error
- `cstr_array_or_return_null!` macro for NULL-terminated `*const *const
  c_char` C string arrays
- New `Error` variants/constructors: `foreign_process()` (registry accessed
  after `fork()` without `exec()`), `wrong_wrapper_kind()` (`Arc`- vs
  `Box`-backed handle mismatch on consuming ownership), `tracking_refused()`
  (handle id space exhausted, or other tracking failures), `pointer_in_use()`
  (exclusive borrow already outstanding)
- `ensure_trackable()`, `is_safe_buffer_size()`, `track_string_array()`,
  `untrack_owned()`, `untrack_owned_pair()` utility functions
- Fork safety: registry calls from a process that didn't create the registry
  now fail with `ForeignProcess` instead of corrupting shared state

### Changed

- Mutex poisoning in the pointer registry is now recovered from instead of
  surfaced as `MutexPoisoned` — a panic elsewhere no longer permanently
  bricks every previously tracked handle (`Error::mutex_poisoned()` is kept
  only for the existing test that exercises it directly)
- `untrack_pointer()` replaced by `untrack_owned()` (single handle) and
  `untrack_owned_pair()` (two handles, taken atomically so a partial failure
  can't leak one side)
- Bumped `rust-version` to 1.87

### Removed

- `validate_pointer` (was `#[doc(hidden)]` and re-exported only for macro
  use) — superseded by `checkout_shared()` / `checkout_exclusive()`
- `MAX_CSTRING_LEN` / `MAX_STRING_ARRAY_LEN` public constants from
  `macros.rs`

## [0.3.1]
_16 February 2026_

### Documentation

- Enhanced crate-level documentation with origin story from c2pa-rs development at Adobe
- Added comprehensive "Why cimpl?" section explaining the AI insight
- Updated all examples to use current API (thiserror, Error::from_error())
- Fixed all rustdoc warnings for clean docs.rs build
- Added links to AI_WORKFLOW.md and PHILOSOPHY.md

### Changed

- Removed unused `paste` dependency (now zero dependencies)

## [0.3.0]
_16 February 2026_

### Note

This is a **new project** taking over the `cimpl` crate name. Previous versions (0.1.0, 0.1.1, 0.2.0) were a different, unrelated project and have been yanked. This version represents a complete rewrite with a different purpose and API.

### Documentation

**Comprehensive crate-level documentation:**
- Added complete "Why cimpl?" section with origin story from c2pa-rs development at Adobe
- Explains the insight: AI excels at C API bindings, Rust natively supports C APIs
- Documents string-based error handling with `Error::from_error()`
- Shows current macro usage patterns (`deref_or_return!`, `ok_or_return!`)
- Includes working example with thiserror integration
- Complete feature list organized by category (pointer safety, strings, bytes, results, options)
- Links to AI_WORKFLOW.md and PHILOSOPHY.md guides
- References both example projects (reference and uuid)
- Highlights AI-friendly design with 15-minute generation proof

**Zero dependencies:**
- Removed unused `paste` crate dependency
- Library now has zero runtime dependencies

**Documentation quality:**
- Fixed all rustdoc warnings (HTML tags, ambiguous links)
- Clean docs.rs build with no warnings

### Added

**Core FFI Infrastructure:**
- Comprehensive macro system for safe C FFI bindings
- Type-safe pointer tracking with validation and leak detection
- Thread-local error storage with string-based error format (`"VariantName: details"`)
- Automatic memory management with `box_tracked!`, `arc_tracked!` macros
- Universal `cimpl_free()` function for tracked allocations

**Pointer Handling Macros:**
- `ptr_or_return!()` family - Null pointer validation
- `deref_or_return!()` family - Safe pointer dereferencing (immutable)
- `deref_mut_or_return!()` family - Safe pointer dereferencing (mutable)
- Support for custom return values (`_null`, `_int`, `_zero`, `_false` variants)

**String Conversion Macros:**
- `cstr_or_return!()` family - C string to Rust with UTF-8 validation
- `to_c_string()` - Rust String to tracked C string
- `option_to_c_string!()` - Option<String> to C string (NULL if None)

**Byte Array Macros:**
- `bytes_or_return!()` family - Validate and convert C byte arrays
- `to_c_bytes()` - Rust Vec<u8> to tracked C byte array

**Result Handling Macros:**
- `ok_or_return!()` family - Result unwrapping with automatic error conversion
- Works with any error type implementing `Into<cimpl::Error>`

**Option Handling Macros:**
- `some_or_return!()` family - Option unwrapping with custom errors
- `some_or_return_other!()` family - Option with Error::other message

**Error System:**
- `Error::new(variant, message)` - Manual error construction
- `Error::from_error(e)` - Automatic error conversion from any std::error::Error
- `Error::last_message()` - Thread-local error retrieval
- `Error::set_last()` - Set thread-local error
- String-based format enables easy parsing in any language

**Documentation:**
- Comprehensive `README.md` with examples and comparison to alternatives
- `AI_WORKFLOW.md` - Complete guide for AI-assisted FFI development
- `PHILOSOPHY.md` - Design principles and three-stage pipeline explanation
- Pre-flight checklist for common anti-patterns

**Examples:**
- `examples/reference/` - Complete ValueConverter example showing all patterns
  - Clean lib.rs/ffi.rs separation
  - Full Python bindings with ctypes
  - Demonstrates struct methods, constructors, error handling
- `examples/uuid/` - Real-world external crate wrapping
  - 15 FFI functions exposing uuid crate
  - Complete Python bindings
  - **AI-generated in 15 minutes** from documentation
  - Demonstrates direct external crate usage pattern

### Features

- Pattern-driven design enabling AI code generation
- Zero unsafe code needed in user FFI functions
- Type validation prevents pointer confusion
- Memory leak detection in tests
- Double-free protection
- Cross-language error format
- cbindgen integration for C header generation
- Production-ready examples with documentation

### Philosophy

The vision: **Write Rust once → Clean C API → AI generates bindings for all languages**

This library enables:
1. Safe, ergonomic FFI from Rust
2. Universal C ABI as stable interface
3. AI-friendly patterns for automatic binding generation

Proven with real AI generation: Complete UUID FFI wrapper created in 15 minutes with zero errors.

---

## Previous Versions (Different Project - Yanked)

**Note:** Versions 0.1.0, 0.1.1, and 0.2.0 were a different project by a previous owner and are not related to this crate. They have been yanked and should not be used.