fix: critical stability, security, and build improvements

[trbielec]

Overview

This Pull Request addresses fundamental stability and security vulnerabilities identified during a production readiness audit. It resolves critical memory safety issues, prevents data corruption during updates, enables deployment on managed platforms, and provides complete installation documentation.

Closes: #20, #26, #27

Changes

1. Core Stability & Security

• Security (Buffer Overread): Replaced unsafe strlen() calls on JSONB strings (which are not null-terminated) with AMbytes(). This prevents potential information disclosure or segfaults during from_jsonb.
• Security (DoS): Added check_stack_depth() guard clauses to all recursive functions (_object_walk, _array_walk, _autodoc_traverse) to prevent stack overflow attacks via deeply nested inputs.
• Data Integrity (Stale Cache): Implemented explicit invalidate_flat_cache() logic in all modification paths. This ensures that sequential UPDATE operations correctly persist the latest state, fixing a bug where stale binary data was written to disk causing data loss.
• Correctness: Added missing AM_OBJ_TYPE_TEXT handler in autodoc_to_jsonb, resolving silent data loss when exporting lists containing Text objects.

2. Build System & Deployment

• Performance: Switched compilation flags from -O0 (debug) to -O2 (production), providing significant performance improvements for serialization-heavy workloads.
• Deployment: Introduced AUTOMERGE_STATIC=1 build flag. This enables static linking of libautomerge.a, allowing the extension to be deployed on managed PostgreSQL platforms (e.g., AWS RDS, Supabase) where system-level shared libraries cannot be installed.

3. Documentation

• Updated README: Added complete installation instructions for both static and dynamic linking workflows.
• Examples: Added clear usage examples for basic operations, modification, and merging to address lack of working examples.

4. Verification

• Regression Suite: Added sql/production_fixes.sql containing tests for stale cache invalidation, buffer safety, text list export, and numeric precision warnings.
• Memory Safety: Validated with Valgrind (0 leaks found in extension code).
• Platform: Verified build and test pass on PostgreSQL 18 (Linux/x86_64).

Impact

These changes are mandatory for production deployment. Without them, the extension is vulnerable to denial-of-service attacks and silent data corruption during standard SQL UPDATE workflows. The build updates allow the extension to run on modern managed cloud infrastructure.