[AI-FSSDK] [FSSDK-12368] Local Holdouts - Cleanup flag base setup and add includedRules and rule-level lookup

[Mat001]

Summary

Implements Local Holdouts support for the Python SDK, replacing legacy flag-level holdout targeting (includedFlags/excludedFlags) with rule-level targeting (includedRules).

Related Ticket: FSSDK-12368

Changes

Data Model

• Added included_rules field to Holdout model (optional array of rule IDs)
• Added is_global property (True when included_rules is None)
• Removed legacy fields: included_flags, excluded_flags

Holdout Configuration

• Updated HoldoutConfig from flag-level to rule-level mapping
• Implemented get_global_holdouts() - returns holdouts with included_rules == None
• Implemented get_holdouts_for_rule(rule_id) - returns holdouts targeting specific rule
• Added validation for rule holdouts map integrity

Decision Flow

• Global holdouts evaluated at flag level (before forced decisions)
• Local holdouts evaluated per-rule (after forced decisions, before audience/traffic)
• If user hits local holdout, rule evaluation is skipped
• Returns correct decision metadata: source="holdout", experiment_id, ruleKey

Edge Cases

• Missing included_rules field defaults to None (global holdout)
• Empty array [] vs None handled correctly (empty = local with no rules, None = global)
• Invalid rule IDs skipped gracefully (no errors)
• Cross-flag targeting supported (one holdout can target rules from multiple flags)

Testing

New Tests (11 comprehensive tests in tests/test_local_holdouts.py)

• Global holdout evaluation
• Local single-rule targeting
• Local multi-rule targeting (same flag and cross-flag)
• Precedence (global before local)
• Edge cases (missing field, empty array, invalid rule IDs)

Updated Tests (60 existing tests)

• Migrated from included_flags/excluded_flags to included_rules
• Updated to use is_global property
• Verified backward compatibility

Quality Metrics

• ✅ Tests: 71/71 passing (100%)
• ✅ Critical Issues: 0
• ✅ Warnings: 0
• ✅ Comprehensive edge case coverage

Files Modified

• optimizely/entities.py - Holdout model updates
• optimizely/project_config.py - Mapping and retrieval logic
• optimizely/decision_service.py - Decision flow integration
• optimizely/helpers/types.py - Type definitions
• tests/test_local_holdouts.py - New comprehensive test suite
• tests/test_decision_service_holdout.py - API updates
• tests/test_config.py - Model updates

Test Plan

• Unit tests pass (71/71)
• Global holdouts work correctly
• Local holdouts work correctly (single rule, multiple rules)
• Edge cases handled (missing field, empty array, invalid IDs)
• Backward compatibility verified (old datafiles work)
• Cross-flag targeting works
• Precedence correct (global → forced → local → rule)

🤖 Generated with Claude Code