Revision history for AmberDB

5.23.0  2026-09-02
        - [ARCHITECTURE & ID SIMPLIFICATION] Pure 64-bit Binary Engine & Deprecation of 8-Byte ASCII IDs:
          * Deprecated 8-byte ASCII IDs (a8) across binary index structures in favor of pure 64-bit Big-Endian unsigned integer packing (Q>*), guaranteeing O(1) binary slicing with fixed 8-byte record strides.
          * Simplified bin_encode() and bin_decode() by removing fragile \0 byte auto-detection and string unpacking heuristics.
          * Removed legacy id_type schema attribute across all modules and test suites; standard relational tables strictly enforce positive integer numeric IDs.
        - [STORAGE & PER-TABLE SIMPLE MODE] Hybrid Multi-Model Architecture with use_simple => 1:
          * Introduced per-table use_simple => 1 attribute allowing key-value tables with arbitrary string keys up to 255 bytes (UUIDs, session tokens, emails, slugs, etc.) alongside standard relational tables.
          * Preserved canonical physical table path ($dbase_dir/tables/$table.db) for use_simple tables in standard database mode.
          * Selective schema sanitization: tables with use_simple => 1 strip indexing, columnar, and caching definitions (blocks, match_block, search_block, facet_block, sort_block, record_index, use_cache, cache_ttl) to achieve zero index/cache I/O overhead while preserving behavioral features (keep_deleted, force, no_transact, no_backup, use_menu, log_owner).
          * Enabled keep_deleted => 1 archiving (.del) on use_simple tables.
        - [RDBM & INTEGRITY] Foreign Key and Cross-Table Isolation:
          * Prohibited standard relational tables from binding foreign keys (RDBM) to use_simple tables in rdbm_target() and _resolve_field_value().
        - [TESTS & VERIFICATION] Dedicated Test Coverage:
          * Added comprehensive test suite t/amberdb_table_use_simple.t verifying arbitrary string keys, schema sanitization, zero index file creation, keep_deleted archiving, and RDBM isolation.
          * Cleaned up legacy id_type occurrences across all 41 test files and concurrency stress tests (xt/amberdb_concurrency_stress.t).
        - [DISTRIBUTION & METADATA] Decoupled Internal Module Versions and CPAN no_index:
          * Stripped redundant $VERSION definitions from 15 internal/engine-only modules (Base, Cache, Transact, Index, Index::Facet, Index::Junk, Locale::Currency, Locale::Lang::*) to streamline release maintenance.
          * Retained explicit $VERSION in public, standalone modules (AmberDB, AmberDB::Array, AmberDB::Date, AmberDB::Locale, AmberDB::String, AmberDB::Tools).
          * Added comprehensive META_MERGE no_index configuration in Makefile.PL covering internal directories, namespaces, and packages.
        - [DATA STRUCTURES & UTILITIES] Non-Destructive hash_diff in AmberDB::Array:
          * Implemented hash_diff($hash1, $hash2) in AmberDB::Array with safe shallow copying, ensuring input hash structures are never mutated.
          * Removed legacy internal _hash_diff from AmberDB::Tools and switched to $adb->hash_diff directly.
          * Added unit test coverage for hash_diff in t/amberdb_array.t.

5.22.2  2026-09-01
        - [CROSS-PLATFORM & CI] Universal GitHub Actions CI Matrix:
          * Configured multi-platform CI matrix testing on Linux (ubuntu-latest), macOS (macos-latest), and Windows (windows-latest) across Perl 5.16 through 5.40.
          * Configured official Strawberry Perl distribution in CI for native Berkeley DB / DB_File binary compatibility and prevented Git Bash PATH collisions.
        - [STORAGE & TRANSACTIONS] Safe Directory Scanner and Windows File Sharing:
          * Introduced dir_files($dir, [$pattern], [%opts]) helper method in AmberDB::Base for cross-platform, safe file discovery supporting wildcards (*.db, txn_*.txn) and compiled regular expressions (qr/../).
          * Refactored AmberDB::Transact and AmberDB::Tools (dir_tables, all_tables, del_table) to use dir_files, completely removing fragile glob usage.
          * Fixed Windows NTFS file sharing collision in transact_recover: journal lines are now read directly from open locked handles, preventing secondary open permission denied errors.
        - [TESTS & STABILITY] Test Concurrency and Monotonic Sequence:
          * Hardened t/amberdb_transact.t orphan recovery subtest to use strictly monotonic table_autoid record IDs (65) and authentic transaction lifecycle simulation.
          * Guaranteed complete handle and lock cleanup with $adb->close_all() in crash recovery test scenarios.

5.22.1  2026-09-01
        - [DOCS] Documentation and Synopsis Fixes:
          * Fixed synopsis and API example signatures across documentation and POD.
          * Updated README.md installation instructions with streamlined CPAN/cpanm cross-platform support.
          * Fixed character encoding and wide-character warnings in test suite schemas.

5.22.0  2026-08-31
        - [REFACTOR] Codebase Cleanliness:
          * Removed redundant single-line helper is_rdbm_block() in favor of direct rdbm_target() calls across AmberDB::Index, AmberDB::Index::Junk, and AmberDB::Tools.
        - [RDBM & INTEGRITY] Hardened Foreign Table Auto-Registration in field_to_list():
          * Replaced decoupled table_autoid() and recs_put() sequence with atomic insert_id($target_table, 0, @record) to prevent ID race conditions.
          * Corrected foreign record column alignment so auto-registered values are accurately placed at block index $target_blk rather than hardcoded column 1.
          * Guaranteed that foreign table primary indexes (.inx) and secondary indexes (.unq, .src, .fac, .slg) are fully and consistently constructed upon auto-registration.
        - [SECURITY & VALIDATION] Universal ID Verification and Simple Mode Key Sanitization:
          * Eliminated opt-in config('id_check') requirement: every schema table now strictly enforces its schema id_type (positive integers for num, safe 8-byte chars for ascii).
          * Enforced scalar ID requirement: any reference (ARRAY ref, HASH ref, etc.) passed as a record ID is strictly rejected across all modes.
          * Introduced Safe Key Sanitization in Simple Mode: automatically trims leading/trailing whitespace, strictly rejects NUL bytes (\0) and control characters (\r, \n, \t, \x00-\x1F, \x7F) that corrupt Berkeley DB or CSV backups, and enforces a maximum key length of 255 bytes.
          * Integrated unconditional id_check across table_autoid(), read_id(), modify_id(), delete_id(), and exist_id().
        - [REFACTOR] Terminology and Codebase Refactoring: SEO -> Slug:
          * Completely replaced SEO terminology with Slug across the entire codebase, test suite, and documentation without legacy aliases:
            - Renamed methods: set_seourl() -> set_slug(), get_seourl() -> get_slug().
            - Renamed schema attributes: seo_block -> slug_block, seo_max_len -> slug_max_len.
          * Renamed test suite t/amberdb_seo_facet_bulk.t to t/amberdb_slug_facet_bulk.t.
        - [STORAGE] Standardized URL Slug Map File Extension: .rwt -> .slg:
          * Renamed binary slug map files from _0.rwt / _1.rwt to _0.slg (ID -> Slug) and _1.slg (Slug -> ID) across AmberDB, Index, Transact, and Tools.
          * Updated Tools->set_index() to reconstruct .slg files with zero data loss.
        - [DOCS] Caching Terminology Unification:
          * Completely removed deprecated L1/L2 caching terminology from all documentation and POD.
          * Standardized on unified "Shared RAM-Disk (tmpfs / ImDisk) Cache" architecture.
        - [TESTS & CONCURRENCY] Cross-Platform Multi-Process Concurrency Stress Testing:
          * Upgraded xt/amberdb_concurrency_stress.t to an OS-aware unified architecture supporting both Linux (POSIX fork+exec) and Windows (independent asynchronous perl.exe processes).
          * Ensures full operating system-level flock(LOCK_EX) lock isolation on Windows without CRT/pseudo-fork thread contention.
          * Comprehensive validation across 5 concurrency scenarios:
            1. Multi-worker parallel writes with secondary index synchronization (.inx, .fld, .src, .fac, .srt, .slg).
            2. Interleaved concurrent reads and writes without deadlocks or corruption.
            3. Concurrent independent transactions with simulated mid-operation process crashes and orphan recovery (transact_recover).
            4. High-concurrency duplicate title insertion verifying deterministic URL slug collision resolution and 100% bidirectional bijection.
            5. Shared record inventory decrements using record-level locks (flock_open / flock_close).
        - Added Section 7.8 ("Multi-Process Concurrency, Lock Isolation, and Stress Verification") to Turkish and English documentation.
        - Updated README.md with concurrency stress testing instructions.

5.21.1  2026-08-29
        - Fixed read_id return signature across documentation examples to consistently return array format.
        - Streamlined transaction workflow documentation to use transact_error() for business validations with automatic commit/rollback in transact_end().
        - Clarified field_fetch return signatures in English documentation to reflect full record retrieval.
        - Declared missing core dependencies (Archive::Tar, Digest::SHA, JSON::PP, Hash::Util) in Makefile.PL and cpanfile.

5.21.0  2026-08-28
        - Fixed schema cache poisoning in restore() and hardened dbase_info()/table_info() against caching empty parse results.
        - Standardized instance variable naming across codebase, test suites, and documentation to $adb (AmberDB Handle):
          * Introduced $adb->config() method supporting scalar get, defensive copy bulk get, and side-effect hook execution (locale reloading, path cache invalidation).
          * Introduced $adb->path() method for standardized path retrieval and modification across core modules and scripts.
          * Enhanced $adb->table_attr() with unified getter/setter and automatic path refresh on schema changes (year, section, lang).
          * Protected $adb->table_info() by returning shallow copies to prevent external reference leaking and unauthorized in-memory state mutations.
          * Refactored all internal core modules (lib/AmberDB.pm, lib/AmberDB/Base.pm, lib/AmberDB/Tools.pm, lib/AmberDB/Transact.pm, lib/AmberDB/Cache.pm, lib/AmberDB/Index/Junk.pm) to interact strictly through accessor methods ($adb->config, $adb->path, $adb->table_attr, $adb->table_info) eliminating raw hash accesses.
          * Enforced restricted hash key access via Hash::Util::lock_keys with private internal naming (_cfg, _path, _table, _dbase, _cache, _db, _txn) and locked container references (Hash::Util::lock_value) against typo/unauthorized overwrites.
          * Added comprehensive unit test suite t/amberdb_encapsulation.t covering all 10 encapsulation scenarios.
        - [MIGRATION NOTICE / BREAKING CHANGE] Standardized schema terminology across the entire codebase and directory layout:
          * UPGRADE ACTION REQUIRED: Existing projects must rename their physical 'dbstore/scheme/' directory to 'dbstore/schema/'.
          * Updated RAM-disk setup scripts (setup_ramdisk.sh, setup_ramdisk.ps1, setup_ramdisk.pl, setup_ramdisk.bat) to mount 'schema/'.
        - Upgraded transaction engine specification to full ACID-Compliance with Strict Two-Phase Locking (Strict 2PL):
          * Enforced Lock-Before-Write and Lock-Before-Read ordering across insert_id, modify_id, and delete_id for true serializable isolation.
          * Introduced 'no_transact => 1' schema attribute and table_attr() support to exempt auxiliary tables from abort cascades while preserving LIFO rollback consistency.
        - Added comprehensive ACID architectural guarantees section to documentation (README.md, Turkish and English User Guides).
        - Clarified architectural distinction between high-throughput batch ETL imports and atomic business transactions.
        - Standardized file open error diagnostics and OS-level reporting ($!) across all core modules:
          * Added explicit OS error reporting ($!) to all open and tie failures in AmberDB, Base, Cache, Transact, and Tools.
          * Replaced silent schema open failure in AmberDB::Base::table_write with diagnostic cluck and graceful return.
          * Improved audit log error handling in AmberDB::auth_insert with cluck and record skipping.
        - Redesigned 2-Pillar Disaster Recovery and Native Backup Architecture:
          * Upgraded recs_back to continuous chronological time-series stream in 'backup/YYYY/YYYY-MM-DD.csv' eliminating folder clutter and ensuring zero-data-loss logging.
          * Added Tools->dump() for creating portable, compressed '.amberdb' archives packaging schemas (schema/*.table, schema/*.dbase), authoritative data files (tables/*.db, tables/*.del, tables/*.aut, tables/*.cnt, tables/*_*.str), and cryptographic SHA-256 integrity manifests (excluding derived indexes).
          * Preserved native physical directory layout (schema/ and tables/) in .amberdb archives for 1-to-1 extraction and portability.
          * Added Tools->restore() with SHA-256 checksum verification, non-empty database safety checks, and automated deterministic binary index reconstruction via set_index.
          * Enhanced Tools->all_tables() with dual scalar/list context (grouped hashref vs. flat list) and automated 4-digit year directory discovery (e.g. 2024/, 2025/, 2026/).
          * Upgraded 'bin/convert_dbstore.pl' table discovery and added side-file reporting for .str string dictionaries alongside .del, .aut, and .cnt.
          * Introduced CLI utility 'bin/amberdb_backup.pl' for command-line database dump and disaster recovery operations.
          * Added comprehensive unit test suite t/amberdb_backup.t covering WAL streaming, .amberdb archiving, .dbase/.str preservation, and full database restore.
        - Updated POD documentation across AmberDB, AmberDB::Transact, and AmberDB::Tools modules.

5.02    2026-08-25
        - Initial public release prepared for CPAN and GitHub.
        - High-performance Berkeley DB (DB_File) flat-file database engine.
        - Packed 8-byte binary indexing pipeline for O(1) substr slicing.
        - High-speed index-assisted full-text search with phonetic and language normalization.
        - Tiered indexing (Active, Junk/Archived, and Hybrid AB/BA query modes).
        - Multi-dimensional Columnar Facet indexing (.fac) with high-efficiency bitsets.
        - Undo-journal transaction engine (transact_start, transact_end, transact_rollback) with automatic LIFO rollback.
        - Multi-granularity concurrency control (table-level and record-level flock).
        - Multilingual locale engine supporting 9 languages (en, tr, de, fr, es, ja, ru, ar, az) with Turkish dotless/dotted 'i' rules, case folding, and number/currency formatting.
        - Cross-platform RAM-Disk helper and binary index converter CLI tools.
        - Comprehensive test suite covering 37 test suites.
