familia 2.0.0.pre7 → 2.0.0.pre10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7a93de51c8a35c420067d9e48895af37862866667af224a8e13f44647c4e4c76
-  data.tar.gz: bbdf64f77c182a0498fc757c393071b04b5da3594b4c7d5c12992fe058b44777
+  metadata.gz: 5f09bb44b39f033bc38faaff02dd33c645ecd6a98bee533a756707daeb47e00c
+  data.tar.gz: 77afd574073258009058ed9f638151b1ca26ba65d06b49f841ad46b52e50a82a
 SHA512:
-  metadata.gz: 59a39a481db42739bbebabab9211645b2f7e9eb605742ab936c0b65dfc32973931b1b1f8a1c5d725fed5f5eb0ebdbb87c1c405f87108390ad3b6eb8f5ca89c5a
-  data.tar.gz: 4dc7dededb21bd7ee988a4d260e30eceb43f19be4c3f5d99f87bac5d632af6e517af5eab2633758e0c6b1552a2635bd0e024ace2210ee1ee83362aa811458b8c
+  metadata.gz: c9bf8c181236218f04e7fff9902b63521d316265792a416525ee5da671789ddd636c372d0481b926b9b65b3116680bac698ebef6d37fd3d0117c9235053b98aa
+  data.tar.gz: d046f73ca2f6d46833e4bdb0f2a59c6c400b807f5e44f92657a470bd50c09ffae56debfd991f6513898a603ce44e761047d1e4449f8526d3d2a5ac333ebb8e72

data/.github/workflows/ci.yml

@@ -66,3 +66,16 @@ jobs:
 
       - name: Run the tryouts
         run: bundle exec try -vf
+
+      - name: Validate examples
+        continue-on-error: true
+        run: |
+          echo "=== Validating example syntax ==="
+          find examples/ -name "*.rb" -exec ruby -c {} \;
+
+          echo "=== Running executable examples ==="
+          cd examples
+          for example in *.rb; do
+            echo "Running $example..."
+            ruby "$example" || echo "Warning: $example failed to run"
+          done

data/.github/workflows/docs.yml

@@ -41,7 +41,7 @@ jobs:
 
       - name: Build YARD documentation
         run: |
-          bundle exec yard doc --output-dir ./doc --readme README.md
+          bundle exec yard doc --output-dir ./doc
           # Ensure doc directory exists and create .nojekyll file to prevent GitHub Pages Jekyll processing
           mkdir -p ./doc
           touch ./doc/.nojekyll

data/.gitignore

@@ -12,20 +12,20 @@
 .*.json
 *.env
 *.log
-*.md
-.mcp.json
-!README.md
-!CLAUDE.md
 *.txt
-!LICENSE.txt
 .ruby-version
 appendonlydir
-etc/config
 log
 tmp
 vendor
 *.gem
 doc/
-!docs/overview.md
-!docs/connection_pooling.md
-!docs/wiki/**/*.md
+
+# Ignore WIP or temp dev files with uppercase names
+[A-Z]*.md
+
+# Exclusions
+!README.md
+!CHANGELOG.md
+!CLAUDE.md
+!LICENSE.txt

data/.rubocop.yml

@@ -34,6 +34,25 @@ AllCops:
     - "try/*.rb"
     - "vendor/**/*"
 
+#
+# Trailing commas
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: comma
+  Enabled: true
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: comma
+  Enabled: true
+
+Style/TrailingCommaInArguments:
+  Enabled: true
+
+Style/TrailingCommaInBlockArgs:
+  Enabled: true
+
+Lint/TrailingCommaInAttributeDeclaration:
+  Enabled: true
+
 Gemspec/DeprecatedAttributeAssignment:
   Enabled: true
 

data/.yardopts

@@ -4,6 +4,27 @@
 --markup-provider kramdown
 --protected
 --no-private
+--embed-mixin ClassMethods
+--embed-mixin Features
+--tag feature:"Feature"
+--tag since:"Since Version"
+--tag example:"Example Usage"
+--tag note:"Note"
+--tag warning:"Warning"
+--tag deprecated:"Deprecated"
+--hide-tag nodoc
+--exclude lib/familia/version.rb
 lib/**/*.rb
 -
-- LICENSE.txt
+CHANGELOG.md
+LICENSE.txt
+docs/guides/Home.md
+docs/guides/Getting-Started.md
+docs/guides/Feature-System-Guide.md
+docs/guides/Relationships-Guide.md
+docs/guides/relationships-methods.md
+docs/guides/Encrypted-Fields-Overview.md
+docs/guides/Connection-Pooling-Guide.md
+docs/reference/api-technical.md
+docs/migration/*.md
+examples/*.rb

data/CHANGELOG.md

@@ -0,0 +1,184 @@
+# CHANGELOG.md
+
+All notable changes to Familia are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+<!--scriv-insert-here-->
+
+<a id='changelog-2.0.0-pre10'></a>
+## [2.0.0-pre10] - 2025-09-02 18:07:56.439890
+
+### Added
+
+- The `Familia::Horreum` initializer now supports creating an object directly from its identifier by passing a single argument (e.g., `Customer.new(customer_id)`). This provides a more convenient and intuitive way to instantiate objects from lookups.
+
+- Automatic indexing and class-level tracking on `save()` operations, eliminating the need for manual index updates.
+- Enhanced collection syntax supports the Ruby-idiomatic `<<` operator for more natural relationship management.
+
+### Changed
+
+- The `member_of` relationship is now bidirectional. A single call to `member.add_to_owner_collection(owner)` is sufficient to establish the relationship, removing the need for a second, redundant call on the owner object. This fixes bugs where members could be added to collections twice.
+
+- **BREAKING**: Refactored Familia Relationships API to remove "global" terminology and simplify method generation. (Closes #86)
+- Split `generate_indexing_instance_methods` into focused `generate_direct_index_methods` and `generate_relationship_index_methods` for better separation between direct class-level and relationship-based indexing.
+- Simplified method generation by removing complex global vs parent conditionals.
+- All indexes are now stored at the class level for consistency.
+
+### Fixed
+
+- Fixed a bug in the `class_indexed_by` feature where finder methods (e.g., `find_by_email`) would fail to correctly instantiate objects from the index, returning partially-formed objects.
+
+- Refactored connection handling to properly cache and reuse Redis connections. This eliminates repetitive "Overriding existing connection" warnings and improves performance.
+
+- Method generation now works consistently for both `class_indexed_by` and `indexed_by` with a `parent:`.
+- Resolved metadata storage issues for dynamically created classes.
+- Improved error handling for nil class names in tracking relationships.
+
+### Documentation
+
+- Updated the `examples/relationships_basic.rb` script to reflect the improved, bidirectional `member_of` API and to ensure a clean database state for each run.
+
+### AI Assistance
+
+- 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
+
+## 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
+
+- **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
+
+- Updated Relationships Guide with new API syntax and migration examples
+- Updated relationships method documentation with new method signatures
+- Updated basic relationships example to demonstrate new API patterns
+- Added tryouts test coverage in try/features/relationships/relationships_api_changes_try.rb
+
+
+<a id='changelog-2.0.0-pre8'></a>
+## [2.0.0-pre8] - 2025-09-01
+
+#### Added
+
+- Implemented Scriv-based changelog system for sustainable documentation
+- Added fragment-based workflow for tracking changes
+- Created structured changelog templates and configuration
+
+### Documentation
+
+- Set up Scriv configuration and directory structure
+- Created README for changelog fragment workflow
+
+
+<a id='changelog-2.0.0-pre7'></a>
+## [2.0.0-pre7] - 2025-08-31
+
+### Added
+
+- Comprehensive relationships system with three relationship types:
+  - `tracked_in` - Multi-presence tracking with score encoding
+  - `indexed_by` - O(1) hash-based lookups
+  - `member_of` - Bidirectional membership with collision-free naming
+- Categorical permission system with bit-encoded permissions
+- Time-based permission scoring for temporal access control
+- Permission tier hierarchies with inheritance patterns
+- Scalable permission management for large object collections
+- Score-based sorting with custom scoring functions
+- Permission-aware queries filtering by access levels
+- Relationship validation framework ensuring data integrity
+
+### Changed
+
+- Performance optimizations for large-scale relationship operations
+
+### Security
+
+- GitHub Actions security hardening with matrix optimization
+
+
+<a id='changelog-2.0.0-pre6'></a>
+## [2.0.0-pre6] - 2025-08-15
+
+### Added
+
+- New `save_if_not_exists` method for conditional persistence
+- Atomic persistence operations with transaction support
+- Enhanced error handling for persistence failures
+- Improved data consistency guarantees
+
+### Changed
+
+- Connection provider pattern for flexible pooling strategies
+- Multi-database support with intelligent pool management
+- Thread-safe connection handling for concurrent applications
+- Configurable pool sizing and timeout management
+- Modular class structure with cleaner separation of concerns
+- Enhanced feature system with dependency management
+- Improved inheritance patterns for better code organization
+- Streamlined base class functionality
+
+### Fixed
+
+- Critical security fixes in Ruby workflow vulnerabilities
+- Systematic dependency resolution via multi-constraint optimization
+
+
+<a id='changelog-2.0.0-pre5'></a>
+## [2.0.0-pre5] - 2025-08-05
+
+### Added
+
+- Field-level encryption with transparent access patterns
+- Multiple encryption providers:
+  - XChaCha20-Poly1305 (preferred, requires rbnacl)
+  - AES-256-GCM (fallback, OpenSSL-based)
+- Field-specific key derivation for cryptographic domain separation
+- Configurable key versioning supporting key rotation
+- Non-persistent field storage for sensitive runtime data
+- RedactedString wrapper preventing accidental logging/serialization
+- Memory-safe handling of sensitive data in Ruby objects
+- API-safe serialization excluding transient fields
+
+### Security
+
+- Encryption field security hardening with additional validation
+- Enhanced memory protection for sensitive data handling
+- Improved key management patterns and best practices
+- Security test suite expansion with comprehensive coverage
+
+
+<a id='changelog-2.0.0-pre'></a>
+## [2.0.0-pre] - 2025-07-25
+
+### Added
+
+- Complete API redesign for clarity and modern Ruby conventions
+- Valkey compatibility alongside traditional Redis support
+- Ruby 3.4+ modernization with fiber and thread safety improvements
+- Connection pooling foundation with provider pattern architecture
+
+### Changed
+
+- `Familia::Base` replaced by `Familia::Horreum` as the primary base class
+- Connection configuration moved from simple string to block-based setup
+- Feature activation changed from `include` to `feature` declarations
+- Method naming updated for consistency (`delete` → `destroy`, `exists` → `exists?`, `dump` → `serialize`)
+
+### Documentation
+
+- YARD documentation workflow with automated GitHub Pages deployment
+- Comprehensive migration guide for v1.x to v2.0.0-pre transition
+
+<!-- scriv-end-here -->

data/CLAUDE.md

@@ -44,18 +44,21 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - **Generate documentation**: `bundle exec yard`
 - **Code linting**: `bundle exec rubocop`
 
+### Changelog Management
+
+Add changelog fragment with each user-facing or documented change (optional but encouraged). See:
+@changelog.d/README.md
+
 ### Known Issues & Quirks
-- **Reserved Keywords**: Cannot use `ttl`, `db`, `redis` as field names - use prefixed alternatives
+- **Reserved Keywords**: Cannot use `ttl`, `db`, `valkey`, `redis` as field names - use prefixed alternatives
 - **Empty Identifiers**: Cause stack overflow in key generation - validate before operations
 - **Connection Pool Race Conditions**: Thread safety issues under high concurrency
-- **Manual Key Sync**: `key` field doesn't auto-sync with identifier changes
-- **RedisType Redis Parameter**: `:redis` parameter silently ignored (missing setter)
 
 ### Debugging
-- **Database command logging**: `tail plop.log` - Real-time Database command monitoring
+- **Database command logging**: You can request real-time Database command monitoring from the user
   - Shows all Database operations with timestamps, database numbers, and full commands
   - Updates live as tests run or code executes
-  - Essential for debugging Familia ORM Database interactions
+  - 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`.

data/Gemfile

@@ -9,7 +9,7 @@ group :test do
     gem 'tryouts', path: '../tryouts'
     gem 'uri-valkey', path: '..//uri-valkey/gems', glob: 'uri-valkey.gemspec'
   else
-    gem 'tryouts', '~> 3.5.1', require: false
+    gem 'tryouts', '~> 3.5.2', require: false
   end
   gem 'concurrent-ruby', '~> 1.3.5', require: false
   gem 'ruby-prof'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    familia (2.0.0.pre6)
+    familia (2.0.0.pre10)
       benchmark
       connection_pool
       csv
@@ -113,7 +113,7 @@ GEM
     ruby-progressbar (1.13.0)
     stackprof (0.2.27)
     stringio (3.1.7)
-    tryouts (3.5.1)
+    tryouts (3.5.2)
       concurrent-ruby (~> 1.0)
       irb
       minitest (~> 5.0)
@@ -148,7 +148,7 @@ DEPENDENCIES
   rubocop-thread_safety
   ruby-prof
   stackprof
-  tryouts (~> 3.5.1)
+  tryouts (~> 3.5.2)
   yard (~> 0.9)
 
 BUNDLED WITH

data/README.md

@@ -118,9 +118,104 @@ user.transaction do |conn|
 end
 ```
 
-## Conclusion
+### Object Relationships
 
-Familia provides a powerful and flexible way to work with Valkey-compatible in Ruby applications. Its features like automatic expiration, safe dumping, and quantization make it suitable for a wide range of use cases, from simple key-value storage to complex time-series data management.
+Familia includes a powerful relationships system for managing object associations:
+
+```ruby
+class Customer < Familia::Horreum
+  feature :relationships
+
+  identifier_field :custid
+  field :custid, :name, :email
+  set :domains  # Collection for related objects
+
+  # Automatic indexing and tracking
+  class_indexed_by :email, :email_lookup
+  class_tracked_in :all_customers, score: :created_at
+end
+
+class Domain < Familia::Horreum
+  feature :relationships
+
+  identifier_field :domain_id
+  field :domain_id, :name, :status
+
+  # Bidirectional membership
+  member_of Customer, :domains
+end
+
+# Clean, Ruby-like syntax
+customer = Customer.new(custid: "cust123", email: "admin@acme.com")
+customer.save  # Automatically indexed and tracked
+
+domain = Domain.new(domain_id: "dom456", name: "acme.com")
+customer.domains << domain  # Clean collection syntax
+
+# Fast O(1) lookups
+found_customer = Customer.find_by_email("admin@acme.com")
+```
+
+## Advanced Features
+
+### Relationships and Associations
+
+Familia provides three types of relationships with automatic management:
+
+- **`member_of`** - Bidirectional membership with clean `<<` operator support
+- **`indexed_by`** - O(1) hash-based field lookups (class-level or relationship-scoped)
+- **`tracked_in`** - Scored collections for rankings, time-series, and analytics
+
+All relationships support automatic indexing and tracking - objects are automatically added to class-level collections when saved, with no manual management required.
+
+## Organizing Complex Models
+
+For large applications, you can organize model complexity using custom features:
+
+### Self-Registering Features
+
+```ruby
+# app/features/customer_management.rb
+module MyApp::Features::CustomerManagement
+  Familia::Base.add_feature(self, :customer_management)
+
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+
+  module ClassMethods
+    def create_with_validation(attrs)
+      # Complex creation logic
+    end
+  end
+
+  def complex_business_method
+    # Instance methods
+  end
+end
+
+# models/customer.rb
+class Customer < Familia::Horreum
+  field :email, :name
+  feature :customer_management  # Clean model definition
+end
+```
+
+This keeps complex models organized while maintaining Familia's clean, declarative style.
+
+## AI Development Assistance
+
+This version of Familia was developed with assistance from AI tools. The following tools provided significant help with architecture design, code generation, and documentation:
+
+- **Google Gemini** - Refactoring, code generation, and documentation.
+- **Claude Sonnet 4, Opus 4.1** - Architecture design, code generation, and documentation
+- **Claude Desktop & Claude Code (Max plan)** - Interactive development sessions and debugging
+- **GitHub Copilot** - Code completion and refactoring assistance
+- **Qodo Merge Pro** - Code review and quality improvements
+
+I remain responsible for all design decisions and the final code. I believe in being transparent about development tools, especially as AI becomes more integrated into our workflows as developers.
+
+## Epilogue
 
 For more information, visit:
 - [Github Repository](https://github.com/delano/familia)

data/changelog.d/README.md

@@ -0,0 +1,66 @@
+# Changelog Fragments
+
+This directory contains changelog fragments managed by [Scriv](https://scriv.readthedocs.io/).
+
+## 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.
+
+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.
+
+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.
+- **Builds Trust:** A clear and well-maintained changelog communicates respect for our users and collaborators.
+
+## 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..."
+
+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.
+
+3.  **Commit with Your Code:**
+    ```bash
+    git add changelog.d/fragments/your_fragment_name.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)`
+
+### Categories
+
+Use these categories from [Keep a Changelog](https://keepachangelog.com):
+
+-   **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.
+
+## 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
+```

data/changelog.d/template.md.j2

@@ -0,0 +1,29 @@
+<!--
+A new scriv fragment. Uncomment sections as needed.
+Reference issues or pull requests in parentheses at the end of the entry.
+Example: - Fixed a bug in the connection pool. (Closes #123)
+-->
+
+### 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
+<!-- - Briefly describe how AI was used for this change (e.g., "Refactoring and documentation by Gemini"). -->

data/docs/archive/.gitignore

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