familia 2.0.0.pre18 → 2.0.0.pre21

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: familia
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre18
+  version: 2.0.0.pre21
 platform: ruby
 authors:
 - Delano Mandelbaum
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.4'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: connection_pool
   requirement: !ruby/object:Gem::Requirement
@@ -137,7 +151,6 @@ files:
 - ".github/workflows/ci.yml"
 - ".github/workflows/claude-code-review.yml"
 - ".github/workflows/claude.yml"
-- ".github/workflows/code-quality.yml"
 - ".github/workflows/code-smells.yml"
 - ".github/workflows/docs.yml"
 - ".gitignore"
@@ -153,31 +166,39 @@ files:
 - LICENSE.txt
 - README.md
 - bin/irb
+- bin/try
+- bin/tryouts
+- changelog.d/20251105_flexible_external_identifier_format.rst
+- changelog.d/20251107_112554_delano_179_participation_asymmetry.rst
+- changelog.d/20251107_213121_delano_fix_thread_safety_races_011CUumCP492Twxm4NLt2FvL.rst
+- changelog.d/20251107_fix_participates_in_symbol_resolution.rst
+- changelog.d/20251107_optimized_redis_exists_checks.rst
+- changelog.d/20251108_frozen_string_literal_pragma.rst
 - changelog.d/README.md
 - changelog.d/scriv.ini
+- docs/1106-participates_in-bidirectional-solution.md
 - docs/archive/.gitignore
-- docs/archive/FAMILIA_RELATIONSHIPS.md
-- docs/archive/FAMILIA_TECHNICAL.md
-- docs/archive/FAMILIA_UPDATE.md
-- docs/archive/README.md
-- docs/archive/api-reference.md
 - docs/conf.py
 - docs/guides/.gitignore
-- docs/guides/core-field-system.md
+- docs/guides/encryption.md
 - docs/guides/feature-encrypted-fields.md
 - docs/guides/feature-expiration.md
 - docs/guides/feature-external-identifiers.md
 - docs/guides/feature-object-identifiers.md
 - docs/guides/feature-quantization.md
+- docs/guides/feature-relationships-indexing.md
 - docs/guides/feature-relationships-methods.md
+- docs/guides/feature-relationships-participation.md
 - docs/guides/feature-relationships.md
 - docs/guides/feature-system-devs.md
 - docs/guides/feature-system.md
 - docs/guides/feature-transient-fields.md
-- docs/guides/implementation.md
+- docs/guides/field-system.md
 - docs/guides/index.md
-- docs/guides/security-model.md
-- docs/guides/time-utilities.md
+- docs/guides/logging.md
+- docs/guides/optimized-loading.md
+- docs/guides/thread-safety-monitoring.md
+- docs/guides/time-literals.md
 - docs/migrating/.gitignore
 - docs/migrating/v2.0.0-pre.md
 - docs/migrating/v2.0.0-pre11.md
@@ -185,6 +206,8 @@ files:
 - docs/migrating/v2.0.0-pre13.md
 - docs/migrating/v2.0.0-pre14.md
 - docs/migrating/v2.0.0-pre18.md
+- docs/migrating/v2.0.0-pre19.md
+- docs/migrating/v2.0.0-pre22.md
 - docs/migrating/v2.0.0-pre5.md
 - docs/migrating/v2.0.0-pre6.md
 - docs/migrating/v2.0.0-pre7.md
@@ -194,21 +217,24 @@ files:
 - examples/autoloader/mega_customer.rb
 - examples/autoloader/mega_customer/features/deprecated_fields.rb
 - examples/autoloader/mega_customer/safe_dump_fields.rb
+- examples/datatype_standalone.rb
 - examples/encrypted_fields.rb
 - examples/json_usage_patterns.rb
 - examples/relationships.rb
 - examples/safe_dump.rb
+- examples/sampling_demo.rb
 - examples/single_connection_transaction_confusions.rb
 - familia.gemspec
 - lib/familia.rb
 - lib/familia/base.rb
 - lib/familia/connection.rb
+- lib/familia/connection/behavior.rb
 - lib/familia/connection/handlers.rb
 - lib/familia/connection/individual_command_proxy.rb
 - lib/familia/connection/middleware.rb
 - lib/familia/connection/operation_core.rb
 - lib/familia/connection/operations.rb
-- lib/familia/connection/pipeline_core.rb
+- lib/familia/connection/pipelined_core.rb
 - lib/familia/connection/transaction_core.rb
 - lib/familia/data_type.rb
 - lib/familia/data_type/class_methods.rb
@@ -248,11 +274,14 @@ files:
 - lib/familia/features/relationships/collection_operations.rb
 - lib/familia/features/relationships/indexing.rb
 - lib/familia/features/relationships/indexing/multi_index_generators.rb
+- lib/familia/features/relationships/indexing/rebuild_strategies.rb
 - lib/familia/features/relationships/indexing/unique_index_generators.rb
 - lib/familia/features/relationships/indexing_relationship.rb
 - lib/familia/features/relationships/participation.rb
 - lib/familia/features/relationships/participation/participant_methods.rb
+- lib/familia/features/relationships/participation/rebuild_strategies.md
 - lib/familia/features/relationships/participation/target_methods.rb
+- lib/familia/features/relationships/participation_membership.rb
 - lib/familia/features/relationships/participation_relationship.rb
 - lib/familia/features/relationships/score_encoding.rb
 - lib/familia/features/safe_dump.rb
@@ -272,6 +301,7 @@ files:
 - lib/familia/horreum/settings.rb
 - lib/familia/horreum/utils.rb
 - lib/familia/identifier_extractor.rb
+- lib/familia/instrumentation.rb
 - lib/familia/json_serializer.rb
 - lib/familia/logging.rb
 - lib/familia/refinements.rb
@@ -280,9 +310,12 @@ files:
 - lib/familia/refinements/time_literals.rb
 - lib/familia/secure_identifier.rb
 - lib/familia/settings.rb
+- lib/familia/thread_safety/instrumented_mutex.rb
+- lib/familia/thread_safety/monitor.rb
 - lib/familia/utils.rb
 - lib/familia/verifiable_identifier.rb
 - lib/familia/version.rb
+- lib/middleware/database_command_counter.rb
 - lib/middleware/database_logger.rb
 - lib/multi_result.rb
 - pr_agent.toml
@@ -330,11 +363,15 @@ files:
 - try/features/quantization/quantization_try.rb
 - try/features/real_feature_integration_try.rb
 - try/features/relationships/indexing_commands_verification_try.rb
+- try/features/relationships/indexing_rebuild_try.rb
 - try/features/relationships/indexing_try.rb
+- try/features/relationships/participation_bidirectional_try.rb
 - try/features/relationships/participation_commands_verification_spec.rb
 - try/features/relationships/participation_commands_verification_try.rb
 - try/features/relationships/participation_performance_improvements_try.rb
 - try/features/relationships/participation_reverse_index_try.rb
+- try/features/relationships/participation_target_class_resolution_try.rb
+- try/features/relationships/participation_unresolved_target_try.rb
 - try/features/relationships/relationships_api_changes_try.rb
 - try/features/relationships/relationships_edge_cases_try.rb
 - try/features/relationships/relationships_performance_minimal_try.rb
@@ -366,6 +403,8 @@ files:
 - try/integration/conventional_inheritance_try.rb
 - try/integration/create_method_try.rb
 - try/integration/cross_component_try.rb
+- try/integration/data_types/datatype_pipelines_try.rb
+- try/integration/data_types/datatype_transactions_try.rb
 - try/integration/database_consistency_try.rb
 - try/integration/familia_extended_try.rb
 - try/integration/familia_members_methods_try.rb
@@ -375,10 +414,15 @@ files:
 - try/integration/models/familia_object_try.rb
 - try/integration/persistence_operations_try.rb
 - try/integration/relationships_persistence_round_trip_try.rb
+- try/integration/save_methods_consistency_try.rb
 - try/integration/scenarios_try.rb
 - try/integration/secure_identifier_try.rb
+- try/integration/transaction_safety_core_try.rb
+- try/integration/transaction_safety_workflow_try.rb
 - try/integration/verifiable_identifier_try.rb
+- try/investigation/pipeline_routing/README.md
 - try/performance/benchmarks_try.rb
+- try/performance/transaction_safety_benchmark_try.rb
 - try/support/benchmarks/deserialization_benchmark.rb
 - try/support/benchmarks/deserialization_correctness_test.rb
 - try/support/debugging/README.md
@@ -428,6 +472,18 @@ files:
 - try/support/prototypes/pooling/lib/visualize_stress_results.rb
 - try/support/prototypes/pooling/pool_siege.rb
 - try/support/prototypes/pooling/run_stress_tests.rb
+- try/thread_safety/README.md
+- try/thread_safety/class_connection_chain_race_try.rb
+- try/thread_safety/connection_chain_race_try.rb
+- try/thread_safety/encryption_manager_cache_race_try.rb
+- try/thread_safety/feature_registry_race_try.rb
+- try/thread_safety/fiber_pipeline_isolation_try.rb
+- try/thread_safety/fiber_transaction_isolation_try.rb
+- try/thread_safety/field_registration_race_try.rb
+- try/thread_safety/logger_initialization_race_try.rb
+- try/thread_safety/middleware_registration_race_try.rb
+- try/thread_safety/module_config_race_try.rb
+- try/thread_safety/secure_identifier_cache_race_try.rb
 - try/unit/core/autoloader_try.rb
 - try/unit/core/base_enhancements_try.rb
 - try/unit/core/connection_try.rb
@@ -435,6 +491,9 @@ files:
 - try/unit/core/extensions_try.rb
 - try/unit/core/familia_logger_try.rb
 - try/unit/core/familia_try.rb
+- try/unit/core/middleware_sampling_try.rb
+- try/unit/core/middleware_test_helpers_bug_try.rb
+- try/unit/core/middleware_thread_safety_try.rb
 - try/unit/core/middleware_try.rb
 - try/unit/core/settings_try.rb
 - try/unit/core/time_utils_try.rb
@@ -450,7 +509,9 @@ files:
 - try/unit/data_types/sorted_set_zadd_options_try.rb
 - try/unit/data_types/string_try.rb
 - try/unit/data_types/unsortedset_try.rb
+- try/unit/familia_resolve_class_try.rb
 - try/unit/horreum/auto_indexing_on_save_try.rb
+- try/unit/horreum/automatic_index_validation_try.rb
 - try/unit/horreum/base_try.rb
 - try/unit/horreum/class_methods_try.rb
 - try/unit/horreum/commands_try.rb
@@ -461,14 +522,20 @@ files:
 - try/unit/horreum/field_definition_try.rb
 - try/unit/horreum/initialization_try.rb
 - try/unit/horreum/json_type_preservation_try.rb
+- try/unit/horreum/optimized_loading_try.rb
 - try/unit/horreum/relations_try.rb
 - try/unit/horreum/serialization_persistent_fields_try.rb
 - try/unit/horreum/serialization_try.rb
 - try/unit/horreum/settings_try.rb
+- try/unit/horreum/unique_index_edge_cases_try.rb
+- try/unit/horreum/unique_index_guard_validation_try.rb
+- try/unit/middleware/database_command_counter_methods_try.rb
+- try/unit/middleware/database_logger_methods_try.rb
 - try/unit/refinements/dear_json_array_methods_try.rb
 - try/unit/refinements/dear_json_hash_methods_try.rb
 - try/unit/refinements/time_literals_numeric_methods_try.rb
 - try/unit/refinements/time_literals_string_methods_try.rb
+- try/unit/thread_safety_monitor_try.rb
 - try/valkey.conf
 homepage: https://github.com/delano/familia
 licenses:
@@ -482,14 +549,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.4'
+      version: 3.3.6
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.2
 specification_version: 4
 summary: An ORM for Valkey-compatible databases in Ruby.
 test_files: []

data/.github/workflows/code-quality.yml

@@ -1,138 +0,0 @@
-name: Code Quality
-
-on:
-  pull_request:
-    branches: [ main ]
-  push:
-    branches: [ main ]
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  pull-requests: write  # Needed to post comments on PRs
-
-jobs:
-  reek:
-    name: Reek Code Analysis
-    runs-on: ubuntu-24.04
-    timeout-minutes: 5
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: 3.4
-          bundler-cache: true
-
-      - name: Configure Bundler for secure gem installation
-        run: |
-          bundle config set --local path 'vendor/bundle'
-          bundle config set --local deployment 'false'
-
-      - name: Install dependencies
-        run: bundle install
-
-      - name: Run Reek analysis
-        run: |
-          echo "=== Running Reek code analysis ==="
-          echo "This analysis identifies code smells and potential improvements."
-          echo "Results are informational and won't fail the build."
-          echo ""
-
-          # Run reek and capture output (don't fail on warnings)
-          # Use success-exit-code to prevent failures from stopping the analysis
-          bundle exec reek --format=text --success-exit-code 0 --failure-exit-code 0 || true
-
-          echo ""
-          echo "=== Reek analysis complete ==="
-        continue-on-error: true  # Don't fail the build on code smells
-
-      - name: Generate Reek report (if analysis available)
-        run: |
-          echo "=== Generating detailed Reek report ==="
-
-          # Generate JSON report for potential future processing
-          bundle exec reek --format=json --success-exit-code 0 --failure-exit-code 0 > reek-report.json || true
-
-          # Display summary
-          if [ -s reek-report.json ]; then
-            echo "Reek JSON report generated: $(wc -l < reek-report.json) lines"
-            echo "Top code smell types found:"
-            jq -r '.[].smells[].smell_type' reek-report.json 2>/dev/null | sort | uniq -c | sort -rn | head -10 || echo "Unable to parse JSON report"
-          else
-            echo "No code smells detected or analysis failed"
-          fi
-        continue-on-error: true
-
-      - name: Upload Reek report as artifact
-        uses: actions/upload-artifact@v4
-        if: always()
-        with:
-          name: reek-report
-          path: reek-report.json
-          retention-days: 30
-
-  # Add other code quality checks here
-  additional-quality-checks:
-    name: Additional Quality Checks
-    runs-on: ubuntu-24.04
-    timeout-minutes: 5
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-
-      - name: Set up Ruby
-        uses: ruby/setup-ruby@v1
-        with:
-          ruby-version: 3.4
-          bundler-cache: true
-
-      - name: Configure Bundler for secure gem installation
-        run: |
-          bundle config set --local path 'vendor/bundle'
-          bundle config set --local deployment 'false'
-
-      - name: Install dependencies
-        run: bundle install
-
-      - name: Check for TODO/FIXME comments
-        run: |
-          echo "=== Scanning for TODO/FIXME comments ==="
-          echo "This helps track technical debt and action items."
-          echo ""
-
-          # Find TODO/FIXME comments (excluding this workflow file)
-          find . -name "*.rb" -not -path "./vendor/*" -not -path "./tmp/*" | \
-            xargs grep -Hn -i -E "(TODO|FIXME|HACK|XXX|NOTE):" 2>/dev/null | \
-            head -20 || echo "No TODO/FIXME comments found"
-        continue-on-error: true
-
-      - name: Check Ruby file syntax
-        run: |
-          echo "=== Checking Ruby syntax ==="
-          echo "Validates that all Ruby files have correct syntax."
-          echo ""
-
-          find . -name "*.rb" -not -path "./vendor/*" -not -path "./tmp/*" | \
-            while read -r file; do
-              if ! ruby -c "$file" > /dev/null 2>&1; then
-                echo "Syntax error in: $file"
-                ruby -c "$file"
-              fi
-            done
-        continue-on-error: true
-
-      - name: Check for long lines
-        run: |
-          echo "=== Checking for long lines (>120 characters) ==="
-          echo "Identifies potentially hard-to-read code lines."
-          echo ""
-
-          find . -name "*.rb" -not -path "./vendor/*" -not -path "./tmp/*" | \
-            xargs grep -Hn "^.\{121,\}$" | \
-            head -10 || echo "No overly long lines found"
-        continue-on-error: true

data/docs/archive/FAMILIA_RELATIONSHIPS.md

@@ -1,210 +0,0 @@
-# Relationship methods
-
-here are the methods automatically generated for each relationship type:
-
-member_of Relationships
-
-When you declare:
-class Domain < Familia::Horreum
-  member_of Customer, :domains, type: :set
-end
-
-Generated methods on Domain instances:
-- add_to_customer_domains(customer_id) - Add this domain to customer's domains collection
-- remove_from_customer_domains(customer_id) - Remove this domain from customer's domains collection
-- in_customer_domains?(customer_id) - Check if this domain is in customer's domains collection
-
-The method names follow the pattern: {action}_to_{lowercase_class_name}_{collection_name}
-
-participates_in Relationships
-
-When you declare:
-class Customer < Familia::Horreum
-  participates_in :all_customers, type: :sorted_set, score: :created_at
-end
-
-Generated class methods:
-- Customer.add_to_all_customers(customer) - Add customer to global tracking
-- Customer.remove_from_all_customers(customer) - Remove customer from global tracking
-- Customer.all_customers - Access the sorted set collection directly
-
-For scoped tracking (with class prefix):
-participates_in :global, :active_users, score: :last_seen
-Generates: Customer.add_to_active_users(customer) and Customer.active_users
-
-indexed_by Relationships
-
-The `indexed_by` method creates Valkey/Redis hash-based indexes for O(1) field lookups. The `context` parameter determines index ownership and scope.
-
-**Global Context (Shared Index)**
-When you declare:
-```ruby
-class Customer < Familia::Horreum
-  indexed_by :email, :email_lookup, target: :global
-end
-```
-
-Generated class methods:
-- Customer.add_to_email_lookup(customer) - Add customer to global email index
-- Customer.remove_from_email_lookup(customer) - Remove customer from global email index
-- Customer.email_lookup - Access the global hash index directly (supports .get(email))
-
-Valkey/Redis key pattern: `global:email_lookup`
-
-**Class Context (Per-Instance Index)**
-When you declare:
-```ruby
-class Domain < Familia::Horreum
-  indexed_by :name, :domain_index, target: Customer
-end
-```
-
-Generated class methods on Customer:
-- Customer.find_by_name(domain_name) - Find domain by name within this customer
-- Customer.find_all_by_name(domain_names) - Find multiple domains by names
-
-Valkey/Redis key pattern: `customer:123:domain_index` (per customer instance)
-
-**When to Use Each Context**
-- **Global context (`:global`)**: Use for system-wide lookups where the field value should be unique across all instances
-  - Examples: email addresses, usernames, API keys
-- **Class context (e.g., `Customer`)**: Use for scoped lookups where the field value is unique within a specific parent object
-  - Examples: domain names per customer, project names per team
-
-Example from the Codebase
-
-From the relationships example file, you can see this in action:
-
-# Domain declares membership in Customer collections
-class Domain < Familia::Horreum
-  member_of Customer, :domains, type: :set
-end
-
-# This generates these methods on Domain instances:
-domain.add_to_customer_domains(customer.custid)     # Add to relationship
-domain.remove_from_customer_domains(customer.custid) # Remove from relationship
-domain.in_customer_domains?(customer.custid)       # Query membership
-
-# For participates_in relationships:
-Customer.add_to_all_customers(customer)    # Class method
-Customer.all_customers.range(0, -1)        # Direct collection access
-
-# For indexed_by relationships:
-Customer.add_to_email_lookup(customer)           # Class method
-Customer.email_lookup.get("user@example.com")   # O(1) lookup
-
-Method Naming Conventions
-
-The relationship system uses consistent naming patterns:
-- member_of: {add_to|remove_from|in}_#{parent_class.downcase}_#{collection_name}
-- participates_in: {add_to|remove_from}_#{collection_name} (class methods)
-- indexed_by: {add_to|remove_from}_#{index_name} (class methods)
-
-This automatic method generation creates a clean, predictable API that handles both the db operations and maintains referential consistency
-across related objects.
-
-
-## Context Parameter Usage Patterns
-
-The `context` parameter in `indexed_by` is a fundamental architectural decision that determines index scope and ownership. Here are practical patterns for when to use each approach:
-
-### Global Context Pattern
-Use `context: :global` when field values should be unique system-wide:
-
-```ruby
-class User < Familia::Horreum
-  feature :relationships
-
-  identifier_field :user_id
-  field :user_id, :email, :username
-
-  # System-wide unique email lookup
-  indexed_by :email, :email_lookup, target: :global
-  indexed_by :username, :username_lookup, target: :global
-end
-
-# Usage:
-User.add_to_email_lookup(user)
-found_user_id = User.email_lookup.get("john@example.com")
-```
-
-**Valkey/Redis keys generated**: `global:email_lookup`, `global:username_lookup`
-
-### Class Context Pattern
-Use `context: SomeClass` when field values are unique within a specific parent context:
-
-```ruby
-class Customer < Familia::Horreum
-  feature :relationships
-
-  identifier_field :custid
-  field :custid, :name
-  sorted_set :domains
-end
-
-class Domain < Familia::Horreum
-  feature :relationships
-
-  identifier_field :domain_id
-  field :domain_id, :name, :subdomain
-
-  # Domains are unique per customer (customer can't have duplicate domain names)
-  indexed_by :name, :domain_index, target: Customer
-  indexed_by :subdomain, :subdomain_index, target: Customer
-end
-
-# Usage:
-customer = Customer.new(custid: "cust_123")
-customer.find_by_name("example.com")           # Find domain within this customer
-customer.find_all_by_subdomain(["www", "api"]) # Find multiple subdomains
-```
-
-**Valkey/Redis keys generated**: `customer:cust_123:domain_index`, `customer:cust_123:subdomain_index`
-
-### Mixed Pattern Example
-A real-world example showing both patterns:
-
-```ruby
-class ApiKey < Familia::Horreum
-  feature :relationships
-
-  identifier_field :key_id
-  field :key_id, :key_hash, :name, :scope
-
-  # API key hashes must be globally unique
-  indexed_by :key_hash, :global_key_lookup, target: :global
-
-  # But key names can be reused across different customers
-  indexed_by :name, :customer_key_lookup, target: Customer
-  indexed_by :scope, :scope_lookup, target: Customer
-end
-
-# Usage examples:
-# Global lookup (system-wide unique)
-ApiKey.key_lookup.get("sha256:abc123...")
-
-# Scoped lookup (unique per customer)
-customer = Customer.new(custid: "cust_456")
-customer.find_by_name("production-api-key")
-customer.find_all_by_scope(["read", "write"])
-```
-
-### Migrating Guide
-If you have existing code with incorrect syntax, here's how to fix it:
-
-```ruby
-# ❌ Old incorrect syntax
-indexed_by :email_lookup, field: :email
-
-# ✅ New correct syntax - Global scope
-indexed_by :email, :email_lookup, target: :global
-
-# ✅ New correct syntax - Class scope
-indexed_by :email, :customer_email_lookup, target: Customer
-```
-
-**Key Differences**:
-1. Parameter order: `indexed_by(field, index_name, context:)`
-2. The `field:` named parameter is now positional
-3. The `context:` parameter is required and determines scope
-4. Index name comes second (allows same field to have multiple indexes)