familia 2.0.0.pre10 → 2.0.0.pre12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f09bb44b39f033bc38faaff02dd33c645ecd6a98bee533a756707daeb47e00c
-  data.tar.gz: 77afd574073258009058ed9f638151b1ca26ba65d06b49f841ad46b52e50a82a
+  metadata.gz: 003a28f3135f0e89f6813e61cf08482350dbff865d2d97971998c714aafcc898
+  data.tar.gz: 6c713c9861043c71d7b2cfc99a37c4522e404ed7461d8dafed5462022735440b
 SHA512:
-  metadata.gz: c9bf8c181236218f04e7fff9902b63521d316265792a416525ee5da671789ddd636c372d0481b926b9b65b3116680bac698ebef6d37fd3d0117c9235053b98aa
-  data.tar.gz: d046f73ca2f6d46833e4bdb0f2a59c6c400b807f5e44f92657a470bd50c09ffae56debfd991f6513898a603ce44e761047d1e4449f8526d3d2a5ac333ebb8e72
+  metadata.gz: b0e4cb9f390ee0a3e1d83cc94a2248690fe757ce343665ef6e4ea6dbd2c74f8f7d07e352661380f0aac23e91f437315300a409847d28896b58b4ddf567d5e953
+  data.tar.gz: 2ec7616c6b2d64d522d441447ac93e58fe89f35eccd357bfdfc65305fc4324122148e5a3722c4bfd613d1f194fac1e5c0228d72b3774aa0e86e09bcdfe8b90fb

data/CHANGELOG.md

@@ -7,8 +7,70 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 <!--scriv-insert-here-->
 
+<a id='changelog-2.0.0.pre12'></a>
+## 2.0.0.pre12 — 2025-09-04
+
+### Added
+
+- Added the `Familia::VerifiableIdentifier` module to create and verify identifiers with an embedded HMAC signature. This allows an application to stateless-ly confirm that an identifier was generated by itself, preventing forged IDs from malicious sources.
+
+- **Scoped VerifiableIdentifier**: Added `scope` parameter to `generate_verifiable_id()` and `verified_identifier?()` methods, enabling cryptographically isolated identifier namespaces for multi-tenant, multi-domain, or multi-environment applications while maintaining full backward compatibility with existing code.
+
+### Changed
+
+- ObjectIdentifier feature now tracks which generator (uuid_v7, uuid_v4, hex, or custom) was used for each objid to provide provenance information for security-sensitive operations.
+- Updated external identifier derivation to normalize objid format based on the known generator type, eliminating format ambiguity between UUID and hex formats.
+
+- Refactored identifier generation methods for clarity and consistency. Method `generate_objid` is now `generate_object_identifier`, and `generate_external_identifier` is now `derive_external_identifier` to reflect its deterministic nature.
+
+### Removed
+
+- Removed the `generate_extid` class method, which was less secure than the instance-level derivation logic.
+
+### Security
+
+- Hardened external identifier derivation with provenance validation. ExternalIdentifier now validates that objid values come from the ObjectIdentifier feature before deriving external identifiers, preventing derivation from potentially malicious or unvalidated objid values while maintaining deterministic behavior for legitimate use cases.
+
+- Improved the security of external identifiers (`extid`) by using the internal object identifier (`objid`) as a seed for a new random value, rather than deriving the `extid` directly. This prevents potential information leakage from the internal `objid`.
+
+### Documentation
+
+- Added detailed YARD documentation for `VerifiableIdentifier`, explaining how to securely generate and manage the required `VERIFIABLE_ID_HMAC_SECRET` key.
+
+### AI Assistance
+
+- Security analysis of external identifier derivation and hardened design approach was discussed and developed with AI assistance, including provenance tracking, validation logic, format normalization, and comprehensive test updates.
+
+- Implementation of scoped verifiable identifiers was developed with AI assistance to ensure cryptographic security properties and comprehensive test coverage.
+
+<a id='changelog-2.0.0.pre11'></a>
+## 2.0.0.pre11 - 2025-09-03
+
+### Added
+
+- **Enhanced Feature System**: Introduced a hierarchical feature system with ancestry chain traversal for model-specific feature registration. This enables better organization, standardized naming, and automatic loading of project-specific features via the new `Familia::Features::Autoloader` module.
+- **Improved SafeDump DSL**: Replaced the internal `@safe_dump_fields` implementation with a cleaner, more robust DSL using `safe_dump_field` and `safe_dump_fields` methods.
+- Added `generate_short_id` and `shorten_securely` utility methods for creating short, secure identifiers, adapted from `OT::Utils::SecureNumbers`.
+- For a detailed guide on migrating to the new feature system, see `docs/migration/v2.0.0-pre11.md`.
+
+### Changed
+
+- External identifier now raises an `ExternalIdentifierError` if the model does not have an objid field. Previously: returned nil. In practice this should never happen, since the external_identifier feature declares its dependency on object_identifier.
+- Moved lib/familia/encryption_request_cache.rb to lib/familia/encryption/request_cache.rb for consistency.
+- **Simplified ObjectIdentifier Feature Implementation**: Consolidated the ObjectIdentifier feature from two files (~190 lines) to a single file (~140 lines) by moving the ObjectIdentifierFieldType class inline. This reduces complexity while maintaining all existing functionality including lazy generation, data integrity preservation, and multiple generator strategies.
+- **Renamed Identifier Features to Singular Form**: Renamed `object_identifier` → `object_identifier` and `external_identifier` → `external_identifier` for more accurate naming. Added full-length aliases (`object_identifier`/`external_identifier`) alongside the short forms (`objid`/`extid`) for clarity when needed.
+- **Simplified ExternalIdentifier Feature Implementation**: Consolidated the ExternalIdentifier feature from two files (~240 lines) to a single file (~120 lines) by moving the ExternalIdentifierFieldType class inline, following the same pattern as ObjectIdentifier.
+
+### Fixed
+
+- Fixed external identifier generation returning all zeros for UUID-based objids. The `shorten_to_external_id` method now correctly handles both 256-bit secure identifiers and 128-bit UUIDs by detecting input length and applying appropriate bit truncation only when needed.
+
+### Security
+
+- Improved input validation in `shorten_to_external_id` method by replacing insecure character count checking with proper bit length calculation and explicit validation. Invalid inputs now raise clear error messages instead of being silently processed incorrectly.
+
 <a id='changelog-2.0.0-pre10'></a>
-## [2.0.0-pre10] - 2025-09-02 18:07:56.439890
+## 2.0.0-pre10 - 2025-09-02
 
 ### Added
 
@@ -45,21 +107,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - This refactoring was implemented with Claude Code assistance, including comprehensive test updates and API modernization.
 
 <a id='changelog-2.0.0-pre9'></a>
-# [2.0.0-pre9] - 2025-09-02 00:35:28.974817
+## 2.0.0-pre9 - 2025-09-02
 
-## Added
+### Added
 
 - Added `class_tracked_in` method for global tracking relationships following Horreum's established `class_` prefix convention
 - Added `class_indexed_by` method for global index relationships with consistent API design
 
-## Changed
+### Changed
 
 - **BREAKING**: `tracked_in :global, collection` syntax now raises ArgumentError - use `class_tracked_in collection` instead
 - **BREAKING**: `indexed_by field, index, context: :global` syntax replaced with `class_indexed_by field, index`
 - **BREAKING**: `indexed_by field, index, context: SomeClass` syntax replaced with `indexed_by field, index, parent: SomeClass`
 - Relationships API now provides consistent parameter naming across all relationship types
 
-## Documentation
+### Documentation
 
 - Updated Relationships Guide with new API syntax and migration examples
 - Updated relationships method documentation with new method signatures
@@ -68,9 +130,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 <a id='changelog-2.0.0-pre8'></a>
-## [2.0.0-pre8] - 2025-09-01
+## 2.0.0-pre8 - 2025-09-01
 
-#### Added
+### Added
 
 - Implemented Scriv-based changelog system for sustainable documentation
 - Added fragment-based workflow for tracking changes
@@ -81,9 +143,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Set up Scriv configuration and directory structure
 - Created README for changelog fragment workflow
 
+<!-- scriv-end-here -->
 
 <a id='changelog-2.0.0-pre7'></a>
-## [2.0.0-pre7] - 2025-08-31
+## 2.0.0-pre7 - 2025-08-31
 
 ### Added
 
@@ -109,7 +172,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 <a id='changelog-2.0.0-pre6'></a>
-## [2.0.0-pre6] - 2025-08-15
+## 2.0.0-pre6 - 2025-08-15
 
 ### Added
 
@@ -136,7 +199,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 <a id='changelog-2.0.0-pre5'></a>
-## [2.0.0-pre5] - 2025-08-05
+## 2.0.0-pre5 - 2025-08-05
 
 ### Added
 
@@ -160,7 +223,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 
 <a id='changelog-2.0.0-pre'></a>
-## [2.0.0-pre] - 2025-07-25
+## 2.0.0-pre - 2025-07-25
 
 ### Added
 
@@ -179,6 +242,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Documentation
 
 - YARD documentation workflow with automated GitHub Pages deployment
-- Comprehensive migration guide for v1.x to v2.0.0-pre transition
+- Comprehensive migrating guide for v1.x to v2.0.0-pre transition
 
 <!-- scriv-end-here -->

data/CLAUDE.md

@@ -32,9 +32,10 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 **Debugging options:**
 - **Stack traces**: `bundle exec try -s` (stack traces without debug logging)
+- **Verbose failures**: `bundle exec try -vfs` (detailed failure output)
 - **Debug mode**: `bundle exec try -D` (additional logging including stack traces)
-- **Verbose failures**: `bundle exec try -vf` (detailed failure output)
-- **Fresh context**: `bundle exec try --fresh-context` (isolate test cases)
+- **Shared context**: `bundle exec try --shared-context` (DEFAULT - reuse shared context across setup, testcases, and teardown)
+- **Fresh context**: `bundle exec try --no-shared-context` (isolate test cases, no shared variables)
 
 *Note: Use `--agent` mode for optimal token efficiency when analyzing test results programmatically.*
 
@@ -60,9 +61,6 @@ Add changelog fragment with each user-facing or documented change (optional but
   - Updates live as tests run or code executes
   - Essential for debugging Familia ORM Database interactions, multi/exec, pipelining, logical_database issues
 
-### Testing Framework
-This project uses `tryouts` instead of RSpec/Minitest. Test files are located in the `try/` directory and follow the pattern `*_try.rb`.
-
 ## Architecture Overview
 
 ### Core Components
@@ -88,7 +86,7 @@ This project uses `tryouts` instead of RSpec/Minitest. Test files are located in
 Familia uses a modular feature system where features are mixed into classes:
 - **Expiration** (`lib/familia/features/expiration.rb`) - TTL management with cascading
 - **SafeDump** (`lib/familia/features/safe_dump.rb`) - API-safe object serialization
-- **Quantization** (`lib/familia/features/quantization.rb`) - Time-based data bucketing
+- **Relationships** (`lib/familia/features/relationships.rb`) - CRUD operations for related objects
 
 #### Key Architectural Patterns
 
@@ -110,15 +108,6 @@ end
 - Proc: `identifier ->(user) { "user:#{user.email}" }`
 - Array: `identifier [:type, :email]`
 
-### Directory Structure
-
-- `lib/familia.rb` - Main entry point and module definition
-- `lib/familia/horreum/` - Horreum class implementation (class_methods, commands, serialization, etc.)
-- `lib/familia/data_type/` - Valkey/Redis type implementations and commands
-- `lib/familia/features/` - Modular feature implementations
-- `try/` - Test files using tryouts framework
-- `try/test_helpers.rb` - Shared test utilities and sample classes
-
 ### Database Connection Management
 - Connection handling in `lib/familia/connection.rb`
 - Settings management in `lib/familia/settings.rb`
@@ -128,46 +117,7 @@ end
 ### Important Implementation Notes
 
 **Field Initialization**: Objects can be initialized with positional args (brittle) or keyword args (robust). Keyword args are recommended.
-
 **Serialization**: Uses JSON by default but supports custom `serialize_value`/`deserialize_value` methods.
-
 **Database Key Generation**: Automatic key generation using class name, identifier, and field/type names (aka dbkey). Pattern: `classname:identifier:fieldname`
-
 **Memory Efficiency**: Only non-nil values are stored in keystore database to optimize memory usage.
-
 **Thread Safety**: Data types are frozen after instantiation to ensure immutability.
-
-## Common Patterns
-
-### Defining a Horreum Class
-```ruby
-class Customer < Familia::Horreum
-  feature :safe_dump
-  feature :expiration
-
-  identifier_field :custid
-  default_expiration 5.years
-
-  field :custid
-  field :email
-  list :sessions
-  hashkey :settings
-end
-```
-
-### Using Features
-```ruby
-# Safe dump for API responses
-customer.safe_dump  # Returns only whitelisted fields
-
-# Expiration management
-customer.update_expiration(default_expiration: 1.hour)
-```
-
-### Transaction Support
-```ruby
-customer.transaction do |conn|
-  conn.set("key1", "value1")
-  conn.zadd("key2", score, member)
-end
-```

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre10)
+    familia (2.0.0.pre12)
       benchmark
       connection_pool
       csv

data/changelog.d/README.md

@@ -4,7 +4,7 @@ This directory contains changelog fragments managed by [Scriv](https://scriv.rea
 
 ## Our Approach
 
-Changelogs are for humans and agents, not just machines. We follow the core principles of [Keep a Changelog](https://keepachangelog.com) to ensure our release notes are clear, consistent, and trustworthy.
+Changelogs are for humans and agents, not just machines. We follow the core principles of [Keep a Changelog](https://keepachangelog.com) and semvar to ensure our release notes are clear, consistent, and useful.
 
 To achieve this, we use a fragment-based workflow with `scriv`. Instead of a single, large `CHANGELOG.md` file that can cause merge conflicts, each developer includes a small changelog fragment with their pull request. At release time, these fragments are collected and aggregated into the main changelog.
 
@@ -12,55 +12,66 @@ This approach provides several benefits:
 - **Reduces Merge Conflicts:** Developers can work in parallel without conflicting over a central changelog file.
 - **Improves Developer Experience:** Creating a small, focused fragment is a simple and repeatable task during development.
 - **Ensures Consistency:** Automation helps maintain a consistent structure for all changelog entries.
+- **AI Transparency:** An opportunity to be specific and detailed about the assistance provided.
 - **Builds Trust:** A clear and well-maintained changelog communicates respect for our users and collaborators.
 
+## Relevant paths
+
+* `changelog.d/` - (e.g. changelog.d/YYYYMMDD_HHmmss_username_branch.md)
+* `docs/migrating/` - (e.g. docs/migrating/v2.0.0-pre.md)
+* `CHANGELOG.md` - The full changelog for all releases, in reverse chronological order. Careful: LARGE DOCUMENT. Limit reading to the first 50 lines.
+
+* `setup.cfg` - Scriv tool settings
+
 ## How to Add a Changelog Entry
 
 1.  **Create a New Fragment:**
-    ```bash
-    scriv create
-    ```
-    This will create a new file in the `changelog.d/fragments/` directory.
 
-    **Alternative:** Use `scriv create --edit` to create and immediately open in your editor.
-    **Important:** You must add content and save before exiting, or scriv will abort with "Empty fragment, aborting..."
+```bash
+# This will create a new file in the `changelog.d/` directory.
+scriv create
+```
 
 2.  **Edit the Fragment File:**
-    Open the newly created file and add your entry under the relevant category. See the guidelines below for writing good entries.
+Open the newly created file and add your entry under the relevant category. See the guidelines below for writing good CHANGELOG entries.
+
+3. **Add or Update Migrating Guide:** (optional)
+Include technical details to help developers update to the new version. Start with a specific introduction, e.g. "This version introduces significant improvements to Familia's feature system, making it easier to organize and use features across complex projects.". Including code snippets and multi-line content that is too detailed for the CHANGELOG.
+
+Use the content of an existing `docs/migrating/vMajor.Minor.Patch*.md file as a reference.
 
-3.  **Commit with Your Code:**
-    ```bash
-    git add changelog.d/fragments/your_fragment_name.md
-    git commit
-    ```
+Compare the headers of your draft content with the headers of the previous migration guide to make sure it does not repeat or overlap.
+
+4.  **Commit with Your Code:**
+```bash
+git add changelog.d/YYYYMMDD_HHmmss_username_branch.md [docs/migrating/v2.0.0-pre.md]
+git commit
+```
 
 ## Fragment Guidelines
 
--   **One Fragment Per Change:** Keep each fragment focused on a single feature, fix, or improvement.
--   **Documenting AI Assistance:** If a change involved significant AI assistance, place it in its own fragment. This ensures the `### AI Assistance` section clearly corresponds to the single change described in that fragment.
--   **Write for a Human Audience:** Describe the *impact* of the change, not just the implementation details.
-    -   **Good:** "Improved the performance and stability of Redis connections under high load."
-    -   **Bad:** "Refactored the `RedisManager` to use a connection pool."
--   **Be Specific:** Avoid generic messages like "fixed a bug." Clearly state what was fixed.
--   **Include Context:** Reference issue or pull request numbers to provide a link to the discussion and implementation details. `scriv` will automatically create links for them.
-    -   **Example:** `- Fixed a bug where users could not reset their passwords. (Closes #123)`
+- **One Fragment Per Change:** Keep each fragment focused on a single feature, fix, or improvement.
+- **Documenting AI Assistance:** If a change involved significant AI assistance, place it in its own fragment. This ensures the `### AI Assistance` section clearly corresponds to the single change described in that fragment.
+- **Write for a Human Audience:** Describe the *impact* of the change, not just the implementation details.
+    - **Good:** "Improved the performance and stability of Redis connections under high load."
+    - **Bad:** "Refactored the `RedisManager`."
+- **Be Specific:** Avoid generic messages like "fixed a bug." Clearly state what was fixed.
+- **Include Context:** Reference issue or pull request numbers to provide a link to the discussion and implementation details. `scriv` will automatically create links for them.
+    - **Example:** `- Fixed a bug where users could not reset their passwords. PR #123`
 
 ### Categories
 
-Use these categories from [Keep a Changelog](https://keepachangelog.com):
+Use these categories:
 
--   **Added**: New features or capabilities.
--   **Changed**: Changes to existing functionality.
--   **Deprecated**: Soon-to-be removed features.
--   **Removed**: Now removed features.
--   **Fixed**: Bug fixes.
--   **Security**: Security-related improvements.
--   **Documentation**: Documentation improvements.
+- **Added**: New features or capabilities.
+- **Changed**: Changes to existing functionality.
+- **Deprecated**: Soon-to-be removed features.
+- **Removed**: Now removed features.
+- **Fixed**: Bug fixes.
+- **Security**: Security-related improvements.
+- **Documentation**: Documentation improvements.
+- **AI Assistance**: Significant AI assistance in the change, including discussion, rubber ducking, formatting, writing documentation, writing tests.
 
 ## Release Process
 
-At release time, an authorized maintainer will collect all fragments into the main `CHANGELOG.md` file:
-
-```bash
-scriv collect --version 2.0.0
-```
+At release time, scriv will collect all fragments into the main `CHANGELOG.md` file with th command `scriv collect`. The version is taken automatically from `lib/familia/version.rb`.

data/docs/archive/FAMILIA_RELATIONSHIPS.md

@@ -189,7 +189,7 @@ customer.find_by_name("production-api-key")
 customer.find_all_by_scope(["read", "write"])
 ```
 
-### Migration Guide
+### Migrating Guide
 If you have existing code with incorrect syntax, here's how to fix it:
 
 ```ruby

data/docs/archive/FAMILIA_UPDATE.md

@@ -179,7 +179,7 @@ end
 
 ---
 
-## Migration Guide Summary
+## Migrating Guide Summary
 
 ### From v1.x to v2.0.0-pre
 1. **Update connection configuration** to use new pooling system

data/docs/archive/README.md

@@ -10,9 +10,9 @@ This directory contains original documentation files that have been migrated to
 ### FAMILIA_UPDATE.md
 **Original Purpose:** Version summary table and detailed release notes for v2.0.0-pre series
 
-**Migration Destinations:**
+**Migrating Destinations:**
 - **Changelog entries** → Extracted to Scriv fragments, aggregated into `CHANGELOG.md`
-- **Migration guides** → Reorganized into `docs/migration/v2.0.0-pre*.md`
+- **Migrating guides** → Reorganized into `docs/migrating/v2.0.0-pre*.md`
 - **Feature descriptions** → Cross-referenced with existing feature guides in `docs/guides/`
 
 ### FAMILIA_RELATIONSHIPS.md
@@ -33,26 +33,22 @@ This directory contains original documentation files that have been migrated to
 
 ```
 docs/
-├── migration/           # Version-specific migration guides
-│   ├── v2.0.0-pre.md   # Foundation migration
-│   ├── v2.0.0-pre5.md  # Security features
-│   ├── v2.0.0-pre6.md  # Architecture improvements
-│   └── v2.0.0-pre7.md  # Relationships system
-├── guides/              # Feature guides (moved from wiki/)
-│   ├── relationships-methods.md  # From FAMILIA_RELATIONSHIPS.md
+├── migrating/              # Version-specific migrating guides
+│   ├── v2.0.0-pre.md
+│   ├── v2.0.0-pre5.md      # Security features
+│   ├── v2.0.0-pre6.md      # Architecture improvements
+│   └── v2.0.0-pre7.md      # Relationships system
+│
+├── guides/                 # Feature-specific guides (moved from wiki/)
+│   ├── relationships.md    # From FAMILIA_RELATIONSHIPS.md
 │   └── [other guides...]
-├── reference/           # Technical reference
-│   └── api-technical.md # From FAMILIA_TECHNICAL.md
-└── archive/            # This directory
+│
+├── reference/              # Technical reference
+│   └── api-technical.md
+│
+└── archive/                # This directory
 ```
 
-## Why These Files Were Archived
-
-1. **Sustainability** - The original files accumulated overlapping content without clear organization
-2. **Maintainability** - Scriv fragment system prevents documentation bloat
-3. **Clarity** - Separation of changelog, guides, and reference improves findability
-4. **Workflow** - Fragment-based workflow scales better with development
-
 ## Finding Migrated Content
 
 - **Version changes** → Check `CHANGELOG.md` (generated from fragments)

data/docs/guides/Home.md

@@ -23,7 +23,7 @@ Welcome to the comprehensive documentation for Familia v2.0. This wiki covers al
 
 ### 🚀 Operations (As Needed)
 
-9. **[Migration Guide](Migration-Guide.md)** - Upgrading existing fields _(coming soon)_
+9. **[Migrating Guide](Migrating-Guide.md)** - Upgrading existing fields _(coming soon)_
 10. **[Key Management](Key-Management.md)** - Rotation and best practices _(coming soon)_
 
 ## 🚀 Quick Start Examples

data/docs/guides/Implementation-Guide.md

@@ -273,4 +273,4 @@ end
 
 - [Security Model](Security-Model) - Understand the cryptographic design
 - [Key Management](Key-Management) - Rotation and best practices
-- [Migration Guide](Migration-Guide) - Upgrade existing fields
+- [Migrating Guide](Migrating-Guide) - Upgrade existing fields

data/docs/guides/relationships-methods.md

@@ -234,7 +234,7 @@ customer.find_by_name("production-api-key")
 customer.find_all_by_scope(["read", "write"])
 ```
 
-### Migration Guide
+### Migrating Guide
 If you have existing code with old syntax, here's how to update it:
 
 ```ruby

data/docs/migrating/.gitignore

@@ -0,0 +1,2 @@
+# Even all wiki markdown docs get the blues
+!*.md

data/docs/migrating/v2.0.0-pre.md

@@ -0,0 +1,84 @@
+# Migrating Guide: v1.x to v2.0.0-pre
+
+This guide covers migrating from Familia v1.x to the v2.0.0-pre foundation release.
+
+## Overview
+
+The v2.0.0-pre series represents a major modernization of Familia with:
+- Complete API redesign for clarity and consistency
+- Valkey compatibility alongside Redis support
+- Ruby 3.4+ modernization with improved thread safety
+- New connection pooling architecture
+
+## Step-by-Step Migration
+
+### 1. Update Connection Configuration
+
+**Before (v1.x):**
+```ruby
+Familia.connect('redis://localhost:6379/0')
+```
+
+**After (v2.0.0-pre):**
+```ruby
+Familia.configure do |config|
+  config.redis_uri = 'redis://localhost:6379/0'
+  config.connection_pool = true
+end
+```
+
+### 2. Migrate Identifier Declarations
+
+**Before (v1.x):**
+```ruby
+class User < Familia::Base
+  identifier :user_id
+end
+```
+
+**After (v2.0.0-pre):**
+```ruby
+class User < Familia::Horreum
+  identifier_field :user_id
+end
+```
+
+### 3. Update Feature Activations
+
+**Before (v1.x):**
+```ruby
+class User < Familia::Base
+  include Familia::Features::Expiration
+end
+```
+
+**After (v2.0.0-pre):**
+```ruby
+class User < Familia::Horreum
+  feature :expiration
+end
+```
+
+### 4. Review Method Calls
+
+Several methods were renamed for consistency:
+
+| v1.x Method | v2.0.0-pre Method | Notes |
+|-------------|------------------|-------|
+| `delete` | `destroy` | More semantic naming |
+| `exists` | `exists?` | Ruby predicate convention |
+| `dump` | `serialize` | Clearer intent |
+
+## Breaking Changes
+
+- `Familia::Base` replaced by `Familia::Horreum`
+- Connection configuration moved to block-based setup
+- Feature inclusion changed from `include` to `feature` declarations
+- Several method names updated for consistency
+
+## Next Steps
+
+After completing the foundation migration:
+1. Review [Security Feature Adoption](v2.0.0-pre5.md) for encrypted fields
+2. See [Architecture Migration](v2.0.0-pre6.md) for persistence improvements
+3. Explore [Relationships Migration](v2.0.0-pre7.md) for the new relationship system